Docx-CLI

为什么选择 Docx-CLI？

Docx-CLI 解决了 AI 开发中一个虽小但却十分棘手的痛点：AI Agent 擅长文本推理，但 Word 文档并非纯文本。一个 .docx 文件实际上是一个包含 OOXML 部件、关系、样式、批注、修订记录、媒体和节元数据的 ZIP 压缩包。让 Agent 直接重写这种复杂结构非常容易出错。

Docx-CLI 为 Agent 提供了一个更安全的抽象层。Agent 无需编辑原始 XML，而是读取带有注释的文档表示，定位到稳定的文档定位器（locators），并调用明确的命令来执行替换、批注、修订、样式更改和结构编辑。当输出结果必须能在 Microsoft Word 中正常打开并由人工审阅时，这款工具显得尤为重要。

核心工作流

典型的工作流程始于复制源 Word 文件，读取特定区域，然后应用针对性编辑。Agent 可以搜索文本、格式、高亮、样式、批注、图像、超链接、页眉、页脚或修订记录。对于合同或审阅文档，Agent 可以开启修订模式、替换短语、在特定文本段添加批注，最后将最终决策权留给在 Word 中进行审阅的人工用户。

最核心的概念是基于定位器的编辑。Docx-CLI 不使用模糊的自然语言（如“修改第三段的第二句话”），而是公开段落和字符范围等引用。这使得 Agent 的操作更具可重复性且易于验证，但也意味着用户需要适应比图形界面编辑器略显技术化的工作流。

适用场景

Docx-CLI 在文档已存在且格式至关重要的工作流中表现最强。合同审查是天然的匹配场景，因为批注和修订需要完全符合 Word 用户的预期。它还可以辅助学生论文评测、基于量表的评分、简历改版、内部政策修订、模板填充以及文档质量检查（QA）。

如果任务仅仅是从头开始生成新文档，那么它的优势就不太明显。对于纯模板化需求，docxtemplater 或 docx.js 等库可能更简单。对于涉及 PDF、HTML、图像和多种 Office 格式的大规模文档解析，Docling 等转换工具包可能是更好的底层选择。

竞品对比

与通用文档库相比，Docx-CLI 更倾向于 Agent 导向。python-docx 和 docx.js 适合开发者编写应用程序代码来调用文档 API。而当终端 Agent 需要明确的命令契约、可预测的标准输出（stdout）、退出代码、稳定定位器以及便于人工复核的变更命令时，Docx-CLI 是更好的选择。

与 OfficeCLI 相比，主要在于广度与深度的权衡。OfficeCLI 定位于 Word、Excel 和 PowerPoint 的自动化，而 Docx-CLI 专精于 Word .docx 工作流。这种专注在文档审阅任务中可能是一个优势，因为批注、修订、定位器和 Word 格式保真度是该产品的设计核心。

最佳配置建议

对于 Agent 工作流，在使用 Claude Code、Codex、Pi 或其他兼容框架时，建议将其安装为 Agent Skill（智能体技能）。这能让 Agent 获得工具指令，并在运行时保持命令界面的可发现性。对于脚本编写和 CI 式用法，使用独立二进制文件路径更清爽，因为它可以避免依赖全局 Bun 环境。

为了确保编辑安全，请将 Word 文件视为源代码资产：在副本上操作，尽可能指定输出路径，渲染或打开结果进行验证，并将原始文件保留在版本控制或对象存储中。虽然 Docx-CLI 可以减少格式破损，但在处理具有法律、学术或商业重要性的文档时，人工最终审核依然不可或缺。

迁移建议

目前正在尝试让 Agent 解压 .docx 并直接修补 OOXML 的团队，应考虑将 Docx-CLI 作为更安全的替代层。迁移工作主要是调整 Agent 提示词和工具契约：使用 Docx-CLI 读取，针对定位器操作，应用显式命令，然后验证结果。

已拥有 Python 或 JavaScript 文档处理流水线的团队不一定需要替换现有系统。Docx-CLI 可以作为面向 Agent 的辅助工具，用于审阅、修订和针对性编辑，而原有代码继续处理批量生成或模板工作流。