isjiamu/gzh-design
微信公众号文章排版引擎，将 Markdown 转换为可直接粘贴到公众号编辑器的 HTML。主题风格从 references/theme-index.md 注册的自定义主题库中选取，自动章节编号、关键词下划线标记、引言卡片、目录导航、代码块、图片/GIF、作者签名。支持 Markdown / Word(.docx) / PDF / 纯文本输入（非 Markdown 先自动归一化），也支持"一键自动排版"（自动推断结构+选主题），还支持根据用户描述/参考图生成自定义主题组件库并保存本地复用。触发场景：(1) 用户提到"公众号排版""公众号文章""微信排版""gzh"，(2) 用户想把文章（md/docx/pdf/纯文本）转成公众号 HTML，(3) 用户说"自动排版""一键排版"公众号内容，(4) 用户想为公众号排版"生成新主题/自定义风格/按这张图做一套组件库"。不用于生成普通网页/落地页/PPT（用前端或 PPT 类 skill）。
npx skills add https://github.com/isjiamu/gzh-design-skill --skill gzh-design把一篇 Markdown 文章转换为可直接复制粘贴进微信公众号编辑器、且粘贴后样式不丢失的 HTML。
核心资产是 references/ 下的主题组件库（每套一个主题：设计变量 + 各组件完整 HTML + 模板骨架 + 映射规则）外加 1 套通用增量库（代码块 / 图片·GIF / 小标签标题，所有主题共用）。主题清单以 references/theme-index.md 为单一来源。本 SKILL.md 只负责流程与决策，具体 HTML 代码一律从组件库取，不要凭记忆手写。
用户可能给：Markdown 文本或 .md 路径（直接进第 1 步）、.docx、.pdf、.txt/无标记纯文本、网页富文本。非 Markdown 输入必须先读 references/format-normalize.md 按其规则转成 Markdown 草稿并做结构确认（docx 用 scripts/extract_docx.py，PDF 用 Read 分页读取+清噪，纯文本按标题启发式推断结构）。什么都没给时，向用户索要。
用户说「直接排 / 自动排 / 一键 / 不用问」时进全自动模式：跳过结构确认与选主题提问，自动推断结构、按题材自选主题、排版校验，交付时附决策说明（章节结构、自拟标题、选题理由）。
读 references/theme-index.md（主题信息的单一来源）。据文章题材主动推荐最契合的主题，再让用户一步确认——推荐但不擅自定死：
用户定下主题后，才进入该主题内部的组件匹配（第 3、4 步：判定文章类型 → 按该主题的配方表选组件组合）。
(1) 据 theme-index 中该主题的"组件库文件"列，Read 该主题专属组件库 references/theme-{标识}.md（含引言卡、章节标题、正文标记、签名等主题专属组件）。
(2) 同时 Read 通用增量库 references/common-components.md——代码块、图片/GIF、小标签标题这三类所有主题共用，套用当前主题主色即可。
后续生成完全依据这两份组件库，HTML 一律从中取、不要手写。
| 元素 | 识别规则 |
|------|---------|
| 文章标题 | # 标题 或 frontmatter title |
| 开头引言 | 文章最开头的 > 引用 块 |
| 章节标题 | ## 标题 |
| 子章节 | ### 标题 |
| 加粗 / 高亮 / 下划线 | 文字 / ==文字== / <u>文字</u> 或 ++文字++ |
| 引用段落 | 非开头的 > 文字 |
| 图片 / GIF | !说明、!（GIF 与图片同样处理） |
| 代码 / 命令 / Prompt | 围栏代码块 、行内 code |
| 分割线 / 列表 | ---、*** / - 项 或 1. 项 |
| 表格 | \| 分隔的 Markdown 表格（常来自 docx 转换）→ 优先用主题库的表格/卡片组件（主题库映射规则为准） |
解析完结构后，判定文章类型（取主导类型，可复合）：教程/操作指南、盘点/工具清单、观点/深度分析、访谈/人物特稿、数据复盘/报告、生活/情感随笔、案例实战。判定依据：步骤和命令多→教程；并列条目多→盘点；引语和人物叙事多→访谈；数字和对比多→数据；论证推演多→观点。
先查所选主题库的「文章类型 → 组件组合配方」表，按文章类型确定本篇的核心组件组合与点缀组件——不要拿到组件库就逐段随机选组件，配方保证同类文章的排版气质稳定。配方之外的元素再按主题库映射规则表补充。
然后依主题库的"完整文章模板骨架"章节装配，把每个 Markdown 元素替换为对应组件：
加粗→主色加粗；==高亮==→渐变背景高亮；<u>文字</u> 或 ++文字++→下划线；~~文字~~→荧光笔（底部半高亮）；>引用→引用高亮块。 → 1a 深色 / 1b 浅色代码块，行内 code !说明→ 2a 图片（有说明才加说明组件）、.gif→ 2b GIF；需要突出的小标题/强调→ 3a 左竖条小标题或 3b 药丸标签，金句→ 3d、提示旁注→ 3e。优先级：先查主题库映射规则表——该主题有等价语义组件（如自己的金句/提示块）就用主题库版本保持气质一致；主题库没有对应组件时才用通用库 3x 并按其换色规则换成主题色。dashed border）套一个标题，那样笨重抢戏。把生成的 HTML 写入目标文件后，必须运行校验脚本，ERROR 清零才算完成：
# 用脚本所在 skill 的绝对路径调用，HTML 参数也用其实际路径（两者目录通常不同）
<SKILL_ROOT>/scripts/validate_gzh_html.py <生成的.html 的实际路径>
它确定性地检查平台禁用项和 <span leaf> 包裹。报 ERROR 就回到第 4 步修；半角标点 WARNING 同样要修复到 0 再交付（这是实际使用中最高频的返工点）。
产物格式：纯 <section>…</section> 正文片段，从全局容器开始，不要包 <!DOCTYPE>/<html>/<head>/<body>——公众号编辑器只接受正文片段，多余的文档外壳会被丢弃或干扰粘贴。
{原文件名}_排版_{主题中文名}({英文标识}).html（英文标识 = theme-index 组件库文件名去掉 theme- 前缀与 .md 后缀）。这份用于校验和手动粘贴兜底。 <SKILL_ROOT>/scripts/wrap_preview.py <上面的干净正文.html>
产出 {...}_预览.html——浏览器打开后右上角有「复制到公众号」按钮，点一下即把渲染后的富文本复制到剪贴板（等价 Ctrl+A/Ctrl+C），再到公众号编辑器 Ctrl/⌘+V 粘贴。按钮和脚本只在预览外壳里、不在被复制的 section 内，所以粘到公众号的仍是干净合规正文。
{...}_预览.html → 点右上角「复制」→ 公众号编辑器粘贴；并给出干净正文文件路径作为兜底。附校验脚本结论（已通过 / 剩余 warning）。## 出现顺序分配 01/02/03…；末章若为结语/总结类，用主题库指定的结语编号变体（如 ∞），主题库未指定时沿用数字编号。## 取前 3 个作为导读/目录要点（主题库有目录组件时）。{{作者名}} 占位，见第 7 条）。我是 {{作者名}}，{{一句话简介，如：热衷于分享 AI 观察与干货}}——用户在请求/偏好里给了署名或简介就直接填入；没给就保留 {{作者名}} / {{简介}} 占位，并在交付时提示用户替换成自己的署名。如果你觉得今天这篇有收获，欢迎点赞、在看、转发三连，我们下篇见, . ! ? : 和英文直引号 " '。生成 HTML 时就直接写弯引号""''，不要先写直引号再事后替换——原文里的直引号在转写时当场转换。例外：代码块、行内代码、英文专名/URL/代码标识符内部保持原样。| 层级 | 作用 | 频率 | 手段 |
|------|------|------|------|
| 锚点层 | 最强锚点：产品名/步骤/CTA/核心金句 | 全文 ≤ 5 处 | 主色加粗、深色底白字引用 |
| 标记层 | 正文关键词，每段 1–3 处 | 高频 | 下划线标记 |
| 容器层 | 引用块、概念标签、长句强调 | 按需 | 浅底引用、荧光笔、徽章 |
<style>/<script>/<div>、class/id 属性、position:fixed/absolute/sticky、float、@media/@keyframes、display:grid、CSS 变量、外部字体/CSS。style；所有文字节点用 <span leaf="">文字</span> 包裹（否则粘贴后样式丢失）。display:flex（有限）、linear-gradient、border-radius、box-shadow、<section>/<p>/<span>/<strong>/<img>/<h3>。<span leaf> 包裹是最常见致命错——粘贴到公众号后样式整片丢失。靠第 5 步校验脚本兜底，别跳过。## 顺序，不要跳号；结语编号变体只用于末章，中间章节不能用。!说明 里真有说明文字才生成说明组件；! 空 alt 不要编造说明。<img> 一律 max-width:100%;height:auto;display:block;margin:0 auto——按图片自身尺寸显示、居中，大图缩到容器宽、小图保持原尺寸。不用 width:100%（会把小图也拉伸变糊）；只有表格 / 封面卡 / 流程图这类布局元素才用 width:100%。<img src="...名片或引导图URL">），没有真实图片 URL 时整行删掉，不要把占位符留在产物里。border:…dashed 四周虚线框包标题。例外：主题库明确定义的虚线组件（如摸鱼绿的 quote-box 引用框、oneliner-card 亮点卡）是该主题的风格特征，按主题库用法正常使用。" ' 都要改成全角；但代码块/行内代码内的半角符号保持原样，不要"全角化"代码。<p style=\"margin:0\">"写法，绝不用 white-space:pre——它会把 HTML 源码里 span 前的缩进和行间换行原样渲染成大左缩进 + 空行；缩进只用全角空格 ，行距靠 line-height:1.6。【插入…】、待录屏 / GIF / 视频 / 成果图等占位，用通用库 2c 居中素材占位板块（浅底柔虚线框 + 居中图标与说明），不要用左对齐的提示块。用户想要内置主题之外的新风格（说「生成一套新主题 / 自定义风格 / 按这张参考图做一套组件库」，或对现有主题都不满意）时，读 references/theme-generator.md 并严格按其流程执行：
assets/theme-previews/{theme-id}.html——全部区块在同一页面连续排布，用户浏览器打开整页一次浏览确认风格，不逐块展示确认。references/theme-{标识}.md（必须补 <span leaf=""> 包裹、去掉预览用 id、补齐五章节，规则详见 theme-generator.md 第三步），登记 theme-index.md，跑 component_lint.py 到 0 ERROR。生成阶段以提示词规则为准；转换进主题库阶段以本文件「平台红线」和「添加新主题的规范」为准（两者冲突时后者优先，因为主题库直接决定排版产物）。
新主题以 references/theme-{英文标识}.md 命名，内容必须包含：
<span leaf=""> 包裹，遵守上面"平台红线"）添加后在 references/theme-index.md 登记一行（主题名 / 主色 / 适用场景 / 组件库文件 / 正文下划线 CSS），并跑 python3 scripts/component_lint.py . 确认组件库无反模式（0 ERROR）。
> 触发与主题选择的回归用例见 references/eval-cases.md（维护时用于回归核对，不影响单次生成）。
Take isjiamu/gzh-design from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.