SKILL 更新

每天使用 SKILL 前进行一次更新检查，按照如下的步骤执行:

1. 查看当前版本version：读取本文件顶部 frontmatter 中的 version 字段；格式为 MAJOR.MINOR.PATCH
2. 查看最新版本latest：通过命令获取最新版本信息latest，输入参数 version 为上一步获取的当前版本

mcporter call "https://docs.qq.com/openapi/mcp" "check_skill_update" --args '{"version": "当前版本"}'

JSON 格式数据返回，返回参数示例： - latest: 最新版本号，格式为 MAJOR.MINOR.PATCH - release_note: 最新版本发布说明 - instruction: 更新指令

1. 更新版本：如果当前版本version低于最新版本latest，则遵循 instruction 指令进行更新，或提示用户更新

腾讯文档 MCP 使用指南

腾讯文档 MCP 提供了一套完整的在线文档操作工具，支持创建、查询、编辑多种类型的在线文档。

支持的文档类型

API详细参考文档

首先需要阅读文件 references/api_references.md 查看所有工具的完整API说明，该文件包含工具的完整调用示例、参数说明、返回值说明及API结构、枚举值说明

🎯 场景化文档指引

根据您的具体任务场景，选择相应的参考文档进行查阅：

• 场景：报告、笔记、文章、总结等文档相关场景，选择文档smartcanvas

- 创建文档：使用 createsmartcanvasbymdx 工具（MDX格式，支持分栏、高亮块、待办列表、表格等高级排版），阅读指引文件 references/mdxreferences.md 了解MDX组件规范 - 编辑已有文档：通过 smartcanvas.* 系列工具操作页面、文本、标题、待办事项等元素，阅读指引文件 references/smartcanvas_references.md

• 场景：结构化数据管理相关场景，选择智能表格smartsheet

- 阅读指引文件 references/smartsheet_references.md，支持通过smartsheet.* 系列工具来操作字段、记录、视图等元素

• 场景：计算、筛选、统计、Excel 操作相关场景，选择在线表格sheet

- 阅读指引文件 sheet/entry.md，支持通过sheet.* 系列工具来操作表格、范围数据、批量更新单元格等元素

• 场景: 生成论文、作业、公文、合同、通知等专业规范化的文件和样式美化后的文档相关操作，选择Word文档doc

- 阅读入口文件 doc/entry.md 了解整体能力和工作流程，支持通过doc.* 系列工具执行文档编写、美化等操作

• 场景: 对已有 Word 文档进行精细编辑操作（插入文本、替换文本、查找文本、插入段落、插入图片、插入表格、修改文本样式、插入任务等），选择 Word 文档编辑 tencent-docengine

- 阅读指引文件 references/docenginereferences.md，docengine 为独立 MCP 服务（tencent-docengine，API 地址：https://docs.qq.com/api/v6/doc/mcp），通过 mcporter call tencent-docengine <工具名> 调用，工具名如 find、inserttext、replace_text 等（不带前缀） - ⚠️ Token 说明：tencent-docengine 与 tencent-docs 使用同一个 Token，完成 tencent-docs 授权后即可直接使用，无需单独配置

• 场景: PPT文件演示文稿，需要逐页展示、投影演示相关场景，选择演示文稿slide

- 阅读指引文件 references/apireferences.md，支持通过 createslide 工具创建幻灯片（AI 自动生成内容，异步接口），需配合 slideprogress 工具轮询进度（每隔20秒轮询一次，最长等待20分钟） - ⚠️ 重要：幻灯片生成通常需要10~15分钟，推荐使用 spawn 子会话专职轮询：(1) 主会话提交任务后立即告诉用户"已开始"；(2) spawn 子会话每20秒检查一次，每次检查生成状态给主会话，超时自动清理并输出超时状态；(3) 主会话接收子会话状态并格式化输出给用户 - 待状态为 completed 时从响应中获取 fileurl 并告知用户

• 场景: 层次化知识整理（知识图谱、大纲），选择思维导图mind

- 阅读指引文件 references/api_references.md，支持通过mind 相关工具来操作思维导图、思维导图页、思维导图元素等元素

• 场景: 流程/架构展示（流程图、时序图），选择流程图flowchart

- 阅读指引文件 references/api_references.md，支持通过flowchart 相关工具来操作流程图、流程图页、流程图元素等元素

• 场景: 白板演示场景，选择白板board

- 阅读指引文件 references/apireferences.md，支持通过createspace_node 工具来创建白板

