必须从 hermes-kb 根目录执行，或传入绝对路径

🎯 【一句话洞察】

• 每次推草稿前先传一张固定占位封面拿到有效 media_id，推完后在公众号后台手动替换真实封面，避免 media_id 过期（40007 invalid media_id）阻塞推送链路。

🗺️ 【核心逻辑链】

1. 痛点：公众号永久素材 media_id 会过期（或被后台删除），每次推送前缓存的 .wxgzh-cover-id 可能失效，报 40007 阻断流程。
2. 解决方案：用一张固定小体积 PNG 作为占位封面，每次推送前重新上传换取新的有效 media_id → 推送成功 → 登录公众号后台编辑草稿，把封面换成真正的出图。media_id 只需要活过"创建草稿"这 5 分钟即可。
3. 额外价值：把"检查隧道→加载 env→快照→上传封面→推草稿→去重守卫"六步串成一键脚本，不再手动按顺序敲命令，并内置重复草稿清理。
4. 踩坑 & 规避（2026-07-03）：wxgzh-cli 的 withAccessTokenRetry 对写接口（POST /cgi-bin/draft/add、/cgi-bin/material/add_material）做了非幂等重试：access_token 临界失效会 clearTokenCache 后再发一次完整 POST。SOCKS5 代理不稳定时，第一次请求已在微信侧创建草稿但返回被判定为 invalid token 错误 → 第二次 POST 再创建第二份。表象是"脚本只打印一次 draft created，实际出现 2 份甚至 3 份"，且两份的 thumb_media_id 不一致（material upload 也被重试了两次，两次上传分配到不同 media_id）。根本防御**：推送前后两次 list draft 做 media_id diff，只保留 create_time 最新的一份，其余用 draft delete 清理。

🏗️ 【技术架构】

• 占位封面路径：placeholder_cover.png（hermes-kb 根目录，建议 1KB 以内纯色或极简图即可）
• 一键脚本：kb/scripts/push_wx_draft.ps1（PowerShell，Windows 原生执行）
• 缓存文件：.wxgzh-cover-id（每次上传后覆盖写入，不依赖历史值）

⚙️ 【上手实践要点】

• 脚本用法：

  # 必须从 hermes-kb 根目录执行，或传入绝对路径

  powershell -ExecutionPolicy Bypass -File kb/scripts/push_wx_draft.ps1 "文章标题" "wxgzh-draft/文章.html"



  # 或带参数名

  ./kb/scripts/push_wx_draft.ps1 -Title "标题" -ContentFile "wxgzh-draft/xxx.html"

• 脚本内部自动做的事（5 步）：

1. 【1/5】检查 127.0.0.1:1080 是否 LISTENING，没起就后台拉起 ssh -D 1080 隧道（等 4 秒二次验证）
2. 【2/5】加载 wxgzh-cli/.env 到当前进程 env，设置代理；同时记录当前所有草稿的 media_id 快照
3. 【3/5】上传 placeholder_cover.png 拿 media_id，写入 .wxgzh-cover-id
4. 【4/5】调用 wxgzh draft add 推送，标题 + 内容 HTML + 新 media_id
5. 【5/5】去重守卫：重新 list draft，对比快照找出「新出现的 media_id」。如果数量 > 1（说明 wxgzh-cli 重试导致重复），按 create_time 倒序只保留最新的 1 份，其余调用 draft delete 清理，并打印 [WARN] 日志。

• 手动查询 + 清理重复草稿的命令（脚本失效时兜底）：

  # 列出所有草稿（JSON）

  $env:HTTP_PROXY="socks5://127.0.0.1:1080"; $env:HTTPS_PROXY="socks5://127.0.0.1:1080"; cd d:/hermes-kb/wxgzh-cli; ./wxgzh.exe draft list --json

  # 删除指定 media_id 的草稿（去后台找到要删的 media_id 替换）

  ./wxgzh.exe draft delete --media-id "<media_id>" --confirm --json

• 船长需要手动做的事：

1. 进公众号后台 → 草稿箱 → 找到刚创建的草稿 → 编辑
2. 替换封面为 DALL·E / SD 出的正式图 → 保存或直接群发

• 风险点：脚本假设 wxgzh-cli/.env 变量格式为 KEY=VALUE 无引号；如果 env 带 export 前缀或引号，需要修改脚本的解析逻辑。
• 验证步骤：脚本跑完全部 4 步，最后一行显示 ✅ 草稿推送完成！ 即成功；如失败会在具体步骤抛出原始错误。

📋 【核心用法】

• 占位封面无需美观，只求体积小、上传快
• 真实封面用公众号后台"替换封面"按钮上传，不走 wxgzh-cli 链路（后台上传后自动拿永久 media_id，不走脚本缓存）
• 如果占位图被误删，任意找一张小于 2MB 的 PNG 存为 placeholder_cover.png 放根目录即可恢复

🔗 【相关链接】

• 微信公众平台：https://mp.weixin.qq.com/
• wxgzh-cli README：wxgzh-cli/README.md

标签: tool, ai