AI工具►技术深度

腾讯文档 MCP Skill 深度技术分析

腾讯文档 MCP Skill 深度技术分析

腾讯文档（docs.qq.com）的 MCP Skill 包，提供完整的在线文档操作能力，支持 AI Agent 通过 MCP 协议创建、编辑、管理各类在线文档。

本文基于项目代码进行深度分析，剖析其架构设计、核心能力、优缺点及改进建议。

支持的文档类型

类型 doc_type 说明
智能文档 smartcanvas MDX 格式，排版美观，支持丰富组件
Excel sheet 数据表格，支持单元格操作、筛选、冻结等
PPT slide 幻灯片演示文稿
思维导图 mind 层次化知识整理
流程图 flowchart 流程/架构展示
Word doc 传统文档格式
收集表 form 表单收集
智能表格 smartsheet 高级结构化表格，支持多视图

快速开始

1. 安装依赖

需要 Node.js 环境。

1
bash ./setup.sh

脚本会自动安装 mcporter 并引导完成腾讯文档 OAuth 授权。

2. 授权流程

1
2
3
4
5
# 第一步：检查授权状态
bash ./setup.sh tdoc_check_and_start_auth

# 第二步：在浏览器中完成授权后
bash ./setup.sh tdoc_fetch_token

也可直接传入 Token 跳过 OAuth：

1
bash ./setup.sh tdoc_set_token <your-token>

Token 获取地址：https://docs.qq.com/scenario/open-claw.html

3. 使用

1
2
3
4
5
# 查看可用工具
mcporter list tencent-docs

# 调用工具
mcporter call "tencent-docs" "<工具名>" --args '<JSON参数>'

项目结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
├── SKILL.md                           # 入口文件，全局导航与核心规则
├── setup.sh                           # 安装与授权脚本
├── import_file.sh                     # 文件导入辅助脚本
├── ocr.js                            # 本地图片 OCR 辅助脚本
├── references/                        # 参考文档
│   ├── auth.md                       # 鉴权与授权流程
│   ├── workflows.md                  # 公共接口与常见工作流
│   ├── smartsheet_references.md      # 智能表格操作
│   ├── slide_references.md           # 幻灯片生成
│   ├── diagram_references.md         # 思维导图 + 流程图
│   ├── docengine_references.md       # Word 文档精细编辑
│   ├── space_references.md           # 知识库空间管理
│   ├── manage_references.md          # 文件管理
│   ├── ocr_references.md             # OCR 图片识别
│   └── unsupported_feature_reporting.md
├── smartcanvas/                      # 智能文档模块
│   ├── entry.md                     # 智能文档入口
│   └── mdx_references.md           # MDX 格式规范
├── doc/                              # Word 文档模块
│   ├── entry.md                     # Word 品类入口
│   └── doc_format/                  # Word 格式定义与模板
└── sheet/                           # Excel 文档模块
    ├── entry.md                     # Sheet 品类入口
    └── api/                        # Sheet API 定义

核心功能

  • 创建文档 — 支持智能文档（MDX）、Excel、PPT、思维导图、流程图、Word 等多种格式
  • 编辑文档 — 智能文档支持插入、删除、修改、分栏布局等操作
  • 表格操作 — 单元格读写、样式设置、合并单元格、筛选冻结、子表管理
  • 文件管理 — 搜索、重命名、移动、删除、复制、导入导出、权限设置
  • 知识库空间 — 创建空间、管理节点与文件夹结构
  • 网页剪藏 — 抓取网页内容自动保存为智能文档
  • OCR 识别 — 图片提取文字、图片转 Word/Excel

版本

当前版本：1.0.32

支持自动更新检查，详见 SKILL.md 中的”SKILL 更新”章节。

相关链接

深度代码分析

基于项目代码分析，这个腾讯文档 MCP Skill 包有以下主要优点：

一、文档类型覆盖全面

支持 8 种文档类型：智能文档（smartcanvas）、Excel、PPT、思维导图、流程图、Word、收集表、智能表格。基本涵盖了在线办公的所有场景。

二、智能文档（SmartCanvas）能力强

  • MDX 格式向下兼容全部 Markdown 语法，不需要额外学习新语法即可上手
  • 支持分栏布局、高亮块、待办列表、表格等高级排版组件，比纯 Markdown 表达力更强
  • 内置 38 个模板（工作总结、述职报告、商业计划书、竞品分析等），开箱即用

三、编辑能力精细

  • 智能文档支持 find → edit 工作流：先搜索定位内容块，再精准插入/删除/修改
  • Excel 支持单元格级操作：设置值、样式、合并、筛选、冻结、行高列宽、子表管理等
  • 不是简单的”创建就完事”，而是支持持续编辑和增量更新

