WeChat Draft Publisher Cloud

WeChat Draft Publisher (Cloud)

一个动作：article.md + cover.png + 标题 → relay → 公众号草稿箱。

默认 dry-run（不真发，只本地转 HTML + 跑流程 + 写 mock media_id）。真发必须显式加 --real——防止自动化测试时误推到用户草稿箱。

何时用 / 不用

用：用户说"推草稿"、"发公众号草稿箱"，或上游流水线 Step 7 调用。 不用：写文章 / trending / 邮件 / 纯本机保存。

relay 是什么

relay 是部署在 微信云托管 上的开源草稿代理服务端，利用官方「开放接口服务（云调用）」免鉴权调用公众号接口，本地脚本无需固定 IP、无需公众号 appid/secret。本 skill 是客户端，负责写稿、把 Markdown 转成微信图文 HTML、处理图片，再把内容交给 relay。

relay 只做三件事（纯代理，不解析 Markdown）：

• POST /material：接收图片 base64，上传到微信素材库，返回 media_id + url
• POST /draft：接收标题 + 已转好的 HTML + 封面 thumb_media_id，创建草稿
• POST /draft-delete：接收 {"media_id": ...}，删除草稿（需先在云调用「微信令牌」权限中加 /cgi-bin/draft/delete）

Markdown -> HTML 在哪里做

在本 skill 本地完成（scripts/md2wechat.py，零依赖纯标准库实现）。relay 不碰 Markdown。 这样 relay 保持极简、零三方依赖；所有内容加工都在你本地可控。

配置注入（访问密钥 + 访问地址）

relay 跑在云托管，默认公网地址是平台生成的默认域名（谁都能访问），所以必须靠「访问密钥」保护。本 skill 按以下优先级解析 访问地址(URL) 与 访问密钥(KEY)：

1. 命令行：--cloud-url / --cloud-key
2. 环境变量（推荐）：
   • WECHAT_DRAFT_RELAY_URL / WECHAT_DRAFT_RELAY_KEY
   • 兼容旧名 DRAFT_CLOUD_URL / DRAFT_API_KEY
3. config.json（放在 scripts/ 目录下，已被 .gitignore 忽略，不进仓库）：

   { "relay_url": "https://<你的服务名>.<地域>.run.tcloudbase.com", "relay_key": "你的 RELAY_API_KEY" }
   

4. 脚本默认值（发布版留空，要求显式配置；私部署可在此填个人默认值）

发布版不硬编码任何个人地址 / 密钥——安装后由用户自己注入，符合开源安全要求。

输入

输出（写 $run_dir/publish_result.json）

{success, media_id, chosen_title, chosen_title_bytes, cloud_url, body_images, html_len, covered_appended, feishu_sent, error_code, error_msg, elapsed_sec}

用法

# 1) dry-run（默认，本地转 HTML + 校验，不发任何请求）
python scripts/publish_script.py --article X.md --cover Y.png --titles-md T.md

# 2) 真发（推荐先 1) 验证后再 2)）
python scripts/publish_script.py --real --article X.md --cover Y.png --titles-md T.md

正文插图怎么写：在 article.md 正常用 markdown 图片语法，脚本自动扫描、本地转 HTML、经 relay 上传。

## 一段说明

![对比图](img/compare.png)

- 要点一
- 要点二

删除草稿

草稿箱会累积（每次 --real 都新增一篇、不覆盖）。清理旧草稿：

# 单个删除（默认 dry-run 只列出，--real 才真删）
python scripts/publish_script.py --delete  --real

# 批量删除（文件每行一个 media_id，# 开头为注释）
python scripts/publish_script.py --delete-batch ids.txt --real

底层走 relay POST /draft-delete，密钥/地址解析规则与发布一致（--cloud-url/--cloud-key > 环境变量 > config.json > 默认值）。需先在云调用「微信令牌」权限中加 /cgi-bin/draft/delete 并重建版本，否则报 48001。

• 本地图：![](img/body1.png) —— 脚本本地转 HTML 时经 relay /material 上传素材库后替换成 mmbiz 链接。
• publish_result.json 里 body_images 字段报告本次扫描到的本地插图数量，html_len 报告生成 HTML 长度，dry-run 即可验证。

流程（--real 时）

1. 校验：article / cover / titles_md|title_file 文件存在；run_dir 自动 makedirs
2. 选标题：titles.md 解析第 1 个 1. / 1、 / 1) 候选；或直读 title.txt
3. 字节：UTF-8 ≤64；超了报错不截断
4. 写 title.txt：覆盖式写入，run-dir/title.txt
5. 本地转 HTML：md2wechat.convert(md, url_map)（dry-run 也跑，验证转换不崩）
6. 上传插图：每张图 base64 后 POST relay /material → 换回 mmbiz url，写入 url_map
7. 上传封面：POST relay /material → 拿到 thumb_media_id
8. 建草稿：标题 + HTML + thumb_media_id POST relay /draft → 返回 media_id
9. 写 publish_result.json

错误码

失败不删 article.md / cover.png，留人重试。

Pitfalls

1. 字节 ≠ 字符：len(s.encode('utf-8'))，中文每字 3 字节
2. 超 64 字节不静默截断：平台上限，截断会改语义
3. 默认 dry-run：mock 返回 MOCK_MEDIA_ID_dryrun，外部副作用全跳过（不真发、不发飞书、不动 covered）。真发必须 --real
4. 零依赖发送 + 零依赖转换：发送用标准库 urllib + base64（JSON 协议）；Markdown->HTML 用 scripts/md2wechat.py（纯标准库）。无需 requests / curl / mistune
5. 幂等：covered_line 追加前先 grep；COVERED.md 不存在自动建文件头
6. 503 (nginx) 是网关层通用冷启动：偶发（任何尺寸都可能）。内置 do_publish_with_retry 风格逻辑：识别 "503" + err_code=NETWORK 时 sleep(8) 后自动重试 1 次
7. 草稿箱会累积：每次 --real 都新增 1 篇，不会自动覆盖前一篇
8. 云调用模式免 IP 白名单、免 appid/secret：relay 部署在微信云托管并开启「开放接口服务」即可，本地脚本零凭证