WeChat Article Downloader

公众号归档器

场景判断

统一入口优先。wizard 返回以下 gate 时按表处理，不要立刻降级为底层命令：

只有 wizard 返回 blocked 或 failed_recoverable 并明确给出底层命令时，才使用底层命令。

范围

可以做：下载公开的 mp.weixin.qq.com 文章、抓取历史文章列表、Exporter 扫码登录和账号管理、定时增量同步。

不要做：绕过登录/付费墙/私密内容；打印 auth-key/cookie/token；把历史列表抓取和 URL 下载混为一谈；扩展成内容改写、总结、SaaS。

执行护栏

• 不要把命令成功等同于交付完整：success_count 只表示流程没有抛错。结束前必须检查 index.csv、Markdown、图片目录和源页面状态。
• 不要只给二维码文件路径：生成或复用二维码后优先调用当前操作系统的默认看图程序直接打开。只有无桌面环境或系统打开失败时，才退回聊天图片展示；裸路径只能作为最后兜底。同一未完成登录会话只打开一次，二维码过期后才重新生成。
• 扫码流程不能少步骤：用户说“已扫码”后先运行 exporter-login-qr-status；只有状态为 confirmed / ready_to_complete=true 才运行 exporter-login-qr-complete。
• 搜索结果必须精确匹配：公众号搜索可能返回多个相似名称。优先选择昵称完全一致的结果，并核对简介或 alias；不要默认使用第一个模糊匹配结果。
• 已有明确选择时不要重复询问：用户已经说“最新 N 篇”或给出标题/日期时，该表达本身就是文章选择；同步后直接执行，但结束时仍要在聊天中列出日期、标题和结果。

场景 1：直接下载已知文章

触发：用户提供一篇或多篇完整文章 URL，或 .txt/.csv/.json 文件。

python3 {baseDir}/scripts/wechat_wizard.py run "下载：<url 或文件路径>"

重跑会跳过已成功的 URL。失败项重试：

python3 {baseDir}/scripts/wechat_wizard.py retry "<task-id>"

下载完成后报告：成功数量、失败数量、失败 URL（如有）、output_dir、index.csv。

场景 2：公众号历史文章

2A. Exporter 模式（默认首选）

触发：用户提供公众号名、关键词或样例文章 URL，想要历史文章列表。

优势：API 稳定、无需代理、支持按名称搜索、一次登录 4 天有效、SQLite 持久化可复用。

边界：Exporter 模式只做公众号搜索、历史文章同步和文章下载；不获取评论、阅读数、点赞数、收藏数、转发数等互动数据。互动数据只在代理快照模式验证通过后再提供。

带评论/互动数据的硬规则：

• 普通下载：exporter-sync -> exporter-download，只用于不带评论/互动数据的正文下载。
• 带评论互动下载：exporter-sync -> engagement batch download。
• 当用户需求包含“评论 / 互动 / 阅读数 / 点赞 / 在看 / 精选评论”时，禁止先调用普通 exporter-download。
• 此时 Exporter 只负责同步文章列表、标题、日期和 URL；正文与互动数据由 wechat-collection-sync-engagement / wizard 的 engagement 批量任务处理。
• 文章落盘只发生一次：成功拿到互动数据后生成最终 Markdown；如果某篇互动失败，再降级写正文并标记“互动数据缺失”。

python3 {baseDir}/scripts/wechat_wizard.py run "获取公众号「<名称>」的历史文章"

wizard 自动处理：检查登录 → 搜索公众号 → 同步文章 → 列出结果。

文章列表展示（强制要求）：

抓取完成后必须在聊天中直接罗列，格式：

- **YYYY-MM-DD**：文章标题

不要只给 CSV/JSON 路径。不要只给编号，必须同时展示标题和日期。

让用户按标题关键词、日期、最新 N 篇或编号范围选择后再下载。

2B. 代理模式（备选）

触发：用户明确说"不登录"或"用代理"，或 Exporter 模式失败。

python3 {baseDir}/scripts/wechat_wizard.py run "代理历史：<sample-article-url>"

硬性规则：

• 必须使用旧版历史入口：https://mp.weixin.qq.com/mp/profile_ext?action=home&__biz=<biz>&scene=124#wechat_redirect
• 不要引导用户使用 channels.weixin.qq.com/web/pages/mp_profile（视频号壳页，不触发 getmsg 接口）
• 启用系统代理前必须向用户确认；结束时必须用 history-capture-finish 恢复系统代理
• 默认使用常驻本地代理 127.0.0.1:23344；切换公众号时不要停止代理服务，直接运行新的 history-capture-prepare 复用进程

