gzh-design-skill · 公众号排版技能CAUTION

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: gzh-design
description: 微信公众号文章排版引擎,将 Markdown 转换为可直接粘贴到公众号编辑器的 HTML。主题风格从 references/theme-index.md 注册的自定义主题库中选取,自动章节编号、关键词下划线标记、引言卡片、目录导航、代码块、图片/GIF、作者签名。支持 Markdown / Word(.docx) / PDF / 纯文本输入(非 Markdown 先自动归一化),也支持"一键自动排版"(自动推断结构+选主题),还支持根据用户描述/参考图生成自定义主题组件库并保存本地复用。触发场景:(1) 用户提到"公众号排版""公众号文章""微信排版""gzh",(2) 用户想把文章(md/docx/pdf/纯文本)转成公众号 HTML,(3) 用户说"自动排版""一键排版"公众号内容,(4) 用户想为公众号排版"生成新主题/自定义风格/按这张图做一套组件库"。不用于生成普通网页/落地页/PPT(用前端或 PPT 类 skill)。
---

# 公众号文章排版 Skill

把一篇 Markdown 文章转换为可直接复制粘贴进微信公众号编辑器、且粘贴后样式不丢失的 HTML。

核心资产是 `references/` 下的**主题组件库**(每套一个主题:设计变量 + 各组件完整 HTML + 模板骨架 + 映射规则)外加 1 套**通用增量库**(代码块 / 图片·GIF / 小标签标题,所有主题共用)。主题清单以 `references/theme-index.md` 为单一来源。本 SKILL.md 只负责流程与决策,**具体 HTML 代码一律从组件库取,不要凭记忆手写**。

## 工作流

### 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)(主题信息的单一来源)。**据文章题材主动推荐最契合的主题**,再让用户一步确认——推荐但不擅自定死:

- **用户已在请求里指定主题** → 直接用,不问。
- **题材有明确契合** → 单问确认:「建议用 XX(理由),确认还是换一套?」选项给推荐项 + 1~2 个备选 + "看全部"。题材→主题契合参考 theme-index"适用场景"列:
  - 教程 / 测评 / 清单 / 工具盘点 / 知识整理 / 方法论拆解(信息密度高)→ 摸鱼绿
  - 深度分析 / 观点 / 力量感话题 → 红白色系
  - 设计 / 科技评论 / 专业观点 / 高端品牌 → 石墨极简风
  - 禅意 / 极简生活 / 深度随笔 → 留白禅意风
  - 工具对比 / 创意评测(票据视觉隐喻)→ 摸鱼票据风
  - 内刊手记 / 深度评测 / 案例复盘 → 橄榄手记
- **无明显倾向** → 默认首选 theme-index 第一行(摸鱼绿)作为推荐项放第一位,用 AskUserQuestion 让用户在几套里选(主题多于 4 套时先按气质分组问,再问该组下主题)。
- **全自动模式**(用户明说「直接排 / 一键 / 不用问」)→ 不提问,自动选题材最契合主题或默认第一行,交付时说明选择理由。
- **用户对现有主题都不满意 / 想要新风格** → 走「自定义主题生成」流程(见下节),生成并登记后再回到本步选用。
- **theme-index 为空** → 停止排版,告知用户需要先添加主题风格(可走「自定义主题生成」)。

用户定下主题后,才进入该主题内部的组件匹配(第 3、4 步:判定文章类型 → 按该主题的配方表选组件组合)。

### 2. 读组件库(两份)

(1) 据 theme-index 中该主题的"组件库文件"列,Read 该主题专属组件库 `references/theme-{标识}.md`(含引言卡、章节标题、正文标记、签名等主题专属组件)。
(2) **同时 Read 通用增量库** `references/common-components.md`——代码块、图片/GIF、小标签标题这三类所有主题共用,套用当前主题主色即可。

后续生成完全依据这两份组件库,HTML 一律从中取、不要手写。

### 3. 解析 Markdown 结构

| 元素 | 识别规则 |
|------|---------|
| 文章标题 | `# 标题` 或 frontmatter `title` |
| 开头引言 | 文章最开头的 `> 引用` 块 |
| 章节标题 | `## 标题` |
| 子章节 | `### 标题` |
| 加粗 / 高亮 / 下划线 | `**文字**` / `==文字==` / `<u>文字</u>` 或 `++文字++` |
| 引用段落 | 非开头的 `> 文字` |
| 图片 / GIF | `![说明](URL)`、`![](xxx.gif)`(GIF 与图片同样处理) |
| 代码 / 命令 / Prompt | ` ``` 围栏代码块 ``` `、行内 `` `code` `` |
| 分割线 / 列表 | `---`、`***` / `- 项` 或 `1. 项` |
| 表格 | `\|` 分隔的 Markdown 表格(常来自 docx 转换)→ 优先用主题库的表格/卡片组件(主题库映射规则为准) |

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

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

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

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

