用途
本技能用于批量归档用户自己管理的微信公众号已发文章到 Obsidian vault。它与单篇归档技能 soia-pkm-clip-wechat-article（贴 URL 归档一篇）互补：本技能处理「把我自己公众号的历史文章一次性拉进 vault」的批量场景。仅适用于归档你自己管理的公众号，不是通用的公众号爬虫。
触发方式
Triggers：「同步我的公众号」「批量拉取我公众号历史文章」「批量归档我的公众号」「导入公众号已发文章」「clip 我的公众号」。
三条路线
技能支持三条路线获取文章列表，各有覆盖范围和账号要求：
- 路 A · 官方 API（scripts/fetch_api.py）：使用 developers.weixin.qq.com 有文档的接口，需已认证服务号/订阅号，凭据为 AppID/AppSecret（长期有效，需 IP 白名单）。覆盖范围仅限通过草稿箱「发布」发出的文章；走群发但未点过发布的内容、以及草稿箱上线前的旧版图文，官方目前无 API 可获取。
- 路 C · 公众号后台接口（scripts/fetch_mp.py，推荐）：复用 mp.weixin.qq.com 后台作者端接口，任意公众号只要你能登录后台即可，能读全部历史（含手动群发的老文），凭据只需抓一对 token/Cookie，比路 B 更不易出错。
- 路 B · 登录态 Cookie（scripts/fetch_cookie.py）：非官方、社区逆向路线，任意公众号只要你能登录后台即可，读全部历史，凭据为 key/pass_ticket/appmsg_token，几小时到几天过期，需配对三个票据。作为路 C 失效时的备选。
建议：先跑路 A 探路（凭据一次配置，可长期用于增量同步，但多数个人未认证号会卡在权限门槛）。要读全部历史优先用路 C，路 B 作为备选。三条路都只在自己能登录/管理的账号上跑，落地时按 url 自动去重。
路 C 内部有两条子路径，脚本按是否传 --name/--fakeid 自动切换：不传（默认）走 appmsgpublish，读你自己当前登录的号；传了 --name/--fakeid 才走 searchbiz+appmsg，读指定/别人的号。
执行前确认与授权
正式抓正文/写文件前，先用 --dry-run --limit 3 之类的小样本探路，报告预计处理的公众号、篇数量级与时间范围，客户确认范围无误后再放开全量。
路 B / 路 C 走公众号后台非官方接口，存在 ToS 风险。首次使用或声明版本变化时，需展示声明并取得客户显式同意，同意后写入 consent.json（{accepted: true, acceptedAt: <ISO 时间戳>, disclaimerVersion: "v1"}，与 config.yml 同级）。客户拒绝则停止，不执行任何抓取动作。路 A 不受此 consent 约束。
安装
安装本技能（单个技能）：
npx skills add soia-team/soia-open-pkm-clip-skills -g -a '*' -s soia-pkm-clip-wechat-account -y
配置
配置约定：
~/.config/soia-skills/soia-pkm-clip-wechat-account/config.yml SOIA_PKM_CLIP_WECHAT_ACCOUNT_CONFIG_FILE=<custom-config-path>
兼容别名：$SOIA_PKM_CLIP_GZH_CONFIG_FILE（以及原有 $SOIA_PKM_CLIP_GZH_ENV_FILE）
如不需私有配置可不创建 config.yml。API key、cookie、session、provider home 或本机路径只能放进私有 config.yml、进程环境或 provider 自己的登录态，不能写进仓库、vault 正文或日志。
凭据获取
- 路 A：WECHAT_APP_ID / WECHAT_APP_SECRET。
- 路 C / 路 B：登录 mp.weixin.qq.com 后台，打开文章编辑页或列表页（路 B 打开历史文章），F12 从地址栏 URL 复制 token（路 C）/ __biz key/pass_ticket/appmsg_token（路 B），从请求头复制完整 Cookie，填入私有 config.yml 的 env 字段。注意路 C 的 token 要取地址栏 URL 里的数字串，不是请求参数里的 appmsg_token 票据。
用法
路 A：
python3 scripts/fetch_api.py [--out <vault内相对目录>] [--limit N] [--dry-run]
[--vault <path>] [--account-name <公众号显示名>] [--force] [--page-size 20]
路 C（默认读自己号）：
python3 scripts/fetch_mp.py [--out <目录>] [--limit N] [--dry-run]
[--vault <path>] [--account-name <显示名>] [--force] [--sleep 3] [--page-size 20]
路 C（传 --name 或 --fakeid 读指定号）：
python3 scripts/fetch_mp.py --name <公众号名> [--out <目录>] [--limit N] [--dry-run]
[--vault <path>] [--account-name <显示名>] [--force] [--sleep 3] [--page-size 5]
路 B：
python3 scripts/fetch_cookie.py --biz <__biz> [--out <目录>] [--limit N] [--dry-run]
[--vault <path>] [--account-name <显示名>] [--force] [--sleep 1.5]
落地规范（三条路共用）
- 落到 vault 的收件箱层（中转区，非最终位置）。
- 默认输出目录：Inbox/gzh-articles/<年>/（vault 内相对路径），可用 --out 或 env.OBSIDIAN_GZH_OUT 覆盖。
- 文件名：<出版日期>-公众号-<账号显示名>-<标题>.md，同名冲突时按 url 特征加短后缀。
- frontmatter：tags:[公众号原创, 待归位]、source: 公众号自有、url、title、author、published_at、captured_at、route: api|cookie|mp-backend、content_complete、topics: []。
- 正文：HTML → Markdown 走 stdlib html.parser（零第三方依赖），不保证 100% 还原排版。content_complete: false 表示正文抓取失败或为空，需人工核对。
- 幂等：三个脚本都按 url 在 out_dir 下递归查找是否已归档，已存在则默认跳过（--force 才覆盖）。
限制与风险
- 路 C / 路 B 为非官方接口，无官方文档背书，随时可能调整失效，Token/Cookie 会过期且无刷新机制（ret 200003 invalid session / 200013 freq control / 200040 invalid csrf token 有针对性提示）。
- 两条子路径列表接口不返回 author 字段，落地时 author 用 --account-name 兜底，不保证等于真实署名作者。
- 有限流风险，脚本默认设置请求间隔，批量抓整年历史建议配合 --limit 分批跑。
- 路 A 覆盖范围有限，不是全量备份方式。
归档后
按 clip 家族惯例，AI 后续可逐篇补「## 摘要」（30-80 字）、判断/回填 frontmatter topics，等作品库重构后交给 organize 从 Inbox/gzh-articles 批量归位。
完成回执
每次执行需让客户看见过程和结果，最低回执含：完成说明、日志摘要（started/processed/created/updated/skipped/failed）、文件变化、验证、问题与下一步。批量归档必须先全部落盘再统一输出回执。