Word AI

Word AI

语言	预览
English	采用 .NET Open XML 后端和 Office.js 实时会话，支持保留结构的 Word DOCX 编辑。
中文	面向 AI Agent 的 Word DOCX 结构稳定编辑；支持 .NET 后端、Office.js 会话和安全 PatchSet。

面向 AI Agent 的结构保留型 Word（DOCX）编辑。

Word AI 是一个开源 MCP 服务和 Office.js 桥接工具，可安全、可审计地增量编辑 Microsoft Word 文档。它面向 Codex、OpenAI Agents 及其他需要编辑 .docx 文件、又不想重建文档或破坏样式、编号、表格、图片、域、页眉、页脚和关系的 MCP 客户端。

为什么选择 Word AI

AI 系统擅长生成文本，但 Word 文档是结构化的包。简单地执行 DOCX 到 Markdown 再到 DOCX 的工作流，可能破坏编号、样式、表格、图片、域、引用和布局。Word AI 将原始 DOCX 结构作为事实来源：

• Agent 生成受约束的 PatchSet 操作。
• 本地引擎应用有针对性的 OOXML/Open XML 编辑。
• 每次写入都经过评估、试运行、备份、验证、审计和差异检查。
• Office.js 加载项提供 Word 任务窗格，用于锚点管理和人在回路中的工作流。

主要功能

• 63 个 MCP 工具，用于 DOCX 检查、锚点、标题、段落、表格、域、图片、批注、修订、PatchSet 规划、试运行、应用、验证、回滚、差异检查、Word 实时会话编辑，以及可选的只读 OfficeCLI 证据。
• 仅通过 PatchSet 写入。默认不重建整个文档、不进行 Markdown/HTML 往返转换，也不直接覆盖源文件。
• 便于 Agent 使用的 PatchSet 规范化，支持 operation、target_tag、new_text、text_sha256 等常见别名和 camelCase 操作名称，同时保留规范的安全检查关卡。
• 优先使用内容控件进行编辑，采用稳定的 Word 内容控件标签，例如 WORD-AI:SRS:1.0:overview。
• 严格的前置条件，包括 source_sha256、expected_old_sha256 和 expected_old_text。
• 结构验证，涵盖包部件、内容控件、表格、段落、域、批注、图片、修订和受保护的正文块。
• Python MCP 外观层和桥接运行时，用于本地 Agent 集成、路径策略、会话队列和分发兼容性。
• .NET 8 Open XML SDK 引擎作为权威的离线 DOCX 事务后端，优先使用打包的原生二进制文件或 Release DLL。
• 单文件独立二进制文件和快速入门包，无需克隆仓库、无需 venv、无需 .NET SDK，即可离线编辑 DOCX，并通过一条命令安装 Agent Skill。
• Office.js 任务窗格，支持 Word 侧锚点、PatchSet 预览、试运行、应用，以及通过哈希检查编辑打开文档中的内容控件。
• Word 实时会话工具（word_session_*），让 Codex 通过 Office.js 读取、预览、应用并回滚当前打开的 Word 文档中的编辑。
• 本地 HTTP 桥接，通过本地令牌和仅限 localhost 的 CORS 为 Office 加载项工作流提供安全保障。

架构

Codex / Agent / MCP Client
        |
        v
Word AI MCP Server
        |
        +--> Python MCP facade / read indexes / Office bridge
        +--> .NET Open XML SDK backend for offline PatchSet transactions
        +--> Office bridge HTTP API
        +--> File-backed Word session command queue
        |
        v
Original DOCX -> PatchSet -> Candidate DOCX -> Validation -> Output DOCX + Audit JSON + Diff

Office.js 任务窗格是 Word 会话层。它会创建并列出内容控件，连接本地桥接服务，将当前 Word 文档注册为实时会话，轮询 Codex 排队的命令，通过 Office.js 执行受支持的 PatchSet 操作，并返回审计和回滚数据。

快速开始

使用 Agent 主机支持的最原生分发方式：

1. 优先选择 MCP Registry / MCPB：从官方 MCP Registry 安装 MCP 服务，服务名称为 io.github.flyfish-dev/word-ai。
2. 以独立快速入门包实现最低本地配置成本：如果你想要一个无需检出源码即可运行 MCP、安装 Skill 并生成 Codex 配置的可执行文件，请下载适用于当前平台的 GitHub Release 包。
3. 接下来安装 Agent Skill：安装 word-ai Skill，让 Codex、Claude Code 和兼容的 Agent 知道何时选择离线 docx_*，何时选择实时 word_session_*。
4. 通过本地源码安装以使用完整的 Word 会话：如果你需要 Office.js 任务窗格、本地主机桥接、.NET Open XML 回归路径或开发工作流，请使用此方式。
5. 将 npm 作为备用渠道：仅当 MCP 主机暂不支持 MCP Registry/MCPB，或你想要无需克隆即可运行的 stdio 服务命令时，才使用 npm。

