技术解读
WordFormat：把 Word 排版这件苦差事交给代码
项目背景与痛点
Word 排版的问题从来不是"不会调字体"，而是"调不完"。
单个文档花十分钟手工修一遍无所谓，但当你要处理五十份从不同人手里收上来的报告、一百份历史公文、或者一批投稿论文时，真正的麻烦才浮现出来：每份文档都带着自己的"格式习惯"——有人用样式刷了标题，有人直接手调加粗三号；有人粘过来的正文里，每个 run 都残留着源文档的直接格式；中英文混排时因为字体槽位没配对，Word 自动回退成等线或者 Calibri；行距一会儿 1.5 倍一会儿固定值 28 磅，看起来"差不多"，打印出来一眼就露馅。
Word 自带的"格式刷""样式集"只在单文档内有效，VBA 宏能批量跑但极难维护、跨平台基本无解，而 Python 生态里的 python-docx 虽然能改格式，却对中英文字体分流、样式继承链、编号定义这些 OOXML 深处的结构束手束脚。WordFormat 切的正是这块空白：把"格式规整"从人工劳动变成一次可重复执行的批处理。
核心技术揭秘
理解这个项目的关键在于一个判断：文档格式处理的本质不是"排版"，而是"状态归一化"。.docx 本质上是一个 zip 包，里面是 OOXML——word/document.xml 装正文，styles.xml 装样式定义，numbering.xml 装列表编号规则。而 Word 的格式生效遵循一条优先级链：
文档默认值 → 段落样式（含 basedOn 继承链）→ 字符样式 → 直接格式
格式混乱的根源几乎全部出在最后一环：大量来自复制粘贴的文档，每个 run 上都挂着直接格式，把上层的样式定义彻底覆盖。所以正确的做法不是"逐个改字体"，而是先判定段落的语义角色，再剥掉游离的直接格式，重新挂回干净的样式。
数据流大致是这样：
段落角色判定是整个系统技术含量最高的部分。可用的信号很多，但没有一个是可靠的：pStyle 样式名在不同来源的文档里五花八门（“标题 1”/“Heading 1”/“1,1,1”），outlineLvl 在手工调格式的文档里常常为空，字号加粗的组合又能被正文模仿。真正稳的做法是多信号加权 + 上下文启发式：看 outlineLvl、看是否含 numPr 编号属性、看段长与结尾标点、看是否以"一、“”（一）""1."开头、看前后段落是否为空白——综合打分后落到模板的标题层级上。这是典型的规则引擎设计，准确率取决于规则覆盖度，也注定了它无法做到 100%。
中英文字体分流是另一个容易被低估的坑。OOXML 里 w:rFonts 有四个槽位：w:ascii（西文）、w:hAnsi（西文高位字符）、w:eastAsia（东亚文字）、w:cs（复杂文种）。想让"中文宋体 + 英文 Arial"真正生效，四个槽位必须分别正确设置；更隐蔽的是 w:asciiTheme、w:eastAsiaTheme 这类主题字体属性——主题字体的优先级会直接覆盖显式指定的字体，不先删掉它们，你设的宋体永远不生效。这正是很多"脚本改完没反应"的真实原因。
行距同样有陷阱：w:spacing 的 w:line 单位是 twips，w:lineRule="auto" 表示倍数行距，"exact" 才是固定值；只改数值不改 lineRule，结果会完全跑偏。再叠加 w:snapToGrid（对齐文档网格）的影响，行距"看起来还是不对"几乎是必然的。
还有一个纯工程细节决定工具好不好用：幂等性。中英混排时 Word 会自动把一段文字拆成多个 run，如果只改格式不合并碎片，每跑一次就多出一批空 run 和碎片 run，文件越来越脏。合格的实现必须在输出前做一次 run 合并与空节点清理，保证同一份文件跑两遍结果一致。
功能亮点与差异
和同类方案比，WordFormat 的差异化不在功能数量，而在抽象层级选对了：
- 模板化而非硬编码。公文、报告、论文的格式规范差异很大，把"字体-字号-行距-缩进"抽成模板配置，才能一套引擎覆盖多种场景。这是它比一次性脚本更有生命力的地方。
- 中英文分槽处理。市面上大量"批量改字体"的脚本只设
w:ascii，中文字体纹丝不动，用户以为工具坏了。四槽位 + 清主题属性是必须做对的基本功。 - 批量 + 可重复。相比 VBA 宏，命令行工具可以进 CI、可以版本管理、可以跨平台跑在服务器上；相比手工，它提供的是一致性保证而不是"差不多就行"。
应用场景与落地建议
适合的场景很明确：格式规整改制，而不是精细排版设计。典型用例包括企业历史文档统一到新版模板、投稿前按期刊要求批量调格式、教培与出版机构的来稿归一化、知识库迁移时的样式对齐。
生产落地有几条必须注意：
- 永远先跑副本。格式改写是不可逆的破坏性操作，缺少 dry-run 报告和回滚机制之前，不要碰唯一副本。
- 目录域与交叉引用未必自动刷新。改了标题格式后，TOC 域需要重新计算，必要时借助 LibreOffice 无头模式打开刷新一次。
- 警惕"脏文档"的边界情况：修订痕迹、批注、表单控件、嵌套表格、文本框与浮动图片定位，这些区域的格式重写风险远高于正文。
- 列表别拍平。处理
numbering.xml时要尊重numId/ilvl的复用关系，粗暴重编号会把多级列表变成一堆散装段落。 - 接受人工兜底。启发式判定必然有误判，把它定位成"处理 90%，剩下 10% 出报告让人看"，比宣称全自动更诚实也更可用。
综合评价
优点：抽象选得准——"语义识别 + 样式归一化"而不是逐字符改属性，这条路走对了；中英文字体四槽位处理和主题属性清理这两个细节，说明作者真的和 OOXML 搏斗过；模板化 + 批处理的定位，精准命中了办公场景里最耗人的那部分工作。
不足：规则引擎的天花板就是它的天花板，文档来源越杂、格式越脏，误判率越高，越依赖人工复核；对域代码、页眉页脚、文本框这些"文档外围状态"的处理深度，直接决定它能否真正进入生产流程；如果缺少 dry-run、差异报告和幂等保证，批量操作的风险会劝退不少谨慎的团队。
一句话总结：它是一个务实的格式规整器，不是排版引擎。把它当作流水线上的标准化工序，而不是设计师的替代品，你会用得相当舒服。
相关仓库
学习如何设计大规模系统。为系统设计面试做准备。包含 Anki 闪卡。
评论