中文正式文书的 .docx 生成

这个 skill 解决什么

pandoc x.md -o x.docx 能跑通，但产物是给英文博客用的：标题 #0F4761 青蓝色、20/16/14pt 且不加粗，Letter 纸型，西文 Aptos。拿去做中文合同，对方法务一眼就觉得不正式。

更麻烦的是三类只有"看了才知道"的问题：表格跨页被劈成两半、条款标题孤零零留在页底而正文在下一页、签章区甲方在上一页乙方在下一页。这些在生成时不报错，在 Word 里打开才看得见。

所以这个 skill 的核心不只是参数，还有一定要把每页渲染成图片看一眼的工作流。

工作流

# 1. 写 markdown（模板见 templates/contract.md）
# 2. 生成
python3 scripts/build.py 合同.md
# 3. 检查：结构 lint + 转 PDF + 逐页渲染
python3 scripts/verify.py 合同.docx --render
# 4. 真的去看渲染出来的 jpg —— 至少看封面、表格页、签章页

第 4 步不能省。前三步全部通过、文档在 Word 里能打开，版面依然可能很难看。看图发现问题后回到 markdown 或 build.py 改，重跑。

verify.py 的版面体检会标出"偏空的页"，那通常意味着有东西被强行推到了下一页——可能是对的（附件另起页），也可能是表格放不下。看图确认。

两个渲染器，各验各的

LibreOffice 匹配不到「宋体 / 黑体」这类中文字体名（即使系统里装着），会回退到 Arial Unicode MS 之类。替换字的度量不同，连页数都会显著变化——同一份合同实测 Word 出 17 页、LibreOffice 出 27 页，差 59%。

所以不能只用一个渲染器：

Word 之所以权威，是因为它自带 SimSun / SimHei，和对方 Windows Word 看到的一致。

实用节奏：改稿循环用 LibreOffice（快、无干扰、能抓结构错误），定稿前在 Word 里开一次确认真实分页与字体。

verify.py 会自动检查字体有没有被替换，并据此告诉你这次的渲染图能信到什么程度。

markdown 怎么写

YAML frontmatter 提供封面信息：

---
title: 技术服务合同
party_a: 【甲方全称】
party_b: 【乙方全称】
party_a_label: 甲方（客户）
party_b_label: 乙方（服务方）
style: A
---

@@COVER@@

## 第 1 条 定义

1.1 **服务**：……

@@SIGNATURE@@

三个占位符：

四套封面与签章方案

用 style: 或 --style 选。差别只在封面、签章区、页眉横线，正文版式相同。

拿不准就用 A。它最像国内公司常见的合同范式，对方法务看着眼熟、审得快。

--all 一次出四份，把封面页渲染出来给人挑。

中文合同的几个惯例

这些不是排版细节，是不写就显得外行的东西：

• 封面靠不同对齐区分信息组：合同编号靠右、缔约方靠左且互相对齐、签订日期单独下沉。全部居中会把这种区分抹平。
• 签章区在正文之后另起，竖排堆叠（甲方组、乙方组上下分开），不是并排表格——盖章需要留白。
• （本行以下无正文，仅供签章之用） 这句要有，防止在空白处补写内容。
• 占位符用 【】，不用 [] 或下划线。待议的数字也用 【10】。
• 页脚要有"第 X 页 / 共 Y 页"，防抽换页。build.py 用 PAGE/NUMPAGES 域自动生成。

更多见 references/contract-zh.md。

排版参数

正文宋体 12pt、1.5 倍行距；标题黑体纯黑加粗 16/14/12pt；A4，上下 2.54cm、左右 3.00cm。

完整参数与取值依据见 references/house-style.md。要改整体风格（比如换仿宋、换字号）就改 scripts/build.py 顶部的常量块，那里集中了全部度量。

分页控制

Word 里控制分页的四个开关，build.py 已经预置，写 markdown 时按需要用：

价格、赔偿上限、责任范围这类条款建议套 Together——被分页切成两半会显得很不专业，也容易在传阅中被误读。

::: {custom-style="Together"}
**本条单价适用条件**：单次充值不低于人民币【　　】元……
:::

表格列宽

pandoc 的管道表列宽由分隔行的连字符数量决定，不是内容。默认全等宽，长内容列会挤成多行而短列一片空白：

| 里程碑 | 时间 | 内容 | 付款 |
| ---------- | --------- | -------------------------- | -------- |

按各列实际内容量分配连字符。中文全角字在 10.5pt 下约 210 twips，正文宽 8504 twips——照这个估每列需要多少。

两个 pandoc 陷阱

- (a) 文字 会变成空项目符号 + 嵌套列表。 pandoc 的 fancy_lists 把 (a) 当成有序列表标记，于是外层项目符号是空的、真正的内容缩进两层。build.py 会自动把这类行转成转义括号 + 悬挂缩进样式。手写 OpenXML 时要记得转义成 \(a\)。

智能引号会把中文引号变成两个右引号。 "通道存在" 经 pandoc 的 smart 扩展后可能渲染成 ”通道存在”——开引号也是右引号。直接在 markdown 里写中文引号 “ ” 最省事。

OpenXML 的硬约束

如果要手写或修改 OpenXML（而不只是调 build.py 的常量），先读 references/openxml-gotchas.md。最容易踩的是：

<w:pPr> 和 <w:style> 的子元素顺序由 XSD 强制。 顺序写错，Word 打开会报"文档已损坏"，而且报错信息完全不提元素顺序，极难 debug。build.py 的 ppr() 按正确顺序拼装，verify.py 的 lint 会检查产物。

常见顺序错误：spacing 放在了 keepNext 前面；tblPr 放在了 pPr 前面；jc 放在了 ind 前面。

依赖

brew install pandoc poppler
brew install --cask libreoffice     # 渲染检查用，强烈建议装

pandoc 必需。poppler 提供 pdftotext / pdftoppm，做版面体检和渲染。

自动化转换首选 LibreOffice——headless、不抢屏、不会卡。verify.py 没找到它时会回退到调用 Microsoft Word（macOS，AppleScript），那条路能出正确字体但不可靠：Word 是 GUI 应用，弹任何对话框都会把转换卡死，脚本既看不见也关不掉。

两个都装最好：LibreOffice 跑循环，Word 做定稿确认（见上文"两个渲染器"）。

参考文件

• references/house-style.md — 完整排版参数、取值依据、四套方案的设计说明
• references/openxml-gotchas.md — XSD 元素顺序、分页控制、页眉页脚注入、字体主题
• references/contract-zh.md — 中文合同的结构与惯例（封面、条款编号、签章、附件）
• templates/contract.md — 可直接改的合同骨架