Files

T

sutong 750f981c7e feat: init media-center skill

资源中心——从多渠道获取资源链接，转存到夸克网盘并整理归档。
- sources/tencent-doc: 腾讯文档读取
- sources/search: 网盘搜索
- storage/quark: 夸克网盘操作
- ref/: 来源 skill 参考归档

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-05-16 18:28:23 +08:00

42 KiB

Raw Blame History

DOC 编辑引擎 API 参考

本文件包含腾讯文档 DOC 编辑引擎（docengine）的所有工具 API 说明。这些工具专用于 Word 文档的编辑操作，包括插入 Markdown、文本插入、替换、查找、段落设置、文本属性修改、任务插入、图片插入、分页符和表格插入等。

⚠️ 注意：本文档中的工具仅适用于 Word 文档（doc_type: word） 类型，不适用于智能文档（smartcanvas）等其他类型。

服务信息

项目	说明
所属服务	`tencent-docs`
工具前缀	`doc.*`（如 `doc.insert_markdown`、`doc.get_outline`、`doc.find` 等）
调用方式	与 tencent-docs 其他工具相同，`mcporter call "tencent-docs" "doc.<工具名>"`，无需额外配置
Token	使用 tencent-docs 统一 Token，完成授权（`references/auth.md`）后自动配置
文档类型	仅支持 Word 文档类型（`doc_type: word`）

⚠️ 所有 doc.* 工具均使用 file_id 标识文档（必填）。若用户提供的是文档链接（形如 https://docs.qq.com/doc/<file_id>），请先从链接末尾解析出 file_id 再调用。

编辑前推荐先调用 doc.get_outline 获取文档大纲结构，了解各标题和正文的可操作位置。

当用户要求「在文档开头插入」时，需向用户确认是在「文档标题之前」（使用 HEADING_LEVEL_TITLE 的 title_start）还是「正文开头/标题之后」（使用 HEADING_LEVEL_TITLE 的 content_start）插入，未明确时应主动询问。

当用户要求将结果写入 Word 文档时，推荐组合使用：1. 用 manage.create_file（file_type=doc）创建一个空白 Word 文档 2. 调用 doc.get_last_operable_pos 获取可操作位置 3. 调用 doc.insert_markdown 将 Markdown 内容写入文档。

通用说明

文档标识

所有 docengine 工具都通过 file_id 标识文档：

file_id (string, 必填): 文档唯一标识符。若用户提供的是腾讯文档链接（形如 https://docs.qq.com/doc/<file_id>），请从链接末尾解析出 file_id 再传入。

版本参数

所有 docengine 工具都支持可选的 version_info 参数，用于指定基于哪个版本进行编辑（不传时默认基于最新版本操作）：

version_info (object, 可选):
- base_version (int64, 可选): 基准版本号，通常使用上一步查询类接口（doc.get_last_operable_pos、doc.get_outline、doc.resolve_document_structure、doc.find 等）返回的 version 值，基于该版本继续编辑，确保编辑操作的连续性。值为 0 表示不指定。
- is_latest (bool, 可选): 是否基于最新版本操作。设为 true 时忽略 base_version，直接在文档最新版本上编辑。

💡 连续多步编辑时，建议将上一步查询接口返回的 version 传入下一步的 version_info.base_version，以避免并发冲突。

响应结构

编辑类 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

工具列表

工具名称	功能说明
doc.find	查找文本所在位置，返回匹配位置和上下文
doc.insert_text	在指定位置插入文本
doc.insert_paragraph	在指定位置插入段落，支持设置标题级别、编号类别和编号级别
doc.replace_text	替换指定范围内的文本
doc.find_and_replace	查找并替换文档中所有匹配的文本
doc.update_text_property	更新指定范围内文本的属性（加粗、斜体、下划线、删除线、颜色等）
doc.insert_task	在指定位置插入一个或多个任务，支持设置任务状态和内容文本
doc.insert_image	在指定位置插入图片
doc.insert_page_break	在指定位置插入分页符
doc.insert_table	在指定位置插入表格
doc.insert_comment	在指定范围插入批注
doc.replace_image	替换文档中的图片
doc.insert_markdown	在指定位置插入 Markdown 格式内容，引擎自动转换为富文本
doc.get_images	获取文档中所有图片的信息，包括图片位置（idx）、图片 URL 或附件 ID，可用于后续 doc.replace_image 操作
doc.get_last_operable_pos	获取文档末尾最后一个可操作位置的索引及前面内容
doc.get_outline	获取文档大纲结构（标题层级树），包含各标题和正文的可操作起止位置
doc.resolve_document_structure	获取文档完整结构树，返回所有块级元素（段落、标题、表格、文本框、代码块等）的层级结构和精确位置，可用于定位表格指定行列、文本框内部等复杂位置

