Diagnostics

Docmod 的 CLI JSON 输出包含 diagnostics[]。它们不是装饰信息，而是 Agent 判断“命令成功但部分改动未应用”的依据。

结构

{
  "code": "PATCH008",
  "severity": "warning",
  "message": "data-find text was not found",
  "hint": {
    "help_topic": "diagnostics",
    "example": "Run docmod read <input> --query \"#6EAA1C8E\""
  }
}

读取阶段

Code	含义
DOCX001	读取某个 docx 元素失败，已跳过。
DOCX010	遇到不支持或受保护结构。
DOCX020	读取媒体、关系或辅助 part 时出现可恢复问题。

HTML 解析

Code	含义
HTML001	HTML 解析失败后清理非法字符重试。
HTML002	输入 fragment 有可恢复结构问题。
HTML010	元素或属性无法完整映射到模型。

Patch / ChangeMerger

Code	含义
PATCH001 到 PATCH006	未知 data-id、未知 anchor、孤立新元素等定位问题。
PATCH007	data-format-only 元素带正文内容，内容被忽略。
PATCH008	data-find 未找到，或 data-find-index 越界。
PATCH009	改动命中 opaque 只读区域。
PATCH010	改动命中不可编辑节点。
PATCH011	试图改写无法从 HTML 重建的 OMML 公式。

表格

Code	含义
TABLE001	行索引越界。
TABLE002	列索引越界。
TABLE003	插入列时提供的单元格数量与行数不匹配。
TABLE004	表格结构不满足增量操作条件。

Agent 处理原则

1. status: "success" 后仍然检查 diagnostics[]。
2. 对 warning 做局部修正，不要重写整个文档。
3. 遇到 PATCH009 / PATCH010 时，不要绕过只读保护，改问用户是否接受替代位置或人工处理。
4. 遇到 PATCH008 时，重新读取目标段落并修正 data-find。