Docxodus：DOCX 处理工具包

项目简介

.docx 本质上是一个装满 XML 的压缩包，通常只有少数程序能真正读懂。Docxodus 是一套结构感知的 OOXML 引擎：它能忠实读取 Word 文档并无损写回，再通过 HTML 渲染、稳定的 markdown 投影、有状态的编辑会话、原生修订标记（redline）和浏览器内编辑器等不同入口对外提供能力。

它以 .NET 库、浏览器 WebAssembly 模块、npm/TypeScript 包、Python 客户端和三个 CLI 工具的形式发布，全部共用同一引擎，因此同一份文档在各端行为一致。

主要功能

比对与修订

• 结构化比较两份文档，输出 Word 可直接打开的原生修订标记：w:ins、w:del、w:moveFrom/w:moveTo、w:pPrChange，而不是简单的文本高亮 diff。
• 移动操作会被识别为一次移动，而不是互不相关的删除加插入；列表编号按“全部接受修订”后的状态重新编号。
• 往返约定：accept(compare(left, right)) 等价于 right，reject(...) 等价于 left，在块文本层面校验。
• 修订也是数据：GetRevisions() 返回带稳定 kind:scope:unid 锚点的类型化修订，GetEditScriptJson() 返回完整编辑脚本 JSON。
• GetSemanticChanges() / GetSemanticChangesJson() 提供确定性的语义变更集，覆盖文本、格式、样式、编号、表格、节、页眉页脚、批注、关系、媒体等。
• 支持 N 路合并：把多个审阅者的副本对同一基线合并为一份多作者修订文档，并给出冲突报告；页眉页脚同样参与比较。

渲染

• DOCX → HTML 保留对齐方式、样式继承、法律文书编号、表格、图片、批注、页眉页脚，以及带反向引用的脚注。
• 分页模式把内容排入真实页面框，带页码、随页脚注和书眉，可在浏览器内做印刷级预览。
• 修订内容渲染为 <ins>/<del> 并携带作者信息；批注可按尾注式、行内或页边方式呈现，也能增量叠加标注而无需重新转换整篇文档。
• HtmlToWmlConverter 支持反方向转换。

Markdown 投影与编辑

• WmlToMarkdownConverter 输出的 markdown 中每个块都带稳定 id，形如 {#p:body:09612b1c13…}，由内容派生且能经受文档其他位置的修改，方便 LLM 代理按锚点定位改写。
• 锚点贯穿整个工具链：同一 id 可定位投影块、渲染后的 DOM 节点（data-anchor）、diff 修订和编辑目标。
• DocxSession 是有状态、按锚点寻址的编辑器，每个修改返回类型化结果封装，支持文本与结构操作、表格行列、字符与段落格式、列表与边框、页眉页脚、页码、脚注尾注、批注、有界撤销重做，以及直接操作原始 OOXML 的出口。
• DocxEditor 是构建在其上的浏览器编辑器：框架无关的 TypeScript + WASM 引擎，无需服务器；只重绘被修改的块，save() 返回无损字节。

安装与使用

.NET：

dotnet add package Docxodus

var redline = DocxCompare.Compare(new WmlDocument("v1.docx"), new WmlDocument("v2.docx"));
redline.SaveAs("redline.docx");

浏览器 / Node：

npm install docxodus

import { initialize, compareDocuments } from 'docxodus/core';
await initialize();
const redline = await compareDocuments(v1, v2);

引擎入口用 docxodus/core；DocxEditor、mountRibbon 等浏览器编辑器 API 从 docxodus 导入。

Python：

pip install docx-scalpel

from docx_scalpel import open_session

with open_session(docx_bytes) as s:
    s.replace_text(anchor, "new text")
    out = s.save()

命令行：

dotnet tool install -g Redline
redline old.docx new.docx out.docx

注意事项

• 旧版 WmlComparer 引擎已在 v11.0.0 中移除。
• DocxCompare.Compare 比较的是各输入“接受修订后”的视图，与 Word 的 Compare 行为一致；直接调用底层 DocxDiff 时默认比较原始标记，若输入本身带修订，需要设置 PreAcceptInputRevisions（或 PreserveInputRevisions），否则会产生整篇文档级别的差异噪音。
• 同一引擎下还可使用 DeliverableVerifier.VerifyDeliverable() 做交付物校验，以及 DeliveryChangeReceiptBuilder 生成可验证的交付变更凭证。
• v15.0.0 包含破坏性变更，升级前请查阅仓库中的 CHANGELOG。
• 许可证：MIT。

---

本作品整理自 GitHub 开源项目 JSv4/Docxodus，原作者 @JSv4，许可证 MIT。中文介绍由 AI 根据项目 README 整理，以原仓库为准。