tencent-docs

# 腾讯文档 MCP 使用指南 腾讯文档 MCP 提供了一套完整的在线文档操作工具，支持创建、查询、编辑多种类型的在线文档。 ## 支持的文档类型 | 类型 | doc_type | 推荐度 | 说明 | |-------| -------------------- | ------------ | ------------------------------------------------------ | | 智能文档 | smartcanvas | ⭐⭐⭐ | 排版美观，支持丰富组件；MDX 格式兼容全部 Markdown 语法 | | Excel | sheet / tencentsheet | ⭐⭐⭐ | 数据表格专用 | | PPT | slide / tencentslide | ⭐⭐⭐ | 幻灯片，演示文稿专用 | | 思维导图 | mind | ⭐⭐⭐ | 知识图谱专用 | | 流程图 | flowchart | ⭐⭐⭐ | 流程展示专用 | | Word | doc / tencentdoc | ⭐⭐ | 传统格式，排版一般 | | 收集表 | form / tencentform | ⭐⭐ | 表单收集 | | 智能表格 | smartsheet | ⭐⭐⭐ | 高级结构化表格，支持多视图、字段管理 | | Html | smartpage | ⭐⭐⭐ | html演示文稿专用 | ## ⚙️ 快速配置 本 skill 由 Pinvou 插件中心的「腾讯文档 MCP」连接器自动安装，四个 MCP 服务（tencent-docs / tdoc-slide / tdoc-doc / tdoc-sheet）共用同一个 Token，已由连接器写入本机系统凭据，无需在对话中配置。鉴权报错时见 `references/auth.md` 的处理指引。 ## 🎯 场景路由表 **先判断用户的操作意图属于以下 4 大类中的哪一类，再按子表路由到对应工具与参考文档。** 同一句话可能混合多个意图（如"把这份 PPT 改一下并重命名"），按"主操作"归类，必要时分步执行。 ``` 用户意图 ├─ 想"从无到有"产出一份文档 → 1️⃣ 文档创建 ├─ 想修改 / 增删 已有文档的内容 → 2️⃣ 文档改写、内容增删 ├─ 只动文件/目录本身（不碰内容） → 3️⃣ 文件管理动作 └─ 想把图片/其他格式转成文档 → 4️⃣ 转换工具 ``` ### 1️⃣ 文档创建（从无到有新建文档） 根据用户意图**识别目标品类**，路由到该品类的创建方法。**创建空白文档使用 `manage.create_file`**。 | 用户意图 / 关键词 | 品类 | 首选创建方法 | 参考文档 | |-------------------------------------------|-------------|------------------------------------------------|--------------------------------------| | PPT / 幻灯片 / 演示文稿（生成整份 / 续写 / 改页等所有 PPT 任务） | slide | **走 Slide 品类工作流（JSX + tdoc-slide）** | `slide/entry.md` | | 思维导图 / 脑图 / 层次化知识整理 | mind | **`create_mind_by_markdown`** | `references/diagram_references.md` | | 流程图 / 架构图 / 流程展示 | flowchart | **`create_flowchart_by_mermaid`** | `references/diagram_references.md` | | 报告 / 笔记 / 文章 / 总结 / 会议纪要 / Markdown | smartcanvas | **`create_smartcanvas_by_mdx`** | `smartcanvas/entry.md` | | 论文 / 公文 / 合同等专业 Word 文档 | doc | doc 品类创建 | `doc/entry.md` | | 数据表格 / 计算 / 统计（Excel） | sheet | sheet 品类创建 | `sheet/entry.md` | | 结构化数据管理 / 多视图表格 | smartsheet | smartsheet 品类创建 | `references/smartsheet_references.md` | | 收集表 / 表单 | form | `manage.create_file` | `references/manage_references.md` | | **空文件 / 上述品类创建失败的兜底** | — | **`manage.create_file`** | `references/manage_references.md` | ### 2️⃣ 文档改写、内容增删（编辑已有文档） **先判断原始文档的类型**（通过 `file_id` / 文档链接前缀 / `manage.query_file_info`等手段确定品类），**再路由到对应品类的编辑工具集**。严禁用 A 品类的工具去改 B 品类文档。 | 原始文档类型 | 品类 | 编辑工具集 | 参考文档 | | ------------------------------------------------------------------------------------- | ------------ | --------------------- |--------------------------------------------| | 智能文档（报告/笔记/文章） | smartcanvas | `smartcanvas.*` | `smartcanvas/entry.md` | | **PPT / 幻灯片**（增删页 / 形状 / 文本 / 表格 / 图表 / 批注 / 动画 / 主题 / 备注等） | slide | **`slide_*`（tdoc-slide）**，统一按 Slide 工作流执行 | **`slide/entry.md`（工作流） + `references/slideengine_references.md`（工具 API）** | | Word 文档 | doc | `doc.*`（tdoc-doc） | `references/docengine_references.md` | | Excel / 计算 / 筛选 / 统计 / 保护区域 | sheet | `sheet.*`（tdoc-sheet）| `sheet/entry.md` | | 智能表格（结构化数据管理） | smartsheet | `smartsheet.*` | `references/smartsheet_references.md` | ### 3️⃣ 文件管理动作（不改内容，只动文件 / 目录 / 权限） | 动作 | 参考文档 | | ---------------------------------------------------------- | ----------------------------------- | | 重命名 / 移动 / 删除 / 复制 / 导入导出 / 权限变更 | `references/manage_references.md` | | 知识库空间管理（创建空间 / 空间列表 / 节点 / 文件夹结构） | `references/space_references.md` | ### 4️⃣ 转换工具（图片 / 格式转文档） | 场景 | 工具 | 参考文档 | | --------------------------------------------- | --------- | --------------------------------- | | 图片识别 / 图片转 Word / 图片转 Excel（OCR） | `ocr.*` | `references/ocr_references.md` | ### 📎 公共能力 | 场景 | 参考文档 | | ------------------------------------------------- | ---------------------------------------------------- | | 获取文档内容 / 上传图片 | `references/workflows.md`（get_content / upload_image） | | 网页剪藏（URL → 文档） | `references/workflows.md`（scrape_url → scrape_progress） | | 本地文件 / HTML 一键上云（.aipage 打包 + 导入） | `references/aipage_references.md` | | 不支持能力上报（report_unsupported_feature） | `references/unsupported_feature_reporting.md` | ## 📁 文件目录结构 ``` tencent-docs/ ├── SKILL.md # 入口文件（本文件），全局导航与核心规则 ├── aipage_pack.js # 本地 HTML 打包成 .aipage ├── references/ # 参考文档（按品类/功能划分） │ ├── auth.md # 鉴权与授权流程 │ ├── workflows.md # 公共接口（get_content）+ 常见工作流 │ ├── aipage_references.md # 本地 HTML → .aipage 打包 + 导入完整工作流 │ ├── smartsheet_references.md # 智能表格（smartsheet）操作 │ ├── slideengine_references.md # 幻灯片 `slide_*` 系列工具完整 API Schema（必须通过独立的 tdoc-slide 服务调用，禁止用 doc_ 或 tencent-docs 通用工具改 PPT） │ ├── diagram_references.md # 思维导图 + 流程图创建 │ ├── docengine_references.md # Word 文档精细编辑（doc.* 系列工具，必须通过独立的 tdoc-doc 服务调用） │ ├── space_references.md # 知识库空间管理（空间/节点/文件夹） │ ├── manage_references.md # 文件管理（重命名/移动/删除/复制/导入导出/权限） │ ├── ocr_references.md # OCR 图片识别（ocr.extract / ocr.toword / ocr.toexcel） │ └── unsupported_feature_reporting.md # 不支持能力上报规则（report_unsupported_feature） ├── smartcanvas/ # 智能文档（smartcanvas）品类模块 │ ├── entry.md # 智能文档（smartcanvas）品类入口，创建与编辑。MDX 格式，兼容全部 Markdown 语法 │ └── mdx_references.md # MDX 格式规范（smartcanvas 内容格式） ├── doc/ # Word 文档（doc）品类模块 │ ├── entry.md # Word 品类入口，工作流指引 │ └── doc_format/ # Word 格式定义与模板 ├── slide/ # 幻灯片（slide / PPT）品类模块 │ └── entry.md # Slide 品类入口（生成 / 续写 / 改页 / 检查 等全工作流，统一走 JSX + tdoc-slide） ├── sidebar-pptx-generator/ # Slide 品类工作流的组件规范与脚本 │ ├── references/ # JSX 组件语法（component-*.md）+ DESIGN.md 编写规范 │ └── scripts/ # 状态脚本 get_slide_info.sh、图片素材提取 doc_image_extractor.py └── sheet/ # Excel 文档（sheet）品类模块 ├── entry.md # Sheet 品类入口（sheet.* 工具列表与工作流指引；必须通过独立的 tdoc-sheet 服务调用） └── api/ # Sheet 专用 API 定义 ``` ## 🔧 调用方式 在 Pinvou 中四个服务以 MCP 工具形式提供，模型直接调用（无需命令行）。注意：这些工具默认延迟加载——当前工具列表里没有时，先 `tool_search` 按名激活；`tool_search` 返回 `mcp_boot` connecting（MCP 服务仍在启动）就等待数秒重试，connecting 消失后仍搜不到，说明对应连接器本轮不可用，向用户说明即可，不要虚构工具名： | 服务 | 工具名前缀 | 用途 | |------|-----------|------| | tencent-docs | `mcp_tencent-docs_*` | 通用文档工具（创建/管理/搜索/OCR/网页剪藏 等） | | tdoc-slide | `mcp_tdoc-slide_*` | PPT 精细编辑（slide_* 前缀工具） | | tdoc-doc | `mcp_tdoc-doc_*` | Word 文档精细编辑（doc.* 前缀工具） | | tdoc-sheet | `mcp_tdoc-sheet_*` | Excel 表格精细编辑（sheet.* 前缀工具） | 调用参数以各工具的输入 Schema 为准；参数结构也可参考下方「API 详细参考」中的说明。 > ⚠️ 参考文档中的参数说明应与 MCP 工具 Schema 保持一致。如有冲突，以工具的输入 Schema 为准（四个服务共用同一 Token，但 endpoint 独立）。 ### 通用响应结构 所有 API 返回都包含： - `error`: 错误信息（成功时为空） - `trace_id`: 调用链追踪 ID ### API 详细参考 各品类工具的完整 API 说明（调用示例、参数说明、返回值说明）请参考场景路由表中对应的参考文档。公共接口和常见工作流详见 `references/workflows.md`。 ## 常见工作流 详见 `references/workflows.md`，包含以下内容： ### 公共接口 - **get_content**：获取文档完整内容，支持所有文档类型的通用读取接口 ### 工作流列表 - **搜索并读取文档**：manage.search_file 按关键词搜索 → 获取 file_id → get_content 读取内容 - **智能表格操作**：先 smartsheet.list_tables 获取 sheet_id，再使用 smartsheet.* 系列工具 - **文件管理**：manage.folder_list 获取目录 → manage.* 工具进行重命名、移动、删除、复制、权限设置 - **网页剪藏**：scrape_url 抓取网页 → scrape_progress 轮询进度 → 自动保存为智能文档（用户提供 URL 时必须优先使用此工作流） - **本地 HTML 一键上云**：`node aipage_pack.js` 打包成 .aipage → 调用 `mcp_tencent-docs_manage.pre_import` 获取上传地址 → shell `curl -X PUT` 上传 .aipage 到 COS → `manage.async_import` 触发 → `manage.import_progress` 轮询，详见 `references/aipage_references.md`。 - **OCR 图片识别**：`ocr.extract` 提取文字 / `ocr.toword` 图片转在线文档 / `ocr.toexcel` 图片转在线表格；本地图片先用 shell `base64` 读取编码后经 `mcp_tencent-docs_ocr.*` 工具调用，公网 URL 图片直接调用 ocr.* 工具，详见 `references/ocr_references.md` ## 核心规则 - **🚨 所有 PPT / 幻灯片任务统一走 Slide 工作流**：用户提供 `https://docs.qq.com/slide/<id>` 链接、或提及 "PPT / 幻灯片 / 演示文稿 / slide / 投影片" 等任何与 PPT 相关的需求（包括 0-1 生成整份、续写、加页、改页、删页、检查），**必须**按 `slide/entry.md` 的工作流执行：先跑状态脚本 → 必要时写 DESIGN → 用 `tdoc-slide` 服务的 `slide_*` 工具落地（API Schema 详见 `references/slideengine_references.md`）。**严禁**用 `doc_*`（docengine）或 `tencent-docs` 主服务的通用工具去改 PPT —— 它们不支持 slide 内部结构（shape_id / page_index / 母版等），返回的内容 / 行为均不正确。 - **文档编辑与新建**：使用`manage.query_file_info`或者`文档链接前缀`获取文档类型，根据文档类型优先使用对应的工具集，可参考**场景路由表** - **优先批量写入，避免多次重复调用**：当对同一文档存在**连续 3 次及以上**的数据写入（如向智能表格写多行记录、向 sheet 写多个单元格/区域、向文档插入多段内容等）时，**必须**使用对应工具的**批量写入接口**一次性提交（如 `smartsheet.add_records` / `smartsheet.update_records`、`sheet.set_range_value`、批量插入类工具），**严禁**用单条写入接口循环多次调用。批量调用可减少往返次数、降低限流与积分消耗、保证写入原子性。具体批量接口以各品类参考文档（场景路由表中对应文档）的 Schema 为准。 - **用户需要保存/上传Markdown格式内容**：直接填入 `create_smartcanvas_by_mdx` 的 `mdx` 参数，MDX 已向下兼容全部 Markdown 语法，无需转换，也无需切换 `content_format` - **用户有本地文件保存/沉淀/落盘**：一律使用 `mcp_tencent-docs_manage.pre_import` → shell `curl -X PUT` 上传 COS → `manage.async_import` → `manage.import_progress` 统一上传通路，保留原文件结构，不要用 `create_*` 工具重新生成内容；文件格式是否支持由后端判定，收到"不支持"错误时再降级到其他通路 - **保存/沉淀/落盘/转写类**：用户提出"整理/保存/归档/转写/沉淀/会议纪要"等把当前对话内容落到云端的诉求时，优先使用 `create_smartcanvas_by_mdx`（智能文档 mdx 格式，排版美观、组件丰富） - **URL 链接**：单独使用 `scrape_url` → `scrape_progress` 网页剪藏通路 - **创建文档支持 `parent_id`**：`create_*_by_markdown` 和 `create_flowchart_by_mermaid` 工具均支持 `parent_id` 参数，可将文档创建到指定目录；不填则在根目录创建。注意：`create_smartcanvas_by_mdx` 不支持 `parent_id` 参数 - **`node_id` 即 `file_id`**：空间节点的 `node_id` 同时也是文档的 `file_id` - **删除节点需谨慎**：`delete_space_node` 默认仅删除当前节点（`remove_type=current`），使用 `all` 时会递归删除所有子节点 - **Markdown 内容**：使用 UTF-8 格式，特殊字符无需转义