git:20260926.bc495aa to git:20260928.7d22abb

---

name: laohu-htmlshow-gzh

description: 将已有文章排成可粘贴到微信公众号的 HTML，提供主题选择、单篇风格调整、复制预览与格式检查；明确要求建设复用主题时提供专业设计并交接长期写回。普通浏览器展示使用 laohu-htmlshow；不登录或发布公众号。

---

开始本入口前，解析当前 `SKILL.md` 所在真实目录为 `{SKILL_DIR}`，读取 `{SKILL_DIR}/../../../docs/runtime.md`；本轮已加载则复用。该文件提供跨项目的路径、授权、交接和保存约定，读完回到本入口执行。

# 公众号文章排版 Skill

把已有文章转换为公众号正文 HTML，并提供复制预览。静态检查、浏览器复制和公众号实际显示分别验证，不承诺未经实测的样式保留。

核心资产是 `references/` 下的**主题组件库**（每套一个主题：设计变量 + 各组件完整 HTML + 模板骨架 + 映射规则）外加 1 套**通用增量库**（代码块 / 图片·GIF / 小标签标题，所有主题共用）。主题清单以 `references/theme-index.md` 为单一来源。本 SKILL.md 只负责流程与决策，**常规排版从组件库取结构；单篇新风格按专门设计分支调整，不凭记忆跳过组件与约束**。

## 工作流

### 0. 输入与格式归一化

用户可能给：Markdown 文本或 `.md` 路径（直接进第 1 步）、`.docx`、`.pdf`、`.txt`/无标记纯文本、网页富文本。**非 Markdown 输入必须先读 [references/format-normalize.md](references/format-normalize.md) 按其规则转成 Markdown 草稿**（docx 用 `scripts/extract_docx.py`，PDF 用 Read 分页读取+清噪，纯文本按标题启发式推断结构）。按现有材料直接整理并继续排版；交付时列出推断出的标题和明显不确定处，用户可指出要改的地方。只有缺少材料会妨碍保留原意或继续制作时才询问。什么都没给时，向用户索要。

用户要求制作排版成品时，按下文默认处理结构与主题，完成后交付并说明重要推断，用户可指出要改的部分。用户明确要先看选项或自己挑主题时，保留选择流程；用户说「直接排 / 自动排 / 一键 / 不用问」时则跳过可选检查点，全程自动完成。

### 1. 选主题（默认代选，可随时调整）

读 [references/theme-index.md](references/theme-index.md)（主题信息的单一来源）。用户已指定主题时直接采用；否则根据文章题材选择最契合的主题并继续排版，交付时说明选择，用户仍可要求换主题。不要把常规主题选择变成前置确认：

- **用户已在请求里指定主题** → 直接用，不问。

- **题材有明确契合** → 直接采用并简要说明理由。题材→主题契合参考 theme-index"适用场景"列：

- 教程 / 测评 / 清单 / 工具盘点 / 知识整理 / 方法论拆解（信息密度高）→ 摸鱼绿

- 深度分析 / 观点 / 力量感话题 → 红白色系

- 设计 / 科技评论 / 专业观点 / 高端品牌 → 石墨极简风

- 禅意 / 极简生活 / 深度随笔 → 留白禅意风

- 工具对比 / 创意评测（票据视觉隐喻）→ 摸鱼票据风

- 内刊手记 / 深度评测 / 案例复盘 → 橄榄手记

- **无明显倾向** → 采用 theme-index 标明的默认主题，继续排版并说明这是默认选择。

- **用户明确想从多个主题中选择** → 展示主题名称和适用场景；由用户选定后继续。

- **全自动模式**（用户明说「直接排 / 一键 / 不用问」）→ 不提问，自动选题材最契合主题或默认主题，交付时说明选择理由。

- **用户对现有主题都不满意 / 想要新风格** → 进入下文“风格调整与复用主题”按产物归属处理；单篇换风格不登记主题库。

- **theme-index 为空** → 停止排版，告知用户需要先添加主题风格（可走「自定义主题生成」）。

