DOC 编辑引擎 API 参考
本文件包含腾讯文档 DOC 编辑引擎（docengine）的所有工具 API 说明。这些工具专用于 Word 文档的编辑操作，包括用 Markdown 创建文档（create_with_markdown）、插入markdown(一般与创建文档组合使用，1.创建文档 2.插入markdown)，文本插入、替换、查找、段落设置、文本属性修改、任务插入、图片插入、分页符和表格插入等。
> ⚠️ 注意：本文档中的工具仅适用于 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`）插入，未明确时应主动询问。 > > 当用户要求将结果写入文档时, 推荐使用 `create_with_markdown` 一步创建 Word 文档；也可以与创建文档manage.create_file组合使用，1.创建word文档 2.获取插入位置get_last_operable_pos 3.插入markdown(insert_markdown)
---
通用说明
文档标识
所有 docengine 工具都支持两种文档标识方式（二选一）：
> 💡 推荐优先使用 `file_url`：用户通常会直接提供文档链接，使用 `file_url` 无需额外解析 `file_id`，更加便捷。
响应结构
编辑类 API 返回：
查询类 API（如 find）返回：
---
工具列表
| 工具名称 | 功能说明 | |---------|---------| | create_with_markdown | 用 Markdown 创建 Word 文档，一步完成文档创建和内容写入 | | 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 | 替换文档中的图片 | | insert_markdown | 在指定位置插入 Markdown 格式内容，引擎自动转换为富文本 | | get_images | 获取文档中所有图片的信息，包括图片位置（idx）、图片 URL 或附件 ID，可用于后续 replace_image 操作 | | get_last_operable_pos | 获取文档末尾最后一个可操作位置的索引及前面内容 | | get_outline | 获取文档大纲结构（标题层级树），包含各标题和正文的可操作起止位置 | | resolve_document_structure | 获取文档完整结构树，返回所有块级元素（段落、标题、表格、文本框、代码块等）的层级结构和精确位置，可用于定位表格指定行列、文本框内部等复杂位置 |
---
工具详细说明
0. create_with_markdown
功能说明
用 Markdown 内容直接创建一篇新的 Word 文档（DOC）。无需先调用 `manage.create_file` 再 `insert_markdown`，一步完成文档创建和内容写入。适合需要快速将 Markdown 格式内容生成为 Word 文档的场景。> ⚠️ 推荐使用 `base64_markdown` 参数：由于 Markdown 内容中可能包含特殊字符（如换行符、引号等），直接传递可能导致 JSON 解析问题。建议先将 Markdown 内容进行 base64 编码后，通过 `base64_markdown` 参数传递。
调用示例
使用 base64_markdown（推荐）： ```json { "base64_markdown": "IyDmoIfpopgKCui/meaYr+S4gOautSoq5Yqg57KXKirmlofmnKzjgIIKCi0g5YiX6KGo6aG5MQotIOWIl+ihqOmhuTIKCnwg5aeT5ZCNIHwg5bm06b6EIHwKfC0tLS0tLXwtLS0tLS18Cnwg5byg5LiJIHwgMjUgfA==", "title": "我的文档" } ```参数说明
返回值说明
```json { "file_id": "doc_1234567890", "file_url": "https://docs.qq.com/doc/xxxxxxxx", "version": 1, "last_index": 100 } ```推荐使用流程
1. 准备好 Markdown 格式的文档内容，将其保存为 `---
1. find
功能说明
在 Word 文档中查找指定文本，返回所有匹配位置及其上下文。如果用户需要替换文本，建议先使用 `find` 查找文本所在的各处位置，让用户确认要替换哪个位置后，再调用 `replace_text` 进行精确替换。调用示例
```json { "file_url": "https://docs.qq.com/doc/xxxxxxxx", "text": "要查找的文本" } ```参数说明
返回值说明
```json { "text_and_locations": [ { "range": { "begin": 10, "end": 15 }, "related_text": "...上下文文本..." } ], "read_result": { "version": 1, "trace_id": "trace_1234567890" } } ```推荐使用流程
1. 调用 `find` 查找目标文本，获取所有匹配位置 2. 将匹配结果展示给用户，让用户选择要替换的位置 3. 根据用户选择，调用 `replace_text` 传入对应的 `range` 进行替换---
2. insert_text
功能说明
在 Word 文档的指定位置插入文本。调用示例
```json { "file_url": "https://docs.qq.com/doc/xxxxxxxx", "text": "要插入的文本内容", "index": 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 } ```参数说明
返回值说明
```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}] } ```参数说明
返回值说明
```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": "替换后的文本" } ```参数说明
返回值说明
```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" } } ```参数说明
返回值说明
```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": "编写单元测试" } ] } ```参数说明
返回值说明
```json { "base_version": 1, "new_version": 2, "trace_id": "trace_1234567890", "err_msg": "" } ```---
insert_image
#### 功能说明 在 Word 文档的指定位置插入图片。
#### 调用示例 ```json { "file_id": "doc_1234567890", "file_url": "https://docs.qq.com/doc/xxxxxxxx", "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "index": 0, "width": 400, "height": 300 } ```
#### 参数说明
#### 返回值说明 ```json { "base_version": 1, "new_version": 2, "trace_id": "", "err_msg": "" } ```
---
9. insert_page_break
功能说明
在 Word 文档的指定位置插入分页符。调用示例
```json { "file_url": "https://docs.qq.com/doc/xxxxxxxx", "index": 10 } ```参数说明
返回值说明
```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 } ```参数说明
返回值说明
```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} } ```参数说明
返回值说明
```json { "base_version": 1, "new_version": 2, "trace_id": "trace_1234567890", "err_msg": "" } ```---
12. get_images
#### 功能说明 获取 Word 文档中所有图片的信息，包括每张图片的位置索引（`pos`）、来源类型（URL 图片或附件图片）以及对应的 URL 或附件 ID。通常在调用 `replace_image` 前先调用此接口，获取目标图片的 `pos`（即 `idx`）和 `image_url`/`attachment_id`（即 `old_image_url`/`old_attachment_id`）。
调用示例
```json { "file_url": "https://docs.qq.com/doc/xxxxxxxx" } ```参数说明
返回值说明
```json { "images": [ { "source": 1, "pos": 42, "image_url": "https://docimg8.docs.qq.com/image/AgAABsUhABzwC7ScF1dHP4mZWR9jTQ5i.jpeg" }, { "source": 2, "pos": 88, "attachment_id": "AgAABsUhABzwC7ScF1dHP4mZWR9jTQ5i" } ], "version": 1024 } ```推荐使用流程
1. 调用 `get_images` 获取文档中所有图片信息 2. 根据返回的 `pos`（作为 `idx`）和 `image_url`/`attachment_id`（作为 `old_image_url`/`old_attachment_id`）定位目标图片 3. 调用 `replace_image` 传入对应参数完成图片替换---
12. replace_image
功能说明
替换 Word 文档中的图片。可以通过旧图片的 URL 或 ID 定位要替换的图片，并指定新图片。调用示例
```json { "file_id": "doc_1234567890", "file_url": "https://docs.qq.com/doc/xxxxxxxx", "idx": 0, "old_image_url": "https://example.com/old_image.png", "image_id": "eyJVUkwiOiJodHRwczovL2V4YW1wbGUuY29tL25ld19pbWFnZS5wbmcifQ==" } ```#### 参数说明
返回值说明
```json { "base_version": 1, "new_version": 2, "trace_id": "trace_1234567890", "err_msg": "" } ```---
13. 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（推荐）： ```json { "file_url": "https://docs.qq.com/doc/xxxxxxxx", "index": 0, "base64_markdown": "IyDmoIfpopgKCui/meaYr+S4gOautSoq5Yqg57KXKirmlofmnKzjgIIKCi0g5YiX6KGo6aG5MQotIOWIl+ihqOmhuTIKCnwg5aeT5ZCNIHwg5bm06b6EIHwKfC0tLS0tLXwtLS0tLS18Cnwg5byg5LiJIHwgMjUgfA==", "version_info": { "base_version": 5, "is_latest": false } } ``` 使用 markdown（备选）： ```json { "file_url": "https://docs.qq.com/doc/xxxxxxxx", "index": 0, "markdown": "# 标题\n\n这是一段加粗文本。\n\n- 列表项1\n- 列表项2\n\n| 姓名 | 年龄 |\n|------|------|\n| 张三 | 25 |" } ```参数说明
> 💡 version_info 使用场景：当需要连续执行多步编辑操作时（如先 `get_outline` 获取大纲，再 `insert_markdown` 插入内容），建议将前一步返回的 `version` 传入 `version_info.base_version`，以确保编辑基于同一版本，避免并发冲突。
返回值说明
```json { "base_version": 1, "new_version": 2, "trace_id": "trace_1234567890", "err_msg": "" } ```---
14. get_last_operable_pos
功能说明
获取 Word 文档正文（main story）最后一个可操作位置的索引，以及该位置前面最多 10 个字符的内容。在需要向文档末尾追加内容时，可先调用此接口获取末尾可操作位置，再使用 `insert_text`/`insert_image` 等接口在该位置插入内容。调用示例
```json { "file_url": "https://docs.qq.com/doc/xxxxxxxx" } ```参数说明
返回值说明
```json { "position": 100, "preceding_text": "...前面内容...", "version": 1 } ```---
15. get_outline
功能说明
获取 Word 文档的完整大纲结构（树形），返回文档标题、各级标题及其下正文的可操作位置范围。可用于：> ⚠️ 关于「在文档开头插入」的位置说明：文档大纲的根节点通常是 `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" } ```参数说明
返回值说明
```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 } ```---
16. resolve_document_structure
功能说明
获取 Word 文档的完整结构树（DOC），返回 main story 下所有块级元素的层级结构和位置信息。与 `get_outline` 只返回标题层级不同，此接口返回所有块级元素，包括：适用场景：
调用示例
```json { "file_url": "https://docs.qq.com/doc/xxxxxxxx" } ```参数说明
返回值说明
```json { "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 } ```---
典型工作流示例
用 Markdown 创建 Word 文档（推荐）
```
1. 准备好 Markdown 格式的文档内容，将其保存为
编辑已有 Word 文档
``` 1. 调用 get_outline 获取文档大纲结构，了解文档的标题层级和各区域的可操作位置 （如需精确定位表格行列、文本框内部等，改用 resolve_document_structure） 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 - 获取完整结构树：resolve_document_structure ```
查找并替换文本（精确替换）
``` 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. 调用 resolve_document_structure 获取文档完整结构树 2. 在返回的 nodes 中找到目标 Table 节点 3. 通过 table_rows[row-1].cells[col-1].end_index 获取目标单元格的末尾位置 4. 调用 insert_text，将 index 设为该 end_index，即可在指定单元格末尾插入文本 ```
在文本框内部插入内容
``` 1. 调用 resolve_document_structure 获取文档完整结构树 2. 在返回的 nodes 中找到目标 TextBox 节点 3. 通过 children 中的段落节点获取内部精确位置 4. 调用 insert_text / insert_paragraph 在对应位置插入内容 ```
为文本添加批注
``` 1. 调用 find 查找目标文本，获取文本的 range（begin/end） 2. 调用 insert_comment 传入 range 和批注内容 ```
替换文档中的图片
``` 1. 调用 get_images 获取文档中所有图片信息，包括图片位置（pos/idx）和 URL/ID 2. 根据返回的 pos（作为 idx）和 url/id（作为 old_url/old_id）定位目标图片 3. 调用 replace_image 传入对应参数完成图片替换 ```
---