AI 改 Word,最怕格式崩:Word AI 开源,63 个 MCP 工具守住结构

Word AI 开源发布：为 AI 智能体带来可验证、可审计、可回滚的 Word 文档编辑能力，覆盖离线 DOCX 与当前 Word 会话。

AI 改 Word，最怕格式崩：Word AI 开源，63 个 MCP 工具守住结构

很多团队第一次让 AI 编辑 Word 文档时，都会经历一个相似的瞬间。

它写得很快，措辞也漂亮。你让它补一段项目背景，它补了；你让它替换几处验收标准，它也替换了。看上去一切顺利。可等文档真正打开，编号轻轻偏了一下，表格多了一条看不见的边，目录字段没对齐，页眉页脚和图片关系也开始让人不放心。

Word 文档的重量，往往藏在文字之外。

它是一只精密的盒子，里面放着段落、样式、编号、表格、图片、字段、批注、页眉页脚、关系文件，以及大量普通读者看不到的 OOXML 细节。AI 会写内容，可交付文档需要的，远远超过内容本身。

所以我开源了 Word AI。

它面向 Codex、Claude Code、OpenAI Agents 和其他 MCP 客户端，让智能体可以安全编辑既有 Word 文档。核心目标只有一句话：

让 AI 只在被允许的位置动笔，并且每一次动笔都有预演、验证、审计和回滚。

项目地址：

https://github.com/flyfish-dev/word-ai^[1]

先说结论：Word AI 解决什么问题

Word AI 适合这些场景：

你有一份已经排好版的合同、标书、需求文档、项目方案或审计报告，希望 AI 只编辑指定位置。
你希望 Codex 能读取 Word 结构，找到标题、表格、内容控件、批注、字段和图片，然后生成可审查的编辑计划。
你希望正式写入前先做 dry-run，写入后能看到 diff、audit JSON 和结构验证结果。
你希望既能处理磁盘上的 .docx，也能编辑当前 Microsoft Word 窗口里打开的文档。
你希望接入 OfficeCLI 的渲染、截图、query、validate 能力，又不希望正式写入绕过审计链路。

当前项目已经具备：

63 个 MCP tools，覆盖读取、定位、表格、字段、图片、批注、PatchSet、验证、回滚、Word 会话和 OfficeCLI 辅助证据。
PatchSet-only writes，正式正文写入统一进入 PatchSet。
内容控件 tag 优先，例如 WORD-AI:SRS:1.0:overview。
强前置条件，支持 source_sha256、expected_old_sha256、expected_old_text。
离线文件编辑，通过 docx_* 工具链生成新 DOCX 与审计文件。
实时 Word 会话编辑，通过 Office.js taskpane 和 word_session_* 工具链编辑当前打开的 Word 文档。
.NET 8 Open XML SDK 引擎，用于类型化 Open XML 处理与回归验证。
OfficeCLI 只读/低侵入集成，默认只开放 HTML、PNG、issues、query、validate。
MCP Registry / Agent Skill / npm 第二渠道，降低智能体接入门槛。

这篇文章会把接入方式和底层路线讲清楚。你可以把它当成一份可直接上手的实战说明。

一、最快接入：四种入口

Word AI 的分发顺序做了取舍：优先 MCP Registry 与 Agent Skill，其次本地源码完整安装，npm 作为第二渠道。

1. MCP Registry / MCPB

支持 MCP Registry 的客户端，可以按 server name 找到：

io.github.flyfish-dev/word-ai

项目的 Registry 元数据在仓库根目录：

server.json

MCPB 包地址：

https://github.com/flyfish-dev/word-ai/releases/download/v0.8.1/word-ai-0.8.1.mcpb

这种方式适合希望通过公共 MCP 元数据发现工具的团队。Registry 提供 server name、版本、transport、包位置和来源信息；真实代码仍由 GitHub Release、npm 等包渠道承载。

2. Agent Skill

MCP server 负责提供工具，Agent Skill 负责告诉智能体怎样使用这些工具。

Word AI 内置正式 word-ai Skill，会写入：

~/.agents/skills/word-ai
~/.codex/skills/word-ai
~/.claude/skills/word-ai

它告诉智能体几件关键事：

