/moore-wechat-article-downloader

name: moore-wechat-article-downloader
description: 当用户要下载或管理微信公众号文章时使用本技能。支持订阅同步、微信收藏和链接导入；互动数据仅在用户微信短时会话有效时补充指标与精选评论。优先本地运行；不要扩展成内容改写、总结、SaaS 或云服务。

公众号归档器

场景判断

| 用户意图 | 场景 | 入口 | |---------|------|------| | 提供了完整文章 URL | 场景 1：直接下载 | `wechat_wizard.py run "下载：<url>"` | | 给公众号名 / 样例 URL，想要历史文章 | 场景 2A：Exporter（默认） | `wechat_wizard.py run "历史文章：<名称或URL>"` | | 明确说"不登录"或"用代理" | 场景 2B：代理（备选） | `wechat_wizard.py run "代理历史：<url>"` | | 想抓评论/阅读/点赞/页面风格 | 场景 2C：微信收藏 | `wechat_downloader.py proxy-enhancer-session-start --yes` | | 管理多个公众号 / 定时同步 | 场景 3：订阅同步 | 见场景 3 |

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

| Gate | 处理 | |------|------| | `need_login` | 引导扫码 → `login-status` 轮询 → `login-complete` 恢复任务 | | `need_proxy_confirm` | 向用户确认启用系统代理 → 确认后继续 | | `need_account_choice` | 聊天中列出候选公众号 → `resume --choice "<序号>"` | | `need_article_choice` | 聊天中列出文章标题+日期 → `resume --choice "<选择>"` |

只有 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`、`deco