工具详细说明

1. doc.find

功能说明

在 Word 文档中查找指定文本，返回所有匹配位置及其上下文。如果用户需要替换文本，建议先使用 doc.find 查找文本所在的各处位置，让用户确认要替换哪个位置后，再调用 doc.replace_text 进行精确替换。

调用示例

{
  "file_id": "doc_1234567890",
  "text": "要查找的文本"
}

参数说明

file_id (string, 必填): 文档唯一标识符
text (string, 必填): 要查找的文本内容
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

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

2. doc.insert_text

功能说明

在 Word 文档的指定位置插入文本。

调用示例

{
  "file_id": "doc_1234567890",
  "text": "要插入的文本内容",
  "index": 0
}

参数说明

file_id (string, 必填): 文档唯一标识符
text (string, 必填): 要插入的文本内容。注意：如果需要插入换行，应该使用插入段落操作，而不是在文本里插入 '\n' 符号
index (integer, 必填): 插入位置的索引，从 0 开始，请确认好索引后再操作
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "base_version": 1,
  "new_version": 2,
  "trace_id": "trace_1234567890",
  "err_msg": ""
}

3. doc.insert_paragraph

功能说明

在 Word 文档的指定位置插入段落。支持设置标题级别、编号类别、编号级别和缩进数量，可用于创建标题、有序/无序列表等。

调用示例

{
  "file_id": "doc_1234567890",
  "idx": 0,
  "level": "1",
  "numbering_type": "1",
  "numbering_lvl": "1",
  "indent_count": 0
}

参数说明

file_id (string, 必填): 文档唯一标识符
idx (integer, 必填): 插入位置的索引，从 0 开始
level (string, 可选): 标题级别，取值：
- "0": 未指定（保持原样）
- "1" ~ "9": 一级标题 ~ 九级标题
- "10": 正文（无标题）
- "11": 标题
- "12": 副标题
numbering_type (string, 可选): 编号类别，取值：
- "0": 未知/无编号
- "1": 圆点列表（无序列表）
- "2": 数字编号列表（有序列表）
numbering_lvl (string, 可选): 编号级别，取值 "1" ~ "9"
indent_count (integer, 可选): 缩进数量
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "base_version": 1,
  "new_version": 2,
  "trace_id": "trace_1234567890",
  "err_msg": ""
}

4. doc.replace_text

功能说明

替换 Word 文档中指定范围内的文本为新文本。建议先使用 doc.find 工具查找文本位置，让用户确认后再调用此工具进行精确替换。

调用示例

{
  "file_id": "doc_1234567890",
  "text": "替换后的文本内容",
  "ranges": [{"begin": 0, "end": 5}]
}

参数说明

file_id (string, 必填): 文档唯一标识符
text (string, 必填): 替换后的文本内容
ranges (array, 必填): 需要替换的文本范围列表，每个范围包含 begin 和 end
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "base_version": 1,
  "new_version": 2,
  "trace_id": "trace_1234567890",
  "err_msg": ""
}

5. doc.find_and_replace

功能说明

在 Word 文档中查找所有匹配的文本并直接替换为新文本。与 doc.find + doc.replace_text 的组合不同，此工具会直接替换所有匹配项，用户无法选择性地替换某个特定位置。

调用示例

{
  "file_id": "doc_1234567890",
  "old_text": "要查找的文本",
  "new_text": "替换后的文本"
}

参数说明

file_id (string, 必填): 文档唯一标识符
old_text (string, 必填): 要查找的原始文本
new_text (string, 必填): 替换后的新文本
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "base_version": 1,
  "new_version": 2,
  "trace_id": "trace_1234567890",
  "err_msg": ""
}

6. doc.update_text_property

功能说明

更新 Word 文档中指定范围内文本的属性，支持设置加粗、斜体、下划线、删除线、小型大写、字体颜色、背景颜色等。建议先使用 doc.find 工具查找文本位置，获取 range 后再调用此工具修改文本属性。

调用示例

{
  "file_id": "doc_1234567890",
  "ranges": [{"begin": 0, "end": 5}],
  "property": {
    "bold": true,
    "color": "FF0000"
  }
}

参数说明

