Tencent Saas Docs

腾讯文档企业版 MCP 使用指南

本 skill 面向腾讯文档企业版（saas.docs.qq.com），通过 MCP 对云端文档进行管理与编辑。

🚨 多 endpoint 架构：能力分散在 4 个独立 MCP endpoint 上，调用前认准 service 名—— doc / sheet / slide 的精细编辑分别走 doc-mcp / sheet-mcp / slide-mcp， 文件管理 / 创建 / 搜索 / 剪藏 / smartcanvas / smartsheet 走主服务 tencent-saas-docs。 4 个 endpoint 共用同一套宿主票据。

前置：鉴权 / 调用方式

本 skill 运行在 tencent-docs-plugin 插件中，鉴权完全依赖宿主（如 Workbuddy 连接器）注入的票据， 不走 OAuth 授权页。所有工具调用一律走 tencentdocs.py 的 tdoc_call 入口（纯 Python 标准库，跨平台，Windows 无需 bash/curl），由它在调用时通过 HTTP header 即时透传票据到服务端，不落盘。详见 references/auth.md。

首次使用前执行一次环境检查：

python3 tencentdocs.py tdoc_init
#   READY            → 已就绪，直接干活
#   ERROR:no_token   → 请在宿主（Workbuddy）中完成腾讯文档授权后重试

调用任意工具：

python3 tencentdocs.py tdoc_call <service> <tool> '[json_args]'

🚨 调用任何工具前，必须先查它的参数定义，严禁凭记忆/猜测拼参数：

python3 tencentdocs.py tdoc_schema <service> <tool>   # 输出该工具描述 + 参数（✓=必填）

按 tdoc_schema 返回的参数名/类型/必填项构造 json_args 再 tdoc_call；需要原始 JSON Schema 加 --raw。工具清单用 tdoc_list <service>。

查看某 endpoint 的真实工具清单：python3 tencentdocs.py tdoc_list <service>； 查单个工具的参数定义：python3 tencentdocs.py tdoc_schema <service> <tool>。

能力总览

A. 文档列表 / 空间管理 ·（tencent-saas-docs）

跨品类的文件与空间管理（增删改、移动、搜索、权限、导入导出、网页剪藏、知识库空间），不区分文档类型。 完整工具清单见 manage.md；知识库空间见 references/space_references.md。

file_id 的来源在这里 —— 一切内容操作都先在本类工具里拿到目标文档的 file_id。

B. 文档内容操作（按品类分 5 类）

每个品类的具体工具清单、用法、所属 endpoint 见对应子文档（编辑 / 创建分开）：

⚠️ doc / sheet / slide 别用主服务的转发工具——一律走对应 engine endpoint （doc-mcp / sheet-mcp / slide-mcp），主服务的同名转发是阉割子集，能力不全。

C. 创建类入口 ·（tencent-saas-docs）

D. 上云 / 公共能力

核心规则

• 🚨 PPT / 幻灯片编辑强制走 slide-mcp：对已有 PPT 做编辑修改时，必须用 slide-mcp 的 slide_* 工具 （见 slide/edit.md）。严禁用 doc / 主服务通用工具改 PPT——它们不支持 slide 内部结构 （shape_id / page_index / 母版等）。从零创建整份 PPT 见 slide/create.md（🚧 待补充）。
• 先定品类再选工具：用 manage.query_file_info 或文档链接前缀确定文档类型，再路由到对应品类工具集； 严禁用 A 品类工具改 B 品类文档。
• 优先批量写入：对同一文档连续 3 次及以上写入时，必须用批量接口一次提交 （如 smartsheet.add_records / set_range_value / 批量插入类），严禁单条循环调用。
• 保存 Markdown 内容：直接填 create_smartcanvas_by_mdx 的 mdx 参数，MDX 向下兼容全部 Markdown，无需转换。
• 本地文件落盘：一律 python3 import_file.py → manage.apply_upload → manage.complete_upload → manage.query_task，保留原文件结构， 不要用 create_* 重新生成内容。
• 整理 / 归档 / 转写 / 纪要：把对话内容落云端时优先 create_smartcanvas_by_mdx（排版美观、组件丰富）。
• URL 链接：单独走 manage.scrape_url → manage.scrape_progress 剪藏通路。
• node_id 即 file_id；删除空间节点谨慎（delete_space_node 默认仅删当前节点，all 递归删子节点）。
• 异步任务用 spawn 子会话轮询：scrape_url 等异步任务推荐 spawn 子会话专职轮询，主会话保持响应。
• 找不到能力先上报：用户需求无对应工具时，静默调用 report_unsupported_feature（{"feature":"..."}，走 tencent-saas-docs）上报后再说明，不要臆造调用。
• 工具清单以服务端为准：本文档工具表可能滞后，权威来源是各 endpoint 的 tdoc_list <service>。

常见错误码