Docx Craft

---
name: docx-craft
version: 0.1.0
description: NoDesign Word 文档设计守则 —— 产出 .docx（真 Word 文件，对方能打开接着改）。先问这份文档给谁看、进什么流程，再把用户嘴里的形容词翻译成一个真实存在的版式名，然后试作、给看、改、锚定、铺开。含中英两套排版军规（中文：eastAsia 字体槽 / 首行缩进随字号 / 禁则 / 中文无真斜体；西文：半角标点 / 段间距不缩进 / 真斜体 / 磅值字号，按产物正文主体语言选，拿不准走中文）、闭合 token 契约、结构真实性（真样式真编号真表格几何）、渲染验收回路。**当用户明确要一份 .docx / Word 文件，或要的东西必须能在 Word 里打开继续编辑，或是有格式硬规定的正式文书（公文、学位论文、合同、投递用简历）时使用。** 反向：要演示 / 幻灯片 / PPT 走 deskskill-engine-mini，要网页 / 站点 / 落地页走 site-craft。⚠️ 用户只说"做个报告 / 写个方案"而没提格式时**不要**用这条 —— 默认仍走 deck 或站点，画布里可看可迭代是主场，Word 是显式出口。
---

# 核心守则：跟 deck / 站点同一条路

**命名 → 试作 → 给看 → 改 → 用户说"就这个" → 锚定 → 铺开**

区别只在试作做什么：deck 试作一页封面，站点试作首页上半屏，**文档试作头一页**
（标题区 + 两三段正文 + 一个二级标题）。文档的气质八成由正文排版决定 —— 行距、
首行缩进、标题层级的字号跳跃。只给用户看个漂亮封面，铺到正文那天他会说"怎么跟
我想的不一样"。

## 〇、先问三件（决定后面所有取舍）

1. **给谁看** —— 领导 / 甲方 / 评审 / 投递对方
2. **进什么流程** —— 要不要盖章、要不要走 OA、要不要打印、对方会不会在上面批注
3. **对方用什么打开** —— 绝大多数情况是 Windows 上的 Word；这条决定字体怎么选

第 3 条尤其不能跳。**docx 的字体是"点名"不是"备选链"** —— 一个槽只能写一个名字，
没有 CSS 那种 fallback。点了用户机器上没有的字体，Word 会自己替一个，你控制不了。

## 一、先给版式一个名字

跟 deck / 站点同一条规矩：**把形容词翻译成一个真实存在的版式名**。形容词
（"正式一点""清爽点"）把模型推向均值；名字有可仿照的对象。

docx 的版式谱系跟网页不是一套，常用的这些：

| 用户可能说 | 翻译成 | 落到 token 上是哪几条 |
|---|---|---|
| 要正式 / 报上去的 / 盖章 | **公文体（GB/T 9704-2012）** | 三号仿宋正文、固定行距 28pt、每页 22 行、黑体一级楷体二级、页边距 37/26/35/28mm |
| 论文 / 投稿 / 毕业 | **学术论文体** | 小四宋体、1.5 倍行距、章节编号、图表题注 |
| 商务 / 提案 / 汇报 | **商务简报体** | 小四、段前段后留白、无首行缩进改段间距、标题带细规则线 |
| 就要普通的 / 别花哨 | **办公标准（素颜 Word）** | Word 默认观感本身。⚠️这是**正当选择，而非省事之举** —— 要混进办公流程的文档，"看起来像人在 Word 里敲的"就是需求 |
| 简历 / 投递 | **单页履历体** | 窄边距、姓名区大字号、条目左对齐悬挂缩进、零装饰 |
| 手册 / 说明书 | **技术文档体** | 编号标题、等宽代码块、表格密排 |

⚠️ 公文体的已知问题（来自实测反馈）：严格国标的三级标题**同缩进、纯换字体**
（黑/楷/仿宋），而预览的替身字体会吃掉楷体与仿宋的对比度 —— 三级在预览里几乎
不可辨，用户大概率抱怨"层级看不出来"。两条路先问一句：a) 严格国标（对方单位
真按 9704 收文时用）；b) **层级强化变体**（用户没点名国标就默认它）——
Heading1 加 `spacing.beforePt: 8`、Heading2 加 `indent.leftChars: 200` + `bold: true`，
层级立刻一眼可辨且不破坏 exact 行距的页数稳定性。

内置词典条目有三个（`build_docx` 的 `preset`）：`办公标准` / `公文` / `学术论文`。
**它们是起点不是菜单** —— 上表其余的用 preset 起手再覆写 tokens，或者干脆不写
preset 给完整 token 表。自造词作废（"科技感文档"不是版式名），但凡是真实存在、
你能说出它长什么样的版式，都可以当名字。

## 二、token 是真相源，docx 是构建产物

工作方式**只有这一种**：

```
写/改 文档.json  →  build_docx  →  screenshot_canvas 看  →  改 JSON  →  再 build
```