file_id (string, 必填): 文档唯一标识符
ranges (array, 必填): 需要更新属性的文本范围列表，每个范围包含 begin 和 end
property (object, 必填): 要设置的文本属性，支持以下字段：
- bold (bool, 可选): 是否加粗
- italic (bool, 可选): 是否斜体
- underline (bool, 可选): 是否下划线
- strikethrough (bool, 可选): 是否删除线
- small_caps (bool, 可选): 是否小型大写
- color (string, 可选): 字体颜色，十六进制 RRGGBB 格式，如 "FF0000"
- background_color (string, 可选): 背景颜色，十六进制 RRGGBB 格式，如 "FFFF00"
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "base_version": 1,
  "new_version": 2,
  "trace_id": "trace_1234567890",
  "err_msg": ""
}

7. doc.insert_task

功能说明

在 Word 文档的指定位置插入一个或多个任务（待办事项）。每个任务支持设置任务状态（待办/已完成）和任务内容文本。

调用示例

插入单个任务：

{
  "file_id": "doc_1234567890",
  "idx": 0,
  "tasks": [
    {
      "state": 1,
      "content": "完成需求文档编写"
    }
  ]
}

插入多个任务：

{
  "file_id": "doc_1234567890",
  "idx": 5,
  "tasks": [
    {
      "state": 1,
      "content": "完成需求文档编写"
    },
    {
      "state": 2,
      "content": "完成接口设计"
    },
    {
      "state": 1,
      "content": "编写单元测试"
    }
  ]
}

参数说明

file_id (string, 必填): 文档唯一标识符
idx (integer, 必填): 插入位置的索引，从 0 开始
tasks (array, 必填): 任务列表，支持一次插入多个任务，每个任务包含：
- state (integer, 必填): 任务状态枚举值，不允许传递 0 值，取值：
  - 1: 待办（未完成）
  - 2: 已完成
- content (string, 必填): 任务内容文本
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "base_version": 1,
  "new_version": 2,
  "trace_id": "trace_1234567890",
  "err_msg": ""
}

doc.insert_image

功能说明

在 Word 文档的指定位置插入图片。

调用示例

{
  "file_id": "doc_1234567890",
  "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "index": 0,
  "width": 400,
  "height": 300
}

参数说明

file_id (string, 必填): 文档唯一标识符
content (string, 可选): 图片的 base64 内容，与 image_id 二选一，适合图片体积较小的场景，若图片过大导致 base64 内容超出传输限制，请改用 image_id 方式
image_id (string, 可选): 图片的 image_id，本质是对图片信息加密后的字符串，与 content 二选一。适合图片体积较大、base64 内容超出传输限制的场景。获取方式：
- 通过 upload_image MCP 接口上传图片后获取
- 通过腾讯文档开放平台 OpenAPI 图片上传接口获取（需先完成 OAuth 授权流程获取 Access-Token），示例命令：
```
curl --location --request POST 'https://docs.qq.com/openapi/resources/v2/images' \
  --header 'Access-Token: ACCESS_TOKEN' \
  --header 'Client-Id: CLIENT_ID' \
  --header 'Open-Id: OPEN_ID' \
  --form 'image=@"/path/to/your/image.png"'
```
上传成功后，取返回结果中的 imageID 字段值传入此参数
index (integer, 必填): 插入位置的索引，从 0 开始
width (integer, 可选): 图片宽度，单位为像素（px），例如 400 表示 400px；不传时使用图床上传返回的宽度
height (integer, 可选): 图片高度，单位为像素（px），例如 300 表示 300px；不传时使用图床上传返回的高度
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "base_version": 1,
  "new_version": 2,
  "trace_id": "",
  "err_msg": ""
}

9. doc.insert_page_break

功能说明

在 Word 文档的指定位置插入分页符。

调用示例

{
  "file_id": "doc_1234567890",
  "index": 10
}

参数说明

file_id (string, 必填): 文档唯一标识符
index (integer, 必填): 插入位置的索引，从 0 开始
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "base_version": 1,
  "new_version": 2,
  "trace_id": "trace_1234567890",
  "err_msg": ""
}

10. doc.insert_table

功能说明

在 Word 文档的指定位置插入表格。

调用示例

{
  "file_id": "doc_1234567890",
  "index": 0,
  "rows": 3,
  "cols": 4
}

参数说明

file_id (string, 必填): 文档唯一标识符
index (integer, 必填): 插入位置的索引，从 0 开始
rows (integer, 必填): 表格行数
cols (integer, 必填): 表格列数
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "base_version": 1,
  "new_version": 2,
  "trace_id": "trace_1234567890",
  "err_msg": ""
}

11. doc.insert_comment

功能说明

在 Word 文档的指定范围内插入批注（评论）。注意：插入批注后文本长度会发生变化，如果需要继续操作应该重新获取位置。

调用示例

{
  "file_id": "doc_1234567890",
  "text": "这里需要修改措辞",
  "range": {"begin": 5, "end": 15}
}

