公众号排版 · WeChat Article Typesetting

把一份 Markdown 草稿排成能直接粘进公众号编辑器、样式不掉版的精致 HTML。6 套主题任选，也能按你的品牌色现场捏一套自己的主题。

• 主线技能：isjiamu/gzh-design-skill（AGPL-3.0）
• 课程主页：https://clawvard.school/courses/wechat-typesetting
• 成本：免费 · 零 API key · 零 credits · 零商业账号（生成靠你已经登录的 coding agent）

0. 前置条件

• 任一已登录的 coding agent CLI：Claude Code / Cursor Agent / OpenAI Codex CLI / Google Gemini CLI / Aider。
• 本地 Python ≥ 3.9（跑校验脚本，几乎所有系统自带；python3 --version）+ git（下面路径 A 一步装完需要它）。
• 一份自己的 Markdown 草稿；也可以是 .docx / .pdf / 纯文本，skill 会先归一化再排版。
• 不需要任何第三方 API key、不需要注册商业账号、不需要下载模型权重、不需要 clone 私有仓库。

1. 安装

本 skill 除了 SKILL.md 外，运行时还要读 references/theme-*.md 组件库、跑 scripts/component_lint.py 与 scripts/validate_gzh_html.py 校验、以及用 assets/sample-article.md 做主题挑选参考。跑通 popularTask 1 / 2 需要完整的目录树，不只是 SKILL.md。

路径 A · git clone（推荐 · 完整安装，两条 popularTask 都能直接跑）

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

Cursor Agent / OpenAI Codex CLI 等其他 coding agent 若走 ~/.agents/skills/ 目录，把上面的目标路径替换成对应目录即可。

路径 B · npx skills add（辅助 · 只装 SKILL.md 前置提示，需再补一步）

上游 skills add 会把 skill 落在当前工作目录下的 ./.agents/skills/gzh-design（跨 agent 的通用目录），Claude Code 用户也可能把它放在 ~/.claude/skills/gzh-design。因此下面的 find 三条路径都覆盖：

# 1) 把 SKILL.md 注册进 coding agent 的 skills 索引，让触发词生效
npx skills add https://github.com/isjiamu/gzh-design-skill

# 2) 定位 skills-CLI 实际写入的 gzh-design 目录（含 $PWD/.agents/skills）
DEST="$(find "$PWD/.agents/skills" ~/.claude/skills ~/.agents/skills -maxdepth 2 -type d -name gzh-design 2>/dev/null | head -1)"
if [ -z "$DEST" ]; then
  echo "ERROR: 找不到 skills add 的安装目录。请改走上面路径 A（git clone）。" >&2
  exit 1
fi

# 3) 上游 skills manifest 目前只发布 SKILL.md 本体；popularTask 1 / 2 依赖的
#    references/ + scripts/ + assets/ 需要补一次 git clone 才能真的跑起来
git clone --depth=1 https://github.com/isjiamu/gzh-design-skill.git /tmp/gzh-src
cp -R /tmp/gzh-src/references /tmp/gzh-src/scripts /tmp/gzh-src/assets "$DEST/"
rm -rf /tmp/gzh-src
echo "gzh-design ready at: $DEST"

上游 skills-CLI 的 npx skills add 目前只搬 SKILL.md（作为 agent 前置触发文件），不带 references/ / scripts/ / assets/。走路径 A 的 git clone 是本课唯一一步就完成的完整安装；路径 B 是给已经用 skills CLI 管 skill 索引的用户的兼容入口，但仍要跑上面第 2、3 步才能跑通 popularTasks。

装好后重启 coding agent（claude / cursor / codex 等），触发词进来即可加载。

触发词："公众号排版" · "公众号文章" · "微信排版" · "gzh"（或英文 "typeset for WeChat"）

2. 三步跑通：Markdown → 主题 → 合规 HTML

准备一份自己的稿子，命名 ./drafts/post.md（800–2000 字最佳；.docx / .pdf 也行）。

在已经登录的 coding agent 里贴下面这段 prompt（技能装好就会触发）：

启动 gzh-design skill。我在 ./drafts/post.md 有一份 Markdown 长文，请按 SKILL.md 六步工作流排成可直接粘进公众号编辑器的 HTML：

1. 按题材推荐一套最契合的主题（现有 6 套：摸鱼绿 / 红白 / 石墨极简 / 留白禅意 / 摸鱼票据 / 橄榄手记），一句话说清理由，让我一步确认。
2. 读 references/theme-<slug>.md（主题专属组件库）+ references/common-components.md（通用增量库）。
3. 解析 Markdown：章节、加粗、==高亮==、<u>下划线</u>、> 引用、图片、代码块、列表。
4. 装配 HTML：自动章节编号（末章 ∞ 或 ///）、每段主动标 1–3 个关键词下划线、从正文提炼引言卡与目录、作者签名、全角标点规范化（代码块内不动）。
5. 双关卡校验：
   - python3 scripts/component_lint.py .  → 必须 0 ERROR
   - python3 scripts/validate_gzh_html.py ./out/post.html  → 必须 0 ERROR、半角 0 WARN
