Kingdoc

Kingdoc enables AI-assisted creation, editing, management, and format conversion of Kingsoft Docs files including docs, sheets, PPTs, forms, and attachments...

fyniujin@fyniujin

Install

openclaw skills install @fyniujin/kingdoc

KingDoc — 金山文档 AI 协作助手 v2.1.0

⚠️ 首次使用必读

1. 申请金山开放平台 App（免费）

不申请 App，所有 API 调用都会报 KD001 鉴权失败。

申请步骤：

访问金山开放平台并登录你的金山文档账号
进入「应用管理」→「创建应用」
填写应用名称（如：KingDoc）和应用描述
获取 App ID 和 App Secret
选择应用权限（OAuth Scope）：
- 必须勾选：user:file:write、user:file:read、team:file:write、team:file:read
- 建议勾选：user:team:read（查看团队信息）、user:notification:write（推送通知）
应用审核通常 1 个工作日通过，测试阶段限速 500 次/天，申请正式版后 10 万次/天

2. 配置 KingDoc

拿到 App ID 和 Secret 后执行：

bash

# Linux/macOS
bash setup.sh

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File setup.ps1

脚本会引导你输入 App ID 和 Secret。

快速开始

你想做什么	直接对 AI 说
新建一个会议纪要	`"帮我写一份会议纪要"`
创建 Excel 数据表	`"建一个销售数据表格，含产品/销量/金额"`
生成 PPT	`"帮我做一份产品发布 PPT"`
查看文档内容	`"看看这个文档说了什么"`
找一个文件	`"搜一下上个月的合同"`
上传本地文件	`"把这个 PDF 上传到云端"`
恢复误删文件	`"回收站里有没有昨天删的 Word？"`
回滚到历史版本	`"这份文档改坏了，回退到上周版本"`
分享文档权限	`"给张三发个可编辑的链接"`
归档到文件夹	`"把文件移到 2026 项目文件夹"`
提取文字	`"把这张发票的文字提取出来"`
格式转换	`"把这份文档转成 PDF"`

安全声明

保护项	方式
🔒 删除确认	删除操作走回收站 API，不物理删除
🗑️ 软删除+恢复	`trash.list → trash.recover`
📝 版本冲突检测	写入前获取最新版本号，冲突时提示用户合并
🔐 权限前置校验	所有写入操作前自动检查权限，无权限拒绝
⚡ 限流保护	429 自动指数退避重试（最多 5 次）
🛡️ 文件类型拦截	默认禁止上传 .exe/.bat/.ps1 等可执行文件
🔑 Token 安全	Token 仅存在于内存，不落盘
📋 审计日志	所有写操作记录到本地日志
🔀 批量合并	50ms 窗口内连续写入自动合并为一次请求

支持的文档类型（6 品类）

类型	doc_type	推荐度	创建方式	编辑方式	说明
文字文档	doc	⭐⭐⭐	API 自动创建	本地生成+上传覆盖	自动排版，支持 DOCX 输出
电子表格	sheet	⭐⭐⭐	API 自动创建	API 精细编辑	单元格/公式/图表/筛选/排序
演示文稿	ppt	⭐⭐⭐	API 自动创建	本地生成+上传覆盖	自动排版，支持 PPTX 输出
多维表格	smartsheet	⭐⭐⭐	API 自动创建	API 精细编辑	记录/字段/视图管理
收集表	form	⭐⭐⭐	API 自动创建	API 自动编辑	表单创建/答卷查询/提交
附件	attachment	⭐⭐⭐	API 自动上传	—	本地文件/图片直接上传

场景路由表

先判断用户的操作意图属于以下 4 大类中的哪一类，再按子表路由到对应工具集。

1️⃣ 文档创建（从无到有）

用户意图 / 关键词	品类	首选创建方法	编辑方法
报告/笔记/文章/总结/会议纪要	doc	`kdoc.file.create`	`kdoc.local.docx.generate` → 上传覆盖
PPT/幻灯片/演示文稿	ppt	`kdoc.file.create`	`kdoc.local.pptx.generate` → 上传覆盖
数据表格/计算/统计/Excel	sheet	`kdoc.et.create`	`kdoc.et.*` 精细编辑
多维表格/轻维表	smartsheet	`kdoc.dbt.create`	`kdoc.dbt.*` 精细编辑
表单/收集表/问卷	form	`kdoc.form.create`	`kdoc.form.*` 配置
上传文件/图片/附件	attachment	`kdoc.file.upload`	—

2️⃣ 文档编辑（改内容）

先通过 kdoc.file.info 或链接前缀确定原始文档类型，再路由到对应编辑工具集。严禁用 A 品类的工具改 B 品类文档。

原始文档类型	编辑工具集
文字文档	`kdoc.local.docx.generate` → 上传覆盖（整文件替换）
电子表格	`kdoc.et.*` 精细编辑（单元格/公式/图表）
演示文稿	`kdoc.local.pptx.generate` → 上传覆盖（整文件替换）
多维表格	`kdoc.dbt.*` 精细编辑（记录/字段/视图）
收集表	`kdoc.form.*` 配置修改