参数说明

file_id (string, 必填): 文档唯一标识符
text (string, 必填): 批注内容
range (object, 必填): 批注关联的文本范围，包含 begin 和 end
ref_id (string, 可选): 评论ID，用于回复已有批注
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "base_version": 1,
  "new_version": 2,
  "trace_id": "trace_1234567890",
  "err_msg": ""
}

12. doc.get_images

功能说明

获取 Word 文档中所有图片的信息，包括每张图片的位置索引（pos）、来源类型（URL 图片或附件图片）以及对应的 URL 或附件 ID。通常在调用 doc.replace_image 前先调用此接口，获取目标图片的 pos（即 idx）和 image_url/attachment_id（即 old_image_url/old_attachment_id）。

调用示例

{
  "file_id": "doc_1234567890"
}

参数说明

file_id (string, 必填): 文档唯一标识符
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "images": [
    {
      "source": 1,
      "pos": 42,
      "image_url": "https://docimg8.docs.qq.com/image/AgAABsUhABzwC7ScF1dHP4mZWR9jTQ5i.jpeg"
    },
    {
      "source": 2,
      "pos": 88,
      "attachment_id": "AgAABsUhABzwC7ScF1dHP4mZWR9jTQ5i"
    }
  ],
  "version": 1024
}

images (array): 文档中所有图片列表，按位置（pos）升序排列
- source (int): 图片来源类型，1 = URL 图片（FromLink），2 = 附件图片（FromAttachment）
- pos (int64): 图片在文档中的位置索引，即 doc.replace_image 接口的 idx 参数
- image_url (string): 当 source=1 时有值，图片的内嵌 URL，即 doc.replace_image 接口的 old_image_url 参数
- attachment_id (string): 当 source=2 时有值，附件图片的 object_key，即 doc.replace_image 接口的 old_attachment_id 参数
version (int64): 当前文档版本号

12. doc.replace_image

功能说明

替换 Word 文档中的图片。必须同时提供三组参数：

idx（图片位置）
old_image_url 或 old_attachment_id（定位旧图片）
image_id 或 content（指定新图片）

缺少任何一组都会导致替换失败。建议先调用 get_images 获取图片信息，再用返回的 pos 和 image_url/attachment_id 填入对应参数。

⚠️ 重要提示：

old_image_url 中不要带查询参数（如 ?w=300&h=281），需去掉问号及之后的部分，否则 C++ 层做精确字符串匹配时会匹配失败

get_images 返回的 pos 是 int64 类型，经 protobuf JSON 序列化后为字符串（如 "12"），传入 idx 时请转为整数

调用示例

{
  "file_url": "https://docs.qq.com/doc/xxxxxxxx",
  "idx": 12,
  "old_image_url": "https://docimg3.docs.qq.com/image/AgAABsUhABzuGm3nPThHvJMLVLu3pZUz.png",
  "image_id": "KlCYcLj1CTUoMfAR9bleB+G+..."
}

参数说明

file_id (string, 可选): 文档唯一标识符，与 file_url 二选一
file_url (string, 可选): 腾讯文档的文档链接，与 file_id 二选一
idx (integer, 必填): 图片在文档中的位置索引，对应 get_images 返回的 pos 字段
old_image_url (string, 条件必填): 旧图片的 URL，与 old_attachment_id 二选一（必须提供其一），对应 get_images 返回的 image_url 字段。注意：URL 中不要带查询参数（如 ?w=300&h=281），需去掉问号及之后的部分
old_attachment_id (string, 条件必填): 旧图片的附件 ID，与 old_image_url 二选一（必须提供其一），对应 get_images 返回的 attachment_id 字段
image_id (string, 条件必填): 新图片的 image_id，本质是对图片信息加密后的字符串，与 content 二选一（必须提供其一）。获取方式：
- 通过 upload_image MCP 接口上传图片后获取
- 通过腾讯文档开放平台 OpenAPI 图片上传接口获取。注意：调用开放平台接口前，需先完成 OAuth 授权流程获取 Access-Token（参考开放平台登录授权文档），示例命令：
```
curl --location --request POST 'https://docs.qq.com/openapi/resources/v2/images' \
  --header 'Access-Token: ACCESS_TOKEN' \
  --header 'Client-Id: CLIENT_ID' \
  --header 'Open-Id: OPEN_ID' \
  --form 'image=@"/path/to/your/image.png"'
```
上传成功后，取返回结果中的 imageID 字段值传入此参数。注意：调用开放平台接口前，需先完成 OAuth 授权流程获取 Access-Token；此方式适合图片体积较大、base64 内容超出传输限制的场景
content (string, 可选): 新图片的 base64 内容，与 image_id 二选一。适合图片体积较小的场景；若图片过大导致 base64 内容超出限制，请改用 image_id 方式
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "base_version": 1,
  "new_version": 2,
  "trace_id": "trace_1234567890",
  "err_msg": ""
}

