agf-writing-docx-reports

# 写 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（踩过的坑） | # | 坑 | 解决 | |:-:...