GitHub 今日推荐｜wordcraft：用 Rust 重写 Word 内核并开放给 AI 调用

一句话看懂

项目地址：github.com/storytold/w...

wordcraft 是一个用 Rust 编写的开源文档处理器,目标是做一个"干净"的 Word 实现:不依赖微软的代码,而是根据公开的文档格式规范重新实现读写与编辑逻辑(即 clean-room reimplementation,不参考原始源码的独立重写)。它既能当桌面应用,也能编译成 WebAssembly 在浏览器里跑,还做了一层给 AI 代理调用的接口。

它解决什么问题

办公文档处理长期被微软 Word 的 .docx 格式和生态绑定,开源替代品(如 LibreOffice)大多是用 C++ 写的老代码库,想做自动化、嵌入或二次开发门槛不低。wordcraft 想解决两类问题:一是提供用现代语言写的、跨平台的文档处理内核,能读写 .docx(即 OOXML,基于 XML 的文档格式标准);二是让文档操作变成"可编程的能力"------不仅人能在界面上点按钮,AI 代理也能通过统一命令集打开、编辑、转换文档。README 给出的一个具体数字:188 页文档重新排版耗时约 1.4 毫秒,说明它在性能上有专门优化,不是简单堆功能。

核心概念速览

• OOXML:Word 文档的 XML 格式标准,.docx 文件本质是按这套规范打包的 XML 集合。wordcraft 的 docx crate 就是围着这套格式做读写。
• clean-room reimplementation(独立重写):不看原始源码,只根据公开规范重新实现同类功能。README 用这个说法解释 wordcraft 为何能做到"开源、无版权争议"的 Word 替代。
• Ribbon(功能区):Office 风格的顶部工具条,把格式、插入、审阅等操作分类摆在条状界面里。wordcraft 在 ui-egui crate 里专门有一个 ribbon.rs 实现这块 UI。
• MCP:给 AI 建一个"遥控器接口",代理可通过它调用程序里已定义好的命令,不用模拟鼠标点击。wordcraft 有专门的 mcp crate 实现这个服务器,供外部代理驱动文档操作。

OOXML 是它要兼容的目标格式,clean-room 重写是实现方式,Ribbon 是给人用的界面,MCP 是给 AI 用的接口。

架构拆解

仓库是一个 Rust workspace,按模块划分:

• wordcraft-doc(crates/doc):文档的数据模型,段落、样式、表格结构都定义在这里,是整个项目的地基。
• wordcraft-docx(crates/docx):负责 .docx 文件读写,把 OOXML 解析成文档模型,或反过来序列化回去。
• wordcraft-layout(crates/layout):排版引擎,做断行、分页、表格布局、点击命中测试等计算密集工作。
• wordcraft-engine(crates/engine):核心调度层,管理编辑会话、撤销重做、389 个命令的集合,以及 Word 功能对照表。
• wordcraft-mcp(crates/mcp):MCP 服务器实现,把 engine 里的命令包装成代理可调用的工具。

依赖关系很直接:docx 读完文件后构建出 doc 模型;engine 的会话对象排版时调用 layout 模块计算结果;mcp 收到代理请求后执行的是 engine 里现成的命令;UI(ui-egui)同样通过调用 engine 的命令驱动界面变化;命令行工具(apps/wordcraft-cli)里还带了一个 mcp 子命令,把 CLI 和 MCP 服务器串起来。整个架构是"一套命令,多种入口"------UI、CLI、MCP 共享同一套 389 个命令,这是 README 反复强调的设计思路。

关键实现走读

排版缓存值得细看,体现了项目对性能的态度。来看 crates/engine/src/session.rs 里 Session::layout 的实现:

pub fn layout(&mut self) -> Arc<DocLayout> {
    let ww = self.view.web_width;
    if let Some((r, w, m, l, pf)) = &self.layout
        && *r == self.rev
        && (*w == ww || self.view.mode == ViewMode::Print)
        && *m == self.view.mode
        && *pf == self.view.proofing
    {
        return l.clone();
    }
    let opts = LayoutOptions { view: self.view.mode, web_width: ww, show_hidden: self.view.marks, proofing: self.view.proofing };
    let l = Arc::new(wordcraft_layout::layout(&self.doc, &mut self.cache, &opts));
    self.layout = Some((self.rev, ww, self.view.mode, l.clone(), self.view.proofing));
    l
}

做了什么:函数先检查缓存结果(self.layout 元组)是否还能用,判断依据是文档版本号 rev、网页视图宽度 web_width、视图模式 mode、校对状态 proofing 四个条件是否一致。全部匹配就直接返回缓存里的 Arc(带引用计数的排版结果,克隆它只增加引用计数,不重新计算)。条件不满足才真正调用 wordcraft_layout::layout 重算,再存入缓存。

为什么这样写:排版计算是文档处理里最耗资源的环节,涉及断行、分页、表格布局等逐字符逐段落的运算。188 页文档重排约 1.4 毫秒的速度,很大程度靠的就是这种"状态没变就不重算"的缓存策略。rev 版本号的设计也说明:只要文档内容没被编辑(rev 不变),哪怕用户只是切换窗口焦点或滚动页面,也不会触发重新排版。

没有它会怎样:如果每次调用 layout() 都重跑一遍排版算法,用户频繁滚动、缩放、切换视图模式时每次界面刷新都要重算断行分页,大文档(几百页报告)会明显卡顿。尤其 Rust 版本还开启了 unsafe_code = forbid 这种工作区级别 lint 规则,也就是放弃了用不安全代码做底层性能优化,缓存复用就成了保证流畅度的关键手段之一。