13. doc.insert_markdown

功能说明

在 Word 文档的指定位置插入 Markdown 格式内容。引擎会自动将 Markdown 转换为文档富文本格式，支持标题、列表、表格、链接、加粗/斜体等常见 Markdown 语法。适合需要批量插入富文本内容的场景，比直接调用多个 insert_text/insert_paragraph 更高效。

⚠️ 推荐使用 base64_markdown 参数：由于 Markdown 内容中可能包含特殊字符（如换行符、引号等），直接传递 markdown 参数容易导致 JSON 解析问题。建议 agent 先将 Markdown 内容进行 base64 编码后，通过 base64_markdown 参数传递。如果填写了 base64_markdown，则无需再填写 markdown。

调用示例

使用 base64_markdown（推荐）：

{
  "file_id": "doc_1234567890",
  "index": 0,
  "base64_markdown": "IyDmoIfpopgKCui/meaYr+S4gOautSoq5Yqg57KXKirmlofmnKzjgIIKCi0g5YiX6KGo6aG5MQotIOWIl+ihqOmhuTIKCnwg5aeT5ZCNIHwg5bm06b6EIHwKfC0tLS0tLXwtLS0tLS18Cnwg5byg5LiJIHwgMjUgfA==",
  "version_info": {
    "base_version": 5,
    "is_latest": false
  }
}

使用 markdown（备选）：

{
  "file_id": "doc_1234567890",
  "index": 0,
  "markdown": "# 标题\n\n这是一段**加粗**文本。\n\n- 列表项1\n- 列表项2\n\n| 姓名 | 年龄 |\n|------|------|\n| 张三 | 25 |"
}

参数说明

file_id (string, 必填): 文档唯一标识符
index (integer, 必填): 插入位置的索引，从 0 开始
base64_markdown (string, ⭐ 首选): Markdown 内容的 base64 编码字符串。推荐优先使用此参数，agent 需要先将 Markdown 文本进行标准 base64 编码后传入。与 markdown 二选一，如果填写了 base64_markdown 则无需再填写 markdown
markdown (string, 备选): Markdown 格式的原始文本内容，与 base64_markdown 二选一。当未提供 base64_markdown 时使用此参数。支持以下语法：
- 标题：# H1、## H2、### H3 等
- 加粗/斜体：**加粗**、*斜体*
- 链接：[文本](URL)
- 无序列表：- 列表项
- 有序列表：1. 列表项
- 表格：使用 | 和 --- 语法
- 代码块：使用反引号包裹
version_info (object, 可选): 版本控制参数，用于指定基于哪个版本进行编辑。不传时默认基于最新版本操作。包含以下字段：
- base_version (int64, 可选): 基准版本号，通常使用 doc.get_last_operable_pos、doc.get_outline 或 doc.resolve_document_structure 返回的 version 值，基于该版本继续编辑，确保编辑操作的连续性。值为 0 表示不指定
- is_latest (bool, 可选): 是否基于最新版本操作。设为 true 时忽略 base_version，直接在文档最新版本上编辑

💡 version_info 使用场景：当需要连续执行多步编辑操作时（如先 doc.get_outline 获取大纲，再 doc.insert_markdown 插入内容），建议将前一步返回的 version 传入 version_info.base_version，以确保编辑基于同一版本，避免并发冲突。

返回值说明

{
  "base_version": 1,
  "new_version": 2,
  "trace_id": "trace_1234567890",
  "err_msg": ""
}

base_version (int64): 文档的基准版本号
new_version (int64): 命令执行之后的文档版本
trace_id (string): 本次调用的链路追踪 ID
err_msg (string): 失败信息

14. doc.get_last_operable_pos

功能说明

获取 Word 文档正文（main story）最后一个可操作位置的索引，以及该位置前面最多 10 个字符的内容。在需要向文档末尾追加内容时，可先调用此接口获取末尾可操作位置，再使用 doc.insert_text/doc.insert_image 等接口在该位置插入内容。

调用示例

{
  "file_id": "doc_1234567890"
}

参数说明

file_id (string, 必填): 文档唯一标识符
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "position": 100,
  "preceding_text": "...前面内容...",
  "version": 1
}

position (int64): 最后一个可操作位置的索引
preceding_text (string): 该位置前面最多 10 个字符的内容
version (int64): 当前文档版本号

15. doc.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

