| name | wx-mp-hunter |
| description | Search WeChat Official Accounts, retrieve the account's latest post list, and fetch full article content by URL. Also supports interactive QR-code login flow for session management. |
| metadata | {"openclaw":{"emoji":"📰","requires":{"bins":["node"]}}} |
WeChat Official Account Hunter (wx-mp-hunter)
Use this skill when:
- The user wants to search for a WeChat Official Account (公众号) by keyword
- The user wants to list the latest posts of a specific Official Account
- The user wants to fetch the full text of a WeChat article by its
mp.weixin.qq.com URL
- The user provides a
mp.weixin.qq.com/mp/homepage topic/homepage URL and wants to collect article links from that page
Does NOT support: WeChat Video Accounts (视频号), comments, or engagement metrics (those require Credentials).
⚠️ Agent 行为约束（必须遵守）
- 严格按本 SKILL.md 的步骤执行，不得在服务器结果未返回时自行编排下一步。
- 等待服务器响应：每次执行脚本命令后，必须等待脚本返回 JSON 结果。若结果需要时间，先向用户说明"正在请求服务器，请稍候……"，然后等待。
- 严禁提前假设结果：不得在脚本输出 JSON 之前就根据假设继续后续步骤。
- 批量前必须小样本验证：批量抓全文前，必须先
check，再选 1 篇文章 fetch 验证链路成功；成功后才能批量。
- 中间产物归集到专用子目录：执行过程中产生的任何中间/临时文件（命令输出落盘、解析片段、
_wx*.txt / _wx_*.txt 之类的 scratch 捕获、二维码图片等）一律写入工作区下的 wx-mp-hunter-out/ 子目录，不要散落工作区根目录。脚本本身只输出 JSON 到 stdout，凡需要落盘的中间态由你显式写到该子目录（必要时先 mkdir -p wx-mp-hunter-out）。最终交付给用户的文章 JSON/Markdown 也放该子目录。
Prerequisites
通过 PATH 调用 wrapper：wx-mp-hunter <cmd>，无需手动拼接 node 命令或脚本路径。
登录态管理：走 camoufox-cli 持久化 session wx_mp（--session wx_mp --persistent，与 wx-mp-engagement 共用同一 profile 目录与登录态，靠 session 名约定共享）。登录态在 session profile 里，无 TTL——失效时 check 命令会 exit 2 触发重登。登录就位后导出 cookie + UA + token 落中央存储：
| 文件 | 内容 |
|---|
~/.openclaw/logins/wx_mp.json | cookie（camoufox-cli cookies export 原生格式）+ token 字段（登录 redirect URL 里提的创作者中心后台 token，拼列表页 URL 用）+ ua 字段（向后兼容）+ updated_at |
~/.openclaw/logins/wx_mp.ua.json | UA + 指纹摘要（camoufox-cli identity export 输出） |
Step 0 — 登录探活
每次使用前可选地检查 session 是否有效：
wx-mp-hunter check
| 返回值 | 含义 |
|---|
{"ok": true} | session 有效，可直接使用 |
{"ok": false, "error": "SESSION_EXPIRED"} (exit 2) | 需要重新登录 |
check 走纯 HTTP _ping（不起浏览器）：带 cookie+token GET mp.weixin.qq.com/cgi-bin/home?t=home/index&token=<token>，解析返回 HTML 的 <h2>——含「新的创作」= 有效，含「请重新登录」/scanloginqrcode = 失效。cookie + token 从中央存储 wx_mp.json 读。
自动重新登录流程（Session 过期时触发）
触发条件：任意命令返回 "error": "SESSION_EXPIRED"（exit code 2），或首次使用无 session 文件。
第 1 步 — 无头截二维码
wx-mp-hunter login
脚本内部走 camoufox-cli：--session wx_mp --persistent open "https://mp.weixin.qq.com/"（默认 headless）+ screenshot /tmp/qr-wx-mp.png，不 close session（仅此一处例外：留给紧接的 login-confirm 复用同一进程，login-confirm 导出后即 close）。等待脚本输出 JSON：
{
"ok": true,
"qr_path": "/tmp/qr-wx-mp.png",
"message": "二维码已截，请用微信（公众号管理员账号）扫码，完成后运行 login-confirm"
}
第 2 步 — 将二维码发给用户
将二维码图直接发送给用户。
不要只发本地文件路径——用户在飞书客户端中无法访问 agent 本地文件系统。
同时告知用户：
"公众号 Cookie 已失效，请用微信（公众号管理员账号）扫描以下二维码重新授权。扫码并点击确认登录后，回复"已扫码"。"
第 3 步 — 等待用户确认
停止执行，等待用户回复。 用户回复"已扫码"、"好了"、"扫完了"或类似确认语即可继续。
第 4 步 — 确认登录 + 导出 cookie + UA + token
wx-mp-hunter login-confirm
脚本内部走 camoufox-cli：复用已开的 wx_mp session open "https://mp.weixin.qq.com/" → eval window.location.href 读 redirect URL 验登录态就位（跳到 /cgi-bin/home?...&token=xxx = 就位）→ 从 URL 提 token → cookies export 到临时文件 → _ping 验证 cookie+token 真能用（后台首页返回「新的创作」）才 commit → 写 ~/.openclaw/logins/wx_mp.json（cookie + token + ua + updated_at 同文件）+ identity export ~/.openclaw/logins/wx_mp.ua.json → close session（登录态已落磁盘 profile + 中央存储，wx-mp-engagement 下次 --session wx_mp --persistent 重起无头即恢复，不留进程占内存）。验证不过直接报错、不写中央存储、不重试（避免风控）。等待脚本返回：
{"ok": true, "message": "登录成功，cookie + UA + token 已落中央存储（session 已关，登录态在磁盘 profile）", "token": "..."}
| 情况 | 处理 |
|---|
{"ok": true} | 继续执行原来被中断的任务 |
ret != 0 或超时 | 重新从第 1 步开始，告知用户二维码已过期 |
两条独立工作流
fetch 和 search + account-posts 是相互独立的两条路径，可单独使用：
流程 0：登录探活（每次使用前可选）
└─ check
流程 1a：搜索账号 → 获取最新发布列表
├─ search <keyword> → 获取 fakeid
└─ account-posts <fakeid> → 获取该账号最新发布文章列表
流程 1b：直接获取指定文章内容（URL 来源不限）
└─ fetch <url> → 获取正文
流程 1c：专题页/主页目录链接采集（mp/homepage）
└─ camoufox-cli 完整滚动页面和分类 → 提取 mp.weixin.qq.com/s 文章链接 → 如需全文再逐篇 fetch
当用户直接提供 mp.weixin.qq.com 文章链接时，直接走流程 1b，无需经过 search / account-posts。
当用户提供的是 mp.weixin.qq.com/mp/homepage 专题页/主页链接时，当前 CLI 不支持直接列出该页面全部文章；必须按“专题页抓取流程”使用 camoufox-cli 完整采集目录，再对单篇链接使用 fetch。
专题页抓取流程（mp/homepage）
触发条件：用户提供类似以下 URL，并要求抓取该页面/专题/合集里的文章：
https://mp.weixin.qq.com/mp/homepage?...
http://mp.weixin.qq.com/mp/homepage?...
目录采集
- 不要直接承诺“已抓完全部文章”。先说明该页面是微信动态专题页，需要完整滚动加载后统计。
- 使用 camoufox-cli 打开专题页（headless session，操作要点：snapshot 拿 ref → eval 滚动/提取，别自己 hack selector）。
- 先执行整页滚动到底，直到
document.documentElement.scrollHeight 连续多次稳定。
- 查找分类 tab（常见 class：
.jsCate）。对每个分类逐个执行：
- 点击分类；
- 等待内容加载；
- 从顶部滚动到底，直到高度稳定；
- 提取所有
a[href*="mp.weixin.qq.com/s"] 的标题和链接。
- 合并顶部推荐与各分类结果，按 URL 去重。
- 向用户报告：分类列表、原始链接数、去重文章数；如果数量明显偏少，继续滚动或请用户确认页面是否还存在折叠/下拉区域。
全文采集
- 批量抓全文前，必须先运行：
wx-mp-hunter check
- 如果返回
SESSION_EXPIRED，先执行自动重新登录流程。
- 登录有效后，只选 1 篇样本运行：
wx-mp-hunter fetch <article_link> --html
- 只有样本返回
content_text / content_markdown / content_html 后，才允许批量抓全文。
- 如果样本返回
未找到文章正文 (#js_content)，用 camoufox-cli 打开该文章验证页面内容：
- 如果出现“环境异常”“拖动下方滑块完成拼图”等验证页，不得尝试绕过验证码或自动拖滑块；告知用户需要人工完成微信环境验证后再继续。
- 如果是文章已删除、私有或付费，跳过该文章并记录失败原因。
- 批量抓取时每篇间隔 1–2 秒；连续失败 3 篇以上时停止批量，先检查错误，不要继续跑完整列表。
命令详解
search — 搜索公众号
wx-mp-hunter search <keyword> [--begin N] [--size N]
| Option | Default | Description |
|---|
keyword | required | 搜索词（账号名或别名） |
--begin | 0 | 分页偏移 |
--size | 10 | 每页数量（最大 20） |
输出示例：
{
"total": 3,
"accounts": [
{
"fakeid": "MzA3NzAyMzMyMA==",
"nickname": "Python之禅",
"alias": "the_zen_of_python",
"signature": "...",
"service_type": 0,
"avatar": "https://..."
}
]
}
注意：保存 fakeid，后续 account-posts 命令需要它。
service_type：0 = 订阅号，2 = 服务号。
account-posts — 获取指定账号最新发布列表
原命令名 articles 仍可用（向后兼容），推荐使用 account-posts。
wx-mp-hunter account-posts <fakeid> [--begin N] [--size N] [--keyword K]
| Option | Default | Description |
|---|
fakeid | required | 来自 search 结果 |
--begin | 0 | 分页偏移（每页 20，依次传 0、20、40…） |
--size | 20 | 每页数量（最大 20） |
--keyword | "" | 按标题关键词过滤 |
输出示例：
{
"total": 312,
"begin": 0,
"size": 20,
"articles": [
{
"aid": "2247483649_1",
"title": "文章标题",
"link": "https://mp.weixin.qq.com/s/xxxxx",
"digest": "文章摘要",
"author": "作者名",
"create_time": 1710000000,
"cover": "https://...",
"item_show_type": 0,
"is_deleted": false,
"is_pay_subscribe": 0,
"wecoin_count": 0
}
]
}
分页：循环传入 --begin 0、--begin 20… 直到 articles 为空或 begin >= total。
item_show_type：0/1 = 图文，5 = 视频，6 = 音乐，8 = 图片帖。
is_pay_subscribe：0 = 免费，1 = 付费文章（直接 fetch 正文需要公众号管理员 Credential，本 skill 不支持）。wecoin_count 为对应的微信豆价格。
重要：请求间隔保持 1–2 秒，避免连续快速请求。
fetch — 获取文章全文
wx-mp-hunter fetch <url> [--html]
| Option | Description |
|---|
url | 文章链接（mp.weixin.qq.com） |
--html | 同时返回正文原始 HTML |
--download-images | 把正文图片下载到本地，content_markdown 中的图片 URL 替换为本地相对路径 |
--output-dir <dir> | 图片下载目标目录（配合 --download-images；默认当前目录） |
输出示例：
{
"url": "https://mp.weixin.qq.com/s/xxxxx",
"title": "文章标题",
"author": "公众号名称",
"publish_time": "2024-03-10",
"content_text": "正文纯文本内容...",
"content_markdown": "段落文字……\n\n\n\n继续文字……**加粗**……",
"images": [
"https://mmbiz.qpic.cn/mmbiz_jpg/xxxxx/0?wx_fmt=jpeg",
"https://mmbiz.qpic.cn/mmbiz_png/xxxxx/0?wx_fmt=png"
]
}
| 字段 | 说明 |
|---|
content_text | 纯文本正文（去除所有 HTML 标签） |
content_markdown | Markdown 格式正文，图片以内联  放在原文位置，保留加粗/斜体/链接；--download-images 时 URL 替换为 images/<hash>.<ext> 本地相对路径 |
images | 正文所有图片 CDN 链接（从 data-src 解析） |
图片本地化
加 --download-images --output-dir <dir> 后，脚本并发下载（默认 4 并发、单图 ≤5MB、总量 ≤100MB、单图失败重试 1 次）到 <dir>/images/<hash>.<ext>，并把 content_markdown 里的图片 URL 替换为本地相对路径，便于离线阅读 / 二次加工 / 转存。仅依赖 Node 18+ stdlib，无 npm 依赖。
wx-mp-hunter fetch <url> --html --download-images --output-dir ./article-out
典型用法示例
场景 A：监控某账号最新文章
1. check → 探活
2. search "公众号名" → 得到 fakeid
3. account-posts <fakeid> → 得到文章列表（第 1 页）
4. fetch <article_link> → 获取感兴趣文章的正文
场景 B：直接抓取已知 URL 的文章
1. check → 探活
2. fetch <url> → 直接获取正文
场景 C：批量获取
loop account-posts --begin 0, 20, 40, ...
for each article link: fetch <link>
pause 1-2s between requests
错误处理
| Error | 原因 | 处理 |
|---|
未登录 | 无 session 文件 | 执行登录流程 |
"error": "SESSION_EXPIRED" (exit 2) | camoufox-cli open 首页后 redirect URL 跳到 login / scanloginqrcode（登录态失效）或无 session 文件 | 执行自动重新登录流程（login → 用户扫码 → login-confirm） |
API 错误 (ret=...) | 微信 API 错误 | 检查网络，重试一次 |
HTTP 4xx on fetch | 文章已删除或私有 | 跳过该文章 |