确定主题后进入该主题内部的组件匹配（第 3、4 步：判定文章类型 → 按该主题的配方表选组件组合）。

### 2. 读组件库（两份）

(1) 据 theme-index 中该主题的"组件库文件"列，Read 该主题专属组件库 `references/theme-{标识}.md`（含引言卡、章节标题、正文标记、签名等主题专属组件）。

(2) **同时 Read 通用增量库** `references/common-components.md`——代码块、图片/GIF、小标签标题这三类所有主题共用，套用当前主题主色即可。

常规主题排版从这两份组件库取结构；明确要求单篇新风格时，按已加载 theme-generator.md 的单篇分支调整或制作必要结构，仍遵守通用语义和正文静态规则。

### 3. 解析 Markdown 结构

| 元素 | 识别规则 |

|------|---------|

| 文章标题 | `# 标题` 或 frontmatter `title` |

| 开头引言 | 文章最开头的 `> 引用` 块 |

| 章节标题 | `## 标题` |

| 子章节 | `### 标题` |

| 行内标记 | 语义按 `references/common-components.md` 的“标记语义与主题适配”，主题只选择对应视觉组件 |

| 引用段落 | 非开头的 `> 文字` |

| 图片 / GIF | ``、``（GIF 与图片同样处理） |

| 代码 / 命令 / Prompt | ` ``` 围栏代码块 ``` `、行内 `` `code` `` |

| 分割线 / 列表 | `---`、`***` / `- 项` 或 `1. 项` |

| 表格 | `\|` 分隔的 Markdown 表格（常来自 docx 转换）→ 优先用主题库的表格/卡片组件（主题库映射规则为准） |

| 段内硬换行 | Markdown 行末两个空格后的换行是源文明确换行；HTML 中保留为 `<br>`，不合并成普通空格或新段落 |

| 制表符 | DOCX 转换得到的四个不换行空格是可见分隔；放在 leaf 文本中原样保留，不压成一个空格。它不代表精确保留 Word 自定义制表位 |

| 表格单元格换行 | `<br>` 留在对应单元格，不拆开表格行；单元格中的不换行空格按原样保留 |

**解析完结构后，判定文章类型**（取主导类型，可复合）：教程/操作指南、盘点/工具清单、观点/深度分析、访谈/人物特稿、数据复盘/报告、生活/情感随笔、案例实战。判定依据：步骤和命令多→教程；并列条目多→盘点；引语和人物叙事多→访谈；数字和对比多→数据；论证推演多→观点。

### 4. 按配方选组件组合 → 装配 HTML

**先查所选主题库的「文章类型 → 组件组合配方」表**，按文章类型确定本篇的核心组件组合与点缀组件——不要拿到组件库就逐段随机选组件，配方保证同类文章的排版气质稳定。配方之外的元素再按主题库映射规则表补充。

然后依主题库的**"完整文章模板骨架"章节**装配，把每个 Markdown 元素替换为对应组件：

- **骨架顺序以主题库为准**，不同主题骨架可能不同，不要套用其它主题的骨架。

- **行内标记**：按已加载通用库的“标记语义与主题适配”选择主题内的等义组件，缺项使用通用组件；主题编号不同，不套用其他主题编号。

- 来自**通用增量库**的组件：` ``` 代码块 ``` `→ 1a 深色 / 1b 浅色代码块，行内 `` `code` ``→ 1c；``→ 2a 图片（有说明才加说明组件）、`.gif`→ 2b GIF；需要突出的**小标题/强调**→ 3a 左竖条小标题或 3b 药丸标签，金句→ 3d、提示旁注→ 3e。**优先级：先查主题库映射规则表**——该主题有等价语义组件（如自己的金句/提示块）就用主题库版本保持气质一致；主题库没有对应组件时才用通用库 3x 并按其换色规则换成主题色。

- **一篇文章只用所选主题的那一套组件**，不跨主题混用。