如果用户未明确说明，应主动询问确认。

调用示例

{
  "file_id": "doc_1234567890"
}

参数说明

file_id (string, 必填): 文档唯一标识符
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "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): 当前文档版本号

16. doc.resolve_document_structure

功能说明

获取 Word 文档的完整结构树（DOC），返回 main story 下所有块级元素的层级结构和位置信息。与 doc.get_outline 只返回标题层级不同，此接口返回所有块级元素，包括：

Paragraph：普通文本段落
Heading：标题段落（含级别）
Table：表格（含每行每列的起止位置）
TextBox：文本框（含内部段落的起止位置）
CodeBlock：代码块（含内部段落的起止位置）

适用场景：

需要在表格指定行列插入或修改文本（通过 table_rows[row].cells[col].end_index 定位单元格末尾）
需要在文本框内部插入内容（通过 children 中的段落位置定位）
需要了解文档完整布局后再决定操作位置
需要精确获取某个段落、代码块的起止范围

调用示例

{
  "file_id": "doc_1234567890"
}

参数说明

file_id (string, 必填): 文档唯一标识符
version_info (object, 可选): 版本参数，详见《通用说明 > 版本参数》

返回值说明

{
  "nodes": [
    {
      "type": "Heading",
      "start_index": 0,
      "end_index": 6,
      "text_preview": "文档标题",
      "heading_level": 1,
      "logical_index": 1,
      "table_rows": [],
      "children": []
    },
    {
      "type": "Paragraph",
      "start_index": 7,
      "end_index": 20,
      "text_preview": "这是第一段正文内容",
      "heading_level": 0,
      "logical_index": 2,
      "table_rows": [],
      "children": []
    },
    {
      "type": "Table",
      "start_index": 21,
      "end_index": 60,
      "text_preview": "",
      "heading_level": 0,
      "logical_index": 3,
      "table_rows": [
        {
          "row": 1,
          "cells": [
            { "row": 1, "col": 1, "start_index": 22, "end_index": 30, "text_preview": "单元格内容" },
            { "row": 1, "col": 2, "start_index": 31, "end_index": 38, "text_preview": "" }
          ]
        },
        {
          "row": 2,
          "cells": [
            { "row": 2, "col": 1, "start_index": 40, "end_index": 48, "text_preview": "" },
            { "row": 2, "col": 2, "start_index": 49, "end_index": 57, "text_preview": "" }
          ]
        }
      ],
      "children": []
    },
    {
      "type": "TextBox",
      "start_index": 61,
      "end_index": 80,
      "text_preview": "文本框内容",
      "heading_level": 0,
      "logical_index": 4,
      "table_rows": [],
      "children": [
        {
          "type": "Paragraph",
          "start_index": 62,
          "end_index": 79,
          "text_preview": "文本框内容",
          "heading_level": 0,
          "logical_index": 1,
          "table_rows": [],
          "children": []
        }
      ]
    },
    {
      "type": "CodeBlock",
      "start_index": 81,
      "end_index": 110,
      "text_preview": "console.log('hello')",
      "heading_level": 0,
      "logical_index": 5,
      "table_rows": [],
      "children": [
        {
          "type": "Paragraph",
          "start_index": 82,
          "end_index": 109,
          "text_preview": "console.log('hello')",
          "heading_level": 0,
          "logical_index": 1,
          "table_rows": [],
          "children": []
        }
      ]
    }
  ],
  "version": 5,
  "total_paragraphs": 3,
  "total_headings": 1,
  "total_tables": 1
}

nodes (array): 顶层块级节点列表（main story 直接子节点），按文档顺序排列，每个节点包含：
- type (string): 节点类型，取值：Paragraph、Heading、Table、TextBox、CodeBlock、HighlightBlock
- start_index (uint32): 节点起始位置（inclusive）
- end_index (uint32): 节点结束位置（在此处插入可追加到节点末尾）
- text_preview (string): 文本预览，最多 50 字符，仅 Paragraph/Heading 有值。文本中可能包含以下占位符标记，表示段落内嵌入的非文字元素：
  - [Image]：嵌入的图片
  - [Math]：数学公式
  - [TextBox]：嵌入的文本框/代码块/高亮块锚点（对应的 TextBox/CodeBlock/HighlightBlock 节点会作为独立的顶层节点出现在 nodes 中）
  - [Drawing]：其他嵌入的图形/形状对象
  - [Hyperlink]：超链接（普通链接、文档链接、附件链接等）
  - [addonHina]：内嵌插件（流程图、思维导图、白板、内嵌表格等腾讯文档内嵌的第三方插件内容）
