md2wechat — 从 Markdown 到微信 HTML 的全流程工具

这篇文章是 md2wechat 的架构笔记，记录我为什么造这个工具、怎么设计它、从中得到了哪些关于 Agent-native CLI 的通用结论。

背景：微信排版工具的问题

市面上不缺微信排版工具，但它们几乎都有同一个问题：把 LLM 当排版引擎来用。

你输入 Markdown，给 Claude 一段提示词，Claude 返回带 inline CSS 的 HTML。这条路有根本性的缺陷：

• 不确定性：同样的 Markdown，今天和明天生成的 HTML 可能完全不同。
• 主题不可控：排版风格靠 prompt 描述，没有精确定义，Claude 每次理解不一样。
• 自动化困难：输出不稳定，不能放进定时任务或 CI 里。

md2wechat 的核心判断是：排版应该是确定性的，LLM 负责写内容，排版系统负责渲染。

核心设计：:::block 排版语言

md2wechat 引入了一套 :::block 语法，作为 Markdown 和 HTML 之间的中间层。

:::block hero
eyebrow: 深度观察
title: AI 时代的公众号写作
subtitle: 为什么你需要重新定义「好内容」
:::

:::block callout type=tip
高级排版模块仅在 API 模式下生效。
:::

:::block timeline
- 2024：GPT-4 发布，内容生产门槛归零
- 2025：AI 写作工具爆发，同质化严重
- 2026：高质量、有视角的内容成为稀缺品
:::

这不是让 LLM「猜」如何排版，而是精确声明你想要什么结构。每个 :::block 对应一个明确定义的排版组件，有固定的参数和渲染规则。

43 个排版模块，从 hero banner、callout、timeline，到数据卡片、对比表格、引用块——覆盖公众号内容的主要排版场景。

# 查看所有可用模块
md2wechat layout list

# 验证文章中的 :::block 用法是否正确
md2wechat layout validate --file article.md

全流程设计

md2wechat 不止做格式转换，它覆盖公众号写作的完整流程：

# 从想法到草稿箱，4 步
md2wechat write --style dan-koe           # 1. 生成文章 + 封面提示词
md2wechat humanize article.md            # 2. 去除 AI 痕迹
md2wechat generate_cover --article article.md  # 3. AI 生成封面图
md2wechat convert article.md --draft --cover cover.jpg  # 4. 推送草稿

每个命令职责单一，可以组合，也可以单独用。inspect 命令在 convert 前检查文章的发布 readiness，避免把不完整的内容推上去：

md2wechat inspect article.md
# 输出：标题、字数、图片数、:::block 验证结果、微信限制检查

Agent-native 设计

这个工具从一开始就为集成 Coding Agent 设计。

Discovery 优先

所有能力都可以通过命令查询，不需要 Agent 靠猜：

md2wechat capabilities --json     # 当前实例能力总览
md2wechat themes list --json      # 所有主题列表
md2wechat layout list --json      # 43 个排版模块列表
md2wechat providers list --json   # 图片生成 provider

Agent 先执行 discovery，再决定怎么做，而不是靠记忆或 hallucination。

JSON envelope

所有命令加 --json 后，stdout 只输出结构化 JSON，包含 status、data、error 字段。Agent 消费这个 envelope 而不是解析人类可读的输出。

Skill 集成

# 安装 CLI（先装这个）
brew install geekjourneyx/tap/md2wechat

# 安装 skill（Claude Code / Codex）
npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat

安装后可以直接用自然语言驱动整个流程：

"用 Dan Koe 风格写一篇关于 AI 时代独立开发者的文章，生成封面，用 elegant-gold 主题推送到草稿箱"

AI 模式 vs API 模式

md2wechat 有两种运行模式，对应不同的使用场景：

# AI 模式（不需要 API Key）
md2wechat convert article.md --mode ai --theme autumn-warm --preview

# API 模式（默认）
md2wechat convert article.md --preview

与「HTML 替代 Markdown」的关系

前面的文章 在 Claude Code 中用 HTML 替代 Markdown 提出：Agent 的输出应该直接是可在浏览器渲染的 HTML，而不是 Markdown。

md2wechat 是这个判断在公众号写作场景的具体落地：

• 内容用 Markdown 写（人类友好）
• 排版用 :::block 声明（结构化，可验证）
• 输出是针对微信渲染优化的 HTML（最终消费格式）

Markdown 作为写作语言的地位没变，变的是中间层和输出层：用 DSL 而不是 prompt 控制排版，用确定性 HTML 而不是 LLM 输出作为最终结果。

生态

围绕 md2wechat 延伸的工具矩阵：

相关项目

同样是"HTML 作为中间排版层"思路的另一个实践：travel-guidebook — 输入一句话行程需求，并行调研 + HTML 写作 + Playwright PDF 导出，输出 30+ 页精排路书。

一个通用结论

造 md2wechat 让我对 Agent-native CLI 有了一个更清晰的认识：

LLM 负责内容，确定性系统负责格式。

凡是有明确规则的事情——排版、格式转换、数据验证——都不应该依赖 LLM。LLM 的价值在于处理模糊、生成内容、理解意图。把这两件事混在一起，两件事都做不好。

这也是 :::block 语法存在的理由：给 LLM 一个精确的词汇表，让它声明「我想要一个 timeline 排版」，而不是用 prompt 描述「我想要类似时间线那种感觉的排版」。