gzh-cli 是一个面向微信公众号发布工作流的 TypeScript 命令行工具。当前版本通过微信公众平台官方 draft/add API 创建公众号草稿，并提供可复用的本地登录会话；freepublish 提交与发布状态轮询正在开发中。
项目坚持 API-first：能通过微信官方 API 完成的操作，不使用浏览器自动化代替。草稿创建与正式发布保持分离，未来的发布命令也会轮询发布状态，不会把 freepublish/submit 成功误判为文章已经发布。
- 持久化登录：
gzh login - 环境诊断：
gzh doctor - 使用微信官方草稿 API 创建单篇图文草稿：
gzh draft create - 支持 HTML 字符串或本地 HTML 文件作为正文
- 支持作者、摘要、原文链接和评论权限参数
- Node.js 20 或更高版本
- 已认证的微信公众号
- 账号已具备草稿相关 API 权限
- 用于创建草稿的
WECHAT_MP_ACCESS_TOKEN - 已上传到微信素材库的封面图
media_id
不同公众号类型、认证状态和接口权限可能不同。执行草稿或发布命令前，请先在微信公众平台确认当前账号拥有相应 API 权限。
npm 包发布后，可通过以下命令全局安装：
npm install -g @joohw/gzh-cli当前尚未发布到 npm Registry 时，可从源码运行：
git clone https://github.com/joohw/gzh-cli.git
cd gzh-cli
npm ci
npm run build
node dist/cli/index.js help先检查当前 CLI 状态：
gzh doctor如需登录微信公众平台并复用本地登录态：
gzh login --timeout 120创建草稿前设置 Access Token：
export WECHAT_MP_ACCESS_TOKEN='your-access-token'然后创建微信公众号草稿：
gzh draft create \
--title '测试文章' \
--thumb-media-id 'THUMB_MEDIA_ID' \
--content-file ./article.html \
--author 'Joo' \
--digest '这是一篇测试草稿' \
--source-url 'https://example.com/post' \
--need-open-comment true命令成功后会输出草稿 media_id 和微信公众平台编辑地址。创建草稿不会自动发布文章。
显示帮助和当前可用命令。
显示当前版本。
显示登录、草稿 API 和发布能力的实现状态。
gzh login [--timeout <秒>]打开微信公众平台登录页，并将登录状态保存在本地 Chrome 配置目录中。该浏览器登录能力用于需要网页会话的辅助场景，不是草稿和发布操作的默认路径。
gzh draft create \
--title <标题> \
--thumb-media-id <mediaId> \
(--content <HTML> | --content-file <path>) \
[--author <作者>] \
[--digest <摘要>] \
[--source-url <链接>] \
[--need-open-comment <true|false>] \
[--only-fans-can-comment <true|false>]--content 与 --content-file 只能选择一个。正文必须是微信图文消息接口可接受的 HTML。
HTML 正文 + 封面 media_id
│
▼
微信官方 draft/add API
│
▼
草稿 media_id + 编辑地址
规划中的正式发布流程为：
草稿 media_id → freepublish/submit → publish_id → 轮询发布状态 → 确认成功或失败
微信草稿与正式发布是两个不同阶段。当前版本只实现草稿创建，避免在没有明确确认的情况下发布内容。
官方 API 的行为更稳定、结果更容易验证。项目只在登录等必要场景使用浏览器能力。
通过环境变量 WECHAT_MP_ACCESS_TOKEN 提供。不要把 Access Token、Cookie 或其他公众号凭据提交到 Git 仓库。
它是已经上传到微信素材库的封面图素材 ID。当前版本暂未提供素材上传命令。
npm ci
npm run build
npm test
node dist/cli/index.js helpgzh publish submit --media-id <id>gzh publish status --publish-id <id>- 发布状态自动轮询与失败原因输出
- 素材上传和账号 API 权限诊断
- 不要提交 Access Token、Cookie 或浏览器用户数据目录。
- 建议使用最小必要权限的微信公众平台凭据。
- 正式发布功能完成后，仍应在发布前核对目标账号和草稿内容。