- heading_level (int32): 标题级别 1-9，仅 Heading 类型有值，其余为 0
- logical_index (int32): 在同级中的逻辑序号（从 1 开始）
- table_rows (array): 仅 Table 类型有值，包含行列结构：
  - row (int32): 行号（从 1 开始）
  - cells (array): 该行所有单元格：
    - row (int32): 行号（从 1 开始）
    - col (int32): 列号（从 1 开始）
    - start_index (uint32): 单元格起始位置
    - end_index (uint32): 单元格结束位置（在此处插入可追加到单元格末尾）
    - text_preview (string): 单元格文本预览，最多 30 字符，可能包含 [Image]/[TextBox]/[Drawing]/[Hyperlink]/[addonHina] 等占位符标记（含义同上）
- children (array): 子节点列表，TextBox/CodeBlock 内部的段落等
version (int64): 当前文档版本号
total_paragraphs (int32): 正文段落总数（不含标题）
total_headings (int32): 标题总数
total_tables (int32): 表格总数

典型工作流示例

用 Markdown 创建 Word 文档（推荐）

1. 准备好 Markdown 格式的文档内容，将其保存为 <workspace>/.tmp/tencent_docs/<标题>.md 文件（<标题> 为文档标题）
2. 使用系统 base64 命令进行编码，并将结果写入工作区目录下的文件（确保 agent 可通过 read_file 访问）：
   mkdir -p <workspace>/.tmp/tencent_docs
   base64 -w 0 <workspace>/.tmp/tencent_docs/<标题>.md > <workspace>/.tmp/tencent_docs/encoded_<标题>.txt
   或：echo -n "Markdown文本" | base64 -w 0 > <workspace>/.tmp/tencent_docs/encoded_<标题>.txt
   （macOS 上无需 -w 0 参数；<workspace> 为当前项目工作区根目录绝对路径）
3. 调用 manage.create_file 创建一个空 Word 文档（file_type=doc），获取返回的 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. 如需修改文档标题，调用 manage.rename_file_title

编辑已有 Word 文档

1. 调用 doc.get_outline 获取文档大纲结构，了解文档的标题层级和各区域的可操作位置
   （如需精确定位表格行列、文本框内部等，改用 doc.resolve_document_structure）
2. 根据大纲定位目标区域，或调用 doc.find 查找具体文本位置
3. 按需调用工具进行编辑：
   - 插入文本：doc.insert_text
   - 插入段落：doc.insert_paragraph
   - 替换文本：doc.replace_text
   - 全文替换：doc.find_and_replace
   - 修改文本样式：doc.update_text_property
   - 插入任务：doc.insert_task
   - 插入图片：doc.insert_image
   - 替换图片：doc.replace_image
   - 插入分页符：doc.insert_page_break
   - 插入表格：doc.insert_table
   - 插入批注：doc.insert_comment
   - 获取文档大纲：doc.get_outline
   - 获取完整结构树：doc.resolve_document_structure

查找并替换文本（精确替换）

1. 调用 doc.find 查找目标文本，获取所有匹配位置
2. 将匹配结果展示给用户，让用户选择要替换的位置
3. 调用 doc.replace_text 传入对应的 range 进行精确替换

查找并替换文本（全部替换）

1. 直接调用 doc.find_and_replace，一次性替换所有匹配项

格式化文本

1. 调用 doc.find 查找目标文本，获取文本的 range
2. 调用 doc.update_text_property 设置文本属性（加粗、颜色等）

向文档末尾追加内容

1. 调用 doc.get_last_operable_pos 获取文档末尾可操作位置
2. 使用返回的 position 作为 index，调用 doc.insert_text / doc.insert_image / doc.insert_table 等工具追加内容

在指定标题下插入内容

1. 调用 doc.get_outline 获取文档大纲，找到目标标题节点
2. 使用节点的 content_start 作为插入位置（在标题下方开头插入）
   或使用 content_end 作为插入位置（在标题下方正文末尾追加）
3. 调用 doc.insert_text / doc.insert_paragraph / doc.insert_image 等工具在对应位置插入内容

在文档开头插入内容

1. 调用 doc.get_outline 获取文档大纲
2. 明确用户意图——是要在「文档标题前」还是「正文开头」插入：
   - 文档标题前：使用 HEADING_LEVEL_TITLE 节点的 title_start 作为插入位置
   - 正文开头（标题之后）：使用 HEADING_LEVEL_TITLE 节点的 content_start 作为插入位置
3. 如果用户未明确说明，应主动询问用户确认具体插入位置
4. 确认位置后，调用 doc.insert_text / doc.insert_paragraph 等工具在对应位置插入内容

在表格指定行列插入文本