用户给 .docx 路径时，使用离线 docx_*。
用户说当前 Word 文档、Word 会话、taskpane 时，使用 word_session_*。
没有 live session 时，不要悄悄退到离线文件路径。
正式写入必须 assess、dry-run、backup、apply、validate、diff。
OfficeCLI 默认只做证据辅助。

单独安装或刷新 Skill：

python3 scripts/install_agent_skills.py

3. 本地源码完整安装

需要 Office.js taskpane、localhost bridge、.NET 8 引擎、Codex 配置片段时，用本地安装。

git clone https://github.com/flyfish-dev/word-ai.git
cd word-ai

bash scripts/install.sh
bash scripts/start.sh

安装脚本会完成：

创建 Python venv。
安装 MCP server 依赖。
构建 Office.js taskpane。
构建 .NET Open XML SDK 引擎。
生成 .wordai/codex-config.toml。
自动安装 Agent Skill。

健康检查：

.venv/bin/word-ai --root "$PWD" doctor

当前本地验证结果里，Python、Node、npm、.NET SDK 8、Office add-in、OfficeCLI 都已经通过检查。

4. npm 第二渠道

如果你的 MCP host 暂时无法消费 MCP Registry/MCPB，可以走 npm。

二、Codex 怎么配

本地安装后直接看生成配置：

cat .wordai/codex-config.toml

手写最小配置可以参考：

[mcp_servers.word_ai]
command = "/absolute/path/to/word-ai/.venv/bin/python"
args = [
  "-m", "word_ai_mcp.server",
  "--root", "/absolute/path/to/word-ai",
  "--allow-root", "/Users/you/Downloads",
  "--allow-root", "/Users/you/Documents"
]
enabled = true
startup_timeout_sec = 30

[mcp_servers.word_ai.env]
PYTHONPATH = "/absolute/path/to/word-ai"

[mcp_servers.word_ai.tools.docx_dry_run_patchset]
approval_mode = "approve"

[mcp_servers.word_ai.tools.docx_apply_patchset]
approval_mode = "approve"

[mcp_servers.word_ai.tools.docx_backup]
approval_mode = "approve"

[mcp_servers.word_ai.tools.word_session_apply_patchset]
approval_mode = "approve"

[mcp_servers.word_ai.tools.word_session_rollback]
approval_mode = "approve"

--root 是主工作目录。外部文档目录需要通过 --allow-root 显式授权，比如 Downloads、Documents、Desktop 或团队文档库。这样做可以避免智能体随意访问用户机器上的其他位置。

三、底层实现路线：DOCX 被当作结构包处理

Word AI 的基本判断是：DOCX 不能被当成纯文本。

一个 .docx 本质上是 ZIP 包，里面有 word/document.xml、styles.xml、numbering.xml、comments.xml、_rels 关系文件、图片资源、页眉页脚 part 等。只改一段文字，理论上也可能牵动结构、关系和字段。

Word AI 因此把编辑路线分成四层。

第一层，读取层。

读取工具尽可能丰富。智能体可以调用：

docx_health_check 看复杂对象、重复 tag、字段、批注、痕迹。
docx_map 获得适合 Codex 理解的文档地图。
docx_list_content_controls 找内容控件 tag。
docx_list_tables、docx_read_table 读取表格。
docx_list_fields、docx_list_images、docx_list_comments、docx_list_headers_footers 查看复杂对象。

第二层，计划层。

智能体不能直接写 XML。它必须生成 PatchSet。PatchSet 描述“要编辑哪里”“旧内容哈希应当是什么”“新内容是什么”“是否允许复杂内容”。

第三层，事务层。

PatchSet 会经过 assess 和 dry-run。dry-run 会写到候选文件，再做结构验证。候选通过后才允许生成最终输出。

第四层，证据层。

写入后输出新 DOCX、audit JSON 和 diff。验证会检查 part 变化、内容控件 tag 集合、表格数量、图片数量、字段数量、批注数量、痕迹数量，以及未触达对象 hash。

这套路线的重点不在“让 AI 能写”。更关键的是，AI 的写入可以被人类审查，可以被机器验证，也可以在出现问题时回退。

四、PatchSet 长什么样

