需要安装第三方依赖吗？

不需要。脚本只用 Python 标准库，无需 pip 安装。

CLI 直接封装了哪些公众号接口？

token 取凭证、upload-image（正文图）、upload-thumb（永久封面）、draft-add / drafts、publish、published。其余官方接口走通用 `call` 子命令。

是否提供绕过微信审核或风控的方法？

不提供。skill 明确声明不含绕审、绕风控、绕反自动化的手段，群发与模板消息等触达操作需先经用户确认。

缓存的 token 存在哪里？

系统临时目录下的一个文件，7000 秒过期；除此之外不读写其他文件，且只请求 api.weixin.qq.com。

编程

Weixin

零依赖 Python 命令行直接调公众号 API，附真实生产事故踩坑清单

它能做什么

提供零依赖 Python CLI（scripts/wxoa.py，仅标准库），封装 access_token 获取、正文图片上传、永久封面素材、草稿新建/列出、发布、已发表记录查询等公众号常用接口；通用 `call` 子命令可调用任何官方端点，未封装的接口也能用。配套的踩坑清单来自真实运营事故复盘：IP 白名单 40164、日配额 45009、token 互相挤掉线、发表标题截断、重复推送、低创作度限流、封面比例等。另含服务器接入验证、网页授权 OAuth2.0、小程序登录、JSSDK 签名、支付 V3 签名与回调加解密等开发速查。

什么时候用它

取 access_token 并本地缓存
上传封面素材与新建图文草稿
发布草稿并查询已发表记录
排查 40164 / 45009 等接口错误

技能文档

微信公众平台开发 Skill

不止讲"微信开发是什么"——本 skill 附带一个零依赖命令行工具 （scripts/wxoa.py，仅 Python 标准库），让 agent 直接替用户完成公众号内容发布全链路：取 token → 传封面 → 建草稿 → 发布 → 查发表记录。另附一份真实生产环境踩坑清单（每一条都来自实际运营公众号的事故复盘）。

快速开始

export WX_APPID=wx开头的AppID
export WX_SECRET=公众号AppSecret

python3 scripts/wxoa.py token                        # 验证凭证
python3 scripts/wxoa.py call /cgi-bin/get_api_domain_ip   # 冒烟测试

脚本行为声明：仅请求 api.weixin.qq.com；本地只写一个 token 缓存文件（系统临时目录，7000 秒过期），不读写其他文件。

命令手册

命令	作用
`token`	取 access_token（本地缓存，避免重复刷新挤掉线上服务的 token）
`call [json]`	通用调用：任何官方接口，无 body 为 GET，有 body 为 POST
`upload-image`	上传正文内图片（uploadimg，返回 url，不占素材库）
`upload-thumb`	上传永久图片素材（返回 media_id，作草稿封面）
`draft-add <标题> [作者] [摘要]`	新建图文草稿
`drafts [offset] [count]`	列草稿箱
`publish`	发布草稿（freepublish/submit）
`published [offset] [count]`	列已发表记录

发一篇文章的完整流程

python3 scripts/wxoa.py upload-thumb cover.jpg
# → {"media_id": "MEDIA_ID", "url": "..."}
python3 scripts/wxoa.py draft-add "文章标题" article.html MEDIA_ID "作者名" "摘要"
# → {"media_id": "DRAFT_MEDIA_ID"}
python3 scripts/wxoa.py publish DRAFT_MEDIA_ID
# → {"publish_id": "..."}（异步，稍后用 published 查结果）

call 兜底示例（脚本未封装的接口都能调）：

python3 scripts/wxoa.py call /cgi-bin/menu/get
python3 scripts/wxoa.py call /cgi-bin/user/get
python3 scripts/wxoa.py call /cgi-bin/message/template/send '{"touser":"OPENID","template_id":"...","data":{}}'

实战踩坑清单（生产事故复盘）

40164 = IP 不在白名单。公众号后台"IP白名单"只认配置过的服务器出口 IP。本地开发机直接调 token 必挂——要么把出口 IP 加白名单，要么经已加白的服务器中转。
45009 = 接口日配额耗尽。draft/freepublish 等接口有每日调用上限，耗尽后当天无解，次日 0 点重置。批量操作前先估算次数，脚本里不要对 45009 做无脑重试。
access_token 全局唯一。任何一端刷新 token 会使旧 token 失效—— 本脚本做了本地缓存，但若线上服务也在刷 token，两边会互相挤掉线。生产环境必须中心化缓存（Redis 等），临时脚本操作尽量复用线上缓存。
发表记录里的标题会被截断。用标题反查已发表文章时必须做 子串匹配，完整标题 == 匹配会漏。freepublish/batchget 也只能拉最近的记录，历史全量要自己本地存档。
推草稿前先去重。同名文章已在草稿箱或已发表时重复 push 会造成重复群发风险，push 前先查 drafts + published 双向子串匹配。
author 字段为空时部分第三方工具会跳过署名，导致历史旧笔名残留。建草稿时显式传作者名。
平台会判定"低创作度内容"。纯 AI 生成、排比堆砌、无真实锚点的文章可能被限流。发布前自查：有无真实数据/引用/具体案例。
封面必须独立生成。公众号封面比例 900×383，从 16:9 头图硬裁必丢内容。

开发知识速查

服务器接入验证

# GET 回调: sha1(sorted([token, timestamp, nonce])) == signature 则原样返回 echostr
tmp = ''.join(sorted([token, timestamp, nonce]))
ok = hashlib.sha1(tmp.encode()).hexdigest() == signature

网页授权 OAuth2.0（三步）

跳 open.weixin.qq.com/connect/oauth2/authorize（scope=snsapi_base 静默拿 openid / snsapi_userinfo 弹窗拿资料）
code 换 token：/sns/oauth2/access_token
拉用户信息：/sns/userinfo（此 token 与全局 access_token 是两回事）

小程序登录

wx.login() 取 code → 服务端 /sns/jscode2session 换 openid+session_key → 生成自定义登录态。session_key 绝不下发前端。

JSSDK 签名

sha1("jsapi_ticket=T&noncestr=N&timestamp=TS&url=U")，url 取 # 前部分。 jsapi_ticket 用全局 access_token 换取，同样需要中心化缓存。

支付 V3 要点

域名 api.mch.weixin.qq.com，JSON + SHA256withRSA 商户私钥签名
回调必须验签 + AES-256-GCM 解密 + 幂等处理（微信会重复通知）
商户私钥/APIv3 密钥绝不进版本库

API 域名速查

用途	域名
公众号/小程序 API	api.weixin.qq.com
微信支付	api.mch.weixin.qq.com
网页授权入口	open.weixin.qq.com
企业微信	qyapi.weixin.qq.com

本 skill 不做什么

不提供绕过微信审核、风控或反自动化机制的方法
不含个人微信号（非公众平台）自动化——那是封号高危区
群发、模板消息等触达用户的写操作，agent 必须先向用户确认再执行
企业微信深度集成建议用专门的 wework skill

常见问题

需要安装第三方依赖吗？: 不需要。脚本只用 Python 标准库，无需 pip 安装。
CLI 直接封装了哪些公众号接口？: token 取凭证、upload-image（正文图）、upload-thumb（永久封面）、draft-add / drafts、publish、published。其余官方接口走通用 `call` 子命令。
是否提供绕过微信审核或风控的方法？: 不提供。skill 明确声明不含绕审、绕风控、绕反自动化的手段，群发与模板消息等触达操作需先经用户确认。
缓存的 token 存在哪里？: 系统临时目录下的一个文件，7000 秒过期；除此之外不读写其他文件，且只请求 api.weixin.qq.com。