KingDoc — 金山文档 AI 协作助手 v3.0.0

对标腾讯文档 TENCENT DOCS，功能 1:1 覆盖 + 差异化增强。 v3.0.0 重点：深度直连在线文档原生 API、危险操作强制确认、硬件自适应性能、免密钥本地能力。

📣 评测反馈与本轮（v3.0.0）优化说明

本版本针对第三方评测（综合 4.5/5「优秀」）的降分项做了逐项闭环：

⚠️ 首次使用必读

1. 申请金山开放平台 App（免费，仅云端协作需要）

只影响「上传到云端 / 多人协作 / 回收站 / 版本」等联网能力。 本地生成文档、本地 OCR、硬件画像完全不需要 Key，开箱即用。

申请步骤：

1. 访问 金山开放平台 并登录金山文档账号
2. 进入「应用管理」→「创建应用」，获取 App ID 和 App Secret
3. 勾选权限（OAuth Scope）：
   • 必须：user:file:write、user:file:read、team:file:write、team:file:read
   • 建议：user:team:read、user:notification:write
4. 测试阶段限速 500 次/天，正式版 10 万次/天

2. （可选）安装本地 Tesseract OCR

仅「图片文字提取」需要；未装则自动降级云端 OCR 或给指引，不影响其他功能。

# Windows
winget install UB-Mannheim.TesseractOCR
# macOS
brew install tesseract tesseract-lang
# Linux
sudo apt-get install tesseract-ocr tesseract-ocr-chi-sim

3. 配置并加载

# Linux/macOS
bash setup.sh
# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File setup.ps1

脚本引导输入 App ID/Secret，自动生成 config.json、mcp-config.json、模板与图标，并采集本机硬件画像。

快速开始

5. 自然语言触发示例（高级功能怎么表达）

为避免「不知道怎么开口」，以下给可直接说的话：

• 批量建表："新建客户管理多维表格，字段：客户名(文本)、签约金额(数字)、状态(单选)，并一次写入 20 条记录"
• 格式转换："把《Q2 报告》导出成 PDF" / "转成 Word 发我"
• OCR 转文档："识别这张发票图片，生成一份 Word 报销单" / "把这张表格图片转成在线电子表格"
• 网页剪藏："把这个网页 https://... 收藏成金山文档"
• 通知推送："导入完成后用企微机器人通知我"
• 版本回滚："列出这份文档的历史版本，回退到 7 月 1 日那版"
• 权限管理："给团队文件夹『2026 项目』里的文档设置只读"
• 本地免密钥生成："本地生成一份周报 DOCX，不用上传"（无需 App Key）

安全声明

6. 🚨 危险操作强制确认（v3.0.0 新增铁律）

评测指出「部分危险操作缺少强制确认」。以下操作执行前必须向用户显式确认， 列出具体影响，待用户明确同意后方可进行；绝不静默执行。

确认模式（config.json 可配）：

{ "safety": { "confirm_mode": "dangerous", "dry_run": false, "audit_enabled": true } }

• dangerous（默认）：仅上表危险操作需确认
• always：所有写操作均确认
• dry_run: true：只展示将要执行的操作，不真正调用

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

核心能力矩阵

1️⃣ 文档创建（9 品类全覆盖）

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

先 kdoc.file.info 确定品类，再路由对应工具集。严禁跨品类操作。

3️⃣ 文件管理

4️⃣ 格式转换与 OCR

5️⃣ 扩展能力（金山独有）

6️⃣ 本地免密钥工具（无需 App Key）

7️⃣ WPS AI 能力（v3.2.0 新增，本地降级优先）

WPS AI 目前无公开开发者 API，本模块采用本地降级 + 自研逻辑实现，零密钥可用。 未来如 WPS AI 开放 API，只需新增后端即可升级，无需改动上层。

后端策略：本地降级优先 → 未来可扩展 WPS Open API / COM 自动化 / Web API

10. 协同编辑冲突解决（v3.3.0 新增，自研 difflib 实现）

多人同时编辑同一文档时经常出现冲突（A 修改了第 3 段，B 也修改了第 3 段）。 本模块提供冲突检测 + 智能合并 + 可视化 diff + 解决模板，零外部依赖。

