公共接口与常见工作流

本文件包含两部分内容： 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，用于问题排查 |

---

常见工作流

用 Markdown 创建 Word 文档

📖 参考文档： `docengine_references.md` — create_with_markdown

使用 `tencent-docengine` 的 `create_with_markdown` 工具，可一步将 Markdown 内容创建为 Word 文档，无需先创建空文档再插入内容。

> 💡 base64 编码：使用系统 `base64` 命令将 Markdown 内容编码后写入工作区目录下的文件，再通过 read_file 工具读取编码结果填入请求参数。

``` 1. 准备好 Markdown 格式的文档内容，将其保存为 /.tmp/tencent_docs/<标题>.md 文件（<标题> 为文档标题） 2. 使用系统 base64 命令将 Markdown 文件编码并写入工作区目录下的文件（确保 agent 可通过 read_file 访问）： mkdir -p /.tmp/tencent_docs # 输入为已保存的 .md 文件 base64 -w 0 /.tmp/tencent_docs/<标题>.md > /.tmp/tencent_docs/encoded_<标题>.txt # 输入为文本字符串 echo -n "# 标题\n正文内容" | base64 -w 0 > /.tmp/tencent_docs/encoded_<标题>.txt （macOS 下不需要 -w 0 参数；为当前项目工作区根目录绝对路径） 3. 使用 read_file 工具读取工作区下的输出文件（如 /.tmp/tencent_docs/encoded_<标题>.txt），获取 base64 编码后的 Markdown 内容 4. 调用 tencent-docengine 的 create_with_markdown，将读取到的内容填入 base64_markdown 参数，并传入可选的 title 5. 从返回值获取 file_url 即可访问文档 6. 如需继续编辑，使用返回的 file_id/file_url 和 last_index 调用其他 docengine 工具 ```

---

组织文档到指定目录

📖 参考文档： `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.move_file_to_space - 生成副本：manage.copy_file - 设置权限：manage.set_privilege（仅支持所有人可读和所有人可编辑） ```

---

移动文件

📖 参考文档： `manage_references.md` — 工作流十：移动文件

---

搜索文档

``` 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，无需再调用其他创建文档工具 ```