Aham Word

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. 缺信息先问：任何具体事实（客户名、报价数字、日期、编号）用户没给，绝不编造；

先问，或留占位 —— 封面/字段函数支持自动标「待补录」（琥珀色）。

1. 生成脚本：写一段可直接运行的 Python，import aham_word as aw，用下面的函数逐块搭建，结尾 doc.save("输出.docx")。
2. 运行 + 校验（有执行环境时）：跑脚本生成 .docx。

• 目录是 Word 域：普通 soffice --convert-to pdf 不填充目录；要在不开 Word 下导出带目录的 PDF，运行 python scripts/update_toc_export.py 输入.docx 输出.pdf（UNO 先更新域再导出）。

1. 交付：把 .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。

---

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

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 接口）。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Aham-AIAPP
• Source: Aham-AIAPP/aham-word
• License: MIT

Install and usage instructions live in the source repository linked above.