docx-cli

docx-cli 是一个命令行工具，旨在解决 AI 智能体在处理 .docx 文件时面临的格式破坏、内容丢失及高 Token 消耗问题。它通过提供稳定的文本定位器和简单的命令接口，让智能体能够精准地添加评论、建议修订或替换文本，而无需直接操作复杂的 OOXML 结构。所有修改均以 Word 原生的“修订模式”或“评论”形式呈现，最终由人类用户在 Microsoft Word 中审核与接受。

核心优势：稳定性、效率与兼容性

与让智能体直接解压并编写 XML 的传统方法相比，docx-cli 带来了显著的性能提升：

• 零格式损坏：CLI 就地修改 XML 结构，保留自定义样式、主题颜色及嵌入对象。测试显示，docx-cli 生成的文档在 Word 中打开的成功率为 100%，而默认技能在廉价模型（Haiku）上每次运行平均产生 1 个损坏文档。
• 大幅降低 Token 消耗：通过提供带注释的 Markdown 阅读视图，智能体无需推理底层 XML。在 Haiku 模型上，Token 消耗从 6.1M 降至 2.4M（约减少 2.5 倍）；在 Sonnet 模型上，从 3.6M 降至 1.6M（约减少 2 倍）。
• 显著提升任务成功率：在受控的 A/B 测试中，使用 docx-cli 的 Haiku 模型解决了 4.3/6 的任务，而默认技能仅解决 0.7/6；Sonnet 模型则从 4/6 提升至满分 6/6。
• 极速执行：由于减少了推理负担，处理时间几乎减半（Haiku：924秒 vs 1882秒）。

工作原理

1. 稳定定位器：智能体通过段落、表格或运行级别的唯一标识符（Locator）寻址文本，避免了基于模糊匹配的误差。
2. 修订与评论机制：所有的修改建议都以 Word 标准的“跟踪更改”（Track Changes）或“评论”形式写入。这确保了人类用户拥有最终的控制权，可以在 Word 的审阅窗格中轻松接受、拒绝或回复。
3. AST 读取视图：docx read 命令将文档转换为结构化的 Markdown/AST 表示，供智能体理解文档布局，但实际写回时仍操作原始 XML。

快速示例：自动化填写 NDA 协议

# 1. 复制副本以保护原件
cp tests/fixtures/mnda.docx mnda-filled.docx

# 2. 读取特定表格内容（可选，用于上下文理解）
docx read mnda-filled.docx --from t1 --to t1

# 3. 批量替换占位符
docx replace mnda-filled.docx "Fill in: today's date" "May 6, 2026"
docx replace mnda-filled.docx "fill in state and/or county" "California"

# 4. 验证是否还有遗漏的占位符
docx find mnda-filled.docx '\[(Fill|fill)[^]]*\]' --regex --all

# 5. 开启修订模式，确保后续修改可追溯
docx track-changes mnda-filled.docx on

# 6. 进行具体措辞修订
docx replace mnda-filled.docx \
    "having a reasonable need to know" \
    "with a documented need to know"

# 7. 在指定位置添加评论供人类审核
docx comments add mnda-filled.docx --at p7:0-30 \
    --text "Should we narrow 'representatives' to a named list?"

在 Word 中打开 mnda-filled.docx，你将看到所有替换内容均处于修订状态，且第 7 段带有指定的评论。

集成与安装

docx-cli 既可作为独立 CLI 使用，也可作为 AI Skill 集成到主流 Agent 平台中。

安装 CLI：

• npm/bun: bun add -g bun-docx
• 二进制: curl -fsSL https://raw.githubusercontent.com/kklimuk/docx-cli/main/install.sh | sh

集成到 Agent：

• Claude Code: npx skills add kklimuk/docx-cli
• Codex: codex plugin marketplace add kklimuk/docx-cli
• Pi: pi install git:github.com/kklimuk/docx-cli

作为 Skill 使用时，它会自动教导智能体如何使用定位器语法和修订工作流，并通过 docx <command> --help 获取最新的权威契约，确保指令不会过时。