10.1 冲突检测

10.2 工具列表

10.3 工作流程

① 检测：kdoc.version.list → 取最近 2-3 个版本 → conflict.detect() → 冲突块列表
② 合并：conflict.merge() → 自动合并无冲突段 + 标注冲突段 → 合并建议
③ 可视化：conflict.diff() → Git 风格并排 diff（可导出 HTML）
④ 解决：用户选模板 → conflict.resolve() → ⚠️ 强制确认 → kdoc.file.upload 覆盖回云端

10.4 解决模板

10.5 安全约束

• 合并结果覆盖回云端属于「覆盖文件」危险操作，必须走强制确认铁律（见第 6 节）
• 冲突段绝不自动覆盖，必须用户明确选择
• 大文档 diff 自动分块处理，不拖累电脑（硬件自适应）

11. 完整场景案例（v3.0.0 新增）

场景 A：月度销售复盘（全链路）

1) kdoc.et.create(name="2026-07 销售复盘")
2) kdoc.et.range.write(sheet_id, "A1:C21", 表头+20 行数据)   ← 批量写入
3) kdoc.et.formula.set(sheet_id, "D2", "=C2*0.1")            ← 提成列
4) kdoc.office.convert(file_id, "pdf")                       ← 导出 PDF
5) kdoc.notification.send(channel="wecom", content="复盘已生成")

场景 B：合同 OCR → 在线文档（免密钥本地优先）

1) kdoc.local.ocr.extract("contract.jpg")        ← 本地 Tesseract，无需 Key
2) kdoc.local.docx.generate(content=, template="contract")
3) kdoc.file.upload(file_path="output.docx")     ← 上传为在线文档

场景 C：项目规划脑图 + 流程图（本地渲染）

1) kdoc.local.mindmap.generate(code="graph TD; 目标-->阶段1; 阶段1-->任务A")
2) kdoc.local.flowchart.generate(code="flowchart TD; 开始([开始])-->审核{通过?}")
3) 分别 kdoc.file.upload 两个 SVG → 在线可视化

场景 D：误删恢复（金山独有）

1) kdoc.trash.list(limit=20)
2) kdoc.trash.recover(file_id)        ← 救回，不丢数据

场景 E：大批量导入（硬件自适应）

1) kdoc.local.hardware.profile → 取得 workers/batch_chunk
2) 按 batch_chunk 分块调用 kdoc.batch.create
3) kdoc.batch.query 轮询直至完成（并发不超过 workers，不卡机）

场景 F：多人协作冲突解决（v3.3.0 新增）

1) kdoc.version.list(file_id) → 获取最近 3 个版本（基准版 + A修改 + B修改）
2) kdoc.conflict.detect(base, a, b) → 检测冲突块
3) kdoc.conflict.merge(base, a, b) → 自动合并无冲突段 + 标注冲突段
4) kdoc.conflict.diff(a, b) → Git 风格可视化
5) 用户选择保留A/保留B/手动合并 → kdoc.conflict.resolve(strategy="keep_a")
6) ⚠️ 强制确认 → kdoc.file.upload 覆盖回云端

12. 核心规则（铁律）

1. 🚨 品类隔离：先 kdoc.file.info 识别品类再路由，严禁跨品类操作。
2. 📦 批量优先：电子表格/多维表格连续 3+ 写入必须用批量接口。
3. 🔒 权限前置：所有写入前必须校验权限。
4. 🔄 异步轮询：批量/转换/剪藏必须子会话轮询，主会话保持响应。
5. 🗑️ 软删除：删除必须走回收站 API，不物理删除。
6. 📝 审计日志：所有写操作必须记录本地审计日志。
7. ⚡ 限流退避：收到 429 必须自动指数退避（最多 5 次）。
8. 🔀 版本防冲突：写入前获取 version，冲突时提示合并。
9. ✅ 危险操作强制确认（v3.0.0）：见第 6 节，未确认不执行。
10. 🧠 性能不拖累：批量/渲染并发不得超过 kdoc.local.hardware.profile 给出的 workers。

13. 能力边界与失败场景（v3.0.0 新增，务必看清）

