腾讯文档

要解决的问题

在自动化工作流或构建 AI Agent 时，经常需要程序化地创建、读取或编辑云文档。然而，不同类型的文档（如 PPT、Excel、智能文档）拥有各自独立的 API 和内部结构。开发者需要逐一适配多个 API 端点，处理不同的参数和返回值，这带来了显著的集成复杂性和维护成本。如何用统一的方式高效、安全地操作腾讯文档生态中的所有文件类型，是一个具体且常见的需求。

技能如何工作

腾讯文档 MCP 技能将上述复杂性封装为一套结构化的工具集和路由规则。

1. 文档类型路由与工具集分离

技能的核心是场景路由表。它首先通过文件 ID 或链接前缀识别文档的品类（如 sheet、slide、smartcanvas），然后严格路由到对应的工具集。例如：

• 对于 PPT / 幻灯片（文件链接含 /slide/ 或提及“幻灯片”），必须使用 slide-mcp 服务的 slide_* 系列工具，并遵循其专用工作流。
• 对于 智能文档，使用 create_smartcanvas_by_mdx 进行创建，或 smartcanvas.* 工具进行编辑。
• 对于 Excel，则使用 sheet-mcp 的 sheet.* 工具。

这种设计确保了每种文档类型都由为其专门设计的 API 处理，避免了用错误工具操作导致结构损坏的问题（对应错误码 400016）。

2. 关键工作流

• 创建文档：根据意图关键词（如“报告”、“PPT”、“脑图”）路由到对应的 create_* 方法。例如，创建思维导图使用 create_mind_by_markdown，创建流程图使用 create_flowchart_by_mermaid。
• 内容编辑与管理：编辑时必须先判断原文件类型，再使用对应工具。文件管理操作（重命名、移动、权限）则使用 manage.* 系列工具。
• 批量操作：为优化性能和成本，当对同一文档进行连续多次写入时（如向表格插入多行），技能要求使用批量接口（如 smartsheet.add_records）一次性提交，而非循环调用单条写入接口。

3. 公共能力与转换

技能还提供了跨类型的公共能力：

• get_content：一个通用的文档内容读取接口。
• 网页剪藏：通过 scrape_url 将 URL 内容转换为智能文档。
• 本地文件上云：通过 import_file.sh 脚本将本地文件导入。
• OCR 图片识别：将图片转换为 Word 或 Excel 文档。

适用边界与注意点

• PPT 任务的特殊性：所有与 PPT 相关的需求（生成、编辑、续写）都必须通过 slide-mcp 的专用工具链完成，使用 doc-mcp 或通用工具会导致内容或行为错误。
• 授权与配额：使用前需完成本地授权（错误码 400006）。VIP 权限（400007）或积分不足（400008）会限制部分功能。
• 参数与格式：文档创建工具中的 mdx 参数直接兼容 Markdown 语法。使用 OCR 时，公网 URL 和 base64 二选一，本地图片必须通过特定脚本处理。
• 异步任务：网页剪藏等异步操作，建议使用独立的子会话进行轮询，以避免阻塞主交互流程。

该技能本质上是为开发者提供的一个协议层，将分散的文档 API 按逻辑聚合，并强制执行最佳实践（如类型匹配、批量写入），使得构建可靠的文档自动化流程成为可能。