• 场景: 数据收集填写等场景，选择收集表form

- 阅读指引文件 references/apireferences.md，支持通过createspace_node 工具来创建收集表

• 其他通用场景，选择文档smartcanvas

⚙️ 快速配置

首次安装使用时，需要先完成本地安装和注册，详见 references/auth.md。

🔧 调用方式

获取完整的工具列表

1. 使用 mcporter list tencent-docs 获取工具列表和参数 Schema
2. 阅读 references/ 目录下的参考文档查看调用示例、返回值结构和注意事项

⚠️ 参考文档中的参数说明应与 MCP 工具 Schema 保持一致。
如有冲突，以 mcporter list tencent-docs 返回的 Schema 为准。

工具列表示例

调用示例

获取正文内容 get_content

mcporter call "tencent-docs" "get_content" --args '{"file_id":"bLkQdUHejxNj"}'

创建智能表格

mcporter call "tencent-docs" "create_space_node" --args '{"title": "测试智能表t1","node_type": "wiki_tdoc","wiki_tdoc_node": { "title": "测试智能表t1-1","doc_type": "smartsheet"}}'

查询智能表中的工作表

mcporter call "tencent-docs" "smartsheet.list_tables" --args '{"file_id":"bDAzsLDGgmqw"}'

智能表中添加字段

mcporter call "tencent-docs" "smartsheet.add_fields" --args '{"file_id":"bEtvncBEcLos","sheet_id": "t00i2h", "fields": [{"field_title":"测试filed1", "field_type": 1}]}'

创建智能文档 createsmartcanvasby_mdx

mcporter call "tencent-docs" "create_smartcanvas_by_mdx" --args '{"title": "项目周报", "mdx": "---\ntitle: 项目周报\nicon: 📋\n---\n\n# 本周工作总结\n\n<Callout icon=\"✅\" blockColor=\"light_green\" borderColor=\"green\">\n    本周所有里程碑任务均已按时完成。\n</Callout>\n\n<ColumnList>\n    <Column width=\"50%\">\n        ## 已完成\n\n        <Todo checked>\n            需求评审\n        </Todo>\n        <Todo checked>\n            接口开发\n        </Todo>\n    </Column>\n    <Column width=\"50%\">\n        ## 待完成\n\n        <Todo>\n            单元测试\n        </Todo>\n        <Todo>\n            部署上线\n        </Todo>\n    </Column>\n</ColumnList>"}'

创建表格 createexcelby_markdown

mcporter call "tencent-docs" "create_excel_by_markdown" --args '{"title": "我的日程表", "markdown": "| 日期 | 时间 | 事项 | 地点 | 状态 | 备注 |\n|------|------|------|------|------|------|\n| 2024-03-11 | 09:00-10:00 | 团队会议 | 会议室A | 待办 | 准备项目汇报 |\n| 2024-03-11 | - | 项目文档编写 | 远程 | 进行中 | 完成需求文档 |\n| 2024-03-11 | 14:00-15:30 | 客户沟通 | 线上会议 | 已安排 | 准备演示材料 |\n| 2024-03-12 | 10:00-12:00 | 产品评审 | 会议室B | 待办 | 检查产品原型 |\n| 2024-03-12 | 15:00-16:00 | 培训学习 | 培训室 | 已安排 | AI工具使用 |\n| 2024-03-13 | 全天 | 项目开发 | 办公室 | 进行中 | 功能模块开发 |\n| 2024-03-14 | 09:30-11:00 | 周会总结 | 会议室A | 待办 | 整理本周工作 |\n| 2024-03-15 | 13:00-17:00 | 项目演示 | 客户现场 | 已安排 | 最终演示准备 |"}'

常见工作流

首先阅读 references目录下的所有参考文件，理解每个工具的功能和参数

创建通用文档（推荐方式）

📖 参考文档： references/mdxreferences.md - createsmartcanvasbymdx

1. 阅读 references/mdx_references.md 了解MDX组件规范
2. 按规范生成包含 Frontmatter 和 MDX 组件的内容
3. 对照 mdx_references 逐条自校验，确保格式合规
4. 调用 createsmartcanvasby_mdx 创建文档
5. 从返回结果中获取 file_id 和 url

编辑已有文档（智能文档 smartcanvas）

📖 参考文档： references/smartcanvas_references.md - 典型工作流示例

