laohu-htmlshow-gzh git:20261005.0a2888fB

Immutable. This exact content never changes and is served at /api/v1/blob/78efe2aa4934c06d.

---
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. 输入与格式归一化

作品路径遵守 `{SKILL_DIR}/../../../docs/runtime.md` 的“作品目录的共同接入”。只有满足该共同接入条件后才处理目录与保存；已有作品目录沿用，独立文章由本 `SKILL.md` 所在目录的 `../laohu-archive/SKILL.md` 核对名称和位置，再按授权保存转换稿、排版文件和预览。未触发时在聊天中交付排版内容，不因文章名称确定自动建目录。后文“当前工作目录”指该作品目录，不指终端目录。主题组件库和技能维护文件仍按原有职责存放。

用户可能给：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 的单篇分支调整或制作必要结构，仍遵守通用语义和正文静态规则。

**文案来源边界**：本入口默认处理已有文章，不代作者补写标题、封面钩子、引言金句、摘要、标签、评分、署名或 CTA。可见文案沿用原文或用户明确提供/指定的内容；主题组件提供视觉，不授权重写角度或提炼新句。缺少来源时删去对应文字槽和依赖它的组件，保留其余版式。用户明确要求创作其中某类文案后，才按授权范围创作；仅说“排版、直接排或一键排”不等于授权改写文案。

### 3. 解析 Markdown 结构

| 元素 | 识别规则 |
|------|---------|
| 文章标题 | `# 标题` 或 frontmatter `title` |
| 开头引言 | 文章最开头的 `> 引用` 块 |
| 章节标题 | `## 标题` |
| 子章节 | `### 标题` |
| 行内标记 | 语义按 `references/common-components.md` 的“标记语义与主题适配”，主题只选择对应视觉组件 |
| 引用段落 | 非开头的 `> 文字` |
| 图片 / GIF | `![说明](URL)`、`![](xxx.gif)`（GIF 与图片同样处理） |
| 代码 / 命令 / Prompt | ` ``` 围栏代码块 ``` `、行内 `` `code` `` |
| 分割线 / 列表 | `---`、`***` / `- 项` 或 `1. 项` |
| 表格 | `\|` 分隔的 Markdown 表格（常来自 docx 转换）→ 优先用主题库的表格/卡片组件（主题库映射规则为准） |
| 段内硬换行 | Markdown 行末两个空格后的换行是源文明确换行；HTML 中保留为 `<br>`，不合并成普通空格或新段落 |
| 制表符 | DOCX 转换得到的四个不换行空格是可见分隔；放在 leaf 文本中原样保留，不压成一个空格。它不代表精确保留 Word 自定义制表位 |
| 表格单元格换行 | `<br>` 留在对应单元格，不拆开表格行；单元格中的不换行空格按原样保留 |

**解析完结构后，判定文章类型**（取主导类型，可复合）：教程/操作指南、盘点/工具清单、观点/深度分析、访谈/人物特稿、数据复盘/报告、生活/情感随笔、案例实战。判定依据：步骤和命令多→教程；并列条目多→盘点；引语和人物叙事多→访谈；数字和对比多→数据；论证推演多→观点。若主题骨架列有封面、引言或金句卡，先查是否有原文内容可承载；骨架顺序不构成补写该卡片文案的许可。

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

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

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