- **强调与小标题用"小标签/左竖条"，不要用虚线框**：要突出一个小标题或一段内容时，用左竖条小标题（3a）、药丸标签（3b）、左竖条金句/提示块（3d/3e）；**不要用四周虚线框（`dashed` border）套一个标题**，那样笨重抢戏。

### 5. 校验合规（强制）

把生成的 HTML 写入目标文件后，**必须运行校验脚本**，ERROR 清零才算完成：

```bash

# 用脚本所在 skill 的绝对路径调用，HTML 参数也用其实际路径（两者目录通常不同）

<SKILL_ROOT>/scripts/validate_gzh_html.py <生成的.html 的实际路径>

```

它静态检查本 Skill 明列的禁用标签、属性和样式、正文片段结构、所有可见文字节点的 `<span leaf>` 包裹及中文叙述中的半角标点或直引号。完整英文句子的英文标点予以保留。任何检查项未通过都要回到第 4 步修复。通过只表示静态规则检查通过，不证明真实公众号编辑器的粘贴或显示效果；交付时不得把脚本结果表述成平台验收。

### 6. 输出

**产物格式：纯 `<section>…</section>` 正文片段，从全局容器开始，不要包 `<!DOCTYPE>`/`<html>`/`<head>`/`<body>`**——公众号编辑器只接受正文片段，多余的文档外壳会被丢弃或干扰粘贴。

1. **干净正文文件**：HTML 保存到当前工作目录，文件名 `{原文件名}_排版_{主题中文名}({英文标识}).html`（英文标识 = theme-index 组件库文件名去掉 `theme-` 前缀与 `.md` 后缀）。这份用于校验和手动粘贴兜底。

2. **带「复制」按钮的预览页**（让用户一键复制，免去手动全选）：

```bash

<SKILL_ROOT>/scripts/wrap_preview.py <上面的干净正文.html>

```

产出 `{...}_预览.html`——浏览器打开后右上角有「复制到公众号」按钮，点一下即把渲染后的富文本复制到剪贴板（只复制正文选区），再到公众号编辑器 Ctrl/⌘+V 粘贴。按钮和脚本只在预览外壳里、**不在被复制的 section 内**，所以粘到公众号的仍是干净合规正文。

3. 告知用户：**打开 `{...}_预览.html` → 点右上角「复制」→ 公众号编辑器粘贴**；并给出干净正文文件路径作为兜底。附校验脚本结论（已通过 / 剩余 warning）。

## 生成时的智能处理（这些是本 skill 的特色，必须做）

1. **章节自动编号**：按 `##` 出现顺序分配 `01/02/03…`；末章若为结语/总结类，用主题库指定的结语编号变体（如 `∞`），主题库未指定时沿用数字编号。

2. **英文标签**：据中文章节标题生成英文标签（实测→TEST、教程→TUTORIAL、总结→SUMMARY、思考→THOUGHTS…），主题库有对应槽位时使用。

3. **正文关键词下划线（核心特色）**：对**每个正文段落**主动找出 1–3 个最重要的短语，用该主题的下划线 CSS（见 theme-index）标记。优先标核心观点、结论、关键数据、专有名词；短语 4–15 字；整段无要点可不标。即使原文没有任何加粗也要主动加下划线——它是出现频率最高的基础标记。

4. **引言关键词高亮**：识别开头金句里的核心词，用高亮组件标记。

5. **目录提取**：主题有导读组件时，默认展示最能说明本文价值的至多三个看点。

- **默认选择**：先根据文章主要问题选直接回答它的结论、关键做法或决定性材料；多个条目表达同一价值时保留更具体的一项，不机械取前三章。

- **展示顺序与编号**：选定后按原文顺序展示；条目显示章节编号时取对应正文的原编号，交付前逐项核对标题与编号，不按精选位置重编或用全文替换误改编号。

- **标题与内容边界**：沿用原标题或忠实概括，不增加正文没有的承诺。

- **章节不足或不可用**：章节不足三个时不补凑；没有可用章节时省略。

- **用户要求完整目录**：用户要求完整目录时列全部章节，按同款条目扩展组件，不套精选限制。

