# md2wechat full context

> Complete Agent-readable context for 面向 AI Agent 的微信公众号创作与发布 CLI，covering the online editor, main CLI, Agent Skill, stable API, documentation, comparisons, and tutorials.

Updated: 2026-09-24
Primary site: https://www.md2wechat.cn
CLI command: md2wechat
Main CLI package: @geekjourneyx/md2wechat
Stable API: POST https://www.md2wechat.cn/api/convert
Publishing API: https://md2wechat.com/api/v1
GitHub Skill: https://github.com/geekjourneyx/md2wechat-skill

## Website entry points

- 命令与能力大全: https://www.md2wechat.cn/cli/commands
- 多平台草稿: https://www.md2wechat.cn/multi-platform
- 多平台草稿教程: https://www.md2wechat.cn/docs/multi-platform
- Obsidian 插件: https://www.md2wechat.cn/obsidian
- API 服务: https://www.md2wechat.cn/product
- CLI 与 Agent Skill: https://www.md2wechat.cn/cli
- 在线编辑器: https://www.md2wechat.cn/editor
- 排版作品: https://www.md2wechat.cn/theme-gallery
- 接入步骤: https://www.md2wechat.cn/docs/quickstart
- 价格与开通: https://www.md2wechat.cn/pricing

## Directed writing

CLI reference version: 3.7.0. 由 Agent 根据产品资料、读者、发布平台、体裁和作者语气准备文章或百科词条草稿。
使用 CLI 内置写作指引，没有新增写作命令或模型接入。百科支持交付词条草稿，不代为提交，不保证审核、收录或搜索引用。
Read: md2wechat skills read md2wechat references/writing/workflow.md --json
Guide: https://github.com/geekjourneyx/md2wechat-skill/blob/v3.7.0/docs/WRITING.md

## Multi-platform unpublished drafts

借助具备浏览器能力的 Agent，将符合要求的 Markdown 保存为知乎、CSDN、头条、腾讯云开发者社区未发布草稿，保存后重新打开核对。
需要具备浏览器能力的 Agent，以及用户已登录的目标平台账号。
支持普通 Markdown 与有效本地图片；远程图片、Obsidian 专用语法、原始 HTML 和高级排版块需先处理。
本地准备不需要微信凭证或排版 API Key；准备成功不等于草稿完成。
头条会归一化标题级别；混合多个标题级别时须在写入前停止，经作者同意调整原稿后再继续。特殊字符须逐字符核对。
腾讯云指引从 v3.7.0 起提供。先粘贴正文，再通过编辑器插入本地图片；保存后重新打开同一草稿核对。多图、长文及草稿列表恢复尚未验证。
项目记录包含 macOS、Chrome 已登录会话的知乎、CSDN、头条短图文、结构与长文验证。腾讯云已验证短结构正文与单图保存重开；多图、长文及从草稿列表恢复尚未验证。其他系统与 Agent 宿主尚未逐一验收。
企业自用、代运营及客户交付请先确认授权范围。商业授权单独沟通，购买服务不自动包含商业授权。
Run `md2wechat capabilities --json` and `md2wechat sync prepare article.md --output ./article-prepared --json`; the output directory must be new and its parent must exist. SYNC_PREPARED / action_required means local preparation only. Read the installed `references/sync/workflow.md` and each target platform instruction with `md2wechat skills read md2wechat <path> --json`. Reopen an existing draft to resume; do not create duplicates. No automatic public publishing or update of previously published articles.
Release: https://github.com/geekjourneyx/md2wechat-skill/releases/tag/v3.7.0
Evidence: https://github.com/geekjourneyx/md2wechat-skill/blob/v3.7.0/docs/SMOKE.md
Private drafts do not create publicly searchable content. Public publication does not guarantee indexing, ranking or AI citations.

## How Agents should use this file

1. Use /llms.txt for quick routing and canonical facts.
2. Use this /llms-full.txt file when complete product context is needed.
3. For execution protocol, prioritize the SKILL.md section below.
4. For setup, configuration, themes, advanced layout, title suggestions, image plans, drafts, FAQ, and troubleshooting, read the handbook section below.
5. For conversion-only work, use POST https://www.md2wechat.cn/api/convert.
6. For WeChat Publishing API work, use https://md2wechat.com/api/v1.
7. For Zhihu, CSDN, Toutiao and Tencent Cloud Developer Community drafts, use local sync prepare and the host Agent browser workflow described at /docs/multi-platform; do not route these targets to the WeChat Publishing API.

## Important routes

- https://www.md2wechat.cn
- https://www.md2wechat.cn/docs
- https://www.md2wechat.cn/docs/md2wechat
- https://www.md2wechat.cn/docs/md2wechat.md
- https://www.md2wechat.cn/docs/md2wechat/skill
- https://www.md2wechat.cn/docs/md2wechat/skill.md
- https://www.md2wechat.cn/api-docs
- https://www.md2wechat.cn/wechat-publishing-api
- https://www.md2wechat.cn/integrations
- https://www.md2wechat.cn/integrations/qwenwork
- https://www.md2wechat.cn/integrations/dumate
- https://www.md2wechat.cn/integrations/doubao-work
- https://www.md2wechat.cn/integrations/workbuddy
- https://www.md2wechat.cn/workflows/markdown-to-wechat-draft
- https://www.md2wechat.cn/compare/md2wechat-vs-wechatsync
- https://www.md2wechat.cn/compare
- https://www.md2wechat.cn/theme-gallery
- https://www.md2wechat.cn/blog


# md2wechat handbook

# md2wechat 接入手册

更新时间：2026-09-22

这是一份给人和 Agent 共用的 md2wechat 手册。它把 README、项目 docs、个人实践手册里的关键路径整理到一个网页里，方便分享，也方便 Agent 直接读取。

适合读者：

- 第一次听说 md2wechat，不懂 API、CLI、微信凭证区别的人
- 已经购买 md2wechat API，不知道下一步怎么配置的人
- 想把 md2wechat 接到 Claude Code、Codex、OpenClaw、Obsidian 或自建 Agent 的用户
- 想让 Agent 自己发现能力、排查问题、选择主题、预览文章、创建草稿的团队

Agent 优先读取：

- 网页版：https://www.md2wechat.cn/docs/md2wechat
- Markdown 版：https://www.md2wechat.cn/docs/md2wechat.md
- SKILL.md 原文：https://www.md2wechat.cn/docs/md2wechat/skill.md
- API 文档：https://www.md2wechat.cn/api-docs
- 主题画廊：https://www.md2wechat.cn/theme-gallery


## 命令目录与版本

完整命令、子命令及参数见[命令与能力大全](/cli/commands)。目录依据 v3.7.0；本机先运行 `md2wechat version --json`，版本不同时以本机 `--help` 为准。升级沿用 npm 安装方式，保留已有配置，不需要重新初始化。

## 产品介绍、平台文章与百科草稿

从 v3.7.0 起，Agent 可以读取内置定向写作指引，根据资料、读者、平台、体裁与作者语气准备文章。没有新增写作命令或模型接入；仅排版时保留原文。

```bash
md2wechat skills read md2wechat references/writing/workflow.md --json
```

产品介绍与平台文章优先走上述流程。已有文章只想判断下一步，可以运行 `md2wechat advise article.md --json`；它只提供改进建议，不改稿、不生成图片、不创建草稿。发布前仍通过 `inspect` 检查条件。

