Docx-CLI 发布：AI代理读写Word文档时间和Token减半

背景

在AI agent与文档处理结合的实践中，一个常见的痛点是让大语言模型（LLM）直接操作Word文档（.docx格式）。传统的做法是让agent解压.docx文件，手动编写内部OOXML（Office Open XML）。这不仅要求模型具备极高的XML操作能力，而且非常消耗token（推理成本高），且经常生成Word无法正常打开的损坏文件。针对这一痛点，开发者kklimuk在Hacker News上发布了开源工具docx-cli，它专为AI agent设计，提供一种更高效、更可靠的Word文档读写方式。

核心内容

docx-cli是一个基于命令行的Word文档处理工具，专为AI agent（如Claude、Codex等）优化。它允许agent通过稳定定位符（stable locator）定位文本，并执行注释、提出修订建议、编辑文档等操作，同时保持原有格式、主题颜色、嵌入对象等完整无缺——所有修改都会以Word原生形式保留，供人类在Word中接受或拒绝。

工作原理

• agent无需直接操作XML。docx-cli向agent提供纯命令列表和带注释的Markdown阅读视图，agent只需调用简单命令即可完成编辑。
• 工具通过直接修改.docx内部的XML（而非从有损模型重新生成）来保证格式无损。
• 使用稳定定位符（如p3:5-20表示第3段第5到20字符）来精确指定文本范围，agent基于此进行替换、注释等操作。

性能对比（A/B测试）

开发者进行了受控对比实验：6个真实文档任务（填写NDA、填写发票、重排简历、修订合同、定稿合同、撰写期刊文章），使用相同初始文件，由独立评审根据Word渲染结果打分。每层模型（Haiku和Sonnet）各跑3轮。

• 正确性差距：在廉价Haiku层级上，默认方式正确率极低，docx-cli的差距约为6倍；即使使用前沿模型Sonnet，默认方式也无法填平差距——默认技能最高只能完成4/6任务，每次Sonnet运行都会丢失合同修订和简历任务。
• 成本与速度：默认方式消耗约2.2–2.6倍token，速度慢1.7–2倍，且两个层级下token消耗和时间范围均无重叠（即docx-cli始终更优）。
• 文件可靠性：默认方式生成的36个文件中，有5个Word无法打开；而docx-cli生成的36个文件全部一次成功打开。

安装方式

1. 通过npm（需要Bun >= 1.3）：

   bun add -g bun-docx
   # 或直接运行
   bunx bun-docx read doc.docx
   

2. 独立二进制（无需Bun）：

   curl -fsSL https://raw.githubusercontent.com/kklimuk/docx-cli/main/install.sh | sh
   

   支持PREFIX（默认$HOME/.local/bin）和VERSION（默认latest）。提供linux/x64、linux/arm64、darwin/x64、darwin/arm64、windows/x64预编译版本。也可手动下载并验证SHA256。

使用示例（以Common Paper Mutual NDA模板为例）

# 复制文件（无撤销操作，建议用git管理历史）
cp tests/fixtures/mnda.docx mnda-filled.docx

# 读取封面表格，让agent了解占位符
docx read mnda-filled.docx --from t1 --to t1

# 替换黄色高亮的占位符
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"
docx replace mnda-filled.docx "fill in state" "California"
docx replace mnda-filled.docx "Fill in, if any." "None."

# 验证无剩余占位符
docx find mnda-filled.docx '\[(Fill|fill)[^]]*\]' --regex --all

# 开启修订模式
docx track-changes mnda-filled.docx on

# 替换指定文本（产生修订标记）
docx replace mnda-filled.docx "having a reasonable need to know" "with a documented need to know"

# 添加注释
docx comments add mnda-filled.docx --at p7:0-30 --text "Should we narrow 'representatives' to a named list?"

在Word中打开mnda-filled.docx，即可看到修订标记和注释，供人类审阅。也可通过docx track-changes accept mnda-filled.docx --all直接从CLI接受所有修订。

作为Agent Skill集成

docx-cli附带一个SKILL.md文件，兼容Claude Code、Codex、Pi等主流agent框架。安装方式：

• 通用安装：npx skills add kklimuk/docx-cli
• Claude Code：/plugin marketplace add kklimuk/docx-cli 然后 /plugin install docx-cli@docx-cli
• Codex：codex plugin marketplace add kklimuk/docx-cli
• Pi：pi install git:github.com/kklimuk/docx-cli 后调用 /skill:docx-cli
• 手动：将skills/docx-cli/目录放入agent的skills目录（如~/.claude/skills/）。

该skill教导agent使用定位符模型和修订/注释/填充工作流，并在运行时通过docx <command> --help获取最新文档，避免信息过时。

弱agent基准测试结果

在6个真实文档任务中，使用弱模型Haiku驱动docx-cli平均完成4.3/6任务，而默认Claude skill仅完成0.7/6，且token消耗少约2.5倍；使用Sonnet时，docx-cli完成6/6，默认技能仅4/6，token消耗少约2倍。所有docx-cli输出均能一次成功打开，无文件被拒绝。

命令参考

• 阅读命令：docx read、docx find、docx wc、docx outline、docx styles
• 修改命令：docx replace、docx track-changes、docx comments add、docx styles set/create
• 信息命令：docx info locators、docx info schema、docx info skill、docx --help

所有命令均支持--help获取详细参数。docx read --ast可输出JSON的AST（抽象语法树）而非Markdown。

关键要点

• 效率提升：docx-cli将agent处理Word文档的token消耗降低约2.2–2.6倍，速度提升约1.7–2倍，且在不同模型层级上效果一致。
• 正确性优势：在弱模型（Haiku）上，正确率差距高达6倍；即使强模型（Sonnet）也无法匹敌docx-cli的可靠性。
• 文件兼容性：默认方式产生的文件有约14%概率无法被Word打开，而docx-cli的所有输出均一次成功打开。
• 核心原理：agent无需直接操作OOXML，而是通过稳定定位符和Markdown视图与docx-cli交互，所有修改直接修改XML，无损格式。
• 安装灵活：支持npm（需Bun）和独立二进制，覆盖主流操作系统，并提供SHA256校验。