- **骨架顺序以主题库为准**，不同主题骨架可能不同，不要套用其它主题的骨架。
- **文字类组件按文案来源边界装配**：以原文标题、引言、摘要或评分填充其对应组件；没有来源时省略文字槽或整个组件，不为凑齐骨架自拟新标题、营销角度、金句或评价。
- **行内标记**：按已加载通用库的“标记语义与主题适配”选择主题内的等义组件，缺项使用通用组件；主题编号不同，不套用其他主题编号。原文中的加粗、高亮、下划线、删除线按语义映射并保留文本；新增强调只在排版目标或确有阅读层级需要时，从原文选择必要焦点，不改变作者的语义主次、限定和情绪力度。主题组件库提供视觉样式，不构成逐段新增强调的授权；可以没有新增强调。
- 来自**通用增量库**的组件：` ``` 代码块 ``` `→ 1a 深色 / 1b 浅色代码块，行内 `` `code` ``→ 1c；`![说明](url)`→ 2a 图片（有说明才加说明组件）、`.gif`→ 2b GIF；需要突出的**小标题/强调**→ 3a 左竖条小标题或 3b 药丸标签，金句→ 3d、提示旁注→ 3e。**优先级：先查主题库映射规则表**——该主题有等价语义组件（如自己的金句/提示块）就用主题库版本保持气质一致；主题库没有对应组件时才用通用库 3x 并按其换色规则换成主题色。
- **图片交付**：保留图片内容、顺序、alt、图注和样式。可携带正文中的本地图片按 HTML 文件所在目录解析，以原文件字节和识别出的 MIME 内嵌为 data URI；远程 URL 与已有 data URI 不改，不下载或上传。图像文件缺失、不可读或 MIME 与扩展名不符时，停止图片便携处理并报告具体路径；不能删图后继续称已完整交付。缺少实际图片来源时保留待补素材说明，不伪造可用图源。
- **一篇文章只用所选主题的那一套组件**，不跨主题混用。
- **强调与小标题用"小标签/左竖条"，不要用虚线框**：要突出一个小标题或一段内容时，用左竖条小标题（3a）、药丸标签（3b）、左竖条金句/提示块（3d/3e）；**不要用四周虚线框（`dashed` border）套一个标题**，那样笨重抢戏。

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

先按第 6 步第 1 项运行便携处理，生成最终正文；然后把命令产出的 `{...}_便携.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. **先生成便携正文与预览文件**：初始装配的 `<section>` HTML 保存到当前工作目录，文件名 `{原文件名}_排版_{主题中文名}({英文标识}).html`。随后执行：
   ```bash
   <SKILL_ROOT>/scripts/wrap_preview.py <上面的干净正文.html> --portable
   ```
   `--portable` 另产 `{...}_便携.html` 干净正文和 `{...}_预览.html`，不改初始装配文件；没有本地图片时远程 URL 与已有 data URI 仍保持原样。只有用户明确要求更新原正文同名文件时才加 `--in-place`；可用第二个位置参数指定预览路径，或用 `--body-output` 指定便携正文路径。旧的单纯包装调用仍可使用，但不会替用户改写源正文。
2. **校验便携正文**：`--portable` 成功后，对它产出的干净正文运行 `scripts/validate_gzh_html.py`，而不是对原本仍引用本地图片路径的初始装配稿运行最终校验。若便携处理或校验失败，修复后重跑；不把仅内嵌在预览页里的图片当作已交付正文。
3. **再展示预览**：校验通过后再打开 `{...}_预览.html`。预览的按钮优先通过 `ClipboardItem` 同时写入正文 `text/html` 与 `text/plain`，只复制干净正文，不复制预览工具栏。浏览器不支持或拒绝富文本剪贴板时，在 `execCommand('copy')` 期间通过一次性 `copy` 事件尝试写入两种正文格式，并在 `finally` 移除监听；仍不可用时保留选区复制，失败则选中正文供手动复制。复制按钮只能报告剪贴板写入结果，必须提醒用户粘贴到公众号后检查图片和样式；不能据此宣称公众号已接收或显示通过。
4. **兜底与交付**：告知用户打开预览、点击复制、到公众号粘贴并检查；提供已校验的便携正文路径，不能把仍含机器本地图片路径的初始装配稿当作可移交兜底。附校验脚本结论（已通过 / 剩余 warning）。

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

1. **章节自动编号**：按 `##` 出现顺序分配 `01/02/03…`；末章若为结语/总结类，用主题库指定的结语编号变体（如 `∞`），主题库未指定时沿用数字编号。
2. **英文标签**：据中文章节标题生成英文标签（实测→TEST、教程→TUTORIAL、总结→SUMMARY、思考→THOUGHTS…），主题库有对应槽位时使用。
3. **正文强调与下划线**：先保留原文已有的语义标记并按主题视觉映射。确有阅读层级需要，或用户明确要求主题强调时，才从原文选择必要的核心判断、结论、关键数据或专有名词作新增强调；只标原文已有文字，不改写其范围、否定、比较关系和情绪力度。每段可标 0–3 处，允许整段不加；不按统一频率强行新增下划线。
4. **引言卡排版**：原文已有的引言标记照语义映射；只在用户明确要求或确有阅读层级需要时，才从引言原句中选择焦点作视觉强调。保留原句及其语义主次，不为配合组件改写金句；不需要额外强调时直接使用原文字样。
5. **目录提取**：主题有导读组件时，默认展示最能说明本文价值的至多三个看点。
   - **默认选择**：先根据文章主要问题选直接回答它的结论、关键做法或决定性材料；多个条目表达同一价值时保留更具体的一项，不机械取前三章。
   - **展示顺序与编号**：选定后按原文顺序展示；条目显示章节编号时取对应正文的原编号，交付前逐项核对标题与编号，不按精选位置重编或用全文替换误改编号。
   - **标题与内容边界**：沿用原标题或忠实概括，不增加正文没有的承诺。
   - **章节不足或不可用**：章节不足三个时不补凑；没有可用章节时省略。
   - **用户要求完整目录**：用户要求完整目录时列全部章节，按同款条目扩展组件，不套精选限制。
   - **组件槽位与示例**：组件示例中的三个槽位只示范外观，按实际条目增删。例如修复教程依次是“背景、术语、失败原因、修复方法、验收结果”，导读优先选择后三项。
