# md2wechat 接入手册

更新时间：2026-06-27

这是一份给人和 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

## 先用一句话解释 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 |
| 生成封面图 | 配置图片 provider，或用图片计划模式 | 不要把图片 Key 写进正文 |
| 让 Agent 接管 | 先跑 discovery 和 doctor | 不要让 Agent 凭记忆猜主题 |

## 安装：只推荐 npm 主路径

当前 README 的快速开始主路径是 npm：

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

安装后验证：

```bash
md2wechat version --json
md2wechat --help
md2wechat capabilities --json
```

如果命令不存在：

```bash
command -v md2wechat
npm config get registry
```

如果 npm 走的是镜像源，并遇到新版本 tarball 404，改用官方源：

```bash
npm install -g @geekjourneyx/md2wechat --registry=https://registry.npmjs.org/
```

安装细节以 GitHub README 为准：

```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`、`verdict`、`toc` |
| 步骤更清楚 | `steps`、`timeline`、`checklist` |
| 对比更清楚 | `comparison-table`、`pros-cons`、`matrix` |
| 观点更突出 | `quote`、`callout`、`summary` |
| 数据更好看 | `metrics`、`stat-row`、`infographic` |
| 引导关注或咨询 | `cta`、`subscribe`、`faq` |

给 Agent 的话术：

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

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

不要堆模块。选完以后说明为什么。
写完后运行 md2wechat layout validate article.md --json。
```

常用命令：

```bash
md2wechat layout list --json
md2wechat layout show hero --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 时先解释问题和下一步

## 标题建议

v2.9.0 支持：

```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 推荐后再确认

## 图片和封面

公众号草稿必须有封面图。图片有两条路径。

### 直接配置图片 provider

国内用户可以优先考虑火山引擎豆包图片模型。

配置示例：

```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
```

### 使用 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 路径还是计划路径

| 场景 | 选哪条 |
| --- | --- |
| 已经配置图片 provider key | 直接用 `generate_cover` / `generate_infographic` |
| 当前 Agent 有 Image Gen 工具 | 用 `--plan --json` |
| 不想把图片 key 配进 md2wechat | 用 `--plan --json` |
| 要全自动 CLI 生成图片 | 配 provider，不用 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。
```