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)。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/isjiamu-gzh-design-skill)HTML
<a href="/listings/isjiamu-gzh-design-skill"><img src="/api/listings/isjiamu-gzh-design-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 172 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- 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 | ``、``(GIF 与图片同样处理) |
- | 代码 / 命令 / Prompt | ` ``` 围栏代码块 ``` `、行内 `` `code` `` |
- | 分割线 / 列表 | `---`、`***` / `- 项` 或 `1. 项` |
- | 表格 | `\|` 分隔的 Markdown 表格(常来自 docx 转换)→ 优先用主题库的表格/卡片组件(主题库映射规则为准) |
- **解析完结构后,判定文章类型**(取主导类型,可复合):教程/操作指南、盘点/工具清单、观点/深度分析、访谈/人物特稿、数据复盘/报告、生活/情感随笔、案例实战。判定依据:步骤和命令多→教程;并列条目多→盘点;引语和人物叙事多→访谈;数字和对比多→数据;论证推演多→观点。
- ### 4. 按配方选组件组合 → 装配 HTML
- **先查所选主题库的「文章类型 → 组件组合配方」表**,按文章类型确定本篇的核心组件组合与点缀组件——不要拿到组件库就逐段随机选组件,配方保证同类文章的排版气质稳定。配方之外的元素再按主题库映射规则表补充。
- 然后依主题库的**"完整文章模板骨架"章节**装配,把每个 Markdown 元素替换为对应组件:
- - **骨架顺序以主题库为准**,不同主题骨架可能不同,不要套用其它主题的骨架。
- - **行内标记按语义到所选组件库里找对应组件**(组件编号各库不统一,一律以语义为准、不要套固定编号):`**加粗**`→主色加粗;`==高亮==`→纯色浅底高亮;`<u>文字</u>` 或 `++文字++`→下划线;`~~文字~~`→荧光笔(纯色浅底);`>引用`→引用高亮块。
- - 来自**通用增量库**的组件:` ``` 代码块 ``` `→ 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 的实际路径>
- ```
- 它确定性地检查平台禁用项和 `<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` 属性、`position:fixed/absolute/sticky`、`float`、`@media`/`@keyframes`、`display:grid`、CSS 变量、外部字体/CSS。
- - **必须**:样式全部内联 `style`;所有文字节点用 `<span leaf="">文字</span>` 包裹(否则粘贴后样式丢失)。
- - **可用**:`display:flex`(有限)、`border-radius`、`box-shadow`、`<section>/<p>/<span>/<strong>/<img>/<h3>`。
- - **渐变背景兼容性**:渐变可渲染,但可能触发公众号 `darkmode-no-gradient` 内容结构检测;文字和卡片背景默认用纯色,不额外添加渐变。旧组件/自定义主题遇到此项也按第 5 步处理。
- ## Gotchas(真实排版踩过的坑)
- - **漏 `<span leaf>` 包裹**是最常见致命错——粘贴到公众号后样式整片丢失。靠第 5 步校验脚本兜底,别跳过。
- - **下划线:逐段落实、每段 1–3 个短语**。不要整段划线(失去焦点),也不要有的段标有的段漏;列表项里的关键描述同样要标。
- - **章节编号错乱**:严格按 `##` 顺序,不要跳号;结语编号变体只用于末章,中间章节不能用。
- - **签名区有且仅有末尾一个**:用固定文案,不在中间或多处出现;原文末尾若已有作者签名/"点赞在看转发三连"类段落,识别并**并入**这唯一的签名区/CTA 卡片,不要保留原文段又再生成一个。
- - **图片说明硬造**:只有 `` 里真有说明文字才生成说明组件;`` 空 alt 不要编造说明。
- - **图片自适应、不铺满**:`<img>` 一律 `max-width:100%;height:auto;display:block;margin:0 auto`——按图片自身尺寸显示、居中,大图缩到容器宽、小图保持原尺寸。**不用 `width:100%`**(会把小图也拉伸变糊);只有表格 / 封面卡 / 流程图这类布局元素才用 `width:100%`。
- - **跨主题混用组件**:一篇文章只用所选主题 + 通用库的组件,不从其它主题借组件。
- - **锚点层滥用**:最强强调全文 ≤ 5 处,到处加粗等于没有重点。
- - **原文内容遗漏**:每个段落、每张图都要转换,不得漏;不要自行增删原文实质内容。
- - **占位图残留**:签名区/CTA 组件里若带名片图占位(如 `<img src="...名片或引导图URL">`),没有真实图片 URL 时整行删掉,不要把占位符留在产物里。
- - **目录是精选不是全量**:前言导读/目录组件展示**精选的 3 个核心看点**,不是完整章节列表;章节多于 3 个时挑最重要的 3 个,不要硬塞或误导读者以为只有 3 章。
- - **不用虚线框**:突出标题/强调用小标签或左竖条(通用库 3a–3e),不要用 `border:…dashed` 四周虚线框包标题。**例外**:主题库明确定义的虚线组件(如摸鱼绿的 quote-box 引用框、oneliner-card 亮点卡)是该主题的风格特征,按主题库用法正常使用。
- - **标点别混半角**:正文出现半角逗号句号、英文直引号 `"` `'` 都要改成全角;但代码块/行内代码内的半角符号保持原样,不要"全角化"代码。
- - **代码/Prompt 必须用代码块**:文章里的代码、命令、提示词用通用库代码块组件(1a/1b),不要塞进普通段落或引用块,否则缩进和等宽会丢失。
- - **代码块要紧凑、忌大空白**:用通用库 1a/1b 的"每行一个 `<p style=\"margin:0\">`"写法,**绝不用 `white-space:pre`**——它会把 HTML 源码里 span 前的缩进和行间换行原样渲染成大左缩进 + 空行;缩进只用全角空格 ` `,行距靠 `line-height:1.6`。
- - **待补素材居中**:`【插入…】`、待录屏 / GIF / 视频 / 成果图等占位,用通用库 **2c 居中素材占位板块**(浅底柔虚线框 + 居中图标与说明),不要用左对齐的提示块。
- ## 自定义主题生成(第二条工作流)
- 用户想要内置主题之外的新风格(说「生成一套新主题 / 自定义风格 / 按这张参考图做一套组件库」,或对现有主题都不满意)时,**读 [references/theme-generator.md](references/theme-generator.md) 并严格按其流程执行**:
- 1. **收集偏好**:主题描述必填(或参考图),名称/ID/五色/字体/三类 TAG/圆角/阴影可空则自动补全;一次问全,不逐字段追问。
- 2. **生成区块库 HTML**:用 theme-generator.md 末尾的【生成提示词】原样执行,产出 45~75 个 Block 的完整区块库,保存到 `assets/theme-previews/{theme-id}.html`——全部区块在同一页面连续排布,用户浏览器打开**整页一次浏览**确认风格,不逐块展示确认。
- 3. **转换 + 登记**:用户确认风格后,转换为标准 `references/theme-{标识}.md`(**必须补 `<span leaf="">` 包裹、去掉预览用 id、补齐五章节**,规则详见 theme-generator.md 第三步),登记 theme-index.md,跑 `component_lint.py` 到 0 ERROR。
- 4. 交付后该主题即成为常驻可选主题,后续排版与内置主题完全同权。
- 生成阶段以提示词规则为准;转换进主题库阶段以本文件「平台红线」和「添加新主题的规范」为准(两者冲突时后者优先,因为主题库直接决定排版产物)。
- ## 添加新主题的规范
- 新主题以 `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`(维护时用于回归核对,不影响单次生成)。
README.md · README · 320 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- > 🏠 **主仓库托管于 [github.com/isjiamu/gzh-design-skill](https://github.com/isjiamu/gzh-design-skill) | 镜像同步:AtomGit**:[atomgit.com/zuiyn/gzh-design-skill](https://atomgit.com/zuiyn/gzh-design-skill)
- > 🤝 **本项目由 甲木 × [「摸鱼小李」](https://mp.weixin.qq.com/s/EMahAzgfAbRQrYukWE7_IQ) 联名共建** —— 排版组件、主题设计与质量标准凝聚了两人的公众号实践与共同打磨,特别感谢小李。
- <div align="center">
- # gzh-design-skill · 公众号排版技能
- **把 Markdown 一键排成可直接粘贴进微信公众号编辑器的精致 HTML**
- 6 套精选主题 + 主题生成器 · 代码块/图片/GIF · 自动章节编号与关键词标记 · 双关卡质量校验
- [](LICENSE)
- [](https://claude.ai/code)
- [](references/theme-index.md)
- [](CONTRIBUTING.md)
- [](#-快速开始)
- [English](README.en.md) | 中文
- </div>
- ---
- 一个给 AI Agent(Claude Code / Codex / Cursor 等)用的公众号排版 Skill。你写完 Markdown,它按你选的主题,生成**样式全内联、粘贴到公众号编辑器不掉格式**的 HTML——自动编章节号、标关键词下划线、配引言卡与目录、处理代码块和图片、合并作者签名,并用脚本确定性地兜住公众号平台的各种限制。
- ## ✨ 核心特性
- - **6 套精选主题**:摸鱼绿(默认)· 红白 · 石墨极简 · 留白禅意 · 摸鱼票据 · 橄榄手记 —— 每套都是自成体系的厚组件库(设计变量 + 数十个精细组件 + 视觉层级表 + 文章类型配方表)。
- - **主题生成器**:不满足现成主题?用一句话描述或一张参考图,生成一套全新组件库并保存本地复用(见 `references/theme-generator.md`)。
- - **内容全兼容**:代码块(深/浅色,等宽不折行)、图片、GIF(带动图角标)、行内代码、引用、列表、产品徽章。
- - **智能排版**:章节自动编号(末章 ∞ / ///)、每段主动标 1–3 个关键词下划线、从正文提炼引言卡与目录、作者签名去重合并。
- - **中文全角标点**:正文自动规范全角,代码块内原样保留。
- - **不掉格式**:所有样式内联、文字 `<span leaf="">` 包裹,规避 `<style>/<div>/class/grid/position` 等公众号会过滤的写法。
- - **双关卡质量校验**:`component_lint.py`(组件库源头)+ `validate_gzh_html.py`(最终产物),构成可复现的「改→验→修」闭环。
- - **一键复制**:生成带「复制」按钮的预览页,点一下把富文本复制到剪贴板,直接粘进公众号,免手动全选。
- ## 👀 效果预览
- 6 套主题各排同一篇长文(真实长图,含配图、引言卡、编号章节、金句、名词旁注等完整组件):
- <table>
- <tr>
- <td colspan="3" align="center"><img src="https://origin.picgo.net/2026/07/07/-40619312d679bc34.jpg" width="100%"><br><sub><b>摸鱼绿(默认)</b></sub></td>
- </tr>
- <tr>
- <td colspan="3" align="center"><img src="https://origin.picgo.net/2026/07/07/-084eb2b9d6f8d5e2.jpg" width="100%"><br><sub><b>红白色系</b></sub></td>
- </tr>
- <tr>
- <td colspan="3" align="center"><img src="https://origin.picgo.net/2026/07/07/-747b33f502544254.jpg" width="100%"><br><sub><b>橄榄手记</b></sub></td>
- </tr>
- <tr>
- <td width="33%" align="center"><img src="https://github.com/isjiamu/gzh-design-skill/releases/download/assets-v1/lf-graphite-minimal.png?v=1" width="250"><br><sub><b>石墨极简风</b></sub></td>
- <td width="33%" align="center"><img src="https://github.com/isjiamu/gzh-design-skill/releases/download/assets-v1/lf-zen-whitespace.png?v=1" width="250"><br><sub><b>留白禅意风</b></sub></td>
- <td width="33%" align="center"><img src="https://github.com/isjiamu/gzh-design-skill/releases/download/assets-v1/lf-moyu-ticket.png?v=1" width="250"><br><sub><b>摸鱼票据风</b></sub></td>
- </tr>
- </table>
- > 📚 **6 套完整长图 → [docs/all-themes.md](docs/all-themes.md)** | 克隆后浏览器打开 `docs/gallery/index.html` 可看可交互的完整 HTML。
- ## ✅ 适合 / ❌ 不适合
- **✅ 适合**:观点/深度分析 · 教程/操作指南 · 测评/工具盘点 · 知识整理/方法论 · 访谈/人物特稿 · 数据复盘/报告 · 生活/情感随笔 · 案例实战 —— 把 Markdown / Word / PDF / 纯文本长文,一键排成可直接粘进公众号编辑器的 HTML;也能按描述或参考图生成自定义主题。
- **❌ 不适合**:普通网页/落地页(用前端 skill)· PPT(用 PPT skill)· 纯图片海报/社交卡片(用社交卡片类 skill)· 非公众号平台的排版 · **代写文章**(本 skill 只排版、不写作——先有 Markdown 再用它)。
- ## 🗂 常见使用场景
- | 你的内容 | 推荐怎么排 |
- |---|---|
- | 观点 / 深度长文 | 红白 或 石墨极简;关键词下划线 + 金句引用 + 居中金句 |
- | 产品测评 / 工具盘点 | 摸鱼绿 或 摸鱼票据;step/tool-label + 卡片,按配方表走 |
- | 教程 / 操作指南 | 摸鱼绿;step-label + 代码块 + 编号列表 |
- | 数据复盘 / 年度报告 | 摸鱼绿 或 橄榄手记;数据卡 + 表格 |
- | 禅意 / 极简随笔 | 留白禅意;大留白 + 居中衬线引用 |
- | 内刊 / 深度评测 / 案例复盘 | 橄榄手记;编者按 + 分节 + 暗色摘要框 |
- | Word / PDF 稿转公众号 | 先自动格式归一化 → 再按题材选主题 |
- | 想要现成之外的风格 | 主题生成器:一句话或参考图现造一套 |
- ## 🎨 6 套精选主题
- 覆盖绝大多数公众号题材,每套都打磨到「拿来即用」:
- | 主题 | 适合 |
- |---|---|
- | **摸鱼绿**(默认) | 教程、测评、清单、工具盘点(卡片丰富、信息密度高) |
- | **红白色系** | 深度分析、观点、力量感话题(经典编辑风) |
- | **石墨极简风** | 设计、科技评论、专业观点、高端品牌 |
- | **留白禅意风** | 禅意、极简生活、深度随笔(呼吸感最强) |
- | **摸鱼票据风** | 工具对比、创意评测(票据视觉隐喻) |
- | **橄榄手记** | 内刊手记、深度评测、案例复盘(编辑部内刊质感) |
- > 主色、下划线色值等**完整速查表见文末 [附录](#-完整主题速查表)**;不够用就让 AI [生成新主题](#-faq)。
- ## 🚀 快速开始
- ### 方式一:一行安装(推荐)
- ```bash
- npx skills add https://github.com/isjiamu/gzh-design-skill
- ```
- ### 方式二:让 AI 自己装
- 对**任意 Agent**(Claude Code / Codex / Cursor 等)说一句:
- > 请帮我查找并自动安装 https://github.com/isjiamu/gzh-design-skill 这个 skill
- 它会自行 clone 到对应的 skills 目录并接入。
- ### 方式三:手动 clone
- ```bash
- git clone https://github.com/isjiamu/gzh-design-skill.git ~/.claude/skills/gzh-design
- ```
- 装好后,直接对 Agent 说:
- > 用摸鱼绿把这篇文章排成公众号 HTML:`article.md`
- ## 💬 交流群
- 扫码加入**官方企业微信交流群**(活码自动邀请入群,一起交流公众号排版 & Agent Skills 玩法):
- <img src="https://github.com/isjiamu/gzh-design-skill/releases/download/assets-v1/group-qr.png" width="220" alt="企业微信交流群二维码">
- > 扫码失效?加作者微信 **`zuiyn_soul`**(备注「gzh-design」)拉你进群。
- ## 📖 使用流程
- 1. **选主题** — 按题材自动推荐最契合的主题并请你一步确认(默认摸鱼绿);也可直接指定,或让 AI 生成新主题。
- 2. **读组件库** — 读所选主题库 + 通用增量库(代码块/图片/小标签)。
- 3. **解析 Markdown** — 识别标题、章节、加粗、高亮、引用、图片、代码块、列表。
- 4. **装配 HTML** — 用组件库里的真实组件拼装,落实编号、下划线、全角、签名。
- 5. **校验** — 跑 `validate_gzh_html.py`,ERROR 清零才交付。
- 6. **输出** — 生成干净正文 + 带「复制」按钮的预览页;浏览器打开预览页点右上角「复制到公众号」,再去编辑器粘贴即可(免手动全选)。
- ## 🧩 公众号平台限制(已内置兜底)
- 生成的 HTML 严格遵守:禁 `<style>/<script>/<div>`、`class/id`、`position:fixed/absolute/sticky`、`float`、`@media/@keyframes`、`display:grid`、CSS 变量、外部字体;样式全部内联;所有文字用 `<span leaf="">` 包裹。这些由校验脚本确定性检查,而非靠模型自觉。
- ## 🔁 可验证循环
- 改组件库或工作流后,用双关卡闭环防回归:
- ```bash
- python3 scripts/component_lint.py . # 源头关:扫组件库反模式
- python3 scripts/validate_gzh_html.py out.html # 产物关:扫最终 HTML 合规
- ```
- - **源头关** 查 `white-space:pre`(大空白)、正文四周虚线框、平台禁用项 —— 须 0 ERROR。
- - **产物关** 查禁用标签、`<span leaf>` 包裹、半角标点 —— 须 0 ERROR / 半角 0 WARN。
- - 逻辑:源头干净 → 产物必然干净。详见 `references/eval-cases.md`。
- ## 💡 为什么这么设计
- - **约束优于自由** — 预设主题色板 + 固定组件先保住输出下限,不让模型每次现场发挥、风格飘忽。
- - **样式粘贴不掉** — 全内联样式 + 每个文字节点 `<span leaf="">` 包裹,专门规避公众号会过滤的写法,粘进去不塌。
- - **质量靠脚本不靠自觉** — 双关卡(源头 `component_lint` + 产物 `validate_gzh_html`)确定性检查平台红线和标点,不靠模型「记得住」。
- - **换模型不走样** — 排版逻辑全沉淀在组件库和脚本里,不依赖某家模型,Claude / GPT / Gemini / 国产模型都能跑出一致效果。
- - **Agent 友好** — 输入输出全是纯文本 Markdown / HTML,任何 Agent 都能读、写、改、验,天然适配 Claude Code / Codex / Cursor。
- ## 📁 目录结构
- ```
- gzh-design/
- ├── SKILL.md # 排版工作流主文档(Agent 入口)
- ├── references/
- │ ├── theme-index.md # 6 套主题索引(主色/适用/下划线,单一来源)
- │ ├── theme-*.md # 6 套主题组件库(theme-moyu-green.md 等)
- │ ├── theme-generator.md # 主题生成器(按描述/参考图生成新主题)
- │ ├── common-components.md # 跨主题通用增量组件(代码块/图片/小标签)
- │ ├── format-normalize.md # 格式归一化(docx/pdf/纯文本 → Markdown)
- │ └── eval-cases.md # 触发用例 + 可验证循环
- ├── scripts/
- │ ├── validate_gzh_html.py # 产物合规校验
- │ └── component_lint.py # 组件库源头检查
- ├── assets/
- │ ├── sample-article.md # 演示输入
- │ └── theme-previews/ # 主题生成器产出的区块库预览
- └── docs/gallery/ # 主题浏览器预览
- ```
- ## 🎯 设计原则
- - **约束而非自由** — 用预设主题色板和固定组件保证输出下限,不让模型现场发挥。
- - **确定性下沉脚本** — 平台限制这类死规则交给校验脚本,模型只做内容判断。
- - **小标签,不用虚线框** — 强调用左竖条/药丸标签,笨重的四周虚线框只留给「待补素材」居中占位。
- - **每处经验都可复现** — 踩过的坑写进 gotchas 和校验脚本,用可验证循环防回归。
- - **配方优于自由** — 先按文章类型查主题库的「配方表」定组件组合,再装配,同类文章排版气质稳定。
- - **克制用色** — 主色只在锚点出现(全文 ≤5 处),大面积白底 + 灰阶,彩色只做点缀。
- - **灰阶承重** — 约 90% 的文字交给一套中性灰阶,色彩不承担正文阅读,避免花哨。
- ## 🧠 方法论:不止 6 套,自己造主题
- ### 主题生成:一句话 / 一张参考图,现造一套新主题
- 内置 6 套不够用时不必等更新——让 AI 现造一套。背后是 [`references/theme-generator.md`](references/theme-generator.md) 定义的第二条工作流:
- 1. **收集偏好**(一次问全,不逐条追问):主题描述必填(或给参考图),名称 / 主色 / 背景 / 正文色 / 强调色 / 装饰色 / 字体 / 圆角 / 阴影 / 适用场景可留空自动补全。
- 2. **生成区块库**:AI 产出 45~75 个区块的完整 HTML 组件库,存到 `assets/theme-previews/{id}.html`,浏览器整页一次浏览确认风格(不逐块问)。
- 3. **转标准主题库 + 登记**:确认后转成 `references/theme-{id}.md`(补 `<span leaf>`、补齐五章节:变量表 / 组件 / 骨架 / 配方表 / 映射表),登记进 theme-index,跑 `component_lint.py` 到 0 ERROR。
- 4. **即刻同权**:之后排版和内置主题完全一样,直接说「用 XX 主题排这篇」。
- **怎么触发**:
- > 按「黑白杂志、克莱因蓝点睛、衬线字体」的气质,给公众号排版生成一套新主题
- >
- > 按这张参考图(附图)做一套公众号排版组件库
- 仓库里 `assets/theme-previews/theme-mono-blue-editorial.html` 就是这样生成的一套「墨蓝刊读风」样例。
- ### 颜色搭配:一套可复制的配色结构,AI 自动生成协调色板
- 每套主题的视觉都建立在一张**设计变量色板**上——配色不是拍脑袋,而是固定的角色分工:
- | 角色 | 作用 | 取色思路 |
- |---|---|---|
- | **主色** | 章节编号、锚点强调、封面点睛 | 一个有辨识度的品牌色(`#059669` emerald / `#DC2626` 正红 …)|
- | **浅底 / 浅边框** | 卡片背景、引用块、标签底 | 主色同色系的极浅色(主色 + 大量白)|
- | **点睛高亮色** | 每段 1~2 处黄底 / 渐变高亮 | 与主色冷暖对比的第二色(绿配黄)|
- | **中性灰阶** | 正文 / 标题 / 辅助 / 分割线 | `#111827 → #9CA3AF` 一套灰阶,承担 90% 的文字 |
- | **下划线标记色** | 正文关键词逐段标记 | 主色的浅色版(`#A7F3D0` / `#FECACA`),温和不抢戏 |
- **克制三原则**:① 主色只在锚点出现(全文 ≤5 处);② 大面积白底 + 灰阶,彩色只点缀;③ 一段内高亮 ≤2 种。
- **让 AI 自动配**:只给一个主色或一句气质描述,主题生成器就据此推导整套协调色板——浅底、边框、高亮、灰阶、下划线色自动生成并保证可读对比度:
- > 以 `#7C9EB2` 雾蓝为主色,生成一套清新旅行随笔风的公众号主题
- ## 🗺 Roadmap
- - [x] 主题生成器:按描述/参考图生成自定义主题
- - [ ] 更多精选内置主题(欢迎 [提建议](../../issues/new?template=theme_request.md))
- - [ ] 主题静态截图预览(docs/screenshots/)
- - [ ] GitHub Pages 在线画廊
- - [ ] 一键把整篇 Markdown + 配图打包导出
- ## ❓ FAQ
- **Q:粘贴到公众号后样式会掉吗?**
- A:不会。所有样式内联、文字 `<span leaf="">` 包裹,这正是校验脚本强制的重点。
- **Q:能自己加主题吗?**
- A:两种方式。① **让 AI 生成**:说「按这个风格 / 这张图生成一套公众号主题」,它会走 `references/theme-generator.md` 的流程生成组件库、登记并复用。② **手写贡献**:照 `CONTRIBUTING.md` 的「新增一套主题风格」,跑通可验证循环即可提 PR。
- **Q:只能在 Claude Code 用吗?**
- A:不限。任何能读取 Skill 目录的 Agent(Codex / Cursor 等)都能用,工作流在 `SKILL.md`。
- **Q:对模型有要求吗?国产模型行不行?**
- A:不挑模型,**国内外模型都能跑出一致效果**。排版逻辑全部沉淀在组件库和校验脚本里,不依赖某家模型的特殊能力——Claude、GPT、Gemini,以及 DeepSeek、Kimi、通义千问、智谱 GLM 等国产模型都可以。模型只负责按规则填充内容,硬约束由校验脚本确定性兜底,所以换模型不会导致排版走样。
- **Q:能一次出多套主题对比吗?**
- A:能。说「用这几套主题各排一遍这篇」即可批量生成多套供你挑。
- **Q:怎么更新到最新版?**
- A:重新跑 `npx skills add https://github.com/isjiamu/gzh-design-skill`,或到安装目录 `git pull`。
- **Q:Agent 写出来不合规怎么办?**
- A:跑 `scripts/validate_gzh_html.py`,报 ERROR 就回到装配步骤修;两关全绿才交付,仍有问题欢迎开 Issue。
- ## 📋 完整主题速查表
- | 主色 | 主题 | 适用 |
- |---|---|---|
- |  `#059669` | 摸鱼绿(默认) | 教程、测评、清单、工具盘点 |
- |  `#DC2626` | 红白色系 | 深度分析、观点、力量感话题 |
- |  `#52525B` | 石墨极简风 | 设计、科技评论、专业观点、高端品牌 |
- |  `#4A5D52` | 留白禅意风 | 禅意、极简生活、深度随笔 |
- |  `#059669` | 摸鱼票据风 | 工具对比、创意评测(票据视觉隐喻) |
- |  `#1e1f23` | 橄榄手记 | 内刊手记、深度评测、案例复盘 |
- > 每套主题的英文标识、组件库文件、下划线 CSS 见 [`references/theme-index.md`](references/theme-index.md)。
- > 需要别的风格?让 AI 用 [主题生成器](#-faq) 现生成一套。
- ## ⭐ Star History
- 如果这个项目帮到了你,点个 Star 支持一下~
- <a href="https://www.star-history.com/?repos=isjiamu%2Fgzh-design-skill&type=date&legend=top-left">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=isjiamu/gzh-design-skill&type=date&theme=dark&legend=top-left&sealed_token=OSZCPLO_3NeTUKAtXcnNT6T3HuZwlFsH1HDGh6BcU0G2bdOm-5snTE01rzgYkwgNkF0pvraNI226pwK4jt9zYc4YuJ196yA1fcRRZKmfVQDMWqtE87dHqXn1E4v2q1mCWNFHzXAGJrCMEHx_0wwNmIVOg5nOaNCtRUYS2C_E1IlITdmy_yv7vpyVxqti" />
- <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=isjiamu/gzh-design-skill&type=date&legend=top-left&sealed_token=OSZCPLO_3NeTUKAtXcnNT6T3HuZwlFsH1HDGh6BcU0G2bdOm-5snTE01rzgYkwgNkF0pvraNI226pwK4jt9zYc4YuJ196yA1fcRRZKmfVQDMWqtE87dHqXn1E4v2q1mCWNFHzXAGJrCMEHx_0wwNmIVOg5nOaNCtRUYS2C_E1IlITdmy_yv7vpyVxqti" />
- <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=isjiamu/gzh-design-skill&type=date&legend=top-left&sealed_token=OSZCPLO_3NeTUKAtXcnNT6T3HuZwlFsH1HDGh6BcU0G2bdOm-5snTE01rzgYkwgNkF0pvraNI226pwK4jt9zYc4YuJ196yA1fcRRZKmfVQDMWqtE87dHqXn1E4v2q1mCWNFHzXAGJrCMEHx_0wwNmIVOg5nOaNCtRUYS2C_E1IlITdmy_yv7vpyVxqti" />
- </picture>
- </a>
- ## 🤝 贡献
- 欢迎新主题、修复与文档改进,请先读 [CONTRIBUTING.md](CONTRIBUTING.md)。
- ## 📄 License
- **AGPL-3.0 © 2026 甲木 × 摸鱼小李**
- 本项目采用 **GNU AGPL-3.0** 协议,要点:
- 1. **必须署名** — 保留版权与联名署名声明
- 2. **衍生品必须开源** — 任何修改版本、Fork、二次分发,必须以 AGPL-3.0(或兼容协议)公开发布,提供完整源代码
- 3. **网络服务也要开源** — 即使只是把修改版本部署成 SaaS / Web 服务给别人用而不分发代码,也要公开源代码(这是 AGPL 区别于 GPL 的核心)
- 4. **不允许闭源、专有化、仅付费分发**
- 完整条款见 [LICENSE](LICENSE)。
- > 🤝 **欢迎 AI Agent 厂商、模型厂商共创**:想把 gzh-design 集成进产品、或基于它做深度共建,我们很欢迎——共创协议请联系甲木。
- ## 🙏 致谢
- - 本项目由 **甲木 × 摸鱼小李** 联名共建:核心组件库与主题设计标准凝聚了两人的公众号排版实践。
- - 质量工程(可验证循环)由 skill-optimizer 审计驱动打磨。
- ---
- <div align="center">
- <img src="https://origin.picgo.net/2026/07/07/22e8d28de5f71eee085939b2f4c1f19548b19a67a79bdb68.png" width="600" alt="甲木 × 摸鱼小李 公众号名片">
- <sub>关注我们的公众号,获取更多 AI 干货与排版实践 👆</sub>
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.