md2wechat CLI 使用手册

# 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)