微信公众号发布管理的 agent-friendly CLI

中文 · English

项目定位

wxgzh-cli 是面向微信公众号发布管理的 agent-friendly CLI。它的目标不是复刻完整 SDK，而是把 agent 工作流最后一步需要的动作整理成稳定、可验证、可脚本化的命令面。

它适合把“内容已经由 agent 生成完成”之后的重复操作收束成一条可审计的发布流水线：检查公众号接口能力、上传素材、创建草稿、提交发布、查询状态，并把最终文章链接回填给后续工作流。对个人创作者、小团队和自动化运营场景来说，它的价值是少做手工搬运，多保留确认门禁，把发布动作变得可脚本化、可复查、可逐步自动化。

1.0.0 目标

第一版以 1.0.0 为里程碑，目标是打通：

• 本地配置与公众号接口能力检查
• access_token 管理
• 素材上传与正文图片处理
• 草稿创建与管理
• 发布提交、状态查询与链接回填
• agent-safe JSON 输出、dry-run 与显式确认门禁

快速开始

make test
go run ./cmd/wxgzh --json doctor
go run ./cmd/wxgzh --json probe

当前版本已提供 doctor、probe、material、draft、publish 和 version。其中 probe 会获取 access_token，并探测素材、草稿、发布能力是否可用。

发布流水线

所有会写入公众号后台或对外可见的动作都默认 dry-run。确认本地输出符合预期后，再显式增加 --confirm。

# 1. 检查配置和接口能力
wxgzh --json doctor
wxgzh --json probe

# 2. 上传封面素材，默认只预览；确认后才上传
wxgzh --json material upload --type image --file ./cover.png
wxgzh --json material upload --type image --file ./cover.png --confirm

# 3. 上传正文图片并替换 Markdown/HTML 本地图片引用
wxgzh --json material rewrite --input ./article.md --output ./article.wx.md
wxgzh --json material rewrite --input ./article.md --output ./article.wx.md --confirm

# 4. 创建草稿，默认只预览；确认后才写入草稿箱
wxgzh --json draft add \
  --title "文章标题" \
  --thumb-media-id "<cover-media-id>" \
  --content-file ./article.wx.md \
  --content-format markdown

wxgzh --json draft add \
  --title "文章标题" \
  --thumb-media-id "<cover-media-id>" \
  --content-file ./article.wx.md \
  --content-format markdown \
  --confirm

# 5. 提交发布，默认只预览；这是外部可见动作，必须人工确认后加 --confirm
wxgzh --json publish submit --media-id "<draft-media-id>"
wxgzh --json publish submit --media-id "<draft-media-id>" --confirm

# 6. 查询发布状态并回填文章链接
wxgzh --json publish status --publish-id "<publish-id>"
wxgzh --json publish wait --publish-id "<publish-id>" --timeout 5m

草稿也可以使用 JSON 输入，适合 agent 生成结构化参数：

{
  "articles": [
    {
      "title": "文章标题",
      "thumb_media_id": "cover-media-id",
      "author": "作者",
      "digest": "摘要",
      "content": "<p>正文 HTML</p>",
      "content_source_url": "https://example.com/original"
    }
  ]
}

wxgzh --json draft add --input ./article.json
wxgzh --json draft add --input ./article.json --confirm

微信公众号平台对接

wxgzh-cli 直接对接微信公众号开放接口，默认不走浏览器模拟，不要求 agent 登录网页后台。真实能力以公众号后台当前接口权限为准，CLI 会优先通过 doctor/probe 判断账号能否继续执行素材、草稿和发布动作。

推荐对接流程：

1. 登录 微信公众平台。
2. 进入「设置与开发」相关页面，获取或重置 AppID、AppSecret。
3. 配置接口调用所需的 IP 白名单，避免 access_token 或后续接口被拒绝。
4. 在接口权限中确认素材管理、草稿箱、发布能力等接口是否可用。
5. 在本地或 CI 环境配置 WXGZH_APP_ID、WXGZH_APP_SECRET。
6. 使用 wxgzh --json doctor 检查本地配置，再用 wxgzh --json probe 探测真实接口能力。
7. 进入发布流水线：上传素材 -> 创建草稿 -> 提交发布 -> 查询状态 -> 回填文章链接。

关键参考链接：

• 微信公众平台
• 微信公众号开发概述
• 接入指南
• 获取 access_token
• 新增草稿
• 发布接口
• 微信公众号 API 整理文档

配置

微信 API 调用会优先读取：

export WXGZH_APP_ID="your-app-id"
export WXGZH_APP_SECRET="your-app-secret"

access_token 会默认缓存到系统用户缓存目录。也可以显式指定缓存文件：

export WXGZH_TOKEN_CACHE="$HOME/.cache/wxgzh-cli/token.json"

CLI 输出必须脱敏，不打印 AppSecret、access_token、素材上传临时凭证等敏感值。

Agent 调用合同

所有可被 agent 调用的命令都应支持 --json，并返回稳定结构：

{
  "ok": true,
  "kind": "wxgzh.action",
  "warnings": [],
  "next": "next action hint"
}

破坏性或外部可见动作必须默认支持 dry-run，并通过显式 --confirm 进入真实执行。当前门禁规则：

• material upload、material upload-image、material rewrite：默认 dry-run，--confirm 后才上传或写输出文件。
• draft add、draft update、draft delete：默认 dry-run，--confirm 后才写入或删除公众号草稿。
• publish submit：默认 dry-run，--confirm 后才提交正式发布。
• draft get/list、publish status/wait/list：只读查询，不需要 --confirm。

更多安全边界见 发布安全门禁。

Logo 设计

当前 logo 资产位于 assets/：

• assets/logo.svg：纯图标 SVG
• assets/logo.png：纯图标 PNG
• assets/logo-lockup.svg：README 顶部横向品牌图
• assets/logo-lockup.png：横向品牌图 PNG

后续重设计可参考 logo 生成 prompt。