agentleFS
ykjshenzhen2008-ship-itykjshenzhen2008-ship-it/commercial-real-estate-skills/skills/wechat-mp-publish/SKILL.md

wechat-mp-publish

Skill0 starsChanged 35 days agoMITView on GitHub

把 Markdown 文章一键推进微信公众号草稿箱(排版 + 配图上传 + 建草稿)。当用户说「把这篇推到公众号」「发到公众号草稿箱」「公众号排版」「文章推草稿」时使用。走微信官方 API(AppID/AppSecret + IP 白名单),零第三方费用,不消耗积分。

  • Reads credentials

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

wechat-mp-publish

Markdown → 微信公众号草稿箱。官方 API 直连,无第三方 SaaS。

何时用

  • 用户说:「把这篇推到公众号草稿箱」「公众号排版」「发文到公众号」「草稿箱」
  • 已有 文章.md + 配图文件夹,想让 AI 完成「排版 + 插图 + 建草稿」

不用于:公众号文章抓取(用 wechat-article-extractor)、群消息(用 wechatreader)、数据分析。

前置检查(每次任务开始先跑)

wxmp check             # 验证凭证 + IP 白名单,一步定位卡在哪
wxmp accounts          # 看有没有配过公众号
  • check 返回 verdict: 全绿 → 直接进发布流程。
  • 返回 blocked_by: ip_whitelist → 直接用回包里的 wechat_seen_ip,不要用 wxmp ip 的结果。
  • 返回 blocked_by: api_permission + errcode: 48001 → 账号未微信认证,API 路线走不通,换浏览器自动化。
  • 返回 credentials_ok: false → AppID/AppSecret 有问题。

⚠️ 多出口网络必做:先采样再填白名单

家庭宽带/多 WAN/负载均衡会轮换多个出口 IP,只加一个会变成"有时成功有时 40164"的随机失败。

wxmp probe-ip --samples 20     # 采样出全部出口 IP,一次填完

微信白名单支持多条(上限 20),把采样到的 IP 全部加上。换网络/重启路由后重采一次。

命令入口:~/.local/bin/wxmp → ~/.workbuddy/skills/wechat-mp-publish/scripts/wxmp.py(纯标准库,无依赖)。

首次接入(三步)

⚠️ 路径已变(2025-12-01 起):设置与开发 - 开发接口管理 已从 mp.weixin.qq.com 迁移到微信开发者平台。AppSecret 和 API IP 白名单现在只能在开发者平台操作。网上 2025 年之前的教程路径全部失效——这是新人最常见的卡点。

  1. wxmp ip → 得到本机公网出口 IP。
  2. 打开 https://developers.weixin.qq.com/platform/ → 右上角「登录」→ 公众号管理员微信扫码
    • 「我的业务与服务」→「公众号」→ 首次需填 AppID 绑定 → 管理员扫码授权
    • 进入「基础信息」→ 下拉到 「开发密钥」:
      • AppID 直接可见可复制
      • AppSecret → 点「启用」或「重置」→ 管理员扫码 → 只显示这一次,立即复制
    • 同页面继续下拉 → 「API IP 白名单」 → 点「编辑」→ 加入第 1 步的 IP(原有条目不要删)→ 管理员扫码确认 → 保存
  3. 写凭证(任选其一):
# A. 追加到 ~/.workbuddy/.env(脚本自动读取)
WECHAT_APPID=wx************
WECHAT_SECRET=****************

# B. 或写入 ~/.workbuddy/wechat_mp.json
{"appid":"wx...","secret":"...","default":"老杨拆商业"}
  1. 复跑 wxmp check 确认 token_ok: true。