下面是最推荐的内容控件编辑方式。

{
  "schema_version": "2.0",
  "strict": true,
  "source_sha256": "源 DOCX 的 sha256",
  "reason": "更新项目概述",
  "guard": {
    "require_preconditions": true,
    "allow_overwrite": false
  },
  "operations": [
    {
      "op": "replace_content_control_text",
      "tag": "WORD-AI:SRS:1.0:overview",
      "expected_old_sha256": "目标内容控件原文 hash",
      "text": "新的项目概述文本。",
      "preserve_style": true,
      "allow_complex_content": false
    }
  ]
}

这段 JSON 里最关键的是三件事。

第一，tag 是编辑锚点。它让 AI 对准文档里明确的一块区域。

第二，expected_old_sha256 是前置条件。打开文件里的目标文本如果已经被别人改过，hash 对不上，写入就会停止。

第三，allow_overwrite 默认为 false。正式输出默认生成新 DOCX，原文件保留。

对交付文档来说，这三件事比“快”更重要。

五、离线 DOCX 编辑链路

当用户提供文件路径时，Word AI 走 docx_* 工具链。

典型调用顺序是：

docx_health_check
  -> docx_map / docx_list_anchors
  -> docx_read_content_control / docx_read_table
  -> docx_assess_patchset
  -> docx_dry_run_patchset
  -> docx_backup
  -> docx_apply_patchset
  -> docx_validate / docx_compare_structure
  -> docx_text_diff

输出通常包含：

sample_contract.edited.docx
sample_contract.edited.audit.json

验证结果会说明：

改动是否只落在允许的 DOCX part。
内容控件 tag 是否保持一致。
表格、图片、字段、批注、痕迹数量是否保持一致。
未触达内容控件、表格、段落的 hash 是否保持一致。
可见文本 diff 是否符合预期。

这很适合批量处理合同、需求、报告、投标文件和文档库。

六、当前 Word 窗口编辑链路

很多人真实工作时，文档已经打开在 Microsoft Word 里。他们希望 AI 直接编辑眼前这份文档。

Word AI 为此做了 Office.js taskpane。

启动本地服务：

bash scripts/start.sh

打开 Word 后 sideload：

office-addin/manifest.xml

taskpane 会做几件事：

包装当前选区为内容控件。
读取打开文档里的内容控件。
连接本地 HTTP bridge。
注册 live session。
轮询 Codex 写入本地队列的命令。
在 Word host 内执行 Office.js 写入。
返回 audit 与 rollback PatchSet。

Codex 侧走：

word_session_list
  -> word_session_snapshot
  -> word_session_read_content_control
  -> word_session_preview_patchset
  -> word_session_apply_patchset
  -> word_session_command_status

Live session 写入范围更窄，只支持内容控件文本类操作：

replace_content_control_text
append_content_control_text
prepend_content_control_text
replace_text_in_content_control

这条边界很重要。当前 Word 窗口里的编辑强调可见、可控和可回退；复杂结构编辑仍然更适合离线文件事务。

七、OfficeCLI 怎么用在 Word AI 里

OfficeCLI 是一个非常优秀的 Office 智能体项目。它覆盖 Word、Excel、PowerPoint，单二进制、跨平台、无需安装 Office，并提供 HTML/PNG 渲染、query、validate、batch、template merge、dump 等能力。

Word AI 深度参考了 OfficeCLI 的很多好设计：help-first、语义路径、渲染证据、watch/render、template merge、dump/batch 这些思路都很有价值。

同时，Word AI 在默认路径里只开放 OfficeCLI 的低侵入能力：

officecli_view_html
officecli_view_screenshot
officecli_view_issues
officecli_query
officecli_validate

默认不开放 set、add、remove、raw-set、batch、merge 这些变更能力。未来如果要用，也会先包进 Word AI 的 PatchSet、dry-run、audit、approval 和 rollback。

这里的取舍很清楚：

OfficeCLI 适合提供渲染、查询、验证和跨 Office 文件能力。
Word AI 负责 Word 交付文档的正式写入边界。

八、和常见方案相比，亮点在哪里

如果你用过 LibreOffice、python-docx、Open XML SDK、Office.js 或 OfficeCLI，大概会关心 Word AI 的位置。