MCP Registry 详情：

• 服务名称：io.github.flyfish-dev/word-ai
• Registry 元数据：server.json
• MCPB 包：https://github.com/flyfish-dev/word-ai/releases/download/v0.8.6/word-ai-0.8.6.mcpb
• Registry 最新版本 API：https://registry.modelcontextprotocol.io/v0.1/servers/io.github.flyfish-dev%2Fword-ai/versions/latest

使用独立快速入门包快速完成本地设置：

tar -xzf word-ai-quickstart-0.8.6-osx-arm64.tar.gz
cd word-ai-quickstart-0.8.6-osx-arm64

./word-ai install-skill
./word-ai codex-config --output .wordai/codex-config.toml
./word-ai mcp --root "$PWD" --allow-root "$HOME/Downloads" --allow-root "$HOME/Documents"

选择与你的平台匹配的构件：linux-x64、linux-arm64、osx-arm64、osx-x64、win-x64 或 win-arm64。完整的发布资源政策请参阅分发。

安装 Skill 和完整的本地运行时：

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

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

此操作会安装 Python MCP 门面、构建 Office.js 任务窗格、在 .NET SDK 8 可用时构建 .NET Open XML 后端、写入 .wordai/codex-config.toml，并将 word-ai Skill 安装到 Codex、Claude Code 和检测到的兼容 Agent 客户端中。

仅安装或刷新 Agent Skill：

python3 scripts/install_agent_skills.py

仅调试浏览器任务窗格：

bash scripts/start.sh --http

在 Windows PowerShell 中：

powershell -ExecutionPolicy Bypass -File scripts\install.ps1
powershell -ExecutionPolicy Bypass -File scripts\start.ps1

执行就绪状态检查：

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

开发者检查：

PYTHONPATH=. .venv/bin/python scripts/run_smoke_test.py
PYTHONPATH=. .venv/bin/python scripts/run_structure_regression.py
PYTHONPATH=. .venv/bin/python scripts/run_outline_regression.py
PYTHONPATH=. .venv/bin/python scripts/run_engine_selection_regression.py

构建 .NET 引擎：

dotnet --version  # requires .NET SDK 8
dotnet build dotnet/WordAi.OpenXml/WordAi.OpenXml.csproj -c Release
scripts/publish_dotnet.sh           # current host RID in dist/native/<rid>
scripts/publish_dotnet.sh --all     # all supported release RIDs
PYTHONPATH=. .venv/bin/python scripts/run_dotnet_regression.py

离线引擎选择

如果 .NET Open XML 后端可用，离线文件事务默认使用该后端。选择顺序如下：

1. WORD_AI_DOTNET_EXE，或 native/<rid>/ 或 dist/native/<rid>/ 下打包的本机可执行文件。
2. WORD_AI_DOTNET_DLL，或本地 Release DLL：dotnet/WordAi.OpenXml/bin/Release/net8.0/WordAi.OpenXml.dll。
3. 本地源项目：通过 dotnet run --project dotnet/WordAi.OpenXml/WordAi.OpenXml.csproj 运行。
4. 仅当 .NET 不可用且 WORD_AI_ENGINE=auto 时，才回退到 Python OOXML。

MCPB 包含适用于 osx-arm64、osx-x64、linux-x64、linux-arm64、linux-musl-x64、linux-musl-arm64、win-x64 和 win-arm64 的自包含本机后端。独立快速入门包面向标准托管平台构建：linux-x64、linux-arm64、osx-arm64、osx-x64、win-x64 和 win-arm64，并将匹配的 Open XML 后端链接到单文件可执行程序中。Word AI 会检测当前 RID，包括用于加载本机后端的 Linux glibc 与 musl，并自动加载匹配的二进制文件。npm 启动器会保持软件包精简：首次运行时，它会从 GitHub Releases 下载适用于当前平台的快速入门包，并执行其中打包的 word-ai。高级部署可通过 WORD_AI_DOTNET_RID、WORD_AI_DOTNET_EXE 或 WORD_AI_DOTNET_NATIVE_DIR 覆盖检测结果；仅当你想使用旧版 Python venv npm 路径时，才设置 WORD_AI_NPM_USE_SOURCE_BOOTSTRAP=1。

可通过 WORD_AI_ENGINE=auto|dotnet|python 控制引擎，或为 docx_assess_patchset、docx_dry_run_patchset、docx_apply_patchset 和 docx_validate 传入 engine。在生产环境中使用 WORD_AI_ENGINE=dotnet，以便在出现问题时立即失败，而不是静默回退。

构建 Office 加载项：

cd office-addin
npm install
npm run build

Agent Skill 自动安装

