jameswu/openclaw-qqlobster-skills
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

技能备份 - 2026-04-15 (40个技能)

Browse Source
This commit is contained in:
root
2026-04-15 18:53:15 +08:00
parent f62f14814f
commit c65fce24e4
791 changed files with 190773 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/tencent-docs/.clawhub/origin.json
+7
View File
@@ -0,0 +1,7 @@
{
"version": 1,
"registry": "https://clawhub.ai",
"slug": "tencent-docs",
"installedVersion": "1.0.6",
"installedAt": 1773129532759
}
skills/tencent-docs/SKILL.md
+435
View File
@@ -0,0 +1,435 @@
---
name: tencent-docs
description: 腾讯文档，提供完整的腾讯文档操作能力。当用户需要操作腾讯文档时使用此skill，包括：(1) 创建各类在线文档（智能文档、Word、Excel、幻灯片、思维导图、流程图）(2) 查询、搜索文档空间与文件 (3) 管理空间节点、文件夹结构 (4) 读取文档内容 (5) 编辑操作智能表 （6）编辑操作智能文档。
homepage: https://docs.qq.com/home
metadata: {"openclaw":{"requires":{"env":["TENCENT_DOCS_TOKEN"]},"primaryEnv":"TENCENT_DOCS_TOKEN","category":"tencent","tencentTokenMode":"custom","tokenUrl":"https://docs.qq.com/open/document/mcp/get-token/","emoji":"📝"}}
---
# 腾讯文档 MCP 使用指南
腾讯文档 MCP 提供了一套完整的在线文档操作工具，支持创建、查询、编辑多种类型的在线文档。
## 📚 详细参考文档
如需查看每个工具的详细调用示例、参数说明和返回值说明，请参考：
- `references/api_references.md` - 包含所有工具的完整调用示例、参数说明、返回值说明及 API 结构、枚举值说明
- `references/smartsheet_references.md` - 智能表格（SmartSheet）专项参考文档，包含字段类型枚举、字段值格式参考、典型工作流示例及所有 `smartsheet.*` 工具的详细说明
- `references/smartcanvas_references.md` - 智能文档（SmartCanvas）专项参考文档，包含元素类型说明、富文本格式枚举、典型工作流示例及所有 `smartcanvas.*` 工具的详细说明
## ⚙️ 配置要求
根据你所使用的环境，选择对应的配置方式：
### ✅ 场景一：CodeBuddy / 其他 IDE（推荐）
**无需额外安装**，在 IDE 的 MCP 配置中添加腾讯文档服务即可直接使用。
**配置步骤：**
1. 访问 [https://docs.qq.com/open/auth/mcp.html](https://docs.qq.com/open/auth/mcp.html) 获取你的个人 Token
2. 在 IDE 的 MCP 配置中添加以下服务：
```json
{
"mcpServers": {
"tencent-docs": {
"url": "https://docs.qq.com/openapi/mcp",
"headers": {
"Authorization": "你的Token值"
}
}
}
}
```
> ⚠️ **重要**：Header 的 key **必须**使用 `Authorization`，不能使用其他名称（如 `token`、`auth`、`X-Token` 等），否则鉴权将失败。
3. 配置完成后，即可在 IDE 中直接调用所有腾讯文档工具，无需任何额外步骤。
---
### 🔧 场景二：OpenClaw（需要安装）
在 OpenClaw 中使用时，需要先完成本地安装和注册。
**安装步骤：**
1. 访问 [https://docs.qq.com/open/auth/mcp.html](https://docs.qq.com/open/auth/mcp.html) 获取 Token，并配置环境变量：
```bash
export TENCENT_DOCS_TOKEN="你的Token值"
```
2. 运行 setup.sh 完成 MCP 服务注册：
```bash
bash setup.sh
```
> setup.sh 会自动将腾讯文档 MCP 服务注册到 mcporter，并验证配置是否成功。
> 如果未执行 setup，所有工具调用将无法找到 `tencent-docs` 服务。
3. 验证安装是否成功：
```bash
mcporter list | grep tencent-docs
```
> ⚠️ **如果用户未配置 Token**，请引导用户访问上方链接获取 Token，否则所有工具调用将返回鉴权失败。
---
## 🚨 错误码处理
### 常见错误码及解决方案
| 错误码 | 错误类型 | 解决方案 |
|--------|----------|----------|
| **400006** | **Token 鉴权失败** | 🔑 **检查 Token 配置**：确认 Header 的 key **必须**使用 `Authorization`；同时确认 Token 值正确，可访问 [https://docs.qq.com/open/auth/mcp.html](https://docs.qq.com/open/auth/mcp.html) 重新获取 |
| **400007** | **VIP权限不足** | ⭐ **立即升级VIP**：访问 [https://docs.qq.com/vip?immediate_buy=1](https://docs.qq.com/vip?immediate_buy=1) 购买VIP服务 |
## 🔧 调用方式
腾讯文档 MCP 的标准配置名称为 **`tencent-docs`**，通过内置 MCP Client 直接调用工具：
```
mcp: tencent-docs
tool: <工具名称>
arguments: { ... }
```
> ⚠️ **注意**：`arguments` 必须是 **JSON 对象**，不能是字符串（即不能是 `"{ ... }"` 这样的字符串形式）。
### 支持的工具完整列表
> ⚠️ **以下工具列表仅供参考，实际可用工具以调用 `tools/list` 接口返回结果为准。**
>
> 获取最新工具列表：
> ```
> mcp: tencent-docs
> method: tools/list
> ```
| 工具名称 | MCP 调用格式 | 功能说明 |
|---------|-------------|---------|
| create_smartcanvas_by_markdown | `create_smartcanvas_by_markdown` | ⭐ 创建智能文档（首选） |
| create_excel_by_markdown | `create_excel_by_markdown` | 创建 Excel 表格 |
| create_slide_by_markdown | `create_slide_by_markdown` | 创建幻灯片 |
| create_mind_by_markdown | `create_mind_by_markdown` | 创建思维导图 |
| create_flowchart_by_mermaid | `create_flowchart_by_mermaid` | 创建流程图 |
| create_word_by_markdown | `create_word_by_markdown` | 创建 Word 文档 |
| query_space_node | `query_space_node` | 查询空间节点 |
| create_space_node | `create_space_node` | 创建空间节点 |
| delete_space_node | `delete_space_node` | 删除空间节点 |
| search_space_file | `search_space_file` | 搜索空间文件 |
| get_content | `get_content` | 获取文档内容 |
| batch_update_sheet_range | `batch_update_sheet_range` | 批量更新表格 |
| smartcanvas.* | 见下方第 4 节 | 智能文档元素操作（页面/文本/标题/待办事项），详见 `references/smartcanvas_references.md` |
| smartsheet.* | 见下方第 5 节 | 智能表格操作（工作表/视图/字段/记录），详见 `references/smartsheet_references.md` |
**详细调用示例请参考：`references/api_references.md`**
## ⭐ 重要：文档类型选择指南
> **首选推荐：智能文档（smartcanvas）**
>
> - **新增文档**：优先使用 `create_smartcanvas_by_markdown` 创建智能文档，原因如下：
> - 📝 排版效果更美观，自动优化布局
> - 🎨 支持更丰富的格式（标题、段落、列表、表格、代码块、引用、图片等）
> - 📱 跨平台显示效果一致
> - **编辑已有文档**：使用 `smartcanvas.*` 系列工具对已有智能文档进行增删改查操作，详见 `references/smartcanvas_references.md`
### 文档类型选择决策树
```
需要创建什么类型的内容？
│
├─ 新增通用文档内容（报告、笔记、文章等）
│ └─ ✅ 使用 create_smartcanvas_by_markdown（首选）
│
├─ 编辑/追加已有智能文档内容
│ └─ ✅ 使用 smartcanvas.* 工具（详见 `references/smartcanvas_references.md`）
│
├─ 数据表格（需要计算、筛选、统计）
│ └─ ✅ 使用 create_excel_by_markdown
│
├─ 演示文稿（需要逐页展示、投影演示）
│ └─ ✅ 使用 create_slide_by_markdown
│
├─ 层次化知识整理（知识图谱、大纲）
│ └─ ✅ 使用 create_mind_by_markdown
│
├─ 流程/架构展示（流程图、时序图）
│ └─ ✅ 使用 create_flowchart_by_mermaid
│
├─ 结构化数据管理（多视图、字段管理、看板）
│ └─ ✅ 使用 smartsheet.* 工具（详见 `references/smartsheet_references.md`）
│
└─ 传统 Word 格式导出需求
└─ 使用 create_word_by_markdown（仅在明确需要时）
```
## 支持的文档类型
| 类型 | doc_type | 推荐度 | 说明 |
|------|----------|--------|------|
| **智能文档** | smartcanvas | ⭐⭐⭐ **首选** | 排版美观，支持丰富组件 |
| Excel | excel | ⭐⭐⭐ | 数据表格专用 |
| 幻灯片 | slide | ⭐⭐⭐ | 演示文稿专用 |
| 思维导图 | mind | ⭐⭐⭐ | 知识图谱专用 |
| 流程图 | flowchart | ⭐⭐⭐ | 流程展示专用 |
| Word | word | ⭐⭐ | 传统格式，排版一般 |
| 收集表 | form | ⭐⭐ | 表单收集 |
| 智能表格 | smartsheet | ⭐⭐⭐ | 高级结构化表格，支持多视图、字段管理 |
| 白板 | board | ⭐⭐ | 在线白板 |
## 工具列表
> 📖 所有工具的完整调用示例、参数说明和返回值说明，请查阅 `references/api_references.md`
>
> ⚠️ **此 skill 中的工具列表仅作使用指导，实际可用工具以调用 `tools/list` 接口返回结果为准。** 如遇工具不存在或参数不符，请先执行 `tools/list` 获取最新工具定义。
### 1. 创建文档类
#### ⭐ create_smartcanvas_by_markdown（首选）
**通用文档首选工具**，通过 Markdown 创建智能文档，排版美观，支持所有 Markdown 基本结构。
**适用场景**：
- 📄 文档、报告、笔记、文章
- 📋 会议纪要、方案说明
- 📚 技术文档、教程
- 🗒️ 任何需要美观排版的内容
**支持 `parent_id` 参数**：可指定父节点 ID，将文档创建到指定目录下；不填则在根目录创建。
> 📖 调用示例请参考：`references/api_references.md` - create_smartcanvas_by_markdown
#### create_excel_by_markdown
通过 Markdown 表格创建 Excel，适用于需要数据计算、筛选的场景。
**适用场景**：数据报表、统计表格、需要公式计算的场景
**支持 `parent_id` 参数**：可指定父节点 ID，将文档创建到指定目录下；不填则在根目录创建。
> 📖 调用示例请参考：`references/api_references.md` - create_excel_by_markdown
#### create_slide_by_markdown
通过 Markdown 创建幻灯片，遵循特定层级结构（`#` 主标题 → `##` 章节 → `###` 页面 → `-` 段落 → 缩进子项正文）。
**适用场景**：演示文稿、项目汇报、培训材料
**支持 `parent_id` 参数**：可指定父节点 ID，将文档创建到指定目录下；不填则在根目录创建。
> 📖 调用示例请参考：`references/api_references.md` - create_slide_by_markdown
#### create_mind_by_markdown
通过 Markdown 创建思维导图，使用标题层级和列表嵌套表示结构。
**适用场景**：知识图谱、大纲整理、头脑风暴
**支持 `parent_id` 参数**：可指定父节点 ID，将文档创建到指定目录下；不填则在根目录创建。
> 📖 调用示例请参考：`references/api_references.md` - create_mind_by_markdown
#### create_flowchart_by_mermaid
通过 Mermaid 语法创建流程图，mermaid 字段内容必须全部使用英文。
**适用场景**：流程图、时序图、架构图
**支持 `parent_id` 参数**：可指定父节点 ID，将文档创建到指定目录下；不填则在根目录创建。
> 📖 调用示例请参考：`references/api_references.md` - create_flowchart_by_mermaid
#### create_word_by_markdown
通过 Markdown 创建 Word 文档。**注意：仅在用户明确要求 Word 格式时使用，否则请使用 smartcanvas**。
**支持 `parent_id` 参数**：可指定父节点 ID，将文档创建到指定目录下；不填则在根目录创建。
> 📖 调用示例请参考：`references/api_references.md` - create_word_by_markdown
### 2. 空间管理类
#### query_space_node
查询空间节点树结构，获取文件夹和文档列表。支持分页，每页返回 20 条。
> 📖 调用示例请参考：`references/api_references.md` - query_space_node
#### create_space_node
在空间中创建新节点，支持创建文件夹（`wiki_folder`）、在线文档（`wiki_tdoc`）、链接（`link`）。
> 📖 调用示例请参考：`references/api_references.md` - create_space_node
#### search_space_file
在空间内搜索文档，支持按关键词匹配标题和内容，支持分页，每页返回 40 条。
> ⚠️ 注意：仅能搜索到文档类节点（word、excel、slide 等），无法搜索文件夹；如需查找文件夹，请使用 `query_space_node` 遍历节点树。
> 📖 调用示例请参考：`references/api_references.md` - search_space_file
#### delete_space_node
删除空间中的指定节点，支持两种删除模式。
**删除类型（remove_type）**：
- `current`（默认）：仅删除当前节点，子节点自动挂载到上级节点
- `all`：删除当前节点及其所有子节点（⚠️ 谨慎使用，会递归删除所有子节点）
> 📖 调用示例请参考：`references/api_references.md` - delete_space_node
### 3. 文档操作类
#### get_content
获取文档完整内容，传入 `file_id` 返回文档正文文本。
> 📖 调用示例请参考：`references/api_references.md` - get_content
#### batch_update_sheet_range
批量更新表格单元格内容（仅适用于 Excel），数据从表格末尾追加，不覆盖已有内容。
> 📖 调用示例请参考：`references/api_references.md` - batch_update_sheet_range
#### smartcanvas.create_smartcanvas_element
在已有智能文档中新增元素，支持添加页面（Page）、文本（Text）、标题（Heading）、待办事项（Task）等多种类型元素。
**元素层级约束**：
- `Text`、`Task`、`Heading` 必须挂载在 `Page` 类型父节点下（`parent_id` 必填）
- `Page` 可不指定父节点，插入到根节点
- 父节点不支持为 `Heading` 类型
> 📖 完整说明请参考：`references/smartcanvas_references.md` - smartcanvas.create_smartcanvas_element
#### smartcanvas.get_element_info
批量查询指定元素的详细信息，支持同时查询多个元素的内容、类型、父子关系等。
> 📖 完整说明请参考：`references/smartcanvas_references.md` - smartcanvas.get_element_info
#### smartcanvas.get_page_info
查询指定页面内的所有元素，支持分页获取。使用 `cursor` 参数进行分页，`is_over=true` 表示已获取全部内容。
> 📖 完整说明请参考：`references/smartcanvas_references.md` - smartcanvas.get_page_info
#### smartcanvas.get_top_level_pages
查询文档的所有顶层页面列表，返回根节点下的直接子页面，用于了解文档目录结构。
> 📖 完整说明请参考：`references/smartcanvas_references.md` - smartcanvas.get_top_level_pages
#### smartcanvas.update_element
批量修改元素内容，支持同时更新多个元素的文本、格式、标题级别、页面标题等属性。
> 📖 完整说明请参考：`references/smartcanvas_references.md` - smartcanvas.update_element
#### smartcanvas.delete_element
批量删除元素，支持同时删除多个指定元素。
> ⚠️ 删除 Page 元素时，其下所有子元素也会被一并删除，请谨慎操作。
> 📖 完整说明请参考：`references/smartcanvas_references.md` - smartcanvas.delete_element
#### smartcanvas.append_insert_smartcanvas_by_markdown
通过 Markdown 文本向已有智能文档追加内容，内容追加到文档末尾。
> 📖 完整说明请参考：`references/smartcanvas_references.md` - smartcanvas.append_insert_smartcanvas_by_markdown
### 4. 智能文档（SmartCanvas）元素操作类
智能文档支持对页面、文本、标题、待办事项等元素进行完整的增删改查操作，共 7 个工具（`smartcanvas.*`）。
> 📖 **所有工具的完整说明（使用场景、元素类型定义、枚举值、参数示例）请查阅：`references/smartcanvas_references.md`**
>
> 包含：元素新增、元素查询、页面内容查询、顶层页面查询、元素修改、元素删除、Markdown 追加，以及标题级别枚举、颜色枚举、富文本格式说明、典型工作流示例。
### 5. 智能表格（SmartSheet）操作类
智能表格支持对工作表、视图、字段、记录进行完整的增删改查操作，共 12 个工具（`smartsheet.*`）。
> 📖 **所有工具的完整说明（使用场景、字段定义、枚举值、参数示例）请查阅：`references/smartsheet_references.md`**
>
> 包含：工作表操作、视图操作、字段操作、记录操作，以及字段类型枚举、字段值格式参考、典型工作流示例。
## 常见工作流
### 创建通用文档（推荐方式）
```
1. 优先调用 create_smartcanvas_by_markdown 创建智能文档
2. 从返回结果中获取 file_id 和 url
```
### 编辑已有智能文档
```
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. 调用 `query_space_node` 查找目标文件夹
2. 调用 `create_space_node` 在目标位置创建文档节点（doc_type 优先选择 smartcanvas）
### 搜索并读取文档
1. 调用 `search_space_file` 搜索文档
2. 从结果中获取 `node_id`（即 `file_id`）
3. 调用 `get_content` 获取文档内容
### 智能表格操作工作流
#### 从零搭建任务管理表
```
1. 获取工作表列表 → smartsheet.list_tables（获取 sheet_id）
2. 添加字段（列）→ smartsheet.add_fields（任务名称、优先级、截止日期等）
3. 批量写入数据 → smartsheet.add_records
4. （可选）创建看板视图 → smartsheet.add_view（view_type=2）
```
#### 查询并更新数据
```
1. 获取工作表 → smartsheet.list_tables
2. 查询记录 → smartsheet.list_records（获取 record_id）
3. 更新记录 → smartsheet.update_records（传入 record_id 和新字段值）
```
> 📖 更多智能表格工作流示例请参考：`references/smartsheet_references.md` - 典型工作流示例
## 注意事项
- **默认使用 smartcanvas**：除非用户明确指定其他格式，否则**新增文档**时优先使用 `create_smartcanvas_by_markdown`；**编辑已有智能文档**时使用 `smartcanvas.*` 系列工具
- **创建文档时支持 `parent_id`**：所有 `create_*_by_markdown` 和 `create_flowchart_by_mermaid` 工具均支持 `parent_id` 参数，可将文档直接创建到指定目录；不填则在根目录创建
- **删除节点**：`delete_space_node` 默认仅删除当前节点（`remove_type=current`），使用 `all` 时会递归删除所有子节点，需谨慎
- Markdown 内容使用 UTF-8 格式，特殊字符无需转义
- 幻灯片必须遵循层级结构，每页包含 2-4 个段落标题
- 分页查询每页返回 20-40 条记录，使用 `has_next` 判断是否有更多
- `node_id` 同时也是文档的 `file_id`
- `create_flowchart_by_mermaid` 的 mermaid 内容必须全部使用英文
- **智能文档元素操作**：`Text`、`Heading`、`Task` 必须挂载在 `Page` 下，`parent_id` 必须为 Page 类型元素 ID；操作前先调用 `smartcanvas.get_top_level_pages` 获取页面结构
- **智能文档分页查询**：`smartcanvas.get_page_info` 使用 `cursor` 分页，`is_over=true` 表示已获取全部内容
- **智能文档删除注意**：删除 Page 元素时，其下所有子元素也会被一并删除
- **智能表格操作**：所有 smartsheet.* 工具都需要 `file_id` 和 `sheet_id`，操作前先调用 `smartsheet.list_tables` 获取 sheet_id
- **字段类型不可更新**：`update_fields` 时 field_type 不能修改，但必须传入原值
- **记录字段值格式**：不同字段类型的值格式不同，详见 `references/smartsheet_references.md` - 字段值格式参考
skills/tencent-docs/_meta.json
+6
View File
@@ -0,0 +1,6 @@
{
"ownerId": "kn71n4rrmmw7469qstfds7c2z181y79z",
"slug": "tencent-docs",
"version": "1.0.6",
"publishedAt": 1773073135580
}
skills/tencent-docs/references/api_references.md
+487
View File
@@ -0,0 +1,487 @@
# 腾讯文档 MCP 工具完整参考
本文件包含腾讯文档 MCP 所有工具的通用 API 说明、详细调用示例、参数说明和返回值说明。
---
## 通用说明
### 响应结构
所有 API 返回都包含：
- `error`: 错误信息（成功时为空）
- `trace_id`: 调用链追踪 ID
### node_type 枚举值
| 值 | 说明 |
|---|---|
| wiki_folder | 文件夹 |
| wiki_tdoc | 在线文档（请求时使用） |
| wiki_file | 在线文档（返回值中使用） |
| link | 链接 |
| resource | 资源文件 |
### doc_type 枚举值
| 值 | 说明 |
|---|---|
| word | 文字处理文档 |
| excel | 电子表格 |
| form | 收集表 |
| slide | 幻灯片 |
| smartcanvas | 智能文档 |
| smartsheet | 智能表格 |
| board | 白板 |
| 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_node`：每页 20 条
- `search_space_file`：每页 40 条
- 使用 `has_next` 判断是否有更多数据
- 页码从 0 开始
---
## 工具调用示例
## 1. create_smartcanvas_by_markdown
### 功能说明
通过 Markdown 格式创建智能文档，排版美观，支持所有 Markdown 基本结构。
### 调用示例
```json
{
"title": "项目需求文档",
"markdown": "# 项目需求\n\n## 项目背景\n\n本项目旨在开发一套智能文档管理系统...\n\n## 功能需求\n\n- 文档创建功能\n- 文档编辑功能\n- 协作功能\n\n## 技术架构\n\n| 组件 | 技术选型 |\n|------|----------|\n| 前端 | React |\n| 后端 | Go |\n| 数据库 | MySQL |",
"parent_id": "folder_1234567890"
}
```
### 参数说明
- `title` (string, 必填): 文档标题
- `markdown` (string, 必填): UTF-8 格式的 Markdown 文本
- `parent_id` (string, 可选): 父节点ID，为空时在空间根目录创建，不为空时在指定节点下创建
### 返回值说明
```json
{
"file_id": "doc_1234567890",
"url": "https://docs.qq.com/doc/DV2h5cWJ0R1lQb0lH",
"error": "",
"trace_id": "trace_1234567890"
}
```
## 2. create_excel_by_markdown
### 功能说明
通过 Markdown 表格创建 Excel，适用于需要数据计算、筛选的场景。
### 调用示例
```json
{
"title": "销售数据报表",
"markdown": "| 日期 | 产品 | 销售额 | 销售量 |\n|------|------|--------|--------|\n| 2024-01-01 | 产品A | 10000 | 100 |\n| 2024-01-02 | 产品B | 15000 | 150 |",
"parent_id": "folder_1234567890"
}
```
### 参数说明
- `title` (string, 必填): 表格标题
- `markdown` (string, 必填): 包含表格的 Markdown 文本
- `parent_id` (string, 可选): 父节点ID，为空时在空间根目录创建，不为空时在指定节点下创建
### 返回值说明
```json
{
"file_id": "sheet_1234567890",
"url": "https://docs.qq.com/sheet/DV2h5cWJ0R1lQb0lH",
"error": "",
"trace_id": "trace_1234567890"
}
```
## 3. create_slide_by_markdown
### 功能说明
通过 Markdown 创建幻灯片，遵循特定层级结构。
### Markdown 层级结构规范
PPT 必须遵循严格的层级结构：
```
# 一级标题 → PPT 主标题（整个演示文稿的标题）
## 二级标题 → 章节标题（区分不同主题章节）
### 三级标题 → 页面标题（每个幻灯片的标题）
- 列表项 → 段落标题（每页 2-4 个）
- 子列表项 → 正文内容（每段约 200 字）
```
### 调用示例
```json
{
"title": "项目汇报",
"markdown": "# 项目汇报\n\n## 项目背景\n\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": "slide_1234567890",
"url": "https://docs.qq.com/slide/DV2h5cWJ0R1lQb0lH",
"error": "",
"trace_id": "trace_1234567890"
}
```
## 4. 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"
}
```
## 5. 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"
}
```
## 6. create_word_by_markdown
### 功能说明
通过 Markdown 创建 Word 文档。
### 调用示例
```json
{
"title": "技术文档",
"markdown": "# 技术文档\n\n## 系统架构\n\n本文档描述系统的技术架构设计...\n\n## 数据库设计\n\n| 表名 | 说明 |\n|------|------|\n| users | 用户表 |\n| documents | 文档表 |",
"parent_id": "folder_1234567890"
}
```
### 参数说明
- `title` (string, 必填): Word 文档标题
- `markdown` (string, 必填): UTF-8 格式的 Markdown 文本
- `parent_id` (string, 可选): 父节点ID，为空时在空间根目录创建，不为空时在指定节点下创建
### 返回值说明
```json
{
"file_id": "word_1234567890",
"url": "https://docs.qq.com/doc/DV2h5cWJ0R1lQb0lH",
"error": "",
"trace_id": "trace_1234567890"
}
```
## 7. query_space_node
### 功能说明
查询空间节点树结构，获取文件夹和文档列表。
### 调用示例
```json
{
"parent_id": "folder_1234567890",
"num": 0
}
```
### 参数说明
- `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"
}
```
## 8. create_space_node
### 功能说明
在空间中创建新节点（文件夹、文档或链接）。
### 调用示例
```json
{
"parent_node_id": "folder_1234567890",
"title": "新建页面文档1",
"node_type": "wiki_tdoc",
"wiki_tdoc_node": {
"title": "新建页面文档",
"doc_type": "smartcanvas"
}
}
```
### 参数说明
- `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"
}
```
## 9. delete_space_node
### 功能说明
删除空间中的指定节点。仅删除当前节点时，子节点自动挂载到上级节点；使用 `all` 模式时递归删除所有子节点（谨慎使用）。
### 调用示例
```json
{
"node_id": "doc_1234567890",
"remove_type": "current"
}
```
### 参数说明
- `node_id` (string, 必填): 要删除的节点ID
- `remove_type` (string, 可选): 删除类型，枚举值：`current`（默认，仅删除当前节点，子节点挂载到上级）、`all`（删除当前节点及所有子节点，⚠️ 谨慎使用）
### 返回值说明
```json
{
"error": "",
"trace_id": "trace_1234567890"
}
```
## 10. search_space_file
### 功能说明
在空间内搜索文档。注意：仅能搜索到文档类节点（word、excel、slide 等），无法搜索到文件夹节点；如需查找文件夹，请使用 `query_space_node` 遍历节点树。
### 调用示例
```json
{
"pattern": "项目文档",
"queryby": 2,
"descending": true,
"num": 0
}
```
### 参数说明
- `pattern` (string, 必填): 搜索关键词
- `queryby` (int32, 可选): 排序方式（1-创建时间，2-修改时间）
- `descending` (bool, 可选): 排序方向（true-降序）
- `num` (uint32, 可选): 分页页码，从0开始，每页返回40条
### 返回值说明
```json
{
"nodes": [
{
"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"
}
```
## 11. get_content
### 功能说明
获取文档完整内容。
### 调用示例
```json
{
"file_id": "doc_1234567890"
}
```
### 参数说明
- `file_id` (string, 必填): 文档唯一标识符
### 返回值说明
```json
{
"content": "# 项目文档\n\n这是文档的完整内容...",
"error": "",
"trace_id": "trace_1234567890"
}
```
## 12. batch_update_sheet_range
### 功能说明
批量更新表格单元格内容。数据将从表格末尾开始追加新行，不会覆盖已有内容。
### 调用示例
```json
{
"file_id": "sheet_1234567890",
"texts": {
"rows": [
{"values": ["姓名", "年龄", "部门"]},
{"values": ["张三", "25", "技术部"]},
{"values": ["李四", "30", "产品部"]}
]
}
}
```
### 参数说明
- `file_id` (string, 必填): 表格唯一标识符
- `texts` (object, 必填): 二维文本数组，数据从 A1 单元格开始按行列顺序填充
### 返回值说明
```json
{
"update_num": 6,
"error": "",
"trace_id": "trace_1234567890"
}
```
## 13. create_smartcanvas_element
### 功能说明
在已有智能文档中追加内容。
### 调用示例
```json
{
"file_id": "doc_1234567890",
"markdown": "## 新增内容\n\n这是追加到文档末尾的新内容..."
}
```
### 参数说明
- `file_id` (string, 必填): 文档唯一标识符
- `markdown` (string, 必填): 要追加的 Markdown 内容
### 返回值说明
```json
{
"error": "",
"trace_id": "trace_1234567890"
}
```
skills/tencent-docs/references/smartcanvas_references.md
+793
View File
@@ -0,0 +1,793 @@
# 智能文档（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` 类型
---
## 元素操作
### 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 | | 要添加的标题元素列表 |
**返回字段**：
| 字段 | 类型 | 说明 |
|------|------|------|
| `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": "提交设计稿"
}
}
]
}
```
---
### 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 | | 标题块背景颜色 |
---
### 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` 字段 |
---
## 典型工作流示例
### 工作流一：创建结构化文档
```
步骤 1：创建智能文档
→ create_smartcanvas_by_markdown（创建文档，获取 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
→ search_space_file（搜索文档，获取 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`，可通过 `search_space_file` 搜索文档获取，或在创建文档时从返回结果中获取。
> - 操作元素前，建议先调用 `smartcanvas.get_top_level_pages` 了解文档结构，再调用 `smartcanvas.get_page_info` 获取具体元素 ID。
> - `Text`、`Heading`、`Task` 元素必须挂载在 `Page` 下，创建时 `parent_id` 必须为 Page 类型元素的 ID。
skills/tencent-docs/references/smartsheet_references.md
+1036
View File
File diff suppressed because it is too large Load Diff
skills/tencent-docs/setup.sh
+53
View File
@@ -0,0 +1,53 @@
#!/bin/bash
# Setup script for 腾讯文档 MCP Skill (内部 OpenClaw 版本)
set -e
echo "🚀 设置腾讯文档 MCP Skill（OpenClaw 版本）..."
echo ""
# 检查 mcporter
if ! command -v mcporter &> /dev/null; then
echo "⚠️ 未找到 mcporter，正在安装..."
npm install -g mcporter
echo "✅ mcporter 安装完成"
fi
# 添加 MCP 配置
echo "🔧 配置 mcporter..."
# 从环境变量中读取用户填写的 Token
mcporter config add tencent-docs "https://docs.qq.com/openapi/mcp" \
--header "Authorization=$TENCENT_DOCS_TOKEN" \
--transport http \
--scope home
echo ""
echo "✅ 配置完成！"
echo ""
echo "ℹ️ TENCENT_DOCS_TOKEN 环境变量由 OpenClaw runtime 自动提供"
echo ""
# 验证配置
echo "🧪 验证配置..."
if mcporter list 2>&1 | grep -q "tencent-docs"; then
echo "✅ 配置验证成功！"
echo ""
mcporter list | grep -A 1 "tencent-docs" || true
else
echo "⚠️ 配置验证失败，请检查网络或 Token 是否有效"
echo ""
echo "如有问题，请访问 https://docs.qq.com/open/document/mcp/get-token/ 获取 Token"
fi
echo ""
echo "─────────────────────────────────────"
echo "🎉 设置完成！"
echo ""
echo "📖 使用方法："
echo " mcporter call tencent-docs.create_smartcanvas_by_markdown"
echo ""
echo "🏠 腾讯文档主页：https://docs.qq.com/home"
echo ""
echo "📖 更多信息请查看 SKILL.md"
echo ""