md2wechat
面向 AI Agent 的微信公众号创作与发布 CLI
写 Markdown，生成公众号排版，制作封面和文章配图，预览校验后推送草稿箱。
支持 Claude Code、Codex、WorkBuddy、Kimi Work、Hermes Agent、OpenClaw 等 Agent 通过 JSON discovery 稳定调用。
排版效果 · 快速开始 · 专业 API · 联系我 / 获取 API Key · 文档
接入有疑问？关注公众号「极客杰尼」，发消息「API咨询」；也可以直接发邮件到 skrphper@gmail.com。查看联系方式与二维码
Tip
v3.8.0 高级排版升级：83 个推荐场景对应 59 个推荐语法；新增 cover-reveal、expand，gallery 进入推荐目录，并扩展 12 种品牌图形符号与动效。 新互动模块默认完整静态展示；显式 first-layer 仅为点击候选，微信内效果仍待验证。布局指南 · 版本化安装
这个项目解决什么问题
md2wechat 把公众号发布流程拆成一组可验证的 CLI 命令：
| 场景 | md2wechat 提供 |
|---|---|
| Markdown 转微信 HTML | convert，支持预览、上传图片、创建草稿 |
| 发布前检查 | inspect --json 输出标题、摘要、图片、cover、draft readiness |
| 稳定排版 | API 模式成功时返回最终 HTML，覆盖 83 个主推高级排版场景条目和 59 个主推 ::: 语法名 |
| Agent 自动化 | capabilities、doctor、themes、layout、providers 等 discovery 命令 |
| 内容生产 | write、humanize、title suggest、generate_cover、generate_infographic |
| 定向产品写作（v3.7.0） | 组合目标搜索产品、文章平台、体裁与作者语气，也可准备分平台百科词条草稿；使用说明 |
| 多平台草稿 | 本地准备正文，宿主复用已登录浏览器，按内置步骤写入知乎、CSDN、头条、腾讯云开发者社区草稿 |
| 多账号发布 | 命名公众号账号，本地只读发现，不输出 Secret |
| 微信白名单 | 高级 API 服务可提供微信接口固定出口能力 |
排版效果
先看文章排出来的样子，再选择使用方式。
图中内容为排版示例；专业主题与高级模块的服务范围见专业 API。
查看更多主题与模块样稿
快速开始
npm install -g @geekjourneyx/md2wechat@3.8.0 md2wechat version --json md2wechat config init --json md2wechat config validate --json
以下预览和转换命令使用付费 API 模式，需要先配置 md2wechat API Key。联系我获取 Key · 查看服务范围与价格。完成凭证配置后，先检查文章，再把 HTML 明确写入本地文件：
md2wechat inspect article.md --json md2wechat preview article.md --output preview.html md2wechat convert article.md --output article.html
以上命令不会上传图片或创建草稿。需要创建微信草稿时，先按同一目标检查，再显式执行副作用：
md2wechat inspect article.md --draft --cover cover.jpg --json md2wechat convert article.md --draft --cover cover.jpg
如果使用可选的 --wechat-account，必须在 inspect 和 convert 两条命令中传入同一个账号名。
想先了解免费 AI 模式？它会生成交给宿主 Agent / 外部 LLM 继续处理的 prompt，不会直接返回最终 HTML。见 AI 模式使用步骤。
v3.6.0 新增跨平台草稿流程：先准备正文，再由宿主 Agent 按内置步骤操作已登录的浏览器。已安装版本先用 capabilities --json 确认支持：
md2wechat sync prepare article.md --output ./article-prepared --json
md2wechat skills read md2wechat references/sync/workflow.md --json准备结果是等待宿主执行，不代表草稿已创建。平台步骤、图片处理、头条标题限制和恢复方式见 多平台草稿。
安装方式、微信凭证和 IP 白名单配置见：
专业 API
API 模式适合需要稳定输出、多人协作、批量发布或 Agent 自动化的场景。
专业 API 是付费服务，包含稳定转换接口、定期更新和专属创作交流群。服务范围与价格以官网及开通时确认的信息为准。
查看服务范围与价格 · 联系我 / 获取 API Key · 接口文档
| 能力 | 免费 AI 模式 | 专业 API 模式 |
|---|---|---|
| 输出方式 | 生成 prompt，由外部 LLM 继续处理 | 直接返回微信 HTML |
| 主题 | 3 个基础主题 | 48 个专业主题 |
| 高级排版模块 | 不解析，:::module 作为普通段落输出 |
API renderer 解析 59 个推荐 :::module 语法 |
| 转换结果 | 需要外部 LLM 完成 HTML | converter 成功时返回最终 HTML |
| 发布自动化 | 适合实验 | 适合团队、客户号、矩阵号 |
专业能力包括：
- 48 个微信渲染精调主题：主题画廊
- 83 个主推高级排版场景条目，对应 59 个主推
:::语法名；本次扩展含 12 种品牌图形符号及受位置约束的动效：docs/LAYOUT.md - 2 个兼容模块只用于旧稿迁移；加上 4 个基础增强能力，共计 65 项渲染层语法能力
- 多公众号账号：docs/CONFIG.md
- 微信接口固定出口：docs/WECHAT-CREDENTIALS.md
- 发布前 readiness 检查：docs/DISCOVERY.md
联系我
我是极客杰尼，md2wechat 的维护者。API 开通、安装配置、团队接入或商业授权，都可以通过下面的方式联系我。
- 微信： 扫码或搜索公众号「极客杰尼」，关注后发消息「API咨询」，说明你的使用需求。
- 邮箱： skrphper@gmail.com
- 接入咨询： 整理接入需求（在页面生成摘要后，通过微信或邮件联系我）
咨询时可以告诉我：你用哪个 Agent / 系统、希望完成什么任务，以及卡在哪一步。
Agent 工作流
md2wechat 给 Agent 提供可机读接口，减少猜测和误操作。
md2wechat capabilities --json
md2wechat doctor --json
md2wechat inspect article.md --json
md2wechat themes list --json
md2wechat layout list --json
md2wechat title suggest article.md --json
md2wechat title suggest article.md --json --hook-level 2
md2wechat skills list --json
md2wechat skills read md2wechat --json按任务选择 discovery：用 capabilities 获取聚合路由事实，用资源的 list 做选择，用 show 查看单个资源的完整定义，仅在该资源支持时使用 render。JSON stdout 是单行紧凑对象并以换行结束；人类阅读时可在命令后加 | jq，不要要求 CLI 改成缩进输出。
文章命令边界固定为：inspect 返回结构化 metadata、checks、readiness targets 和 blockers；preview 只把成功的 API converter 最终 HTML 原样写入文件；convert 执行转换，并且只在用户明确请求时执行 upload/draft 副作用。AI preview 返回 PREVIEW_ACTION_REQUIRED 且不创建输出文件，需要 readiness 时使用 inspect --json。
这些命令适合 Claude Code、Codex、WorkBuddy、Kimi Work、Hermes Agent、OpenClaw 以及其他能调用本地 CLI 的 Agent 使用。
Agent 可以据此判断：
- 当前 CLI 支持哪些命令
- API、草稿、上传是否具备执行条件
- 某篇文章能不能发草稿
- 当前主题和排版模块是否可用
- 标题建议是否应交给宿主 Agent / 外部模型完成
- 当前二进制内置的 Agent SOP 是什么
Brand Profile 支持把长期风格偏好写入 ~/.config/md2wechat/brand.md，由 Agent 在写作和排版时读取。详见 docs/BRAND-PROFILE.md。
图片生成
md2wechat 支持两条图片路径。
先从当前二进制发现可用 preset，再调用图片 provider：
md2wechat prompts list --kind image --archetype cover --json md2wechat prompts list --kind image --archetype infographic --json md2wechat generate_cover --article article.md md2wechat generate_cover --article article.md --preset cover-semantic-concept md2wechat generate_infographic --article article.md --preset infographic-claude-warm
完整 preset 清单、用途和默认画幅以 prompts list/show --json 为准，文档只保留代表性示例。
支持 Volcengine、ModelScope、OpenRouter、OpenAI、Gemini、MiniMax、Atlas Cloud 等服务。配置见 docs/IMAGE_PROVISIONERS.md。
需要在生成结果中保持同一人物形象时，可以用 MiniMax 的主体参考（图生图）：
md2wechat generate_image "保持同一人物形象的秋日封面" \ --subject-reference "https://cdn.example.com/portrait.png"
--subject-reference 只支持 minimax provider 的 image-01 模型，参考图必须是可公开访问的 http(s) 图片 URL。
使用宿主 Agent 的 Image Gen：
md2wechat generate_cover --article article.md --plan --json md2wechat generate_infographic --article article.md --plan --json
计划模式返回 IMAGE_PLAN_READY，不请求图片 provider，不要求 IMAGE_API_KEY，也不会上传到微信。仅当当前宿主运行时实际暴露 Image Gen 工具时，Agent 才能继续执行图片生成。详见 docs/AGENT_IMAGE_GEN.md。
高级排版
API 模式支持 :::module 语法，用 Markdown 写结构化公众号排版。
:::hero eyebrow: 深度观察 title: AI 时代的公众号写作 subtitle: 为什么读者愿意继续读下去 ::: :::callout type: info body: 高级排版模块只在 API 模式渲染。 :::
查看和验证模块：
md2wechat layout list --json md2wechat layout show hero --json md2wechat layout validate --file article.md --json
本地 layout validate 只验证语法，不能证明远端 renderer 已部署；需要通过 API preview 或 convert 验证实际渲染。
完整教程见 docs/LAYOUT.md。
这里的计数不是同一维度：83 是上游使用场景条目，一个语法名可以覆盖多个结构变体；59 是 layout list --json 默认返回的推荐语法名。兼容模块默认不混入推荐列表。完整计数契约见 docs/LAYOUT.md。
常用命令
| 命令 | 用途 |
|---|---|
inspect |
返回结构化 metadata、checks、readiness targets 和 blockers |
advise |
为已有文章推荐可选的最小增强动作 |
preview |
只写入成功 API 转换的最终 HTML；失败或 AI handoff 不新建或覆盖 |
convert |
转换 Markdown，并按显式请求执行 upload/draft 副作用 |
write |
从想法生成文章 |
humanize |
重写 AI 文章，支持 authentic 强度 |
title suggest |
生成公众号标题建议的 AI 请求 |
generate_cover |
生成封面图或图片计划 |
generate_infographic |
生成信息图或图片计划 |
upload_image |
上传图片到微信素材库 |
create_image_post |
创建微信图片消息（小绿书/newspic） |
sync prepare |
本地准备跨平台正文，等待宿主创建和核验草稿 |
config wechat-accounts |
查看本地多公众号账号配置 |
doctor |
本地配置体检 |
文档
| 文档 | 内容 |
|---|---|
| QUICKSTART | 新手主路径 |
| USAGE | 命令完整说明 |
| DISCOVERY | Agent discovery 契约 |
| SYNC | 知乎、CSDN、头条、腾讯云开发者社区草稿同步 |
| WORKBUDDY | WorkBuddy 安装、检查、预览与草稿确认流程 |
| ADVISE | 已有文章的可选增强建议 |
| LAYOUT | 高级排版模块教程与 discovery 用法 |
| HUMANIZE | AI 去痕与 authentic 写作 |
| AGENT_IMAGE_GEN | 宿主 Agent Image Gen 工作流 |
| CONFIG | 配置字段和环境变量 |
| FAQ | 常见问题 |
| TROUBLESHOOTING | 故障排查 |
许可与商业使用
本项目采用 Source Available License。个人使用、学习、评估、非营利使用免费。商业使用、SaaS、客户交付、白标、再分发和训练数据用途需要商业授权。
专业 API：查看服务范围与价格 · 联系我获取 API Key。购买 API 服务不自动包含商业授权；商业授权（SaaS、客户交付、白标、再分发和训练数据）请联系我。
Made by geekjourneyx