Word AI 提供正式的 word-ai Agent Skill。即使通过 MCP Registry 安装 MCP 服务，也建议使用此 Skill 教会 Agent 安全的工作流。安装程序会将 Skill 复制到当前 Agent 客户端会自动扫描的位置：

• Codex 官方用户 Skill：~/.agents/skills/word-ai
• Codex 应用兼容 Skill：~/.codex/skills/word-ai
• Claude Code 个人 Skill：~/.claude/skills/word-ai
• 检测到兼容客户端时：Cursor、Windsurf、GitHub Copilot 和 OpenClaw 的 Skill 文件夹

仅安装或刷新 Skill：

python3 scripts/install_agent_skills.py

高级目标：

python3 scripts/install_agent_skills.py --agents all
python3 scripts/install_agent_skills.py --project
python3 scripts/install_agent_skills.py --dry-run

安装后，请启动新的 Agent 会话，或在 Skill 未立即显示时重启客户端。之后可直接调用该 Skill：word-ai / $word-ai；如果 DOCX 编辑任务提及 Word、Office.js、内容控件、PatchSet、验证、回滚或审计，也可以隐式选择该 Skill。

全局 MCP 分发

Word AI 已发布到官方 MCP Registry 和 MCPB 分发渠道，供用户发现。建议通过此渠道安装 MCP 主机，因为它包含标准化的服务元数据、版本信息、传输详情和来源信息：

• MCP 服务名称：io.github.flyfish-dev/word-ai
• MCPB 软件包：https://github.com/flyfish-dev/word-ai/releases/download/v0.8.6/word-ai-0.8.6.mcpb
• Registry 元数据：server.json
• 发布指南：MCP Registry 发布
• 独立版和快速入门指南：分发

本地容器冒烟测试：

docker build -t word-ai:local .
docker run --rm -i \
  -v "$PWD:/workspace" \
  -v "$HOME/Downloads:/documents/Downloads" \
  word-ai:local

MCP Registry 版本使用公开的 MCPB 构件，便于一键在本地安装服务。独立版快速入门包是最省事的本地命令行方案，因为它将 Python 外观层、依赖项、适用于当前平台的 .NET Open XML 后端、架构和 Skill 模板打包到一个可执行文件中。MCPB 软件包需要 Python 3.10+，并会在首次运行时引导创建本地虚拟环境。Dockerfile 仍可用于本地或可自托管构建。若要进行完整的 Office.js 实时会话编辑，请使用本地源码安装方式，因为 Word 任务窗格和 localhost 桥接服务必须在用户的计算机上运行。

次要 npm 渠道

对于尚未使用 MCP Registry/MCPB 软件包的客户端、CI 冒烟测试，以及无需克隆即可快速启动 stdio 服务，npm 是便捷的备用方案。它不是主要的发现渠道。

建议使用带作用域的软件包：

npm exec --yes --package @flyfish-dev/word-ai -- word-ai-mcp --root "$PWD" --allow-root "$HOME/Downloads"
npm exec --yes --package @flyfish-dev/word-ai -- word-ai --root "$PWD" doctor

无作用域兼容软件包：

npx -y word-ai-mcp --root "$PWD"
npm exec --yes --package word-ai-mcp -- word-ai --root "$PWD" doctor
npm exec --yes --package word-ai-mcp -- word-ai-mcp --root "$PWD"

全局安装后，可直接使用相同的命令：

npm install -g @flyfish-dev/word-ai
word-ai --root "$PWD" doctor
word-ai-mcp --root "$PWD" --allow-root "$HOME/Downloads"

首次运行 npm 命令时，会从 GitHub Releases 下载适用于当前平台的快速入门包，将其缓存在用户缓存目录下，并执行其中打包的独立版 word-ai。默认的 npm 方案不需要 Python venv、pip install 或单独下载 Open XML 后端。只有在明确需要旧版 Python venv 引导路径时，才设置 WORD_AI_NPM_USE_SOURCE_BOOTSTRAP=1。

与 Codex MCP 配合使用

安装程序会生成一段可直接合并的 MCP 配置：

cat .wordai/codex-config.toml

将其添加到 Codex MCP 配置中。生成的代码段包含写入工具的审批关卡。最简手动配置如下：

