---
name: agf-writing-docx-reports
description: 用 docx-js 写"阅读友好的中文 docx 报告"（决议书 / 评审报告 / 调研 / 分析 / 投标书等高密度报告型文档）。当用户要求把 markdown 内容转 docx 且抱怨"格式混乱 / 不专业 / 看不下去"时启用——pandoc 默认转换难以满足。提供：路径决策 / 设计 token / 可复用 helper 全套 / 11 个 pitfall / 生成-预览闭环。
---
# 写 docx 报告 — 高密度实战手册
> 重型参考材料（设计 token / spacing 数值 / 9 个 helper / 文档外壳 / 用法示例 / 装配顺序）在 `references/`，按下方索引**按需 Read 全文**，不要凭记忆手写。
## 何时用本 skill
| 信号 | 用本 skill |
|---|:--:|
| 用户要把 markdown 报告 → docx | ✅ |
| 报告是中文 / 含大量表格 / 需要视觉强调（决议 / 警示） | ✅ |
| 用户反馈"格式混乱 / 不专业 / 字段被分行 / 段前段后大 / 页边距宽" | ✅ |
| 报告需要封面页 / 自动目录 / 页眉页脚 / 警示框 | ✅ |
| 只是导出几页纯文本 / 没有表格 | ❌ 用 pandoc 默认即可 |
| 要做的是 PPT / Excel | ❌ 转 pptx / xlsx skill |
## 路径决策（3 选 1）
| 路径 | 何时选 | 代价 |
|---|---|---|
| **pandoc 默认** `pandoc x.md -o x.docx` | 内部草稿 / 纯文本为主 / 表格 ≤ 3 个 | 几秒；视觉无控制 |
| **pandoc + reference.docx** | 想统一字体 / 标题色但不要 callout | 中等；要先在 Word 里手工调样式做模板 |
| **docx-js 全定制**（本 skill 核心） | 正式对外报告 / 高密度表格 / 警示框 / 封面页 | 一次写 ~600 行 JS，复用率 90% |
判定经验：**用户说"格式混乱"基本就是要 docx-js**——根因是 pandoc 的列宽 auto + 无样式覆盖。
## References 索引（什么时候必读哪份）
| 场景 | 必读（Read 全文） |
|---|---|
| 动手写任何 docx-js 生成脚本前 | [`references/design-tokens-and-helpers.md`](./references/design-tokens-and-helpers.md)——设计 token / spacing 收紧数值 / 9 个可复用 helper + 用法示例 / 文档外壳模板 / 结构化数据→表格技巧 / 装配顺序，全套粘贴即用 |
## 配色铁律
- 标题用 `PRIMARY`（深蓝）不用默认黑——视觉层次靠颜色对比
- "强制不通过 / 警示 / 一票否决"用 `DANGER` + 浅红 BG callout
- "事实风险 / 即将逾期"用 `WARN` + 浅黄 BG callout
- 表头一律 `PRIMARY_LIGHT` 底，body 用 `ALT_ROW` 隔行底（zebra）
- 普通文本辅助信息（注释 / 路径）用 `MUTED` 灰
## spacing 要点（完整数值表见 references）
段前段后是 docx 最易膨胀的维度：default spacing（before 240+ / after 180+）= 19 页，收紧后 15 页（-21%）。收紧基准：H1=240/120、H2=160/80、H3=120/60、p=40/40、表格周边=30/30、bullet=30/30、cell margins=60/100。
## 11 个 pitfall（踩过的坑）
| # | 坑 | 解决 |
|:-:|---|---|
| 1 | 中文字体没指定 → LibreOffice 渲染丑 | 每个 TextRun 都带 `font: "PingFang SC"`（不能依赖 default styles） |
| 2 | 表格列宽 auto → 长字段强制换行 | 设计稿基准列宽 + `scaleWidths` 缩到 `CONTENT_WIDTH`；table.width + cell.width **两处都设** |
| 3 | `WidthType.PERCENTAGE` 在 Google Docs 渲染异常 | 全部用 `WidthType.DXA` |
| 4 | `ShadingType.SOLID` 让 cell 整块变黑 | 用 `ShadingType.CLEAR`（这是 docx 协议惯例反直觉的地方） |
| 5 | 段前段后 spacing 用默认 → 文档膨胀 30% | H1=240/120、H2=160/80、p=40/40、表格周边=30/30 |
| 6 | `PageBreak` 单独放 → 生成无效 XML | 必须在 Paragraph 里：`new Paragraph({ children: [new PageBreak()] })` 或 `pageBreakBefore: true` |
| 7 | bullet 用 `• Item` 字面字符 | 必须 `numbering.config` + `LevelFormat.BULLET` + Paragraph 的 `numbering: { reference: "bullets", level: 0 }` |
| 8 | docx-js 默认 A4，国内场景 OK；但海外项目要 Letter | A4: 11906×16838 / Letter: 12240×15840（都是 DXA） |
| 9 | cell margins **不计入** columnWidths → 实际可用窗口比想象小 | columnWidths 总和 == table.width；cell 内 padding 是 margins 单独算 |
| 10 | TOC 标题没出现 | Heading1/2/3 必须用确切 ID 覆盖样式 + `outlineLevel` 必填 |
| 11 | `validate.py` 依赖 defusedxml 可能没装 | 跳过 validate.py，用 `pandoc → plain` 反向读 + `unzip -l` 看结构替代 |
## 生成 → 预览 → 反馈闭环
```bash
# 1. 安装依赖
npm install -g docx
# 2. 写脚本到 /tmp/gen.js（不要写到项目目录，跑完即弃）
# 3. 跑生成
NODE_PATH=$(npm root -g) node /tmp/gen.js
# 4. 转 PDF 看效果（LibreOffice 会用 PingFang SC fallback）
python3 .claude/skills/docx/scripts/office/soffice.py --headless --convert-to pdf output.docx
# 5. 截图前 6 页
pdftoppm -jpeg -r 110 -f 1 -l 6 output.pdf /tmp/preview
# 6. Read JPG 验证视觉
# （如有问题：改 token / 列宽 / spacing，回到 3）
# 7. 反向 pandoc 验证内容完整性
pandoc output.docx -t plain | head -60
```
**关键**：截图给用户看比 review JS 代码有效 10 倍。**像设计师一样反复看渲染图，别像程序员一样 review 代码**。
## 用户反馈映射（常见 → 调整）
| 用户反馈 | 你要调的 token |
|---|---|
| "页边距太宽" | `MARGIN` 左右 1440 → 720；重算 `CONTENT_WIDTH` |
| "表格分行" | 同上 + 重新分配 `widthsBefore`（让长字段列更宽） |
| "段前段后大" | H1 H2 H3 + p 的 spacing 全局缩 50% |
| "颜色太花" / "正式场合" | 砍掉 OK 绿 / WARN 黄，只保留 PRIMARY + DANGER + MUTED |
| "中文字体丑" | 检查每个 TextRun 是否带 `font: FONT`；考虑加 `Microsoft YaHei` 备选 |
| "想要封面页" | section 0 加居中大标题 + 元信息 + 红框 callout |
| "想要目录" | 加 `new TableOfContents("目录", { hyperlink: true, headingStyleRange: "1-3" })`；Word 打开后 F9 刷新 |
| "页码不对 / 没页眉" | section.headers/footers + `PageNumber.CURRENT` / `TOTAL_PAGES` |
## 决策矩阵 — 不需要 docx-js 的反例
| 场景 | 用什么 | 原因 |
|---|---|---|
| 1 页备忘录 | pandoc | 不值得写 600 行 JS |
| 内部 README | 留 markdown | 别强行 docx |
| 含复杂数学公式 | LaTeX → PDF | docx 公式渲染不稳 |
| 1000+ 行数据表 | xlsx skill | docx 表格大了渲染慢 |
| 简历 / 投递书 | Word 模板手填 | 别造轮子 |
| 含截图 / 图片 | docx-js + ImageRun（必须带 `type` 参数） | OK 但要算图片尺寸（EMU 单位，914400 = 1 inch） |
## 自检清单（交付前）
逐条 grep 验"11 个 pitfall"前三条（`font: FONT` 不漏 / 无 `PERCENTAGE` / 无 `SOLID`）+ 跑完整"生成 → 预览 → 反馈闭环"（soffice 转 PDF 截图自看 + 反向 `pandoc -t plain` 验内容没丢）。两节全过 = 可交付用户。