---
name: wechat-official-account-draft-pipeline
description: |
  发布微信公众号草稿箱的通用 skill。适用于：需要把 Markdown/HTML 文章做成稳定版式、锁封面/正文图/固定头尾图、上传微信素材、写入草稿箱、或维护 manifest 驱动的公众号发布流水线。内置 draft/update 遇到 invalid media_id 自动回退到 draft/add。
version: 1.0.0
date: 2026-04-17
---

# WeChat Official Account Draft Pipeline

一个**去私有化、可复用、可直接分享给别人**的微信公众号草稿发布 skill。

目标不是“帮某个人发文”，而是提供一条通用主链：

1. 锁 manifest
2. 上传封面 / 正文图 / 固定图
3. 渲染最终 HTML
4. 写入微信草稿箱
5. 回查 media_id

## 何时使用

当用户要做这些事时使用：

- 发到微信公众号草稿箱
- 维护微信公众号长文排版流水线
- 用 manifest 管图片、封面、固定头图、固定尾图
- 批量上传公众号素材并回填 `wechat_url` / `media_id`
- `draft/update` 失败后，需要自动兜底到 `draft/add`

## 这个 skill 提供什么

### 1. manifest 校验

脚本：

- `scripts/validate-assets-manifest.mjs`

作用：

- 校验 `cover / inline / fixed_head / fixed_tail / cta`
- 检查必填素材是否存在本地文件或已有微信引用
- 阻止缺素材就发草稿

### 2. 微信素材上传

脚本：

- `scripts/wechat-upload-assets-from-manifest.mjs`

作用：

- 按 manifest 上传图片到微信永久素材
- 自动回填 `wechat_url` 与 `media_id`
- 支持 `--only`、`--force`

### 3. HTML 渲染

主推荐：

- `scripts/render-normal-wechat-article.py`

可选增强：

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

说明：

- `render-normal-wechat-article.py` 自包含、依赖少，适合默认主链
- `render-wechat-inline-html.py` 适合接现有 `md-to-wechat.ts` 体系，但需要额外提供：
  - `WECHAT_MD_TO_WECHAT_PATH`
  - 或 `scripts/vendor/md-to-wechat.ts`

### 4. 草稿箱写入

脚本：

- `scripts/wechat-draft-api.mjs`

能力：

- `draft/add`
- `draft/update`
- `draft/batchget` 回查
- `invalid media_id` 自动回退 `draft/add`

### 5. 一键串联

脚本：

- `scripts/publish-draft-from-manifest.mjs`

作用：

- 可选先跑 Grok 出图
- 自动校验 manifest
- 最后调用草稿写入脚本

## 最低配置口径

以后对外统一说这句话：

> **别人只需要配置：Grok URL、Grok key、微信凭证，就可以把这条链条跑起来；不需要再改源码里的私有映射。**

对应最少环境变量：

```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"
# 微信凭证二选一：这里示例用 APPID + APPSECRET
export WECHAT_APPID="wx1234567890"
export WECHAT_APPSECRET="your-wechat-secret"
```

如果不想直接暴露微信凭证，也可以改用：

- `WECHAT_ACCESS_TOKEN`
- 或 `--account-config ./wechat-account-config.json`

## 凭证配置方式

支持三种方式，优先级从高到低：

1. `WECHAT_ACCESS_TOKEN`
2. `WECHAT_APPID + WECHAT_APPSECRET`
3. `--account-config` / `WECHAT_ACCOUNT_CONFIG`

### account-config 适合分享给别人

推荐使用：

- `examples/wechat-account-config.example.json`

这样别人不需要改源码里的账号映射，只需要：

- 复制 example 文件
- 改成自己的账号名
- 填自己的 env 名或直接填 appid/appsecret

## 最短主链

```bash
# 0) 可选：先配环境变量
# 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"
# 微信凭证二选一：这里示例用 APPID + APPSECRET
export WECHAT_APPID="wx1234567890"
export WECHAT_APPSECRET="your-wechat-secret"

# 1) 校验 manifest
node scripts/validate-assets-manifest.mjs --manifest ./article-assets.json

# 2) 上传素材并回填 manifest
node scripts/wechat-upload-assets-from-manifest.mjs \
  --manifest ./article-assets.json \
  --account main \
  --account-config ./wechat-account-config.json

# 3) 渲染最终 HTML
python3 scripts/render-normal-wechat-article.py \
  --markdown ./article.md \
  --manifest ./article-assets.json \
  --output ./article-final.html

# 4) 写入草稿箱
node scripts/wechat-draft-api.mjs \
  --manifest ./article-assets.json \
  --html ./article-final.html \
  --title "你的标题" \
  --account main \
  --account-config ./wechat-account-config.json \
  --json
```

## 交付给别人时，最少一起给这些文件

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

## 快速上手

直接看：

- `SETUP-CHECKLIST.md`