- **组件槽位与示例**：组件示例中的三个槽位只示范外观，按实际条目增删。例如修复教程依次是“背景、术语、失败原因、修复方法、验收结果”，导读优先选择后三项。

6. **开头引言卡署名**：按文章的**作者或主题**而定——文章有署名就写"—— 作者名"，没有明确作者就用与主题相关的简短落款或直接省略。**不要固定写"甲木"**（尾部签名区同样用 `{{作者名}}` 占位，见第 7 条）。

7. **尾部作者签名区（作者自填，仅末尾一处）**：**默认不写死任何人名**，用占位署名让用户替换成自己的。

- 第一句（作者介绍）：`我是 {{作者名}}，{{一句话简介，如：热衷于分享 AI 观察与干货}}`——用户在请求/偏好里给了署名或简介就直接填入；没给就**保留 `{{作者名}}` / `{{简介}}` 占位**，并在交付时提示用户替换成自己的署名。

- 第二句（互动引导，通用可保留原样）：`如果你觉得今天这篇有收获，欢迎**点赞、在看、转发**三连，我们下篇见`

- **原文末尾已有作者签名段**（如"我是 XXX…"）→ 直接沿用原文的署名，不替换成占位。

8. **列表转换**：按主题库映射规则处理；无专属列表组件时转为带缩进的正文段落。

9. **中文叙述使用全角标点**（，。！？：；“”‘’（）—— …），生成 HTML 时直接使用中文标点。完整英文句子保留英文标点与直引号，不转换成中文标点；英文专名、URL 和代码标识符内部的标点同样原样保留。中文句中的半角中文标点改为全角；代码块和行内代码原样保留。

## 视觉层级（3 层递进，所有主题通用）

| 层级 | 作用 | 频率 | 手段 |

|------|------|------|------|

| 锚点层 | 最强锚点：产品名/步骤/CTA/核心金句 | 全文 ≤ 5 处 | 主色加粗、深色底白字引用 |

| 标记层 | 正文关键词，每段 1–3 处 | 高频 | 下划线标记 |

| 容器层 | 引用块、概念标签、长句强调 | 按需 | 浅底引用、荧光笔、徽章 |

## 正文片段静态规则（校验脚本检查下列禁项）

- **禁止**：完整文档外壳 `<html>/<head>/<body>`；`<style>/<script>/<title>/<meta>/<base>/<link>/<div>`，以及表单和交互媒体标签 `<button>/<form>/<input>/<select>/<option>/<textarea>/<video>/<audio>/<canvas>/<svg>/<iframe>/<object>/<embed>/<source>`；`class`/`id` 及 `on*` 事件属性；`position:fixed/absolute/sticky`、`float`、`@media`/`@keyframes`/`@import`、`display:grid`、CSS 变量和外部字体。

- **必须**：样式全部内联 `style`；所有文字节点用 `<span leaf="">文字</span>` 包裹（否则粘贴后样式丢失）。

- **可用**：`display:flex`（有限）、`linear-gradient`、`border-radius`、`box-shadow`、`<section>/<p>/<span>/<strong>/<img>/<h3>`。

## Gotchas（真实排版踩过的坑）

- **漏 `<span leaf>` 包裹**是最常见致命错——粘贴到公众号后样式整片丢失。靠第 5 步校验脚本兜底，别跳过。

- **下划线：逐段落实、每段 1–3 个短语**。不要整段划线（失去焦点），也不要有的段标有的段漏；列表项里的关键描述同样要标。

- **章节编号错乱**：严格按 `##` 顺序，不要跳号；结语编号变体只用于末章，中间章节不能用。

- **签名区有且仅有末尾一个**：用固定文案，不在中间或多处出现；原文末尾若已有作者签名/"点赞在看转发三连"类段落，识别并**并入**这唯一的签名区/CTA 卡片，不要保留原文段又再生成一个。

- **图片说明硬造**：只有 `` 里真有说明文字才生成说明组件；`` 空 alt 不要编造说明。