四、工具设计成熟

  • 统一鉴权 — 一个 Token 通行所有文档类型，OAuth 流程自动化
  • 场景路由表 — 根据任务类型快速找到对应工具和文档，降低使用门槛
  • 异步任务处理 — PPT 生成、网页剪藏等耗时操作支持异步轮询，不阻塞用户交互
  • 图片处理统一 — 所有图片统一通过 upload_image 上传获取 image_id，避免外链失效
  • 不支持能力自动上报 — 遇到不支持的功能会静默上报，推动产品迭代

五、文件管理完善

支持搜索、重命名、移动、删除、复制、导入导出、权限设置，以及知识库空间管理，不只是”能创建”，还能做完整的文档生命周期管理。

六、辅助工具贴心

  • import_file.sh — 本地文件上传到云端，保留原文件结构
  • ocr.js — 本地图片 OCR 识别，支持图片转 Word/Excel
  • scrape_url — 网页剪藏自动保存为智能文档

不足分析

总体来说，它的定位不只是一个简单的文档创建 API 封装，而是一个完整的在线文档操作平台，从创建、编辑、管理到导入导出形成了闭环，且针对 AI Agent 的使用场景做了大量适配（模板匹配、场景路由、异步轮询等）。

但基于项目代码的深入分析，这个包存在以下不足：

1. 强依赖腾讯文档生态

  • 必须使用 QQ 或微信扫码授权，绑定腾讯账号体系
  • Token 有过期机制，需要定期重新授权
  • 部分功能需要 VIP 权限（400007 错误码）和积分（400008 错误码），有付费门槛
  • 文档存储在腾讯云端，数据自主性受限

2. 工具碎片化严重

SKILL.md 中列出了 smartcanvas.*、sheet.*、doc.*、smartsheet.*、ocr.*、manage.* 等多套工具前缀，但缺乏统一的抽象层：

  • 同样是”读取文档内容”，智能文档用 smartcanvas.read，Excel 用 sheet.get_cell_data，通用读取又有 get_content，AI Agent 需要记住多套接口
  • 不同文档类型的创建工具命名不统一：create_smartcanvas_by_mdx、create_slide、create_flowchart_by_mermaid，参数约定各不相同

3. 智能文档编辑有严格约束

  • UPDATE / DELETE 操作必须先通过 find 或 read 获取 Block ID，不能凭记忆操作，每次编辑至少两次调用
  • 带 readonly 属性的组件（如 Table）完全不可编辑，只能绕开操作
  • ColumnList 删除列时有特殊约束（不能只剩 1 列），边界处理逻辑复杂
  • 不支持对单个 TableCell 直接 UPDATE，必须替换整个 Table，操作粒度粗

4. 图片处理链路长

所有图片必须先调用 upload_image 上传获取 image_id，禁止直接使用 URL：

  • 本地图片需要 node ocr.js 转 base64 再上传，链路长
  • 图片过大上传失败时需要本地压缩后重试，没有自动降级机制
  • 增加了网络开销和调用次数

5. 异步任务体验差

PPT 生成（create_slide）、网页剪藏（scrape_url）等是异步操作：

  • 需要手动轮询进度（scrape_progress）
  • 官方建议用”spawn 子会话专职轮询”，实现复杂度高
  • 没有回调/Webhook 机制，只能轮询

6. 本地部署能力缺失

  • setup.sh 依赖 curl、openssl、jq 等工具，在 Windows 上兼容性存疑
  • 所有操作通过 HTTP 调用腾讯文档 API，没有离线/本地模式
  • import_file.sh 依赖 COS（腾讯云对象存储），上传链路绑定腾讯云基础设施

7. 错误处理粗糙

  • 错误码体系不够完整，大量场景归到 ERROR:unknown（见 setup.sh:310）
  • setup.sh 中 tdoc_fetch_token 的 token 提取有 DEBUG 输出（第 262 行 echo "DEBUG:token=$token"），属于调试遗留
  • 没有重试机制，网络抖动直接返回失败

8. 缺少批量操作能力

  • 没有批量创建文档的接口
  • Excel 操作逐单元格调用（set_cell_value / set_range_value），大数据量场景效率低
  • 文件管理（重命名、移动、删除）也是单个操作，不支持批量

9. 版本更新机制原始

更新检查需要手动读取 frontmatter 中的 version 字段，再调用 check_skill_update 对比，没有自动更新能力，需要用户手动执行更新指令。

改进建议

总结来看，主要问题集中在生态锁定、接口碎片化、编辑约束多、异步处理复杂这几个方面。作为 MCP Skill 封装，它对腾讯文档 API 的覆盖面不错，但抽象层设计和开发者体验还有较大提升空间。

