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

⚠️ 首次使用必读

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

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

申请步骤：

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

2. 配置 KingDoc

拿到 App ID 和 Secret 后执行：

# Linux/macOS
bash setup.sh

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

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

快速开始

安全声明

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

场景路由表

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

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

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

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

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

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

公共能力

常见工作流

1. 创建+编辑文字文档

步骤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. 创建+编辑电子表格

步骤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. 创建多维表格

步骤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. 搜索并读取文档

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

5. 恢复误删文件

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

6. 回滚到历史版本

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

7. 本地文件上传

步骤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. 格式转换

步骤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 设置

步骤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. 批量导入数据

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

核心规则（铁律）

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

风险项与限制

错误码

🔄 自动更新提示

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

# 手动检查更新
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 个参考文档

详细文档参考

安装说明

前置要求：

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

快速安装：

# Linux / macOS
bash setup.sh

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

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

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