aham-word

---
name: aham-word
description: 用机读规范生成风格统一的 Word 文档（.docx），解决"AI 生成文档样式不统一、无法精确定义样式"。当用户说"做个 Word""做一份方案/报告/需求说明/会议纪要/函件 Word""把这个做成 Word""按规范出 Word""生成 Word 实施方案/说明"，或要把内容整理成 Word 交付物时触发。做法：所有样式取值集中在机读的 word-tokens.json（单一事实源），调用参考引擎 scripts/aham_word.py 据令牌生成结构合法、风格一致的 .docx（封面/目录/标题/三级层级/横线表/页码域）；不手写格式、不自由发挥字体磅值色值。默认走 Aham 品牌样式（微软雅黑/Inter/Consolas、钢蓝点缀、横线表、软黑 #262626），可通过改 tokens 一键换成自己的规范。注意：本技能用于 Word/.docx。
---

# Aham Word —— 写一次规范，AI 产出处处一致的 Word

> **本文件是给 AI 看的技能说明**（怎么调库、按什么规则产出 `.docx`）。
> 对外介绍 / 宣传那一份是 `README.md`，面向人，别把两者搞混。

把内容生成为**风格统一**的 Word 文档。核心理念：**样式不是每次手设，而是从一份机读规范取值。**

- **单一事实源**：所有影响排版的取值都在 `word-tokens.json`。改它 = 改全局。
- **参考引擎**：`scripts/aham_word.py` 读令牌、出 `.docx`，封装好封面/目录/标题/横线表/页码域等构件。
- **可换皮**：默认 Aham 品牌；要做自己的规范，复制 `word-tokens.json` 改色值/字体/字号即可，**不改代码**。

> 解决的问题：AI 一次次生成文档，字体、颜色、间距、表格各自为政——十几个文件十几种样式。
> Aham Word 把"该长什么样"写成机器能读的规范，AI 据规范产出，处处一致。

---

## 工作流（每次生成 Word 都按这个走）

1. **理解需求**：文档类型（方案/报告/需求/纪要/函件…）、要含哪些内容、是否要封面和目录。
2. **缺信息先问**：任何具体事实（客户名、报价数字、日期、编号）用户没给，**绝不编造**；
   先问，或留占位 —— 封面/字段函数支持自动标「待补录」（琥珀色）。
3. **生成脚本**：写一段可直接运行的 Python，`import aham_word as aw`，用下面的函数逐块搭建，结尾 `doc.save("输出.docx")`。
4. **运行 + 校验**（有执行环境时）：跑脚本生成 `.docx`。
   - **目录是 Word 域**：普通 `soffice --convert-to pdf` 不填充目录；要在不开 Word 下导出带目录的 PDF，运行 `python scripts/update_toc_export.py 输入.docx 输出.pdf`（UNO 先更新域再导出）。
5. **交付**：把 `.docx`（及需要的 PDF）给用户。

> 想换品牌/规范：改 `word-tokens.json`，引擎自动按新值产出，无需改 `aham_word.py`。
> 引擎找不到 `word-tokens.json` 时会回退到内置的 Aham 默认值（与 JSON 一致）。

---

## 库 API（`scripts/aham_word.py`）

调用前 `import aham_word as aw`。完整实现见脚本，常用函数：

**文档与结构**
- `new_document()` — 新建已套用 Aham 页面（A4、边距、页眉页脚距）与正文规范（雅黑/Inter 10.5pt、行距 1.5、中文版式）的空文档
- `add_page_break(doc)` — 分页符
- `set_tokens(path)` — 运行时切换 tokens 文件（换品牌 profile）

**封面与目录**
- `add_cover(doc, title, subtitle=None, meta=[(标签,值),...], org_text=None, classification=None, logo="brand")` — 封面：（默认）顶部嵌入 logo + 左对齐大标题 + 钢蓝短线 + 元信息块；`meta` 里值为 `""` 自动标「待补录」；自动分页。`logo="brand"` 用 tokens.brand.logo；`logo=None` 不放；`logo="路径"` 临时换
- `add_toc(doc, heading="目录", level_range="1-3")` — 自动目录（TOC 域）；自动分页

**图片 / Logo**
- `add_image(doc, path, width_cm=None, align="center")` — 嵌入图片；`path` 支持相对 tokens 目录解析（找不到会跳过不报错）
- Logo 由 `word-tokens.json` 的 `brand.logo` 指定，默认 `assets/aham-logo.png`；封面自动用它，换品牌改这一项即可

**标题与正文**
- `add_title(doc, text)` — 文档标题 H1（22pt 加粗 + 钢蓝装饰线）
- `add_h2(doc, text)` / `add_h3(doc, text)` — 一级（16pt）/ 二级（13pt）标题，带大纲级别
- `add_body(doc, text)` — 正文（10.5pt、首行缩进 2 字符、两端对齐、行距 1.5）
- `add_caption_text(doc, text)` — 说明/注释（9pt 三级墨色）
- `add_quote_block(doc, text)` — 引用/结论块（左侧钢蓝竖线，不填底）

**列表**
- `add_bullet(doc, text)` / `add_number(doc, text)` — 无序/有序列表项（用 Word 样式，绝不手敲符号）

