夜雨聆风
先扔结论：我花了20分钟装了一个叫 docx-cli 的命令行工具，拿一份NDA合同模板试了试——自动填充4个占位符、做了一处红线修订、留了一条审阅批注。打开Word，全部正常渲染，修订模式和批注都在。这听起来没什么特别的，但如果你用过AI代理（Claude、Codex）直接编辑 .docx 文件，就知道这有多难——我之前试过让Claude改一份Word合同，它把表格全部打散了，直接生成一个打不开的文件。
docx-cli 的作者 kklimuk 做了一个严格的对比测试：让Claude用原生方式（手写OOXML）和用 docx-cli 各做6个文档任务。结果——docx-cli 完成了6/6，原生方式只完成了4/6，而且原生方式有5份文档Word打不开。这差距实在明显。
项目信息
GitHub: github.com/kklimuk/docx-cli⭐ 129 stars | HN: 70 points | 最近更新: 2天前License: MIT | 语言: TypeScript
为什么AI编辑Word文档是个大问题
.docx 文件本质上是一个ZIP压缩包，里面装的是OOXML格式的XML文件。AI模型虽然能看懂XML，但要让它们正确生成一份符合Word规范的文档，需要处理：命名空间、关系文件、样式定义、页眉页脚、修订标记、表格边框、图片嵌入……任何一个细节错了，Word要么打不开，要么渲染成一团乱。
更麻烦的是，AI代理的上下文窗口有限。直接操纵OOXML会消耗大量token，而且模型越弱（比如Haiku），输出的文档质量越差。docx-cli 做的事情很简单：它把 .docx 文件转成一种带定位标记的Markdown视图，AI代理通过简单的命令（replace、find、comments add）来操作，docx-cli 在底层处理OOXML的复杂细节。格式永远保留，文件永远不会损坏。
安装
安装方式有两种：npm 和 预编译二进制。我用npm装的（需要Bun运行时）：
# 安装Bun（如果还没有）
npm install -g bun
# 安装docx-cli
npm install -g bun-docx
# 验证
docx --version
# 输出: docx 0.20.3整个过程大约30秒。如果用预编译二进制（不需要Bun），直接从GitHub Releases下载就行。两种方式都支持 macOS ARM64/x64、Linux、Windows。
⚠️ 注意：我在国内网络环境下安装时，GitHub Releases下载经常断连。如果你也遇到这个问题，用 npm 安装会更稳定——它会走国内镜像源（npmmirror.com），速度很快。
实测：一份NDA合同的全流程
我从项目仓库下载了 Common Paper 的 Mutual NDA 模板（一份标准的保密协议），然后试了docx-cli的全部核心功能。
第一步：读取文档
先用 docx read 查看文档结构。docx-cli 会把 .docx 渲染成带注释的Markdown，每个段落、表格、单元格都有稳定的定位标识：
docx read mnda.docx --from t1 --to t1输出是一个表格视图，每个单元格都标有 t1:r0c0:p0 这样的定位符。表格里的占位符被高亮成 [Fill in: today's date] 这样的格式——AI代理可以直接用这些文本作为替换目标。
第二步：填充占位符
用 docx replace 命令批量替换占位符：
docx replace mnda.docx "Fill in: today's date" "2026年7月10日"
docx replace mnda.docx "fill in state and/or county" "California"
docx replace mnda.docx "fill in state" "California"
docx replace mnda.docx "Fill in, if any." "None."
# 验证没有遗漏
docx find mnda.docx '\[(Fill|fill)[^]]*\]' --regex --all
# 输出: no matches所有替换都返回了"1 occurrence replaced"，最后用正则检查确认零遗漏。
第三步：开启修订模式 + 做红线编辑
这是docx-cli最实用的功能之一——它能在 .docx 里生成Word的 Track Changes（修订标记）：
# 开启修订追踪
docx track-changes mnda.docx on
# 输出: track-changes tracking on
# 修改合同条款 — 会生成修订标记
docx replace mnda.docx "having a reasonable need to know" "with a documented need to know"
# 输出: replace 1 occurrence replaced这个功能对合同审核场景太重要了——AI代理可以做建议性修改，人类在Word里一键接受或拒绝，双方都能看到改了哪里。
第四步：加批注
docx comments add mnda.docx --at p7:0-30 \
--text "Should we narrow 'representatives' to a named list?"
# 输出: c0（批注ID）批注使用定位符指定目标文本范围（这里是第7段的前30个字符），AI代理可以在审查合同时标记问题段落，人类在Word里查看并回复。
最终验证
用 docx read 再次读取，确认修订模式已开启（track-changes on），所有占位符已被替换（"2026年7月10日"、"California"显示在正确位置）。文件从28KB变为26KB——格式保持完整，没有损坏。
实测结果总结
✅ 读取 .docx → 输出带定位符的Markdown
✅ 替换占位符 → 4个全部成功
✅ 正则搜索 → 定位精确
✅ 修订追踪 → Track Changes 正常生成
✅ 批注 → 正确关联到目标文本
✅ 格式保留 → 所有表格、字体、颜色完整
⚠️ 未测：用AI代理（Claude/Codex）驱动docx-cli（需要MCP配置）
和其他方案对比
目前AI操作Word文档的主流方案有三种：
- AI直接写OOXML
：让模型手写XML。作者测试了36次，5次产出文件Word打不开。token消耗高2.2-2.6倍，耗时多1.7-2倍。 - 转Markdown再转.docx
：格式丢失严重，表格、批注、修订全部消失。 - docx-cli
：在OOXML层面直接操作，定位精确到字符级别。格式100%保留，0次损坏。
作者做了一项A/B对比测试，结果很有说服力：用Haiku（弱模型）驱动docx-cli完成了4.3/6个任务，而用AI原生方式只完成0.7/6——差距6倍。即使是Sonnet（强模型），原生方式也只能完成4/6，docx-cli则是6/6全通。
这说明了什么
docx-cli 的模式值得注意：它不是让AI变得更聪明，而是给AI一把趁手的工具。实际工作中90%的AI Agent应用场景，瓶颈不在模型能力，而在工具链——AI能理解你的需求，但没有合适的方式去操作你的文件。
随着 MCP（Model Context Protocol）生态成熟，这类"工具型"项目会越来越多。每个传统文件格式（PDF、Excel、PPT、PSD）都值得有一个AI友好的CLI封装。docx-cli 是 .docx 方向的一个好样本。
如果你平时工作中频繁处理Word合同、标书、报告，这个工具值得关注。特别是合同审核场景——让AI先做一轮红线修改和批注，然后再打开Word最终确认，能省掉大量重复劳动。
觉得有用点个👍
有问题留言聊