与 LibreOffice

LibreOffice 很适合转换、导出、批量处理。Word AI 关注既有 DOCX 的增量编辑，尽量避免转换链路带来的细节漂移。

与 python-docx

python-docx 简洁、轻量，适合很多生成类任务。Word AI 面向智能体工作流，内置 MCP tools、PatchSet、审计、回滚和结构验证。

与 Open XML SDK

Word AI 里已经接入 .NET 8 Open XML SDK 引擎。它提供类型化 Open XML 处理能力，和 Python OOXML 引擎一起构成双路径验证。

与 Office.js

Office.js 能在真实 Word host 中操作当前文档。Word AI 用 taskpane 把它纳入 MCP 会话，让 Codex 可以读取当前文档、预演 PatchSet、应用内容控件编辑，并拿到 live audit。

与 OfficeCLI

OfficeCLI 能力更广，覆盖三大 Office 格式和丰富命令。Word AI 聚焦 Word 的正式编辑事务，默认把 OfficeCLI 作为只读证据与视觉检查辅助。

九、验证已经覆盖到什么程度

本仓库已经在本地做过完整检查，重点包括：

Python 编译、smoke test、结构回归。
Word session 命令队列 smoke。
.NET 8 Open XML SDK build。
.NET PatchSet 回归。
Office bridge smoke。
Office.js taskpane TypeScript build。
manifest validation。
MCPB build 与 validate。
Docker local smoke。
npm 包发布验证。
MCP Registry active/latest 验证。

QA 报告记录在：

docs/QA_REPORT.md

当前公开分发状态：

MCP server: io.github.flyfish-dev/word-ai
MCP Registry version: 0.8.1
npm scoped package: @flyfish-dev/word-ai@0.8.1
npm unscoped package: word-ai-mcp@0.8.2
License: AGPL-3.0-or-later

十、真正使用时，建议这样开始

如果你是 Codex 用户，建议按这个顺序来：

从 MCP Registry 安装 io.github.flyfish-dev/word-ai，或用本地源码安装。
安装 word-ai Agent Skill。
把 Downloads、Documents、团队文档库加入 --allow-root。
对重要文档优先添加内容控件 tag。
让 Codex 先执行 docx_health_check 和 docx_map。
只读取目标锚点内容，不把整份长文档塞给模型。
生成 PatchSet 后先 docx_assess_patchset。
再 docx_dry_run_patchset。
通过后 docx_backup 与 docx_apply_patchset。
最后查看 docx_validate、docx_text_diff 和 audit JSON。

如果你要编辑当前 Word 窗口：

启动 bash scripts/start.sh。
在 Word 里 sideload taskpane。
连接 bridge。
用 taskpane 包装选区或列出内容控件。
在 Codex 里用 word_session_*。
写入前看 preview，写入后保存 live audit 与 rollback PatchSet。

十一、开源之后还会继续做什么

Word AI 接下来会继续围绕几条线前进：

更完整的 Word live session 操作。
更细的结构验证与视觉证据。
更好的内容控件治理体验。
更便捷的 MCP host 安装路径。
更完善的 OfficeCLI 辅助证据链。
更适合团队使用的审计、审批和批量流程。

我希望它能成为一个真正有用的开源组件：让智能体除了写内容，也能尊重交付文档里那些细密的结构；让人类把重要文档交给 AI 时，多一份清楚的边界和证据。

开源地址：

https://github.com/flyfish-dev/word-ai^[2]

也欢迎参考文档：

README.md
docs/GETTING_STARTED.md
docs/TOOL_CONTRACT.md
docs/CODEX_TOOL_CATALOG.md
docs/QA_REPORT.md
skills/word-ai/SKILL.md

感谢每一位认真处理文档的人，感谢每一位愿意试用、提问、指出问题、贡献代码的朋友。开源的意义，常常就在这些细小而具体的改进里：有人把真实困难讲出来，有人把解决路径写清楚，更多人因此少走弯路，多一点从容。

谢谢阅读，感谢同行。

引用链接

[1]https://github.com/flyfish-dev/word-ai

[2]https://github.com/flyfish-dev/word-ai