docx-cli: 使 AI Agent 编辑 Word 文档实现高保真度

docx-cli: 使 AI Agent 编辑 Word 文档实现高保真度

docx-cli 优化了 AI Agent 与 Word 文档的交互

docx-cli 是一款专为 AI agent（例如 Claude 和 Codex）设计的专用 CLI，旨在让它们在读取、编辑和对 .docx 文件进行评论时能够保持完整的格式保真度。与传统的 agent 尝试直接修改底层 OOXML (Office Open XML) 的方法不同——后者通常会导致文件损坏和高 token 消耗——docx-cli 为 agent 提供纯文本命令和带注释的 Markdown 读取视图。这种方法确保了自定义样式、主题颜色和嵌入式对象在编辑过程中得以保留。

性能基准测试：docx-cli 与默认 agent 能力对比

在涉及六项真实文档任务（包括填写 NDA、修订合同和撰写期刊）的受控 A/B 测试中，docx-cli 在两个模型层级上都显著优于默认的 agent 能力：

  • 成功率：在“弱” Haiku 层级上，docx-cli 解决了 4.3/6 项任务，而默认能力仅解决了 0.7/6 项。在“强” Sonnet 层级上，它实现了完美的 6/6，而默认能力为 4/6。
  • Token 效率：docx-cli 将输入 token 减少了约 2.2-2.6 倍，从而降低了成本并提高了速度。
  • 延迟：两个层级的墙钟时间（Wall-clock time）均减少了 1.7-2.0 倍。
  • 可靠性：100% 的 docx-cli 输出在第一次尝试时即可在 Microsoft Word 中打开，而默认能力产生的多个文件无法被 Word 打开。

核心技术架构

原地 XML 变异

与其从有损模型中重新生成文档，docx-cli 将 AST (Abstract Syntax Tree) 视为解析后的 XML 树的一个视图。当 agent 执行 edit 或 comments add 命令时，CLI 会直接修改底层的 XML 节点并将更改序列化回文件。这确保了任何未在 AST 中明确建模的元素（例如专有架构扩展或复杂的主题颜色）都保持原封不动且完整。

稳定的定位器与寻址

为了避免原始文本偏移量的脆弱性，docx-cli 使用定位器系统来精确寻址文档元素：

  • 块 ID：pN (段落)、tN (表格) 和 sN (分节符) 是根据文档顺序派生的。
  • 实体 ID：cN (评论)、imgN (图像)、linkN (超链接)、fnN (脚注) 和 enN (尾注) 通过 list 动词公开。
  • Span：字符偏移量是基于 0 的，起始包含，结束不包含（例如，p3:5-20 针对段落 3 的第 5 到第 19 个字符）。

丰富的内容处理

docx-cli 实现了多项高级功能来处理复杂的 Word 元素：

  • 公式：使用自定义的 MathML–OMML 适配器，将 OOXML <m:oMath> 往返转换至 LaTeX。
  • 修订模式：使用原生的 <w:ins> 和 <w:del> 标签进行修订。CLI 支持三种读取视图：--accepted (纯文本)、--current (带有脚注的 CriticMarkup) 和 --baseline (变更前文本)。
  • 图像：支持从路径、data: URIs 或 HTTP(S) URLs 插入图像，并带有自动 HEIC–JPEG 转码。
  • 样式：允许编辑 styles.xml 中的样式定义，从而实现全局更改（例如，“将所有标题 1 设为绿色”）而无需修改文档正文中的每个实例。

命令与工作流参考

读取与查询

Agents 使用 docx read 获取文档的 Markdown 表示，并辅以 HTML 注释注释（例如，<!-- docx:p pN style="Caption" -->），这些注释提供了关于样式、对齐和间距的结构化提示。

变异 (Mutation)

Mutators 会原地修改文件。关键命令包括：

  • docx replace: 替换模式时保留 run 格式。
  • docx edit: 在特定定位器处修改内容，支持纯文本、Markdown 或原始 runs。
  • docx insert: 在定位器前后添加内容。
  • docx comments add: 在特定的 span 或短语上附加评论。
  • docx render: 允许 agents 通过驱动 Microsoft Word (通过 osascript 或 PowerShell COM) 或 LibreOffice 生成 PDF，然后使用捆绑的 PDFium WASM 包将其光栅化为 PNG 或 JPG 图像，从而验证其工作。

安装与 Agent 集成

docx-cli 作为 Agent Skill 分发，兼容 Claude Code、Codex 和 Pi。它可以通过 npx skills add kklimuk/docx-cli 安装，也可以作为 Linux、macOS 和 Windows 的独立二进制文件使用。对于 Claude Code，用户可以使用 /plugin marketplace add kklimuk/docx-cli 命令。

Sources