动手上手

克隆仓库后用 cargo 直接跑:

git clone https://github.com/storytold/wordcraft
cd wordcraft

执行后应能在当前目录看到工程文件,包含 Cargo.toml 和 crates/、apps/ 等目录,说明克隆成功。

用带样例文档启动桌面应用:

cargo run --release -p wordcraft -- --sample        # the desktop app with the sample document

首次执行会触发 Rust 编译(release 模式编译通常比 debug 慢,需耐心等待),编译完成后应弹出桌面窗口,自动加载示例文档,界面能看到功能区(Ribbon)、样式面板等元素。

打开自己的文档:

cargo run --release -p wordcraft -- report.docx     # open a document

验证方式是检查窗口标题或文档内容区是否正确显示了 report.docx 的内容。

命令行工具提供格式转换能力:

wordcraft-cli convert report.docx report.pdf        # docx, pdf, odt, rtf, html, md, txt, png

执行完检查当前目录是否生成了 report.pdf,文件大小不为零且能用 PDF 阅读器打开,即可确认转换成功。

另外两个检查类命令:

wordcraft-cli text report.docx                      # plain text
wordcraft-cli inspect report.docx                   # structure as JSON

text 命令应在终端输出文档的纯文本内容,inspect 命令应输出一段 JSON,描述文档结构(段落、样式层级)。两个命令都能正常打印内容而不报错,说明 docx 解析模块工作正常。

应用场景

• 本地编辑 .docx 文档 :用 cargo run --release -p wordcraft -- report.docx 打开文档进行排版和样式调整,适合不想依赖微软生态、需要跨平台(macOS/Windows/Linux/BSD)编辑能力的用户。不过 ROADMAP 自评功能对等约 62%,具体哪些高级功能缺失需实际打开复杂文档逐项核实。
• CLI 批量转换文档 :用 wordcraft-cli convert 做格式转换,支持 docx、pdf、odt、rtf、html、md、txt、png,适合放进脚本或 CI 流程做批量处理,不需要图形界面。
• 代理驱动的文档自动化 :通过 MCP 服务器把文档操作暴露给 AI 代理,官方接入方式类似 claude mcp add wordcraft -- wordcraft-cli mcp,配合 list_commands、execute 等工具调用具体命令。细节文档在 docs/mcp.md,适合想让 AI 自动生成报告、批量改格式的团队深入看。

独立分析

这个项目最有意思的地方不是"又做了一个 Word 替代品",而是把文档操作做成了一套可以被程序和 AI 代理共享的命令集。README 提到同一套 389 个命令同时驱动功能区点击、键盘快捷键、命令搜索框、CLI、JSON 控制通道和 MCP 服务器,这意味着无论是人点一下"插入表格",还是 AI 代理通过 MCP 调用对应命令,底层走的是完全一样的执行路径。这种设计比单独做一个"AI 插件"更彻底,因为从架构层面就没把人机操作分成两套逻辑。

但功能完整度和成熟度是现阶段最大的不确定因素。README 自评功能区覆盖率 87%、深度实现约 62%,且 alpha 版本还没发布,ROADMAP 里图表、SmartArt、公式编辑器等功能排在后续计划里。这是一个诚实但也意味着风险的自评------62% 的深度对等具体缺在哪些场景(比如复杂表格合并、特定审阅标记样式),没有展开说明,需要用户自己拿实际文档跑一遍才能摸清边界。808 星配 285 fork 的比例也值得注意,fork 数相对星标数不低,可能说明有一部分开发者是出于贡献或调试目的在跟进代码,而不只是单纯关注。

局限与风险

• README 明确标注 alpha 版本尚未发布,意味着当前代码还没经过大规模真实 .docx 文件测试,也没有原生打印功能和首个带签名的发布包,生产环境使用需谨慎。
• ROADMAP 把图表、SmartArt、公式编辑器和 Draw 选项卡列为"之后实现",目前这些高级排版和绘图能力是缺失的。
• 功能深度对等约 62% 只是整体估算,具体哪些命令是"能跑但效果和 Word 不一致"没有列出清单,实际使用中可能在某些排版细节上和 Word 原生表现有差异。
• 插件或扩展机制的实现细节现有资料中没有说明,如有二次开发需求需先看源码或等文档补充。
• 38 个未关闭 issue 和创建仅一个多月的仓库年龄放在一起看,说明项目还在快速迭代期,API 和命令集可能会有变动。

结论卡片

适合谁:需要跨平台开源 Word 替代方案的个人和团队,尤其是想把文档操作接入 AI 代理工作流(通过 MCP)的开发者,以及对 Rust 内存安全特性有偏好、想要可审计文档处理内核的技术团队。

不适合谁:需要图表、SmartArt、公式编辑器等尚未实现功能的用户,或需要生产级稳定性、不能接受 alpha 阶段风险的场景。

下一步:在决定投入使用前,建议先去仓库 ROADMAP.md 核实具体的功能对等清单,拿几份有代表性的真实 .docx 文件(含表格、修订、引用等元素)实际跑一遍转换和编辑流程,确认深度实现的 62% 具体覆盖了哪些场景,再评估是否满足生产需求。

---

项目地址：github.com/storytold/w...

原文地址：tools.wflynn.cn/aitools/git...