[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"

基于 npm 的 Codex 次要配置，适用于暂时无法从 MCP Registry/MCPB 安装的主机：

[mcp_servers.word_ai]
command = "npm"
args = [
  "exec",
  "--yes",
  "--package",
  "@flyfish-dev/word-ai",
  "--",
  "word-ai-mcp",
  "--root",
  "/absolute/path/to/workspace",
  "--allow-root",
  "/Users/you/Downloads",
  "--allow-root",
  "/Users/you/Documents"
]
enabled = true
startup_timeout_sec = 60

在基于 npm 的 Codex 配置中，你可以将 @flyfish-dev/word-ai 替换为非作用域兼容包 word-ai-mcp。

--root 是相对路径和 Word AI sidecar 的主工作区。对于希望 Codex 编辑的外部文档文件夹（例如 Downloads、Documents 或团队项目文件夹），重复使用 --allow-root。安装程序生成的 .wordai/codex-config.toml 会自动包含常见的用户文档文件夹。

写入工具的推荐审批策略：

• docx_dry_run_patchset
• docx_apply_patchset
• docx_backup
• docx_restore_backup
• docx_rollback
• word_session_apply_patchset
• word_session_wrap_selection
• word_session_rollback
• sidecar 导出工具

提示词示例：

Use word_ai to inspect examples/sample_contract.docx, list content controls, read WORD-AI:SRS:1.0:overview, and prepare a PatchSet. Run assess and dry-run before applying.

对于当前打开的 Word 文档，加载 Office 加载项并连接桥接服务，然后向 Codex 提问：

Use word_ai to list active Word sessions, read WORD-AI:SRS:1.0:overview from the live Word session, preview a PatchSet through Office.js, then apply it to the open document and return the audit plus rollback PatchSet.

Office.js 桥接服务和实时 Word 会话

最简单的方式是：

bash scripts/start.sh

手动启动时，启动本地桥接服务：

PYTHONPATH=. .venv/bin/python -m word_ai_mcp.server_http \
  --root "$PWD" \
  --host 127.0.0.1 \
  --port 8765

启动任务窗格：

cd office-addin
npm run dev

然后在 Word 中旁加载 office-addin/manifest.xml。任务窗格默认运行在 https://localhost:3100/taskpane.html，并将 /bridge/* 代理到本地桥接服务。桥接服务启动时会输出一个本地令牌。在任务窗格中使用该令牌。

在 Word 中连接后，任务窗格会在 .wordai/sessions 下注册一个实时会话。Codex 随后可以使用：

• word_session_list
• word_session_snapshot
• word_session_read_content_control
• word_session_preview_patchset
• word_session_apply_patchset
• word_session_wrap_selection
• word_session_rollback
• word_session_command_status

此方式通过 Office.js 编辑当前打开的 Word 文档。word_session_apply_patchset 会针对打开的文档执行实时预检、检查 expected_old_sha256、应用受支持的内容控件操作、返回审计对象，并生成回滚 PatchSet。离线 DOCX 方式仍使用 docx_* 工具和 OOXML/Open XML 验证器。

OfficeCLI 兼容性策略

Word AI 可选择将 OfficeCLI 用作只读或低风险检查的辅助证据：view html、view screenshot、view issues、query --json 和 validate。除非通过 Word AI PatchSet、试运行、审计、回滚和明确的审批关卡进行封装，否则 OfficeCLI 的修改命令（例如 set、add、remove、raw-set、batch 和 merge）不属于 Word AI 的默认工作流。

MCP 服务仅通过允许列表中的封装工具提供此集成：officecli_view_html、officecli_view_screenshot、officecli_view_issues、officecli_query 和 officecli_validate。如果未安装 OfficeCLI，这些工具会返回 available=false，核心 Word AI 工作流则继续使用 docx_* 和 word_session_*。

Word AI 借鉴了 OfficeCLI 的一些实用设计理念，例如优先查看架构和帮助信息、语义路径、监视/渲染证据、模板合并概念，以及转储/批量检查。权威的写入模型仍然是 Word AI PatchSet。

安全编辑工作流

docx_health_check
  -> docx_map / docx_list_anchors / docx_list_content_controls
  -> docx_read_content_control / docx_read_table_cell / docx_read_paragraph
  -> generate PatchSet with source_sha256 and expected_old_sha256
  -> docx_assess_patchset
  -> docx_dry_run_patchset
  -> docx_backup
  -> docx_apply_patchset
  -> docx_validate / docx_compare_structure
  -> docx_text_diff

文档

• 文档索引
• 快速入门
• 分发
• Word AI Codex Skill
• 架构
• 工具契约
• 安全设计
• QA 报告
• 验证矩阵
• MCP Registry 发布
• v0.8.6 更新日志
• v0.8.5 更新日志
• v0.8.4 更新日志
• v0.8.3 更新日志
• v0.8.1 更新日志
• v0.8.0 更新日志
• v0.7.1 更新日志
• v0.7 更新日志

仓库状态

Word AI 目前是一款本地优先的开发者工具，适用于受控的 DOCX 编辑实验、Agent 集成和内部工作流试点。对于生产环境中的远程 MCP 部署，请使用适当的 MCP Streamable HTTP 传输、身份验证、网络控制、审计存储以及渲染/视觉差异基础设施。

许可证

GNU Affero 通用公共许可证 v3.0 或更高版本（AGPL-3.0-or-later）。请参阅 许可证。