- **图片自适应、不铺满**：`<img>` 一律 `max-width:100%;height:auto;display:block;margin:0 auto`——按图片自身尺寸显示、居中，大图缩到容器宽、小图保持原尺寸。**不用 `width:100%`**（会把小图也拉伸变糊）；只有表格 / 封面卡 / 流程图这类布局元素才用 `width:100%`。

- **跨主题混用组件**：一篇文章只用所选主题 + 通用库的组件，不从其它主题借组件。

- **锚点层滥用**：最强强调全文 ≤ 5 处，到处加粗等于没有重点。

- **原文内容遗漏**：每个段落、每张图都要转换，不得漏；DOCX 的段内硬换行、表格单元格 `<br>` 和不换行空格分隔应在 HTML 中继续可见；不要自行增删原文实质内容。

- **占位图残留**：签名区/CTA 组件里若带名片图占位（如 `<img src="...名片或引导图URL">`），没有真实图片 URL 时整行删掉，不要把占位符留在产物里。

- **不用虚线框**：突出标题/强调用小标签或左竖条（通用库 3a–3e），不要用 `border:…dashed` 四周虚线框包标题。**例外**：主题库明确定义的虚线组件（如摸鱼绿的 quote-box 引用框、oneliner-card 亮点卡）是该主题的风格特征，按主题库用法正常使用。

- **标点按语言保留**：中文叙述中的半角中文标点改成全角；完整英文句子、英文专名、URL、代码标识符及代码块中的英文标点保持原样。不要把英文句子改成中文标点。

- **代码/Prompt 必须用代码块**：文章里的代码、命令、提示词用通用库代码块组件（1a/1b），不要塞进普通段落或引用块，否则缩进和等宽会丢失。

- **代码内容与布局分开**：生成、字符保留和复制验证统一遵循通用库 1a；不得用排版字符替换原代码。

- **待补素材居中**：`【插入…】`、待录屏 / GIF / 视频 / 成果图等占位，用通用库 **2c 居中素材占位板块**（浅底柔虚线框 + 居中图标与说明），不要用左对齐的提示块。

## 风格调整与复用主题

当前文章换风格与长期主题建设按用户所需产物区分。“这篇不要现有主题”“这篇按参考图排”只调整当前作品；认可一次预览不自动授权登记常驻主题。只有明确要求新增、维护可复用主题或组件库，才进入长期建设；已明确的授权不重复询问。

本入口负责人在这两类任务中读取 [风格设计与主题生成](references/theme-generator.md)，沿用文章、偏好、参考图、作品目录与授权，执行对应分支。单篇分支返回本入口第 4 步装配正文，交付文件仍在作品目录；长期分支提供专业设计、组件及预览，由 `../laohu-evolution/SKILL.md` 协调长期文件写回、索引和验证，返回可调用主题及检查结论。交接保留用户选定风格、原文语义与代码保真要求，不能把专业设计重新推回用户，也不因缺少真实使用反馈阻止已授权试用。

## 添加新主题的规范

新主题以 `references/theme-{英文标识}.md` 命名，内容必须包含：

1. **设计变量速查表**（主色/浅底/深字/标题色/正文色/分割线色等）

2. **各组件完整 HTML**（内联样式 + `<span leaf="">` 包裹，遵守上面"正文片段静态规则"）

3. **完整文章模板骨架**（组件装配顺序；若有目录/导航组件，明确其相对封面/引言的位置）

4. **文章类型 → 组件组合配方表**（每种文章类型的核心组件组合 + 点缀组件，配方是排版气质稳定的关键）

5. **Markdown → 组件映射规则表**

添加后在 `references/theme-index.md` 登记一行（主题名 / 主色 / 适用场景 / 组件库文件 / 正文下划线 CSS），并跑 `python3 scripts/component_lint.py .` 确认组件库无反模式（0 ERROR）。

> 触发与主题选择的回归用例见 `references/eval-cases.md`（维护时用于回归核对，不影响单次生成）。