| name | document-editing |
| description | 二进制文档（DOCX/XLSX/PPTX）部分编辑：检索定位 → skill 编辑 → ES Copy-on-Write 快照 |
| metadata | {"tags":["document","editing","docx","xlsx","pptx"],"emoji":"📝"} |
Document Editing — 二进制文档部分编辑
⚠️ 与 docx/xlsx/pptx skill 的关系
| Skill | 职责 | 何时使用 |
|---|
| document-editing (本 skill) | 工作流编排：ES 检索 → 定位 → 调用技术 skill → ES 快照更新 | 编辑知识库中的文档 |
| docx/xlsx/pptx skill | 技术实现：XML 操作 / 格式处理 / 创建新文档 | 编辑本地文件 或 被 document-editing 调用 |
关键流程：本 skill 负责「找到位置」，技术 skill 负责「修改内容」。
适用场景
用户需要修改、分析、对比知识库中的 DOCX / XLSX / PPTX 等二进制文档。
前置条件
- 文档已在知识库中（已被 DeepDoc 解析，ES 中有 chunks）
- chunks 包含位置信息（
para_range / row_range / slide_num）
⚡ ES-first 原则 — 二进制文档有 ES 时优先用 ES
核心规则：二进制文档（docx/xlsx/pptx）经过 copy_kb_document 或 snapshot_and_index 后就拥有 ES chunks。读取这些文档的内容时，必须优先走 ES search，不要用 read_file。
read_file 读二进制文档 = 把整个文档转成纯文本塞进 context，丢失结构信息、浪费 token、还需要写代码二次解析。ES search 直接返回精确 chunk + 段落位置。
工具选择决策表
| 我要做什么 | 用什么 | 为什么 |
|---|
| 查某个需求/条款的内容 | unified_search(query="关键词", doc_ids="ws_doc_id") | 返回精确 chunk + 段落位置，token 友好 |
| 对比两份文档的差异 | 对每个对比项分别搜两个文档的 ws_doc_id | 逐条精确对比，不需要读整个文档 |
| 列出文档全部内容 | unified_search(action="list_chunks", doc_ids="ws_doc_id") | 结构化分片，带位置信息 |
| 提取文档中的特定模式（如所有编号） | unified_search(query="编号模式关键词", doc_ids="ws_doc_id") | 比正则扫描全文更快 |
| 修改文档二进制结构（XML/格式/超链接/高亮） | execute_code（下载 docx → 操作 → upload） | 需要操作二进制格式 |
| 在文档中插入新段落/章节 | execute_code + docx_utils.insert_paragraphs_after() | 禁止用 doc.add_paragraph()，会在末尾产生重复 |
| 读取纯文本文件（.md / .py / .json） | read_file | 纯文本文件没有 ES 索引 |
反面案例
❌ 错误：用 read_file 读整个 docx 来提取需求列表
→ 消耗大量 tokens，丢失结构信息，还需要写代码解析
✅ 正确：unified_search(query="FUNC_0007", doc_ids="ws_...")
→ 直接返回该需求的 chunk（含段落范围、上下文）
❌ 错误：read_file 读两个完整 docx → execute_code 逐行对比
→ 两份文档全文进 context，token 爆炸
✅ 正确：对每个需求项分别搜 EEA 和 GAC 的 ws_doc_id
→ 每次只对比两个精确 chunk，在 reasoning 中直接分析差异
什么时候用 read_file？
- 纯文本文件（
.md / .py / .json 等），没有 ES 索引
- 需要查看二进制文件的原始格式/编码（极少见）
判断标准很简单：二进制文档有 ES chunks → 用 ES；纯文本文件没有 ES → 用 read_file。
工作流概览
| Step | 动作 | 说明 |
|---|
| 1 | copy_kb_document(doc_id) | 拷贝到 workspace/downloads + fork ES chunks → ws_{sid}_{doc_id} |
| 2 | unified_search(query="...", doc_ids="ws_doc_id") | 检索定位，返回位置信息 + workspace_path |
| 3 | 向用户确认修改范围 | 展示搜索结果中的文本内容 |
| 4 | skill / execute_code 编辑 | write_file_bytes 写入修改后的文档（可以是新文件名） |
| 5 | workspace_ops(action="snapshot_and_index") | 必须：fork 父 ES → 新 ws_doc_id → full_reparse 新文件。不做这步 = 后续搜不到 |
| 6 | 验证 + 自动注册 | 用新 ws_doc_id 抽样搜索确认内容正确，展示文件卡片 |
⚠️ 规则：execute_code 产出新文件后必须 snapshot_and_index
每次 execute_code 产出新的二进制文档（docx/xlsx/pptx）后，必须立即调用 snapshot_and_index，不可跳过。
execute_code → write_file_bytes → snapshot_and_index → 拿到新 ws_doc_id
↑ 不做这步 = ES 里没有新文件的 chunks
= 后续 unified_search 搜不到
= 后续任务无法用 ES 对比/检索
为什么：write_file_bytes 只把文件存到 MinIO，不会更新 ES。没有 snapshot_and_index，新文件在 ES 中不存在，后续轮次的 unified_search 无法检索到它的内容。这会导致：
- 第二个任务想检索第一个任务的产出 → 搜不到
- 对比两份文档的差异 → 只能
read_file 而不是 ES 精确搜索
- ws_doc_id 不进 Digest → 后续轮次完全不知道有这个文档
多步任务中每步都要做：如果任务分为"编号 → 超链接 → 对比高亮"三步，每步产出新文件后都要 snapshot_and_index，不能只在最后一步做。
二次编辑：在已有产出上继续编辑时，使用该产出文件的 ws_doc_id 检索，编辑后再次 snapshot_and_index。
ES Copy-on-Write 快照机制
核心原则
每个产出文件独立拥有一份 ES chunks，不覆盖父版本。
KB 原始文档 (doc_id=abc)
│ ES: ragflow_{tenant}/abc ← 知识库 chunks（只读，不动）
│
├─ copy_kb_document
│
downloads/合同.docx (ws_doc_id=ws_{sid}_abc)
│ ES: ragflow_{tenant}/ws_{sid}_abc ← fork from KB（只读快照）
│
├─ 编辑 + write_file_bytes (新文件名)
│
outputs/合同_numbered.docx (ws_doc_id=ws_{sid}_{hash1})
│ ES: ragflow_{tenant}/ws_{sid}_{hash1} ← fork from parent + full_reparse
│
├─ 继续编辑 + write_file_bytes (又一个新文件名)
│
outputs/合同_linked.docx (ws_doc_id=ws_{sid}_{hash2})
ES: ragflow_{tenant}/ws_{sid}_{hash2} ← fork from parent + full_reparse
为什么不原地覆盖 ES？
| 方案 | 问题 |
|---|
| 覆盖原 ws_doc_id 的 chunks | 文件名变了但 docnm_kwd 没变 → 按新名称搜不到；旧版本也丢了 |
只更新 docnm_kwd / workspace_path | 版本不对应：ES 内容是旧的，文件是新的 |
| Copy-on-Write（本方案） | 每个文件独立 ES，版本永远对应，搜索不会混乱 |
存储开销
一个 1000 页 DOCX ≈ 500-2000 个 ES chunks ≈ 2-10 MB 文本。session 内通常 2-5 个版本，总增量 < 50 MB，完全可接受。
snapshot_and_index 内部流程
Step 1: Fork 父 chunks → 新 ws_doc_id
复制所有 chunks，更新 doc_id / workspace_path / docnm_kwd
→ 新 ws_doc_id 拥有完整基线（和父文件内容一致）
Step 2: trigger_chunk_update(new_ws_doc_id, output_path, old_range)
在基线上做增量更新，只重解析被改的范围
├─ Agent 提供 old_range → 增量更新（快）
└─ 不提供 old_range → full_reparse fallback（慢但正确）
→ 新 ws_doc_id 的 chunks 和新文件内容一致
Fork 是增量更新的前提：没有基线，增量更新不知道哪些旧 chunks 要删、哪些要保留、后续偏移多少。
调用方式
workspace_ops(
action="snapshot_and_index",
params='{
"parent_ws_doc_id": "ws_{sid}_abc",
"output_path": "sessions/{sid}/outputs/合同_numbered.docx",
"source_type": "docx",
"old_range": {"para_start_int": 0, "para_end_int": 50}
}'
)
参数说明：
| 参数 | 必填 | 说明 |
|---|
parent_ws_doc_id | ✅ | 父文档的 ws_doc_id（从 copy_kb_document 返回值或上次 snapshot 返回值获取） |
output_path | ✅ | 新文件在 workspace 中的路径 |
source_type | ✅ | "docx" / "xlsx" / "pptx" |
old_range | 推荐 | 被修改的段落/行范围。有 → 增量更新；没有 → full_reparse fallback |
new_para_count | 可选 | 修改后该范围变成了多少段落/行 |
返回：
{
"status": "snapshot_created",
"new_ws_doc_id": "ws_{sid}_{hash}",
"parent_ws_doc_id": "ws_{sid}_abc",
"output_path": "sessions/{sid}/outputs/合同_numbered.docx",
"chunks_forked": 296,
"update_mode": "incremental",
"search_cmd": "unified_search(query='关键词', doc_ids='ws_{sid}_{hash}')"
}
后续检索该产出
拿到 new_ws_doc_id 后，后续所有检索都用它：
unified_search(action="search", query="违约责任", doc_ids="ws_{sid}_{hash}")
在产出物上二次编辑
如果需要在已有产出上继续编辑（如在 _numbered.docx 基础上加超链接）：
unified_search(action="search", query="前雾灯", doc_ids="ws_{sid}_{hash1}")
workspace_ops(
action="snapshot_and_index",
params='{"parent_ws_doc_id": "ws_{sid}_{hash1}", "output_path": "..._linked.docx", ...}'
)
✅ 产出验证 — execute_code 之后必须用 ES 抽样检查
代码执行（如批量添加编号、创建超链接、修改格式）容易出现 off-by-one、匹配遗漏、映射错位等 bug。每次 execute_code 产出文档后，必须用 ES 搜索抽样验证结果正确性。
验证流程
execute_code 产出新文档
↓
snapshot_and_index → 新 ws_doc_id（ES chunks 已更新）
↓
unified_search(query="第一个期望内容", doc_ids="new_ws_doc_id")
→ 检查返回的 chunk 是否包含预期修改
↓
unified_search(query="最后一个期望内容", doc_ids="new_ws_doc_id")
→ 检查边界条目是否正确
↓
确认无误 → 输出给用户
典型验证场景
批量编号：搜索第一个和最后一个编号，确认序号连续、没有偏移
unified_search(query="GAC_外灯系统_01", doc_ids="ws_{sid}_{hash}")
超链接映射：搜索映射的两端，确认对应关系
unified_search(query="FUNC_0007", doc_ids="ws_{sid}_{hash_gac}")
内容修改：搜索被修改的关键词，确认新旧值
unified_search(query="60天", doc_ids="ws_{sid}_{hash}")
为什么不能只靠代码内部验证？
代码可以 assert 检查行数/计数，但无法验证 语义正确性（编号对应到正确的需求项、超链接指向正确的位置）。ES 搜索是唯一能从「用户视角」验证内容的方式。
按格式选择工具
根据 source_type 字段选择编辑工具：
| source_type | 编辑工具 | 位置字段 |
|---|
| docx | docx skill | para_start_int / para_end_int + 关键词定位 |
| xlsx | xlsx skill (execute_code + openpyxl) | sheet_name + row_start_int / row_end_int |
| pptx | pptx skill / execute_code | slide_num |
| pdf | 有限编辑 | page_num_int |
🔑 关键词定位协议（与 docx skill 协作）
为什么需要关键词定位？
ES 返回的 para_start_int/para_end_int 是基于段落索引的定位，但：
- 跨文档编辑时，段落索引可能不稳定
- docx skill 在 XML 层操作，需要更精确的定位
- 简单关键词可能重复（如 "REQ_001" 可能出现多次）
解决方案：Agent 提供丰富的上下文关键词，docx skill 在 XML 层精确匹配。
LocatorSpec 格式
调用 docx skill 时，除 ES 位置信息外，必须提供 LocatorSpec：
{
"primary": "REQ_001",
"context_before": ["第3.2条", "违约责任"],
"context_after": ["赔偿金额"],
"match_mode": "run",
"occurrence": 0
}
字段说明：
| 字段 | 必须 | 说明 |
|---|
primary | ✅ | 主关键词（要定位/修改的文本） |
context_before | 推荐 | 前置上下文词（提升唯一性） |
context_after | 推荐 | 后置上下文词（提升唯一性） |
match_mode | 可选 | "run"（默认，精确到 run）/ "paragraph"（段落级）/ "fuzzy"（模糊） |
occurrence | 可选 | 仍有多个匹配时，选择第几个（0-based） |
消歧逻辑
docx skill 的 keyword_locator.py 会：
- 找到所有包含
primary 的候选位置
- 检查
context_before 是否在前面 10 段内出现
- 检查
context_after 是否在后面 10 段内出现
- 按上下文匹配得分排序，返回最佳匹配
如果仍无法消歧：返回候选列表，Agent 需提供更多上下文。
两种定位方式配合
document-editing docx skill
│ │
├── unified_search() ────────────┤ 获取 ES 位置信息
│ (para_start_int, para_end) │
│ │
├── 分析上下文 ──────────────────┤ 确定 LocatorSpec
│ → LocatorSpec │
│ │
└── 调用 docx skill ─────────────┤
+ workspace_path │
+ LocatorSpec │
+ 修改内容 │
│
┌───────────┴───────────┐
│ keyword_locator.py │
│ 精确定位 XML 位置 │
│ 执行修改 │
└───────────────────────┘
示例
用户："把合同第 3.2 条的违约责任里的赔偿金额从 30 天改成 60 天"
Agent 分析：
- ES 检索：找到"第3.2条 违约责任"在 para 45-52
- 要修改：
30 → 60
- LocatorSpec：
{
"primary": "30",
"context_before": ["第3.2条", "违约责任", "赔偿"],
"context_after": ["天"],
"match_mode": "run"
}
这样即使文档中有多处 "30"，也能精确定位到正确位置。
详细参考
- DOCX 编辑流程 + 示例：
references/docx-editing.md
- XLSX 编辑流程 + 示例：
references/xlsx-editing.md
- PPTX 编辑流程 + 示例：
references/pptx-editing.md
- 表格/图片/公式定位：
references/element-positioning.md
- 增量更新机制：
references/incremental-update.md
