mcpField
W
wxmp-article-harvester

wxmp-article-harvester

github.com/zjp1997720Productivity78652 installsUpdated 2d ago
Repository

About wxmp-article-harvester

wxmp-article-harvester packages public WeChat Official Account articles as local files for research, study, and archiving. It retains article metadata and image order, with batch processing, task state, and resume support.

Key features

  1. 01Search accounts and export article indexes
  2. 02Filter articles by date and title
  3. 03Extract text while preserving image order
  4. 04Process batches and resume tasks
  5. 05Report successful, partial, and failed results

Use cases

  1. 01Build a local index of account articles
  2. 02Collect full text within a date range
  3. 03Filter and archive tutorial articles
  4. 04Resume an interrupted historical collection

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/zjp1997720/zhijian-skills --skill wxmp-article-harvester

After installing, type/wxmp-article-harvesterin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
evals/
evals.json
references/
troubleshooting.md
scripts/
browser_reader.py
harvest_wxmp.py
metaso_reader.py
preflight.py
refresh_token_playwright.py
runtime_paths.py
wcx_batch_fetch.py
wcx_run.py
tests/
test_harvester.py

Details

From the project README

wxmp-article-harvester

目标：把公开公众号文章稳定加工成可检索、可审计、可恢复的本地资料包。

运行架构

  1. preflight.py 只检查依赖，不自动安装或升级任何软件。
  2. wcx_run.py 搜索公众号、刷新登录态、抓元数据并导出索引。
  3. harvest_wxmp.py 过滤日期和标题，复用一个 Playwright 上下文提取正文并保留图片顺序。
  4. 首次命中微信验证码或风控页后打开浏览器熔断，停止本轮后续页面请求；刷新失败时保留已通过质量门的旧正文。
  5. 没有可信正文时标记 partial。只有用户明确授权付费和第三方 URL 传输后，才加 --allow-metaso。

开始前

运行预检：

python3 <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、作者和发布时间；不把抓取结果包装成可再分发版权。

分批与恢复

# 第一轮：按真实 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 必须停止并重新建任务。

常用命令

# 最近 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。

Comments

Markdown supported