通过公众号官方开放 API，把 Markdown 文章（含本地图片）一键推送到微信公众号草稿箱。纯 Python 标准库实现、零第三方依赖，自动完成 access_token 获取、正文配图上传、封面永久素材上传与 draft/add；正式发布动作保留人工在后台确认。

wechat-mp-publish · 微信公众号草稿推送 Skill

通过公众号官方开放 API，把 Markdown 文章（含本地图片）一键推送到公众号草稿箱。纯 Python 标准库实现，零第三方依赖。

触发词

• 推送/发布文章到公众号、公众号草稿箱、公众号 API 发布
• wechat mp publish、公众号 draft

前置条件

1. 公众号 APPID / APPSECRET（存放在调用方指定的 env 文件里，如项目根目录 0-config.env，格式：APPID = "wx..." / APPSECRET = "..."）；
2. IP 白名单：公众号后台 → 设置与开发 → 基本配置 → IP白名单，必须加入执行机公网 IP，否则获取 access_token 报 40164（脚本会自动提示该 IP）；
3. 网络可访问 api.weixin.qq.com；
4. 封面图建议 900×383、<2MB；正文配图 <1MB（jpg/png）；
5. 图片必须是真 jpg/png：扩展名为 .png 但实际是 WebP 等格式会被 40137 拒收，上传前用 file 命令抽查，必要时用 macOS 自带 sips -s format png 转换。

使用流程（标准四步，对应 scripts/）

SKILL=~/.qoder/skills/wechat-mp-publish/scripts

# 0) 可选：dry-run 预览 HTML，不消耗任何 API 调用
python3 $SKILL/push_draft.py --config <env文件> --md <文章.md> --dry-run

# 1) 推送草稿（内部自动完成：token → 正文配图上传 → 封面永久素材上传 → draft/add）
python3 $SKILL/push_draft.py --config <env文件> --md <文章.md> 
    --cover <封面图> [--title 标题] [--digest 摘要] [--author 署名]

# 2) 验证：查询草稿箱列表
python3 $SKILL/check_drafts.py --config <env文件>

成功标志：push_draft.py 输出 [SUCCESS] 草稿已推送，并返回草稿 media_id；随后可在公众号后台草稿箱看到文章并直接发布。

参数说明

API 对照（内部实现）

严格禁止 (NEVER DO)

• 不得把 APPSECRET / access_token 打印、写入讲义、文档、PPT 或任何对外材料；
• 不得执行正式发布（freepublish/submit）——发布动作始终保留人工在后台确认；
• 不得连续重试失败命令超过 3 次；遇到 40164/40001/48001 按脚本提示处理后停止并报告。

常见错误速查