1. 调用 smartcanvas.get_top_level_pages 获取文档页面结构
2. 按需调用 smartcanvas.* 工具进行增删改查：
   - 追加内容：smartcanvas.append_insert_smartcanvas_by_markdown（Markdown 方式）
   - 新增元素：smartcanvas.create_smartcanvas_element
   - 查询元素：smartcanvas.get_element_info / smartcanvas.get_page_info
   - 修改元素：smartcanvas.update_element
   - 删除元素：smartcanvas.delete_element

编辑已有 Word 文档（tencent-docengine 独立服务）

📖 参考文档： references/docengine_references.md

⚠️ docengine 是独立的 MCP 服务（服务名：tencent-docengine，API 地址：https://docs.qq.com/api/v6/doc/mcp），工具名不带前缀，通过 mcporter call tencent-docengine <工具名> 调用。

🔑 Token 复用：tencent-docengine 与 tencent-docs 共用同一个 Token，完成 tencent-docs 授权（references/auth.md）后自动配置，无需单独鉴权。

查找并替换文本

1. 调用 tencent-docengine 的 find 工具查找目标文本，获取所有匹配位置和上下文
2. 将匹配结果展示给用户，让用户选择要替换的位置
3. 调用 tencent-docengine 的 replace_text 传入对应的 range 进行精确替换
   （如需全部替换，可直接调用 find_and_replace）

插入内容到文档

1. 调用 tencent-docengine 的 get_outline 获取文档大纲结构，定位目标标题的可操作位置
   或调用 find 定位插入位置（获取目标文本的 index）
2. 按需调用 tencent-docengine 的工具插入内容：
   - 插入文本：insert_text
   - 插入段落：insert_paragraph（支持标题级别、有序/无序列表）
   - 插入图片：insert_image
   - 插入表格：insert_table
   - 插入分页符：insert_page_break
   - 插入任务：insert_task
   - 插入批注：insert_comment
   - 替换图片：replace_image
   - 获取末尾可操作位置：get_last_operable_pos（追加内容到文档末尾时先获取位置）
   - 获取文档大纲：get_outline（了解文档结构和各标题、正文的可操作位置）

修改文本样式

1. 调用 tencent-docengine 的 find 查找目标文本，获取 range（begin/end）
2. 调用 tencent-docengine 的 update_text_property 传入 range 和属性（加粗、斜体、颜色等）

组织文档到指定目录

📖 参考文档： references/apireferences.md - queryspacenode, createspace_node

1. 调用 queryspacenode 查找目标文件夹
2. 调用 createspacenode 在目标位置创建文档节点（doc_type 优先选择 smartcanvas）

查找并读取文档

📖 参考文档： references/apireferences.md - queryspacenode, getcontent

1. 调用 queryspacenode 遍历节点树查找文档
2. 从结果中获取 nodeid（即 fileid）
3. 调用 get_content 获取文档内容

智能表格操作工作流

📖 参考文档： references/smartsheet_references.md - 典型工作流示例

从零搭建任务管理表

1. 获取工作表列表 → smartsheet.list_tables（获取 sheet_id）
2. 添加字段（列）→ smartsheet.add_fields（任务名称、优先级、截止日期等）
3. 批量写入数据 → smartsheet.add_records
4. （可选）创建看板视图 → smartsheet.add_view（view_type=2）
5. （可选）删除字段（列） → smartsheet.delete_fields

查询并更新数据

1. 获取工作表 → smartsheet.list_tables
2. 查询记录   → smartsheet.list_records（获取 record_id）
3. 更新记录   → smartsheet.update_records（传入 record_id 和新字段值）

📖 更多智能表格工作流示例请参考：references/smartsheet_references.md - 典型工作流示例

在指定目录创建文档

📖 参考文档： references/manage_references.md - 典型工作流示例

1. 调用 manage.folder_list 获取文件夹目录
2. 按需调用 manage.* 工具进行文档增删改查、重命名、移动文档：
   - 重命名：manage.rename_file_title
   - 删除文档：manage.delete_file
   - 移动文档：manage.move_file
   - 生成副本：manage.copy_file
   - 设置权限：manage.set_privilege（仅支持所有人可读和所有人可编辑）

搜索文档

1. 搜索文档 → manage.search_file（传入用户指定的关键词）

📖 更多文件管理工作流示例请参考：references/manage_references.md - 典型工作流示例

注意事项