6. 输出：
   - ./out/post.html          干净正文，样式全部内联、每个文字节点 <span leaf=""> 包裹
   - ./out/post-preview.html  浏览器预览页 + 「复制到公众号」按钮

跑完给我三件事：所选主题 + 推荐理由、两个 lint 命令的报告摘要（ERROR 必须为 0）、两份 HTML 的路径。不需要任何 API key、不需要注册账号。

3. 六套预设主题速查

选定 → 组件全部从 references/theme-<slug>.md 拿，不要凭记忆手写。

4. 不喜欢现成的？用主题生成器现造一套

只有一件事需要你给：品牌主色（十六进制），加一句风格描述。剩下的（强调色、中性灰阶、下划线、圆角、阴影、字体气质）主题生成器都会自动补齐。

在 coding agent 里贴：

启动 gzh-design skill 的主题生成器（references/theme-generator.md 工作流）。我想给「XX 品牌」造一套自制主题，然后用它排今天的稿子。

- 主题描述：清新旅行随笔风，杂志感、留白多、不花哨
- 主色：#7C9EB2（雾蓝）
- 强调 / 高亮：让 AI 自动推导（要与主色冷暖对比、可读对比度达标）
- 中性灰阶 / 下划线色 / 背景 / 圆角 / 阴影：主题生成器自动补
- 字体：优先衬线正文 + 无衬线副标
- 适用场景：旅行随笔 / 生活方式 / 深度长文

按四步走：
1. 生成完整区块库到 assets/theme-previews/travel-mist-blue.html（一次性看整套风格）。
2. 转标准主题库到 references/theme-travel-mist-blue.md（补齐变量表 / 组件 / 骨架 / 配方表 / 映射表 + <span leaf>）。
3. 登记进 references/theme-index.md，跑 python3 scripts/component_lint.py . 到 0 ERROR。
4. 用这套新主题排 ./drafts/travel-post.md → ./out/travel-post.html，跑 python3 scripts/validate_gzh_html.py ./out/travel-post.html 到 0 ERROR。

最后给我：区块库预览路径、新主题 md 路径、新排 HTML 路径、两个 lint 报告摘要。不用第三方 API key。

主题生成器的规范来源是上游 references/theme-generator.md。生成完成后主题会被写进 references/theme-index.md，后续新稿子就能选它了。

5. 双关卡校验（不允许跳过）

排完必跑，两条都要 0 ERROR：

python3 scripts/component_lint.py .                    # 源头关：扫组件库反模式
python3 scripts/validate_gzh_html.py ./out/post.html   # 产物关：扫最终 HTML

两个脚本都是纯 Python、零依赖、不联网、不上传。

• component_lint.py 扫组件库里的 <div>、class=、id=、<style>、position:fixed/absolute 等 WeChat 编辑器过滤反模式。
• validate_gzh_html.py 扫最终 HTML 是否符合 WeChat 编辑器契约：所有文字节点包裹在 <span leaf=""> 内、样式全部内联、无外链 CSS / JS、无 class / id 属性、无 position: fixed/absolute/sticky、无 float。

任一条报 ERROR，先修再交付。

6. 粘进公众号编辑器版式为什么会保留

微信公众号编辑器识别 <span leaf=""> 作为叶节点标记。上游 skill 组件库里所有文字节点都已包在 <span leaf=""> 里、样式全部内联，粘贴时编辑器会把它们当作已排好版的段落原样保留：字号、颜色、下划线、章节编号、引言卡、代码块高亮全都在。反过来说，只要遇到 <div> / class= / <style> / 外链 CSS，编辑器会把它剥掉——所以两个 lint 才是硬门槛。

7. 与相邻课的边界

• 一份 markdown 想一次出「公众号杂志感长文 + 小红书封面卡 + 邮件周报」（多平台 generalist） → agentic-html-publish
• 深耕公众号：多主题任选 / 自制品牌主题 / WeChat 编辑器合规 lint / 长期沉淀主题库 → 本课 wechat-typesetting
• AI 味重的稿子想改成人味 → humanizer-text
• 公众号长文想配一组风格一致的正文小插图 → inline-illustration-cn
• 造一个自己的 skill 走作品集路线 → agent-skills-author

8. 上游 license 与商用边界

上游 skill 采用 AGPL-3.0。

• 你在本机 / 团队内部用它排自己公众号稿件 → 不受限。
• 你把这套 skill 包成对外提供的 SaaS 服务、订阅或托管排版工具 → 需要遵守 AGPL-3.0 的网络服务开源条款（对外提供服务时公开完整源码，包含改动）。

只是私人 / 团队用，直接装、直接排、直接粘，不用管商用条款。

9. 学习完成后

告诉用户：

我已经学会了 wechat-typesetting。给我你自己的 Markdown 草稿（或 .docx / .pdf），我按 SKILL.md 六步流程排成可直接粘公众号编辑器的合规 HTML，6 套主题任选，也能按你的品牌色现场捏一套自制主题。双 lint 0 ERROR 才收工。课程主页 https://clawvard.school/courses/wechat-typesetting。