isjiamu/gzh-design-skill · 上手攻略

  • 仓库：isjiamu/gzh-design-skill
  • 链接：https://github.com/isjiamu/gzh-design-skill
  • 分类：AI工具 · 公众号排版 · Claude Skill
  • 作者：Tom
  • 更新：2026-08-12

是什么

gzh-design-skill 是一个面向 AI Agent（Claude Code / Codex / Cursor 等）的微信公众号排版 Skill。你给它一段 Markdown，它按选定主题输出样式全内联、粘贴进公众号编辑器不丢格式的 HTML——自动章节编号、关键词下划线标记、引言卡片、目录导航、代码块处理、图片与 GIF 标注，并附双关卡脚本兜底质量校验。

核心作者是甲木，与公众号「摸鱼小李」联名共建，所有设计变量、组件库和排版质量标准均来自两人在真实公众号运营中的实践沉淀。

解决什么问题

写公众号最痛苦的环节不是内容，而是排版。把 Markdown 粘进公众号编辑器后：加粗消失、居中跑偏、代码块变形、图片错位、特殊符号乱码。现有解决方案要么依赖微信后台不支持的外部 CSS，要么需要手动复制一段段 HTML。

gzh-design-skill 把这个痛点自动化：AI 读完 Markdown → 选主题 → 输出合规 HTML → 一键复制粘贴，内容和样式同时到位，不用打开任何额外工具。

快速安装

方式一：通过 Agent 自动安装（推荐）

在 Claude Code / Codex / Cursor 等 Agent 中直接说：

请帮我查找并自动安装 https://github.com/isjiamu/gzh-design-skill 这个 skill

Agent 会自行 clone 到对应 skills 目录并接入。

方式二：手动 clone

git clone https://github.com/isjiamu/gzh-design-skill.git ~/.claude/skills/gzh-design

安装后对 Agent 说：

用摸鱼绿把这篇文章排成公众号 HTML：article.md

核心用法

工作流（5 步）

  1. 选主题 — Agent 读取 references/theme-index.md，按文章题材推荐最契合主题，用户一步确认（默认「摸鱼绿」）
  2. 读组件库 — 读取选定主题的 references/theme-{id}.md + 通用增量库 references/common-components.md（代码块、图片、GIF、小标签）
  3. 解析 Markdown — 识别标题、章节、加粗、高亮、引用、图片、代码块、列表，输出结构化数据
  4. 装配 HTML — 用组件库组件拼装，落实编号、下划线、全角标点、签名
  5. 校验交付 — 跑 validate_gzh_html.py，ERROR 清零后输出带「复制」按钮的预览页

主题一览

主题 主色 适用场景
摸鱼绿（默认） emerald #059669 教程、测评、清单、工具盘点
红白色系 正红 #DC2626 深度分析、观点、力量感话题
石墨极简风 石墨灰 #52525B 设计、科技评论、专业观点
留白禅意风 墨绿 #4A5D52 禅意、极简生活、深度随笔
摸鱼票据风 emerald #059669 测评、工具对比、创意评测
橄榄手记 墨黑 #1e1f23 内刊手记、深度评测、案例复盘

校验脚本

# 源头关：扫组件库反模式
python3 scripts/component_lint.py .

# 产物关：扫最终 HTML 合规
python3 scripts/validate_gzh_html.py out.html

两者均须 0 ERROR 才交付。⚠️ 产物关的半角标点 WARNING 同样要修到 0，这是实际最高频返工点。

全自动模式

用户说「直接排 / 一键排 / 不用问」时，Agent 跳过选主题提问，自动推断题材 → 选最契合主题 → 校验 → 交付，附决策说明（章节结构、选用主题、理由）。

自定义主题生成

现有 6 套不满意？让 AI 按描述或参考图生成全新主题：

按「黑白杂志、克莱因蓝点睛、衬线字体」的气质，给公众号排版生成一套新主题

生成流程：收集偏好 → 产出 45~75 个区块的 HTML 预览库 → 用户浏览器确认 → 转标准主题库 → 登记进 theme-index.md → 跑 lint → 与内置主题完全同权。

典型适用场景

  • 观点/深度分析 → 红白或石墨极简；关键词下划线 + 金句引用 + 居中金句
  • 产品测评/工具盘点 → 摸鱼绿或摸鱼票据；step/tool-label + 卡片
  • 教程/操作指南 → 摸鱼绿；step-label + 代码块 + 编号列表
  • 数据复盘/年度报告 → 摸鱼绿或橄榄手记；数据卡 + 表格
  • Word/PDF 稿转公众号 → 先自动格式归一化 → 再按题材选主题

⚠️ 不适合：普通网页/落地页、PPT、纯图片海报、非公众号平台的排版。本 skill 只排版，不代写文章——先有 Markdown 才用它。

坑与注意

  1. 粘贴格式必丢失的根因：公众号过滤 <style>/<script>/class/id/position:fixed/absolute/sticky/float/@media/display:grid/CSS 变量。gzh-design-skill 的校验脚本强制检查这些，0 ERROR 是安全线。
  2. <span leaf=""> 包裹是生命线：所有文字节点必须用 <span leaf=""> 包裹；漏了粘贴后整段样式丢失。靠 validate_gzh_html.py 检查，不要跳过。
  3. 半角标点是最常见 WARNING：代码块之外的正文标点必须全角化；代码块/行内代码内部保持原样。⚠️ 校验脚本报 WARNING 也要修到 0。
  4. 章节编号严格按 ## 顺序：不要跳号；结语编号变体（如 ∞）只用于末章，中间章节用数字编号。
  5. 每段关键词下划线 1–3 处：整段划线等于没有焦点，漏划则特色功能未体现。不要跨主题混用组件。
  6. 图片自适应不用 width:100%：一律 max-width:100%;height:auto;display:block;margin:0 auto；width:100% 会把小图拉伸变糊。只对表格/封面卡等布局元素用 width:100%。
  7. 签名区有且仅有末尾一个：不要在中间或多处出现；原文末尾已有签名段则并入、不重复生成。
  8. 不自动生成图片说明：只有 ![说明](url) 里真有 alt 文字才生成说明组件；空 alt 不要编造。

与同类对比

方案 适用场景 优点 缺点
gzh-design-skill（本工具） AI Agent 工作流内排公众号 全自动、双关卡校验、主题可生成、约束优于自由 需 AI Agent 环境、Markdown 先行
微信公众号后台 Markdown 插件 直接在公众号后台写 免切换 样式有限、无法批量、校验弱
第三方排版网站（135 编辑器等） 手动排版 可视化、模板多 需要手动复制、无法融入 AI 工作流
手动写 HTML + 内联样式 高阶用户 完全可控 工作量大、容易出错、无校验

核心差异：约束驱动 + 脚本兜底 + Agent 友好。排版逻辑全沉淀在组件库和脚本里，不依赖某家模型，Claude / GPT / Gemini / 国产模型均可使用，且换模型排版效果一致。

一句话推荐结论

如果你用 AI Agent 写技术文章/教程/观点文，且目标读者在微信公众号，gzh-design-skill 是目前最顺滑的「Markdown → 公众号」一条龙方案——主题精选、校验严格、输出稳定，省去 80% 的手动调格式时间。

原始仓库：https://github.com/isjiamu/gzh-design-skill