技术排版工具（如 Typst）具备源码化、版本控制和规则驱动渲染的优势，但企业协作环境的标准载体依然是 Microsoft Word。跨部门会签与公文报送无法脱离 .docx。

过去常见的过渡方式（Typst $\rightarrow$ PDF $\rightarrow$ Word）依赖视觉逆向工具，容易出现版面错位、公式损坏和表格断裂；直接向非技术人员交付未格式化的 Word，又会导致对方因视觉不合规而手工调乱底层结构。

本文介绍一套正向高保真注水与逆向容错两阶段归档的工程方案，在不改变协作方 Word 使用习惯的前提下，实现源码与办公文档的双向对齐。

1. 协作断层与破局思路

技术排版与办公文字处理存在不同的数据模型与协作假设：

维度 Typst 体系 传统 Word 协作体系
数据载体 纯文本源码（AST、函数、模块导入） 压缩包二进制（OpenXML、内联样式）
排版逻辑 样式与内容解耦，规则驱动渲染 所见即所得，大量依赖手工选区调整
版本管理 Git 行级 Diff 与分支合并 邮件/IM 互传文件、文件名尾缀与批注
协作痛点 无法直接交付给非技术同事协同修改 结构脆弱，多人修改后样式极易崩坏

破局的关键策略在于：对外交付符合企业公文规范的原生 Word，对内保留源码与版本控制体系。

双向协同架构与数据流闭环

2. 全局架构：流程编排与原子技能解耦

为保证可维护性与跨项目复用能力，系统将协作流程划分为 Workflow（工作流编排）、Skill（原子能力） 与 Templates（模板资产） 三层结构：

三层解耦架构

职责边界划分

  1. 上游起草（typst Skill）：
    • 专注于纯语义内容编写，使用 =、==、#table、#figure 等标准 AST 语法，禁止内联样式。
    • 默认仅产出 .typ 源码，由人工裁决后续导出动作（原生 PDF / Word / 纯源码留存），杜绝静默隐式编译。
  2. 正向转换（typst-docx-publisher）：
    • 基于 Pandoc AST 桥接，读取企业规范母版 reference.docx，将语义大纲映射为原生 Word Heading，实现字体、字号、段落网格的无损注水。
  3. 标杆逆向（docx-reference-builder）：
    • 从现有标杆红头文档中提取 styles.xml 与 numbering.xml，利用视觉指纹聚类算法，自动推导生成合规的 reference.docx。
  4. 两阶段归档（word-to-typst-archiver）：
    • 处理协作方返回的 Word 文档，执行清洗、AST 重构与 Section-level 差异合流。

3. 正向高保真注水：从源码到企业级 Word

直接使用常规转换工具生成的 Word，通常存在大纲层级丢失、字体不对齐、行距杂乱等问题，协作方往往会因“格式粗糙”而手动全选修改，破坏底层标记。

正向交付的流程如下：

  1. 检查 Typst 源码与元数据完整性；
  2. 匹配对应场景的 reference.docx（公文 / 报告 / 方案）；
  3. 调用 typst-docx-publisher 执行样式注水；
  4. 运行质量门禁审查（大纲窗格导航校验、表格对齐检查）；
  5. 输出交付版 DOCX 并记录 Git Baseline 锚点。

攻克“纯视觉”标杆母版

许多企事业单位的“标杆文档”在底层全是 Normal 样式，各级标题依靠手工设置“二号、小标宋、加粗”或“三号、黑体”。

若直接提取此类文档的样式表，生成的母版将缺少大纲定义。为此，docx-reference-builder 采用视觉指纹聚类与虚拟样式合成引擎：

标杆母版逆向提取与虚拟样式合成流程

该算法能够从无大纲样式的原始 Word 中，自动推导并重构出一份具备标准 Heading 1~4、且完全继承原文档字体和行距特征的 reference.docx 母版。

4. 逆向容错管道：被破坏的 Word 如何安全回流？