告诉用户：把旧版入口发到微信文件传输助手，用桌面客户端内置浏览器打开，看到历史列表后向下滚动。

2C. 微信收藏（互动数据与页面保存）

触发：用户要评论、阅读数、点赞数、收藏数、在看数、完整页面快照、公众号排版风格。

此模式保存用户当前浏览的文章，也可在短时凭证有效期内恢复同公众号已授权任务的互动同步。历史列表仍默认走 Exporter；旧代理历史列表只作为备用。只同步精选评论，不承诺全量评论或完整回复树。

批量互动任务必须使用已经同步出的文章列表和 URL 创建，不要先用普通 Exporter 下载正文。用户说“下载某公众号最新 N 篇文章的评论和互动数据”时，正确链路是：

exporter-sync -> engagement batch download

主流程不再使用 proxy-snapshot-prepare --yes。

每次新会话从 23032-24045 选择一个空闲随机端口。启动前先固定当前 upstream，再启动增强代理并切换系统 HTTP/HTTPS 代理。端口、PID、upstream 和恢复状态写入活动会话；同一会话安全重载时必须复用这些值。

启动成功后会终止旧的微信 WeChatAppEx WebView 进程。微信主进程和登录状态保持不变；用户下次打开文章时，微信会创建使用当前代理的新 WebView。代理增强代码安全重载后也执行同样的 WebView 重置，避免旧进程继续使用缓存页面。

系统/微信 -> 127.0.0.1:<会话端口> -> 会话启动时确定的上游代理或直连 -> 外网

启动命令：

python3 {baseDir}/scripts/wechat_downloader.py proxy-enhancer-session-start --upstream-proxy none --yes

如果修改了代理增强代码或需要重载，只能使用安全重载。该命令自动读取并复用活动端口与 upstream：

python3 {baseDir}/scripts/wechat_downloader.py proxy-enhancer-restart --upstream-proxy none --yes

不要在系统代理指向活动端口时直接 kill、proxy-enhancer-stop 或 stop && start；这会让系统代理指向死端口。安全重载会临时恢复上游或直连，使用原端口重启，再切回活动端口。

启动后常见链路：

系统/微信 -> 127.0.0.1:<会话端口> -> 启动时确定的上游代理 -> 外网

以下命令自动读取活动端口，不要手工猜端口：

python3 {baseDir}/scripts/wechat_downloader.py proxy-enhancer-route-help
python3 {baseDir}/scripts/wechat_downloader.py proxy-enhancer-check-ingress --minutes 10
python3 {baseDir}/scripts/wechat_downloader.py proxy-enhancer-logs --hours 24 --limit 80
python3 {baseDir}/scripts/wechat_downloader.py proxy-enhancer-video-links --hours 24 --limit 100

增强代理常驻期间会额外捕获公开的 channels.weixin.qq.com 视频号页面地址，写入 proxy-snapshots/video-links.jsonl。只提供页面链接，不下载视频；禁止保存或展示 finder.video.qq.com 临时媒体地址以及 token、ticket、exportkey、session、auth 等签名凭证。

视频号链接捕获规则：

• 必须先启动再浏览：常驻拦截只能捕获启动后的流量，不能追溯之前打开过的视频号页面。
• 先确认流量进入代理：启动后运行 proxy-enhancer-check-ingress；确认微信流量到达，再让用户在微信里打开视频号卡片或页面。
• 只保存可复用页面链接：仅保留脱敏后的 channels.weixin.qq.com 页面 URL；finder.video.qq.com 通常是短时签名媒体地址，不作为结果。
• 没有结果不代表没有视频：可能是页面未重新打开、流量未经过代理、链接只存在于客户端内部状态，或公开链接依赖已过滤的临时凭证。报告时必须说明是哪一层没有观察到。
• 结束时恢复系统代理：用户明确结束常驻拦截后运行 proxy-enhancer-session-finish --yes，避免系统继续指向已停止的本地端口。

视频下载入口：

• Exporter 直接下载：先运行常驻增强代理并打开目标视频页完成短时媒体凭证捕获，再执行 python3 {baseDir}/scripts/wechat_exporter.py exporter-download --account-id <id> --latest <N> --include-video --video-quality highest。输出在账号目录 videos/ 下，文件名前缀为 [视频]。
• 视频号页面按钮：常驻增强代理会尝试在 channels.weixin.qq.com/web/pages/... 页面注入“下载视频”按钮；按钮只在用户当前有权限播放、页面 JS 暴露 objectDesc.media[] 后可下载。
• 无凭证必须明示：Exporter 未发现活跃代理或匹配的短时媒体描述时返回 needs_capture，不得报告视频下载成功。处理方式是保持/启动 proxy-enhancer-session-start --yes，重新打开目标视频页，等按钮显示“下载视频”后再重跑。
• 敏感字段只留内存：urlToken、decodeKey、签名媒体 URL、Cookie 和请求头只在代理进程内短时保存和下载使用；禁止写入 SQLite、Markdown、JSONL、调试日志或聊天输出。结果只报告页面 URL、descriptor id、文件路径、大小、是否解密。
• 能力边界：不绕过私密、付费或 DRM 内容；只下载用户当前会话能播放的公开视频。加密视频会按 decodeKey 生成 128 KiB key stream 并 XOR 文件头，失败时标记 failed / decrypt_failed。