**表格（Aham 横线表）**
- `add_doc_table(doc, headers, rows, numeric_cols=set(), total_row=False, col_widths_cm=None)`
  - 只横线、无竖线、表头浅灰底 `#F3F3F3`；`total_row=True` 末行合计（加粗）；`numeric_cols` 数字列右对齐 + 等宽 + 千分位；表头跨页自动重复；按可用宽度自动适配不溢出
- `add_table_caption(doc, text)` — 表题（放表格**上方**）
- `add_figure_caption(doc, text)` — 图题（放图片**下方**，居中）

**单据字段**
- `add_field_pair(doc, label, value, pending=False)` — 标签在上、值在下；`pending=True` 标「待补录」（琥珀色）

**页眉页脚**
- `add_header(doc, text=None, logo="brand")` — 页眉：**右对齐 Aham 字标 logo** + 可选左侧标题 + 下方细线（`logo=None` 不放、`logo="路径"` 临时换）
- `add_page_number_footer(doc, left_text=None)` — 页脚（第 X 页 / 共 Y 页，页码用域）

---

## 铁规（引擎已实现，正确调用即可）

1. **软黑、克制用色**：正文标题软黑 `#262626`；层级靠字号字重不靠颜色；蓝只点缀，绝不铺底。
2. **横线表**：只横线、无竖线无外框、表头浅灰底 `#F3F3F3`；数字列右对齐 + 等宽 + 千分位；自动适配页边距不溢出。
3. **单一无衬线**：中文微软雅黑、西文 Inter，正文标题同族；数字用 Consolas；**中文禁等宽、禁斜体**。
4. **不手敲**：页码用域、项目符号用列表样式、缩进用首行缩进、标题用标题样式（不放大加粗冒充）。
5. **不编造**：用户没给的事实留「待补录」，先问，绝不填虚构数字/客户名/日期。

字体速查：正文/标题 微软雅黑 + Inter；数字 Consolas；正文 10.5pt、H1 22 / H2 16 / H3 13；软黑 `#262626`；钢蓝 `#336EE8` 点缀；表格线 `#E7E7E7`；待补录琥珀 `#8A7333`。

---

## 标准文档骨架（含封面+目录的方案/报告）

```python
import aham_word as aw

doc = aw.new_document()
doc.sections[0].different_first_page_header_footer = True   # 封面不显示页眉页脚

aw.add_header(doc, "你的公司名 / 文档标题")
aw.add_page_number_footer(doc, left_text="你的公司名")

# ① 封面（用户没给的字段留空 → 自动「待补录」）
aw.add_cover(doc,
    title="XXX 项目实施方案",
    subtitle="副标题",
    classification="内部资料",
    meta=[("客户名称", ""), ("项目编号", ""), ("文档版本", "V1.0"), ("签署日期", "")])

# ② 目录
aw.add_toc(doc)

# ③ 正文
aw.add_title(doc, "XXX 项目实施方案")
aw.add_body(doc, "概述……")
aw.add_h2(doc, "一、项目目标")
aw.add_bullet(doc, "要点一")
aw.add_h3(doc, "1.1 范围说明")
aw.add_quote_block(doc, "结论：……")
aw.add_h2(doc, "二、报价概览")
aw.add_table_caption(doc, "表 1  项目整体报价（含税，单位：元）")
aw.add_doc_table(doc,
    headers=["项目", "供应商", "数量", "金额"],
    rows=[["...", "...", "1", "286,000"], ["合计", "—", "—", "604,000"]],
    numeric_cols={2, 3}, total_row=True, col_widths_cm=[6.5, 3.0, 2.5, 4.0])

doc.save("aham_output.docx")
```

简单文档（无需封面目录）：去掉 `different_first_page` 与 `add_cover`/`add_toc` 即可。

---

## 换成你自己的规范（卖点）

1. 复制 `word-tokens.json`。
2. 对照 `references/word-spec.md`（影响 Word 排版的元素全清单）逐项改：色值、字体、字号、间距、表格线、页码格式、`brand.logo`（换成你的 logo）……
3. 用环境变量指定：`AHAM_WORD_TOKENS=/路径/你的-tokens.json`，或把它放在引擎能找到的位置（脚本同级/上级/当前目录）。
4. 不改一行代码，引擎按你的规范产出。

---

## 坑与提醒（如实告知用户）

- **字体回落**：.docx 里写「微软雅黑 / Inter / Consolas」。运行/打开环境没装这些字体会渲染回落（如 Linux 沙箱 → Noto），但 .docx 的 XML 仍写雅黑/Inter，Windows + Word 打开即正确。要对外完全一致可在 Word 里嵌入字体。
- **目录是 Word 域**：内容在「更新域」时出现。真 Word 打开会自动更新（已写 `updateFields=true`），或 Ctrl+A、F9；普通 LibreOffice 转 PDF 不填充——用 `scripts/update_toc_export.py`。
- **一致性边界**：让 AI 复用本引擎是一致性关键；不要让它绕过引擎自己手写格式。

---

## 完整规范在哪

逐项核对"该规范哪些元素""取什么值"时，读 `references/word-spec.md`（影响 Word 排版的元素全清单 + 取值表 + 禁止项）。日常生成只需照本 SKILL.md 调库。

## 依赖

- `pip install python-docx`
- 运行引擎时把 `scripts/aham_word.py` 与 `word-tokens.json` 放在可被找到的位置。
- 转 PDF / 更新目录需 LibreOffice（`update_toc_export.py` 用其 UNO 接口）。