腾讯文档开放平台技能（自建独立版）

Overview

本技能通过腾讯文档开放平台的官方接口（MCP JSON-RPC 端点 + OAuth2 Bearer 鉴权）操作腾讯文档全系产品：在线文档、在线表格、幻灯片、思维导图、智能表、空间文件等。核心调用器 scripts/tencentdocs.py（纯 Python 标准库、跨平台、无第三方依赖）与宿主内置 tencent-docs 插件协议兼容，唯一区别是票据来源——本技能使用你自己的 OAuth2 access_token，不依赖宿主连接器。

适用场景：从零生成腾讯文档、读取 / 编辑指定文档、批量查最近文件、对表格写入数据、把日报 / 月报自动写入腾讯文档等。

何时使用（触发条件）

• 用户明确要求操作「腾讯文档 / Tencent Docs / docs.qq.com」下的文档、表格、幻灯片、思维导图、智能表。
• 关键词：腾讯文档、在线文档、在线表格、腾讯幻灯片、思维导图、智能表、doc.qq.com / docs.qq.com。
• 用户要做腾讯文档的「创建 / 生成 / 写入 / 读取 / 搜索 / 导入导出 / OCR」。
• 边界：若用户要求的是本地 Word / Excel / PPT（.docx / .xlsx / .pptx），应使用 Office 技能而不是本技能。

与宿主内置插件的区别

• 内置 tencent-docs 插件依赖宿主注入票据，当前环境连接器未连接时不可用。
• 本技能完全独立：token 来自你注册的第三方应用（OAuth2 授权码流程），脚本自带纯 Python 调用器，可离线分发、可定制。
• 两者 protocol / endpoint 完全一致，本技能是对内置插件的「去宿主化」替代。

前置准备（首次必做）

1. 到腾讯文档开放平台（https://docs.qq.com/open/）注册第三方应用，获取 client_id 与 client_secret，登记回调地址 redirect_uri（默认 https://docs.qq.com）。
2. 保存应用配置：
   python3 scripts/tdoc_auth.py setup --client_id <ID> --client_secret <SECRET>
3. 走 OAuth2 授权码流程拿 token（会打印授权页地址，用 QQ / 微信登录后把跳转 URL 或 code 粘回）：
   python3 scripts/tdoc_auth.py login
   token 缓存到 scripts/.tdoc_token.json。也可手动 python3 scripts/tdoc_auth.py set-token <TOKEN> 兜底。

> 替代方案：直接设置环境变量 TDOC_OAUTH_ACCESS_TOKEN=<token>，无需走 OAuth 流程。

命令速查

所有命令在技能根目录执行（脚本在 scripts/）。Python 用绝对路径调用以规避 bash 环境对 shim 的兼容问题。

service 取值

• tencent-docs → https://docs.qq.com/openapi/mcp（综合能力面：文件管理 / 文档 / 表格 / 幻灯片等）
• doc-mcp → https://docs.qq.com/api/v6/doc/mcp
• sheet-mcp → https://docs.qq.com/api/v6/sheet/mcp
• slide-mcp → https://docs.qq.com/api/v6/slide/mcp

标准工作流

A. 创建文档 / 表格 / 幻灯片（从零生成）

1. 先 tdoc_list tencent-docs 或 tdoc_schema tencent-docs manage.create_file 确认工具名与参数。
2. 调用示例：
   python3 scripts/tencentdocs.py tdoc_call tencent-docs manage.create_file '{"file_type":"doc","title":"我的文档"}'
   实际工具名与参数以 tdoc_schema 输出为准——严禁凭记忆拼参数。

B. 读取 / 编辑已有文档

1. 拿到文档 file_id（文档 URL 形如 https://docs.qq.com/doc/<file_id>）。
2. 用对应 service 调用：文档用 tencent-docs 或 doc-mcp，表格用 sheet-mcp，幻灯用 slide-mcp。
3. 调用前一律 tdoc_schema 查参数。

C. 搜索 / 批量操作

• 最近文件：tdoc_call tencent-docs manage.recent_online_file '{"num":20}'
• 具体工具名以 tdoc_list / tdoc_schema 实时返回为准。

关键纪律（防止踩坑）

• 调用 tdoc_call 前必须先跑 tdoc_schema 拿真实参数定义。腾讯文档工具参数随版本变动，严禁凭记忆 / 猜测拼 JSON。
• JSON 参数务必合法：用单引号包裹整段 JSON、内部双引号；或写成单行避免换行转义问题。
• 个人版用 TDOC_OAUTH_ACCESS_TOKEN；企业版（OneID）用 TDOC_ONEID_ACCESS_TOKEN，不要混用。
• 401 / 403 多为 token 失效或权限范围不足：跑 tdoc_auth.py status，过期则 refresh 或重新 login。
• 网络异常可加 --no-proxy 绕过系统代理；超时加 --timeout 300。

故障排查

参考

详细端点、OAuth2 鉴权流程、所有 service 工具清单与示例见 references/api_reference.md。