# ENGINE —— 主题排版装配规则

> 本文件由 gzh-design-skill 的 SKILL.md 提炼适配（AGPL-3.0，见同目录 LICENSE 与 README）。融合改动已用「融合」标注。装配 HTML 时**具体代码一律从主题组件库取，不凭记忆手写**。

## 装配流程

1. **读两份库**：所选主题的 `theme-{标识}.md`（设计变量、组件 HTML、模板骨架、配方表、映射规则）+ `common-components.md`（代码块 / 图片·GIF / 小标签标题，所有主题共用）。一篇文章只用一套主题，不跨主题混组件。
2. **判定文章类型**（取主导类型，可复合）：教程/操作指南、盘点/工具清单、观点/深度分析、访谈/人物特稿、数据复盘/报告、生活/情感随笔、案例实战——直接沿用第 1 步已选定的主类型，不重复判定。
3. **查配方表**：按文章类型在该主题库「文章类型 → 组件组合配方」表选核心组件组合与点缀组件，保证同类文章排版气质稳定；配方外元素按主题库映射规则表补充。
4. **装配**：按主题库「完整文章模板骨架」的顺序，把 article.md 的每个元素替换为对应组件。每个段落、每张图都要转换，不得遗漏，不增删实质内容。

## 行内标记映射

- `**加粗**` → 主题主色加粗（锚点层）
- `==高亮==` → 渐变背景高亮；`<u>文字</u>` / `++文字++` → 下划线；`~~文字~~` → 荧光笔
- `> 引用` → 引用高亮块（开头引言用主题引言卡）
- 代码/命令/Prompt → common-components 1a/1b 代码块（**必须**，塞普通段落会丢缩进）；行内 code → 1c
- 图片 → 2a（只有 `![说明](url)` 真有说明文字才加说明行，不编造）；**融合**：本地 `imgs/*.png` 路径原样保留，草稿箱同步时由 publish_draft.py 替换为微信域名

## 智能处理（装配时必须做）

1. **章节自动编号**：按 `##` 顺序编 01/02/03…；末章为结语/总结时用主题库指定的结语编号变体（如 `∞`）。
2. **英文标签**：据中文章节标题生成（实测→TEST、教程→TUTORIAL、总结→SUMMARY…），主题库有槽位才用。
3. **正文关键词下划线（核心特色）**：对每个正文段落主动挑 1–3 个最重要短语（4–15 字），用 theme-index「正文下划线 CSS」列的值标记——优先核心观点、结论、关键数据、专有名词。原文没有加粗也要标；与写作侧「加粗是扫读落点」互补：md 里的加粗进锚点层，下划线在装配时补标。不整段划线。
4. **引言关键词高亮**：开头金句的核心词用高亮组件。
5. **目录**：主题库有目录组件时，从全部 `##` 挑最重要的 3 个作精选导读，不是全量章节列表。
6. **签名区**：「融合」只在**该账号画像配置了文末固定块**时渲染（对应 style-rules「不自动追加关注引导」红线），文案逐字取自画像；画像没配就不生成签名区。原文末尾已有的签名/引导段并入这唯一一处，不在中间或多处出现。
7. **中文全角标点**：正文标点全角（，。！？：；""''（）——…），生成时直接写弯引号；代码块/行内代码/URL/英文标识符内保持原样。
8. **列表**：按主题库映射规则；无专属组件时转带缩进正文段。

## 视觉层级（3 层，防滥用）

| 层级 | 作用 | 频率 | 手段 |
|------|------|------|------|
| 锚点层 | 最强锚点：产品名/步骤/CTA/核心金句 | 全文 ≤5 处 | 主色加粗、深底白字引用 |
| 标记层 | 正文关键词 | 每段 1–3 处 | 下划线 |
| 容器层 | 引用块、标签、长句强调 | 按需 | 浅底引用、荧光笔、徽章 |

## 平台红线（校验脚本兜底，但装配时就该守）

- **禁止**：`<style>`/`<script>`/`<div>`、`class`/`id`、`position:fixed|absolute|sticky`、`float`、`@media`/`@keyframes`、`display:grid`、CSS 变量、外部字体/CSS。
- **必须**：样式全内联；所有文字节点用 `<span leaf="">文字</span>` 包裹（漏包是粘贴丢样式的头号原因）。
- **可用**：有限 `display:flex`、`linear-gradient`、`border-radius`、`box-shadow`、`<section>/<p>/<span>/<strong>/<img>/<h3>`。

## Gotchas（实战踩坑，高频返工点）

- 代码块每行一个 `<p style="margin:0">`，**绝不用 `white-space:pre`**（会渲染出大缩进+空行）；缩进用全角空格 `　`。
- 半角标点（中文后的 `, ; ! ?`、英文直引号）是最高频返工点，校验 WARNING 也要清零；但代码内不「全角化」。
- 图片用 `max-width:100%;height:auto;display:block;margin:0 auto`，**不用 `width:100%`**（小图拉伸变糊）；只有表格/封面卡/流程图布局元素才铺满。
- 强调/小标题用左竖条、药丸标签，**不用四周虚线框**（主题库自己定义的虚线组件除外）。
- 产物是纯 `<section>` 正文片段，**不包** `<!DOCTYPE>`/`<html>`/`<head>`/`<body>`（编辑器只接受正文片段）。
- 占位图/名片图没有真实 URL 时整行删掉，不留占位符。

## 校验与输出（融合）

```bash
# 1. 合规校验：ERROR 与半角标点 WARNING 都清零才算完成
python3 scripts/validate_gzh_html.py <文章目录>/article.html
# 2. 预览页：浏览器打开 → 右上角「复制到公众号」→ 编辑器粘贴
python3 scripts/wrap_preview.py <文章目录>/article.html <文章目录>/article_预览.html
```

「融合」产物命名固定：干净正文 `article.html`（草稿箱同步与校验用），预览页 `article_预览.html`（人工粘贴用）——不用原工程的 `{名}_排版_{主题}.html` 命名。校验不过回到装配修，不带着 ERROR 交付。