⚠️ 「认证才能建草稿」是错的(2026-10-03 实测推翻):账号「老杨拆商业」= 个人主体、认证状态「暂未认证」,实测 thumb(素材)、draft(草稿)全部一次成功,无 48001。微信文档里 仅认证 的口径约束的是群发/发布,不是建草稿。→ 结论:先别用 48001 判断"账号死路",实跑一次 wxmp draft 才知道。只有 draft/add、uploadimg、material/* 真的返回 48001 时,才判定为资质问题(此时换浏览器后台建稿)。 ⚠️ IP 白名单是强校验:AppID/Secret 再对,IP 不在名单里也一律拒绝(40164)。 ⚠️ ifconfig.me 查到的 IP ≠ 微信看到的 IP。本机实测:ifconfig.me 报 223.104.86.51,微信回包报 58.248.27.68。永远以微信回包里的 IP 为准,wxmp check 会自动提取。这是最容易填错白名单的坑。 ⚠️ 白名单只接受具体 IP,不支持网段;上限 20 条。多出口网络先把 IP 全采样出来再加(见上)。 ⚠️ 重置 AppSecret 会让旧密钥立即失效。如果这个公众号还在别处(第三方平台、其他脚本)用了旧 Secret,重置会一并断掉。 🔒 AppSecret 生成后平台不再保存,忘了只能再重置一次。

长期稳定性判断

出口 IP 会随拨号/换网络变化。判断当前路线值不值得长期用:

情况建议
出口 IP 固定API 路线长期可用
2–3 个 IP 轮换且稳定全加白名单,可用;换网络后需重采
IP 频繁大幅变化 / 移动热点放弃 API 路线,改浏览器自动化(browser-skill),不依赖白名单

发布流程(四步)

# 1. 先本地看排版(不联网、不产生副作用)
wxmp build 文章.md --output /tmp/preview.html

# 2. 传封面(永久素材,返回 thumb_media_id,可复用)
wxmp thumb cover.jpg

# 3. 建草稿:正文图自动上传,返回 media_id
wxmp draft 文章.md --cover cover.jpg --author 老杨

# 4. 核对草稿箱
wxmp list

连通性冒烟测试(新账号/换网络后跑一次)

准备一个含标题、二级标题、引用、列表、表格、配图的 Markdown,跑 wxmp draft 后 wxmp list 核对。草稿总数 +1 且标题正确 = 全链路通。

删掉测试稿:wxmp delete <media_id>。

输出合同(必须向用户汇报)

每次 draft 成功后回报这 5 项:media_id / title / images_uploaded / html_chars / 「到后台检查后手动发布」。

draft 关键行为

  • 标题:默认取 front matter 的 title:,否则取第一个 # 标题;正文里的首个 H1 会被自动剔除(避免与标题重复)。可用 --title 覆盖。
  • 配图:Markdown 里 ![说明](相对路径) 的本地图 → 自动走 media/uploadimg 上传,替换为 mmbiz.qpic.cn 链接;alt 文字渲染为图注。相对路径按 Markdown 文件所在目录解析。
  • 封面:必填。--cover <路径> 或 --thumb-media-id <已有素材ID>。两者都不给会直接报错——公众号不接受无封面草稿。
  • 摘要:默认从正文剥掉标记后截前 100 字;用 --digest 覆盖。
  • 留言:--open-comment 开留言;再加 --fans-only = 仅粉丝可留言。
  • 原文链接:--source-url。

排版参数(默认就是老杨视觉规范)

参数默认含义
--h120一级标题 px
--h218二级标题 px(带左侧红条)
--h317三级标题 px
--body16正文字号 px
--indent8左右缩进 px
--accent#C0392B强调色(老杨红)

正文主色 #2B2B2B(暗炭),标题左对齐,段间距 16px,行高 1.8。改配色只需传 --accent。

支持的 Markdown 语法

标题 #~###、段落、**粗体**、*斜体*、`行内码`、[链接](url)、> 引用(渲染成浅红底卡片)、- / 1. 列表、| 表格 |(渲染成红底表头表格)、--- 分隔线、![alt](path) 图片+图注。

不支持:原始 HTML 透传、脚注、代码块高亮(代码块按普通段落处理)。

输出合同(必须向用户汇报)

每次 draft 成功后必须回报这 5 项:

字段来源
草稿 media_iddraft 返回的 media_id
文章标题实际写入的 title
上传配图数images_uploaded
HTML 字数html_chars
下一步「到公众号后台草稿箱检查,确认后手动发布」

草稿 ≠ 发布。 脚本只建草稿,绝不调用发布接口。发布必须由用户在公众号后台手动点。

🔴 合规红线(2026-09 现状,最高优先级)

规则原文

《微信公众平台运营规范》3.27 非真人自动化创作行为(2026-03-27 新增):

  • 3.27.1 脱离真实创作者表达,利用人工智能等方式生成、改写、拼接或者搬运内容
  • 3.27.2 通过脚本、程序托管等自动化方式批量、连续发布内容
  • 3.27.3 传播非真人自动化创作的教程、方法或服务

处罚:内容层面「流量限制、删除」;账号层面「能力限制、封禁」。已有真实案例——某账号因「一天内发布多篇文章」被判批量连续发布而封号(后申诉解封)。

边界划在哪

动作判定说明
API 建草稿(单篇或批量)✅ 合规草稿是私有准备区,3.27.2 管的是「发布」,不是建草稿
人工在后台逐篇发布✅ 合规官方鼓励「合理使用工具辅助创作、提升创作效率」
API 自动发布 / 定时批量发布❌ 红线直接命中 3.27.2,可致封号
一天内发布多篇❌ 高危已有误伤封号先例,即便非群发也算

本 skill 的硬边界:只建草稿,永不调用发布接口。 脚本层面就没有 publish 命令——这是刻意的设计,不要加。

🔴 但「只建草稿」不等于零风险:批量建草稿同样触发风控(见「实测教训」)。任何超过 3 篇的批量操作都必须先征得用户明确同意,且即便同意也要劝阻。

🔴 实测教训(2026-09-28,务必记住)

「批量建草稿不违规」这个判断是错的。 实测结果:

  • 65 篇草稿通过 batch-draft 在 15 分钟内全部创建成功(每个都返回了 media_id)
  • 微信风控随后实时删除,草稿数 69 → 35 → 32 → 24 → 15,约 40 分钟内删掉约 54 篇
  • 删除是静默的:无报错、无通知,draft/add 当时全部返回成功
  • 删除稳定后停止(不是删光),但账号已经暴露了自动化特征

结论:API 批量建草稿本身就是 3.27.2 的判定对象,不需要等到"发布"那一步。微信风控看的不是「有没有发布」,而是「短时间内通过接口出现的大量内容」。

因此本 skill 的批量能力必须这样用:

场景允许
单篇建草稿(日常发文节奏)✅ 正常用法
一次建 2–3 篇(比如本周要发的)⚠️ 勉强可以,间隔拉长
一次建 10 篇以上 / 任何"批量导入库存"❌ 禁止。会触发风控删除,且给账号留下自动化记录

存量稿件的正确处理方式:不要批量导入。本地管理(Markdown + 配图),发布当天才建那一篇的草稿,建完即人工发布。

发布节奏纪律(不可协商)

  • 单日 ≤ 1 篇 ← 唯一硬线,绝不可破
  • 每周删文 ≤ 2 篇(频繁删文同样判异常)
  • 每篇发布前在后台手动勾「原创」
  • 不要断更超 2 周(判低活,推荐减少 30–50%)
  • 人工逐篇发布:两条之间建议间隔 ≥ 48h(保守值,非官方明文)

实测校正:日更可行,"间隔 ≥48h" 不是硬线(2026-09-28 后台数据)

对账号「老杨拆商业」30 天后台数据的实测(窗口 2026-08-29~09-27):

  • 该账号实际已在做接近日更:09-2009-24 连续 5 天每天 1 篇、09-0109-04 连续 4 天每天 1 篇
  • 同期指标未出现任何降权痕迹:推荐占比 80.90%、取关率仅 1.8%、推荐阅读未被砍
  • 唯一一次 3 天空档(09-11~09-13)反而触发了推荐下滑

结论(修正前述表述):

动作判定
人工在后台每天发 1 篇✅ 允许(本号已自证)
单日发 ≥2 篇🔴 绝对禁止(已有真实封号先例)
API 自动发布 / 定时批量发布🔴 绝对禁止(3.27.2)

"每天 1 篇" 就是安全上限。 再往上(一天 2 篇)不是"更密",是"踩封号线"。 "间隔 ≥48h" 应作为保守建议而非硬约束——它与"日更"互斥,按账号实证优先选日更。 ⚠️ 但注意:本结论仅来自单一账号的观察性数据,不是官方规则。若更换账号或账号出现流量异常,回归保守值(≥48h)。

关于「换 Word 格式能规避 AI 检测」——无效

检测模型读的是文本内容,不是文件格式。MD→HTML→API 上传,和 Word→粘贴,最终在微信数据库里都是同一套 HTML。

换 Word 不会降低任何检测风险,只会增加重复工作量。

真正影响判定的三件事(按权重):

  1. 发布节奏与批量性 —— 权重最高,也是唯一会导致封号的因素
  2. 内容相似度 —— 与全网/自己已发内容重复度超 30% 触发降权
  3. 低创作度 —— AIGC 占比显著高于人工创作且未声明

格式层面唯一有意义的做法:同批文章的排版做出变化(不同文章的标题样式、配图密度、段落长度天然不同即可),避免 76 篇一个模子印出来的观感。但这是锦上添花,不是风控主力。

批量建草稿

🔴 先读上面「实测教训」。批量模式只保留给极小批量(≤3 篇)的日常场景,禁止用于库存导入。

# 1. 先 dry-run 盘点:看清单、缺图、无封面
wxmp batch-draft <文章目录或 manifest.json> --dry-run

# 2. 小批量执行(≤3 篇)
wxmp batch-draft <manifest.json> --delay 30 --author 老杨

# 3. 核对
wxmp list
  • --dry-run 不调任何接口,只出清单。
  • --delay 每篇间隔秒数,默认 3;小批量时请手动提到 30 以上。
  • 封面必填:脚本自动找配图目录里的 *封面*,找不到用正文首图,再没有该篇判失败。

批量操作后必须做的:wxmp list 核对数量与标题,向用户汇报「建了 N 篇、跳过 M 篇、缺图 X 张」。如果建的数量和草稿箱实际数量对不上,说明被风控删了——立即停止一切批量操作并告知用户。

封面生成(缺封面时的补齐路径)

建草稿必须有封面。文章没有封面时按此顺序补:

  1. 配图目录已有 → 扫描自动找到(~/Downloads/老杨配图/文章NN/ 里的 *封面*)
  2. 没有 → 用即梦按文章内容生成(走用户自己的火山引擎 key,不消耗 Buddy 积分):
set -a; source ~/.workbuddy/.env; set +a
node ~/.workbuddy/skills/jimeng-image-gen/scripts/jimeng.mjs generate \
  --prompt "<按文章内容定制的场景描述>" \
  --ratio 21:9 \
  --save ~/Downloads/老杨配图/文章NN/00_封面_<关键词>.png
  • 比例用 21:9(3024×1296 ≈ 2.33:1),最接近公众号封面 2.35:1 规格;不要用 16:9(裁切后左右太空)。
  • 命名必须是 00_封面_<关键词>.png,扫描逻辑靠「文件名含封面」识别。
  • 编号重复的文章(同号两篇)必须用不同 tag,否则两篇会拿到同一张封面。

封面提示词模板(老杨内容线通用):

真实摄影风格,<按文章主题定制的中国商业场景>,<光线与氛围>,商业地产纪实摄影,横版宽幅

要点:真实摄影(不是插画/3D)、国内场景、横版、画面克制不堆元素。

批量生成参考脚本:/tmp/gen_covers.sh + /tmp/cover_specs.json(规格清单 JSON:num / tag / prompt),可复用到其他账号。

编号重复文章的封面分配

同一编号有两篇文章时(如 文章51、52 各两篇),不能依赖目录自动扫描(会拿到同一张)。必须建 manifest 显式指定:

{"articles": [{"md": "/abs/文章51_劝退….md", "cover": "/abs/老杨配图/文章51/00_封面_劝退品牌.png"}, …]}

然后 wxmp batch-draft /path/manifest.json。manifest 里 cover_src 字段标记来源:spec / dir / first-image。

排错对照表

errcode原因处置
40001AppSecret 错 / token 失效核对 AppSecret;wxmp check --force
40013AppID 无效核对 AppID(wx 开头 18 位)
40164 / 53500IP 不在白名单wxmp check → 用回包 wechat_seen_ip 加白(不要 wxmp ip,实测两者不同),等 1 分钟
建出来标题是「未命名文章」md 里既没有 # 标题 也没有 front matter title:推草稿时显式传 --title;或在 md 首行加 # 标题(draft 会自动剔除正文里首个 H1)。78 有 H1 所以没事,91/92/93 没有就全变成「未命名文章」
加了白还是 40164白名单编辑没落库编辑弹窗必须点「管理员扫码确认」并扫码——只点保存直接关页面=没保存。2026-10-03 用户报了两次「已加白」、check 仍 40164,截图一看白名单里压根没有那个 IP。排障顺序:①截图看后台白名单实际条目 ②确认该条 AppID 就是本地配的那个 ③确认是扫码确认后保存 ④白名单上限 20 条,满了会静默失败(先看条数)
48001接口未授权账号未微信认证,个人订阅号无此权限
45004摘要/描述字段问题检查 digest 长度,或正文确实超长
45009调用超限等配额重置

与 md2wechat 的关系

md2wechat(已装在 ~/.local/bin/md2wechat)是第三方 SaaS CLI:排版更强(53 套主题 + 53 个排版模块),但 convert 要 MD2WECHAT_API_KEY(付费)。

本 skill 是免费替代路径:排版用本地 build,上传/建草稿走微信官方 API。

选型:

  • 日常发文、要老杨视觉规范、不想花钱 → 用 wxmp。
  • 要高级排版模块(卡片/引用框/数据条)、且愿意付 API 费用 → 用 md2wechat convert --draft。
  • 两者共用同一套 AppID/AppSecret:wxmp 读 ~/.workbuddy/.env;md2wechat 读 ~/.config/md2wechat/config.yaml。

硬边界

  • 不发布,只建草稿。 脚本没有 publish 命令,这是刻意设计。
  • 不代替用户勾「原创」——必须在后台手动勾。
  • 不推测用户公众号的账号类型与认证状态,遇到 48001 直接如实报告。
  • AppSecret 绝不写进任何报告、日志、聊天回复;输出只允许 wx1234****abcd 形式的打码。
  • 批量建草稿前必须先跑 --dry-run 并向用户确认范围。
  • 不得为规避平台风控而设计任何「绕过检测」的功能(换格式、模仿人工节奏发假发布等)——这类需求要如实告知无效并说明真实风险点。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.