1. 调用 doc.resolve_document_structure 获取文档完整结构树
2. 在返回的 nodes 中找到目标 Table 节点
3. 通过 table_rows[row-1].cells[col-1].end_index 获取目标单元格的末尾位置
4. 调用 doc.insert_text，将 index 设为该 end_index，即可在指定单元格末尾插入文本

在文本框内部插入内容

1. 调用 doc.resolve_document_structure 获取文档完整结构树
2. 在返回的 nodes 中找到目标 TextBox 节点
3. 通过 children 中的段落节点获取内部精确位置
4. 调用 doc.insert_text / doc.insert_paragraph 在对应位置插入内容

为文本添加批注

1. 调用 doc.find 查找目标文本，获取文本的 range（begin/end）
2. 调用 doc.insert_comment 传入 range 和批注内容

替换文档中的图片

1. 调用 doc.get_images 获取文档中所有图片信息，包括图片位置（pos/idx）和 URL/ID
2. 根据返回的 pos（作为 idx）和 url/id（作为 old_url/old_id）定位目标图片
3. 调用 doc.replace_image 传入对应参数完成图片替换

注意事项

仅支持 Word 文档类型（doc_type: word）
index / idx 参数表示插入位置，从 0 开始计数
操作前需确保拥有文档的写入权限
replace_text 的 ranges 参数中 begin 和 end 必须在文档有效范围内
替换文本的推荐流程：先调用 doc.find 查找定位，让用户确认后再用 doc.replace_text 精确替换；如果需要全部替换可直接使用 doc.find_and_replace
所有 doc.* 工具均使用 file_id 标识文档（必填）；若用户提供的是文档链接（形如 https://docs.qq.com/doc/<file_id>），需先从链接末尾解析出 file_id 再传入
所有 doc.* 工具都支持可选的 version_info（base_version / is_latest），连续多步编辑时建议将上一步查询返回的 version 传入下一步的 version_info.base_version，避免并发冲突
doc.get_last_operable_pos 返回的 position 即为文档末尾可安全插入内容的位置
doc.get_outline 返回树形大纲结构，每个节点的 content_start/content_end 表示该标题下正文区域的可操作范围，可直接用作 doc.insert_text 等工具的 index 参数
「在文档开头插入」需明确位置：用户要求在文档开头插入内容时，应先通过 doc.get_outline 获取大纲，区分「文档标题前」（HEADING_LEVEL_TITLE 的 title_start）和「正文开头」（HEADING_LEVEL_TITLE 的 content_start），并向用户确认具体插入位置
doc.resolve_document_structure 返回所有块级元素的完整结构树，table_rows[row].cells[col].end_index 即为对应单元格末尾可插入位置；TextBox/CodeBlock 的内部段落通过 children 字段获取；logical_index 表示节点在同级中的顺序（从 1 开始）
快速用 Markdown 生成 Word 文档的推荐组合方式：1. manage.create_file（file_type=doc）创建空文档 → 2. doc.get_last_operable_pos 获取插入位置 → 3. doc.insert_markdown 写入内容
doc.insert_comment 的 range 必须在文档有效范围内，建议先用 doc.find 获取精确范围
doc.replace_image 需要通过 old_image_url 或 old_attachment_id 定位旧图片，新图片通过 image_id 或 content（base64）指定

42 KiB Raw Blame History Unescape Escape

DOC 编辑引擎 API 参考

服务信息

通用说明

文档标识

版本参数

响应结构

工具列表

工具详细说明

1. doc.find

功能说明

调用示例

参数说明

返回值说明

推荐使用流程

2. doc.insert_text

功能说明

调用示例

参数说明

返回值说明

3. doc.insert_paragraph

功能说明

调用示例

参数说明

返回值说明

4. doc.replace_text

功能说明

调用示例

参数说明

返回值说明

5. doc.find_and_replace

功能说明

调用示例

参数说明

返回值说明

6. doc.update_text_property

功能说明

调用示例

参数说明

返回值说明

7. doc.insert_task

功能说明

调用示例

参数说明

返回值说明

doc.insert_image

功能说明

调用示例

参数说明

返回值说明

9. doc.insert_page_break

功能说明

调用示例

参数说明

返回值说明

10. doc.insert_table

功能说明

调用示例

参数说明

返回值说明

11. doc.insert_comment

功能说明

调用示例

参数说明

返回值说明

12. doc.get_images

功能说明

调用示例

参数说明

返回值说明

推荐使用流程

12. doc.replace_image

功能说明

调用示例

参数说明

返回值说明

13. doc.insert_markdown

功能说明

调用示例

参数说明

42 KiB

Raw Blame History