3️⃣ 文件管理（不动内容，只动文件/目录/权限）

动作	工具
重命名/移动/删除/复制	`kdoc.file.*`
导入（本地→云端）	`kdoc.file.upload`
导出（云端→本地）	`kdoc.file.download`
权限变更/分享链接	`kdoc.file.permission` / `kdoc.share.*`
回收站查询/恢复	`kdoc.trash.list` / `kdoc.trash.recover`
版本历史/回滚	`kdoc.version.list` / `kdoc.version.restore`
批量操作	`kdoc.batch.create` → `kdoc.batch.query`
空间管理	`kdoc.space.` / `kdoc.folder.`

4️⃣ 格式转换（文档↔其他格式）

场景	工具
文档→PDF/Word/Excel/PPT	`kdoc.office.convert`
文档纯文本提取	`kdoc.office.extract`
通知推送（企微/钉钉/金山协作）	`kdoc.notification.send`
多维表格 Webhook 设置	`kdoc.dbt.webhook.set`

公共能力

场景	工具
获取文档内容	`kdoc.file.content`
文档纯文本提取	`kdoc.office.extract`
格式转换	`kdoc.office.convert`
搜索文档	`kdoc.file.search`
获取文档元信息	`kdoc.file.info`
上传图片	`kdoc.file.upload`
用户信息	`kdoc.user.info`
空间用量	`kdoc.space.quota`
能力上报	`kdoc.report.unsupported`
SKILL 更新检查	`kdoc.skill.update_check`

常见工作流

1. 创建+编辑文字文档

text

步骤1: kdoc.file.create(name="会议纪要", type="doc")
步骤2: kdoc.local.docx.generate(content="会议内容...", template="meeting_notes")
步骤3: kdoc.file.upload(file_path="output.docx", file_id=<file_id>)
返回: docs.qq.com/doc/<file_id>

2. 创建+编辑电子表格

text

步骤1: kdoc.et.create(name="销售数据")
步骤2: kdoc.et.range.write(sheet_id=<id>, range="A1:C10", values=[...])
步骤3: kdoc.et.formula.set(sheet_id=<id>, cell="D1", formula="=SUM(C1:C10)")
返回: docs.qq.com/sheet/<file_id>

3. 创建多维表格

text

步骤1: kdoc.dbt.create(name="客户管理")
步骤2: kdoc.dbt.field.add(table_id=<id>, name="客户名", type="text")
步骤3: kdoc.dbt.field.add(table_id=<id>, name="签约金额", type="number")
步骤4: kdoc.dbt.record.add_batch(table_id=<id>, records=[{...}])
返回: docs.qq.com/dbt/<file_id>

4. 搜索并读取文档

text

步骤1: kdoc.file.search(keyword="合同", limit=10)
步骤2: kdoc.file.info(file_id=<file_id>)
步骤3: kdoc.file.content(file_id=<file_id>)
返回: 文档内容

5. 恢复误删文件

text

步骤1: kdoc.trash.list(limit=20)
步骤2: kdoc.trash.recover(file_id=<file_id>)
返回: 已恢复文件信息

6. 回滚到历史版本

text

步骤1: kdoc.version.list(file_id=<file_id>)
步骤2: kdoc.version.restore(file_id=<file_id>, version=<target_version>)
返回: 回滚结果

7. 本地文件上传

text

步骤1: kdoc.space.list()  → 选择目标文件夹
步骤2: kdoc.file.upload(file_path="D:\docs\报告.pdf", folder_id=<id>)
步骤3: kdoc.file.permission(file_id=<id>, members=[{email: "xxx", role: "editor"}])
返回: 上传成功 + 文档链接

8. 格式转换

text

步骤1: kdoc.office.convert(file_id=<id>, target_format="pdf")
步骤2: kdoc.file.download(file_id=<转换后的file_id>, save_path="D:\output.pdf")
返回: 下载成功

9. 多维表格 Webhook 设置

text

步骤1: kdoc.dbt.webhook.set(table_id=<id>, callback_url="https://your-app.com/webhook", events=["record.add", "record.update"])
步骤2: kdoc.dbt.webhook.list(table_id=<id>)
返回: Webhook 配置确认

10. 批量导入数据

text

步骤1: kdoc.batch.create(operation="import", files=[...])
步骤2: kdoc.batch.query(task_id=<task_id>)  → 轮询直到完成
返回: 导入结果 + 成功/失败统计

核心规则（铁律）