明确不支持：本地直接修改已上传 DOCX/PPTX 的某一段（需整文件重生成）； 对加密/损坏文件 OCR；超过配额的非付费批量操作。

14. 风险项与限制

15. 深度绑定在线文档（v3.0.0 强化）

KingDoc 直连金山文档（WPS）开放平台原生 API（https://developer.kdocs.cn/api/v1/openapi）， 而非简单桥接：

• 原生能力全覆盖：文件/文件夹/回收站/版本/权限/空间/通知/用户均调用官方端点。
• 精细编辑：电子表格走 et API（单元格/公式），多维表格走 dbt API（记录/字段/视图）。
• 本地增强：文字/演示/脑图/流程图用本地库生成原生格式（DOCX/PPTX/SVG）后上传覆盖， 既保真又免去服务端复杂排版。
• 政企可用：国内网络直连、文档全中文、权限模型对齐企业协作。

16. 四大 MCP 服务（v3.0.0 架构）

4 个 MCP 服务共享同一 Token，可独立限流、独立降级。

17. 性能与硬件自适应（v3.0.0 新增，绝不拖累电脑）

engine/hardware.py 在首次运行时自动采集本机 CPU 核数/内存并计算出安全并发：

• 画像缓存到 .kingdoc_hardware_profile.json（30 分钟复用），不频繁探测。
• 批量写表、脑图/流程图并行渲染不得超过 workers，保证用户电脑流畅。
• AI 在执行批量/渲染任务前应调用 kdoc.local.hardware.profile 读取参数。

python -m engine.hardware          # 查看本机画像与推荐参数

18. 🚫 禁止上传的文件类型（v3.0.0 强化）

为安全，用户「上传附件」默认拦截以下全部类型（来源：产品安全规范）：

1. Windows 可执行/批处理：.bat .cmd .ps1 .vbs .exe .dll .lnk .msi
2. Office 二进制文档：.docx .xlsx .pptx .doc .xls .ppt .xlsm .docm .pptm
3. 二进制镜像/安装包：.iso .dmg .zip .rar .7z .tar .gz .apk .jar
4. 系统缓存/隐藏文件：.DS_Store .git（目录） .env .log .tmp
5. 其他风险脚本：.sh .com .scr .hta .reg

内部豁免：技能「本地生成→上传覆盖」产物（.docx/.pptx/.xlsx/.pdf/.svg/.png/.txt/.md 等）经 internal=True 通道上传，仅限技能自身生成，用户无法借道上传任意同类文件。 命中拦截将抛出 KD009。详见 references/security.md。

19. 错误码

20. 🔄 自动更新提示与反馈

每天首次使用自动检查更新（本地缓存，每天仅查一次，离线不打扰）。 发现新版本时 AI 会主动提示升级，不会自动安装：

# 手动检查 / 仅看提醒文案
python -m engine.update_check --version 3.0.0 --reminder

📮 有更好建议：njskills@agent.qq.com

更新日志

