信息充足，现在输出完整笔记。

---

用 AI Agent 把 Markdown 一键排成公众号 HTML：gzh-design-skill 深度解析

项目地址：github.com/isjiamu/gzh-design-skill
作者：甲木 × 摸鱼小李（AGPL-3.0 开源）

---

核心观点

这个项目解决的是一个听起来"小"、实际上很扎手的工程问题：微信公众号编辑器对 HTML/CSS 有一套白名单式的强过滤机制，导致普通前端 HTML 粘进去必然塌格式。gzh-design-skill 的本质不是"好看的模板"，而是一套把微信平台限制从"靠人记"变成"靠脚本兜底"的确定性工程体系。

放进历史脉络看：这不是什么新赛道，"Markdown 转公众号"工具至少存在五年，Markdown Nice、墨滴、md2wechat 等早就在做。但前代方案普遍是浏览器端渲染 → 复制富文本的路子，依赖浏览器剪贴板行为，格式稳定性差；或者直接调公众号草稿 API（需要 OAuth 授权），链路重、门槛高。gzh-design-skill 走的是第三条路：生成"确定性合规"的 HTML 文件，用户自己粘贴，把对齐平台限制的工作量前置到脚本校验而非运行时修复。这是渐进优化而非范式突破，但工程严谨度确实高出一档。

---

关键机制：为什么"双关卡 + 全内联"才是真正的护城河

很多人看这个项目会把注意力放在"6 套主题好看"上，其实最关键的设计是两层确定性保障：

第一层：全内联样式 + <span> 包裹每个文字节点

微信编辑器会过滤掉 <style> 块、外链 CSS、class/id（id 直接删除，class 保留但无规则可挂）。唯一能活下来的样式路径是 style="..." 直接写在元素上。不仅如此，公众号还会过滤 position:fixed/absolute/sticky、float、display:grid、@media、@keyframes、CSS 变量、外部字体——几乎砍掉了所有现代布局手段。项目的做法是：所有样式全内联，正文每个文字节点用 <span> 包裹。这不是为了好看，是平台的活命要求。

第二层：双关卡脚本——"改 → 验 → 修"闭环

# 源头关：扫组件库是否有反模式（0 ERROR 才通过）
python3 scripts/component_lint.py .

# 产物关：扫最终 HTML 是否合规（0 ERROR / 半角 0 WARN）
python3 scripts/validate_gzh_html.py out.html

源头关拦的是：white-space:pre 导致大片空白、正文四周虚线框、平台禁用 CSS 属性。
产物关拦的是：禁用 HTML 标签、漏掉 <span> 包裹的裸文字节点、没转成全角的标点。

这个设计的精髓在于"确定性下沉脚本，不靠模型记得住规矩"。LLM 在长上下文任务中遗忘约束是已知弱点，把硬规则交给 Python 脚本而非让模型自律，是真正懂 AI Agent 局限性的工程选择。

---

主题系统：设计变量驱动而非"堆 CSS"

6 套主题（摸鱼绿、红白、石墨极简、留白禅意、摸鱼票据、橄榄手记）都不是简单的换色，每套都是设计变量 + 数十个精细组件 + 视觉层级表 + 文章类型配方表的完整体系。

配色结构有固定的角色分工：

角色	作用	取色思路
主色	章节编号、锚点强调	品牌色（如 #059669 emerald）
浅底/浅边框	卡片背景、引用块底	主色同色系极浅版
点睛高亮色	每段 1~2 处黄底高亮	与主色冷暖对比的第二色
中性灰阶	正文/标题/分割线	#111827 → #9CA3AF，承担 90% 文字
下划线标记色	关键词逐段标记	主色浅色版，温和不抢戏

克制三原则：主色全文 ≤5 处出现；大面积白底+灰阶；一段内高亮 ≤2 种。这三条约束实际上是在对抗 LLM 的"用色过度"倾向——不加约束的模型会把文章排成彩色大礼包。

---

智能排版：章节编号、关键词下划线、引言卡

这是这个项目超出"静态模板"的地方，属于 Agent 层面的内容理解能力：

• 章节自动编号：末章特殊处理（∞ / ///），不是简单的 1、2、3
• 关键词下划线：每段主动标 1~3 个关键词，由 Agent 判断重要性
• 从正文提炼引言卡与目录：需要理解文章结构而非机械套模板
• 作者签名去重合并：防止多次运行重复插入签名
• 中文全角标点：正文自动转换，代码块内原样保留（区分语境）

---

安装与使用

三种安装方式，推荐第一种：

# 方式一：一行安装（推荐）
npx skills add https://github.com/isjiamu/gzh-design-skill

# 方式二：手动 clone（适合 Claude Code）
git clone https://github.com/isjiamu/gzh-design-skill.git ~/.claude/skills/gzh-design

装好后直接对 Agent 说：

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

Agent 工作流依次完成：选主题确认 → 读组件库 → 解析 Markdown → 装配 HTML → 跑校验 → 输出带"复制"按钮的预览页。

目录结构的核心：

gzh-design/
├── SKILL.md                    # Agent 入口（工作流主文档）
├── references/
│   ├── theme-index.md          # 6 套主题索引（单一来源）
│   ├── theme-*.md              # 各主题组件库
│   ├── theme-generator.md      # 主题生成器
│   └── common-components.md    # 跨主题通用增量组件
├── scripts/
│   ├── validate_gzh_html.py    # 产物合规校验
│   └── component_lint.py       # 源头检查

---

交叉验证