🚨 品类隔离：通过 kdoc.file.info 识别品类后按路由表选择对应工具集。严禁用 A 品类的工具改 B 品类文档。
📦 批量优先：电子表格/多维表格连续 3 次及以上写入必须用批量接口（kdoc.et.range.write / kdoc.dbt.record.add_batch）。
🔒 权限前置：所有写入操作前必须调用前置权限校验。
🔄 异步轮询：批量任务、格式转换等异步操作，必须使用子会话轮询，主会话保持响应。
🗑️ 软删除：删除必须走回收站 API（kdoc.file.delete → 回收站），不物理删除。
📝 审计日志：所有写操作必须记录到本地审计日志。
⚡ 限流退避：收到 429 必须自动指数退避重试（间隔 2^n 秒 + 随机抖动，最多 5 次）。
🔀 版本防冲突：写入前获取 file.version，写入时带版本号，冲突时提示用户合并。

风险项与限制

风险项	影响	规避措施
🔑 账号权限未配置	无法调用任何 API	首次使用弹出授权页引导绑定金山开放平台 App
💰 API 配额不足（测试应用 500 次/天）	写入操作被拒绝	提示用户申请正式应用（100,000 次/天）
📝 文字/演示只能文件级远程编辑	无法逐段/逐页编辑	自动降级为"本地生成 → 上传覆盖"模式
🗑️ 图片 OCR 不支持	无法直接识别图中文字	仅支持在线文档→纯文本提取；图片需先转在线文档
📦 大文件上传超时（>100MB）	上传失败	自动切换为异步上传 + 进度轮询
🔀 版本冲突	多人同时编辑导致数据丢失	写入前校验版本号，冲突时提示手动合并
📵 网络依赖	所有功能需联网	提示用户确保网络连接；关键操作支持离线暂存

错误码

错误码	含义	解决方案
KD001	Token 鉴权失败	重新执行 `setup.sh` 授权
KD002	权限不足	升级应用权限或联系管理员
KD003	配额不足	申请提额或购买配额
KD004	文档类型不匹配	执行 `kdoc.file.info` 确认品类后按路由表
KD005	文档不存在	检查 `file_id` 是否正确
KD006	限流触发（429）	自动指数退避重试
KD007	版本冲突	获取最新版本后重新写入
KD008	文件过大	走异步上传
KD009	文件类型被拦截	检查 MIME 类型，可执行文件禁止上传
KD010	服务暂时不可用	稍后重试或联系支持
KD011	参数错误	检查 file_id、content 等必填参数
KD012	文件夹不存在	检查 `folder_id` 是否正确
KD013	表单已截止	收集表已过截止日期
KD014	Webhook 回调失败	检查回调 URL 是否可访问
KD015	转换失败	格式不支持或文件损坏

🔄 自动更新提示

每天首次使用 KingDoc 时自动检查更新。 发现新版本时，AI 会主动提示您升级，不会自动安装。

bash

# 手动检查更新
python -m engine.update_check --version 2.1.0

📋 更新历史

v2.1.0 — 2026-07-02

新增功能

✅ 新增每日首次使用自动检查更新提示
✅ 新增文档纯文本提取 API（kdoc.office.extract）
✅ 新增格式转换 API（kdoc.office.convert）
✅ 新增多维表格 Webhook 事件监听（kdoc.dbt.webhook.set）
✅ 新增批量异步任务（kdoc.batch.create / kdoc.batch.query）
✅ 新增通知推送（kdoc.notification.send 支持企微/钉钉/金山协作）
✅ 新增版本历史回滚（kdoc.version.list / kdoc.version.restore）
✅ 新增回收站完整操作（kdoc.trash.*）

体验优化

🔧 SKILL.md 新增「⚠️ 首次使用必读」两步引导
🔧 安装脚本自动生成 mcp-config.json、模板文件和占位图标
🔧 错误码从 KD001-KD015 扩展到 15 个精确定位
🔧 11 个常见工作流全部基于真实金山 API

安全增强

🛡️ 5 层安全防御模型（用户确认/权限前置/输入校验/操作保护/限流配额）
🛡️ 文件 ID 正则校验
🛡️ 可执行文件 MIME 双层拦截
🛡️ 限流指数退避重试（2^n + 随机抖动）
🛡️ 操作审计日志

v2.0.0 — 2026-07-02

初始版本

🎭 6 品类全功能（文字/电子表格/演示文稿/多维表格/收集表/附件）
📄 40+ MCP 工具实现
🔗 OAuth Client Credentials 鉴权
📝 DOCX/PPTX 本地生成 + 上传覆盖
🧭 场景路由表（4 大类 × 6 品类）
🗃️ 电子表格精细编辑（单元格/公式/图表/筛选/排序）
🗃️ 多维表格精细编辑（记录/字段/视图）
📋 11 个可运行工作流
📖 6 个参考文档

详细文档参考

文档	路径
鉴权流程	`references/auth.md`
多维表格 API	`references/dbt_references.md`
电子表格 API	`references/et_references.md`
文本提取/格式转换	`references/office_references.md`
限流策略	`references/rate_limit.md`
安全设计	`references/security.md`

安装说明

前置要求：

Python 3.10+
金山开放平台 App（AppID + AppSecret）

快速安装：

bash

# Linux / macOS
bash setup.sh

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File setup.ps1

安装完成后重启 WorkBuddy 即可生效。

最后更新：2026-07-02 | v2.1.0