⛔ **永远不要直接改 .docx**。它是构建产物，下一次 build 会把你的手改无声抹掉。
（外来文档除外，见第七节。）

**放进文件夹，一份文档一个家**：`报告/文档.json` + `报告/文档.docx`。画布会把
整个文件夹显示成一张文档卡，里面所有 .docx 都是它的成员，用户在窗里切换查看。
所以**用户要保留旧版时，另起文件名**（`报告/终稿v2.json` → build 出 `终稿v2.docx`，
新旧并排），⛔ 别覆盖旧版 —— 版本保留是为了用户查阅，不是为了节省空间。

起手文件 `文档.template.json` 已经拷进工作区了 —— 照着它改，别从空白开始。
**字段全集 Read `references/token-schema.md`**（⚠️ 相对**本 SKILL 文件所在目录**，
不相对工作区 —— 用加载本 skill 时给出的 SKILL.md 路径拼出绝对路径去 Read，
别在工作区里找、更别 find / 全盘扫）—— 键名、值域、单位、块的形状、
常见错法对照全在那里，别靠猜，也别去读引擎源码。

**schema 是闭合的**：写了没登记过的字段名，`build_docx` 直接报错。这是故意的 ——
静默忽略会让你以为那条排版指令生效了。闭合的是"哪些问题必须回答"，不是"答案是
什么"，跟"不预设范式"不冲突。

⭐ **没写的值由打开文件的那个渲染器决定**（Word 各版本 / WPS / Pages 各不同）。
网页至少还有一份 CSS 初始值规范兜底，docx 没有。所以：**凡是你在意的值就显式写出来**，
别指望默认。

## 三、结构真实性：不许假造

这一条决定文档是"能看"还是"能交"。

- **标题必须是真样式**（带 `outlineLevel`），不是"把一行字调大加粗"。假标题
  → Word 的导航窗格是空的、TOC 生成不出来、对方改样式时它不跟着变。
- **列表必须是真编号定义**，不是手打 `1.` `2.` 或者 `•`。假列表在用户插一条的
  时候不会自动重排，删一条就断号。写法：`tokens.numbering` 里起个名字挂一个梯队，
  段落上 `list: { name:'条款', ilvl:0 }`（单层可以简写成 `list: '条款'`）。
  内置四个梯队都是照中文排版传统定的，**先用内置的**：
  - `公文条款` 一、→（一）→ 1. →（1）。首行缩进两字、文字紧跟编号、折行顶格
  - `数字条款` 1. → 1.1 → 1.1.1。悬挂缩进，折行对齐到文字起点
  - `圈码` ①②③ —— 中文文档里"并列要点"最常见的那种
  - `项目符号` ●○▪（故意用真汉字区符号，不用 Symbol/Wingdings 的私用码位：
    那些在没装对应字体的机器上会变豆腐块）
  自己写梯队见 `references/token-schema.md` 的 numbering 节。
- **表格必须给显式几何**（DXA 宽度，`tblW` / `tblGrid` / 每个 `tcW` 要一致），
  不许靠 autofit，不许拿表格当版式骨架。
- **缩进用缩进属性，不用空格/全角空格凑**。

判据很简单：**用户在 Word 里改一处，会不会散架。** 会散架的就是假的。

## 四、排版军规

**先定这份文档的正文主体是什么语言**，排版规矩跟它走 —— 不跟界面语言走，也不跟
当前对话使用的语言走。一个界面设成英文的人照样会做中文简历，反过来也一样；brief 里
没说清就问一句。中英混排按**正文主体**那一种算（中文文章里引几句英文，仍是中文文档）。

### 4.1 中文正文（默认路径）

下面六条是硬约束，不是可选项：


1. ⭐ **`eastAsia` 槽必须设。** 中文字符走的是 `w:rFonts` 的 `eastAsia` 槽，
   只写 `ascii` 等于没给中文指定字体。token 里 `fonts` 每个槽四件套都要填。
2. ⭐ **首行缩进用字符单位**（`firstLineChars`，200 = 两字符），不要用固定磅值。
   字号一变，固定磅值的缩进就不是两个字了。（引擎会自动同时发 twip 兜底，
   因为 LibreOffice 不认单独的 chars —— 这条已经内建，你不用管。）
3. **首行缩进和段间距二选一。** 中文正文传统是缩进不留白；两个都上是网页习惯
   带过来的错，看起来会松垮。
4. **中文没有真斜体。** Word 的中文斜体是把字硬拉斜，很难看。强调改用
   加粗 / 换字体（楷体）/ 着重号（`em`）/ 字号。
5. **标题不要跟着正文缩进。** 标题样式 `basedOn` 正文时会继承首行缩进 ——
   这是中文文档最常见的排版缺陷之一。标题样式里显式写 `firstLineChars: 0`。

字号用中文字号名（三号 / 小四 / 五号）比写磅值可靠，token 直接收它们。

### 4.2 西文正文（例外路径）

**只有确认正文主体是西文时才走这一节**，拿不准就走 4.1。逐条对应上面：