基于前面分析的不足，按优先级给出改进建议：

一、统一抽象层（影响最大）

当前最大的问题是接口碎片化。建议加一个统一的文档操作层：

统一读取 — 做一个 docs.read(file_id) 入口，内部根据文档类型自动路由到 smartcanvas.read / sheet.get_cell_data / get_content

统一编辑 — 做一个 docs.edit(file_id, action, target, content) 入口，对智能文档走 Block 编辑，对 Excel 走单元格操作，对其他类型走内容替换

统一创建 — docs.create(type, title, content) 一个入口，替代当前 create_smartcanvas_by_mdx / create_slide / create_flowchart_by_mermaid 等散落的工具

这样 AI Agent 只需记住 3 个核心 API，降低使用门槛。

二、简化图片链路

当前：本地图片 → node ocr.js → base64 → upload_image → image_id → 写入文档

改进方案：

  • 在 smartcanvas.edit / create_smartcanvas_by_mdx 内部自动处理图片上传，用户只需传 URL 或本地路径
  • 支持传入公网 URL 时自动下载上传，省去手动调用 upload_image 的步骤
  • 大图自动压缩后再上传，去掉”上传失败需手动压缩”的人工介入

三、优化异步任务体验

当前：spawn 子会话轮询，实现复杂

改进方案：

1
2
3
4
5
6
7
8
# 方案 A：同步等待（简单场景）
docs.wait(task_id, timeout=60)

# 方案 B：回调通知（复杂场景）
docs.create_slide(..., callback_url="...")

# 方案 C：统一任务状态查询
docs.task_status(task_id)  # 替代散落的 scrape_progress 等

至少提供一个 docs.wait(task_id) 的阻塞等待工具，让简单场景不需要手动轮询。

四、增加批量操作能力

1
2
3
4
5
6
7
8
# 批量设置单元格（当前已有 set_range_value，但可扩展）
sheet.batch_update(file_id, [
  {"range": "A1:C3", "values": [[...]]},
  {"range": "D1", "value": "标题", "style": {"bold": true}}
])

# 批量文件操作
manage.batch(file_id_list, action="move", target_folder="...")

五、改进智能文档编辑体验

当前问题：每次编辑至少 2 次调用（find + edit），readonly 组件不可操作

改进方案：

内联定位 — edit 工具支持文本匹配定位，不需要先 find：

1
2
3
4
5
6
{
  "file_id": "xxx",
  "action": "UPDATE",
  "locate": {"text": "项目背景"},
  "content": "新的项目背景内容"
}

这样省掉一次 find 调用，内部实现为 find + edit 的组合即可。

readonly 组件降级 — 遇到 readonly Table 时，自动在 Table 前后寻找锚点插入，而不是返回错误让 AI Agent 自己处理。

六、改进错误处理

1
2
3
4
5
6
7
8
9
10
11
12
# 当前：粗糙的错误
ERROR:unknown(ret=xxx, response=yyy)

# 改进：结构化错误 + 重试建议
{
  "error": {
    "code": "NETWORK_TIMEOUT",
    "message": "请求超时",
    "retryable": true,
    "retry_after": 3
  }
}
  • 为可重试错误（网络超时、限流）自动加 retryable: true 标记
  • SDK 层内置重试逻辑（3 次，指数退避）
  • 清理 setup.sh 中的 DEBUG 输出

七、降低生态锁定

  • 支持本地文件操作模式（至少支持导出为本地文件）
  • 图片上传支持自定义存储后端，不强制绑定腾讯 COS
  • 提供文档内容的纯文本/Markdown 导出，方便迁移到其他平台

优先级建议

优先级 改进项 投入 收益
P0 统一抽象层 中 大幅降低使用门槛
P0 简化图片链路 小 减少一半的调用次数
P1 内联定位编辑 小 编辑操作减 1 次调用
P1 改进错误处理 小 提升稳定性
P2 异步任务优化 中 提升复杂场景体验
P2 批量操作 中 提升数据量大时的效率
P3 降低生态锁定 大 提升可迁移性

其中统一抽象层和简化图片链路投入产出比最高，建议优先做。

总结

腾讯文档 MCP Skill 是一个覆盖全面但抽象不足的 MCP 实现：

✅ 优点：文档类型全覆盖、智能文档能力强、编辑能力精细、辅助工具完善
⚠️ 不足：接口碎片化、编辑约束多、异步体验差、生态锁定强
🔧 改进方向：统一抽象层、简化图片链路、优化异步任务、增加批量操作

对于想要快速上手腾讯文档自动化的开发者，这是一个功能完整但需要一定学习成本的工具包。改进统一抽象层后，体验会提升一个档次。