6. **开头引言卡署名**：只保留原文已有或用户明确提供的作者署名；不按主题推测作者，不代拟落款。原文无署名且用户未要求时省略。
7. **尾部签名与互动引导**：原文已有的作者介绍、署名或互动引导按原意保留，排入适合组件；不得改成占位或替换成固定文案。原文没有、用户也未明确要求添加时，省略整个对应部分；用户明确要求新增 CTA 时，按其目标和上下文拟合文案，保留用户指定的动作与边界，不附加其他互动动作。缺少作者姓名或简介时不编造。签名和 CTA 是两个可分别保留/省略的内容，不相互推定；主题库中的署名、图标和互动组件只是可选视觉样式。
8. **列表转换**：按主题库映射规则处理；无专属列表组件时转为带缩进的正文段落。
9. **中文叙述使用全角标点**（，。！？：；“”‘’（）—— …），生成 HTML 时直接使用中文标点。完整英文句子保留英文标点与直引号，不转换成中文标点；英文专名、URL 和代码标识符内部的标点同样原样保留。中文句中的半角中文标点改为全角；代码块和行内代码原样保留。

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

| 层级 | 作用 | 频率 | 手段 |
|------|------|------|------|
| 锚点层 | 最强锚点：产品名、步骤、CTA、核心金句 | 新增设计强调默认 ≤5 处；用户明确要求时可调整 | 主色加粗、深色底白字引用 |
| 标记层 | 正文关键词 | 按需；可为 0 处，不按段配额新增 | 下划线标记 |
| 容器层 | 引用块、概念标签、长句强调 | 按需 | 浅底引用、荧光笔、徽章 |

主题库列出的数量和配色配额用于控制本次排版新增强调的默认视觉密度。原文已有的加粗、高亮、下划线、删除线按语义保留，不计入新增配额；用户明确指定不同的视觉密度时据此调整。

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

- **禁止**：完整文档外壳 `<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 步校验脚本兜底，别跳过。
- **强调新增需有内容依据**。保留原文标记；新增强调只突出原文已存在且符合排版目标的焦点，0–3 处/段均可，不要求每段都有。不要重写或扩展作者重点来适配组件；列表项也按同一判据处理。
- **章节编号错乱**：严格按 `##` 顺序，不要跳号；结语编号变体只用于末章，中间章节不能用。
- **签名与 CTA 以来源为准**：仅排版原文已有内容或用户明确要求新增的对应部分；无署名、简介或 CTA 时分别省略，不用占位符、主题名或固定“三连”补空。原文已有内容只调整其组件承载，不重复生成，也不改变其动作和语气。
- **图片说明硬造**：只有 `![说明](url)` 里真有说明文字才生成说明组件；`![](url)` 空 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`（维护时用于回归核对，不影响单次生成）。