我搜索了两个独立信息源：

信源一：axtonliu.ai《微信公众号 HTML/CSS 支持情况解析》（2025年3月）

这是一篇独立技术作者对公众号平台限制的实测文章，结论与 gzh-design-skill 的设计完全吻合：

• 确认 <style> 块、外链 CSS 被完全禁止，必须使用内联样式
• 确认 position（absolute/fixed/relative 全部失效）、float、@media、@keyframes、transform 均被过滤
• 确认 id 属性会被微信删除（gzh-design-skill 因此刻意回避了锚点跳转依赖）
• 补充了一个 gzh-design-skill README 没提到的细节：class 属性实际上会被保留，只是无 CSS 规则可挂，因此也没有实际作用——这说明 gzh-design-skill 禁用 class 的选择是正确的，不是过度保守

信源二：腾讯云开发者社区《公众号排版太痛苦？AI Agent 来救你》（2026年6月）

这是另一位开发者独立实现了类似思路的文章（不同代码库），核心架构与 gzh-design-skill 高度重叠：感知（Markdown 解析）→ 决策（主题选择）→ 行动（HTML 生成 + 微信适配）。但两者有明显差异：

• 该文的方案没有双关卡校验脚本，属于"生成即交付"，合规性依赖人工检查
• 该文的主题系统是独立 CSS 文件 + 脚本注入，没有"组件库 + 配方表"的厚度
• 两者均认同"30 分钟手动排版 → 秒级自动生成"的效率提升判断，但 gzh-design-skill 的工程严谨度明显更高

综合判断：原文的核心技术主张（全内联样式、禁用 position/grid/class、脚本确定性校验）均得到独立信源的事实层面印证。关于"换模型不走样"的主张也是合理的——确定性逻辑下沉到脚本后，模型只做内容填充，理论上国产模型均可跑通。

---

边界与局限：不能无条件唱赞歌

几个需要诚实指出的限制：

1. 只排版、不写作：README 明确写了这是"先有 Markdown 再用它"，不能指望它帮你生产内容。这在宣传语境下容易被忽视。

2. 图片仍需手动上传：公众号要求图片来自微信素材库（mmbiz.qpic.cn 域名），生成的 HTML 里的外链图片在公众号内无法显示。这个痛点项目没有完全解决，只能在文章里用占位组件，上传步骤仍是手动的。

3. "粘贴不掉格式"的前提是用对粘贴方式：必须用预览页的"复制到公众号"按钮而非普通 Ctrl+C，否则剪贴板行为取决于浏览器，仍可能出问题。

4. 主题生成器依赖模型能力：用一句话或参考图生成新主题，背后是让 LLM 输出 45~75 个 HTML 组件块，质量高度依赖模型的上下文理解能力。能力弱的模型生成的主题可能一致性差，仍需人工审核。

5. AGPL-3.0 协议的商业使用风险：如果有公司想把它集成进 SaaS 产品，AGPL 要求即使只部署成服务也必须开源修改版代码——这是很多商业场景的硬门槛，需提前评估。

---

个人启发

对内容运营者：如果你每周写 2 篇以上公众号，排版时间是实打实的沉没成本。这个工具的价值不在于"生成漂亮排版"（市面上有很多），而在于可重复、跨模型、不依赖某个网页工具的稳定性——你的主题文件就在本地 Git 仓库里，不会因为第三方工具关停而丢失。

对 AI Agent 开发者：gzh-design-skill 是一个很好的"确定性约束 + LLM 内容生成"组合的范本。核心思路是：把平台的死规则写成校验脚本（不可绕过的硬约束），让 LLM 只做"软判断"（内容理解、关键词提取、风格匹配）。这个分工思路可以直接迁移到其他平台适配场景。

对工具开发者/贡献者：项目当前最大的工程缺口是图片自动上传——如果能接入微信公众号素材 API 做图片批量上传，整个链路的"一键"才算真的闭合。这是最有价值的贡献方向。

---

延伸思考

1. "确定性下沉脚本"能走多远？ 当平台（微信）悄悄更新白名单规则时，脚本校验会出现漏判——这套工程体系的维护成本取决于有没有人持续跟踪平台变更。开源社区能否形成"平台变更 → Issue → 脚本更新"的快速响应机制，决定了这个项目的长期可靠性。

2. Agent Skill 这个形态会成为主流吗？ 目前 Claude Code / Cursor 等工具的 Skill/Rule 体系还没有标准化，各家实现不兼容。gzh-design-skill 作为一个早期实践，验证了"把领域知识打包成 Skill 给 Agent 调用"的可行性——但如果 Agent 平台出现大的架构变更（如 Claude Code 换接口协议），这套 Skill 可能需要重写适配层。

3. "主题生成器"是这套系统最脆弱的环节还是最有价值的扩展点？ 让 LLM 一次性生成 45~75 个组件的完整主题库，成功率高度依赖 prompt 工程和模型能力。随着模型上下文窗口和指令遵循能力的提升，这个功能的稳定性会系统性提高——这意味着"用户自定义主题"的门槛会越来越低，6 套内置主题的价值反而会相对下降，项目的核心竞争力将更多落在校验脚本的准确性而非主题数量上。

---

📚 参考来源

1. GitHub - isjiamu/gzh-design-skill: 把 Markdown 一键排成可直接粘进公众号编辑器的精致 HTML —— 6 套精选主题 + 主题生成器 + 双关卡校验。An AI-agent skill that turns Markdown into paste-ready WeChat article HTML. · GitHub