微信公众号文章发布

把一篇写好的文章，一键推到自己的公众号草稿箱。它支持两条通道，互为备份——一条不通会自动降级到另一条：

方式一·微信官方通道：用公众号 AppID + AppSecret 调微信官方 draft/add，直接把草稿推进草稿箱。要求本机公网出口 IP 在公众号后台白名单内。
方式二·微绿流量宝：走 wx.limyai.com 的开放接口（weChat_bloom_key），不要求配白名单。

草稿进草稿箱后，最终「点击群发」这一下都留给你自己在后台操作。

安装方法

先问使用者用的是什么 AI 工具，选项按这个顺序列：1. WorkBuddy　2. Claude Code　3. Codex　4. 其他（用户直接说工具名），回答记作 X
只安装给 X，不安装或链接其他任何工具：
- X 是 WorkBuddy：把本技能下载后放进 ~/.workbuddy/skills/（WorkBuddy 的技能目录；skills CLI 不支持 WorkBuddy，由你直接放置）
- X 是其他工具：
```
npx -y --registry=https://registry.npmmirror.com skills add https://modelscope.cn/skills/sunny31221/wechat-publisher-buheliwa -a X -y
```
  （不带 -a 会安装给本机所有检测到的工具，禁止；--registry 为 npmmirror 镜像，保证国内不翻墙也能拉到 CLI）
- X 不在上述范围时，按该工具自身的技能机制安装，装完确认 X 能识别本技能即可
装完后询问使用者是否现在配置发布通道、开始发布

通道选择规则

两条通道互为备份：一条不通自动降级到另一条。也可用 --channel 手动指定。

自动判定（默认）：

| 配置情况 | 行为 | |---|---| | 两个都配了 | 先走官方，失败自动降级到微绿流量宝 | | 只配了官方（AppID + AppSecret） | 只走官方（另一条没凭证，降不了） | | 只配了微绿流量宝（weChat_bloom_key） | 只走微绿流量宝 | | 小绿书（--type newspic） | 只走微绿流量宝（官方通道不支持小绿书） |

手动指定：--channel official 或 --channel bloom 只跑指定的那一条，不降级。

两条都不通时，脚本会分别打印两条通道的失败原因，并给出针对性排查指引（官方通道报 40164 直接提示去配白名单 IP；微绿流量宝连不上提示先用浏览器确认第三方服务是否正常）。降级成功时也会明确告诉你「本次实际走的是哪条通道」。

封面格式两条通道不同：官方通道要本地文件（配图技能产出的 PNG），微绿流量宝要 HTTP(S) URL。降级时格式对不上会跳过封面并提示，不中断发布。

使用前的一次性配置

方式一（微信官方通道）：

在公众号后台「设置与开发 → 基本配置 → 开发接口管理」拿到 AppID 和 AppSecret（AppSecret 点「重置」后只显示一次）。
在同一页的「IP 白名单」里加进本机公网出口 IP（设置后约 10 分钟生效）。
在项目根目录 .env.local 里填 weChat_AppID= 和 weChat_AppSecret=。

方式二（微绿流量宝）：

浏览器打开 https://wx.limyai.com/login 注册登录；进「开放平台 → 创建密钥」拿 API 密钥；进「公众号管理 → 添加公众号」扫码绑定授权。
在 .env.local 加 weChat_bloom_key=<密钥>；可选 weChat_bloom_AppID=<AppID> 固定默认公众号。

When to Use

发布 Markdown 或 HTML 文章到公众号草稿箱
用小绿书（图文）模式发布图片为主的内容
查已授权的公众号列表

When NOT to Use

文章还在写作阶段 → 先完成内容再发布
只需要 HTML 排版（不发布）→ 用「公众号排版」（gzh-layout-buheliwa），不调本技能

与排版技能搭配使用

本技能负责把文章推进公众号草稿箱，不负责排版。常见搭配是先排版再发布：用「公众号排版」（gzh-layout-buheliwa）把成稿排成公众号格式的 HTML（样式内联、图片路径保留），再把这份 HTML 交给本技能上传——文章里的本机图片由本技能上传到微信服务器，排版那一步不处理图片。也可以跳过排版、直接发 Markdown，但样式会朴素。

Quick Reference

脚本路径以实际安装位置为准（Claude Code 是 .claude/skills/wechat-publisher-buheliwa/，多数工具是 .agents/skills/wechat-publisher-buheliwa/）：

