# WeChat Official Account Draft Pipeline 配置清单

测试日期：2026-04-17  
文档版本：v1.0.0

这份清单的目标是：**别人拿到 skill 后，按清单一步步配置，就能快速在 Codex 里跑起来。**

## 一句话最低要求

别人只要配置下面这几项，就能把整条链条跑起来：

- `GROK_BASE_URL`
- `GROK_API_KEY`
- 微信凭证（任选一种）：
  - `WECHAT_APPID + WECHAT_APPSECRET`
  - 或 `WECHAT_ACCESS_TOKEN`
  - 或 `wechat-account-config.json`

## 一、拿到 skill 后先检查目录

目标目录建议：

```bash
~/.codex/skills/wechat-official-account-draft-pipeline
```

至少应包含：

- `SKILL.md`
- `SETUP-CHECKLIST.md`
- `examples/wechat-account-config.example.json`
- `references/fixed-assets-manifest.md`
- `scripts/`

## 二、安装本地依赖

### Node

要求：

- Node.js 18+

检查：

```bash
node --version
```

### Python

要求：

- Python 3.10+

检查：

```bash
python3 --version
```

安装 Python 依赖：

```bash
python3 -m pip install markdown beautifulsoup4 lxml
```

## 三、配置微信公众号凭证

推荐两种方式。

### 方式 A：最简单，直接环境变量

```bash
export WECHAT_APPID="wx1234567890"
export WECHAT_APPSECRET="your-app-secret"
```

或：

```bash
export WECHAT_ACCESS_TOKEN="your-access-token"
```

### 方式 B：推荐分享给团队，使用 account-config

复制样例：

```bash
cp ~/.codex/skills/wechat-official-account-draft-pipeline/examples/wechat-account-config.example.json \
   ./wechat-account-config.json
```

然后修改：

- `default_account`
- `accounts.main.appid_env`
- `accounts.main.appsecret_env`

再把真实凭证放到环境变量：

```bash
export WECHAT_APPID_MAIN="wx1234567890"
export WECHAT_APPSECRET_MAIN="your-app-secret"
```

如果你有多个公众号，就继续在 `accounts` 里加：

- `main`
- `finance`
- `brand`

## 四、配置 Grok

这是让“自动出图 + 发布链路”跑起来的最短配置。

### 方式 A：直接环境变量

```bash
# GROK_BASE_URL 必须填写 OpenAI-compatible 的 /v1 基地址
# 已验证样例：https://grok74.tap365.org/v1
export GROK_BASE_URL="https://your-grok-compatible-endpoint/v1"
# GROK_API_KEY 填你这套 Grok 服务对应的 Bearer key
export GROK_API_KEY="sk-xxx"
```

可选：

```bash
export GROK_IMAGE_MODEL="grok-imagine-1.0"
export GROK_CLI_BIN="grok-cli"
```

### 方式 B：命令行临时传入

```bash
node ~/.codex/skills/wechat-official-account-draft-pipeline/scripts/grok-assets-from-manifest.mjs \
  --manifest ./article-assets.json \
  --base-url https://your-grok-compatible-endpoint/v1 \
  --api-key sk-xxx
```

默认推荐还是**环境变量方式**，这样别人只配一次，后面整条链都能复用。

## 五、准备 manifest

参考：

- `references/fixed-assets-manifest.md`

要求至少包含：

- `article`
- `platform = "wechat"`
- `assets`

并为图片设置：

- `key`
- `role`
- `required`
- `local_path`

## 六、先跑最小验收

### 1）manifest 校验

```bash
node ~/.codex/skills/wechat-official-account-draft-pipeline/scripts/validate-assets-manifest.mjs \
  --manifest ./article-assets.json
```

### 2）上传素材

```bash
node ~/.codex/skills/wechat-official-account-draft-pipeline/scripts/wechat-upload-assets-from-manifest.mjs \
  --manifest ./article-assets.json \
  --account main \
  --account-config ./wechat-account-config.json \
  --json
```

### 3）渲染 HTML

```bash
python3 ~/.codex/skills/wechat-official-account-draft-pipeline/scripts/render-normal-wechat-article.py \
  --markdown ./article.md \
  --manifest ./article-assets.json \
  --output ./article-final.html
```

### 4）写入草稿箱

```bash
node ~/.codex/skills/wechat-official-account-draft-pipeline/scripts/wechat-draft-api.mjs \
  --manifest ./article-assets.json \
  --html ./article-final.html \
  --title "你的标题" \
  --account main \
  --account-config ./wechat-account-config.json \
  --json
```

### 5）如果要自动出图，再跑一条 Grok 验证

```bash
node ~/.codex/skills/wechat-official-account-draft-pipeline/scripts/grok-assets-from-manifest.mjs \
  --manifest ./article-assets.json
```

### 6）整链串起来

```bash
node ~/.codex/skills/wechat-official-account-draft-pipeline/scripts/publish-draft-from-manifest.mjs \
  --manifest ./article-assets.json \
  --html ./article-final.html \
  --title "你的标题" \
  --account main \
  --account-config ./wechat-account-config.json \
  --auto-grok
```

## 七、可选：启用 inline 渲染增强链路

如果你要用：

- `scripts/render-wechat-inline-html.py`

则还需要提供一个 `md-to-wechat.ts`：

### 方案 A：直接指定环境变量

```bash
export WECHAT_MD_TO_WECHAT_PATH="/absolute/path/to/md-to-wechat.ts"
```

### 方案 B：放到 skill 内

```bash
~/.codex/skills/wechat-official-account-draft-pipeline/scripts/vendor/md-to-wechat.ts
```

这个链路属于**增强项**，不是默认必需项。

## 八、已内置的稳态行为

拿到 skill 后，默认已经有这些行为：

- `draft/update` 命中 `invalid media_id`
- 自动 fallback 到 `draft/add`
- 封面 / 固定头图 / 固定尾图 / 正文图都能走 manifest
- 正文字号默认已下调到更稳的阅读尺寸
- Grok 默认可直接读取 `GROK_BASE_URL` / `GROK_API_KEY`

## 九、最容易踩坑的地方

- 只给了 `--account`，却没给 `--account-config`
- 配了 `account-config`，但没导出对应 env
- 忘了配置 `GROK_BASE_URL` / `GROK_API_KEY`，却直接开 `--auto-grok`
- manifest 里图片路径写错
- 直接发 HTML，但 manifest 没先回填 `wechat_url`
- 把 `render-wechat-inline-html.py` 当默认主链，但没配置 `md-to-wechat.ts`

## 十、给别人时怎么说最省事

直接把这三句话发给他：

1. 先装 Node 18+ 和 Python 依赖
2. 配好 `GROK_BASE_URL`、`GROK_API_KEY` 和微信凭证
3. 按 `SETUP-CHECKLIST.md` 里的命令从 manifest 校验一路跑到草稿箱