| v3.3.0 | 2026-07-21 | 增加：协同编辑冲突解决模块 engine/conflict_resolver.py（自研 difflib 实现，零第三方依赖）；增加：冲突检测 kdoc.conflict.detect、智能合并 kdoc.conflict.merge（自动合并无冲突段 + 标注冲突段）、Git diff 可视化 kdoc.conflict.diff、解决模板 kdoc.conflict.resolve（keep_a/keep_b/manual/auto_merge）；增加：冲突解决 MCP 工具 4 个；增加：大文档 diff 分块硬件自适应处理；增加：多人协作冲突解决场景案例；优化：冲突段强制用户确认，绝不自动覆盖 | | v3.2.0 | 2026-07-17 | 增加：WPS AI 能力适配层（写作辅助/数据分析/PPT 生成/阅读助手），本地降级优先、自研逻辑实现、零密钥可用；增加：WPS AI 适配器 engine/wps_ai/adapter.py；增加：本地降级后端 engine/wps_ai/backends/local_fallback.py；增加：能力定义与意图映射 engine/wps_ai/capabilities.py；增加：WPS AI API 调研记录 engine/wps_ai/research_notes.md；优化：MCP Server 注册 5 个 WPS AI 工具；优化：版本号 3.0.0→3.2.0 | | v3.1.0 | 2026-07-15 | 增加：wps-office-suite 互通方案调研（已废弃，因平台合规不允许双 skill 互通） | | v3.0.0 | 2026-07-12 | 增加：危险操作强制确认铁律与确认清单（删除/彻底删除/覆盖/批量/权限/清空回收站/版本回滚/Webhook）；增加：禁止文件类型扩展至完整 35 类（执行脚本/Office 二进制/归档镜像/系统文件/风险脚本）；增加：用户上传拦截与技能内部生成豁免白名单；增加：engine/hardware.py 硬件自适应性能调度（自动采集 CPU/内存，自动分配并发子进程数与批量分块）；增加：本地 OCR 模块 engine/local/ocr.py（优先本地 Tesseract，降级云端，给安装指引）；增加：能力边界与失败场景专章；增加：自然语言触发示例专章；增加：完整场景案例专章（5 个端到端场景）；增加：FAQ 专章（8 个高频问题）；补齐：缺失参考文档 et_references.md/office_references.md/rate_limit.md；补齐：技能图标 assets/icon.png；补齐：engine/__init__.py 与 engine/api/mcp_server.py（真实 MCP Server 入口）；优化：MCP Server 深度直连金山文档开放平台原生 API；优化：每日更新提醒 + 反馈邮箱 njskills@agent.qq.com | | v2.3.0 | 2026-07-05 | 增加：智能文档/思维导图/流程图 3 品类，品类总数 6→9；增加：本地 Tesseract OCR；增加：网页剪藏；增加：HTML 一键上云；优化：MCP 服务拆分 1→4，独立限流/降级 | | v2.1.0 | 2026-07-02 | 增加：每日自动更新检查；增加：纯文本提取 API；增加：多维表 Webhook 事件监听；增加：批量异步任务；增加：SKILL.md 首次使用必读引导 | | v2.0.0 | 2026-07-02 | 初始版本发布：6 品类 + 40+ MCP 工具 + 5 层安全防御 |

22. 详细文档参考

23. 安装说明

前置要求：Python 3.10+；云端功能需金山开放平台 App（免费）；OCR 可选装 Tesseract。

# Linux / macOS
bash setup.sh
# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File setup.ps1

安装后重启 WorkBuddy 生效。本地生成/OCR/硬件画像无需任何配置即可用。

24. 📮 反馈与建议

本技能持续迭代。有任何功能建议、问题或更好的实现思路，欢迎反馈：

📧 有更好建议：njskills@agent.qq.com

也可在每日更新提醒中一键查看新版本。

25. ❓ FAQ（v3.0.0 新增）

Q1：没有金山 App Key 能用吗？ 能。本地生成 DOCX/PPTX、思维导图/流程图 SVG、本地 OCR、硬件画像均零密钥可用； 仅「上传云端/多人协作/回收站/版本」等联网能力需 Key。

Q2：为什么删除前要确认？ 防止误操作。删除进回收站可恢复；「彻底删除」「清空回收站」为不可逆操作，需二次确认（见第 6 节）。

Q3：OCR 一定要装 Tesseract 吗？ 首选本地 Tesseract（免费、离线、无 key）。未装时自动降级云端 OCR（需 Key），都无则给出安装指引，不崩溃。

Q4：大文件传不上去？ 超过阈值（默认 100MB，低端机 50MB）会自动转异步上传 + 轮询；仍失败请压缩或分卷。

Q5：会不会把我的电脑拖卡？ 不会。技能自动按本机硬件分配并发子进程数（见第 17 节），批量/渲染均受限。

Q6：报 KD009 文件被拦截？ 你上传的文件属于禁止类型（见第 18 节）。技能自身生成的 docx/pptx/pdf/svg 等不受影响。

Q7：如何升级？ 每天首次使用会自动提醒；也可 python -m engine.update_check --version 3.0.0 --reminder。

Q8：文字/演示文档能改其中一段吗？ 当前为整文件替换模式：本地改源文件→重新上传覆盖。逐段精细编辑需金山在线编辑器。

最后更新：2026-07-12 | v3.0.0