跨部门会签完成后收回的 Word，通常存在以下问题：

  • 样式全部降级为 Normal，大纲导航消失；
  • 标题前被打入硬编码的“一、/（一）/ 1.”序号；
  • 首行缩进被替换为手工输入的全角空格；
  • 单元格内存在无规律的软回车与断裂网格。

两阶段架构设计

直接将 Word 解析并全量覆写回主 Typst 文件会破坏主文件中的模板导入（#import "@local/..."）、页面配置、复杂函数调用以及专用组件（如 #callout[...]）。Word 无法表达这些语义，暴力覆写会导致工程资产丢失。

两阶段逆向架构通过“中间态净化 $\rightarrow$ 差异比对合流”解决这一冲突：

两阶段逆向归档管道

四层清洗与转换机制 (Stage 1 实现)

  1. Layer 1: 解包与资产提取器
    • 解开 .docx 容器，提取 word/document.xml 与 word/media/。
    • 将嵌入图片统一抽取至 .staging/assets/ 目录，按出现顺序命名并维护关系映射，避免图片丢失或重名覆盖。
  2. Layer 2: 启发式语义恢复引擎
    • 采用“正则模式 + 视觉权重”双轨判定，对退化为普通正文的段落进行大纲重构：
层级 识别特征（正则与视觉） Typst 映射 清洗规则
一级标题 命中 ^(第[一二三四五六七八九十百]+[章节]\|[一二三四五六七八九十]+、) 或 加粗+字号>=16pt = 标题文本 剥离硬编码编号前缀，由 Typst 自动编号接管
二级标题 命中 ^[（\(][一二三四五六七八九十]+[）\)] 或 加粗+14pt == 标题文本 统一括号为中文全角 （ ）
三级标题 命中 ^([0-9]+\.\|[0-9]+、) === 标题文本 统一序号标点
四级标题 命中 ^[（\(][0-9]+[）\)] ==== 标题文本 统一括号格式
普通段落 其他正文内容 纯文本段落 移除行首缩进空格、多余空行，修复断裂的软换行
  1. Layer 3: 表格规范化与对齐器
    • 解析 OpenXML 的 <w:gridSpan>（跨列）与 <w:vMerge>（跨行）标签。
    • 转换为 Typst 表格语法：#table(columns: ..., table.cell(colspan: n, rowspan: m)[...])，避免表格行列错位。
  2. Layer 4: Typst 模板序列化器
    • 输出纯净的 #figure(image(...)) 与段落流，支持独立编译调试。

5. 业务协同与版本生命周期

文档在实际流转中涵盖起草、跨部门会签与最终归档三个阶段。生命周期协议定义了不同阶段的执行路径：

业务协同与版本生命周期

  • 分支 A（常规迭代 / 需长期维护）：运行 Stage 1 逆向 $\rightarrow$ Stage 2 差异比对合流 $\rightarrow$ 回填 main.typ $\rightarrow$ 提交 Git 仓库。
  • 分支 B（紧急会签 / 终稿临界冲刺）：阶段性冻结 Typst 源码 $\rightarrow$ 直接在 Word 中完成最终会签 $\rightarrow$ 交付完成后一键逆向沉淀为 Typst 归档资产。

6. 演进路径与实践总结

通过“正向样式注水”与“逆向两阶段归档”，团队实现了以下效果：

  1. 协作方无感知：业务部门收到的始终是符合排版规范的原生 Word 文档，无需学习任何标记语言；
  2. 源码资产受保护：通过 AST 级 Diff 与安全注入，主 Typst 项目中的宏封装、排版参数与 Git 提交历史得以完整保留；
  3. 能力组件化沉淀：将标杆母版逆向、正向注水编译、脏文档清洗固化为全局可复用的 Skill。

后续演进将聚焦于提升复杂多层嵌套表格的逆向准确率，以及在 CI/CD 流程中引入自动化的排版质量门禁。