调试日志位于 ~/.moore/wechat-article-downloader/proxy-snapshots/debug.jsonl，只记录脱敏事件：请求路径、响应状态、是否识别为文章页、是否注入脚本、页面脚本是否执行、按钮是否放置成功。日志只保留 24 小时；清理动作每 12 小时最多执行一次。

成功识别并注入的文章 HTML 响应必须写入 Cache-Control: no-store，并移除 ETag / Last-Modified，防止微信 WebView 在下一次会话继续复用未更新的注入代码。已禁用的系统代理状态视为没有 endpoint；不要保存或展示其残留的 server/port。

不要在用户点击保存后自动恢复系统代理。只有用户明确要求恢复时才运行：

python3 {baseDir}/scripts/wechat_downloader.py proxy-enhancer-session-finish --yes

该命令先恢复系统代理，再停止并回收本次会话的随机端口进程。

用户之后正常打开公众号文章。页面加载完成后应自动出现注入按钮：顶部元信息行一个，评论区标题旁一个，点击任意一个都会保存当前文章现场。

收藏到本地

用户点击后读取最近快照：

python3 {baseDir}/scripts/wechat_downloader.py snapshot-latest
python3 {baseDir}/scripts/wechat_downloader.py snapshot-list --limit 10

如果用户说“已保存”“处理刚才保存的快照”“整理今天保存的快照”，默认不要只处理 latest。先看快照收件箱，再把所有未处理快照归档到文章库：

python3 {baseDir}/scripts/wechat_downloader.py snapshot-inbox --limit 50
python3 {baseDir}/scripts/wechat_downloader.py snapshot-attach --all-unprocessed

归档规则：

• 已下载过的文章：按 URL/微信文章参数匹配，增强数据放到对应公众号目录。
• 没下载过的文章：从快照正文生成 Markdown，也放到 ~/Downloads/wechat-articles/<公众号名>/。
• 评论、阅读数、点赞数、收藏数等页面数据必须写进文章 Markdown 的 ## 页面数据 区块；同一篇文章重复归档时替换旧区块，不重复追加。
• 同一篇文章多次保存：保留每次快照，并更新 latest.json 和 metrics_history.jsonl。
• 不递归复制原始快照目录；只归档结构化提取产物，避免把敏感或调试文件带进文章库。

把最近快照提取成后续处理用的结构化文件：

python3 {baseDir}/scripts/wechat_downloader.py snapshot-extract latest

也可以指定快照：

python3 {baseDir}/scripts/wechat_downloader.py snapshot-extract <snapshot-id> --output-dir <dir>

输出位于：

~/.moore/wechat-article-downloader/proxy-snapshots/<snapshot-id>/

主要文件：

• snapshot.json：DOM 快照和基础字段
• dom.html：脱敏后的完整页面 DOM
• js_content.html：正文 DOM
• comments_dom.html：页面已渲染评论 DOM
• engagement_dom.html：互动区域 DOM
• metrics.json：阅读、点赞、在看、评论、收藏、分享的可观察结果
• network.jsonl：脱敏后的网络响应摘要
• style_profile.json / style_summary.md：页面风格摘要
• report.md：本次快照报告

snapshot-extract 默认输出到 <snapshot-dir>/extracted/：

• article.md：正文 Markdown
• comments.json：已加载评论文本和原始评论 DOM，complete=false
• comments_structured.json：结构化评论，包含昵称、地区/时间、点赞、回复数、内容
• metrics.json：可观察互动数据
• style_profile.json：页面风格特征
• image_urls.json：正文图片 URL 列表
• engagement.html：互动区域 DOM
• report.md：提取报告

规则：不承诺一定拿到所有互动字段；页面未暴露时必须标记 missing。不要保存或打印 cookie、auth-key、token、pass_ticket、key 等敏感值。

文章落盘规则：标题和 Markdown 文件名必须带 [图文] 或 [贴图] 前缀；微信 item_show_type=8 判定为贴图，其他文章判定为图文。贴图 Markdown 先集中输出全部图片，再输出文字内容。