百度百科、头条百科分别有内置指引，交付的是词条草稿与材料缺口，不提交词条，不保证审核、收录或引用。头条百科完整当前细则尚未核实。示例与核对方法见[定向写作教程](/blog/md2wechat-directed-writing-guide)，来源见[v3.7.0 写作说明](https://github.com/geekjourneyx/md2wechat-skill/blob/v3.7.0/docs/WRITING.md)。

## 办公 Agent 如何安装和使用 md2wechat

千问办公、DuMate、WorkBuddy、豆包工作（也常被称为豆包办公）采用同一条使用路径：让 Agent 在当前执行环境安装 md2wechat CLI，再读取操作手册。把下面这段提示词直接发给你的办公 Agent：

```text
帮我安装 md2wechat，执行安装：
npm install -g @geekjourneyx/md2wechat

如果没有初始化配置，请执行初始化配置：
md2wechat config init

已有配置请保留。如果缺少 Node.js 或 npm，请先检查并完成安装。
安装后读取操作手册：https://www.md2wechat.cn/docs/md2wechat/skill
CLI 使用手册：https://www.md2wechat.cn/docs/md2wechat
请检查 md2wechat version --json，告诉我安装结果和下一步需要补充的配置。
```

Agent 需要能执行终端命令并读写文章文件。如果它运行在远程环境或沙箱，安装也应在那个环境完成。初始化配置不会自动开通 API Key；调用排版服务时按手册填写自己的有效密钥。

安装后，把文章交给 Agent：

```text
请使用 md2wechat 为这篇文章排版。
先阅读 https://www.md2wechat.cn/features，了解高级排版模块。
保留原文事实和数据，选择适合内容的模块，不要为了使用模块增加虚构内容。
按 https://www.md2wechat.cn/docs/md2wechat/skill 操作。
将排版后的 Markdown 另存为新文件，生成预览供我检查。
如果缺少配置，请明确告诉我需要补充什么。本次只预览。
```

完整步骤见[办公 Agent 安装与排版教程](/blog/office-agent-md2wechat-install-guide)。高级排版可先看[功能介绍](https://www.md2wechat.cn/features)，再查[网页版文档](https://www.md2wechat.cn/docs)和[高级排版教程](https://mp.weixin.qq.com/s/im5k-SXcoHMA6Kewtnm4Fw)。

## 先用一句话解释 md2wechat

md2wechat 是面向 AI Agent 的微信公众号创作与发布工具。

你用 Markdown 写文章，md2wechat 负责生成公众号排版、检查文章状态、制作封面和文章配图、生成预览，并在配置好微信凭证以后推送到公众号草稿箱。

如果配合 Agent，它可以把“整理文字、检查错别字、生成结构、选择主题、做排版、生成封面、发草稿箱”连成一条流程。

## 先分清 4 个概念

### Markdown 是文章原稿

Markdown 是干净的文章格式。你先把正文写成 Markdown，再交给 md2wechat 排版。

### CLI 是本地命令工具

CLI 是在电脑或服务器里运行的工具。它适合：

1. 本地预览文章
2. 转换公众号 HTML
3. 上传图片
4. 创建公众号草稿
5. 让 Agent 用命令执行发布流程

新手不需要一开始理解所有命令。Agent 可以帮你执行命令，你只需要知道每一步要达成什么结果。

### API 是在线排版服务

API 负责把 Markdown 稳定渲染成微信可用 HTML。它适合：

1. 稳定使用 API 模式主题
2. 使用高级排版模块
3. 接入自己的系统、团队流程或 Agent 服务
4. 批量处理公众号文章

API 服务负责稳定转换，不负责替你理解文章。文章理解、结构增强、品牌表达、模块选择，应该由人或 Agent 在调用 API 前完成。

### 微信凭证不是 md2wechat API Key

很多问题来自把几类 Key 混在一起。

| 名称 | 用来做什么 | 写到哪里 |
| --- | --- | --- |
| md2wechat API Key | 调用 md2wechat 排版服务 | `api.md2wechat_key` |
| 微信 AppID / AppSecret | 上传图片、创建公众号草稿 | `wechat.appid` / `wechat.secret` |
| 图片服务 Key | 生成封面图、配图、信息图 | `api.image_key` |

三类 Key 不能混用。不要把任何 Key 写进文章正文、README、公开截图或公开仓库。

## 你现在该走哪条路径

| 你要做什么 | 先做什么 | 暂时不用做什么 |
| --- | --- | --- |
| 只体验排版 | 在线体验或本地 `preview` | 不用配置微信 AppID |
| Markdown 转 HTML | 配置 `api.md2wechat_key` | 不用配置微信 AppSecret |
| 用高级排版模块 | 使用 API 模式，先跑 `layout validate` | 不要走 AI 模式 |
| 生成本地预览 | `inspect` 后运行 `preview` | 不要直接发草稿 |
| 创建公众号草稿 | 配置微信凭证、封面、IP 白名单 | 不要只配 API Key |
| 生成封面图 | 配置图片服务和微信凭证，或用图片计划模式 | 不要把图片 Key 写进正文 |
| 让 Agent 接管 | 先跑 discovery 和 doctor | 不要让 Agent 凭记忆猜主题 |

## 安装：统一使用 npm 主路径

文档系统、Agent 指南和用户教程统一推荐 npm 安装，避免不同安装渠道造成能力口径不一致。当前版本不要从网页文案推断，以 npm、GitHub Release 和本机 `md2wechat version --json` 的结果为准。

```bash
npm install -g @geekjourneyx/md2wechat
md2wechat config init
```

Windows PowerShell 同样使用 npm：

```bash
npm install -g @geekjourneyx/md2wechat
md2wechat config init
```

安装后验证：

```bash
md2wechat version --json
md2wechat capabilities --json
md2wechat skills read md2wechat --json
```

`skills read md2wechat --json` 读取的是当前 CLI 内置的 Agent 操作协议。Agent 不应该凭记忆猜命令、主题、provider、prompt 或 layout 模块，应该以这条命令和 discovery 输出为准。

如果命令不存在：

```bash
command -v md2wechat
md2wechat version --json
```

安装细节以 GitHub README 和 release 文档为准：

```text
https://github.com/geekjourneyx/md2wechat-skill
```

## 购买 API 后下一步做什么

买完 API 后，先配置 md2wechat API Key。不要一上来配置微信草稿箱。

### 让 Agent 配置 API Key 的话术

把这段发给你自己的私有 Agent：

```text
帮我配置 md2wechat API Key。

我的 md2wechat API Key 是 xxx。
请写入 md2wechat 的本地配置文件，字段是 api.md2wechat_key。
不要写进文章正文、README、截图或公开仓库。

如果没有配置文件，先运行 md2wechat config init。
配置完请运行：
1. md2wechat config show --format json
2. md2wechat config validate
3. md2wechat doctor --json

最后告诉我 API 模式是否可用。
```

配置文件默认位置：

```text
~/.config/md2wechat/config.yaml
```

最小配置：

```yaml
api:
  md2wechat_key: "你的 md2wechat API Key"
  md2wechat_base_url: "https://www.md2wechat.cn"
  convert_mode: "api"
  default_theme: "default"
```

临时环境变量：

```bash
export MD2WECHAT_API_KEY="你的 md2wechat API Key"
```

## 第一次预览

第一次不要直接创建草稿。先安装、验证、预览。

准备 `article.md`：

```md
# 我的第一篇 md2wechat 测试文章

这是我用 md2wechat 跑通的第一篇公众号文章。

## 为什么要测试

先跑通预览，再考虑封面、草稿和自动化。
```

按顺序运行：

```bash
md2wechat inspect article.md --json
md2wechat preview article.md
md2wechat convert article.md -o article.html
```

做对的标志：

- `version --json` 有正常输出
- `inspect` 能读到文章
- `preview` 生成了本地预览文件
- `convert` 能输出 HTML
- 还没有把微信密钥写进正文或公开仓库

## 直接调用 API

如果你要把 md2wechat 接到自己的系统里，可以直接调用 `/api/convert`。

请求头支持：

```http
X-API-Key: YOUR_MD2WECHAT_API_KEY
```

或：

```http
Authorization: Bearer YOUR_MD2WECHAT_API_KEY
```

最小请求：

```bash
curl -X POST "https://www.md2wechat.cn/api/convert" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_MD2WECHAT_API_KEY" \
  -d '{
    "markdown": "# 标题\n\n这是一个**加粗**的文本。",
    "theme": "default",
    "fontSize": "medium",
    "backgroundType": "default"
  }'
```

返回里的 `data.html` 就是可以用于微信公众号编辑器的 HTML。

完整接口说明看：

```text
https://www.md2wechat.cn/api-docs
```

## 主题怎么选

两种方式。

### 人先看主题画廊

```text
https://www.md2wechat.cn/theme-gallery
```

适合先看视觉效果，再选择一个主题。

### Agent 查本机可用主题

```bash
md2wechat themes list --json
md2wechat themes show elegant-gold --json
```

给 Agent 的话术：

```text
请只从 md2wechat themes list --json 返回的主题里选择。
结合这篇文章类型，推荐 3 个主题，并说明每个主题适合什么场景。
不要凭记忆猜主题名。
```

新手可以先从这些方向选：

| 文章类型 | 主题建议 |
| --- | --- |
| 商业、方法论、个人品牌 | `elegant-gold` |
| 工具教程、技术说明、产品更新 | `minimal-blue` |
| 稳妥干净 | `wechat-native` |
| 先跑通流程 | `default` |

API 模式只能选择 `type: api` 且 `selectable: true` 的主题。

## 高级排版模块

高级排版模块入口：

```text
https://www.md2wechat.cn/features
```

新手不要一上来堆很多模块。先按文章目的选。

| 你想解决什么 | 模块方向 |
| --- | --- |
| 建立刊头式第一屏 | `hero: masthead` |
| 建立长文章节层级 | `section-title` |
| 开头更吸引人 | `hero`、`verdict`、`toc` |
| 步骤更清楚 | `steps`、`timeline`、`checklist` |
| 对比更清楚 | `comparison-table`、`pros-cons`、`matrix` |
| 观点更突出 | `quote`、`callout`、`summary` |
| 数据更好看 | `metrics`、`stat-row`、`infographic` |
| 进入最后判断 | `epilogue` |
| 引导收藏、咨询或试用 | `cta` |
| 轻量感谢或签名 | `closing` |

标题与收尾模块的职责边界：

- `hero: masthead`：专题、发布稿和品牌栏目的刊头开场。
- `section-title`：长文章节入口，支持 `marker`、`divider`、`numbered`、`frame`、`focus`、`vertical` 六种结构。普通小节仍使用 Markdown 标题。
- `part`：开启普通大章节；不要和 `epilogue` 表达同一次转场。
- `epilogue`：只表示文章进入尾声或最后判断。
- `cta`：推动下一步行动。`save-follow` 用于收藏关注，`consult` 用于咨询沟通，`trial` 用于试用转化；只有 `trial` 使用 `points`。
- `closing`：只做感谢、祝愿或安静签名，不承担收藏、咨询或试用。

标题与收尾的 `symbol` 不接收任意字符。调用方填写系统公布的语义化英文键，由渲染器映射为纯文字符号。完整键名和字段规则以 `md2wechat layout show <name> --json` 返回为准。

给 Agent 的话术：

```text
请先判断这篇文章是教程、案例、产品说明还是观点文。

然后执行 md2wechat layout list --json。
按 attention、readability、memorability、conversion 四个目标，每个目标最多选 1 个模块。

不要堆模块。选完以后说明为什么。
不要直接填写符号、Emoji、HTML 或 SVG，也不要自行发明字段或枚举值。
每次写入前先执行 md2wechat layout show <name> --json 读取字段和可选值。
写完后运行 md2wechat layout validate article.md --json。
```

常用命令：

```bash
md2wechat layout list --json
md2wechat layout show hero --json
md2wechat layout show section-title --json
md2wechat layout show cta --json
md2wechat layout validate article.md --json
```

高级排版模块主要在 API 模式渲染。AI 模式可能把模块语法当普通文本。

## 让 Agent 写公众号的标准流程

给 Agent 的最小协议：

```text
你要处理 md2wechat 任务时，先运行：
1. md2wechat version --json
2. md2wechat capabilities --json
3. md2wechat skills read md2wechat --json

如果要排版文章：
1. md2wechat inspect article.md --json
2. md2wechat themes list --json
3. md2wechat layout list --json
4. md2wechat layout validate article.md --json
5. md2wechat preview article.md
6. md2wechat convert article.md

只有我明确要求上传或草稿时，才使用 --upload 或 --draft。
```

Agent 需要遵守：

- 不猜主题名
- 不猜模块语法
- 不把 API Key 写进正文
- 不把高级模块直接写回原文，先写临时稿并校验
- 不在没有用户确认时创建草稿
- 看到 blockers 时先解释问题和下一步

## 标题建议

当前 CLI 支持：

```bash
md2wechat title suggest article.md --json
```

这个命令不是本地标题生成器。它会读取文章，渲染内置标题 prompt，然后把 prompt 放进 JSON 返回。真正生成标题候选的是宿主 Agent 或外部模型。

常用：

```bash
md2wechat title suggest article.md \
  --target-reader "独立开发者" \
  --count 10 \
  --max-title-chars 25 \
  --hook-level 2 \
  --json
```

常用参数：

| 参数 | 默认值 | 范围 | 作用 |
| --- | --- | --- | --- |
| `--target-reader` | 从文章推断 | 任意文本 | 告诉模型标题要打给谁 |
| `--count` | `10` | `8..10` | 希望生成多少个候选标题 |
| `--max-title-chars` | `25` | `12..32` | 单个标题最长字数 |
| `--hook-level` | `1` | `1..3` | 标题钩子张力 |
| `--json` | 必填 | - | 输出机器可读 JSON |

返回里重点看这些字段：

```json
{
  "code": "TITLE_SUGGEST_REQUEST_READY",
  "status": "action_required",
  "data": {
    "prompt": "给外部模型执行的完整提示词",
    "execution_owner": "host_agent",
    "side_effects": false,
    "requires_external_model": true,
    "recommendation_only": true
  }
}
```

`status: "action_required"` 表示 CLI 已经准备好请求，下一步需要 Agent 或外部模型执行 `data.prompt`。

### hook-level 怎么选

| Level | 适合场景 | 风险 |
| --- | --- | --- |
| `1` | 默认、稳健、可信、偏直给价值 | 点击欲望可能不够强 |
| `2` | 想增强反差、数字、实体、后果感 | 需要确保文章内容支撑 |
| `3` | 高张力标题实验 | 最容易越界，必须有证据和风险标记 |

推荐从 `--hook-level 2` 开始。高张力标题必须有文章证据支撑。

### Agent 推荐流程

```text
1. md2wechat capabilities --json
   确认 title_generation 可用。

2. md2wechat title suggest article.md --json --hook-level 2
   读取 data.prompt。
   确认 side_effects=false。
   确认 requires_external_model=true。

3. 调用宿主模型执行 data.prompt。
   让模型返回 strict JSON，不要返回 Markdown 表格。

4. 展示候选标题。
   先看 truthfulness，再看 value，再看 curiosity。

5. 用户确认最终标题后，再进入 preview / convert / draft。
```

### 事实边界

标题可以更有吸引力，但不能编造事实。

| 表达 | 什么时候可以用 | 什么时候不要用 |
| --- | --- | --- |
| `刚刚` | 文章有明确当前时间信号 | 普通复盘、旧闻、无时间证据 |
| `全网` | 文章有传播范围、平台范围或讨论量证据 | 没有范围证据 |
| `第一` | 文章有排名证据 | 只是主观判断 |
| `榜首` | 文章有榜单或排名来源 | 没有榜单 |
| `变天` | 文章能支撑行业变化 | 只是小功能、小更新 |

边界：

- CLI 不直接调用模型
- CLI 不自动选最终标题
- CLI 不写回 Markdown
- CLI 不创建草稿
- 最终标题应由用户确认，或由 Agent 推荐后再确认

## 图片和封面

公众号草稿必须有封面图。封面用于文章入口，正文配图用于解释内容；可以使用自己已有的图片，也可以按下面两条路径生成。

| 任务 | 命令 | 下一步 |
| --- | --- | --- |
| 根据文章制作封面 | `generate_cover --article article.md` | 确认图片，用返回的 `media_id` 设置草稿封面 |
| 根据文章制作信息图 | `generate_infographic --article article.md` | 确认图片，把返回的 `wechat_url` 插入正文 |
| 根据描述制作普通配图 | `generate_image "配图描述"` | 确认图片，把返回的 `wechat_url` 插入正文 |
| 交给宿主 Agent 生成图片 | 上述命令加 `--plan --json` | 执行返回的提示词，保存实际图片后再使用 |

直接生成会调用图片服务并上传微信素材，需要图片服务 Key、微信 AppID / AppSecret 和符合要求的 IP 白名单。仅配置图片服务还不够。计划模式只准备提示词，不生成图片，也不上传素材。

### 直接配置图片 provider

可选服务包括 Volcengine、ModelScope、OpenRouter、OpenAI、Gemini、MiniMax 和 Atlas Cloud 等。先运行 `md2wechat providers list --json` 查看本机支持的服务，再按已有账号和模型需求选择。下面以 Volcengine 为例。

配置示例：

```yaml
api:
  image_provider: "volcengine"
  image_key: "你的火山引擎图片 API Key"
```

让 Agent 配置时这样说：

```text
请帮我配置 md2wechat 图片生成服务。

图片服务使用 volcengine。
我的图片服务 API Key 是 xxx。

请写入 api.image_provider 和 api.image_key。
配置后运行：
1. md2wechat providers list --json
2. md2wechat providers show volcengine --json
3. md2wechat config validate

不要把图片 API Key 写进正文、截图或公开仓库。
```

生成封面：

```bash
md2wechat generate_cover --article article.md
```

### 制作封面图并用于草稿

先发现当前可用的封面预设，再选择与文章内容相符的表达：

```bash
md2wechat prompts list --kind image --archetype cover --json
md2wechat prompts show cover-semantic-concept --kind image --json
md2wechat generate_cover --article article.md --preset cover-semantic-concept --json
```

不指定 `--preset` 时使用内置默认预设。生成成功后，查看返回的 `data.wechat_url` 确认图片，保留同一返回中的 `data.media_id`。用户确认要创建草稿后执行：

```bash
md2wechat convert article.md --draft --cover-media-id "替换为返回的 media_id"
```

`--cover-media-id` 接收微信素材 ID，不接收图片网址。如果用自己的本地封面，则改用 `--cover cover.jpg`；两个参数不能同时使用。封面生成本身不会创建草稿。

### 制作文章配图和信息图

信息图适合解释步骤、对比和知识结构；普通配图适合场景、情绪和具体事物。先明确图片要帮助读者理解什么，再选择预设或编写描述。

```bash
# 查看可用信息图预设与具体用途
md2wechat prompts list --kind image --archetype infographic --json
md2wechat prompts show infographic-claude-warm --kind image --json

# 根据文章制作信息图
md2wechat generate_infographic --article article.md --preset infographic-claude-warm --json

# 根据具体描述制作普通配图
md2wechat generate_image "公众号配图：书桌上的手写提纲与书本，暖色自然光，无文字" --json
```

查看返回的 `data.wechat_url`，核对画面与图中文字后，把实际图片网址插入对应段落附近。CLI 不会自动把生成结果写回文章。

```markdown
![说明这张图帮助读者理解的内容](替换为返回的 wechat_url)
```

如果使用已有本地图片，可写成 `![配图说明](images/figure.png)`，确认路径存在后再预览。需要上传正文图片时使用 `convert article.md --upload`；需要创建草稿时按草稿流程执行。普通预览不会自动上传图片。

### 使用 Atlas Cloud 生成图片

Atlas Cloud 支持从 v3.5.0 开始提供。先更新 CLI，并确认本机已识别该服务：

```bash
npm install -g @geekjourneyx/md2wechat@latest
md2wechat version --json
md2wechat providers show atlascloud --json
```

通过 Homebrew 或安装脚本安装的用户，请沿用原安装方式升级，避免多个安装版本混用。

在配置文件中设置：

```yaml
api:
  image_provider: "atlascloud"
  image_key: "你的 Atlas Cloud API Key"
  image_base_url: "https://api.atlascloud.ai/api/v1/model"
  image_model: "openai/gpt-image-2/text-to-image"
  image_size: "1024x1024"
```

`atlascloud`、`atlas-cloud`、`atlas` 指向同一服务。上面的模型和尺寸是 v3.5.0 的默认值；尺寸使用 `WIDTHxHEIGHT`，不能填 `16:9`。切换模型或尺寸前，请核对所选模型支持的参数。

配置检查通过后，再执行生成：

```bash
md2wechat config validate
md2wechat generate_image "公众号文章配图：暖色纸张上的阅读笔记，留白充足" --json
md2wechat generate_cover --article article.md
```

CLI 提交任务后会等待生成结果。认证失败时检查 Atlas Cloud 密钥；余额不足时检查图片服务账户；限流时稍后重试；任务失败时根据返回原因检查模型和参数。`config validate` 只检查配置，不能证明远程账户余额或生成服务可用。

图片服务使用自己的密钥与计费，购买排版 API 不包含 Atlas Cloud 图片额度。仅需要交给宿主 Agent 生成图片时，可使用下面的计划模式，无需配置此服务。

来源：[v3.5.0 发布说明](https://github.com/geekjourneyx/md2wechat-skill/releases/tag/v3.5.0) · [该版本图片服务配置](https://github.com/geekjourneyx/md2wechat-skill/blob/v3.5.0/docs/IMAGE_PROVISIONERS.md)。

### 使用 Agent 图片计划

v2.8.0 开始，`generate_image`、`generate_cover`、`generate_infographic` 支持 `--plan --json`。

如果当前 Agent 环境有 Image Gen 工具，可以先生成图片计划：

```bash
md2wechat generate_cover --article article.md --plan --json
md2wechat generate_infographic --article article.md --plan --json
md2wechat generate_image "一张适合公众号文章的扁平插画" --plan --json
```

计划模式只返回 prompt 和用途，不请求图片 provider，不上传微信，不要求 `IMAGE_API_KEY`。

典型返回会包含：

```json
{
  "code": "IMAGE_PLAN_READY",
  "status": "action_required",
  "data": {
    "prompt": "Create a WeChat article cover image...",
    "archetype": "cover",
    "primary_use_case": "cover",
    "aspect": "16:9",
    "side_effects": false,
    "requires_provider": false,
    "requires_image_api_key": false,
    "execution_owner": "host_agent"
  }
}
```

Agent 要做的事：

1. 读取 `data.prompt`
2. 确认 `side_effects=false`
3. 用宿主 Image Gen 工具生成图片
4. 保存成明确的本地路径，例如 `/tmp/cover.png`
5. 让用户确认图片
6. 再上传或作为草稿封面

宿主 Agent 生成图片后，再交给 md2wechat：

```bash
md2wechat upload_image /tmp/cover.png --json
md2wechat convert article.md --draft --cover /tmp/cover.png
```

### 怎么选 provider 路径还是计划路径

| 场景 | 选哪条 |
| --- | --- |
| 已配置图片服务和微信凭证 | 直接用 `generate_cover` / `generate_infographic` |
| 当前 Agent 有 Image Gen 工具 | 用 `--plan --json` |
| 不想把图片 key 配进 md2wechat | 用 `--plan --json` |
| 要全自动生成并上传微信图片 | 配置图片服务和微信凭证，不用 plan |
| 只想先看图片提示词 | 用 `--plan --json` |

重要边界：

- `--plan --json` 不会生成图片文件
- `--plan --json` 不会上传到微信
- `--plan --json` 不判断宿主 Agent 是否真的有 Image Gen
- 没有名为 `agent` 的特殊图片 provider
- 在宿主工具完成前，本地不存在 `/tmp/cover.png`

## 微信草稿箱

如果只做本地预览，不需要微信 AppID 和 AppSecret。

如果要推送到公众号草稿箱，必须配置：

- 微信 AppID
- 微信 AppSecret
- 微信 API IP 白名单
- 封面图

配置：

```yaml
wechat:
  appid: "你的公众号 AppID"
  secret: "你的公众号 AppSecret"
```

创建草稿：

```bash
md2wechat inspect article.md --draft --json
md2wechat convert article.md --draft --cover cover.jpg
```

创建草稿前，Agent 应读取：

```text
data.readiness.targets
data.readiness.blockers
```

常见 blocker：

| blocker | 含义 |
| --- | --- |
| `MISSING_API_KEY` | API 模式缺少 `MD2WECHAT_API_KEY` |
| `MISSING_COVER` | 草稿模式缺少 `--cover` 或 `--cover-media-id` |
| `LOCAL_IMAGE_MISSING` | 本地图片路径不存在 |

`doctor --json` 是本地配置体检，`inspect --json` 是单篇文章执行状态。不要混用。

## 微信 IP 白名单

微信会检查调用接口的机器公网 IP。如果公网 IP 不在白名单里，就会报 IP 相关错误。

在哪台机器运行 md2wechat，就查哪台机器的公网 IP。

macOS / Linux：

```bash
curl -s https://ifconfig.me
```

或：

```bash
curl -s https://httpbin.org/ip
```

Windows PowerShell：

```powershell
(Invoke-WebRequest -Uri "https://ifconfig.me" -UseBasicParsing).Content.Trim()
```

把查到的公网 IP 填进微信公众平台后台的 API IP 白名单。

注意：

- 本地内网 IP 不行，比如 `192.168.x.x`、`10.x.x.x`
- 家庭宽带 IP 可能变化
- 服务器和本地电脑不是同一个出口 IP
- GitHub Actions、云函数、公司网络出口 IP 可能不固定
- 重置 AppSecret 后要同步更新本地配置

### 给 Agent 的微信配置话术

```text
帮我配置 md2wechat 的微信公众号草稿箱能力。

我的公众号 AppID 是 xxx。
我的公众号 AppSecret 是 xxx。

请写入 wechat.appid 和 wechat.secret。
然后运行 md2wechat config validate 和 md2wechat doctor --json。

接着帮我查询这台机器的公网 IP，并告诉我应该把哪个 IP 填到微信 API IP 白名单。
不要把 AppSecret 写进文章正文、README、截图或公开仓库。
```

## 多公众号账号

v2.6.0 开始，多公众号使用命名账号。

适合这些场景：

- 同时维护个人号、品牌号、客户号、测试号
- Agent 要明确把草稿发到哪个公众号
- 团队不希望每次改全局 AppID / Secret

配置示例：

```yaml
wechat:
  default_account: main
  accounts:
    main:
      appid: "主公众号 AppID"
      secret: "主公众号 AppSecret"
    client-a:
      appid: "客户 A AppID"
      secret: "客户 A AppSecret"
```

账号名规则：

- 只能使用小写字母、数字、`_`、`-`
- 必须以小写字母或数字开头
- 示例：`main`、`client-a`、`brand_2026`

查看账号：

```bash
md2wechat config wechat-accounts --json
```

这个命令只读取本地配置：

- 不调用 `/api/auth/validate`
- 不要求 `MD2WECHAT_API_KEY`
- 不输出 `secret`

创建草稿时指定账号：

```bash
md2wechat convert article.md --draft --cover cover.jpg --wechat-account client-a
md2wechat upload_image cover.jpg --wechat-account client-a
md2wechat create_image_post --title "标题" --images cover.jpg --wechat-account client-a
```

临时用环境变量选择：

```bash
export WECHAT_ACCOUNT=client-a
md2wechat convert article.md --draft --cover cover.jpg
```

账号选择顺序：

```text
--wechat-account
  -> WECHAT_ACCOUNT
  -> wechat.default_account
  -> 直接配置 wechat.appid / wechat.secret
  -> 唯一的命名账号
  -> WECHAT_ACCOUNT_AMBIGUOUS
```

### 多账号和 API Key 的边界

`api.md2wechat_key` / `MD2WECHAT_API_KEY` 有两类用途：

1. API 模式转换 Markdown 到微信 HTML
2. 命名账号执行微信副作用前，验证你已购买高级 API 服务

命名账号执行这些副作用前会校验 API Key：

- `upload_image`
- `download_and_upload`
- `generate_image`
- `generate_cover`
- `generate_infographic`
- `create_draft`
- `test-draft`
- `convert --upload`
- `convert --draft`
- `create_image_post` 非 dry-run

不会做 live API Key 校验的本地只读命令：

- `config show`
- `config validate`
- `doctor`
- `config wechat-accounts`
- `inspect`

常见错误：

| 错误码 | 常见原因 | 处理方式 |
| --- | --- | --- |
| `WECHAT_ACCOUNT_NOT_FOUND` | 传了不存在的账号 | 运行 `config wechat-accounts --json` 查看账号名 |
| `WECHAT_ACCOUNT_AMBIGUOUS` | 多个账号但没有默认选择 | 设置 `default_account` 或传 `--wechat-account` |
| `WECHAT_ACCOUNT_INVALID` | 账号名格式不合法 | 改成小写字母、数字、`_`、`-` |
| `API_KEY_REQUIRED` | 命名账号副作用缺少 API Key | 配置 `api.md2wechat_key` |
| `API_KEY_INVALID` | API Key 被服务端判定无效 | 检查 key 是否复制完整 |

## 固定出口

v2.7.0 开始，md2wechat 支持微信固定出口代理。

它解决的是微信后台 IP 白名单问题。适合：

- 家庭宽带 IP 经常变化
- 公司网络或 VPN 出口不稳定
- Agent 在云环境、CI、云函数里运行
- 团队希望统一从一个固定出口调用微信接口

开通固定出口能力后，你会拿到：

- 完整的 `proxy_url`
- 需要填写到微信后台 IP 白名单的固定出口 IP

配置文件写法：

```yaml
wechat:
  proxy_url: "https://wechat-egress-url-provided-by-md2wechat.example"
```

或：

```bash
export WECHAT_PROXY_URL="https://wechat-egress-url-provided-by-md2wechat.example"
```

验证配置：

```bash
md2wechat config show --format json
md2wechat doctor --json
```

`config show --format json` 中对应字段是 `wechat_proxy_url`，默认会隐藏代理密码。

### 固定出口只影响什么

固定出口只影响微信侧请求：

- `upload_image`
- `convert --upload`
- `convert --draft`
- `create_image_post`
- `test-draft`

它不会影响：

- API 排版
- 本地预览
- Markdown 转换
- 主题发现
- prompt 发现
- 图片 provider 调用
- 图片计划模式

启用固定出口后，执行微信副作用前需要有效的 `MD2WECHAT_API_KEY`。

微信后台 IP 白名单应填写服务提供的固定出口 IP。不要自己拼代理主机、端口或部署形态，以服务侧给出的完整 URL 为准。

优先使用 `wechat.proxy_url` / `WECHAT_PROXY_URL`，不要用 `HTTPS_PROXY` 代理所有流量，避免把非微信流量一起代理。

## 真实需求怎么拆：微信群留言和配图生成公众号文章

常见需求：

```text
把微信学习群里的学员文字留言和配图自动生成微信公众号文章。
文章不需要复杂创作，主要是梳理语句、审校错别字、基本保留原留言。
关键需求是自动化、文字和图片排版。
```

可以做，但要拆清边界。

md2wechat 负责后半段：

1. 把整理好的 Markdown 转成公众号排版
2. 处理本地图片
3. 生成预览
4. 上传图片
5. 推送公众号草稿箱

它不负责自动读取个人微信群聊天记录。微信群内容采集需要你自己提供来源，比如手动复制、导出记录、表格、企业微信机器人、表单、社群工具或已有系统。

给 Agent 的任务说明：

```text
我会给你一批微信群学员留言和图片路径。

请帮我整理成一篇公众号 Markdown 草稿：
1. 基本保留原留言意思。
2. 只做语句梳理、错别字审校和段落整理。
3. 不要编造学员没说过的话。
4. 图片按留言顺序插入。
5. 生成适合公众号阅读的标题、摘要和小标题。

写完后用 md2wechat inspect 检查，再用 md2wechat preview 生成预览。
不要直接创建草稿，等我确认。
```

## 排查：先跑这 4 个命令

遇到任何问题，先让 Agent 跑：

```bash
md2wechat version --json
md2wechat config show --format json
md2wechat config validate
md2wechat doctor --json
```

这 4 个命令分别回答：

1. CLI 是否安装
2. 实际读的是哪份配置
3. 配置文件格式是否正确
4. 预览、API、layout、图片、微信草稿链路是否可用

不要一上来改配置。先拿诊断信息。

## 快速判断表

| 现象 | 最可能原因 | 先做什么 |
| --- | --- | --- |
| `command not found: md2wechat` | CLI 没装好，或 PATH 没生效 | 重装 npm 包，再开新终端 |
| npm 安装提示 tarball 404 | npm 镜像同步慢或缓存旧 | 切到官方 registry |
| 装了 skill 但 Agent 不能用 | 只装了 skill，没装 CLI | 先装 md2wechat |
| `WECHAT_APPID is required` | 没配置公众号 AppID | 填 `wechat.appid` 和 `wechat.secret` |
| API 模式需要 Key | 没配置 `api.md2wechat_key` | 填 md2wechat API Key |
| 配置改了没生效 | 改错配置文件 | 跑 `config show --format json` |
| 转换结果为空 | 文件路径错，或 Markdown 内容为空 | 确认文件存在且有内容 |
| 中文乱码 | 文件编码不对 | 保存为 UTF-8 |
| AI 模式没有最终 HTML | AI 模式不是最终渲染主路径 | 新手改用 API 模式 |
| `:::module` 原样输出 | 走了 AI 模式，或模块语法错误 | 用 API 模式，跑 `layout validate` |
| 图片没替换成微信 URL | 只预览，没走上传路径 | 创建草稿或显式上传图片 |
| 图片上传失败 | 微信凭证、白名单或图片路径问题 | 先单独测试图片上传 |
| `ip not in whitelist` | 公网 IP 没加进微信白名单 | 查公网 IP，更新白名单 |
| `errcode=45004` | 摘要、标题或微信接口限制 | 先检查 digest 和 metadata |
| 草稿创建失败 | 微信凭证、白名单、封面图任一项不对 | 跑 `doctor --json` 和 `inspect --draft` |

## 常见问题

### 我完全不懂 API 和 CLI，能不能用？

可以用。你不需要自己理解所有命令。

你只要知道：CLI 是本地工具，API 是在线排版服务，Agent 可以帮你执行配置和预览。

第一次建议先让 Agent 帮你跑通 `version`、`config validate`、`preview` 三步，不要一开始就直接发草稿箱。

### 买了 API 下一步做什么？

拿到 API Key 后，先配置 `api.md2wechat_key`。

如果只做排版和预览，先不用配置微信 AppID。

如果要发公众号草稿箱，再配置 `wechat.appid`、`wechat.secret`，并把运行机器的公网 IP 加入微信 API IP 白名单。

### 主题怎么选？

先看主题画廊：

```text
https://www.md2wechat.cn/theme-gallery
```

如果不确定，就让 Agent 执行：

```bash
md2wechat themes list --json
```

然后结合文章类型推荐 3 个主题。不要让 Agent 凭记忆猜主题名。

### 高级排版模块怎么选？

先看高级排版模块：

```text
https://www.md2wechat.cn/features
```

新手不要堆模块。每篇文章只选少数几个模块，让它分别解决开头吸引、阅读清晰、重点记忆和行动引导。

### 图片没有显示或没有上传？

普通预览不会一定替换成微信素材 URL。

图片替换通常发生在上传和草稿路径中：

```bash
md2wechat convert article.md --upload
md2wechat convert article.md --draft --cover cover.jpg
```

### `errcode=45004` 怎么办？

优先检查标题和摘要。

运行：

```bash
md2wechat inspect article.md --draft --json
```

重点看 metadata、digest、title、readiness。很多时候是 digest 过长、字段不合规，或微信接口限制。

## 给用户收集信息的话术

如果用户说“还是不行”，让他发回这些信息：

```text
请把下面信息发我，注意不要发 API Key、AppSecret、token。

1. md2wechat version --json 的输出
2. md2wechat config validate 的输出
3. md2wechat doctor --json 的输出
4. 你执行的完整命令
5. 完整报错信息
6. 你的系统：macOS / Windows / Linux
7. 你是在本机、服务器、CI、云函数还是公司网络里运行
```

## 推荐阅读顺序

第一次使用：

1. 本手册
2. API 文档
3. 主题画廊
4. 高级排版功能页
5. FAQ 和排障

Agent 首次接入：

1. `/docs/md2wechat.md`
2. `/docs/md2wechat/skill.md`
3. `md2wechat version --json`
4. `md2wechat capabilities --json`
5. `md2wechat skills read md2wechat --json`
6. `md2wechat doctor --json`
7. `md2wechat inspect <article.md> --json`

源文档：

- GitHub README：https://github.com/geekjourneyx/md2wechat-skill
- SKILL.md 原文：https://www.md2wechat.cn/docs/md2wechat/skill.md
- 项目文档入口：https://www.md2wechat.cn/docs/md2wechat
- Agent 可读原文：https://www.md2wechat.cn/docs/md2wechat.md

## 给 Agent 的最短提示词

```text
请把这篇 Markdown 处理成公众号稿。

先读取 https://www.md2wechat.cn/docs/md2wechat.md 和 https://www.md2wechat.cn/docs/md2wechat/skill.md。
然后运行：
1. md2wechat version --json
2. md2wechat capabilities --json
3. md2wechat skills read md2wechat --json
4. md2wechat inspect article.md --json
5. md2wechat themes list --json
6. md2wechat layout validate article.md --json
7. md2wechat preview article.md

不要猜主题名，不要直接创建草稿。
只有我明确要求发布草稿时，再使用 --draft，并先检查封面、微信凭证和 readiness blockers。
```


## 多平台未发布草稿

借助具备浏览器能力的 Agent，将符合要求的 Markdown 保存为知乎、CSDN、头条、腾讯云开发者社区未发布草稿，保存后重新打开核对。

需要具备浏览器能力的 Agent，以及用户已登录的目标平台账号。 支持普通 Markdown 与有效本地图片；远程图片、Obsidian 专用语法、原始 HTML 和高级排版块需先处理。 本地准备不需要微信凭证或排版 API Key；准备成功不等于草稿完成。

头条会归一化标题级别；混合多个标题级别时须在写入前停止，经作者同意调整原稿后再继续。特殊字符须逐字符核对。 腾讯云指引从 v3.7.0 起提供。先粘贴正文，再通过编辑器插入本地图片；保存后重新打开同一草稿核对。多图、长文及草稿列表恢复尚未验证。

先运行 `md2wechat capabilities --json`，再运行 `md2wechat sync prepare article.md --output ./article-prepared --json`。输出目录须为新目录且父目录已存在。成功的 SYNC_PREPARED / action_required 只代表本地准备完成。

Agent 应读取 `md2wechat skills read md2wechat references/sync/workflow.md --json`，以及目标平台的 references/sync/zhihu.md、references/sync/csdn.md、references/sync/toutiao.md、references/sync/tencent-cloud.md。通过正常编辑器保存，取得草稿地址后重新打开，核对标题、全文、图片位置及主要结构。中断时恢复同一草稿，不能盲目重复创建。当前不自动公开发布或更新旧文章。

项目记录包含 macOS、Chrome 已登录会话的知乎、CSDN、头条短图文、结构与长文验证。腾讯云已验证短结构正文与单图保存重开；多图、长文及从草稿列表恢复尚未验证。其他系统与 Agent 宿主尚未逐一验收。 企业自用、代运营及客户交付请先确认授权范围。商业授权单独沟通，购买服务不自动包含商业授权。

[完整首篇草稿教程](https://www.md2wechat.cn/docs/multi-platform) · [能力与费用](https://www.md2wechat.cn/multi-platform) · [实测记录](https://github.com/geekjourneyx/md2wechat-skill/blob/v3.7.0/docs/SMOKE.md)


# md2wechat SKILL.md

---
name: md2wechat
description: Convert Markdown to WeChat Official Account HTML. Use this whenever the user wants WeChat article formatting, article preview, WeChat draft upload, image generation for articles, cover or infographic generation, image-post creation, writer-style drafting, title suggestions, AI trace removal, or current discovery of supported providers, themes, prompts, and layout modules. Also use for unpublished Zhihu, CSDN, Toutiao, or Tencent Cloud Developer Community drafts through a browser. Use for product introductions, encyclopedia articles or entry drafts, and writing tailored to platforms or search targets.
---

# md2wechat

Use this skill to operate the `md2wechat` CLI. Keep the skill focused on execution decisions. For full command tutorials, installation details, and FAQ-level explanations, refer users to the project docs instead of expanding this runtime protocol.

## 办公 Agent 如何安装和使用 md2wechat

千问办公、DuMate、WorkBuddy、豆包工作（也常被称为豆包办公）采用同一条使用路径：让 Agent 在当前执行环境安装 md2wechat CLI，再读取操作手册。把下面这段提示词直接发给你的办公 Agent：

```text
帮我安装 md2wechat，执行安装：
npm install -g @geekjourneyx/md2wechat

如果没有初始化配置，请执行初始化配置：
md2wechat config init

已有配置请保留。如果缺少 Node.js 或 npm，请先检查并完成安装。
安装后读取操作手册：https://www.md2wechat.cn/docs/md2wechat/skill
CLI 使用手册：https://www.md2wechat.cn/docs/md2wechat
请检查 md2wechat version --json，告诉我安装结果和下一步需要补充的配置。
```

Agent 需要能执行终端命令并读写文章文件。如果它运行在远程环境或沙箱，安装也应在那个环境完成。初始化配置不会自动开通 API Key；调用排版服务时按手册填写自己的有效密钥。

安装后，把文章交给 Agent：

```text
请使用 md2wechat 为这篇文章排版。
先阅读 https://www.md2wechat.cn/features，了解高级排版模块。
保留原文事实和数据，选择适合内容的模块，不要为了使用模块增加虚构内容。
按 https://www.md2wechat.cn/docs/md2wechat/skill 操作。
将排版后的 Markdown 另存为新文件，生成预览供我检查。
如果缺少配置，请明确告诉我需要补充什么。本次只预览。
```

完整步骤见[办公 Agent 安装与排版教程](/blog/office-agent-md2wechat-install-guide)。高级排版可先看[功能介绍](https://www.md2wechat.cn/features)，再查[网页版文档](https://www.md2wechat.cn/docs)和[高级排版教程](https://mp.weixin.qq.com/s/im5k-SXcoHMA6Kewtnm4Fw)。

## Intent Routing

Choose the command family before taking any publish or generation action:

- Standard article HTML, article preview, metadata inspection, or WeChat article draft: use `inspect`, `preview`, and `convert`.
- Unpublished Zhihu, CSDN, Toutiao, or Tencent Cloud Developer Community draft: run `md2wechat skills read md2wechat references/sync/workflow.md --json` for the current CLI's embedded workflow; the CLI prepares content and the Agent operates the browser.
- Image-first post, image note, image-text note, `newspic`, or multi-image post: use `create_image_post`, not `convert --draft`.
- Article cover or article infographic: prefer `generate_cover` or `generate_infographic` over raw `generate_image` when a bundled preset fits.
- Host-agent image generation request with no provider configured: use image plan mode (`--plan --json`) to get prompt intent, then hand it to the host image-generation tool if one is available outside md2wechat.
- WeChat title candidates for an existing article: use `title suggest <article.md> --json`; it emits a host-Agent AI request and does not choose or write the final title.
- Product introductions, encyclopedia articles or entry drafts, and platform/search-directed writing: read `md2wechat skills read md2wechat references/writing/workflow.md --json` and follow it as the host Agent. Prefer this route over `advise` or `write` for these requests; skip it for formatting-only tasks.
- Existing article or draft, user asks what to improve next: run `md2wechat advise <article.md> --json`; treat it as recommendation-only and keep `inspect --json data.readiness.targets/blockers` as the publish gate.
- Writing in a creator style or removing AI traces: use `write` or `humanize`.
- Provider, theme, prompt, or layout uncertainty: run discovery first. Do not guess from memory or repository files.

Treat `convert --draft` and `create_image_post` as different publish targets, not interchangeable variants.

## Discovery First

Use CLI discovery as the source of truth, but keep it scoped to the next decision. Do not run the full catalog for tasks that do not need provider, theme, prompt, or layout selection.

Use `capabilities` for aggregate routing facts, resource `list` for lightweight selection fields, `show` for one full resource definition, and `render` for materialized prompt/layout output. JSON stdout is compact; use `jq` only when a human needs formatted output.

Run the smallest useful discovery set:

- Article formatting with no theme or modules chosen:
  ```bash
  md2wechat themes list --json
  md2wechat layout list --json
  ```

- A named theme, provider, prompt, or layout module:
  ```bash
  md2wechat themes show <name> --json
  md2wechat providers show <name> --json
  md2wechat prompts show <name> --kind <kind> --json
  md2wechat layout show <name> --json
  ```

- Image generation or image-preset selection:
  ```bash
  md2wechat providers list --json
  md2wechat prompts list --kind image --json
  ```

- Subject-reference (image-to-image) capability before using `--subject-reference`:
  ```bash
  md2wechat providers show minimax --json
  ```
  Read `supports_subject_reference` on the provider and on each entry of `supported_models`. Only the `minimax` provider and its `image-01` model accept `--subject-reference`, and the reference must be a publicly reachable `http(s)` portrait image URL; inline data URLs and local paths are rejected. Unsupported provider/model combinations fail immediately with `CONFIG_INVALID`, so do not retry them as generation failures.

For Atlas Cloud image generation (introduced in v3.5.0), discover `atlascloud` with `providers show atlascloud --json` before configuring it. The aliases `atlas-cloud` and `atlas` select the same provider. Configure `api.image_provider` and the user's Atlas Cloud `api.image_key`; the v3.5.0 defaults are model `openai/gpt-image-2/text-to-image` and size `1024x1024`. Sizes use `WIDTHxHEIGHT`, not aspect-ratio notation. The CLI submits the image task and waits for its result. Image credentials and billing are separate from the Markdown conversion API. Do not claim live authentication or sufficient balance from local configuration checks. Use `--plan --json` when the user wants prompt intent for a host image tool instead of a remote generation request.

- Title suggestion prompt selection:
  ```bash
  md2wechat prompts list --kind title --json
  md2wechat prompts show wechat-title-expert --kind title --json
  ```

- Draft, upload, API local-readiness, or configuration troubleshooting:
  ```bash
  md2wechat doctor --json
  md2wechat config show --format json
  md2wechat config wechat-accounts --json
  ```
  `doctor` readiness is local configuration attemptability. `config wechat-accounts` is local-only and never prints WeChat secrets. Use `inspect --json` for article-specific target readiness.

- Unknown CLI version, changed behavior, or capability uncertainty:
  ```bash
  md2wechat version --json
  md2wechat capabilities --json
  md2wechat skills list --json
  md2wechat skills read md2wechat --json
  ```

`md2wechat skills read md2wechat --json` reads the SOP embedded in the current CLI binary. Prefer it when the installed external skill, README, or repository checkout may be stale relative to the executable on `PATH`.

For simple local actions such as `preview`, `humanize`, or a user-specified command with explicit flags, do not run unrelated provider, theme, prompt, or layout discovery.

Inspect specific resources only when the task needs them:

```bash
md2wechat providers show <name> --json
md2wechat themes show <name> --json
md2wechat prompts show <name> --kind <kind> --json
md2wechat layout show <name> --json
```

Use CLI output as the source of truth for currently available modes, providers, themes, prompts, and layout modules.

## Configuration Boundaries

- Assume `md2wechat` is already available on `PATH`.
- `convert` defaults to API mode unless the user explicitly asks for `--mode ai`.
- API-mode preview and conversion require a valid `MD2WECHAT_API_KEY`.
- WeChat upload, article draft creation, and `create_image_post` require WeChat credentials whenever the user explicitly requests those side effects.
- Read-only discovery, `inspect`, `preview`, and plain conversion are free of any global WeChat publishing credential requirement; API-mode preview and conversion still require a valid `MD2WECHAT_API_KEY`.
- Named WeChat account execution requires a valid `MD2WECHAT_API_KEY`; the CLI validates it before upload, draft, or `create_image_post` effects.
- Direct image generation calls the provider and uploads the result to WeChat material storage; it requires image-provider credentials plus WeChat credentials and the applicable IP allowlist. It returns `data.media_id` and `data.wechat_url`, does not write images into Markdown, and does not create a draft. After user confirmation, use `--cover-media-id` for a generated cover or insert the actual `wechat_url` into the article. Image plan mode (`--plan --json`) only emits prompt intent for a host Agent or external tool and does not require image-provider credentials.
- `title suggest --json` only emits a title-generation prompt request for the host Agent or external model. It does not call a model, upload, create drafts, or write back to Markdown.
- For stronger factual title hooks, pass --hook-level 2 or 3; do not treat generated titles as confirmed publishing intent.
- `doctor --json` is local-only: it checks local readiness and does not perform live authentication, upload images, or create drafts.
- Use `config show --format json` when the user asks what configuration is currently effective.
- Use `config wechat-accounts --json` when the user asks which local WeChat accounts are configured.

## Article Workflow

Prefer a confirm-first workflow for article work:

1. `md2wechat inspect <article.md> --json`
2. `md2wechat preview <article.md>`
3. `md2wechat convert <article.md> ...`
4. Add `--upload`, `--draft`, `--cover`, or `--cover-media-id` only when the user explicitly asks for upload or draft creation.

`inspect` is the source-of-truth command for structured metadata, checks, readiness targets, and blockers. In `--json` output, read `data.readiness.targets` and `data.readiness.blockers` before deciding whether `convert`, `upload`, or `draft` is blocked. If the requested target is blocked, stop and report the matching blockers; do not continue by guessing from legacy booleans or `checks` alone. Do not invent `data.agent_readiness`, `data.target_readiness`, `ArticleState`, state files, or a second readiness/state object. `preview` writes only byte-identical final API HTML from a successful converter result; with `--json`, inspect diagnostics are returned in `data.inspect` and are never wrapped into that file. It does not upload images, create drafts, or write back to Markdown. `convert` performs conversion and only the explicitly requested upload/draft effects. `convert --preview` is the convert-path preview flag and is not the same as the standalone `preview` command. On `PREVIEW_ACTION_REQUIRED` or `PREVIEW_FAILED`, this invocation does not create or overwrite preview HTML. With `--json`, `PREVIEW_ACTION_REQUIRED` returns an empty `data.output_file`. Any pre-existing explicit output path is stale and must not be treated as this invocation's result; use the returned prompt for host-Agent work or report the failure.
When the intended execution path is `convert --mode ai --custom-prompt ...`, run `inspect` with the same `--mode ai --custom-prompt ...` before trusting readiness.

## Formatting Protocol

When the user asks to format an article and has not chosen a theme or modules:

1. Read the article and optional Brand Profile.
2. Use discovery output as facts.
3. Choose a compatible theme and a small set of modules from the article's content goal.
4. Keep the source Markdown read-only.
5. Create a temporary formatted Markdown artifact, for example `/tmp/md2wechat-format/<run-id>/article.formatted.md`.
6. Insert only layout modules whose required fields can be filled correctly.
7. Run `md2wechat layout validate --file <formatted.md> --json`.
8. Pass the formatted Markdown artifact to `convert`.

Saving generated Markdown next to the source file requires explicit user confirmation and must not overwrite the source.

## Theme Selection

- Read `type` and `selectable` from `themes list --json`.
- API mode can use only `type: api` and `selectable: true` themes.
- AI mode can use only `type: ai` and `selectable: true` themes.
- Do not use collection descriptors such as non-selectable theme groups as concrete themes.
- If Brand Profile names a theme, verify it through CLI discovery before using it.
- If a requested theme is invalid or mode-incompatible, stop that path and choose a valid theme or ask the user.

## Layout Modules

Advanced layout modules render only in API mode. AI mode (`--mode ai`) does not parse `:::module` syntax, so advanced layout cards will not render there.

Use this decision frame:

- `attention`: help readers decide whether the article is worth reading.
- `readability`: make mobile reading easier.
- `memorability`: make one judgment, quote, metric, or brand anchor stick.
- `conversion`: help readers save, follow, inquire, share, or buy.

Use CLI discovery as the source of truth for layout syntax instead of memorizing or guessing `body_format` values:

- Inspect the opener, body schema, canonical executable example, and structurally distinct variants with `layout show <name> --json`. Reuse the canonical witness.
- Use `layout render` for structured fields and `--body-file` (or `--body-file -` for stdin) for complex bodies, then validate the generated Markdown.
- Default discovery returns recommended modules. Use `layout list --lifecycle compatibility --json` only for old-content migration. Local validation proves syntax acceptance only; production support is a release-conformance fact.

Default module discipline:

- Do not pile on modules.
- Use at most one hero, one verdict, and one cta unless the user explicitly asks for more.
- Skip modules when the article does not provide enough content to fill them honestly.

### Title and closing contract

Use these modules by reading task, not by visual resemblance:

- `hero: masthead`: masthead opening for a feature, release, or branded column.
- `section-title`: strong section entry. Its variants are exactly `marker`, `divider`, `numbered`, `frame`, `focus`, and `vertical`. Keep ordinary subsections as Markdown headings.
- `part`: ordinary major-section transition.
- `epilogue`: entry into the tail or final judgment. Do not use it for the same transition as `part`.
- `cta`: next action. Choose exactly one intent: `save-follow`, `consult`, or `trial`. Only `trial` accepts and renders up to three `points`; do not add `points` to the other variants.
- `closing`: lightweight thanks, wish, or quiet signature. It has no action role and must not replace `cta`.

Existing basic `symbol` keys include the following. Read `layout show` for the selected module before using a key:

- `spark-solid`
- `spark-outline`
- `diamond-solid`
- `diamond-outline`
- `reference-mark`
- `asterism`
- `double-circle`
- `circle`
- `square-solid`
- `square-outline`
- `star`
- `infinity`

不要直接填写符号、Emoji、HTML、SVG、多字符组合或自行创造的英文别名。系统负责把以上英文键映射为安全的纯文字符号。不要自行发明字段或枚举值；未知值的回退是渲染器的安全行为，不是 Agent 可以依赖的写法。

Before emitting a new module block:

1. Run `md2wechat layout list --json` and confirm the module exists.
2. Run `md2wechat layout show <name> --json` and read `fields`, `body_format`, enums, defaults, ignored fields, and invalid cases.
3. Emit only documented fields and values.
4. Run `md2wechat layout validate --file <formatted.md> --json`.

## API And AI Mode

- API mode is the default and is required for advanced layout modules.
- AI mode is a lighter path and does not render advanced layout modules.
- Do not silently switch from API mode to AI mode after an API failure. That changes the output capability.
- Use AI mode only when the user asks for it or accepts losing advanced layout rendering.
- If an AI-mode conversion completes, it is acceptable to briefly mention that API mode supports advanced layout modules and stronger visual structure.

## Brand Profile

Brand Profile lives at `~/.config/md2wechat/brand.md`.

- It is free-form Markdown, not YAML and not a fixed schema.
- The CLI does not parse it.
- Read it as context for voice, theme preferences, module preferences, CTA preferences, and forbidden expressions.
- Treat quantity preferences as soft constraints.
- Verify any named theme or module through CLI discovery.
- If Brand Profile does not exist, do not block the task. You may mention once that system defaults will be used.
- Create or edit Brand Profile only when the user explicitly asks.

## Publishing Side Effects

Do not create drafts, upload images, publish, or call remote image generation unless the user asks for that action.

Before every explicit WeChat side effect—image upload, article draft creation, or `create_image_post`—require configured WeChat credentials and use the target-matched readiness/preflight path. Discovery and inspection remain non-publishing paths; preview and plain conversion are free of any global WeChat publishing credential requirement, while API mode still requires a valid `MD2WECHAT_API_KEY`.

Before WeChat article draft creation through `convert`:

- Use `inspect --json` and check `data.readiness.targets.draft`; when blocked, read matching `data.readiness.blockers`.
- Draft creation requires a cover via `--cover` or `--cover-media-id`.
- Do not assume a WeChat URL or `mmbiz.qpic.cn` URL can be reused as `thumb_media_id`.
- If draft creation returns `45004`, check digest, summary, and description before assuming the body is too long.

In the WeChat `convert` flow, Markdown images are uploaded or replaced only during `--upload` or `--draft`, not during plain conversion or preview.

## Failure Handling

- Missing or invalid config: run `doctor --json` and `config show --format json`; report `data.overall` plus the blocking `data.readiness.*` item.
- Invalid layout syntax: run `layout validate`, inspect the failing module with `layout show`, fix the generated artifact, then validate again.
- Unknown layout modules warn for forward compatibility; verify typos against `layout list --json`.
- Theme rejection: check `type` and `selectable`, then choose a compatible theme or ask the user.
- AI request or style-writing flows may return a prompt/request rather than final prose or HTML unless the external model step is completed.


## 多平台未发布草稿

借助具备浏览器能力的 Agent，将符合要求的 Markdown 保存为知乎、CSDN、头条、腾讯云开发者社区未发布草稿，保存后重新打开核对。

需要具备浏览器能力的 Agent，以及用户已登录的目标平台账号。 支持普通 Markdown 与有效本地图片；远程图片、Obsidian 专用语法、原始 HTML 和高级排版块需先处理。 本地准备不需要微信凭证或排版 API Key；准备成功不等于草稿完成。

头条会归一化标题级别；混合多个标题级别时须在写入前停止，经作者同意调整原稿后再继续。特殊字符须逐字符核对。 腾讯云指引从 v3.7.0 起提供。先粘贴正文，再通过编辑器插入本地图片；保存后重新打开同一草稿核对。多图、长文及草稿列表恢复尚未验证。

先运行 `md2wechat capabilities --json`，再运行 `md2wechat sync prepare article.md --output ./article-prepared --json`。输出目录须为新目录且父目录已存在。成功的 SYNC_PREPARED / action_required 只代表本地准备完成。

Agent 应读取 `md2wechat skills read md2wechat references/sync/workflow.md --json`，以及目标平台的 references/sync/zhihu.md、references/sync/csdn.md、references/sync/toutiao.md、references/sync/tencent-cloud.md。通过正常编辑器保存，取得草稿地址后重新打开，核对标题、全文、图片位置及主要结构。中断时恢复同一草稿，不能盲目重复创建。当前不自动公开发布或更新旧文章。

项目记录包含 macOS、Chrome 已登录会话的知乎、CSDN、头条短图文、结构与长文验证。腾讯云已验证短结构正文与单图保存重开；多图、长文及从草稿列表恢复尚未验证。其他系统与 Agent 宿主尚未逐一验收。 企业自用、代运营及客户交付请先确认授权范围。商业授权单独沟通，购买服务不自动包含商业授权。

[完整首篇草稿教程](https://www.md2wechat.cn/docs/multi-platform) · [能力与费用](https://www.md2wechat.cn/multi-platform) · [实测记录](https://github.com/geekjourneyx/md2wechat-skill/blob/v3.7.0/docs/SMOKE.md)


# Comparison context

## Agent workflow evidence

URL: https://www.md2wechat.cn/compare#agent-workflows

Checked: 2026-09-08

按固定提交的第一方 README 与技能文档逐项核对，共四个项目、十个维度。文档已记载不代表本次实测；未核实只表示在所列资料范围内证据不足，不表示不支持。未安装或运行对比项目，也未执行其微信发布请求。企业治理按组织权限、审批链与审计留存核对，不以多账号或安全建议替代。

### md2wechat
- 排版: API 模式将 Markdown 转成微信 HTML，并解析高级排版模块。 [documented; 2026-09-08] Source: https://github.com/geekjourneyx/md2wechat-skill/blob/cbc8c600ed1f9cccbc29a33576f657c07d39ba9a/README.md#L78-L104 Limit: API 模式需要配置 Key；AI 模式返回 prompt，需要外部模型继续处理。
- 主题: README 区分 AI 基础主题与 API 专业主题，并提供主题发现命令。 [documented; 2026-09-08] Source: https://github.com/geekjourneyx/md2wechat-skill/blob/cbc8c600ed1f9cccbc29a33576f657c07d39ba9a/README.md#L78-L104 Limit: 主题可用性应以所用版本及服务端结果为准。
- 图片处理: 提供封面、信息图生成及微信图片上传命令。 [documented; 2026-09-08] Source: https://github.com/geekjourneyx/md2wechat-skill/blob/cbc8c600ed1f9cccbc29a33576f657c07d39ba9a/README.md#L149-L184 Limit: 生图依赖已配置的 provider，或宿主实际提供 Image Gen 工具。
- 草稿: convert --draft 显式创建草稿，示例先按同一封面和账号执行 inspect。 [documented; 2026-09-08] Source: https://github.com/geekjourneyx/md2wechat-skill/blob/cbc8c600ed1f9cccbc29a33576f657c07d39ba9a/README.md#L57-L69 Limit: 需要微信凭证、封面及相应微信接口执行条件。
- API: 文档提供专业 API 转换模式，成功时直接返回微信 HTML。 [documented; 2026-09-08] Source: https://github.com/geekjourneyx/md2wechat-skill/blob/cbc8c600ed1f9cccbc29a33576f657c07d39ba9a/README.md#L78-L104 Limit: 此格描述 CLI 对转换服务的使用，不把草稿命令等同于本站转换接口。
- 安装: README 提供 npm 全局安装、版本查询与配置初始化命令。 [documented; 2026-09-08] Source: https://github.com/geekjourneyx/md2wechat-skill/blob/cbc8c600ed1f9cccbc29a33576f657c07d39ba9a/README.md#L44-L53 Limit: 本次未执行安装；操作系统与具体版本要求需查看安装指南。
- discovery: 提供 capabilities、doctor、themes、layout、skills 等 JSON 发现命令。 [documented; 2026-09-08] Source: https://github.com/geekjourneyx/md2wechat-skill/blob/cbc8c600ed1f9cccbc29a33576f657c07d39ba9a/README.md#L114-L145 Limit: 可发现的资源及子命令以当前二进制输出为准。
- 校验: inspect 返回 metadata、checks、readiness 和 blockers，区分检查与发布动作。 [documented; 2026-09-08] Source: https://github.com/geekjourneyx/md2wechat-skill/blob/cbc8c600ed1f9cccbc29a33576f657c07d39ba9a/README.md#L114-L145 Limit: readiness 是发布前条件检查，不能证明实际远端转换或微信草稿请求成功。
- 失败恢复: 故障文档按安装、配置、转换、图片和草稿错误给出排查步骤。 [documented; 2026-09-08] Source: https://github.com/geekjourneyx/md2wechat-skill/blob/cbc8c600ed1f9cccbc29a33576f657c07d39ba9a/docs/TROUBLESHOOTING.md#L1-L16 Limit: 属于排障说明，本次未验证重试结果或重复草稿防护。
- 企业治理证据: 已读 README 描述命名账号与只读发现，未核实组织级权限、审批链和审计留存。 [unknown; 2026-09-08] Source: https://github.com/geekjourneyx/md2wechat-skill/blob/cbc8c600ed1f9cccbc29a33576f657c07d39ba9a/README.md#L28-L40 Limit: 多账号配置和 Secret 隐藏不等同于完整企业治理；未核实不表示不支持。

### gzh-design-skill
- 排版: 按主题组件库把 Markdown 装配为内联样式 HTML，并提供复制预览页。 [documented; 2026-09-08] Source: https://github.com/isjiamu/gzh-design-skill/blob/ba1f4175519b481cb3566616c9e5178705067904/README.md#L25-L34 Limit: 需要 Agent 执行工作流；文档说明的粘贴效果未在本次实测。
- 主题: README 列出六套主题及根据描述或参考图生成本地主题的流程。 [documented; 2026-09-08] Source: https://github.com/isjiamu/gzh-design-skill/blob/ba1f4175519b481cb3566616c9e5178705067904/README.md#L194-L202 Limit: 自定义主题仍需生成、登记和组件校验。
- 图片处理: 文档覆盖图片、GIF 角标和代码块等通用组件。 [documented; 2026-09-08] Source: https://github.com/isjiamu/gzh-design-skill/blob/ba1f4175519b481cb3566616c9e5178705067904/README.md#L25-L34 Limit: 这里核实的是图片排版，未核实图片生成或微信素材上传。
- 草稿: 已读流程以 HTML 预览、复制并手动粘贴公众号编辑器为交付方式。 [unknown; 2026-09-08] Source: https://github.com/isjiamu/gzh-design-skill/blob/ba1f4175519b481cb3566616c9e5178705067904/README.md#L127-L134 Limit: 未在已读 README / SKILL.md 核实自动创建微信草稿；未核实不表示不支持。
- API: 未在已读 README / SKILL.md 核实对外 HTTP 转换或发布 API。 [unknown; 2026-09-08] Source: https://github.com/isjiamu/gzh-design-skill/blob/ba1f4175519b481cb3566616c9e5178705067904/README.md#L161-L180 Limit: 文件与脚本工作流不等于 HTTP 服务；未核实不表示不支持。
- 安装: 提供 npx skills add 和手动 clone 两种安装路径。 [documented; 2026-09-08] Source: https://github.com/isjiamu/gzh-design-skill/blob/ba1f4175519b481cb3566616c9e5178705067904/README.md#L93-L117 Limit: 本次未执行安装，也未验证各 Agent 的加载行为。
- discovery: SKILL.md 是 Agent 入口，references/theme-index.md 是主题索引。 [documented; 2026-09-08] Source: https://github.com/isjiamu/gzh-design-skill/blob/ba1f4175519b481cb3566616c9e5178705067904/README.md#L161-L180 Limit: 这是文档与文件发现；未核实统一 JSON capabilities 契约。
- 校验: 提供 component_lint.py 与 validate_gzh_html.py 两级检查。 [documented; 2026-09-08] Source: https://github.com/isjiamu/gzh-design-skill/blob/ba1f4175519b481cb3566616c9e5178705067904/README.md#L140-L151 Limit: 脚本通过不等于公众号编辑器最终表现已获实测。
- 失败恢复: FAQ 要求 HTML 报错后回到装配步骤修复，两关通过后交付。 [documented; 2026-09-08] Source: https://github.com/isjiamu/gzh-design-skill/blob/ba1f4175519b481cb3566616c9e5178705067904/README.md#L254-L258 Limit: 这是排版修复循环，未核实任务断点恢复或发布重试。
- 企业治理证据: 未在已读 README / SKILL.md 核实组织权限、审批或审计留存。 [unknown; 2026-09-08] Source: https://github.com/isjiamu/gzh-design-skill/blob/ba1f4175519b481cb3566616c9e5178705067904/README.md#L161-L180 Limit: 主题复用与质量校验不构成完整企业治理；未核实不表示不支持。

### WeWrite
- 排版: preview / publish 提供 Markdown 排版，并列出微信兼容修复和容器组件。 [documented; 2026-09-08] Source: https://github.com/imraywang/wewrite/blob/a363da0d92d30fc442aba6549d1a8824ebb0c115/README.md#L230-L289 Limit: 文档中的兼容效果未在本次公众号编辑器实测。
- 主题: 提供 themes、gallery 及从文章 URL 学习排版主题的命令。 [documented; 2026-09-08] Source: https://github.com/imraywang/wewrite/blob/a363da0d92d30fc442aba6549d1a8824ebb0c115/README.md#L230-L248 Limit: 自定义主题在本地加载；学习结果未在本次验证。
- 图片处理: image-gen 生成封面或必要配图，并在生成前检查数量及预估费用。 [documented; 2026-09-08] Source: https://github.com/imraywang/wewrite/blob/a363da0d92d30fc442aba6549d1a8824ebb0c115/README.md#L169-L192 Limit: 生图需要图片服务配置；缺少服务时文档说明可输出提示词。
- 草稿: publish 通过封面与标题参数推送公众号草稿；工作流要求明确授权。 [documented; 2026-09-08] Source: https://github.com/imraywang/wewrite/blob/a363da0d92d30fc442aba6549d1a8824ebb0c115/README.md#L291-L313 Limit: 需要微信 appid / secret 等执行条件；本次未创建草稿。
- API: README 说明 CLI 调用微信 API 发布，并调用数据分析 API 回填阅读数据。 [documented; 2026-09-08] Source: https://github.com/imraywang/wewrite/blob/a363da0d92d30fc442aba6549d1a8824ebb0c115/README.md#L169-L192 Limit: 核实的是调用外部 API，未核实自身对外托管 HTTP API。
- 安装: install.sh 安装 CLI 并链接 Skills；也支持 skills.sh 与独立 CLI 安装。 [documented; 2026-09-08] Source: https://github.com/imraywang/wewrite/blob/a363da0d92d30fc442aba6549d1a8824ebb0c115/README.md#L71-L88 Limit: 本次未执行安装或验证平台检测与迁移结果。
- discovery: 提供 themes、diagnose、home 及 run 子命令，并列出独立 Skill 路由。 [documented; 2026-09-08] Source: https://github.com/imraywang/wewrite/blob/a363da0d92d30fc442aba6549d1a8824ebb0c115/README.md#L291-L313 Limit: 未核实统一 JSON capabilities 清单，不将 CLI 列表等同于该契约。
- 校验: validate 检查微信 HTML；preview / publish 自动运行该校验。 [documented; 2026-09-08] Source: https://github.com/imraywang/wewrite/blob/a363da0d92d30fc442aba6549d1a8824ebb0c115/README.md#L248-L248 Limit: 这与内容评审是不同检查，也不能替代编辑器实测。
- 失败恢复: 文章使用独立任务目录，run 提供 resume，README 说明可恢复进度。 [documented; 2026-09-08] Source: https://github.com/imraywang/wewrite/blob/a363da0d92d30fc442aba6549d1a8824ebb0c115/README.md#L139-L155 Limit: 本次未中断任务验证恢复，也未验证发布失败后的幂等性。
- 企业治理证据: README 描述来源账本、编辑报告、任务状态与发布授权，未核实组织级治理。 [unknown; 2026-09-08] Source: https://github.com/imraywang/wewrite/blob/a363da0d92d30fc442aba6549d1a8824ebb0c115/README.md#L216-L227 Limit: 这些追溯和授权机制不能证明 RBAC、审批链或组织审计留存；未核实不表示不支持。

### workbuddy-wechat-publisher
- 排版: HTML formatter 子技能将 Markdown 转为可粘贴的公众号 HTML。 [documented; 2026-09-08] Source: https://github.com/cnproduct/workbuddy-wechat-publisher/blob/c413c40fb5ab9391b346a8e378cb9601941d3d43/README.md#L48-L54 Limit: 这是 README 的能力说明，未实测生成质量与微信兼容性。
- 主题: README 列出科技蓝、活力橙、清新绿三种主题配色。 [documented; 2026-09-08] Source: https://github.com/cnproduct/workbuddy-wechat-publisher/blob/c413c40fb5ab9391b346a8e378cb9601941d3d43/README.md#L186-L203 Limit: 配色列举不等于独立组件主题系统；文档指向修改 CSS 自定义。
- 图片处理: README 描述生图 API 与图库匹配两条配图路径。 [documented; 2026-09-08] Source: https://github.com/cnproduct/workbuddy-wechat-publisher/blob/c413c40fb5ab9391b346a8e378cb9601941d3d43/README.md#L205-L211 Limit: 未验证所列服务的连接、权限或实际生成结果。
- 草稿: draft publisher 子技能调用微信接口写入草稿箱。 [documented; 2026-09-08] Source: https://github.com/cnproduct/workbuddy-wechat-publisher/blob/c413c40fb5ab9391b346a8e378cb9601941d3d43/README.md#L56-L74 Limit: 需要 AppID、AppSecret、白名单及草稿权限；未验证返回预览链接可用性。
- API: 草稿子技能文档列出微信 token 获取和 draft/add 接口调用。 [documented; 2026-09-08] Source: https://github.com/cnproduct/workbuddy-wechat-publisher/blob/c413c40fb5ab9391b346a8e378cb9601941d3d43/skills/wechat-draft-publisher/SKILL.md#L38-L64 Limit: 这是微信 API 客户端流程，未核实自身对外 HTTP 服务。
- 安装: README 要求安装 Python requests 并复制配置模板填写微信参数。 [documented; 2026-09-08] Source: https://github.com/cnproduct/workbuddy-wechat-publisher/blob/c413c40fb5ab9391b346a8e378cb9601941d3d43/README.md#L64-L96 Limit: 已读快速开始未形成跨 Agent 安装验证记录，本次未安装。
- discovery: README 按触发词列出四个子技能及输入输出，主 SKILL.md 负责编排。 [documented; 2026-09-08] Source: https://github.com/cnproduct/workbuddy-wechat-publisher/blob/c413c40fb5ab9391b346a8e378cb9601941d3d43/README.md#L9-L62 Limit: 这是文本路由说明；未核实机器可读 capabilities 或 schema。
- 校验: 未在已读 README、主技能和草稿技能中核实独立的发布前校验命令。 [unknown; 2026-09-08] Source: https://github.com/cnproduct/workbuddy-wechat-publisher/blob/c413c40fb5ab9391b346a8e378cb9601941d3d43/skills/wechat-draft-publisher/SKILL.md#L116-L149 Limit: API 参数错误说明不等于完整 readiness 校验；未核实不表示不支持。
- 失败恢复: 草稿技能文档描述 token 刷新、限流指数退避和网络重试。 [documented; 2026-09-08] Source: https://github.com/cnproduct/workbuddy-wechat-publisher/blob/c413c40fb5ab9391b346a8e378cb9601941d3d43/skills/wechat-draft-publisher/SKILL.md#L124-L149 Limit: 仅按文档记载；未运行脚本核实重试实现或重复草稿防护。
- 企业治理证据: 草稿技能提供密钥保护、环境变量、token 缓存与 HTTPS 建议。 [unknown; 2026-09-08] Source: https://github.com/cnproduct/workbuddy-wechat-publisher/blob/c413c40fb5ab9391b346a8e378cb9601941d3d43/skills/wechat-draft-publisher/SKILL.md#L195-L200 Limit: 未核实组织权限、审批链和审计留存；安全建议不等同于完整企业治理。

## wechat sync 怎么选：文章同步助手与 md2wechat 的 Agent 工作流对比

URL: https://www.md2wechat.cn/compare/md2wechat-vs-wechatsync

比较 Wechatsync（文章同步助手）与 md2wechat 的平台范围、浏览器执行方式、草稿核对和费用边界，附可在 Codex 中复现的任务示例。

### When md2wechat fits
- 在 Agent 中处理本地 Markdown，逐平台保存和核对草稿

### When Wechatsync（文章同步助手） fits
- 优先需要广泛的平台覆盖与浏览器扩展同步

### Comparison rows
- 目标平台: md2wechat=本页所核对的 v3.6.0 多平台草稿步骤覆盖知乎、CSDN、头条。当前版本的平台范围见多平台草稿页。; Wechatsync（文章同步助手）=官网列出 29+ 平台，适合先按平台覆盖筛选。不同平台仍需核对实际能力。
- Agent 如何执行: md2wechat=本地准备后，由宿主 Agent 用浏览器正常上传、粘贴、保存和重开检查。; Wechatsync（文章同步助手）=CLI 通过 WebSocket 连接 Chrome 扩展，再由扩展调用平台接口；CLI 仍需要扩展。
- AI 接入入口: md2wechat=命令返回结构化结果及下一步说明，Agent 读取当前程序内置操作步骤，再执行浏览器任务。; Wechatsync（文章同步助手）=提供 CLI、MCP、Skill 与 OpenClaw 接入，可接入已有 AI 工作流。
- 完成边界: md2wechat=仅处理未发布草稿；重开后核对标题、全文、图片位置和主要结构才算完成。; Wechatsync（文章同步助手）=官网说明保存到草稿，用户检查后再发布，不会自动公开发布。
- 成本与许可: md2wechat=sync prepare 不要求微信凭证或排版 API Key；商业使用条件须另行确认。; Wechatsync（文章同步助手）=官网将文章同步助手列为免费工具。外部 Agent 或模型的成本需另算。

## md2wechat vs Doocs：微信 Markdown 编辑器怎么选

URL: https://www.md2wechat.cn/compare/md2wechat-vs-doocs

对比 md2wechat 和 Doocs 微信 Markdown 编辑器的适用场景：在线排版、主题预览、API 转换、md2wechat CLI、公众号排版 Skill 和 Agent 发布工作流。

### When md2wechat fits
- 希望把 Markdown 写作接入 CLI、API 或 Agent 发布流程
- 需要标题建议、图片计划、主题发现、微信兼容检查和草稿箱工作流
- 想让 Claude Code、Codex、OpenClaw 或自建 Agent 读取文档后自动执行

### When Doocs fits
- 只需要一个轻量在线 Markdown 编辑器
- 主要工作是手动复制到公众号后台
- 偏好开源社区维护的简洁编辑体验

### Comparison rows
- 核心定位: md2wechat=微信 Markdown 编辑器 + 公众号排版 CLI + Agent 发布入口; Doocs=简洁的微信 Markdown 在线编辑器
- Agent 友好: md2wechat=提供文档中心、Markdown 手册、SKILL.md 和 llms.txt; Doocs=更适合人工打开网页使用
- 自动化: md2wechat=支持 /api/convert、CLI 工作流和发布前检查; Doocs=以网页编辑和复制为主
- 内容表达: md2wechat=覆盖主题、模块、信息卡、CTA、图片计划和标题建议; Doocs=重点在 Markdown 到微信样式的基础转换

## md2wechat vs Markdown Nice：公众号排版工具怎么选

URL: https://www.md2wechat.cn/compare/md2wechat-vs-markdown-nice

对比 md2wechat 和 Markdown Nice / 墨滴社区的公众号排版场景，说明什么时候用在线排版工具，什么时候用 md2wechat CLI、Skill、API 和 Agent 发布链路。

### When md2wechat fits
- 需要把公众号排版接入自动化脚本、团队流程或 Agent
- 希望文章从 Markdown 到预览、转换、图片、标题和草稿箱有固定检查顺序
- 需要用 API 把 Markdown 稳定转成微信可用 HTML

### When Markdown Nice fits
- 喜欢社区化的在线编辑体验
- 文章主要由人工手动排版和复制
- 需要更轻的网页端写作入口

### Comparison rows
- 使用方式: md2wechat=网页、API、CLI、Skill 和 Agent 手册一起使用; Markdown Nice=网页编辑和社区内容为主
- 发布链路: md2wechat=覆盖 Markdown 写作、微信 HTML 转换和草稿发布协作; Markdown Nice=面向文章排版和复制
- 开发者接入: md2wechat=稳定接口为 POST /api/convert，也提供 CLI 文档; Markdown Nice=更偏普通创作者在线使用
- GEO 可读性: md2wechat=提供 /llms.txt、/docs/md2wechat.md 和 /docs/md2wechat/skill.md; Markdown Nice=主要依赖网页内容被搜索引擎理解

## md2wechat vs 秀米/135：公众号排版工具和 Agent 发布 CLI 怎么选

URL: https://www.md2wechat.cn/compare/md2wechat-vs-xiumi-135

对比 md2wechat 与秀米、135 编辑器的公众号排版差异：模板编辑、AI 排版、Markdown 工作流、公众号排版 CLI、Skill 和 Agent 发布。

### When md2wechat fits
- 内容来自 Markdown、Obsidian、代码仓库、Agent 或自动化流程
- 团队希望沉淀一套可复用、可检查、可脚本化的公众号发布方式
- 需要让 Agent 自动理解结构、选主题、出图片计划、生成预览并转换 HTML

### When 秀米 / 135 编辑器 fits
- 运营同学需要大量模板、素材库和拖拽式图文编辑
- 主要做活动页、营销海报、图文视觉装修
- 团队已经围绕传统公众号编辑器形成固定流程

### Comparison rows
- 内容来源: md2wechat=Markdown 文件、CLI、API、Agent 生成内容; 秀米 / 135 编辑器=运营人员在网页编辑器中组织图文素材
- 工作流: md2wechat=写作、检查、预览、转换和草稿箱工作流; 秀米 / 135 编辑器=模板、素材、拖拽编辑和公众号运营工具
- 适合人群: md2wechat=开发者、知识工作者、AI Agent 用户、内容自动化团队; 秀米 / 135 编辑器=新媒体运营、设计运营、活动页和模板化图文团队
- 推荐组合: md2wechat=用作 Markdown 和 Agent 发布底座; 秀米 / 135 编辑器=用作素材和视觉模板补充

# Tutorial index

- [md2wechat 3.7.0：定向写作指引与腾讯云草稿](https://www.md2wechat.cn/blog/md2wechat-3-7-directed-writing-tencent-cloud): Agent 读取内置写作指引，按资料与体裁准备内容；腾讯云草稿采用独立的图片步骤。
- [用 md2wechat 准备产品介绍、平台文章与百科草稿](https://www.md2wechat.cn/blog/md2wechat-directed-writing-guide): 先明确要交付的文章，再提供可核对的资料。附产品介绍、平台教程和百科词条草稿的任务示例。
- [办公 Agent 如何使用 md2wechat：千问办公、DuMate、WorkBuddy、豆包工作安装与排版教程](https://www.md2wechat.cn/blog/office-agent-md2wechat-install-guide): 四种办公 Agent，同一套安装方式。复制提示词，从安装、配置到公众号高级排版逐步开始。
- [md2wechat 3.6.0：把 Markdown 保存为知乎、CSDN、头条草稿](https://www.md2wechat.cn/blog/md2wechat-3-6-multi-platform-drafts): 公众号排版之外，新增三平台未发布草稿流程。先准备普通 Markdown，再逐平台保存并核对。
- [MD2WeChat Publisher 2.0：在 Obsidian 预览排版、确认公众号草稿](https://www.md2wechat.cn/blog/obsidian-publisher-2-0-release): 文章仍在笔记库里写，排版在笔记旁检查。2.0 把预览、刷新和草稿确认放进同一套 Obsidian 操作流程。
- [md2wechat-skill 2026 年 6 月更新总览：v2.5.0 到 v2.9.0 改了什么](https://www.md2wechat.cn/blog/md2wechat-skill-june-2026-release-guide): 6 月的更新集中在 Agent 发布链路：主题发现、当前版本 SOP、多公众号账号、微信固定出口、图片计划和标题建议都变成可发现、可检查的步骤。
- [公众号高密度内容怎么排？callout、quote-card、stat-row 使用指南](https://www.md2wechat.cn/blog/wechat-callout-quote-card-stat-row-guide): 如果正文信息很多，但读者看完记不住重点，先不要继续加大标题。callout、quote-card、stat-row 更适合把提醒、判断和关键数字变成清楚的阅读停顿点。
- [术语、社交证明和问答怎么排？definition、tweet、question 三个模块的用法](https://www.md2wechat.cn/blog/wechat-definition-tweet-question-guide): 术语解释、用户反馈和常见问题，本质上都在降低理解成本。definition、tweet、question 适合把这些内容从正文里拎出来，让读者更快建立信任。
- [选型、更新日志和资源合集怎么排？comparison-table、changelog、resource-list 用法](https://www.md2wechat.cn/blog/wechat-comparison-changelog-resource-list-guide): 产品文章最容易写散：一会儿讲对比，一会儿讲更新，一会儿丢链接。comparison-table、changelog、resource-list 能把这三类信息整理成读者可收藏的结构。
- [自由布局模块怎么用？split、flow、matrix、dialogue-pair 的最新推荐语法](https://www.md2wechat.cn/blog/wechat-split-flow-matrix-dialogue-pair-guide): 自由布局用来处理复杂内容。split 负责左右信息，flow 负责短流程，matrix 负责多方案对比，dialogue-pair 负责双人视角。
- [infographic 变体怎么选：主判断、公式、诊断和路径卡指南](https://www.md2wechat.cn/blog/wechat-infographic-variants-commercial-guide): 信息卡的价值在于让读者记住一个判断。infographic 的不同变体，分别服务于主判断、方法公式、问题诊断、行动路径和方案对比。
- [开头和结尾怎么更能转化？hero、summary、cta 多变体组合指南](https://www.md2wechat.cn/blog/wechat-hero-summary-cta-variants-guide): 公众号排版要让读者先判断、再记住、最后行动。hero、summary、cta 是最直接影响阅读完成和转化的三个模块。
- [md2wechat-skill v2.4.0 更新解读：Agent readiness 为什么重要](https://www.md2wechat.cn/blog/md2wechat-skill-v2-4-readiness-guide): Agent 自动发布公众号文章时，最怕不知道现在能不能执行下一步。v2.4.0 的 readiness 合约，让 Agent 可以先判断目标状态，再决定发布、降级或追问。
- [Agent 写公众号前应该先检查什么？doctor、layout validate、inspect 的正确顺序](https://www.md2wechat.cn/blog/md2wechat-doctor-layout-validate-agent-workflow): 稳定的 Agent 工作流，不应该一上来就发草稿。更好的顺序是先 doctor 看环境，再 layout validate 看模块语法，再 inspect 判断发布就绪状态。
- [Agent 怎么选公众号主题？themes list/show、48 个专业主题和 API 兼容边界](https://www.md2wechat.cn/blog/md2wechat-theme-discovery-agent-guide): Agent 选主题要先看当前 CLI 能发现什么。themes list/show 的价值，是让主题选择从猜测变成可验证的发现动作。
- [从 v2.1.0 到 v2.9.0：md2wechat-skill 的 Agent 发布链路怎么成型](https://www.md2wechat.cn/blog/md2wechat-release-history-layout-agent-map): 从高级模块到 readiness，再到多账号、固定出口、图片计划和标题建议，md2wechat-skill 的更新主线越来越清楚：让 Agent 能稳地把文章推进到可发布状态。
- [md2wechat：面向 Agent 的公众号发布引擎](https://www.md2wechat.cn/blog/md2wechat-agent-publishing-engine): 从草稿整理、字段校验、主题渲染到人工确认，逐步说明 md2wechat 在 Agent 发布流程中的职责。
- [如何让 Agent 整理公众号草稿，同时保留作者语气](https://www.md2wechat.cn/blog/agent-wechat-article-upgrade-workflow): 一份清楚的任务说明，应告诉 Agent 哪些内容可以调整、哪些判断必须保留，以及输出如何进入 md2wechat。
- [从草稿到公众号预览：Agent 与 md2wechat 的协作流程](https://www.md2wechat.cn/blog/wechat-draft-to-publishable-article-30min): 把内容整理、排版转换和发布确认拆成独立步骤，便于定位问题，也便于决定何时接入 API 或 CLI。
- [网页排版与 md2wechat Agent 工作流有什么区别](https://www.md2wechat.cn/blog/md2wechat-vs-free-markdown-tools): 免费排版工具适合文章写完后的样式处理，但 md2wechat 更适合把草稿、选题和提纲推进成高级公众号稿，并接入 API 或 CLI 发布工作流。