- **骨架顺序以主题库为准**,不同主题骨架可能不同,不要套用其它主题的骨架。
- **行内标记按语义到所选组件库里找对应组件**(组件编号各库不统一,一律以语义为准、不要套固定编号):`**加粗**`→主色加粗;`==高亮==`→纯色浅底高亮;`<u>文字</u>` 或 `++文字++`→下划线;`~~文字~~`→荧光笔(纯色浅底);`>引用`→引用高亮块。
- 来自**通用增量库**的组件:` ``` 代码块 ``` `→ 1a 深色 / 1b 浅色代码块,行内 `` `code` ``→ 1c;`![说明](url)`→ 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 的实际路径>
```

它确定性地检查平台禁用项和 `<span leaf>` 包裹。报 ERROR 就回到第 4 步修;**半角标点 WARNING 同样要修复到 0 再交付**(这是实际使用中最高频的返工点)。

**渐变背景 WARNING 要逐项处理**:文字高亮、引用/数据/引导卡背景默认改为主题内纯色或 rgba 纯色;用户明确要求保留时,交付注明可能触发 `darkmode-no-gradient` 弹窗。纯装饰渐变也会提示,尚未确认其不会触发弹窗,保留时同样说明风险。

### 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+A/Ctrl+C),再到公众号编辑器 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. **目录提取**:从所有 `##` 取前 3 个作为导读/目录要点(主题库有目录组件时)。
6. **开头引言卡署名**:按文章的**作者或主题**而定——文章有署名就写"—— 作者名",没有明确作者就用与主题相关的简短落款或直接省略。**不要固定写"甲木"**(尾部签名区同样用 `{{作者名}}` 占位,见第 7 条)。
7. **尾部作者签名区(作者自填,仅末尾一处)**:**默认不写死任何人名**,用占位署名让用户替换成自己的。
   - 第一句(作者介绍):`我是 {{作者名}},{{一句话简介,如:热衷于分享 AI 观察与干货}}`——用户在请求/偏好里给了署名或简介就直接填入;没给就**保留 `{{作者名}}` / `{{简介}}` 占位**,并在交付时提示用户替换成自己的署名。
   - 第二句(互动引导,通用可保留原样):`如果你觉得今天这篇有收获,欢迎**点赞、在看、转发**三连,我们下篇见`
   - **原文末尾已有作者签名段**(如"我是 XXX...")→ 直接沿用原文的署名,不替换成占位。
8. **列表转换**:按主题库映射规则处理;无专属列表组件时转为带缩进的正文段落。
9. **中文全角标点**:正文标点一律用全角(,。!?:;""''()—— ...),不要用半角 `, . ! ? :` 和英文直引号 `" '`。**生成 HTML 时就直接写弯引号""'',不要先写直引号再事后替换**——原文里的直引号在转写时当场转换。**例外**:代码块、行内代码、英文专名/URL/代码标识符内部保持原样。

## 视觉层级(3 层递进,所有主题通用)

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

## 平台红线(核心,完整检查交给校验脚本)

- **禁止**:`<style>`/`<script>`/`<div>`、`class`/`id` 属性、`posit

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

<span style="background:#EA580C;color:#FFFFFF;padding:2px 8px;border-radius:4px;"><span leaf="">不是技术</span></span>

<span style="background:#EA580C;color:#FFFFFF;padding:2px 8px;border-radius:4px;"><span leaf="">驾驭</span></span>

<p style="display:inline-block;background:#EA580C;color:#FFFFFF;font-size:12px;font-weight:800;padding:2px 10px;border-radius:4px;margin:0 0 8px;"><span leaf="">01</span></p>

<p style="display:inline-block;background:#EA580C;color:#FFFFFF;font-size:12px;font-weight:800;padding:2px 10px;border-radius:4px;margin:0 0 8px;"><span leaf="">02</span></p>

<p style="display:inline-block;background:#EA580C;color:#FFFFFF;font-size:12px;font-weight:800;padding:2px 10px;border-radius:4px;margin:0 0 8px;"><span leaf="">03</span></p>

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: gzh-design-skill · 公众号排版技能](https://modelsatlas.com/skills/isjiamu/gzh-design/badge.svg)](https://modelsatlas.com/skills/isjiamu/gzh-design/)

Not your listing, or something out of date? Claim or update your listing.