aham-word

# AGENTS.md — 给 AI 的消费指引

**你是 AI（写文档 / 编码 agent），要生成 Word？先读完这页再动手。**

Aham Word 是机读文档规范 + 参考引擎，目的是**让你产出风格一致的 .docx，不要自由发挥**。
性格：极简、克制、留白、内容优先；软黑的纸、钢蓝点缀、单一无衬线。

## 一条铁律

**值只从 `word-tokens.json` 取，颜色只用调色板，字体只用三族（微软雅黑 / Inter / Consolas），
字号/间距/表格线只用既定档位——绝不自创值、不手写格式、不放装饰。**

## 消费顺序

1. **取值** → `word-tokens.json`：页面 / 颜色 / 字体 / 字号 / 段落 / 标题装饰线 / 表格 / 列表 / 引用 / 字段 / 页眉页脚 / 目录 / 禁止项开关。直接引用，不改不近似。
2. **取规则** → `references/word-spec.md`：影响 Word 排版的元素全清单（取什么值、禁止什么）。
3. **出文档** → `scripts/aham_word.py`：调封装好的构件（`add_title` / `add_body` / `add_doc_table` / `add_cover` / `add_toc` …），不要绕过它自己写 OXML。
4. **看成品** → `examples/aham-word-demo.docx` / `.pdf`：标准方案/报告长这样。

## 按任务怎么做

- **方案 / 报告**：封面（`add_cover`，留空字段自动「待补录」）→ 目录（`add_toc`）→ 标题层级（`add_title/h2/h3`）→ 正文（`add_body`）→ 表格（`add_doc_table`）。
- **会议纪要 / 函件 / 需求说明**：通常无需封面目录，直接标题 + 正文 + 列表 + 表格。
- **报价 / 数据表**：用 `add_doc_table`，`numeric_cols` 标数字列（右对齐 + 等宽 + 千分位），`total_row=True` 出合计。
- **换品牌**：复制 `word-tokens.json` 改值，或设环境变量 `AHAM_WORD_TOKENS` 指向你的文件；引擎自动按新值产出，**不改代码**。

## 产出前自查（最常违反的）

- 颜色：正文标题软黑 `#262626`（**不是纯黑**）；蓝 `#336EE8` 只在标题装饰线/关键数字/链接，**绝不铺底/铺行/铺列**。
- 字体：中文微软雅黑、西文 Inter，正文标题同族；数字 Consolas；**中文禁等宽、禁斜体**；标题不用衬线。
- 表格：**只横线**，无竖线/外框/全网格；表头加粗 + 浅灰底 `#F3F3F3`（仅表头，数据区不铺色）；数字右对齐等宽；合计靠加粗；自动适配页边距不溢出。
- 不手敲：页码用域、项目符号用列表样式、缩进用首行缩进、标题用标题样式。
- 不编造：用户没给的事实留「待补录」，先问，绝不填虚构数字/客户名/日期。
- 文档固定亮色，不跟随系统暗色（Office 轨）。

## 文件清单

| 文件 | 用途 |
|---|---|
| `word-tokens.json` | 值（机读，单一事实源） |
| `references/word-spec.md` | 规则（影响排版的元素全清单 + 禁止项） |
| `scripts/aham_word.py` | 参考引擎（读令牌出 .docx） |
| `scripts/update_toc_export.py` | 更新目录域 + 导出 PDF（UNO） |
| `examples/build_examples.py` | 生成示范文档的脚本 |
| `examples/aham-word-demo.docx` / `.pdf` | 成品示范 |
| `SKILL.md` | 技能入口（触发词 + 工作流 + API） |

**拿不准就回到 `word-tokens.json` 和 `references/word-spec.md`，不要猜。你的工作是执行这套规范，不是设计。**