| 操作 | 命令 | |------|------| | 发布 Markdown 文章 | npx tsx <技能目录>/scripts/publish.ts publish article.md | | 发布 HTML 文章 | npx tsx <技能目录>/scripts/publish.ts publish article.html | | 发布小绿书 | npx tsx <技能目录>/scripts/publish.ts publish content.md --type newspic --cover-image https://... --images img1.jpg,img2.jpg | | 获取公众号列表 | npx tsx <技能目录>/scripts/publish.ts list | | 仅验证不发布 | 加 --dry-run | | 指定 AppID | --appid wxXXXXXX | | 指定标题 | --title "自定义标题" | | 指定摘要 | --summary "文章摘要" | | 指定封面图 | --cover-image https://example.com/cover.jpg | | 指定作者 | --author "作者名"（不传则用公众号默认作者） | | 指定通道 | --channel official（官方）或 --channel bloom（微绿流量宝）；默认自动判定 | | 官方通道封面 | --cover-image 封面.png（本地文件，配图技能产出的 PNG；官方通道会自动上传成永久素材） |

官方通道（方式一）的 --cover-image 传本地文件路径（配图技能产出的封面 PNG）；微绿流量宝（方式二）传 HTTP(S) URL。两者语义不同。

Publishing Workflow

Step 1: 确认配置

发布前检查环境变量（在项目根目录 .env.local 或 .env 中配置）：

| 变量 | 必填 | 说明 | |------|------|------| | weChat_AppID | 官方通道必填 | 公众号 AppID（方式一） | | weChat_AppSecret | 官方通道必填 | 公众号 AppSecret（方式一） | | weChat_bloom_key | 微绿流量宝必填 | API 密钥（方式二） | | weChat_bloom_AppID | 否* | 默认公众号 AppID（方式二；未指定 --appid 时自动从账号列表取第一个） |

Step 2: 准备内容

Markdown 文件（.md）：直接发布，自动以 contentFormat: markdown 发送
HTML 文件（.html）：自动以 contentFormat: html 发送（脚本会把 <style> 里的样式内联，微信编辑器只认行内样式）
标题：从文件首行 # 标题 或 <h1> 提取，也可 --title 手动指定（最长 64 字符）
摘要：从首个段落提取，也可 --summary 手动指定（最长 120 字符）

Step 3: 执行发布

推荐先 dry-run 验证：

npx tsx <技能目录>/scripts/publish.ts publish article.md --dry-run

正式发布：

npx tsx <技能目录>/scripts/publish.ts publish article.md

Step 4: 到后台确认

发布成功只代表文章进了草稿箱。打开微信公众号后台，确认文章躺在草稿箱里、排版和配图正常，再由你手动点发布。

小绿书（图文模式）

当 --type newspic 时发布为小绿书：

必须通过 --cover-image 或 --images 提供图片（至少一张）
图片合并顺序：封面图 → 主体图片，自动去重，最多 20 张
文字内容仅支持纯文本，最多 600 字
适合以图片为主的内容发布

npx tsx <技能目录>/scripts/publish.ts publish content.md \
  --type newspic \
  --cover-image https://example.com/cover.jpg \
  --images "https://example.com/1.jpg,https://example.com/2.jpg"

获取公众号列表

npx tsx <技能目录>/scripts/publish.ts list

输出示例：

已授权公众号列表 (1 个):
  - 示例公众号
    AppID: wxaaaaaaaaaa000000
    类型: 订阅号
    状态: active

Common Mistakes

| 错误 | 原因 | 修复 | |------|------|------| | Could not find API key | .env.local 未配置 | 加 weChat_bloom_key=xxx | | HTTP 401 | API 密钥无效 | 检查密钥值是否正确 | | ACCOUNT_NOT_FOUND | 公众号不存在或未授权 | 先用 list 命令看可用账号，检查 --appid | | NO_IMAGES | 小绿书模式未提供图片 | 加 --cover-image 或 --images | | INVALID_PARAMETER | 参数错误（标题/摘要超长等） | 标题 ≤64 字符，摘要 ≤120 字符，小绿书文字 ≤600 字 | | 标题提取为空 | 文件无 # 标题 或 <h1> | 用 --title 手动指定 | | 封面图必须是 HTTP(S) URL | 微绿流量宝用了本地路径 | 先上传图片到图床，获取公网 URL（或改走官方通道传本地文件） |

官方通道（方式一）错误码

| 错误 | 原因 | 修复 | |------|------|------| | 40164（IP 不在白名单） | 本机公网出口 IP 没在公众号后台白名单 | 去「微信开发者平台 → 我的业务 → 公众号 → 基础信息 → 开发信息 → API IP 白名单」加本机出口 IP，等约 10 分钟生效 | | 40013 | AppID 不合法 | 检查 weChat_AppID | | 40125 | AppSecret 不合法 | 检查 weChat_AppSecret | | 40005 / 40009 | 正文图格式/尺寸不对 | 正文图仅 jpg/png、≤1MB；封面图 ≤10MB | | 40007 | 封面 media_id 无效 | 重新规划封面图上传 |

Resources

scripts/publish.ts — TypeScript 发布脚本（strict 模式，零依赖）
references/api-reference.md — wx.limyai.com API 完整接口文档