Agent 编辑流程

Agent 不应该猜测 Word 结构，也不应该重写整个文档。稳定流程是：先读 outline，再精读目标，再输出 changes fragment，最后检查 diagnostics。

1. 读取结构

docmod read report.docmod --outline

outline 用来找元素 ID、标签、样式和预览文本。对 docx 来源文档，段落 ID 通常是 8 位大写 hex，例如 6EAA1C8E。不要使用 #p3 这类位置式选择器。

2. 精读目标

docmod read report.docmod --query "#6EAA1C8E"
docmod read report.docmod --query ":contains(运行质量)"
docmod read report.docmod --query "[pstyle=Normal]"

#id 按 data-id 精确匹配。data-n 只是给人看的顺序号，不能当锚点。

3. 输出 changes fragment

替换段落：

<p data-id="6EAA1C8E" data-pstyle="Body">更新后的段落内容。</p>

删除段落：

<p data-id="3F2A91D7" data-delete="true" />

在已有元素后插入：

<p data-after="6EAA1C8E" data-pstyle="Body">新增段落。</p>

段内查找替换：

<p data-id="A1B2C3D4">
  <span data-find="旧文字" data-replace="新文字" />
</p>

4. 执行编辑

docmod edit report.docmod changes.html

对 .docmod 执行 edit 是惰性合并：只更新 document.html，保留 source.docx 不变。真正的 XML patch 会延迟到 export 或 compact。

5. 检查 diagnostics

status: "success" 表示命令完成且文档仍有效，不表示每条改动都应用成功。必须检查 diagnostics[]。

常见情况：

• PATCH008：data-find 未找到，或 data-find-index 超出匹配数量。
• PATCH009：改动命中 opaque 只读区域。
• PATCH010：改动命中不可编辑节点。
• TABLE001 到 TABLE004：表格行列操作索引或数量错误。

修复方式通常是重新 read --query 精读目标，修正锚点或查找文本后再次编辑。

6. 导出 docx

docmod export report.docmod --to report.updated.docx

导出时 Docmod 会把当前 document.html 和原始 source.docx 合成最终 .docx。连续多次编辑只需要在最终导出时打一次 patch。