feat: 初始化黄小瓜AI助手记忆仓库

- 核心配置: IDENTITY, USER, SOUL, AGENTS, TOOLS, HEARTBEAT, MEMORY - memory/: 每日总结和临时记录 - skills/: 所有已安装技能 - notes/: 语音配置笔记
2026-04-04 02:42:48 +08:00
parent 2d24fe9b50
commit 691b8cdd0c
115 changed files with 18198 additions and 0 deletions
--- a/skills/tencent-docs/references/api_references.md
+++ b/skills/tencent-docs/references/api_references.md
--- a/skills/tencent-docs/references/auth.md
+++ b/skills/tencent-docs/references/auth.md
@@ -0,0 +1,78 @@
+# 腾讯文档鉴权检查
+
+腾讯文档授权流程，**必须按以下步骤执行**：
+
+> 💡 **说明**：授权成功后，Token 会同时配置到 `tencent-docs` 、 `tencent-docengine`、`tencent-sheetengine` 三个服务，无需为 tencent-docengine和tencent-sheetengine 单独授权。
+
+## 第一步：检查状态（立即返回）
+
+```bash
+bash ./setup.sh tdoc_check_and_start_auth
+```
+
+| 输出                  | 处理方式                                                     |
+| --------------------- | ------------------------------------------------------------ |
+| `READY`               | ✅ 直接执行用户任务，**无需第二步**                           |
+| `AUTH_REQUIRED:<url>` | **立即**向用户展示授权链接（见下方模板），**然后执行第二步** |
+| `ERROR:*`             | 告知用户对应错误                                             |
+
+## 第二步：等待授权完成（仅 AUTH_REQUIRED 时执行）
+
+**展示授权链接后**，立即执行：
+
+```bash
+bash ./setup.sh tdoc_wait_auth
+```
+
+| 输出                  | 处理方式                                     |
+| --------------------- | -------------------------------------------- |
+| `TOKEN_READY:*`       | ✅ 授权成功，继续执行用户任务                 |
+| `AUTH_TIMEOUT`        | 告知用户：「授权超时，请重新发起请求。」     |
+| `ERROR:expired`       | 告知用户：「授权码已过期，请重新发起请求。」 |
+| `ERROR:token_invalid` | 告知用户：「Token 已失效，请重新发起请求。」 |
+| `ERROR:*`             | 告知用户对应错误，请重新发起请求             |
+
+## 第三步：人工兜底（前两步都失败的情况）
+
+🔑 **检查 Token 配置**：可访问 [https://docs.qq.com/scenario/open-claw.html](https://docs.qq.com/scenario/open-claw.html) 获取 Token，再执行以下命令来设置mcporter:
+```bash
+# 使用传入的 Token 写入 mcporter 配置（tencent-docs）
+mcporter config add tencent-docs "https://docs.qq.com/openapi/mcp" \
+    --header "Authorization=$Token" \
+    --transport http \
+    --scope home
+
+# 同时配置 tencent-docengine（复用相同 Token）
+mcporter config add tencent-docengine "https://docs.qq.com/api/v6/doc/mcp" \
+    --header "Authorization=$Token" \
+    --transport http \
+    --scope home
+
+# 同时配置 tencent-sheetengine（复用相同 Token）
+mcporter config add tencent-sheetengine "https://docs.qq.com/api/v6/sheet/mcp" \
+    --header "Authorization=$Token" \
+    --transport http \
+    --scope home
+```
+
+## 授权链接展示模板
+
+当第一步输出 `AUTH_REQUIRED:<url>` 时，**立即**向用户展示：
+
+> 🔑 **需要先完成腾讯文档授权**
+>
+> 请确保在**浏览器**中打开以下链接完成授权：**[点击授权腾讯文档]({url})**
+>
+> ⚠️ 请使用 **QQ 或微信** 扫码 / 登录授权
+>
+> _(授权后将自动继续，无需回复)_
+
+## 错误说明
+
+| 错误                       | 含义                               |
+| -------------------------- | ---------------------------------- |
+| `ERROR:mcporter_not_found` | 缺少依赖，请先安装 Node.js         |
+| `ERROR:expired`            | 授权码已过期，重新发起请求         |
+| `ERROR:token_invalid`      | Token 鉴权失败（400006），重新授权 |
+| `ERROR:save_token_failed`  | Token 写入配置失败                 |
+| `AUTH_TIMEOUT`             | 用户未在时限内完成授权             |
--- a/skills/tencent-docs/references/diagram_references.md
+++ b/skills/tencent-docs/references/diagram_references.md
@@ -0,0 +1,83 @@
+# 图形化文档（思维导图 / 流程图）参考文档
+
+本文件包含腾讯文档 MCP 中思维导图和流程图的创建工具说明。
+
+---
+
+## 工具列表
+
+| 工具名称 | 功能说明 |
+|---------|---------|
+| create_mind_by_markdown | 通过 Markdown 创建思维导图 |
+| create_flowchart_by_mermaid | 通过 Mermaid 语法创建流程图 |
+
+---
+
+## 工具详细说明
+
+### 1. create_mind_by_markdown
+
+#### 功能说明
+通过 Markdown 创建思维导图，使用标题层级和列表嵌套表示结构。
+
+#### 调用示例
+```json
+{
+  "title": "产品功能规划",
+  "markdown": "# 产品功能规划\n\n## 核心功能\n\n- 文档管理\n    - 创建文档\n    - 编辑文档\n    - 版本控制\n\n## 协作功能\n\n- 实时协作\n- 评论系统\n- 权限管理",
+  "parent_id": "folder_1234567890"
+}
+```
+
+#### 参数说明
+- `title` (string, 必填): 思维导图标题
+- `markdown` (string, 必填): 层次化的 Markdown 文本
+- `parent_id` (string, 可选): 父节点ID，为空时在空间根目录创建，不为空时在指定节点下创建
+
+#### 返回值说明
+```json
+{
+  "file_id": "mind_1234567890",
+  "url": "https://docs.qq.com/mind/DV2h5cWJ0R1lQb0lH",
+  "error": "",
+  "trace_id": "trace_1234567890"
+}
+```
+
+---
+
+### 2. create_flowchart_by_mermaid
+
+#### 功能说明
+通过 Mermaid 语法创建流程图。
+
+#### 调用示例
+```json
+{
+  "title": "用户登录流程",
+  "mermaid": "graph TD\n    A[User Access] --> B{Logged in?}\n    B -->|Yes| C[Go to Home]\n    B -->|No| D[Go to Login Page]\n    D --> E[Enter Username and Password]\n    E --> F{Auth Success?}\n    F -->|Yes| C\n    F -->|No| G[Show Error Message]\n    G --> E",
+  "parent_id": "folder_1234567890"
+}
+```
+
+#### 参数说明
+- `title` (string, 必填): 流程图标题
+- `mermaid` (string, 必填): 不包含中文的 Mermaid 语法文本
+- `parent_id` (string, 可选): 父节点ID，为空时在空间根目录创建，不为空时在指定节点下创建
+
+#### 返回值说明
+```json
+{
+  "file_id": "flow_1234567890",
+  "url": "https://docs.qq.com/flow/DV2h5cWJ0R1lQb0lH",
+  "error": "",
+  "trace_id": "trace_1234567890"
+}
+```
+
+---
+
+## 注意事项
+
+- `create_flowchart_by_mermaid` 的 mermaid 内容**必须全部使用英文**，不支持中文字符
+- 两个工具均支持 `parent_id` 参数，可将文档创建到指定目录；不填则在根目录创建
--- a/skills/tencent-docs/references/docengine_references.md
+++ b/skills/tencent-docs/references/docengine_references.md
@@ -0,0 +1,750 @@
+# DOC 编辑引擎 API 参考
+
+本文件包含腾讯文档 DOC 编辑引擎（docengine）的所有工具 API 说明。这些工具专用于 Word 文档的编辑操作，包括文本插入、替换、查找、段落设置、文本属性修改、任务插入、图片插入、分页符和表格插入等。
+
+> ⚠️ **注意**：本文档中的工具仅适用于 **Word 文档（doc_type: word）** 类型，不适用于智能文档（smartcanvas）等其他类型。
+
+---
+
+## 服务信息
+
+| 项目 | 说明 |
+|------|------|
+| 服务名 | `tencent-docengine` |
+| API 地址 | `https://docs.qq.com/api/v6/doc/mcp` |
+| 调用方式 | `mcporter call tencent-docengine <工具名>` |
+| Token | 与 tencent-docs **共用同一个 Token**，完成 tencent-docs 授权（`auth.md`）后自动配置，无需单独鉴权 |
+| 文档类型 | 仅支持 Word 文档类型 |
+
+> ⚠️ **推荐优先使用 `file_url`（文档链接）而非 `file_id` 来标识文档**，用户通常直接提供文档链接，使用更便捷。
+>
+> 编辑前推荐先调用 `get_outline` 获取文档大纲结构，了解各标题和正文的可操作位置。
+>
+> 当用户要求「在文档开头插入」时，需向用户确认是在「文档标题之前」（使用 `HEADING_LEVEL_TITLE` 的 `title_start`）还是「正文开头/标题之后」（使用 `HEADING_LEVEL_TITLE` 的 `content_start`）插入，未明确时应主动询问。
+
+---
+
+## 通用说明
+
+### 文档标识
+
+所有 docengine 工具都支持两种文档标识方式（二选一）：
+- `file_url` (string): **⭐ 推荐** 腾讯文档的文档链接（如 `https://docs.qq.com/doc/xxxxxxxx`），直接使用用户提供的文档链接即可
+- `file_id` (string): 文档唯一标识符
+
+> 💡 **推荐优先使用 `file_url`**：用户通常会直接提供文档链接，使用 `file_url` 无需额外解析 `file_id`，更加便捷。
+
+### 响应结构
+
+编辑类 API 返回：
+- `base_version` (int64): 文档的基准版本号
+- `new_version` (int64): 编辑后的文档新版本号
+- `err_msg` (string): 错误信息（成功时为空）
+- `trace_id` (string): 调用链追踪 ID
+
+查询类 API（如 find）返回：
+- `read_result.version` (int64): 文档当前版本号
+- `read_result.trace_id` (string): 调用链追踪 ID
+
+---
+
+## 工具列表
+
+| 工具名称 | 功能说明 |
+|---------|---------|
+| find | 查找文本所在位置，返回匹配位置和上下文 |
+| insert_text | 在指定位置插入文本 |
+| insert_paragraph | 在指定位置插入段落，支持设置标题级别、编号类别和编号级别 |
+| replace_text | 替换指定范围内的文本 |
+| find_and_replace_text | 查找并替换文档中所有匹配的文本 |
+| update_text_property | 更新指定范围内文本的属性（加粗、斜体、下划线、删除线、颜色等） |
+| insert_task | 在指定位置插入一个或多个任务，支持设置任务状态和内容文本 |
+| insert_image | 在指定位置插入图片 |
+| insert_page_break | 在指定位置插入分页符 |
+| insert_table | 在指定位置插入表格 |
+| insert_comment | 在指定范围插入批注 |
+| replace_image | 替换文档中的图片 |
+| get_last_operable_pos | 获取文档末尾最后一个可操作位置的索引及前面内容 |
+| get_outline | 获取文档大纲结构（标题层级树），包含各标题和正文的可操作起止位置 |
+
+---
+
+## 工具详细说明
+
+## 1. find
+
+### 功能说明
+在 Word 文档中查找指定文本，返回所有匹配位置及其上下文。如果用户需要替换文本，建议先使用 `find` 查找文本所在的各处位置，让用户确认要替换哪个位置后，再调用 `replace_text` 进行精确替换。
+
+### 调用示例
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
+  "text": "要查找的文本"
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+- `text` (string, 必填): 要查找的文本内容
+
+### 返回值说明
+```json
+{
+  "text_and_locations": [
+    {
+      "range": { "begin": 10, "end": 15 },
+      "related_text": "...上下文文本..."
+    }
+  ],
+  "read_result": {
+    "version": 1,
+    "trace_id": "trace_1234567890"
+  }
+}
+```
+- `text_and_locations` (array): 匹配到的文本位置列表
+  - `range.begin` (uint32): 匹配文本的起始位置
+  - `range.end` (uint32): 匹配文本的结束位置
+  - `related_text` (string): 匹配位置的上下文文本
+- `read_result.version` (int64): 当前文档版本号
+- `read_result.trace_id` (string): 调用相关的可追踪链路id
+
+### 推荐使用流程
+1. 调用 `find` 查找目标文本，获取所有匹配位置
+2. 将匹配结果展示给用户，让用户选择要替换的位置
+3. 根据用户选择，调用 `replace_text` 传入对应的 `range` 进行替换
+
+---
+
+## 2. insert_text
+
+### 功能说明
+在 Word 文档的指定位置插入文本。
+
+### 调用示例
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
+  "text": "要插入的文本内容",
+  "index": 0
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+- `text` (string, 必填): 要插入的文本内容
+- `index` (integer, 必填): 插入位置的索引，从 0 开始，请确认好索引后再操作
+
+### 返回值说明
+```json
+{
+  "base_version": 1,
+  "new_version": 2,
+  "trace_id": "trace_1234567890",
+  "err_msg": ""
+}
+```
+
+---
+
+## 3. insert_paragraph
+
+### 功能说明
+在 Word 文档的指定位置插入段落。支持设置标题级别、编号类别和编号级别，可用于创建标题、有序/无序列表等。
+
+### 调用示例
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
+  "idx": 0,
+  "level": "1",
+  "type": "1",
+  "numbering_lvl": "1",
+  "space_cnt": 0
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+- `idx` (integer, 必填): 插入位置的索引，从 0 开始
+- `level` (string, 可选): 标题级别，取值：
+  - `"0"`: 未指定（保持原样）
+  - `"1"` ~ `"9"`: 一级标题 ~ 九级标题
+  - `"10"`: 正文（无标题）
+  - `"11"`: 标题
+  - `"12"`: 副标题
+- `type` (string, 可选): 编号类别，取值：
+  - `"0"`: 未知/无编号
+  - `"1"`: 圆点列表（无序列表）
+  - `"2"`: 数字编号列表（有序列表）
+- `numbering_lvl` (string, 可选): 编号级别，取值与 `level` 相同（`"1"` ~ `"9"`）
+- `space_cnt` (integer, 可选): 空格数量
+
+### 返回值说明
+```json
+{
+  "base_version": 1,
+  "new_version": 2,
+  "trace_id": "trace_1234567890",
+  "err_msg": ""
+}
+```
+
+---
+
+## 4. replace_text
+
+### 功能说明
+替换 Word 文档中指定范围内的文本为新文本。建议先使用 `find` 工具查找文本位置，让用户确认后再调用此工具进行精确替换。
+
+### 调用示例
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
+  "text": "替换后的文本内容",
+  "ranges": [{"start_index": 0, "end_index": 5}]
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+- `text` (string, 必填): 替换后的文本内容
+- `ranges` (array, 必填): 需要替换的文本范围列表，每个范围包含 `start_index` 和 `end_index`
+
+### 返回值说明
+```json
+{
+  "base_version": 1,
+  "new_version": 2,
+  "trace_id": "trace_1234567890",
+  "err_msg": ""
+}
+```
+
+---
+
+## 5. find_and_replace_text
+
+### 功能说明
+在 Word 文档中查找所有匹配的文本并直接替换为新文本。与 `find` + `replace_text` 的组合不同，此工具会直接替换所有匹配项，用户无法选择性地替换某个特定位置。
+
+### 调用示例
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
+  "old_text": "要查找的文本",
+  "new_text": "替换后的文本"
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+- `old_text` (string, 必填): 要查找的原始文本
+- `new_text` (string, 必填): 替换后的新文本
+
+### 返回值说明
+```json
+{
+  "base_version": 1,
+  "new_version": 2,
+  "trace_id": "trace_1234567890",
+  "err_msg": ""
+}
+```
+
+---
+
+## 6. update_text_property
+
+### 功能说明
+更新 Word 文档中指定范围内文本的属性，支持设置加粗、斜体、下划线、删除线、小型大写、字体颜色、背景颜色等。建议先使用 `find` 工具查找文本位置，获取 range 后再调用此工具修改文本属性。
+
+### 调用示例
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
+  "ranges": [{"begin": 0, "end": 5}],
+  "property": {
+    "bold": true,
+    "color": "#FF0000"
+  }
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+- `ranges` (array, 必填): 需要更新属性的文本范围列表，每个范围包含 `begin` 和 `end`
+- `property` (object, 必填): 要设置的文本属性，支持以下字段：
+  - `bold` (bool, 可选): 是否加粗
+  - `italic` (bool, 可选): 是否斜体
+  - `underline` (bool, 可选): 是否下划线
+  - `strikethrough` (bool, 可选): 是否删除线
+  - `small_caps` (bool, 可选): 是否小型大写
+  - `color` (string, 可选): 字体颜色，如 "#FF0000"
+  - `background_color` (string, 可选): 背景颜色，如 "#FFFF00"
+
+### 返回值说明
+```json
+{
+  "base_version": 1,
+  "new_version": 2,
+  "trace_id": "trace_1234567890",
+  "err_msg": ""
+}
+```
+
+---
+
+## 7. insert_task
+
+### 功能说明
+在 Word 文档的指定位置插入一个或多个任务（待办事项）。每个任务支持设置任务状态（待办/已完成）和任务内容文本。
+
+### 调用示例
+
+**插入单个任务：**
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
+  "idx": 0,
+  "tasks": [
+    {
+      "state": 1,
+      "content": "完成需求文档编写"
+    }
+  ]
+}
+```
+
+**插入多个任务：**
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
+  "idx": 5,
+  "tasks": [
+    {
+      "state": 1,
+      "content": "完成需求文档编写"
+    },
+    {
+      "state": 2,
+      "content": "完成接口设计"
+    },
+    {
+      "state": 1,
+      "content": "编写单元测试"
+    }
+  ]
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+- `idx` (integer, 必填): 插入位置的索引，从 0 开始
+- `tasks` (array, 必填): 任务列表，支持一次插入多个任务，每个任务包含：
+  - `state` (integer, 必填): 任务状态枚举值，不允许传递0值，取值：
+    - `1`: 待办（未完成）
+    - `2`: 已完成
+  - `content` (string, 必填): 任务内容文本
+
+### 返回值说明
+```json
+{
+  "base_version": 1,
+  "new_version": 2,
+  "trace_id": "trace_1234567890",
+  "err_msg": ""
+}
+```
+
+---
+
+## 8. insert_image
+
+### 功能说明
+在 Word 文档的指定位置插入图片。
+
+### 调用示例
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
+  "image_url": "https://example.com/image.png",
+  "index": 0,
+  "width": 400,
+  "height": 300
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+- `image_url` (string, 必填): 图片的 URL 地址
+- `index` (integer, 必填): 插入位置的索引，从 0 开始
+- `width` (integer, 可选): 图片宽度（像素）
+- `height` (integer, 可选): 图片高度（像素）
+- `addon_source` (string, 可选): 插件来源类型
+- `addon_id` (string, 可选): 插件 ID
+- `anchor_id` (string, 可选): 锚点 ID
+- `extra_data` (string, 可选): 额外数据
+
+### 返回值说明
+```json
+{
+  "base_version": 1,
+  "new_version": 2,
+  "trace_id": "trace_1234567890",
+  "err_msg": ""
+}
+```
+
+---
+
+## 9. insert_page_break
+
+### 功能说明
+在 Word 文档的指定位置插入分页符。
+
+### 调用示例
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
+  "index": 10
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+- `index` (integer, 必填): 插入位置的索引，从 0 开始
+
+### 返回值说明
+```json
+{
+  "base_version": 1,
+  "new_version": 2,
+  "trace_id": "trace_1234567890",
+  "err_msg": ""
+}
+```
+
+---
+
+## 10. insert_table
+
+### 功能说明
+在 Word 文档的指定位置插入表格。
+
+### 调用示例
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
+  "index": 0,
+  "rows": 3,
+  "cols": 4
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+- `index` (integer, 必填): 插入位置的索引，从 0 开始
+- `rows` (integer, 必填): 表格行数
+- `cols` (integer, 必填): 表格列数
+
+### 返回值说明
+```json
+{
+  "base_version": 1,
+  "new_version": 2,
+  "trace_id": "trace_1234567890",
+  "err_msg": ""
+}
+```
+
+---
+
+## 11. insert_comment
+
+### 功能说明
+在 Word 文档的指定范围内插入批注（评论）。
+
+### 调用示例
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
+  "text": "这里需要修改措辞",
+  "range": {"begin": 5, "end": 15}
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+- `text` (string, 必填): 批注内容
+- `range` (object, 必填): 批注关联的文本范围，包含 `begin` 和 `end`
+- `ref_id` (string, 可选): 评论ID，用于回复已有批注
+
+### 返回值说明
+```json
+{
+  "base_version": 1,
+  "new_version": 2,
+  "trace_id": "trace_1234567890",
+  "err_msg": ""
+}
+```
+
+---
+
+## 12. replace_image
+
+### 功能说明
+替换 Word 文档中的图片。可以通过旧图片的 URL 或 ID 定位要替换的图片，并指定新图片。
+
+### 调用示例
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
+  "idx": 0,
+  "source": 1,
+  "old_url": "https://example.com/old_image.png",
+  "new_url": "https://example.com/new_image.png"
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+- `idx` (integer, 必填): 图片位置索引
+- `source` (integer, 必填): 图片来源类型，0-未知，1-链接来源，2-附件来源
+- `old_url` (string, 可选): 旧图片的 URL，与 `old_id` 二选一
+- `old_id` (string, 可选): 旧图片的 ID，与 `old_url` 二选一
+- `new_url` (string, 可选): 新图片的 URL 地址，与 `content` 二选一
+- `content` (string, 可选): 新图片的 base64 内容，与 `new_url` 二选一
+
+### 返回值说明
+```json
+{
+  "base_version": 1,
+  "new_version": 2,
+  "trace_id": "trace_1234567890",
+  "err_msg": ""
+}
+```
+
+---
+
+## 13. get_last_operable_pos
+
+### 功能说明
+获取 Word 文档正文（main story）最后一个可操作位置的索引，以及该位置前面最多 10 个字符的内容。在需要向文档末尾追加内容时，可先调用此接口获取末尾可操作位置，再使用 `insert_text`/`insert_image` 等接口在该位置插入内容。
+
+### 调用示例
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx"
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+
+### 返回值说明
+```json
+{
+  "position": 100,
+  "preceding_text": "...前面内容...",
+  "version": 1
+}
+```
+- `position` (int64): 最后一个可操作位置的索引
+- `preceding_text` (string): 该位置前面最多 10 个字符的内容
+- `version` (int64): 当前文档版本号
+
+---
+
+## 14. get_outline
+
+### 功能说明
+获取 Word 文档的完整大纲结构（树形），返回文档标题、各级标题及其下正文的可操作位置范围。可用于：
+- 了解文档整体结构和层级关系
+- 获取指定标题或正文区域的精确位置（`title_start`/`title_end`、`content_start`/`content_end`），以便在对应位置插入或替换内容
+- 在操作前先掌握文档大纲，避免盲目使用 `find` 查找
+
+> ⚠️ **关于「在文档开头插入」的位置说明**：文档大纲的根节点通常是 `HEADING_LEVEL_TITLE`（文档标题），其 `title_start` 表示文档标题之前的位置，`content_start` 表示标题之后、正文开头的位置。当用户要求"在文档开头插入内容"时，需要向用户确认具体含义：
+> - **在文档标题之前插入**：使用 `HEADING_LEVEL_TITLE` 节点的 `title_start`
+> - **在正文开头插入（标题之后）**：使用 `HEADING_LEVEL_TITLE` 节点的 `content_start`
+> 
+> 如果用户未明确说明，应主动询问确认。
+
+### 调用示例
+```json
+{
+  "file_url": "https://docs.qq.com/doc/xxxxxxxx"
+}
+```
+
+### 参数说明
+- `file_url` (string, 推荐): 腾讯文档的文档链接，与 `file_id` 二选一，**推荐优先使用**
+- `file_id` (string, 可选): 文档唯一标识符，与 `file_url` 二选一
+
+### 返回值说明
+```json
+{
+  "outlines": [
+    {
+      "title": "文档标题",
+      "level": "HEADING_LEVEL_TITLE",
+      "title_start": 0,
+      "title_end": 5,
+      "content_start": 6,
+      "content_end": 100,
+      "children": [
+        {
+          "title": "第一章 概述",
+          "level": "HEADING_LEVEL_1",
+          "title_start": 6,
+          "title_end": 12,
+          "content_start": 13,
+          "content_end": 50,
+          "children": [
+            {
+              "title": "1.1 背景",
+              "level": "HEADING_LEVEL_2",
+              "title_start": 13,
+              "title_end": 18,
+              "content_start": 19,
+              "content_end": 50,
+              "children": []
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "version": 1
+}
+```
+
+- `outlines` (array): 大纲根节点列表（树形结构），每个节点包含：
+  - `title` (string): 标题文本内容
+  - `level` (string): 标题级别，取值说明：
+    - `HEADING_LEVEL_TITLE` (11): 文档标题
+    - `HEADING_LEVEL_1` ~ `HEADING_LEVEL_9` (1~9): 一级标题 ~ 九级标题
+    - `HEADING_LEVEL_BODY` (10): 正文（无标题）
+  - `title_start` (int64): 标题可操作的起始位置（可在此位置前插入内容）
+  - `title_end` (int64): 标题可操作的结束位置
+  - `content_start` (int64): 该标题下正文可操作的起始位置（在标题下方插入内容时使用）
+  - `content_end` (int64): 该标题下正文可操作的结束位置（在正文末尾追加内容时使用）
+  - `children` (array): 子目录项列表（递归结构，构成树形大纲）
+- `version` (int64): 当前文档版本号
+
+---
+
+## 典型工作流示例
+
+### 编辑已有 Word 文档
+
+```
+1. 调用 get_outline 获取文档大纲结构，了解文档的标题层级和各区域的可操作位置
+2. 根据大纲定位目标区域，或调用 find 查找具体文本位置
+3. 按需调用工具进行编辑：
+   - 插入文本：insert_text
+   - 插入段落：insert_paragraph
+   - 替换文本：replace_text
+   - 全文替换：find_and_replace_text
+   - 修改文本样式：update_text_property
+   - 插入任务：insert_task
+   - 插入图片：insert_image
+   - 替换图片：replace_image
+   - 插入分页符：insert_page_break
+   - 插入表格：insert_table
+   - 插入批注：insert_comment
+   - 获取文档大纲：get_outline
+```
+
+### 查找并替换文本（精确替换）
+
+```
+1. 调用 find 查找目标文本，获取所有匹配位置
+2. 将匹配结果展示给用户，让用户选择要替换的位置
+3. 调用 replace_text 传入对应的 range 进行精确替换
+```
+
+### 查找并替换文本（全部替换）
+
+```
+1. 直接调用 find_and_replace_text，一次性替换所有匹配项
+```
+
+### 格式化文本
+
+```
+1. 调用 find 查找目标文本，获取文本的 range
+2. 调用 update_text_property 设置文本属性（加粗、颜色等）
+```
+
+### 向文档末尾追加内容
+
+```
+1. 调用 get_last_operable_pos 获取文档末尾可操作位置
+2. 使用返回的 position 作为 index，调用 insert_text / insert_image / insert_table 等工具追加内容
+```
+
+### 在指定标题下插入内容
+
+```
+1. 调用 get_outline 获取文档大纲，找到目标标题节点
+2. 使用节点的 content_start 作为插入位置（在标题下方开头插入）
+   或使用 content_end 作为插入位置（在标题下方正文末尾追加）
+3. 调用 insert_text / insert_paragraph / insert_image 等工具在对应位置插入内容
+```
+
+### 在文档开头插入内容
+
+```
+1. 调用 get_outline 获取文档大纲
+2. 明确用户意图——是要在「文档标题前」还是「正文开头」插入：
+   - 文档标题前：使用 HEADING_LEVEL_TITLE 节点的 title_start 作为插入位置
+   - 正文开头（标题之后）：使用 HEADING_LEVEL_TITLE 节点的 content_start 作为插入位置
+3. 如果用户未明确说明，应主动询问用户确认具体插入位置
+4. 确认位置后，调用 insert_text / insert_paragraph 等工具在对应位置插入内容
+```
+
+### 为文本添加批注
+
+```
+1. 调用 find 查找目标文本，获取文本的 range（begin/end）
+2. 调用 insert_comment 传入 range 和批注内容
+```
+
+### 替换文档中的图片
+
+```
+1. 调用 replace_image 传入旧图片的 URL 或 ID，以及新图片的 URL 或 base64 内容
+```
+
+---
+
+## 注意事项
+
+- 仅支持 Word 文档类型（doc_type: word）
+- `index` / `idx` 参数表示插入位置，从 0 开始计数
+- 操作前需确保拥有文档的写入权限
+- `replace_text` 的 `ranges` 参数中 `start_index` 和 `end_index` 必须在文档有效范围内
+- 替换文本的推荐流程：先调用 `find` 查找定位，让用户确认后再用 `replace_text` 精确替换；如果需要全部替换可直接使用 `find_and_replace_text`
+- `file_id` 和 `file_url` 二选一，**推荐优先使用 `file_url`**（直接传入文档链接更便捷），两者都传时优先使用 `file_id`
+- `get_last_operable_pos` 返回的 `position` 即为文档末尾可安全插入内容的位置
+- `get_outline` 返回树形大纲结构，每个节点的 `content_start`/`content_end` 表示该标题下正文区域的可操作范围，可直接用作 `insert_text` 等工具的 `index` 参数
+- **「在文档开头插入」需明确位置**：用户要求在文档开头插入内容时，应先通过 `get_outline` 获取大纲，区分「文档标题前」（`HEADING_LEVEL_TITLE` 的 `title_start`）和「正文开头」（`HEADING_LEVEL_TITLE` 的 `content_start`），并向用户确认具体插入位置
+- `insert_comment` 的 `range` 必须在文档有效范围内，建议先用 `find` 获取精确范围
+- `replace_image` 需要通过 `old_url` 或 `old_id` 定位旧图片，新图片通过 `new_url` 或 `content`（base64）指定
--- a/skills/tencent-docs/references/manage_references.md
+++ b/skills/tencent-docs/references/manage_references.md
@@ -0,0 +1,800 @@
+# 腾讯文档 MCP 工具完整参考
+
+本文件包含腾讯文档 MCP 中 文件管理类 相关工具的完整 API 说明、支持文件的增删改查、文件搜索、文件夹列表、文件夹信息查询、文档权限设置。
+
+---
+## 目录
+- [文件夹操作](#文件夹操作)
+  - [manage.folder_list](#managefolder_list)
+  - [manage.query_folder_meta](#managequery_folder_meta)
+- [文档创建操作](#文档创建操作)
+  - [manage.create_file](#managecreate_file)
+- [文档搜索操作](#文档搜索操作)
+- [文档重命名](#文档重命名)
+- [云文档最近浏览列表页查询](#云文档最近浏览列表页查询)
+- [文档权限设置](#文档权限设置)
+  - [manage.set_privilege](#manageset_privilege)
+- [文档导入操作](#文档导入操作)
+  - [manage.import_file](#manageimport_file)
+  - [manage.import_progress](#manageimport_progress)
+- [文档导出操作](#文档导出操作)
+  - [manage.export_file](#manageexport_file)
+  - [manage.export_progress](#manageexport_progress)
+- [典型工作流示例](#典型工作流示例)
+
+---
+
+## 文件夹操作
+
+### manage.folder_list
+
+**功能**：拉取指定目录下的文件与文件夹列表。
+
+**使用场景**：
+- 查看根目录或指定文件夹下的所有文件和子文件夹
+- 在创建文档前先获取目标文件夹的 ID
+- 浏览用户的云文档目录结构
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|-----|------|
+| `folder_id` | string |  | 文件夹ID，默认为空，表示查询根目录下的文件 |
+| `start` | integer |  | 查询记录的起始位置，默认为0 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `list[].id` | string | 文件/文件夹 ID |
+| `list[].title` | string | 文件/文件夹标题 |
+| `list[].url` | string | 文件链接 |
+| `list[].is_folder` | boolean | 是否为文件夹，`true` 表示文件夹，`false` 表示文件 |
+| `finish` | boolean | 列表分页是否查完，`false` 表示还有分页未查到，`true` 表示所有分页都查询完成 |
+
+**调用示例（查询根目录）**：
+
+```json
+{}
+```
+
+**调用示例（查询指定文件夹）**：
+
+```json
+{
+  "folder_id": "folder_abc123",
+  "start": 0
+}
+```
+
+**返回示例**：
+
+```json
+{
+  "list": [
+    {
+      "id": "folder_001",
+      "title": "项目文档",
+      "url": "",
+      "is_folder": true
+    },
+    {
+      "id": "doc_001",
+      "title": "会议纪要",
+      "url": "https://docs.qq.com/doc/DV2h5cWJ0R1lQb0lH",
+      "is_folder": false
+    }
+  ],
+  "finish": false,
+  "trace_id": "trace_xyz"
+}
+```
+
+> **注意**：
+> - 返回结果中 `is_folder=true` 的条目为文件夹，其 `id` 可作为 `folder_id` 继续查询子目录内容
+> - 当 `finish=false` 时，需增大 `start` 参数值进行翻页查询
+
+---
+
+### manage.query_folder_meta
+
+**功能**：查询指定文件夹的元信息（meta），支持根据 folderID 查询。
+
+**使用场景**：
+- 查询某个文件夹的详细信息（名称、创建时间等）
+- 验证文件夹 ID 是否有效
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|-----|------|
+| `folder_id` | string | ✅ | 文件夹ID |
+
+**调用示例**：
+
+```json
+{
+  "folder_id": "folder_abc123"
+}
+```
+
+---
+
+## 文档创建操作
+
+### manage.create_file
+
+**功能**：创建腾讯云文档，支持创建多种类型的文档。
+
+**使用场景**：
+- 在指定文件夹下创建新的在线文档（如文档、表格、幻灯片等）
+- 传入 `space_id` 时，在知识库空间中创建文档节点（兼容 `create_space_node` 能力）
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|-----|------|
+| `title` | string | ✅ | 文件标题，长度不超过36字符 |
+| `file_type` | string | ✅ | 文件类型，详见下方取值说明 |
+| `parent_id` | string |  | 父节点ID。不传 `space_id` 时表示个人文件夹唯一标识；传入 `space_id` 时表示空间父节点ID；为空则在个人首页或空间根路径创建 |
+| `space_id` | string |  | 知识库空间ID，传入时在空间中创建节点，不传时在个人首页中创建文件 |
+| `link_node` | object |  | 空间链接节点配置信息，`file_type` 为 `wikilink` 时必填，包含 `link_url`（必填）和 `link_description` |
+
+**file_type 取值说明**：
+
+| 值              | 含义     | 支持场景 |
+|-----------------|----------|---------|
+| `smartcanvas`   | 智能文档  | 个人首页 / 空间 |
+| `doc`           | Word     | 个人首页 / 空间 |
+| `sheet`         | 表格     | 个人首页 / 空间 |
+| `form`          | 收集表   | 个人首页 / 空间 |
+| `slide`         | 幻灯片   | 个人首页 / 空间 |
+| `mind`          | 思维导图  | 个人首页 / 空间 |
+| `flowchart`     | 流程图   | 个人首页 / 空间 |
+| `smartsheet`    | 智能表格  | 个人首页 / 空间 |
+| `folder`        | 文件夹   | 个人首页 / 空间 |
+| `wikilink`      | 空间链接  | 仅空间（需传 `space_id`） |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `file_id` | string | 文件ID（文档ID、文件夹ID 或空间内节点ID） |
+| `title` | string | 文件名称 |
+| `url` | string | 文件链接 |
+| `type` | string | 文件类型 |
+| `space_id` | string | 空间ID，在空间内创建文件时返回 |
+| `error` | string | 错误信息（如有） |
+
+**调用示例**：
+
+```json
+{
+  "title": "项目计划",
+  "file_type": "doc"
+}
+```
+
+**返回示例**：
+
+```json
+{
+  "file_id": "doc_1234567890",
+  "title": "项目计划",
+  "url": "https://docs.qq.com/doc/DV2h5cWJ0R1lQb0lH",
+  "type": "doc",
+  "space_id": "",
+  "error": "",
+  "trace_id": "trace_xyz"
+}
+```
+
+---
+
+## 文档搜索操作
+
+### manage.search_file
+
+**功能**：根据关键词搜索云文档，返回匹配关键词的文档列表。
+
+**使用场景**：
+- 搜索文档标题包含"MCP"关键字的文档
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明                                                   |
+|------|------|-----|------------------------------------------------------|
+| `search_key` | string | ✅ | 搜索关键字                                                |
+
+**返回字段**：
+
+| 字段             | 类型     | 说明       |
+|----------------|--------|----------|
+| `list[].file_id`    | string | 文档id     |
+| `list[].title` | string | 文档标题     |
+| `list[].url`   | string | 文档链接     |
+
+**调用示例**：
+
+```json
+{
+  "search_key": "MCP"
+}
+```
+
+**返回示例**：
+
+```json
+{
+  "list":[
+    {
+      "file_id": "sheet_1",
+      "title": "sheet_name_1",
+      "url": "https://docs.qq.com/sheet/sheet_file_id_1"
+    },
+    {
+      "file_id": "sheet_2",
+      "title": "sheet_name_2",
+      "url": "https://docs.qq.com/sheet/sheet_file_id_2"
+    }
+  ],
+  "trace_id": "trace_xyz"
+}
+```
+
+---
+
+## 文档重命名
+
+### manage.rename_file_title
+
+**功能**：根据云文档ID更新文档标题。
+
+**使用场景**：
+- 将文档(file_id)标题更新为"MCP重命名"
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明                      |
+|------|------|-----|-------------------------|
+| `file_id` | string | ✅ | 文档ID                    |
+| `title` | string | ✅ | 文档标题                    |
+
+**返回字段**：
+
+| 字段             | 类型     | 说明         |
+|----------------|--------|------------|
+| `file_id`      | string  | 文档ID       |
+| `title`        | string  | 文档新标题      |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "MCP",
+  "title": "title"
+}
+```
+
+**返回示例**：
+
+```json
+{
+  "file_id": "MCP",
+  "title": "new_title",
+  "trace_id": "trace_xyz"
+}
+```
+
+---
+
+## 云文档最近浏览列表页查询
+
+### manage.recent_online_file
+
+**功能**：查询云文档最近浏览页文档列表
+
+**使用场景**：
+- 用户查询最近查看或者编辑过的文档列表
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明             |
+|------|------|-----|----------------|
+| `num` | uint32 | ✅ | 当前查询页码数，从1开始   |
+| `count` | uint32 |  | 分页条数，默认为100，每页最多查询的记录数量   |
+| `order_by` | uint32 |  | 排序方式：0-按文档查看时间排序（默认），1-按文件修改时间排序，2-按文档名称排序   |
+
+**返回字段**：
+
+| 字段                  | 类型     | 说明   |
+|---------------------|--------|------|
+| `files[].file_id`   | string  | 文档ID |
+| `files[].file_name` | string  | 文档标题 |
+| `files[].file_url`  | string  | 文档链接 |
+
+**调用示例**：
+
+```json
+{
+  "num": "1"
+}
+```
+
+**返回示例**：
+
+```json
+{
+  "file":[
+    {
+      "file_id": "file_1",
+      "file_name": "file_name_1",
+      "file_url": "xxx"
+    },
+    {
+      "file_id": "file_2",
+      "file_name": "file_name_2",
+      "file_url": "xxx"
+    }
+  ],
+  "trace_id":"trace_abc"
+}
+```
+
+---
+
+## 文档权限管理
+
+### manage.get_privilege
+
+**功能**：根据文档ID查询文档权限策略。返回当前文档的权限设置，仅支持返回 0（私密文档）、1（部分成员可见）、2（所有人可读）、3（所有人可编辑）四种权限场景，其他权限类型暂不支持。
+
+**使用场景**：
+- 查看文档当前的权限状态，决定是否需要调整
+- 在设置权限前先查询当前状态，避免重复设置
+- 确认文档分享权限是否符合预期
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|-----|------|
+| `file_id` | string | ✅ | 文档ID |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `file_id` | string | 文档ID |
+| `policy` | uint32 | 权限策略，0-私密文档，1-部分成员可见，2-所有人可读，3-所有人可编辑 |
+
+**policy 返回值说明**：
+
+| 值 | 含义 | 说明 |
+|----|------|------|
+| 0 | 私密文档 | 仅文档所有者可访问 |
+| 1 | 部分成员可见 | 仅指定的协作者可访问 |
+| 2 | 所有人可读 | 任何获得链接的人都可以查看文档 |
+| 3 | 所有人可编辑 | 任何获得链接的人都可以编辑文档 |
+
+> ⚠️ **注意**：当前仅支持返回上述四种权限场景（0/1/2/3），如果文档设置了其他权限类型（如所有人可执行、所有人可标注等），将返回错误。
+
+**调用示例**：
+
+```json
+{
+  "file_id": "DtDywXFgYFru"
+}
+```
+
+**返回示例**：
+
+```json
+{
+  "file_id": "DtDywXFgYFru",
+  "policy": 2
+}
+```
+
+---
+
+### manage.set_privilege
+
+**功能**：根据文档ID设置文档权限。当前仅支持设置文档为所有人可读或所有人可编辑。
+
+**使用场景**：
+- 创建文档后设置为所有人可查看，方便团队成员浏览
+- 设置文档为所有人可编辑，支持多人协作编辑
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|-----|------|
+| `file_id` | string | ✅ | 文档ID |
+| `policy` | uint32 | ✅ | 权限策略，2-所有人可读，3-所有人可编辑 |
+
+**policy 取值说明**：
+
+| 值 | 含义 | 说明 |
+|----|------|------|
+| 2 | 所有人可读 | 任何获得链接的人都可以查看文档 |
+| 3 | 所有人可编辑 | 任何获得链接的人都可以编辑文档 |
+
+> ⚠️ **注意**：目前仅支持 policy=2（所有人可读）和 policy=3（所有人可编辑）两种权限设置，其他权限值暂不支持。
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `trace_id` | string | 请求追踪ID |
+
+**调用示例（设置所有人可读）**：
+
+```json
+{
+  "file_id": "DtDywXFgYFru",
+  "policy": 2
+}
+```
+
+**调用示例（设置所有人可编辑）**：
+
+```json
+{
+  "file_id": "DtDywXFgYFru",
+  "policy": 3
+}
+```
+
+**返回示例**：
+
+```json
+{
+  "trace_id": "trace_xyz"
+}
+```
+
+---
+
+## 文档导入操作
+
+### manage.import_file
+
+**功能**：将本地文件导入到腾讯云文档。调用后返回task_id，必须配合 `manage.import_progress` 轮询查询导入进度（建议间隔3-5秒），直到progress=100表示导入完成。
+
+**使用场景**：
+- 将本地 docx/xlsx/pptx 等文件导入为腾讯云文档在线文档
+- 批量迁移本地文件到云端
+
+**支持的文件格式**：`xls`、`xlsx`、`csv`、`doc`、`docx`、`txt`、`text`、`ppt`、`pptx`、`pdf`、`xmind`
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|-----|------|
+| `file_name` | string | ✅ | 文件名称（含后缀），如 `report.docx`。支持的文件后缀有xls,xlsx,csv,doc,docx,txt,text,ppt,pptx,pdf,xmind |
+| `file_size` | integer | ✅ | 文件大小，单位为字节(bytes)，如 `36752` |
+| `file_md5` | string | ✅ | 文件的MD5哈希值，hex编码的32位小写字符串，如 `d41d8cd98f00b204e9800998ecf8427e` |
+| `file_base64` | string | ✅ | 文件完整内容经标准Base64编码(StdEncoding)后的字符串，注意不是URL-safe编码 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `task_id` | string | 导入任务 ID，用于查询导入进度 |
+
+**调用示例**：
+
+```json
+{
+  "file_name": "report.docx",
+  "file_size": 36752,
+  "file_md5": "a1b2c3d4e5f6...",
+  "file_base64": "UEsDBBQAAAAI..."
+}
+```
+
+**返回示例**：
+
+```json
+{
+  "task_id": "144115210435508643_e52cf886-5eae-e61c-c828-a0dddb59703d",
+  "trace_id": "trace_xyz"
+}
+```
+
+> **注意**：由于 `file_base64` 字段可能非常大（文件越大 Base64 字符串越长），建议通过 Python 脚本等方式直接构造 HTTP 请求调用 MCP 接口，避免 AI 模型逐 token 生成 Base64 字符串导致超时或截断。
+
+---
+
+### manage.import_progress
+
+**功能**：根据导入任务 `task_id` 查询导入进度。每隔3-5秒轮询一次，当progress=100时表示导入完成，此时返回file_id和file_url。
+
+**使用场景**：
+- 调用 `manage.import_file` 后轮询查询导入状态
+- 导入完成后获取生成的云文档 ID 和访问链接
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|-----|------|
+| `task_id` | string | ✅ | 导入任务 ID（由 `manage.import_file` 返回） |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `progress` | integer | 导入进度百分比（0-100） |
+| `status` | string | 任务状态 |
+| `file_id` | string | 导入完成后的云文档 ID |
+| `file_name` | string | 文档名称 |
+| `file_url` | string | 文档访问链接 |
+| `error` | string | 错误信息（失败时返回） |
+
+**调用示例**：
+
+```json
+{
+  "task_id": "144115210435508643_e52cf886-5eae-e61c-c828-a0dddb59703d"
+}
+```
+
+**返回示例（进行中）**：
+
+```json
+{
+  "progress": 25,
+  "trace_id": "trace_xyz"
+}
+```
+
+**返回示例（完成）**：
+
+```json
+{
+  "progress": 100,
+  "file_id": "DjVlDHwqVVzs",
+  "file_name": "report",
+  "file_url": "https://docs.qq.com/doc/DRGpWbERId3FWVnpz",
+  "trace_id": "trace_xyz"
+}
+```
+
+---
+
+## 文档导出操作
+
+### manage.export_file
+
+**功能**：根据云文档 ID 发起导出任务，返回导出任务 ID。需配合 `manage.export_progress` 轮询查询导出进度（建议间隔3-5秒），导出完成后获取file_url下载链接（带签名的临时URL，有效期约30分钟）。
+
+**使用场景**：
+- 将云端在线文档导出为本地 docx/xlsx/pptx 文件
+- 备份云文档到本地
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|-----|------|
+| `file_id` | string | ✅ | 云文档 ID |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `task_id` | string | 导出任务 ID，用于查询导出进度 |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "DAJpzYoLEpWS"
+}
+```
+
+**返回示例**：
+
+```json
+{
+  "task_id": "144115210435508643_0e15f9be-a2ed-b40a-27c2-10561b7c5072",
+  "trace_id": "trace_xyz"
+}
+```
+
+---
+
+### manage.export_progress
+
+**功能**：根据导出任务 `task_id` 查询导出进度。每隔3-5秒轮询一次，当progress=100时表示导出完成，此时返回file_url（带签名的临时下载链接，有效期约30分钟）。
+
+**使用场景**：
+- 调用 `manage.export_file` 后轮询查询导出状态
+- 导出完成后获取文件下载 URL，通过 curl 等工具下载到本地
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|-----|------|
+| `task_id` | string | ✅ | 导出任务 ID（由 `manage.export_file` 返回） |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `progress` | integer | 导出进度百分比（0-100），100表示导出完成 |
+| `status` | string | 任务状态 |
+| `file_name` | string | 导出的文件名 |
+| `file_url` | string | 文件下载链接（导出完成后返回，带签名的临时URL，有效期约30分钟） |
+| `error` | string | 错误信息（失败时返回） |
+
+**调用示例**：
+
+```json
+{
+  "task_id": "144115210435508643_0e15f9be-a2ed-b40a-27c2-10561b7c5072"
+}
+```
+
+**返回示例（进行中）**：
+
+```json
+{
+  "progress": 50,
+  "trace_id": "trace_xyz"
+}
+```
+
+**返回示例（完成）**：
+
+```json
+{
+  "progress": 100,
+  "file_name": "mcp_import.docx",
+  "file_url": "https://docs-import-export-xxx.cos.ap-guangzhou.myqcloud.com/export/docx/...",
+  "trace_id": "trace_xyz"
+}
+```
+
+> **注意**：`file_url` 为带签名的临时下载链接，有效期约 30 分钟，需及时下载。可通过 `curl -L -o <本地路径> "<file_url>"` 命令保存到本地。
+
+---
+
+## 典型工作流示例
+
+### 工作流一：从零在指定目录下创建指定品类文档
+
+```
+步骤 1：获取文件夹列表
+ → manage.folder_list（判断is_folder=true后获取文件夹id）
+
+步骤 2：创建指定品类文档
+ → manage.create_file（传入文件夹id和品类枚举）
+```
+
+### 工作流二：按照关键字搜索文件列表
+
+```
+步骤 1：搜索文档
+ → manage.search_file（传入用户指定的关键词）
+
+步骤 2：处理数据
+ → 从返回的文档列表中获取所需的文档信息
+ 
+```
+
+### 工作流三：给指定文档生成副本到指定目录
+
+```
+步骤 1：获取文件夹列表
+ → manage.folder_list（判断is_folder=true后获取文件夹ID）
+
+步骤 2：按照指定文档ID生成副本
+ → manage.copy_file（传入文件夹ID和待生成副本的文档ID）
+
+ 
+```
+
+### 工作流四：根据关键词搜索后删除文档
+
+```
+步骤 1：搜索文档
+ → manage.search_file（传入用户指定的关键词，获取文档id）
+
+步骤 2：删除文档
+  → manage.delete_file（传入指定的file_id）
+ 
+```
+
+### 工作流五：将本地文件导入为云文档
+
+```
+步骤 1：读取本地文件并编码
+ → 读取本地文件的二进制内容
+ → 计算文件大小（file_size，单位字节）
+ → 计算文件 MD5 哈希值（file_md5）
+ → 将文件内容进行 Base64 编码（file_base64）
+
+步骤 2：调用导入接口
+ → manage.import_file（传入 file_name、file_size、file_md5、file_base64）
+ → 返回 task_id
+
+步骤 3：轮询查询导入进度
+ → manage.import_progress（传入 task_id）
+ → 每隔 3-5 秒轮询一次，直到 progress=100 或返回错误
+ → 导入完成后获取 file_id 和 file_url
+```
+
+> **特别说明**：由于 `file_base64` 字段数据量大，建议通过 Python 脚本直接构造 HTTP 请求调用 MCP 接口，
+> 而非由 AI 模型逐 token 生成 Base64 字符串。示例脚本流程：
+> 1. 用 Python 读取文件并计算 md5、base64
+> 2. 构造 JSON-RPC 请求体（method: `tools/call`, tool: `manage.import_file`）
+> 3. POST 到 MCP 端点 `https://docs.qq.com/openapi/mcp`（携带 Authorization 和 Cookie 头）
+> 4. 拿到 task_id 后通过 `manage.import_progress` 查询进度
+
+### 工作流六：将云文档导出到本地
+
+```
+步骤 1：发起导出任务
+ → manage.export_file（传入 file_id）
+ → 返回 task_id
+
+步骤 2：轮询查询导出进度
+ → manage.export_progress（传入 task_id）
+ → 每隔 3-5 秒轮询一次，直到 progress=100 或返回错误
+ → 导出完成后获取 file_url（临时下载链接）
+
+步骤 3：下载文件到本地
+ → 使用 curl 或其他 HTTP 工具下载文件
+ → curl -L -o <本地保存路径> "<file_url>"
+```
+
+> **注意事项**：
+> - 导出的下载链接（file_url）为带签名的临时 URL，有效期约 30 分钟，需及时下载
+> - 导出的文件格式取决于原始文档类型（doc→docx，sheet→xlsx，slide→pptx 等）
+
+### 工作流七：导入本地文件后再导出验证（完整闭环）
+
+```
+步骤 1：导入本地文件
+ → 按工作流五执行导入操作
+ → 记录返回的 file_id
+
+步骤 2：导出刚导入的文件
+ → manage.export_file（传入步骤 1 返回的 file_id）
+ → 返回 task_id
+
+步骤 3：轮询导出进度并下载
+ → manage.export_progress（传入 task_id）
+ → 导出完成后通过 file_url 下载到本地
+
+步骤 4：验证文件完整性
+ → 对比原文件与导出文件的大小（可能有微小差异，属正常现象）
+ → 导入导出过程中腾讯文档会对文件内部 XML 结构做标准化处理
+```
+
+### 工作流八：创建文档并设置分享权限
+
+```
+步骤 1：创建文档
+ → create_smartcanvas_by_markdown（传入标题和Markdown内容）
+ → 返回 file_id 和 url
+
+步骤 2：设置文档权限
+ → manage.set_privilege（传入 file_id 和 policy）
+ → policy=2 设置所有人可读，policy=3 设置所有人可编辑
+
+步骤 3：分享文档链接
+ → 将步骤 1 返回的 url 分享给相关人员
+```
+
+### 工作流九：查询文档权限后按需调整
+
+```
+步骤 1：查询文档当前权限
+ → manage.get_privilege（传入 file_id）
+ → 返回 policy：0-私密文档、1-部分成员可见、2-所有人可读、3-所有人可编辑
+
+步骤 2：根据需要调整权限
+ → 如果 policy 不符合预期，调用 manage.set_privilege（传入 file_id 和目标 policy）
+ → policy=2 设置所有人可读，policy=3 设置所有人可编辑
+```
--- a/skills/tencent-docs/references/mdx_references.md
+++ b/skills/tencent-docs/references/mdx_references.md
@@ -0,0 +1,881 @@
+==============================================================================
+AI INGEST SPECIFICATION
+Version: 2.0.0
+==============================================================================
+本文件定义用于生成与解析 MDX 文档的强制性规范。
+该规范主要面向 AI 生成内容使用，同时兼顾人工可读性。
+任何未在本规范中明确允许的语法、组件、属性与取值，均视为禁止。
+
+-------------------------------------------------------------------------------
+AI 解析约定
+-------------------------------------------------------------------------------
+
+本规范使用固定的分隔符来表示文档结构层级。
+
+AI 在解析本规范时，必须将以下分隔符视为结构标记：
+
+    "======"  表示章节(chapter)
+    "------"  表示小节(section)
+
+这些分隔符用于定义本规则文档结构层级， 并非装饰性格式。
+严禁使用将该分隔符应用到 MDX 文档来定义结构(禁止)。
+
+===============================================================================
+第 0 章：总体原则
+===============================================================================
+
+-------------------------------------------------------------------------------
+Markdown语法与 MDX 组件使用规则
+-------------------------------------------------------------------------------
+Markdown 优先
+    Markdown 是主要内容表达形式。
+    仅当 Markdown 无法表达所需结构或语义(例如：表格、分栏、复杂引用、需要属性的块等)时，才允许使用 MDX。
+
+行内样式一律使用 Mark(强制)
+    所有行内样式必须使用 <Mark>。
+    禁止使用 Markdown 的 **bold** / *italic* / ~~strike~~ / __underline__ 等行内样式。
+
+未知组件规则(强制)
+    AI 只能使用本规范中定义的组件。
+    如果需要表达的结构没有对应组件，必须退化为 Markdown 表达。
+    禁止生成任何未在本规范中声明的组件。
+
+-------------------------------------------------------------------------------
+缩进、换行规则
+-------------------------------------------------------------------------------
+缩进单位
+    一级缩进固定为 4 个空格；
+    禁止使用 Tab。
+
+块缩进规则(强制)
+    块级组件必须“三段式多行写法”(强制)
+    块级组件禁止写成一行(即使内容很短)。
+
+    错误(禁止):
+        <Heading level="1">标题</Heading>
+    正确(强制):
+        <Heading level="1">
+            标题
+        </Heading>
+
+块内内容与子块的缩进规则(强制)
+    块级组件的“直接内容行”(纯文本 / Mark / Link)必须缩进到开标签下一层：
+        内容行缩进 = 开标签缩进 + 4 空格
+    子块(嵌套块级组件)同样必须缩进一层：
+        子块开标签缩进 = 父块开标签缩进 + 4 空格
+    同一层级的兄弟块必须保持一致的缩进深度。
+    禁止出现“块级嵌套但无缩进”的写法。
+
+行内内容的换行限制(强制)
+    Mark / Link 必须与周围文本处于同一行文本流中。
+    禁止为了排版在句子中间插入换行，造成“软换行”。
+    单段内容(例如 Callout 内的一段说明)必须保持连续文本流，除非明确需要软换行。
+
+-------------------------------------------------------------------------------
+表达式能力限制(强制)
+-------------------------------------------------------------------------------
+以下全部禁止：
+    任何 {...} 表达式属性(例如 level={3})
+    任何 MDX expression
+    任何 ESM(import / export)
+    任何未定义组件
+
+-------------------------------------------------------------------------------
+属性语法规则(强制)
+-------------------------------------------------------------------------------
+禁止使用表达式(再次强调)
+    禁止使用 {}, 包括属性值、子表达式等
+
+属性值必须使用双引号(强制)
+    错误(禁止):
+        <Heading level=1>
+
+    错误(禁止):
+        <Heading level='1'>
+
+    错误(禁止):
+        <Heading level={1}>
+
+    正确(强制):
+        <Heading level="1">
+
+布尔属性不写值(强制):
+    以下属性为布尔属性，出现即为 true, 不得写 ="true":
+        Mark: bold / italic / underline / strike
+        Todo: checked(如有)
+    严禁使用 false 显式设置。
+    如果后续章节中明确了属性为布尔类型，遵循该规则
+        正确:
+            <Mark bold>文本</Mark>
+            <Todo checked>
+                已完成
+            </Todo>
+        不推荐(禁止生成):
+            <Mark bold="true">文本</Mark>
+            <Todo checked="true">
+                已完成
+            </Todo>
+        错误(禁止):
+            <Mark bold="false">文本</Mark>
+            <Todo checked="false">
+                已完成
+            </Todo>
+
+-------------------------------------------------------------------------------
+颜色 Token 规则(强制)
+-------------------------------------------------------------------------------
+所有颜色相关属性均为 token 白名单。
+禁止使用任何 CSS 颜色值(例如 #fff、rgb(...)、red 等)。
+颜色表名单会在末尾附录中定义。
+
+===============================================================================
+第 1 章：页面级属性(Frontmatter)
+===============================================================================
+文档的页面级属性使用 frontmatter 来定义
+
+位置与格式(强制)
+    文档顶部必须包含 YAML frontmatter。
+    frontmatter 必须是文档的第一段内容，前面不得出现任何字符(包括空行)。
+    frontmatter 必须以 --- 开始，并以 --- 结束。
+    frontmatter 中必须包含 title 字段，且为非空字符串。
+
+允许字段(强制白名单)
+    仅允许以下字段(其余字段禁止出现)：
+        title
+        cover
+        icon
+        fontFamily
+        fontSize
+        spacing
+
+取值规则(强制)
+    title (required)
+        表示文档的标题。
+        允许字符串。
+    cover (recommended)
+        建议都添加，除非文档内容非常不适合添加。
+        表示文档的头图，横幅展示。
+        允许图片链接。
+    icon (optional)
+        必须为单个 emoji 字符,禁止多个 emoji。
+        禁止文本或图片 URL。
+
+    fontFamily (optional)
+        仅允许：
+            simsun
+            kaiti
+            default
+        含义：
+            simsun  → 宋体
+            kaiti   → 楷体
+            default → 默认字体(黑体体系)
+
+    fontSize (optional)
+        仅允许：
+            small
+            default
+            large
+
+    spacing (optional)
+        仅允许：
+            compact
+            default
+            loose
+
+默认行为(重要强制)
+    fontFamily / fontSize / spacing 的默认值均为 default。
+    如无明确需求：必须省略这三个字段；禁止为了“完整性”自动写入 default。
+
+    示例(正确)：
+        ---
+        title: React 学习路线
+        icon: ⚛️
+        cover: https://example.cdn.com/images/learn-react-road.png
+        ---
+
+    示例(错误：不应显式写默认值)：
+        ---
+        title: React 学习路线
+        cover: https://example.cdn.com/images/learn-react-road.png
+        fontFamily: default
+        fontSize: default
+        spacing: default
+        ---
+
+==============================================================================
+第 2 章: Block Components (块级组件)
+==============================================================================
+
+------------------------------------------------------------------------------
+Paragraph
+------------------------------------------------------------------------------
+用途
+    段落
+
+属性
+    textAlign (文本对齐方式)
+    blockColor (段落背景颜色)
+
+取值规则
+    textAlign (optional)
+        left
+        center
+        right
+    blockColor (optional)
+        BLOCK_COLORS
+
+子元素
+    Text
+    Mark
+    Link
+
+示例
+    <Paragraph textAlign="right">
+        <Mark bold>加粗</Mark>普通文本
+    </Paragraph>
+
+限制规则
+    如不需要段落级属性：必须不包 Paragraph(直接输出纯文本/Mark/Link)。
+    仅当需要段落级属性(例如 textAlign、blockColor)时才使用 Paragraph。
+    默认为文本左对齐，不需要显示设置 textAlign 为 left。
+
+------------------------------------------------------------------------------
+Heading
+------------------------------------------------------------------------------
+用途
+    标题
+
+属性
+    textAlign (文本对齐方式)
+    blockColor (段落背景颜色)
+    level (标题层级)
+
+取值规则
+    textAlign (optional)
+        left
+        center
+        right
+    blockColor (optional)
+        BLOCK_COLORS
+    level (required)
+        数字字面量字符串 1-6
+
+子元素
+    Text
+    Mark
+    Link
+
+示例
+    <Heading level="1" blockColor="red">
+        标题1
+    </Heading>
+
+限制规则
+    当标题只需要 level 属性且无其他属性时，应优先使用 Markdown 标题语法：
+        # 标题1
+        ## 标题2
+    当需要额外属性（例如 textAlign、blockColor）时，必须使用 Heading 组件。
+    标题支持标题 1-6。
+
+    frontmatter.title 定义页面或文档的唯一标题。
+    正文中允许使用一级标题 (#)， 但不得将与 frontmatter.title 内容相同的一级标题放在正文开头。
+    如果正文第一段为与 frontmatter.title 相同的一级标题 (#)， 则视为重复标题，生成时应避免。
+    正文中的一级标题仅用于章节划分，不表示页面标题。
+
+------------------------------------------------------------------------------
+BlockQuote
+------------------------------------------------------------------------------
+用途
+    引用块
+
+属性
+    textAlign (文本对齐方式)
+    blockColor (段落背景颜色)
+
+取值规则
+    textAlign (optional)
+        left
+        center
+        right
+    blockColor (optional)
+        BLOCK_COLORS
+
+子元素
+    所有块级元素
+
+示例
+    <BlockQuote>
+        引用内容
+
+        <BlockQuote>
+            子引用内容
+        </BlockQuote>
+    </BlockQuote>
+
+限制规则
+    当引用块中只有一个段落时，且无属性设置时，采用 Markdown 的表达方式。
+    当引用块中有嵌套或者多个段落时，采用 Mdx 表达。
+
+------------------------------------------------------------------------------
+Callout
+------------------------------------------------------------------------------
+用途
+    高亮块
+
+属性
+    blockColor (高亮背景颜色)
+    borderColor (高亮边框颜色)
+    icon (高亮块左上角 icon)
+
+取值规则
+    blockColor (required)
+        BLOCK_COLORS
+    borderColor (required)
+        BORDER_COLORS
+    icon (optional)
+        单个 Emoji 字符
+
+子元素
+    所有块级元素
+
+示例
+    <Callout icon="⚠️" blockColor="yellow" borderColor="light_orange">
+        警告
+
+        警告内容...
+    </Callout>
+
+限制规则
+    blockColor 和 borderColor 建议使用同一色系, 除非需要反差场景。
+    单段 Callout 文本必须保持连续文本流(禁止句中人为换行)。
+
+------------------------------------------------------------------------------
+ColumnList
+------------------------------------------------------------------------------
+用途
+    分栏容器
+
+属性
+    无
+
+取值规则
+    无
+
+子元素
+    Column
+
+示例
+    <ColumnList>
+        <Column>
+            分栏左
+        </Column>
+        <Column>
+            分栏右
+        </Column>
+    </ColumnList>
+
+限制规则
+    仅表达容器，无需设置任何属性。
+    子元素中必须为 Column，且必须至少存在一个。
+
+------------------------------------------------------------------------------
+Column
+------------------------------------------------------------------------------
+用途
+    分栏实体 item
+
+属性
+    width (宽度)
+
+取值规则
+    width (recommended)
+        带 % 的百分比字符串
+
+子元素
+    所有块级元素
+
+示例
+    <ColumnList>
+        <Column width="20%">
+            分栏左
+        </Column>
+        <Column width="60%">
+            分栏中
+        </Column>
+        <Column width="20%">
+            分栏右
+        </Column>
+    </ColumnList>
+
+限制规则
+    不能独立定义，只允许出现在 ColumnList 下。
+    width 代表宽度百分比，不设置的会均分剩下的宽度，但建议都根据内容进行合理设置。
+
+------------------------------------------------------------------------------
+Divider
+------------------------------------------------------------------------------
+用途
+    分割线
+
+属性
+    blockColor (分割线颜色)
+
+取值规则
+    blockColor (optional)
+       DIVIDER_COLORS
+
+子元素
+    无
+
+示例
+    <Divider blockColor="sky_blue" />
+
+限制规则
+    使用自闭合标签。
+    如果不需要设置颜色，使用 Markdown 的 --- 表达方式。
+
+------------------------------------------------------------------------------
+Image
+------------------------------------------------------------------------------
+用途
+    图片
+
+属性
+    src (图片地址)
+    alt (图片说明)
+    align (对齐方式)
+    width (宽度)
+    height (高度)
+
+取值规则
+    src (required)
+        图片地址字符串
+    alt (recommended)
+        文字字符串
+    align (optional)
+        left
+        center
+        right
+    width (optional)
+        数字字面量字符串，单位 px
+    height (optional)
+        数字字面量字符串，单位 px
+
+子元素
+    无
+
+示例
+    <Image src="https://example.com/image.png" alt="示例图片" align="right" />
+
+限制规则
+    图片均采用 Mdx 表达方式，不使用 Markdown 表达。
+    图片地址必须使用 src 属性，严禁使用 imageId、image_id 等非标准属性名。upload_image 返回的 image_id 值也必须设置到 src 属性中（如 <Image src="image_id值" />）。
+    align 默认是 center，可不显式设置。
+    width 和 height 需要根据原始比例设置，如果获取不到原始比例，只需要设置宽度。不设置的话最大宽度为文档容器宽度。
+
+图片获取优先级(强制)
+    MDX 文档应积极使用图片来丰富文档内容和视觉效果。
+    图片获取方式按以下优先级执行：
+        1. 优先使用网络搜索的可公开访问图片（如 Unsplash、Pexels 等免费图库的直链）
+           确保图片 URL 可访问、可下载，直接设置到 src 属性中。
+           示例：<Image src="https://images.unsplash.com/photo-xxx" alt="描述" />
+        2. 仅当网络搜索无法满足需求时，再通过 AI 生成图片并调用 upload_image 上传获取 image_id
+           将 image_id 设置到 src 属性中。
+           示例：<Image src="upload_image返回的image_id" alt="描述" />
+    禁止在有合适的网络可访问图片时仍然走 upload_image 流程。
+
+------------------------------------------------------------------------------
+Todo
+------------------------------------------------------------------------------
+用途
+    待办列表
+
+属性
+    blockColor (段落背景颜色)
+    checked (是否完成)
+
+取值规则
+    blockColor (optional)
+        BLOCK_COLORS
+    checked (optional)
+        布尔类型，不用显式设置值，存在属性即代表 true
+
+子元素
+    Text
+    Mark
+    Link
+
+示例
+    <Todo>
+        任务1
+        <Todo checked>
+            任务1-1
+        </Todo>
+        <Todo>
+            任务1-2
+        </Todo>
+    </Todo>
+    <Todo checked>
+        任务2
+    </Todo>
+
+
+限制规则
+    每一个 Todo 代表一个待办项，连续的组成一个视觉列表。
+    允许有子待办，但必须放在待办正文的后面。
+    Todo 第一个 child 必须为行内文本流或Mark，Link。
+    Todo 后面的 child 可以为任意块元素，但建议子任务嵌套或需要混合使用无序列表有序列表的场景。
+
+------------------------------------------------------------------------------
+BulletedList
+------------------------------------------------------------------------------
+用途
+    无序列表
+
+属性
+    blockColor (段落背景颜色)
+
+取值规则
+    blockColor (optional)
+        BLOCK_COLORS
+
+子元素
+    Text
+    Mark
+    Link
+    所有块级元素
+
+示例
+    <BulletedList>
+        无序列表
+        <BulletedList>
+            无序子列表
+        </BulletedList>
+    </BulletedList>
+    <BulletedList>
+        无序列表
+    </BulletedList>
+
+    错误(禁止):
+        <BulletedList>
+            无序列表1
+
+            无序列表2
+
+            无序列表3
+        </BulletedList>
+
+
+限制规则
+    每一个 BulletedList  代表一个列表项，连续的组成一个视觉列表。
+    第一个 child 必须为行内文本流或Mark，Link, 表示列表项文本内容。
+    后面的 child 可以为任意块元素，但建议子列表嵌套或需要混合使用待办列表、无序列表、有序列表的场景。
+
+------------------------------------------------------------------------------
+NumberedList
+------------------------------------------------------------------------------
+用途
+    有序列表
+
+属性
+    blockColor (段落背景颜色)
+
+取值规则
+    blockColor (optional)
+        BLOCK_COLORS
+
+子元素
+    Text
+    Mark
+    Link
+    所有块级元素
+
+示例
+    <NumberedList>
+        有序列表1
+        <NumberedList>
+            有序列表1.1
+        </NumberedList>
+        <NumberedList>
+            有序列表1.2
+        </NumberedList>
+    </NumberedList>
+    <NumberedList>
+        有序列表2
+    </NumberedList>
+
+    错误(禁止):
+        <NumberedList>
+            有序列表1
+
+            有序列表2
+
+            有序列表3
+        </NumberedList>
+
+
+限制规则
+    每一个 NumberedList 代表一个列表项，连续的组成一个视觉列表。
+    第一个 child 必须为行内文本流或Mark，Link, 表示列表项文本内容。
+    后面的 child 可以为任意块元素，但建议子列表嵌套或需要混合使用待办列表、无序列表、有序列表的场景。
+------------------------------------------------------------------------------
+Table
+------------------------------------------------------------------------------
+用途
+    表格
+
+属性
+    无
+
+取值规则
+    无
+
+子元素
+    TableRow
+
+示例
+    <Table>
+        <TableRow>
+            <TableCell>
+                cell A1
+            </TableCell>
+            <TableCell>
+                cell A2
+            </TableCell>
+        </TableRow>
+    </Table>
+
+
+限制规则
+    表格使用 Mdx 表达，禁止使用 Markdown 语法表达。
+
+------------------------------------------------------------------------------
+TableRow
+------------------------------------------------------------------------------
+用途
+    表格行
+
+属性
+    无
+
+取值规则
+    无
+
+子元素
+    TableCell
+
+示例
+    <Table>
+        <TableRow>
+            <TableCell>
+                cell A1
+            </TableCell>
+            <TableCell>
+                cell A2
+            </TableCell>
+        </TableRow>
+    </Table>
+
+
+限制规则
+    禁止单独使用，仅可作为 Table 的子元素来表达行容器。
+
+------------------------------------------------------------------------------
+TableCell
+------------------------------------------------------------------------------
+用途
+    表格单元格
+
+属性
+    无
+
+取值规则
+    无
+
+子元素
+    除 Table 外的块元素
+
+示例
+    <Table>
+        <TableRow>
+            <TableCell>
+                cell A1
+            </TableCell>
+            <TableCell>
+                cell A2
+            </TableCell>
+        </TableRow>
+    </Table>
+
+
+限制规则
+    禁止单独使用，仅可作为 TableRow 的子元素来表达单元格容器。
+
+==============================================================================
+第 3 章: Inline Components (行内组件)
+==============================================================================
+
+------------------------------------------------------------------------------
+Mark
+------------------------------------------------------------------------------
+用途
+    带样式文本
+
+属性
+    bold(加粗)
+    italic(斜体)
+    underline(下划线)
+    strike(中划线)
+    color(文本颜色)
+    backgroundColor(文本背景色)
+
+取值规则
+    bold (optional)
+        布尔属性不写值
+    italic (optional)
+        布尔属性不写值
+    underline (optional)
+        布尔属性不写值
+    strike (optional)
+        布尔属性不写值
+    color(optional)
+        TEXT_COLORS
+    backgroundColor (optional)
+        BLOCK_COLORS
+
+子元素
+    文本
+
+示例
+    <Mark bold>重点内容</Mark><Mark color="yellow">警告</Mark>
+
+限制规则
+    Mark 必须单行书写(开始标签、内容、结束标签在同一行)。
+    Mark 不得被拆行，不得在 Mark 前后额外插入换行造成软换行。
+
+------------------------------------------------------------------------------
+Link
+------------------------------------------------------------------------------
+用途
+    超链接
+
+属性
+    href (链接地址)
+
+取值规则
+    href (required)
+        链接文本
+
+子元素
+    文本
+
+示例
+    <Link href="...">文本</Link>
+
+限制规则
+    Link 必须单行书写(开始标签、内容、结束标签在同一行)。
+    Link 不得被拆行，不得在 Link 前后额外插入换行造成软换行。
+
+==============================================================================
+APPENDIX
+==============================================================================
+
+------------------------------------------------------------------------------
+BLOCK_COLORS
+------------------------------------------------------------------------------
+用于：
+    blockColor
+    Mark.backgroundColor
+
+允许值：
+    default
+    grey
+    light_grey
+    dark
+    light_blue
+    blue
+    light_sky_blue
+    sky_blue
+    light_green
+    green
+    light_yellow
+    yellow
+    light_orange
+    orange
+    light_red
+    red
+    light_rose_red
+    rose_red
+    light_purple
+    purple
+
+
+------------------------------------------------------------------------------
+BORDER_COLORS
+------------------------------------------------------------------------------
+用于：
+    Callout.borderColor
+
+允许值：
+    default
+    grey
+    blue
+    sky_blue
+    green
+    yellow
+    orange
+    red
+    rose_red
+    purple
+
+
+------------------------------------------------------------------------------
+DIVIDER_COLORS
+------------------------------------------------------------------------------
+用于：
+    Divider.blockColor
+
+允许值：
+    default
+    black
+    light_grey
+    grey
+    light_blue
+    blue
+    light_sky_blue
+    sky_blue
+    light_green
+    green
+    light_yellow
+    yellow
+    light_orange
+    orange
+    light_red
+    red
+    light_rose_red
+    rose_red
+    light_purple
+    purple
+
+
+------------------------------------------------------------------------------
+TEXT_COLORS
+------------------------------------------------------------------------------
+用于：
+    Mark.color
+
+允许值：
+    default
+    grey
+    blue
+    sky_blue
+    green
+    yellow
+    orange
+    red
+    rose_red
+    purple
+
+==============================================================================
+END
+==============================================================================
--- a/skills/tencent-docs/references/slide_references.md
+++ b/skills/tencent-docs/references/slide_references.md
@@ -0,0 +1,150 @@
+# 幻灯片（Slide / PPT）参考文档
+
+本文件包含腾讯文档 MCP 幻灯片相关工具的使用指南和注意事项。
+
+---
+
+## 概述
+
+幻灯片通过 `create_slide` 工具创建，AI 自动根据用户描述和参考资料生成 PPT 内容。该接口为**异步接口**，需配合 `slide_progress` 工具轮询进度。
+
+---
+
+## 工具列表
+
+| 工具名称 | 功能说明 |
+|---------|---------|
+| create_slide | 创建幻灯片（AI 自动生成内容，异步接口） |
+| slide_progress | 查询幻灯片生成进度 |
+
+---
+
+## 工具详细说明
+
+### 1. create_slide
+
+#### 功能说明
+根据用户描述和参考资料，由 AI 自动生成幻灯片内容并创建 PPT。
+
+#### 调用示例
+
+**示例1：根据主题生成 PPT**
+```json
+{
+  "description": "生成一份主题为'2024年度销售总结'的PPT，要求包含业绩回顾、亮点项目、问题分析和来年规划四个章节"
+}
+```
+
+**示例2：根据参考材料生成 PPT**
+```json
+{
+  "reference_context": "第一季度销售额达到1200万，同比增长25%。主要增长来自华南区域，新客户占比40%。存在问题：北方市场渗透率不足，客单价偏低。",
+  "description": "根据材料生成PPT，要求风格简洁专业，重点突出数据亮点"
+}
+```
+
+#### 参数说明
+- `description` (string, 必填): 用户对 PPT 的要求描述。样例1：【生成一份主题为xxx的PPT，要求xxxx】；样例2：【根据材料生成PPT，要求xxxx】
+- `reference_context` (string, 可选): 生成 PPT 的参考资料，必须是 UTF-8 文本格式。**仅当用户明确指定需要根据某段内容/材料生成PPT时才传此参数，不要自由发挥填充内容**
+
+#### 返回值说明
+```json
+{
+  "session_id": "session_1234567890",
+  "error": "",
+  "trace_id": "trace_1234567890"
+}
+```
+
+> ⚠️ **注意**：`create_slide` 为异步接口，返回 `session_id` 后需配合 `slide_progress` 工具轮询进度（每隔20秒轮询一次，最长等待20分钟），待状态为 `completed` 时从响应中获取 `file_url`。
+
+### 2. slide_progress
+
+#### 功能说明
+查询幻灯片生成进度，与 `create_slide` 配合使用。调用 `create_slide` 获取 `session_id` 后，每隔 20 秒轮询一次，最长等待 20 分钟，直到状态为 `completed` 或 `failed`。
+
+#### 状态说明
+- `in_progress`：进行中，继续轮询
+- `completed`：已完成，幻灯片已生成，从响应中获取 `file_url`
+- `failed`：失败，停止轮询
+- `canceled`：已取消，停止轮询
+- `not_found`：未找到（`session_id` 不正确或已过期），停止轮询
+
+#### 调用示例
+```json
+{
+  "session_id": "session_1234567890"
+}
+```
+
+#### 参数说明
+- `session_id` (string, 必填): `create_slide` 返回的异步任务 session_id
+
+#### 返回值说明
+```json
+{
+  "status": "completed",
+  "file_url": "https://docs.qq.com/slide/DV2h5cWJ0R1lQb0lH",
+  "error": "",
+  "trace_id": "trace_1234567890"
+}
+```
+
+---
+
+## 典型工作流
+
+### 创建幻灯片
+
+```
+1. 调用 create_slide 传入 description（用户要求）和可选的 reference_context（参考资料）
+2. 获取返回的 session_id
+3. 使用 slide_progress 轮询进度（每隔 20 秒轮询一次，最长等待 20 分钟）
+4. 待状态为 completed 时从响应中获取 file_url 并告知用户
+```
+
+### ⚠️ Agent 执行指引（重要）
+
+#### 异步轮询任务：推荐使用 spawn 子会话
+
+幻灯片生成通常需要 **10~15 分钟**，推荐使用 **spawn 子会话**专职轮询，主会话保持响应，避免阻塞用户交互。
+
+#### ✅ 推荐做法：spawn 子会话轮询 + 主会话实时播报
+
+**标准工作流：**
+
+1. **主会话**：提交 `create_slide` 任务 → 立即告诉用户"已开始"
+2. **spawn 子会话**：专职轮询
+   - 每 20 秒检查一次
+   - 每次检查生成状态给主会话
+   - 超时自动清理，输出超时状态给主会话
+3. **主会话**：接收子会话状态并格式化输出给用户
+   - 进行中：`⏳ 正在生成中，第 N 次轮询，请稍候...`
+   - 完成：`✅ 生成完成！PPT 链接：<file_url>`
+   - 失败：`❌ 生成失败：<原因>`
+   - 超时：`⚠️ 生成超时（已等待 20 分钟），请稍后重试`
+
+#### ❌ 避免的做法
+
+```bash
+# ❌ 错误1：主会话直接 sleep 循环阻塞，用户无法交互
+for i in 1..15; do
+  mcporter call tencent-docs slide_progress ...
+  sleep 20  # 阻塞主会话，用户体验差
+done
+
+# ❌ 错误2：后台进程静默等待，不向用户播报进度
+# 用户看不到任何进度，体验如同宕机
+
+# ❌ 错误3：子会话轮询完成后不通知主会话
+# 用户在主会话中无法得知结果
+```
+
+---
+
+## 注意事项
+
+- `create_slide` 为异步接口，返回 `session_id` 后必须轮询
+- 轮询间隔：每 20 秒一次
+- 最长等待时间：20 分钟
+- `reference_context` 仅在用户明确指定需要根据某段内容/材料生成 PPT 时才传
--- a/skills/tencent-docs/references/smartcanvas_references.md
+++ b/skills/tencent-docs/references/smartcanvas_references.md
@@ -0,0 +1,907 @@
+# 文档（SmartCanvas）工具完整参考文档
+
+腾讯文档文档（SmartCanvas）提供了一套完整的文档元素操作 API，支持对页面、文本、标题、待办事项等元素进行增删改查操作。
+
+---
+
+## 目录
+
+- [概念说明](#概念说明)
+- [元素操作](#元素操作)
+  - [smartcanvas.create_smartcanvas_element - 新增元素](#smartcanvascreatesmartcanvaselement)
+  - [smartcanvas.get_element_info - 查询元素信息](#smartcanvasgetelement_info)
+  - [smartcanvas.get_page_info - 查询页面内容](#smartcanvasgetpageinfo)
+  - [smartcanvas.get_top_level_pages - 查询顶层页面](#smartcanvasgettoplevelpages)
+  - [smartcanvas.update_element - 修改元素](#smartcanvasupdateelement)
+  - [smartcanvas.delete_element - 删除元素](#smartcanvasdeleteelement)
+- [追加内容](#追加内容)
+  - [smartcanvas.append_insert_smartcanvas_by_markdown - 追加 Markdown 内容](#smartcanvasappendinsertsmartcanvasbymarkdown-追加)
+- [枚举值参考](#枚举值参考)
+- [元素类型详细说明](#元素类型详细说明)
+- [典型工作流示例](#典型工作流示例)
+
+---
+
+## 概念说明
+
+| 概念 | 说明 |
+|------|------|
+| `file_id` | 文档的唯一标识符，每个文档有唯一的 file_id |
+| `element_id` | 元素 ID，文档中每个元素（页面、文本、标题、任务）都有唯一 ID |
+| `page_id` | 页面元素 ID，Page 是文档的基本容器单元 |
+| `parent_id` | 父元素 ID，用于确定元素的层级关系 |
+
+**元素层级关系**：
+
+```
+file_id（文档）
+└── Page（页面）
+    ├── Heading（标题，LEVEL_1 ~ LEVEL_6）
+    ├── Text（文本）
+    └── Task（待办事项）
+```
+
+> ⚠️ **重要约束**：
+> - `Text`、`Task`、`Heading` 必须挂载在 `Page` 类型的父节点下
+> - `Page` 可以不指定父节点（挂载到根节点）
+> - 父节点不支持为 `Heading` 类型
+
+---
+
+## 创建智能文档 — create_smartcanvas_by_mdx
+
+通过 MDX 格式创建排版丰富的在线智能文档。MDX 支持分栏布局（ColumnList）、高亮块（Callout）、待办列表（Todo）、表格（Table）、带样式文本（Mark）等高级组件。MDX 内容必须严格遵循 `mdx_references.md` 规范生成。
+
+**📖 MDX 规范详见：** `mdx_references.md`
+
+### 工作流
+
+```
+1. 阅读 mdx_references.md 了解 MDX 组件规范（组件、属性、取值白名单、格式约束）
+2. 按规范生成包含 Frontmatter 和 MDX 组件的内容
+3. 对照 mdx_references 逐条自校验，确保格式合规
+4. 调用 create_smartcanvas_by_mdx 创建文档（传入 title + MDX 内容）
+5. 从返回结果中获取 file_id 和 url
+```
+
+### 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `title` | string | ✅ | 文档标题，不超过36个字符 |
+| `mdx` | string | ✅ | 严格符合 mdx_references 规范的 MDX 格式文本 |
+| `parent_id` | string | | 父节点ID，为空时在空间根目录创建，不为空时在指定节点下创建 |
+
+### 调用示例
+
+```json
+{
+  "title": "项目需求文档",
+  "mdx": "---\ntitle: 项目需求文档\nicon: 📋\n---\n\n# 项目需求\n\n<Callout icon=\"📌\" blockColor=\"light_blue\" borderColor=\"blue\">\n    本项目旨在开发一套智能文档管理系统。\n</Callout>\n\n## 功能需求\n\n<BulletedList>\n    文档创建功能\n</BulletedList>\n<BulletedList>\n    文档编辑功能\n</BulletedList>\n<BulletedList>\n    协作功能\n</BulletedList>"
+}
+```
+
+### 返回值说明
+
+```json
+{
+  "file_id": "doc_1234567890",
+  "url": "https://docs.qq.com/doc/DV2h5cWJ0R1lQb0lH",
+  "error": "",
+  "trace_id": "trace_1234567890"
+}
+```
+
+---
+
+## 元素操作
+
+### smartcanvas.create_smartcanvas_element
+
+**功能**：在文档中新增元素，支持同时添加页面、文本、标题、待办事项等多种类型元素。
+
+**使用场景**：
+- 在文档中追加新页面
+- 在已有页面中添加文本、标题、待办事项
+- 在指定元素后面插入新内容
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明                                                                     |
+|------|------|------|------------------------------------------------------------------------|
+| `file_id` | string | ✅ | 文档的唯一标识符                                                             |
+| `parent_id` | string | 条件必填 | 父节点元素 ID。插入 Text/Task/Heading 时必填（父节点必须为 Page 类型）；插入 Page 时可不填（插入到根节点） |
+| `after` | string | | 插入到哪个节点之后的元素 ID，不填则作为父节点的最后一个子节点插入                                     |
+| `pages` | []Page | | 要添加的页面元素列表                                                             |
+| `texts` | []Text | | 要添加的文本元素列表                                                             |
+| `tasks` | []Task | | 要添加的待办事项元素列表                                                           |
+| `headings` | []Heading | | 要添加的标题元素列表                                                             |
+| `image` | []Image | | 要添加的图片元素列表，需先调用 `upload_image` 获取 image_ID                             |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `element_infos` | array | 创建的元素信息列表，详见 ElementInfo 结构 |
+| `error` | string | 错误信息，操作失败时返回 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**ElementInfo 结构**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 元素唯一标识符 |
+| `version` | uint32 | 元素版本号 |
+| `type` | string | 元素类型：Page、Text、Heading、Task |
+| `element` | string | 元素内容（JSON 格式字符串） |
+| `parent_id` | string | 父元素 ID |
+| `children` | []string | 子元素 ID 列表 |
+| `created_by` | string | 创建者用户 ID |
+| `created_at` | uint64 | 创建时间戳（毫秒） |
+| `updated_by` | string | 最后更新者用户 ID |
+| `updated_at` | uint64 | 最后更新时间戳（毫秒） |
+
+**调用示例（新增页面）**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "pages": [
+    {
+      "title": "第一章：项目背景"
+    }
+  ]
+}
+```
+
+**调用示例（在页面中添加标题和文本）**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "parent_id": "page_element_id",
+  "headings": [
+    {
+      "rich_text": {
+        "text": "项目目标",
+        "formats": {
+          "bold": true
+        }
+      },
+      "level": "LEVEL_1"
+    }
+  ],
+  "texts": [
+    {
+      "rich_text": {
+        "text": "本项目旨在提升用户体验，优化核心流程。"
+      }
+    }
+  ]
+}
+```
+
+**调用示例（添加待办事项）**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "parent_id": "page_element_id",
+  "tasks": [
+    {
+      "rich_text": {
+        "text": "完成需求评审"
+      },
+      "reminder": {
+        "due_time": 1720072890000,
+        "reminder_time": 30
+      }
+    },
+    {
+      "rich_text": {
+        "text": "提交设计稿"
+      }
+    }
+  ]
+}
+```
+
+**调用示例（添加图片）**：
+
+> ⚠️ 需先调用 `upload_image` 上传图片获取 `image_id`，再传入此处。
+
+```json
+{
+  "file_id": "your_file_id",
+  "parent_id": "page_element_id",
+  "image": [
+    {
+      "image_id": "从 upload_image 返回的 image_id",
+      "width": 800,
+      "height": 600
+    }
+  ]
+}
+```
+
+---
+
+### smartcanvas.get_element_info
+
+**功能**：批量查询指定元素的详细信息，支持同时查询多个元素。
+
+**使用场景**：
+- 查询特定元素的内容和属性
+- 获取元素的父子关系
+- 验证元素是否存在及其当前状态
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 文档的唯一标识符 |
+| `element_ids` | []string | ✅ | 查询元素 ID 列表，支持批量查询多个元素 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `element_infos` | array | 查询到的元素信息列表，详见 ElementInfo 结构 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "element_ids": ["element_id_001", "element_id_002"]
+}
+```
+
+**返回示例**：
+
+```json
+{
+  "element_infos": [
+    {
+      "id": "element_id_001",
+      "version": 3,
+      "type": "Page",
+      "element": "{\"title\": \"第一章：项目背景\"}",
+      "parent_id": "",
+      "children": ["element_id_003", "element_id_004"],
+      "created_by": "user_001",
+      "created_at": 1720000000000,
+      "updated_by": "user_001",
+      "updated_at": 1720086400000
+    }
+  ],
+  "error": "",
+  "trace_id": "trace_xyz"
+}
+```
+
+---
+
+### smartcanvas.get_page_info
+
+**功能**：查询指定页面内的所有元素，支持分页获取。
+
+**使用场景**：
+- 读取某个页面下的所有内容（标题、文本、待办事项）
+- 分页获取内容较多的页面
+- 遍历文档内容进行分析
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 文档的唯一标识符 |
+| `page_id` | string | ✅ | 要查询的页面元素 ID |
+| `cursor` | []CursorItem | | 分页游标，首次查询不传，后续查询使用上次响应返回的 cursor |
+
+**CursorItem 结构**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 游标 ID |
+| `index` | uint32 | 游标索引位置 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `element_infos` | array | 页面内的元素信息列表 |
+| `cursor` | []CursorItem | 下次分页的 cursor 信息 |
+| `is_over` | bool | 是否已查询完所有内容，为 true 表示分页结束 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例（首次查询）**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "page_id": "page_element_id"
+}
+```
+
+**调用示例（分页继续查询）**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "page_id": "page_element_id",
+  "cursor": [
+    { "id": "cursor_id_001", "index": 20 }
+  ]
+}
+```
+
+---
+
+### smartcanvas.get_top_level_pages
+
+**功能**：查询文档的所有顶层页面列表，返回根节点下的直接子页面。
+
+**使用场景**：
+- 获取文档的目录结构（顶层页面列表）
+- 遍历文档所有页面
+- 在操作前先了解文档的页面组织结构
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 文档的唯一标识符 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `top_level_pages` | array | 顶层页面列表，包含所有顶级页面的基本信息 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id"
+}
+```
+
+**返回示例**：
+
+```json
+{
+  "top_level_pages": [
+    {
+      "id": "page_id_001",
+      "type": "Page",
+      "element": "{\"title\": \"第一章：项目背景\"}",
+      "children": ["element_id_003", "element_id_004"]
+    },
+    {
+      "id": "page_id_002",
+      "type": "Page",
+      "element": "{\"title\": \"第二章：技术方案\"}",
+      "children": ["element_id_005"]
+    }
+  ],
+  "error": "",
+  "trace_id": "trace_xyz"
+}
+```
+
+---
+
+### smartcanvas.update_element
+
+**功能**：批量修改元素内容，支持同时更新多个元素的文本、格式、标题级别等属性。
+
+**使用场景**：
+- 修改页面标题
+- 更新文本内容或格式（加粗、颜色等）
+- 修改标题级别
+- 更新待办事项内容或截止时间
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 文档的唯一标识符 |
+| `updates` | []UpdateElementRequest | ✅ | 元素更新请求列表，支持批量更新多个元素 |
+
+**UpdateElementRequest 结构**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `element_id` | string | ✅ | 要更新的元素 ID |
+| `page` | Page | | 更新页面元素（修改标题） |
+| `text` | Text | | 更新文本元素 |
+| `task` | Task | | 更新待办事项元素 |
+| `heading` | Heading | | 更新标题元素 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `updated_elements` | array | 更新成功的元素信息列表 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例（修改页面标题）**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "updates": [
+    {
+      "element_id": "page_element_id",
+      "page": {
+        "title": "第一章：项目背景（已更新）"
+      }
+    }
+  ]
+}
+```
+
+**调用示例（修改文本内容和格式）**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "updates": [
+    {
+      "element_id": "text_element_id",
+      "text": {
+        "rich_text": {
+          "text": "这是更新后的文本内容，支持富文本格式。",
+          "formats": {
+            "bold": true,
+            "text_color": "COLOR_BLUE"
+          }
+        },
+        "block_color": "BG_COLOR_LIGHT_BLUE"
+      }
+    }
+  ]
+}
+```
+
+**调用示例（修改标题级别）**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "updates": [
+    {
+      "element_id": "heading_element_id",
+      "heading": {
+        "rich_text": {
+          "text": "技术架构设计"
+        },
+        "level": "LEVEL_2"
+      }
+    }
+  ]
+}
+```
+
+**调用示例（更新待办事项截止时间）**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "updates": [
+    {
+      "element_id": "task_element_id",
+      "task": {
+        "rich_text": {
+          "text": "完成代码评审"
+        },
+        "reminder": {
+          "due_time": 1720159290000,
+          "reminder_time": 60
+        }
+      }
+    }
+  ]
+}
+```
+
+---
+
+### smartcanvas.delete_element
+
+**功能**：批量删除元素，支持同时删除多个指定元素。
+
+**使用场景**：
+- 删除不再需要的页面或内容块
+- 清理文档中的冗余内容
+- 批量删除多个元素
+
+> ⚠️ **注意**：删除 Page 元素时，其下的所有子元素（Text、Heading、Task）也会被一并删除，请谨慎操作。
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 文档的唯一标识符 |
+| `element_ids` | []string | ✅ | 需要批量删除的元素 ID 列表 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | string | 错误信息，操作失败时返回 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "element_ids": ["element_id_001", "element_id_002"]
+}
+```
+
+---
+
+## 追加内容
+
+### smartcanvas.append_insert_smartcanvas_by_markdown 追加
+
+**功能**：通过 Markdown 文本向已有文档追加内容，内容追加到文档末尾。
+
+**使用场景**：
+- 快速向文档末尾追加大段 Markdown 内容
+- 批量导入 Markdown 格式的文档内容
+- 在已有文档基础上继续补充内容
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 文档的唯一标识符 |
+| `markdown` | string | ✅ | UTF-8 格式的 Markdown 文本，特殊字符不需要转义 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | string | 错误信息，操作失败时返回 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "markdown": "## 新增章节\n\n这是通过 Markdown 追加的内容。\n\n- 支持列表\n- 支持**加粗**\n- 支持`代码`"
+}
+```
+
+---
+
+## 枚举值参考
+
+### 标题级别（HeadingLevel）
+
+| 枚举值 | 说明 |
+|--------|------|
+| `LEVEL_1` | 一级标题（最大） |
+| `LEVEL_2` | 二级标题 |
+| `LEVEL_3` | 三级标题 |
+| `LEVEL_4` | 四级标题 |
+| `LEVEL_5` | 五级标题 |
+| `LEVEL_6` | 六级标题（最小） |
+
+### 文本颜色（TextColor）
+
+| 枚举值 | 颜色 |
+|--------|------|
+| `COLOR_GREY` | 灰色 |
+| `COLOR_BLUE` | 蓝色 |
+| `COLOR_SKY_BLUE` | 天蓝色 |
+| `COLOR_GREEN` | 绿色 |
+| `COLOR_YELLOW` | 黄色 |
+| `COLOR_ORANGE` | 橙色 |
+| `COLOR_RED` | 红色 |
+| `COLOR_ROSE_RED` | 玫瑰红 |
+| `COLOR_PURPLE` | 紫色 |
+
+### 背景颜色（BackgroundColor）
+
+| 枚举值 | 颜色 |
+|--------|------|
+| `BG_COLOR_GREY` | 灰色 |
+| `BG_COLOR_LIGHT_GREY` | 浅灰色 |
+| `BG_COLOR_DARK` | 深色 |
+| `BG_COLOR_LIGHT_BLUE` | 浅蓝色 |
+| `BG_COLOR_BLUE` | 蓝色 |
+| `BG_COLOR_LIGHT_SKY_BLUE` | 浅天蓝色 |
+| `BG_COLOR_SKY_BLUE` | 天蓝色 |
+| `BG_COLOR_LIGHT_GREEN` | 浅绿色 |
+| `BG_COLOR_GREEN` | 绿色 |
+| `BG_COLOR_LIGHT_YELLOW` | 浅黄色 |
+| `BG_COLOR_YELLOW` | 黄色 |
+| `BG_COLOR_LIGHT_ORANGE` | 浅橙色 |
+| `BG_COLOR_ORANGE` | 橙色 |
+| `BG_COLOR_LIGHT_RED` | 浅红色 |
+| `BG_COLOR_RED` | 红色 |
+| `BG_COLOR_LIGHT_ROSE_RED` | 浅玫瑰红 |
+| `BG_COLOR_ROSE_RED` | 玫瑰红 |
+| `BG_COLOR_LIGHT_PURPLE` | 浅紫色 |
+| `BG_COLOR_PURPLE` | 紫色 |
+
+---
+
+## 元素类型详细说明
+
+### Page（页面）
+
+页面是文档的基本容器单元，所有内容元素（Text、Heading、Task）都必须挂载在 Page 下。
+
+```json
+{
+  "title": "页面标题（仅支持纯文本）"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `title` | string | | 页面标题，仅支持纯文本，不支持富文本格式 |
+
+---
+
+### Text（文本）
+
+普通文本块，支持富文本格式和背景颜色。
+
+```json
+{
+  "rich_text": {
+    "text": "文本内容",
+    "formats": {
+      "bold": false,
+      "italic": false,
+      "under_line": false,
+      "strike": false,
+      "text_color": "COLOR_BLUE",
+      "background_color": "BG_COLOR_LIGHT_YELLOW",
+      "text_link": {
+        "link_url": "https://example.com"
+      }
+    }
+  },
+  "block_color": "BG_COLOR_LIGHT_GREY"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `rich_text` | RichText | ✅ | 富文本内容 |
+| `block_color` | BackgroundColor | | 文本块背景颜色 |
+
+---
+
+### Heading（标题）
+
+标题块，支持 1-6 级标题，支持富文本格式和背景颜色。
+
+```json
+{
+  "rich_text": {
+    "text": "标题内容",
+    "formats": {
+      "bold": true
+    }
+  },
+  "level": "LEVEL_1",
+  "block_color": "BG_COLOR_LIGHT_BLUE"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `rich_text` | RichText | ✅ | 富文本内容 |
+| `level` | HeadingLevel | ✅ | 标题级别，枚举值：LEVEL_1 ~ LEVEL_6 |
+| `block_color` | BackgroundColor | | 标题块背景颜色 |
+
+---
+
+### Image（图片）
+
+图片块，需先通过 `upload_image` 工具上传图片获取 `image_id`，再插入到文档中。
+
+```json
+{
+  "image_id": "从 upload_image 返回的 image_id",
+  "width": 800,
+  "height": 600
+}
+```
+
+| 字段         | 类型 | 必填 | 说明 |
+|------------|------|------|------|
+| `image_id` | string | ✅ | 图片 ID，通过 `upload_image` 工具上传图片后获取，有效期为一天 |
+| `width`    | float | | 图片显示宽度（像素），不填则使用图片原始宽度 |
+| `height`   | float | | 图片显示高度（像素），不填则使用图片原始高度 |
+
+> ⚠️ **注意**：`image_id` 有效期为一天，请在获取后及时使用。
+
+---
+
+### Task（待办事项）
+
+待办事项块，支持设置截止时间和提醒。
+
+```json
+{
+  "rich_text": {
+    "text": "待办事项内容"
+  },
+  "reminder": {
+    "due_time": 1720072890000,
+    "reminder_time": 30
+  }
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `rich_text` | RichText | ✅ | 待办事项文本内容 |
+| `reminder` | Reminder | | 提醒设置 |
+
+**Reminder 结构**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `due_time` | uint64 | 任务截止时间，Unix 时间戳（毫秒），例如 `1720072890000` |
+| `reminder_time` | int32 | 提前提醒时间间隔（分钟） |
+
+---
+
+### RichText（富文本）
+
+富文本对象，包含文本内容和格式设置。
+
+```json
+{
+  "text": "文本内容",
+  "formats": {
+    "bold": true,
+    "italic": false,
+    "under_line": true,
+    "strike": false,
+    "text_color": "COLOR_RED",
+    "background_color": "BG_COLOR_LIGHT_YELLOW",
+    "text_link": {
+      "link_url": "https://docs.qq.com"
+    }
+  }
+}
+```
+
+**Formats 格式说明**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `bold` | bool | 粗体 |
+| `italic` | bool | 斜体 |
+| `under_line` | bool | 下划线 |
+| `strike` | bool | 删除线 |
+| `text_color` | TextColor | 文本颜色，枚举值见上方 |
+| `background_color` | BackgroundColor | 背景颜色，枚举值见上方 |
+| `text_link` | TextLink | 文本链接，包含 `link_url` 字段 |
+
+---
+
+## 典型工作流示例
+
+### 创建通用文档（推荐方式）
+
+**📖 参考文档：** `mdx_references.md` — create_smartcanvas_by_mdx
+
+```
+1. 阅读 mdx_references.md 了解 MDX 组件规范
+2. 按规范生成包含 Frontmatter 和 MDX 组件的内容
+3. 对照 mdx_references 逐条自校验，确保格式合规
+4. 调用 create_smartcanvas_by_mdx 创建文档
+5. 从返回结果中获取 file_id 和 url
+```
+
+### 编辑已有文档（智能文档 smartcanvas）
+
+```
+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
+```
+
+### 工作流一：创建结构化文档
+
+```
+步骤 1：创建文档
+  → create_smartcanvas_by_mdx（创建文档，获取 file_id）
+
+步骤 2：查询顶层页面
+  → smartcanvas.get_top_level_pages（获取已有页面的 page_id）
+
+步骤 3：在页面中添加内容
+  → smartcanvas.create_smartcanvas_element（传入 parent_id=page_id，添加标题和文本）
+
+步骤 4：继续追加内容
+  → smartcanvas.create_smartcanvas_element（追加更多页面或内容块）
+```
+
+### 读取文档内容
+
+```
+步骤 1：获取顶层页面列表
+  → smartcanvas.get_top_level_pages（获取所有顶层页面）
+
+步骤 2：逐页读取内容
+  → smartcanvas.get_page_info（传入 page_id，获取页面内所有元素）
+  → 若 is_over=false，继续传入 cursor 获取下一页
+
+步骤 3：（可选）查询特定元素详情
+  → smartcanvas.get_element_info（传入 element_ids，获取元素详细信息）
+```
+
+### 工作流三：更新文档内容
+
+```
+步骤 1：获取顶层页面
+  → smartcanvas.get_top_level_pages（获取页面列表）
+
+步骤 2：读取页面内容，找到目标元素
+  → smartcanvas.get_page_info（获取页面内元素及其 element_id）
+
+步骤 3：更新目标元素
+  → smartcanvas.update_element（传入 element_id 和新内容）
+```
+
+### 工作流四：追加内容到已有文档
+
+```
+步骤 1：获取文档 file_id
+  → manage.search_file（搜索文档，获取文档id）
+
+步骤 2：追加 Markdown 内容
+  → smartcanvas.append_insert_smartcanvas_by_markdown（传入 file_id 和 markdown 内容）
+
+步骤 3：（可选）精细化追加结构化元素
+  → smartcanvas.get_top_level_pages（获取最新页面列表）
+  → smartcanvas.create_smartcanvas_element（在指定页面后追加元素）
+```
+
+### 工作流五：清理文档内容
+
+```
+步骤 1：获取顶层页面
+  → smartcanvas.get_top_level_pages
+
+步骤 2：读取页面内容，找到要删除的元素
+  → smartcanvas.get_page_info（获取 element_id 列表）
+
+步骤 3：批量删除元素
+  → smartcanvas.delete_element（传入 element_ids 数组）
+```
+
+---
+
+## 注意事项
+
+- 所有操作都需要先获取 `file_id`，可通过 `manage.search_file` 搜索文档获取，或在创建文档时从返回结果中获取
+- 操作元素前，建议先调用 `smartcanvas.get_top_level_pages` 了解文档结构，再调用 `smartcanvas.get_page_info` 获取具体元素 ID
+- **元素挂载约束**：`Text`、`Heading`、`Task`、`Image` 必须挂载在 `Page` 下，`parent_id` 必须为 Page 类型元素 ID
+- **分页查询**：`smartcanvas.get_page_info` 使用 `cursor` 分页，`is_over=true` 表示已获取全部内容
+- **删除注意**：删除 Page 元素时，其下所有子元素也会被一并删除
--- a/skills/tencent-docs/references/smartsheet_references.md
+++ b/skills/tencent-docs/references/smartsheet_references.md
@@ -0,0 +1,1052 @@
+# 智能表格（SmartSheet）工具完整参考文档
+
+腾讯文档智能表格（SmartSheet）提供了一套完整的表格操作 API，支持对工作表、视图、字段、记录进行增删改查操作。
+
+---
+
+## 目录
+
+- [概念说明](#概念说明)
+- [工作表（SubSheet）操作](#工作表subsheet操作)
+  - [smartsheet.list_tables - 列出工作表](#smartsheetlist_tables)
+  - [smartsheet.add_table - 新增工作表](#smartsheetadd_table)
+  - [smartsheet.delete_table - 删除工作表](#smartsheetdelete_table)
+- [视图（View）操作](#视图view操作)
+  - [smartsheet.list_views - 列出视图](#smartsheetlist_views)
+  - [smartsheet.add_view - 新增视图](#smartsheetadd_view)
+  - [smartsheet.delete_view - 删除视图](#smartsheetdelete_view)
+- [字段（Field）操作](#字段field操作)
+  - [smartsheet.list_fields - 列出字段](#smartsheetlist_fields)
+  - [smartsheet.add_fields - 新增字段](#smartsheetadd_fields)
+  - [smartsheet.update_fields - 更新字段](#smartsheetupdate_fields)
+  - [smartsheet.delete_fields - 删除字段](#smartsheetdelete_fields)
+- [记录（Record）操作](#记录record操作)
+  - [smartsheet.list_records - 列出记录](#smartsheetlist_records)
+  - [smartsheet.add_records - 新增记录](#smartsheetadd_records)
+  - [smartsheet.update_records - 更新记录](#smartsheetupdate_records)
+  - [smartsheet.delete_records - 删除记录](#smartsheetdelete_records)
+- [枚举值参考](#枚举值参考)
+- [字段值格式参考](#字段值格式参考)
+- [典型工作流示例](#典型工作流示例)
+
+---
+
+## 概念说明
+
+| 概念 | 说明 |
+|------|------|
+| `file_id` | 智能表格文档的唯一标识符，每个文档有唯一的 file_id |
+| `sheet_id` | 工作表 ID，一个智能表格文档可包含多个工作表 |
+| `view_id` | 视图 ID，每个工作表可有多个视图（网格视图、看板视图等） |
+| `field_id` | 字段 ID，对应表格的列 |
+| `record_id` | 记录 ID，对应表格的行 |
+
+**层级关系**：`file_id（文档）` → `sheet_id（工作表）` → `view_id（视图）` / `field_id（字段）` / `record_id（记录）`
+
+---
+
+## 工作表（SubSheet）操作
+
+### smartsheet.list_tables
+
+**功能**：列出文档下的所有工作表，返回工作表基本信息列表。
+
+**使用场景**：
+- 查看一个智能表格文档中有哪些工作表
+- 获取 sheet_id 以便后续操作字段、记录、视图
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+
+**返回字段**：
+
+| 字段                    | 类型 | 说明 |
+|-----------------------|------|------|
+| `sheets`              | array | 工作表列表 |
+| `sheets[].sheet_id`   | string | 工作表唯一标识符 |
+| `sheets[].title`      | string | 工作表名称 |
+| `sheets[].is_visible` | bool | 工作表可见性 |
+| `error`               | string | 错误信息，操作失败时返回 |
+| `trace_id`            | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id"
+}
+```
+
+**返回示例**：
+
+```json
+{
+  "sheets": [
+    {
+      "sheet_id": "sheet_abc123",
+      "title": "任务列表",
+      "is_visible": true
+    },
+    {
+      "sheet_id": "sheet_def456",
+      "title": "已归档",
+      "is_visible": false
+    }
+  ],
+  "error": "",
+  "trace_id": "trace_xyz"
+}
+```
+
+---
+
+### smartsheet.add_table
+
+**功能**：在文档中新增工作表，支持设置工作表名称和初始配置。
+
+**使用场景**：
+- 在已有智能表格文档中添加新的工作表（如新增"2024年Q2"工作表）
+- 按业务模块拆分数据到不同工作表
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `properties` | object | ✅ | 工作表属性配置 |
+| `properties.sheet_id` | string | ✅ | 工作表名称（注意：此字段实际含义为工作表名称） |
+| `properties.title` | string | | 工作表标题 |
+| `properties.index` | uint32 | | 工作表下标（位置） |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `properties` | object | 新创建工作表的属性信息 |
+| `properties.sheet_id` | string | 工作表名称 |
+| `properties.title` | string | 工作表标题 |
+| `properties.index` | uint32 | 工作表下标 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "properties": {
+    "sheet_id": "新工作表",
+    "title": "2024年Q2数据",
+    "index": 1
+  }
+}
+```
+
+---
+
+### smartsheet.delete_table
+
+**功能**：删除指定的工作表。
+
+**使用场景**：
+- 删除不再需要的工作表
+- 清理测试数据工作表
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 要删除的工作表 ID |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | string | 错误信息，操作失败时返回 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123"
+}
+```
+
+---
+
+## 视图（View）操作
+
+### smartsheet.list_views
+
+**功能**：列出工作表下的所有视图，返回视图基本信息和配置。
+
+**使用场景**：
+- 查看工作表有哪些视图（网格视图、看板视图）
+- 获取 view_id 以便按视图筛选记录或字段
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `view_ids` | []string | | 需要查询的视图 ID 数组，不填则返回全部 |
+| `offset` | uint32 | | 分页查询偏移量，默认 0 |
+| `limit` | uint32 | | 分页大小，最大 100 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `views` | array | 视图列表 |
+| `views[].view_id` | string | 视图唯一标识符 |
+| `views[].view_name` | string | 视图名称 |
+| `views[].view_type` | uint32 | 视图类型，枚举值见下方 |
+| `total` | uint32 | 符合条件的视图总数 |
+| `hasMore` | bool | 是否还有更多项 |
+| `next` | uint32 | 下一页偏移量 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**视图类型枚举值**：
+
+| 值 | 说明 |
+|----|------|
+| `1` | 网格视图（grid） |
+| `2` | 看板视图（kanban） |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "offset": 0,
+  "limit": 20
+}
+```
+
+---
+
+### smartsheet.add_view
+
+**功能**：在工作表中新增视图，支持自定义视图名称和类型。
+
+**使用场景**：
+- 为工作表创建看板视图，按状态分组展示任务
+- 创建多个网格视图，分别展示不同筛选条件的数据
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `view_title` | string | ✅ | 视图标题 |
+| `view_type` | uint32 | | 视图类型：1-网格视图，2-看板视图 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `view_id` | string | 新创建的视图 ID |
+| `view_title` | string | 视图标题 |
+| `view_type` | uint32 | 视图类型 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "view_title": "按状态分组",
+  "view_type": 2
+}
+```
+
+---
+
+### smartsheet.delete_view
+
+**功能**：删除指定的视图，支持批量删除多个视图。
+
+**使用场景**：
+- 删除不再使用的视图
+- 批量清理多余视图
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `view_ids` | []string | ✅ | 要删除的视图 ID 列表 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "view_ids": ["view_id1", "view_id2"]
+}
+```
+
+---
+
+## 字段（Field）操作
+
+### smartsheet.list_fields
+
+**功能**：列出工作表的所有字段，返回字段基本信息和类型配置。
+
+**使用场景**：
+- 查看工作表有哪些列（字段）及其类型
+- 获取 field_id 以便后续更新或删除字段
+- 在写入记录前，先了解字段结构和类型
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `view_id` | string | | 视图 ID，按视图筛选字段 |
+| `field_ids` | []string | | 指定字段 ID 数组 |
+| `field_titles` | []string | | 指定字段标题数组 |
+| `offset` | uint32 | | 偏移量，初始值为 0 |
+| `limit` | uint32 | | 分页大小，最大 100；不填或为 0 时，总数 >100 返回 100 条，否则返回全部 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `total` | uint32 | 符合条件的字段总数 |
+| `has_more` | bool | 是否还有更多项 |
+| `next` | uint32 | 下一页偏移量 |
+| `fields` | array | 字段列表，详见 FieldInfo 结构 |
+
+**FieldInfo 结构**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `field_id` | string | 字段唯一 ID |
+| `field_title` | string | 字段标题（列名） |
+| `field_type` | uint32 | 字段类型，枚举值见下方 |
+| `property_*` | object | 字段属性，根据 field_type 不同而不同 |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123"
+}
+```
+
+---
+
+### smartsheet.add_fields
+
+**功能**：批量新增字段（列），支持同时添加多个不同类型的字段。
+
+**使用场景**：
+- 为工作表添加新列，如"优先级"（单选）、"截止日期"（日期）、"负责人"（用户）
+- 初始化工作表结构
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `fields` | []FieldInfo | ✅ | 要添加的字段列表 |
+
+**FieldInfo 参数说明**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `field_title` | string | ✅ | 字段标题（列名） |
+| `field_type` | uint32 | ✅ | 字段类型，枚举值见下方 |
+| `property_text` | object | | 文本类型属性（无需额外配置） |
+| `property_number` | object | | 数字类型属性 |
+| `property_checkbox` | object | | 复选框类型属性 |
+| `property_date_time` | object | | 日期时间类型属性 |
+| `property_url` | object | | 超链接类型属性 |
+| `property_select` | object | | 多选类型属性 |
+| `property_single_select` | object | | 单选类型属性 |
+| `property_progress` | object | | 进度类型属性 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `fields` | array | 添加成功的字段列表（含 field_id） |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例（添加多种类型字段）**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "fields": [
+      {
+        "field_title": "任务名称",
+        "field_type": 1,
+        "property_text": {}
+      },
+      {
+        "field_title": "优先级",
+        "field_type": 17,
+        "property_single_select": {
+          "options": [
+            { "text": "高", "style": 1 },
+            { "text": "中", "style": 3 },
+            { "text": "低", "style": 4 }
+          ]
+        }
+      },
+      {
+        "field_title": "截止日期",
+        "field_type": 4,
+        "property_date_time": {
+          "format": "yyyy-mm-dd",
+          "auto_fill": false
+        }
+      },
+      {
+        "field_title": "完成进度",
+        "field_type": 14,
+        "property_progress": {
+          "decimal_places": 0
+        }
+      },
+      {
+        "field_title": "是否完成",
+        "field_type": 3,
+        "property_checkbox": {
+          "checked": false
+        }
+      }
+    ]
+}
+```
+
+---
+
+### smartsheet.update_fields
+
+**功能**：批量更新字段属性，支持修改字段名称和配置信息。
+
+**使用场景**：
+- 修改字段标题（列名）
+- 更新单选/多选字段的选项列表
+- 修改数字字段的精度配置
+
+> ⚠️ **注意**：`field_type`（字段类型）不允许被更新，但更新时必须传入原字段类型值。
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `fields` | []FieldInfo | ✅ | 要更新的字段列表，必须包含 field_id |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `fields` | array | 更新成功的字段列表 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例（修改字段标题和选项）**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "fields": [
+      {
+        "field_id": "field_id_001",
+        "field_title": "任务状态",
+        "field_type": 17,
+        "property_single_select": {
+          "options": [
+            { "text": "待处理", "style": 7 },
+            { "text": "进行中", "style": 3 },
+            { "text": "已完成", "style": 4 },
+            { "text": "已取消", "style": 1 }
+          ]
+        }
+      }
+    ]
+}
+```
+
+---
+
+### smartsheet.delete_fields
+
+**功能**：批量删除字段（列），支持同时删除多个字段。
+
+**使用场景**：
+- 删除不再需要的列
+- 清理冗余字段
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `field_ids` | []string | ✅ | 要删除的字段 ID 数组 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "field_ids": ["field_id_001", "field_id_002"]
+}
+```
+
+---
+
+## 记录（Record）操作
+
+### smartsheet.list_records
+
+**功能**：分页列出工作表记录（行），支持排序和按字段筛选。
+
+**使用场景**：
+- 读取工作表中的数据
+- 按特定字段排序查看数据
+- 分页获取大量数据
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `view_id` | string | | 视图 ID，按视图筛选记录 |
+| `record_ids` | []string | | 指定记录 ID 数组，精确查询 |
+| `field_titles` | []string | | 只返回指定字段标题的值，不填则返回全部字段 |
+| `sort` | []Sort | | 排序配置 |
+| `offset` | uint32 | | 偏移量，初始值为 0 |
+| `limit` | uint32 | | 分页大小，最大 100；不填或为 0 时，总数 >100 返回 100 条，否则返回全部 |
+
+**Sort 排序配置**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `field_title` | string | ✅ | 需要排序的字段标题 |
+| `desc` | bool | | 是否降序，默认 false（升序） |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `total` | uint32 | 符合条件的记录总数 |
+| `has_more` | bool | 是否还有更多项 |
+| `next` | uint32 | 下一页偏移量 |
+| `records` | array | 记录列表，详见 RecordInfo 结构 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**RecordInfo 结构**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `record_id` | string | 记录唯一 ID |
+| `field_values` | map | 字段值映射，key 为字段标题，value 为字段值 |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "field_titles": ["任务名称", "优先级", "截止日期"],
+  "sort": [
+    { "field_title": "截止日期", "desc": false }
+  ],
+  "offset": 0,
+  "limit": 50
+}
+```
+
+---
+
+### smartsheet.add_records
+
+**功能**：批量添加记录（行），支持同时添加多条记录数据。
+
+**使用场景**：
+- 批量导入数据到工作表
+- 添加新任务、新条目
+- 从其他数据源同步数据
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `records` | []AddRecord | ✅ | 要添加的记录列表 |
+
+**AddRecord 结构**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `field_values` | map | ✅ | 字段值映射，key 为字段标题，value 为字段值（格式见下方） |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `records` | array | 添加成功的记录列表（含 record_id） |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "records": [
+      {
+        "field_values": {
+          "任务名称": [{"text": "完成需求文档", "type": "text"}],
+          "优先级": [{"text": "高"}],
+          "截止日期": "1720000000000",
+          "完成进度": 30,
+          "是否完成": false
+        }
+      },
+      {
+        "field_values": {
+          "任务名称": [{"text": "代码评审", "type": "text"}],
+          "优先级": [{"text": "中"}],
+          "截止日期": "1720086400000",
+          "完成进度": 0,
+          "是否完成": false
+        }
+      }
+    ]
+}
+```
+
+---
+
+### smartsheet.update_records
+
+**功能**：批量更新记录，支持修改多条记录的字段值。
+
+**使用场景**：
+- 更新任务状态、进度
+- 修改记录中的某些字段值
+- 批量修改多条数据
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `records` | []RecordInfo | ✅ | 要更新的记录列表，必须包含 record_id |
+
+**RecordInfo 参数说明**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `record_id` | string | ✅ | 记录 ID，标识要更新哪条记录 |
+| `field_values` | map | ✅ | 要更新的字段值映射 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "records": [
+      {
+        "record_id": "record_id_001",
+        "field_values": {
+          "完成进度": 100,
+          "是否完成": true,
+          "优先级": [{"text": "高"}]
+        }
+      }
+    ]
+}
+```
+
+---
+
+### smartsheet.delete_records
+
+**功能**：批量删除记录（行），支持同时删除多条指定的记录。
+
+**使用场景**：
+- 删除已完成或过期的任务记录
+- 清理测试数据
+- 批量删除多条记录
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `record_ids` | []string | ✅ | 要删除的记录 ID 列表 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "record_ids": ["record_id_001", "record_id_002", "record_id_003"]
+}
+```
+
+---
+
+## 枚举值参考
+
+### 字段类型（field_type）
+
+| 枚举值 | 类型名称 | 对应 property 字段 | 说明 |
+|--------|---------|-------------------|------|
+| `1` | 文本 | `property_text` | 普通文本，无需额外配置 |
+| `2` | 数字 | `property_number` | 整数或浮点数 |
+| `3` | 复选框 | `property_checkbox` | 布尔值 true/false |
+| `4` | 日期 | `property_date_time` | 毫秒时间戳字符串 |
+| `5` | 图片 | `property_image` | 图片 ID 数组 |
+| `8` | 超链接 | `property_url` | URL 数组 |
+| `9` | 多选 | `property_select` | 选项数组（可多选） |
+| `10` | 创建人 | `property_user` | 系统自动填充，无需配置 |
+| `11` | 最后编辑人 | `property_modified_user` | 系统自动填充，无需配置 |
+| `12` | 创建时间 | `property_created_time` | 系统自动填充，无需配置 |
+| `13` | 最后编辑时间 | `property_modified_time` | 系统自动填充，无需配置 |
+| `14` | 进度 | `property_progress` | 整数或浮点数（百分比） |
+| `15` | 电话 | `property_phone_number` | 字符串，无需额外配置 |
+| `16` | 邮件 | `property_email` | 字符串，无需额外配置 |
+| `17` | 单选 | `property_single_select` | 选项数组（只能单选） |
+| `18` | 关联 | - | 关联其他记录，值为 record_id 字符串数组 |
+| `25` | 自动编号 | - | 系统自动生成编号，无需手动配置 |
+| `26` | 货币 | - | 浮点数，表示货币金额 |
+| `28` | 百分比 | - | 浮点数，如 0.75 表示 75% |
+
+### 视图类型（view_type）
+
+| 枚举值 | 说明 |
+|--------|------|
+| `1` | 网格视图（grid）- 传统表格形式 |
+| `2` | 看板视图（kanban）- 按列分组展示 |
+
+### 选项颜色（style）
+
+| 枚举值 | 颜色 |
+|--------|------|
+| `1` | 红色 |
+| `2` | 橘黄色 |
+| `3` | 蓝色 |
+| `4` | 绿色 |
+| `5` | 紫色 |
+| `6` | 粉色 |
+| `7` | 灰色 |
+| `8` | 白色 |
+
+### 超链接展示样式（UrlFieldProperty.type）
+
+| 枚举值 | 说明 |
+|--------|------|
+| `0` | 未知 |
+| `1` | 文字 |
+| `2` | 图标文字 |
+
+---
+
+## 字段值格式参考
+
+在 `add_records` 和 `update_records` 中，`field_values` 的 value 格式因字段类型而异：
+
+| 字段类型 | 值格式 | 示例                                                         |
+|---------|--------|------------------------------------------------------------|
+| 文本（1） | JSON Array of TextValue | `[{"text": "内容", "type": "text"}]`                         |
+| 数字（2） | number | `42` 或 `3.14`                                              |
+| 复选框（3） | bool | `true` 或 `false`                                           |
+| 日期（4） | string（毫秒时间戳） | `"1720000000000"`                                          |
+| 图片（5） | JSON Array of ImageIDValue | `[{"image_id": "图片id"}]`                                   |
+| 超链接（8） | JSON Array of UrlValue | `[{"text": "链接文字", "type": "url", "link": "https://..."}]` |
+| 多选（9） | JSON Array of OptionValue | `[{"text": "选项1"}, {"text": "选项2"}]`                       |
+| 进度（14） | number | `75` 或 `75.5`                                              |
+| 电话（15） | string | `"13800138000"`                                            |
+| 邮件（16） | string | `"user@example.com"`                                       |
+| 单选（17） | JSON Array of OptionValue（单个） | `[{"text": "选项文字"}]`                                       |
+| 关联（18） | array string | `["record_id_1", "record_id_2"]`                           |
+| 自动编号（25） | JSON(AutoNumberValue) | `{"seq": "1", "text": "编号内容"}`                             |
+| 货币（26） | double | `99.99`                                                    |
+| 百分比（28） | double | `0.75`（表示 75%）                                             |
+
+### TextValue 结构
+
+```json
+{
+  "text": "文本内容",
+  "type": "text"
+}
+```
+
+### UrlValue 结构
+
+```json
+{
+  "text": "链接显示文字",
+  "type": "url",
+  "link": "https://example.com"
+}
+```
+
+### OptionValue 结构
+
+```json
+{
+  "id": "选项ID（可选）",
+  "text": "选项文字",
+  "style": 3
+}
+```
+
+> ⚠️ **注意**：写入记录时，单选/多选字段的 `text` 必须与字段属性中已定义的选项文字完全匹配，否则可能写入失败。
+
+---
+
+## 字段属性（Property）详细说明
+
+### NumberFieldProperty（数字字段属性）
+
+```json
+{
+  "decimal_places": 2,
+  "use_separate": true
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `decimal_places` | uint32 | 小数点位数（精度） |
+| `use_separate` | bool | 是否使用千位符（如 1,000） |
+
+### CheckboxFieldProperty（复选框字段属性）
+
+```json
+{
+  "checked": false
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `checked` | bool | 新增记录时是否默认勾选 |
+
+### DateTimeFieldProperty（日期时间字段属性）
+
+```json
+{
+  "format": "yyyy-mm-dd",
+  "auto_fill": false
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `format` | string | 日期格式，支持格式见下方 |
+| `auto_fill` | bool | 新建记录时是否自动填充当前时间 |
+
+**支持的日期格式**：
+
+| 格式字符串 | 示例 |
+|-----------|------|
+| `yyyy"年"m"月"d"日"` | 2018 年 4 月 20 日 |
+| `yyyy-mm-dd` | 2018-04-20 |
+| `yyyy/m/d` | 2018/4/20 |
+| `m"月"d"日"` | 4 月 20 日 |
+| `[$-804]yyyy"年"m"月"d"日" dddd` | 2018 年 4 月 20 日 星期五 |
+| `yyyy"年"m"月"d"日" hh:mm` | 2018 年 4 月 20 日 14:00 |
+| `yyyy-mm-dd hh:mm` | 2018-04-20 14:00 |
+| `m/d/yyyy` | 4/20/2018 |
+| `d/m/yyyy` | 20/4/2018 |
+
+### UrlFieldProperty（超链接字段属性）
+
+```json
+{
+  "type": 1
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `type` | uint32 | 展示样式：0-未知，1-文字，2-图标文字 |
+
+### SelectFieldProperty（多选字段属性）
+
+```json
+{
+  "options": [
+    { "id": "opt_001", "text": "选项A", "style": 3 },
+    { "id": "opt_002", "text": "选项B", "style": 4 }
+  ],
+  "is_multiple": true,
+  "is_quick_add": false
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `options` | []Option | 选项列表 |
+| `is_multiple` | bool | 是否多选（系统参数，用户无需设置） |
+| `is_quick_add` | bool | 是否允许填写时新增选项（系统参数，用户无需设置） |
+
+### SingleSelectFieldProperty（单选字段属性）
+
+结构与 `SelectFieldProperty` 相同，但只允许单选。
+
+### ProgressFieldProperty（进度字段属性）
+
+```json
+{
+  "decimal_places": 0
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `decimal_places` | uint32 | 小数位数 |
+
+---
+
+## 典型工作流示例
+
+### 工作流一：从零创建表
+
+```
+步骤 1：获取文档的工作表列表
+  → smartsheet.list_tables（获取 sheet_id）
+
+步骤 2：为工作表添加字段
+  → smartsheet.add_fields（添加：任务名称、优先级、负责人、截止日期、状态、进度）
+
+步骤 3：批量添加任务记录
+  → smartsheet.add_records（写入多条任务数据）
+
+步骤 4：删除默认空行和默认列
+  → smartsheet.list_records（获取建表时自动生成的空行 record_id 列表）
+  → smartsheet.delete_records（传入空行 record_ids，批量删除默认空行）
+  → smartsheet.list_fields（获取建表时自动生成的默认列 field_id 列表）
+  → smartsheet.delete_fields（传入默认列 field_ids，批量删除默认列）
+
+步骤 5：（可选）创建看板视图
+  → smartsheet.add_view（view_type=2，按状态分组）
+```
+
+### 工作流二：查询并更新任务状态
+
+```
+步骤 1：列出工作表
+  → smartsheet.list_tables（获取 sheet_id）
+
+步骤 2：查询记录
+  → smartsheet.list_records（获取 record_id 和当前字段值）
+
+步骤 3：更新指定记录
+  → smartsheet.update_records（传入 record_id 和新的字段值）
+```
+
+### 工作流三：读取数据并分析
+
+```
+步骤 1：列出工作表
+  → smartsheet.list_tables
+
+步骤 2：了解字段结构
+  → smartsheet.list_fields（了解有哪些列及其类型）
+
+步骤 3：分页读取所有记录
+  → smartsheet.list_records（offset=0, limit=100）
+  → 若 has_more=true，继续请求下一页（offset=100）
+
+步骤 4：处理数据
+  → 根据 field_values 中的数据进行统计分析
+```
+
+### 工作流四：清理过期数据
+
+```
+步骤 1：列出工作表
+  → smartsheet.list_tables
+
+步骤 2：查询需要删除的记录
+  → smartsheet.list_records（获取目标 record_id 列表）
+
+步骤 3：批量删除记录
+  → smartsheet.delete_records（传入 record_ids 数组）
+```
+
+---
+
+> 📌 **提示**：所有操作都需要先获取 `file_id`（智能表格文档 ID）和 `sheet_id`（工作表 ID）。
+> 可通过 `manage.search_file` 搜索文档获取 `file_id`，再通过 `smartsheet.list_tables` 获取 `sheet_id`。
+
+
+## 注意事项
+
+- **前置条件**：所有 smartsheet.* 工具都需要 `file_id` 和 `sheet_id`，操作前先调用 `smartsheet.list_tables` 获取 sheet_id
+- **图片字段写入**：向图片类型字段（field_type=5）写入数据时，需先调用 `upload_image` 工具上传图片获取 `image_id`，再以 `[{"image_id": "xxx"}]` 格式填入字段值
+- **字段类型不可变**：`update_fields` 时 `field_type` 不能修改，但必须传入原值；支持的字段类型详见字段类型枚举表
+- **记录字段值格式**：不同字段类型的值格式不同，详见上方"字段值格式参考"章节
--- a/skills/tencent-docs/references/space_references.md
+++ b/skills/tencent-docs/references/space_references.md
@@ -0,0 +1,282 @@
+# 知识库空间 API 参考
+
+本文件包含腾讯文档 MCP 知识库空间相关工具的 API 说明，包括空间管理和节点操作。
+
+---
+
+## 通用类型说明
+
+### node_type 枚举值
+
+| 值 | 说明 |
+|---|---|
+| wiki_folder | 文件夹 |
+| wiki_tdoc | 在线文档（请求时使用） |
+| wiki_file | 在线文档（返回值中使用） |
+| link | 链接 |
+| resource | 资源文件 |
+
+### doc_type 枚举值
+
+| 值 | 说明 |
+|---|---|
+| word | 文字处理文档 |
+| excel | 电子表格 |
+| form | 收集表 |
+| slide | 幻灯片 |
+| smartcanvas | 智能文档 |
+| smartsheet | 智能表格 |
+| mind | 思维导图 |
+| flowchart | 流程图 |
+
+### NodeInfo 节点信息结构
+
+```json
+{
+  "node_id": "节点 ID，同时也是 file_id",
+  "title": "节点标题",
+  "node_type": "节点类型",
+  "has_child": true,
+  "doc_type": "文档类型（仅 wiki_file 有效）",
+  "url": "访问链接"
+}
+```
+
+### StringMatrix 表格数据结构
+
+```json
+{
+  "texts": {
+    "rows": [
+      {"values": ["单元格1", "单元格2"]},
+      {"values": ["单元格3", "单元格4"]}
+    ]
+  }
+}
+```
+
+数据从 A1 单元格开始，按行列顺序填充。
+
+---
+
+## 工具列表
+
+| 工具名称 | 功能说明 |
+|---------|---------|
+| query_space_list | 获取知识库空间列表 |
+| create_space | 创建新的知识库空间 |
+| query_space_node | 查询空间内节点列表 |
+| create_space_node | 在空间中创建新节点（文件夹、文档或链接） |
+| delete_space_node | 删除空间中的指定节点 |
+
+---
+
+## 工具详细说明
+
+### 1. query_space_list
+
+#### 功能说明
+获取知识库空间列表，支持按不同方式排序和分页查询。
+
+#### 调用示例
+```json
+{
+  "num": 0,
+  "order_by": 1,
+  "query_by": 1,
+  "descending": true
+}
+```
+
+#### 参数说明
+- `num` (uint32, 可选): 分页页码，从0开始，每页最多返回100个空间
+- `order_by` (uint32, 可选): 排序方式（1-按最近预览时间排序，2-按最近编辑时间排序，3-按创建时间排序）
+- `query_by` (uint32, 可选): 查询范围（0-查询全部空间（默认），1-仅查询我创建的空间，2-仅查询我加入的空间）
+- `descending` (bool, 可选): 是否降序排列，true-降序（最新在前），false-升序，默认为true
+
+#### 返回值说明
+```json
+{
+  "spaces": [
+    {
+      "space_id": "space_1234567890",
+      "title": "我的知识库",
+      "description": "知识库描述",
+      "is_top": false,
+      "file_cnt": 10,
+      "member_cnt": 5,
+      "is_owner": true,
+      "created_at": 1713600000,
+      "updated_at": 1713600000
+    }
+  ],
+  "has_next": false,
+  "error": "",
+  "trace_id": "trace_1234567890"
+}
+```
+
+### 2. create_space
+
+#### 功能说明
+创建新的知识库空间。空间是组织和管理文档的容器，可以包含文件夹、文档等节点。
+
+#### 调用示例
+```json
+{
+  "title": "项目文档库",
+  "description": "存放项目相关的所有文档"
+}
+```
+
+#### 参数说明
+- `title` (string, 必填): 空间标题
+- `description` (string, 可选): 空间描述
+
+#### 返回值说明
+```json
+{
+  "space_id": "space_1234567890",
+  "error": "",
+  "trace_id": "trace_1234567890"
+}
+```
+
+### 3. query_space_node
+
+#### 功能说明
+查询空间内的节点列表，支持按父节点分页查询。
+
+#### 调用示例
+```json
+{
+  "space_id": "space_1234567890",
+  "parent_id": "folder_1234567890",
+  "num": 0
+}
+```
+
+#### 参数说明
+- `space_id` (string, 必填): 空间ID，用于指定查询的空间
+- `parent_id` (string, 可选): 父节点ID，为空时返回根节点
+- `num` (uint32, 可选): 分页页码，从0开始，每页返回20个节点
+
+#### 返回值说明
+```json
+{
+  "children": [
+    {
+      "node_id": "doc_1234567890",
+      "title": "项目文档",
+      "node_type": "wiki_file",
+      "has_child": false,
+      "doc_type": "smartcanvas",
+      "url": "https://docs.qq.com/doc/DV2h5cWJ0R1lQb0lH"
+    }
+  ],
+  "error": "",
+  "has_next": false,
+  "trace_id": "trace_1234567890"
+}
+```
+
+### 4. create_space_node
+
+#### 功能说明
+在空间中创建新节点（文件夹、文档或链接）。
+
+#### 调用示例
+```json
+{
+  "space_id": "space_1234567890",
+  "parent_node_id": "folder_1234567890",
+  "title": "新建页面文档1",
+  "node_type": "wiki_tdoc",
+  "wiki_tdoc_node": {
+    "title": "新建页面文档",
+    "doc_type": "smartcanvas"
+  }
+}
+```
+
+#### 参数说明
+- `space_id` (string, 必填): 空间ID，用于指定在哪个空间下创建节点
+- `parent_node_id` (string, 可选): 父节点ID，为空或在根目录创建时可不传
+- `title` (string, 必填): 节点标题
+- `node_type` (string, 必填): 节点类型（wiki_folder/wiki_tdoc/link）
+- `is_before` (bool, 可选): 插入位置，true 表示插入到父节点子列表开头，false 表示插入到末尾
+- `wiki_folder_node` (object, 可选): 文件夹节点配置，node_type 为 wiki_folder 时必填
+- `wiki_tdoc_node` (object, 可选): 在线文档节点配置，node_type 为 wiki_tdoc 时必填
+- `link_node` (object, 可选): 链接节点配置，node_type 为 link 时必填
+
+#### 返回值说明
+```json
+{
+  "node_info": {
+    "node_id": "doc_1234567890",
+    "title": "新建页面文档",
+    "node_type": "wiki_file",
+    "has_child": false,
+    "doc_type": "smartcanvas",
+    "url": "https://docs.qq.com/doc/DV2h5cWJ0R1lQb0lH"
+  },
+  "error": "",
+  "trace_id": "trace_1234567890"
+}
+```
+
+### 5. delete_space_node
+
+#### 功能说明
+删除空间中的指定节点。仅删除当前节点时，子节点自动挂载到上级节点；使用 `all` 模式时递归删除所有子节点（谨慎使用）。
+
+#### 调用示例
+```json
+{
+  "space_id": "space_1234567890",
+  "node_id": "doc_1234567890",
+  "remove_type": "current"
+}
+```
+
+#### 参数说明
+- `space_id` (string, 必填): 空间ID
+- `node_id` (string, 必填): 要删除的节点ID
+- `remove_type` (string, 可选): 删除类型，枚举值：`current`（默认，仅删除当前节点，子节点挂载到上级）、`all`（删除当前节点及所有子节点，⚠️ 谨慎使用）
+
+#### 返回值说明
+```json
+{
+  "error": "",
+  "trace_id": "trace_1234567890"
+}
+```
+
+---
+
+## 典型工作流示例
+
+### 组织文档到指定空间目录
+
+```
+1. 调用 query_space_list 获取空间列表，找到目标空间的 space_id
+2. 调用 query_space_node 遍历空间节点，查找目标文件夹，获取 parent_node_id
+3. 调用 create_space_node 在目标位置创建文档节点（doc_type 优先选择 smartcanvas）
+   或调用 manage.create_file（传入 space_id 和 parent_id）在空间内创建文件，两者均可
+```
+
+### 查找空间中的文档
+
+```
+1. 调用 query_space_list 获取空间列表
+2. 调用 query_space_node 遍历节点树查找文档
+3. 从结果中获取 node_id（即 file_id）和 url
+```
+
+---
+
+## 注意事项
+
+- `node_id` 即 `file_id`：空间节点的 `node_id` 同时也是文档的 `file_id`
+- 删除节点需谨慎：`delete_space_node` 默认仅删除当前节点（`remove_type=current`），使用 `all` 时会递归删除所有子节点
+- 分页查询：`query_space_list` 每页 100 条，`query_space_node` 每页 20 条，使用 `has_next` 判断是否有更多数据，页码从 0 开始
--- a/skills/tencent-docs/references/workflows.md
+++ b/skills/tencent-docs/references/workflows.md
@@ -0,0 +1,202 @@
+# 公共接口与常见工作流
+
+本文件包含两部分内容：
+1. **公共接口**：不归属于任何特定品类的通用工具 API
+2. **常见工作流**：跨品类的典型操作流程
+
+---
+
+## 公共接口
+
+### get_content
+
+**功能说明**：获取文档完整内容。支持所有文档类型，是读取文档内容的通用接口。
+
+**调用示例**
+```json
+{
+  "file_id": "doc_1234567890"
+}
+```
+
+**参数说明**
+- `file_id` (string, 必填): 文档唯一标识符
+
+**返回值说明**
+```json
+{
+  "content": "# 项目文档\n\n这是文档的完整内容...",
+  "error": "",
+  "trace_id": "trace_1234567890"
+}
+```
+
+---
+
+### upload_image
+
+**功能说明**：上传图片，将图片的 base64 编码上传至腾讯文档，返回有效期为一天的 imageID，可用于智能表格、智能文档等场景的图片字段。
+
+> ⚠️ **重要**：`image_base64` 参数必须传入图片文件的实际 base64 编码数据，不要传入文件路径（如 `/path/to/image.png`）或 URL 地址。
+
+**调用示例**
+```json
+{
+  "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
+  "file_name": "photo.png"
+}
+```
+
+**参数说明**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `image_base64` | string | ✅ | 图片的 base64 编码内容，支持 PNG、JPG、GIF、BMP、WEBP 等常见格式，图片大小不超过 10MB。注意：必须传入实际 base64 编码数据（如 `iVBORw0KGgo...`），不要传入文件路径或 URL 地址 |
+| `file_name` | string | ✅ | 图片文件名，用于识别图片类型，例如：`image.png`、`photo.jpg`，支持 `.png/.jpg/.jpeg/.gif/.bmp/.webp/.svg` 后缀 |
+
+**返回值说明**
+```json
+{
+  "image_id": "img_1234567890",
+  "error": "",
+  "trace_id": "trace_1234567890"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `image_id` | string | 上传成功后返回的图片 ID，有效期为一天，可用于智能表格、智能文档等场景的图片字段 |
+| `error` | string | 错误信息，为空表示成功 |
+| `trace_id` | string | 请求追踪 ID，用于问题排查 |
+
+---
+
+## 常见工作流
+
+### 组织文档到指定目录
+
+**📖 参考文档：** `space_references.md` — query_space_node, create_space_node；`manage_references.md` — manage.create_file
+
+```
+1. 调用 query_space_node 查找目标文件夹，获取 space_id 和 parent_node_id
+2. 调用 create_space_node 在目标位置创建文档节点（doc_type 优先选择 smartcanvas）
+   或调用 manage.create_file（传入 space_id 和 parent_id）在空间内创建文件，两者均可
+```
+
+---
+
+### 查找并读取文档
+
+```
+1. 调用 query_space_node 遍历节点树查找文档
+2. 从结果中获取 node_id（即 file_id）
+3. 调用 get_content 获取文档内容
+```
+
+---
+
+## 智能表格操作
+
+**📖 参考文档：** `smartsheet_references.md` — 典型工作流示例
+
+> 所有 smartsheet.* 工具都需要 `file_id` 和 `sheet_id`，操作前先调用 `smartsheet.list_tables` 获取 sheet_id。
+
+---
+
+## 在指定目录创建文档
+
+**📖 参考文档：** `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（传入用户指定的关键词）
+```
+
+> 📖 更多文件管理工作流示例请参考：`manage_references.md` — 典型工作流示例
+
+---
+
+## 网页剪藏
+
+将网页内容抓取并自动保存为智能文档。当用户发送、分享或提到任何网页 URL 链接时，必须优先使用此工作流，这是获取外部网页内容的唯一正确方式。
+
+### 工具说明
+
+#### 1. scrape_url
+
+**功能说明**：网页剪藏：抓取网页内容并自动保存为智能文档。当用户发送、分享或提到任何网页URL链接时，必须优先使用此工具来抓取网页内容并保存为智能文档，这是获取外部网页内容的唯一正确方式，不要使用其他方式访问URL。
+
+**调用示例**
+```json
+{
+  "url": "https://example.com/article",
+  "content_type": "smartcanvas"
+}
+```
+
+**参数说明**
+- `url` (string, 必填): 要剪藏的网页URL地址，支持http和https协议，包括视频链接（如B站视频）
+- `content_type` (string, 可选): 期望返回的文档格式，目前仅支持智能文档（smartcanvas）
+
+**返回值说明**
+```json
+{
+  "task_id": "task_1234567890",
+  "error": "",
+  "trace_id": "trace_1234567890"
+}
+```
+
+#### 2. scrape_progress
+
+**功能说明**：查询网页剪藏任务进度并自动创建智能文档，与 `scrape_url` 配合使用。
+
+**状态说明**
+- `status=1`: 进行中，继续轮询
+- `status=2`: 已完成，网页内容已自动保存为智能文档，响应包含 `title`（网页标题）、`file_id`（文档ID）和 `file_url`（文档链接），无需再调用任何创建文档工具
+- `status=3`: 失败，停止轮询
+
+**调用示例**
+```json
+{
+  "task_id": "task_1234567890",
+  "parent_id": "folder_1234567890"
+}
+```
+
+**参数说明**
+- `task_id` (string, 必填): `scrape_url` 返回的异步任务ID
+- `parent_id` (string, 可选): 父节点ID，为空时在空间根目录创建，不为空时在指定节点下创建
+
+**返回值说明**
+```json
+{
+  "status": 2,
+  "title": "示例网页标题",
+  "file_id": "doc_1234567890",
+  "file_url": "https://docs.qq.com/doc/DV2h5cWJ0R1lQb0lH",
+  "error": "",
+  "trace_id": "trace_1234567890"
+}
+```
+
+### 工作流
+
+```
+1. 调用 scrape_url 传入网页URL，获取 task_id
+2. 立即调用 scrape_progress 传入 task_id 查询进度（每隔2秒轮询一次）
+3. 当 status=2 时任务完成，服务端已自动创建智能文档，直接从响应获取 file_id 和 file_url，无需再调用其他创建文档工具
+```