wechat-mp-obsidian-archiver

name

wechat-mp-obsidian-archiver

description

Export 微信公众号 articles into an Obsidian vault starting from a single shared article link, and optionally subscribe to 公众号 for automatic incremental updates. Supports two article-list sources with automatic fallback - WeWe-RSS upstream and the wechat-article-exporter official-platform APIs. Use when the user wants to resolve a 公众号 from one mp.weixin.qq.com article URL, fetch a date-bounded historical article list, handle sparse WeWe-RSS upstream pagination, save full-text Markdown notes into Obsidian, or set up / manage auto-updating subscriptions (订阅、自动更新、追更).

WeChat MP Obsidian Archiver

Turn one mp.weixin.qq.com share link into full-text Markdown notes in an Obsidian vault — either as a one-off date-range export, or as a subscription that keeps pulling new articles automatically.

Two article-list sources are supported; full-text fetching works the same either way. source: auto (subscription default) tries WeWe-RSS first and falls back to the exporter path when it fails.

1. wewe-rss — a trusted WeWe-RSS-compatible upstream. Privacy: the login relays your WeRead session through that upstream; prefer self-hosted.
2. exporter — the mp.weixin.qq.com backend APIs used by wechat-article-exporter; needs a logged-in 公众号平台 cookie + token (any personal 订阅号 account works). Strictly rate-limited: keep intervals long, page scans small.

export WECHAT_ARCHIVER_BASE_URL="https://your-trusted-wewe-rss.example.com"

For manual API flows, sparse-page probing, and full flag documentation, read references/reference.md — only when the commands below are not enough.

Credentials (once per source; configure either or both)

WeWe-RSS — one command: prints QR (scanUrl + PNG if qrcode is installed), waits for the scan, stores credentials into the config file (chmod 600). The token never enters the conversation.

python3 scripts/wechat_subscriptions.py login --base-url "$WECHAT_ARCHIVER_BASE_URL" --wait

Exporter — also one QR command: fetches the official-platform login QR, saves it as a PNG (open it for the user to scan), polls the scan status (auto-refreshes expired QRs), and stores the session cookie + token on confirmation. Use the WeChat account that administers any personal 订阅号.

python3 scripts/wechat_subscriptions.py mp-login

Platform sessions expire after hours–days; on session expired errors just run mp-login again. (Manual fallback: setup --mp-cookie '...' --mp-token '...'.)

One-off export (default workflow)

1. Resolve the 公众号 from a share link — add --article-url does this too; for export-only use the wxs2mp call in references/reference.md.
2. Export metadata for a date range (handles sparse pages; add --page-retries 5 if pages intermittently return 0 items):

node scripts/export_wewe_articles.cjs \
  --base-url "$WECHAT_ARCHIVER_BASE_URL" \
  --mp-id MP_WXS_123 --account-name "公众号名" \
  --xid YOUR_VID --token "Bearer ..." \
  --output-dir "/abs/output/wechat-export" \
  --since 2025-01-01 --until 2026-12-31

3. Fetch full text and write notes (idempotent; reruns skip existing notes):

python3 scripts/export_wechat_fulltext_to_obsidian.py \
  --manifest "/abs/output/wechat-export/manifest.json" \
  --vault-dir "/abs/path/to/ObsidianVault" \
  --subdir "微信文章/公众号名（2025-2026）" \
  --image-mode local

Subscriptions & auto-update (optional — ask the user first)

MrRSS-style scheduling: per-subscription interval (>0 minutes fixed, -1 intelligent, 0 manual-only), watermark + id dedup (plus title+date dedup so the same article via different sources never duplicates), idempotent runs. The background sync runs via launchd with no LLM involvement.

S=scripts/wechat_subscriptions.py
python3 $S add --article-url "https://mp.weixin.qq.com/s/XXXX" \
  --vault-dir "/abs/ObsidianVault" --subdir "微信文章/公众号名" \
  --image-mode local --interval 360 --since 2026-01-01   # since = backfill start
python3 $S list                      # one line per subscription; --verbose for full state
python3 $S run [公众号名] [--due-only] # sync now; --due-only = scheduler tick
python3 $S set 公众号名 --interval -1 | --disable | --enable
python3 $S set 公众号名 --source exporter # pin a source (default auto = wewe-rss→exporter)
python3 $S remove 公众号名            # keeps exported notes
python3 $S schedule --tick-minutes 30 # writes launchd plist; user runs printed launchctl cmd

add resolves ids on every configured source (wewe mpId + exporter fakeid) so auto fallback keeps working later; list shows which source the last sync actually used (via=...). If the exporter path reports session expired, run mp-login to re-scan. Note: wxs2mp "No book found" means the 公众号 is not indexed by 微信读书 — the wewe-rss route can never work for it; use exporter.

After improving the full-text parser, rebuild existing notes from cache (no re-download) with export_wechat_fulltext_to_obsidian.py --manifest <workdir>/manifest.json --vault-dir ... --subdir ... --image-mode local --refresh-existing.

Token-efficiency rules

• Routine run / list need no Claude session — the user can run them in a terminal, and schedule makes updates fully automatic.
• Don't re-probe pages or re-derive credentials in conversation; the subscription script handles retries, dedup, and state internally.
• Read references/reference.md only when actually needed.

Resources

• scripts/wechat_subscriptions.py: QR logins (login = wewe-rss, mp-login = exporter), subscriptions, incremental sync, launchd scheduling.
• scripts/export_wewe_articles.cjs: one-off metadata export with sparse-page support.
• scripts/export_wechat_fulltext_to_obsidian.py: full text → Obsidian notes.
• references/reference.md: manual API flows and full option details.