docxredline

docxredline

docxredline 以 Agent 所需的方式处理 Word .docx 文件： 将文件读取为便于推理的纯文本，编辑文件以便 Word 本身显示修订痕迹，并在文件离开工作环境前将其清理干净。所有操作都在本地进行——文档不会离开本机，除了 stdio MCP 接口外，不包含任何服务端组件。

这是一个标注过的核心子集：仅包含三个文档工具 （read_docx、process_document_batch、finalize_document），不包含其他内容。它不会驱动正在运行的 Word 实例，不会渲染任何 UI，也不处理文档批注（请参阅下方各工具的说明）。

安装

npx @reneturcios/docxredline read agreement.docx

或者运行容器映像：

docker run -i ghcr.io/cloudcorprecords/docxredline

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。请注意，CLI 按路径读取和写入文件，因此需要为容器挂载包含文档的卷。

CLI

# Read a document (tracked changes shown as CriticMarkup)
docxredline read agreement.docx

# Read the final clean version instead
docxredline read agreement.docx --clean

# Only paragraphs mentioning payment terms; synthetic page 2
docxredline read agreement.docx --search "payment"
docxredline read agreement.docx --page 2

# Apply a batch of edits from a JSON file
docxredline batch agreement.docx changes.json --author "Review Bot"

# Pre-send scrub, locked read-only
docxredline finalize agreement.docx --protection read_only

docxredline --version

退出代码：成功时为 0，无法读取文件或批次中没有任何更改生效时为 1，用法错误时为 2。所有命令都接受 --json。

更改文件是一个由更改对象组成的 JSON 数组：

[
  { "type": "modify", "target_text": "thirty days", "new_text": "sixty days" },
  { "type": "modify", "target_text": "old clause", "new_text": "new clause", "match_mode": "all" },
  { "type": "accept", "target_text": "12" },
  { "type": "reject", "target_text": "13" }
]

MCP 服务

一个可执行文件同时提供这两种接口。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/docxredline mcp

MCP 客户端配置：

{
  "mcpServers": {
    "docxredline": {
      "command": "npx",
      "args": ["-y", "@reneturcios/docxredline", "mcp"]
    }
  }
}

工具

工具	输入	功能
read_docx	path（字符串，必需）；clean_view（布尔值）、search_query（字符串）、page（数字）可选	逐段返回类似 Markdown 的文档文本。现有修订痕迹会呈现为 CriticMarkup——{++inserted++} 和 {--deleted--}——除非通过 clean_view 将其消除。search_query 仅保留包含该文本的段落。
process_document_batch	path（字符串，必需）、changes（数组，必需）；output_path、author 可选	应用一批更改并写入结果（默认写入输入文件所在目录下的 <name>.redlined.docx）。返回已生效的更改数量，以及其余更改的逐项错误列表。只有至少一项更改生效时才会写入输出文件。
finalize_document	path（字符串，必需）；output_path、protection_mode 可选	写入可供分发的副本（默认写入 <name>.scrubbed.docx）：清空 docProps/core.xml 中的作者字段，从正文中剥离 w:rsid* 属性，并在设置 protection_mode: "read_only" 时添加 documentProtection 锁定。

此子集中的编辑与 ID 工作方式

• modify 更改会在单个段落的文本中查找 target_text，并重写包含该文本的运行：旧文本会包裹在 <w:del> 元素中，新文本会包裹在 <w:ins> 元素中；两者都会标记批次中的 author，并使用新的 w:id，因此 Word 会显示真正的修订痕迹。
• 安全检查：对于非正则表达式 modify，若使用默认的 match_mode "first"，且目标匹配到多个段落，则会因存在歧义而拒绝操作，而不会猜测段落并应用更改。请使用更长的目标，或使用 match_mode: "all" 编辑每个匹配段落中的所有匹配项。regex: true 会将 target_text 视为正则表达式。
• 跨越段落内多个运行的目标无法通过此子集重写，并会作为单项更改失败报告。
• accept / reject 使用修订痕迹的 w:id 字符串作为 target_text。接受会保留插入文本并删除删除内容；拒绝则相反。（此处未复现原工具对批注和范围更丰富的 ID 模型。）
• 此子集不支持 reply：它会作为单项更改失败返回，错误信息为 "comments not supported in this subset"，绝不会被静默计为已生效。

合成分页

.docx 没有分页概念，因此 page 是一项本地约定：每 40 个段落分为一页，页码从 1 开始。每次返回结果时，read_docx 都会报告文档的段落总数和合成页数，以便调用方有意分页。

最终说明

当文档没有 word/settings.xml 部件且请求了保护时，docxredline 会创建一个仅包含保护元素的最小文件。完整的软件包还会在 [Content_Types].xml 和软件包关系中注册该部件；此子集将其记录为已知缺口，而不会重写这些部件。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network
npm run dev     # run the CLI from source via tsx

测试会在临时目录中使用该工具自带的同一存储式 ZIP 写入器生成自己的最小 .docx 测试文件，因此测试套件会端到端地运行真正的归档读取器。

许可证

MIT — 请参阅 LICENSE。