media-center/ref/tencent-docs/references/workflows.md

公共接口与常见工作流

本文件包含两部分内容：

1. 公共接口：不归属于任何特定品类的通用工具 API
2. 常见工作流：跨品类的典型操作流程

---

公共接口

get_content

功能说明：获取文档完整内容。支持所有文档类型，是读取文档内容的通用接口。

调用示例

{
  "file_id": "doc_1234567890"
}

参数说明

• file_id (string, 必填): 文档唯一标识符

返回值说明

{
  "content": "# 项目文档\n\n这是文档的完整内容...",
  "error": "",
  "trace_id": "trace_1234567890"
}

---

upload_image

功能说明：上传图片，将图片的 base64 编码上传至腾讯文档，返回有效期为一天的 imageID，可用于智能表格、智能文档等场景的图片字段。

⚠️ 重要：image_base64 参数必须传入图片文件的实际 base64 编码数据，不要传入文件路径（如 /path/to/image.png）或 URL 地址。

调用示例

{
  "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 后缀

返回值说明

{
  "image_id": "img_1234567890",
  "error": "",
  "trace_id": "trace_1234567890"
}

字段	类型	说明
image_id	string	上传成功后返回的图片 ID，有效期为一天，可用于智能表格、智能文档等场景的图片字段
error	string	错误信息，为空表示成功
trace_id	string	请求追踪 ID，用于问题排查

---

常见工作流

用 Markdown 创建 Word 文档

📖 参考文档： manage_references.md — manage.create_file；docengine_references.md — doc.get_last_operable_pos、doc.insert_markdown

通过「manage.create_file 创建空 Word 文档 + doc.insert_markdown 插入 Markdown 内容」的组合，可将 Markdown 内容写入一个新的 Word 文档。

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

1. 准备好 Markdown 格式的文档内容，将其保存为 <workspace>/.tmp/tencent_docs/<标题>.md 文件（<标题> 为文档标题）
2. 使用系统 base64 命令将 Markdown 文件编码并写入工作区目录下的文件（确保 agent 可通过 read_file 访问）：
   mkdir -p <workspace>/.tmp/tencent_docs
   # 输入为已保存的 .md 文件
   base64 -w 0 <workspace>/.tmp/tencent_docs/<标题>.md > <workspace>/.tmp/tencent_docs/encoded_<标题>.txt
   # 输入为文本字符串
   echo -n "# 标题\n正文内容" | base64 -w 0 > <workspace>/.tmp/tencent_docs/encoded_<标题>.txt
   （macOS 下不需要 -w 0 参数；<workspace> 为当前项目工作区根目录绝对路径）
3. 调用 manage.create_file（file_type=doc, title=<标题>）创建一个空 Word 文档，记下返回的 file_id
4. 调用 doc.get_last_operable_pos（传入 file_id）获取文档末尾可操作位置 position 以及当前 version
5. 使用 read_file 工具读取步骤 2 生成的 encoded_<标题>.txt，拿到 base64 编码后的 Markdown 内容
6. 调用 doc.insert_markdown，传入 file_id、index=position、base64_markdown（可选 version_info.base_version=上一步的 version），将 Markdown 写入文档
7. 如需继续编辑，使用 file_id 调用其他 docengine 工具；如需修改文档标题，调用 manage.rename_file_title

---

组织文档到指定目录

📖 参考文档： 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。

调用示例

{
  "url": "https://example.com/article",
  "content_type": "smartcanvas"
}

参数说明

• url (string, 必填): 要剪藏的网页URL地址，支持http和https协议，包括视频链接（如B站视频）
• content_type (string, 可选): 期望返回的文档格式，目前仅支持智能文档（smartcanvas）

返回值说明

{
  "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: 失败，停止轮询

调用示例

{
  "task_id": "task_1234567890",
  "parent_id": "folder_1234567890"
}

参数说明

• task_id (string, 必填): scrape_url 返回的异步任务ID
• parent_id (string, 可选): 父节点ID，为空时在空间根目录创建，不为空时在指定节点下创建

返回值说明

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