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

信息充足现在输出完整笔记。用 AI Agent 把 Markdown 一键排成公众号 HTMLgzh-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/idid 直接删除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 局限性的工程选择。主题系统设计变量驱动而非堆 CSS6 套主题摸鱼绿、红白、石墨极简、留白禅意、摸鱼票据、橄榄手记都不是简单的换色每套都是设计变量 数十个精细组件 视觉层级表 文章类型配方表的完整体系。配色结构有固定的角色分工角色作用取色思路主色章节编号、锚点强调品牌色如#059669emerald浅底/浅边框卡片背景、引用块底主色同色系极浅版点睛高亮色每段 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 说用摸鱼绿把这篇文章排成公众号 HTMLarticle.mdAgent 工作流依次完成选主题确认 → 读组件库 → 解析 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 被完全禁止必须使用内联样式确认positionabsolute/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、脚本确定性校验均得到独立信源的事实层面印证。关于换模型不走样的主张也是合理的——确定性逻辑下沉到脚本后模型只做内容填充理论上国产模型均可跑通。边界与局限不能无条件唱赞歌几个需要诚实指出的限制只排版、不写作README 明确写了这是先有 Markdown 再用它不能指望它帮你生产内容。这在宣传语境下容易被忽视。图片仍需手动上传公众号要求图片来自微信素材库mmbiz.qpic.cn域名生成的 HTML 里的外链图片在公众号内无法显示。这个痛点项目没有完全解决只能在文章里用占位组件上传步骤仍是手动的。粘贴不掉格式的前提是用对粘贴方式必须用预览页的复制到公众号按钮而非普通 CtrlC否则剪贴板行为取决于浏览器仍可能出问题。主题生成器依赖模型能力用一句话或参考图生成新主题背后是让 LLM 输出 45~75 个 HTML 组件块质量高度依赖模型的上下文理解能力。能力弱的模型生成的主题可能一致性差仍需人工审核。AGPL-3.0 协议的商业使用风险如果有公司想把它集成进 SaaS 产品AGPL 要求即使只部署成服务也必须开源修改版代码——这是很多商业场景的硬门槛需提前评估。个人启发对内容运营者如果你每周写 2 篇以上公众号排版时间是实打实的沉没成本。这个工具的价值不在于生成漂亮排版市面上有很多而在于可重复、跨模型、不依赖某个网页工具的稳定性——你的主题文件就在本地 Git 仓库里不会因为第三方工具关停而丢失。对 AI Agent 开发者gzh-design-skill 是一个很好的确定性约束 LLM 内容生成组合的范本。核心思路是把平台的死规则写成校验脚本不可绕过的硬约束让 LLM 只做软判断内容理解、关键词提取、风格匹配。这个分工思路可以直接迁移到其他平台适配场景。对工具开发者/贡献者项目当前最大的工程缺口是图片自动上传——如果能接入微信公众号素材 API 做图片批量上传整个链路的一键才算真的闭合。这是最有价值的贡献方向。延伸思考确定性下沉脚本能走多远当平台微信悄悄更新白名单规则时脚本校验会出现漏判——这套工程体系的维护成本取决于有没有人持续跟踪平台变更。开源社区能否形成平台变更 → Issue → 脚本更新的快速响应机制决定了这个项目的长期可靠性。Agent Skill 这个形态会成为主流吗目前 Claude Code / Cursor 等工具的 Skill/Rule 体系还没有标准化各家实现不兼容。gzh-design-skill 作为一个早期实践验证了把领域知识打包成 Skill 给 Agent 调用的可行性——但如果 Agent 平台出现大的架构变更如 Claude Code 换接口协议这套 Skill 可能需要重写适配层。主题生成器是这套系统最脆弱的环节还是最有价值的扩展点让 LLM 一次性生成 45~75 个组件的完整主题库成功率高度依赖 prompt 工程和模型能力。随着模型上下文窗口和指令遵循能力的提升这个功能的稳定性会系统性提高——这意味着用户自定义主题的门槛会越来越低6 套内置主题的价值反而会相对下降项目的核心竞争力将更多落在校验脚本的准确性而非主题数量上。 参考来源GitHub - isjiamu/gzh-design-skill: 把 Markdown 一键排成可直接粘进公众号编辑器的精致 HTML —— 6 套精选主题 主题生成器 双关卡校验。An AI-agent skill that turns Markdown into paste-ready WeChat article HTML. · GitHub