• 管理空间：使用 queryspacelist 获取空间列表，使用 createspace 创建新空间，使用 queryspace_node 浏览空间内的节点树
• 默认使用 smartcanvas：除非用户明确指定其他格式，否则新增文档时优先使用 createsmartcanvasby_markdown；编辑已有文档时使用 smartcanvas.* 系列工具
• 创建文档时支持 parentid：所有 create*bymarkdown 和 createflowchartbymermaid 工具均支持 parentid 参数，可将文档直接创建到指定目录；不填则在根目录创建
• Word 文档编辑：docengine 是独立 MCP 服务（服务名：tencent-docengine，API：https://docs.qq.com/api/v6/doc/mcp），与 tencent-docs 共用同一个 Token（完成 tencent-docs 授权后自动配置，无需单独鉴权）。工具名不带前缀（如 find、inserttext、replacetext、insertcomment、replaceimage、getlastoperablepos、getoutline 等），仅支持 Word 文档类型，操作前需确保拥有文档写入权限。⚠️ 推荐优先使用 fileurl（文档链接）而非 fileid 来标识文档，用户通常直接提供文档链接，使用更便捷。编辑前推荐先调用 getoutline 获取文档大纲结构，了解各标题和正文的可操作位置；当用户要求「在文档开头插入」时，需向用户确认是在「文档标题之前」（使用 HEADINGLEVELTITLE 的 titlestart）还是「正文开头/标题之后」（使用 HEADINGLEVELTITLE 的 contentstart）插入，未明确时应主动询问；替换文本推荐流程：先调用 find 查找定位，让用户确认后再用 replacetext 精确替换；如需全部替换可直接使用 findandreplace。向文档末尾追加内容时，先调用 getlastoperablepos 获取末尾位置。详见 references/docenginereferences.md
• 默认使用 smartcanvas：除非用户明确指定其他格式，否则新增文档时优先使用 createsmartcanvasby_mdx；编辑已有文档时使用 smartcanvas.* 系列工具; 编辑已有 Word 文档时使用 tencent-docengine 独立服务的工具
• 创建文档时支持 parentid：所有 create*bymarkdown、createsmartcanvasbymdx 和 createflowchartbymermaid 工具均支持 parent_id 参数，可将文档直接创建到指定目录；不填则在根目录创建
• 删除节点：deletespacenode 默认仅删除当前节点（remove_type=current），使用 all 时会递归删除所有子节点，需谨慎
• Markdown 内容使用 UTF-8 格式，特殊字符无需转义
• 创建幻灯片：使用 createslide 工具，传入 description（用户要求）和可选的 referencecontext（参考资料），AI 自动生成内容；该接口为异步接口，返回 sessionid 后推荐使用 spawn 子会话专职轮询：(1) 主会话提交任务后立即告诉用户"已开始"；(2) spawn 子会话每20秒检查一次，每次检查生成状态给主会话，超时自动清理并输出超时状态；(3) 主会话接收子会话状态并格式化输出（进行中/完成/失败/超时），状态为 completed 时从响应中获取 fileurl
• 分页查询每页返回 20-40 条记录，使用 has_next 判断是否有更多
• nodeid 同时也是文档的 fileid
• createflowchartby_mermaid 的 mermaid 内容必须全部使用英文
• 文档元素操作：Text、Heading、Task、Image 必须挂载在 Page 下，parentid 必须为 Page 类型元素 ID；操作前先调用 smartcanvas.gettoplevelpages 获取页面结构
• 文档分页查询：smartcanvas.getpageinfo 使用 cursor 分页，is_over=true 表示已获取全部内容
• 文档删除注意：删除 Page 元素时，其下所有子元素也会被一并删除
• 智能表格操作：所有 smartsheet.* 工具都需要 fileid 和 sheetid，操作前先调用 smartsheet.listtables 获取 sheetid
• 字段类型不可更新：updatefields 时 fieldtype 不能修改，但必须传入原值
• 记录字段值格式：不同字段类型的值格式不同，详见 references/smartsheet_references.md - 字段值格式参考

问题定位指南

常见错误码及解决方案

问题排查步骤

1. 检查错误信息：查看错误信息，确定错误类型，例如授权、网络问题、业务参数问题
2. 检查请求参数：确认请求参数是否正确，例如file_id、content 等
3. 阅读参考文档：references/ 目录下的参考文档中包含所有工具的参数说明，可帮助快速定位问题
4. 获取工具列表：使用 mcporter list tencent-docs 获取所有工具列表，确认工具是否可用，检查有的参数是否正确