wxmp-article-harvester
目标：把公开公众号文章稳定加工成可检索、可审计、可恢复的本地资料包。
运行架构
preflight.py只检查依赖，不自动安装或升级任何软件。wcx_run.py搜索公众号、刷新登录态、抓元数据并导出索引。harvest_wxmp.py过滤日期和标题，复用一个 Playwright 上下文提取正文并保留图片顺序。- 首次命中微信验证码或风控页后打开浏览器熔断，停止本轮后续页面请求；刷新失败时保留已通过质量门的旧正文。
- 没有可信正文时标记
partial。只有用户明确授权付费和第三方 URL 传输后，才加--allow-metaso。
开始前
运行预检：
bashpython3 <skill-root>/scripts/preflight.py --json
缺少依赖时明确报告并停止。安装命令见 README.md。登录过期由 wcx_run.py 打开浏览器刷新一次；token 不打印，cookie 不进入进程参数。
意图路由
| 用户意图 | 执行 |
|---|---|
| 搜索公众号 | python3 scripts/wcx_run.py -- search "账号名" |
| 最近文章索引 | python3 scripts/harvest_wxmp.py --account "账号名" --limit 50 --no-fulltext |
| 日期范围全文 | python3 scripts/harvest_wxmp.py --account "账号名" --from-date YYYY-MM-DD --to-date YYYY-MM-DD --fulltext |
| 教程类文章 | 在日期范围命令后加 `--title-regex '(教程 |
| 年度/深历史 | 首轮加 --batch，冷却后只用 --resume；状态会恢复账号、范围和全文策略 |
| 保存单篇链接 | python3 scripts/browser_reader.py --url "https://mp.weixin.qq.com/s/..." --output-dir "目录" |
没有指定数量时默认最近 50 篇。最近 N 天默认最多取 min(N × 8, 80) 篇元数据。
硬规则
- 只接受
https://mp.weixin.qq.com/s...公开文章链接；拒绝其他域名、协议和带用户信息的 URL。 - 所有
wcx search/fetch/list/export/status都走wcx_run.py。运行时禁止自动pip install或强制升级。 --limit、--batch-size的代码硬上限都是 80。深历史任务使用 offset 游标分批，每轮最多 80 篇，并校验远端总数、头部文章 ID 和上一批边界 ID。- 只补正文或重新筛选时加
--skip-fetch，避免重复触发微信频控。 - 默认不调用 Metaso。用户明确接受付费和把文章 URL 发给第三方后，才使用
--allow-metaso。 wcx摘要占位、正文尚未抓取、微信页面壳、通用Video页面和低信息量结果都不能标记成功。- 正文成功后同步更新标题、页面发布时间、作者、来源 URL 和提取通道。索引保存相对路径，迁移目录后仍可用。
- 默认输出到系统用户数据目录下的
wxmp-article-harvester/exports/<公众号>/；可用WXMP_HARVEST_HOME覆盖。 - 文章仅用于用户授权的研究、学习和归档。保留原文 URL、作者和发布时间；不把抓取结果包装成可再分发版权。
分批与恢复
bash# 第一轮：按真实 offset 抓一批 python3 scripts/harvest_wxmp.py --account "账号名" --year 2025 --fulltext --batch --batch-size 60 # 到达 .harvest-state.json 的 resume_after 后继续 python3 scripts/harvest_wxmp.py --resume
存在多个待恢复账号时，--resume 会停止并要求补 --account 或 --output-dir。监控 JSON 中的 status、task_id 和 batch.completion_reason；complete 才代表本次契约完成，cursor_drift 必须停止并重新建任务。
常用命令
bash# 最近 30 天全文，默认不使用付费兜底 python3 scripts/harvest_wxmp.py --account "账号名" --since 30d --fulltext # 精确日期范围 + 教程标题筛选 python3 scripts/harvest_wxmp.py --account "账号名" \ --from-date 2026-06-25 --to-date 2026-07-25 --fulltext \ --title-regex '(教程|手把手|教你|技巧|实操|实践|工作流)' # 已有索引，只补正文；用户已明确授权 Metaso python3 scripts/harvest_wxmp.py --account "账号名" --skip-fetch --fulltext --allow-metaso
输出契约
index.json、index.csv、index.md：文章元数据、相对路径、状态和失败原因。articles/*.md：保留原文 URL、发布时间、作者、提取通道以及正文中的图片顺序。harvest-report.md：success、partial、failed分开统计；任何页面壳或摘要占位进入 unresolved。.harvest-state.json：稳定任务 ID、配置指纹、批次 offset、远端头/边界 ID、范围、完成原因、全文策略、Metaso 授权和冷却状态。
回执必须说明保存目录、成功/部分/失败数量、报告路径和未解决文章。排障时读取 references/troubleshooting.md。
