wxmp-article-harvester

wxmp-article-harvester

目的：将公开的公众号文章稳定地处理成本地资料包，使其可检索、可审计、可恢复。

実行アーキテクチャ

1. preflight.py は依存関係のみを確認し、ソフトウェアの自動インストールやアップグレードは行いません。
2. wcx_run.py は公众号を検索し、ログイン状態を更新して、メタデータを取得し、インデックスをエクスポートします。
3. harvest_wxmp.py は日付とタイトルで絞り込み、Playwright のコンテキストを 1 つ再利用して本文を抽出し、画像の順序を保持します。
4. WeChat の CAPTCHA またはリスク管理ページに初めて遭遇した時点でブラウザーを開いてサーキットブレーカーを作動させ、この実行での後続ページリクエストを停止します。更新に失敗した場合は、品質ゲートを通過済みの古い本文を保持します。
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 を検証します。
• 本文のみを補完する場合や再絞り込みを行う場合は、WeChat のレート制限を繰り返し受けないよう --skip-fetch を追加します。
• デフォルトでは Metaso を呼び出しません。ユーザーが有料利用と記事 URL の第三者への送信を明示的に承諾した場合に限り、--allow-metaso を使用します。
• wcx の要約プレースホルダー、正文尚未抓取、WeChat ページの外枠、汎用の 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 を参照してください。