1. `eastAsia` 槽照样填 —— 英文文档里也会出现中文（人名、引用、参考文献），
   槽空着那几个字就掉到系统默认字体。这条不是中文特有的，别关。
2. 首行缩进**不用**。西文段落靠段间距分段，不靠缩进；两个都上跟中文里两个都上
   一样难看。`firstLineChars: 0` + 段后距。
3. 上一条的推论：4.1 第 3 条的"二选一"在这边固定选段间距那一边。
4. **西文有真斜体，正常用。** 书名、期刊名、外来语、强调都走 `i`，
   别为了跟中文一致改成加粗。
5. 标题不缩进这条照旧（`firstLineChars: 0`），理由一样。
6. 标点用**半角**，后面跟一个空格。中文文档里的全角 `，：` 出现在英文正文里
   是最明显的一种错。引号用 `"…"` / `'…'`，不用 `「」`。
7. 字号写**磅值**（11pt / 12pt），不用中文字号名 —— "小四"在英文语境里没有意义。
   正文常用 11pt 或 12pt，行距 1.15 到 1.5。
8. 编号走 `1. / a. / i.` 这套，不用 `①②③`（4.1 里推荐的圈码是中文文档的习惯）。

⚠️ 这一节是**例外**，不是"另一半"。判断不出正文主体语言时，
走 4.1 —— 给中文文档套西文排版，比反过来更容易被一眼看出不对。

## 五、渲染验收：做完必须看

`screenshot_canvas` 对 .docx 会渲成页图（LibreOffice → PDF → PNG），带 `pages` 参数
（`"3"` / `"2-5"` / `"all"`），默认前两页、一次最多六页。

⚠️ **构建没报错不等于排版对了。** docx 没有 DOM，没有 `query_elements` 可查 ——
渲染是唯一的验收手段。每次 build 完看一眼，不要攒到最后。

**渲染预览的三条已知失真**（caption 里也会重复，别忘）：

- **中文字体看平台**（caption 会说明本次是哪种）：站点是替身字体（雅黑/等线→MiSans、
  仿宋→朱雀仿宋、宋体→Noto Serif、楷体→LXGW 文楷），字形跟用户 Word 里有差，字形观感不能判；
  桌面版 Windows 用的是本机真字体，五件齐全时字形可以照图判，缺的那几件才是替身。
  **CJK 全角等宽，断行位置两边都一致**。
- ⚠️ **multiple 行距下页数不可照图判**（实测：预览中 2 页的
  简历在真实 Word 中会变成 4 页）。multiple 乘的是**字体自带行高**，替身和真机字体
  不同高 —— 雅黑/等线档已对齐（MiSans 1.326 ≈ 真雅黑 1.32，Windows Word 基本
  同高），但宋体等其它档、Mac 替到苹方（≈1.4）仍有差。**页数敏感的文档（简历
  「必须两页」、公文这类）行距一律用 `exact` / `atLeast` 磅值**：磅值在哪个
  渲染器里都一样高，页数就钉死了（公文词典条目本来就是 exact 28pt，天然免疫）。
- **TOC 域显示的是占位文案**，不是真目录（Word 打开更新域才生成）。页码域是
  正常的，看到几就是几。

**能判的**：版面留白、行距密度、标题层级跳跃、缩进、表格对齐、孤行寡行；
exact/atLeast 行距下分页位置也能判。
**不能判的**：字形好不好看、目录内容、multiple 行距下的页数、跨版本 Word 兼容性。

最后一条只有用户能验 —— 交付时主动说一句"建议在 Word 里开一遍确认"。

## 六、验收次序

```
build_docx        →  过不了就按报错改 JSON，别猜
screenshot_canvas →  看版式
（多页文档）screenshot_canvas pages:"N-M"  →  看分页处有没有孤行、标题掉在页底
交付前            →  提醒用户在真 Word 里开一遍
```

## 七、外来文档（用户上传的 .docx）

⚠️ 这部分能力尚未开放，请勿向用户承诺。现在能做的只有：读它的内容、渲染它、
原样导出。原件的定点修改暂不支持。

如果用户要改一份上传的文档，应如实说明：可以基于它的内容**重新生成**一份
（使用本产品的 token 源，后续修改更清晰），但不能在他那份原件上做定点修改。
问清楚他要哪种再动手。

## 八、导出

`raw` 就是那个 .docx 本身 —— **它就是交付物**，不是"导出的副产品"，这跟 deck /
站点反过来。`pdf` 走 LibreOffice，是快速预览用的；要发出去的正式 PDF 让用户在
Word 里导（域和字体都对）。

用户要**页图**（PNG）时：`screenshot_canvas` 传 `saveTo:"交付/<文档名>页图"`（只落盘不看图再加
`shot:false`），页图写进这个文件夹，再用 `deliver_files` 交这个文件夹（整夹打成一个 zip）。
页图就是第五节那套渲染，字体失真一并告诉用户。