name: wechat-article-archive
displayName: 微信公众号文章归档助手
displayNameEn: WeChat Article Archive
slug: wechat-article-archive-sl
emoji: 📚
description: "把用户有权访问的微信公众号文章、公开合集页与浏览器可见页面上下文，合规归档为可长期保存、可检索、可增量更新的资料库，交付 Markdown、HTML、JSON、DOCX、PDF、ZIP 与飞书 / IMA 知识库发布包。支持单篇归档、批量抓取去重、断点续抓、合集页导出、增量入库与发布交接。核心红线：只处理用户显式提供且有权访问的内容，不绕过登录、验证码、付费墙、已删除文章与平台风控，不伪造登录态，不承诺抓取某公众号全部历史文章，不做像素级排版复刻，未获授权不声称已完成外部知识库写入。在用户说「归档这篇公众号文章」「批量抓取这些公众号链接」「导出公众号合集」「公众号文章转 Markdown」「归档到飞书文档」「更新 IMA 知识库」「增量补充资料库」时使用。"
description_zh: "微信公众号文章归档助手。把用户有权访问的公众号文章、公开合集页与浏览器可见页面归档为可长期保存、可检索、可增量更新的资料库，输出 Markdown、HTML、JSON、DOCX、PDF、ZIP 与飞书 / IMA 发布包。核心红线是不绕登录、验证码、付费墙、已删除内容与平台风控，不伪造登录态，如实交代覆盖率。触发场景：归档单篇文章、批量抓取一组链接、导出合集页清单、文章转 Markdown、归档到飞书文档、更新 IMA 知识库、对已有资料库做增量补充。"
description_en: "Archive WeChat Official Account articles the user is entitled to read, covering public album pages and user-visible browser context, into a long-term searchable library that supports incremental updates. Delivers Markdown, HTML, JSON, DOCX, PDF, ZIP, plus Lark and IMA knowledge-base handoff packages. Capabilities cover single-article archiving, batch fetching with deduplication, resume, album-page export, incremental catalog maintenance, and publish handoff. Hard boundaries: never bypass login, captcha, paywalls, deleted content or platform risk control; never forge authentication; never promise full historical coverage of an account; never claim an external knowledge-base write without authorization. Use when the user asks to archive an article, batch-fetch a link list, export an album, convert articles to Markdown, publish to Lark, update an IMA knowledge base, or incrementally extend an existing library."
version: "1.1.0"
author: 小浣熊肖恩
license: MIT-0
category: 知识管理
subcategory: 网页归档
tags:
- 微信公众号
- 文章归档
- 批量抓取
- markdown
- 知识库
- 飞书
- ima
- 增量同步
triggerKeywords:
- 公众号文章
- 微信公众号文章
- 归档文章
- 归档公众号文章
- 保存文章
- 保存公众号文章
- 下载公众号文章
- 批量抓取
- 批量归档
- 批量下载文章
- 导出文章
- 导出文章链接
- 公众号合集
- 合集页
- 增量归档
- 增量更新
- 文章转Markdown
- 公众号转Markdown
- 导出Markdown
- 飞书文档
- 飞书知识库
- IMA知识库
- 知识库归档
- 资料库
- 文章资料库
- 断点续抓
- 去重归档
modes:
- agent
- ask
compatibility:
platforms:
- 商汤办公小浣熊
- Raccoon Skills
python: ">=3.9"
network: "需要公网访问 mp.weixin.qq.com。可选依赖 requests、beautifulsoup4、markdownify、python-docx、reportlab，缺失时按格式降级并在 capabilities 段记录。"
credentials: "历史文章接口所需的 Cookie 与 token 仅从环境变量或命令行读入，不写入任何产物、报告与日志。"
entry: scripts/fetch_wechat_article.py
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
解释器解析（IMP-24）
下方所有命令以 $BOX_AGENT_PYTHON 开头。该变量在本机并未设置——
直接照抄会失败（shell 把它展开成空串，命令变成 scripts/fetch_...，通常报
command not found）。取解释器的规则如下，实现在
wechat_archive/services/doctor_service.py::resolve_interpreter()：
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | 环境变量 $BOX_AGENT_PYTHON |
用户显式指定，优先级最高（显式配置覆盖自动探测） |
| 2 | which python3 |
PATH 中第一个可用的 python3 |
| 3 | sys.executable |
当前进程的解释器 |
拿本机可执行的完整命令（推荐——不用自己判断该用哪个）：
<解释器> scripts/fetch_wechat_article.py doctor
doctor 会逐项报告本机实际使用的解释器与来源，并输出可直接复制的完整命令。
先跑它，再复制它给的命令，这样不会抄错。
> 示例（某次核实的真实结果，换机器会变，以 doctor 输出为准）：
> > 解释器（PATH 中的 python3）：/Users/…/python/versions/3.13.12/bin/python3
> 下方命令可直接复制执行：
> /Users/…/python/versions/3.13.12/bin/python3 scripts/fetch_wechat_article.py doctor
>
⚠️ 为什么不在文档里写死一个绝对路径
绝对路径因机器而异。把某次核实的路径写死进文档，换台机器就错——
那与原来的 $BOX_AGENT_PYTHON 占位符问题只是换了个形式：一个是「换机器就
对不上变量名」，一个是「换机器就对不上路径」。
所以本节只给规则（规则跨机器不变），把「这台机器上是哪个」交给
doctor 现场报告。tests/test_batch4_delivery.py 会从本节提取规则
与 resolve_interpreter() 的实际顺序比对，两边不一致即测试失败。
任务状态机
Agent 自行判断当前处于哪个阶段。每阶段的「完成判据」是可验证的事实，不是「看起来做完了」。
| 阶段 | 输入 | 动作 | 产出 | 完成判据 |
|---|---|---|---|---|
| S1 环境确认 | 用户请求 | 跑 doctor |
解释器路径 + 依赖清单 | 拿到可复制的完整命令；缺依赖项已知 |
| S2 目标解析 | 用户指令 / 命令行 / 环境变量 | 四级优先级定位 | 知识库与文件夹（或「需用户确认」） | 未落到默认库时已询问用户，未自动建库 |
| S3 抓取归档 | 链接清单 | 取页、分类、落盘 | articles/ 树 + manifest.csv |
manifest 有行；每行有 status |
| S4 交付生成 | 归档产物 | 按 --formats 渲染 |
Markdown / reader / docx / txt | 每种格式单独报告 ok 或 skip + 原因 |
| S5 回执交代 | 本次结果 | 统计与如实说明 | README-交付说明.md + 控制台汇总 |
覆盖率从 manifest 实算；未产出项已说明 |
阶段可跳过，不可假装完成 —— S1 没过就跑 S3 是「用了错的解释器」，S4 跳过后 S5 报「全部完成」是「声明了但不真」。
首次使用
- 确认环境：跑
doctor，复制它给出的完整命令（不要照抄$BOX_AGENT_PYTHON）。 - 抓一篇试试：
<解释器> scripts/fetch_wechat_article.py current "<url>" --output output/wechat-archive - 打开交付物：双击
output/wechat-archive/README-交付说明.md，
从它指向的入口开始读（HTML 阅读器是最推荐的入口）。
何时不用本 Skill
- 不需要绕过登录、验证码、付费墙、已删除文章或平台风控。
- 不需要承诺某公众号的全部历史文章 —— 本技能只处理你显式提供的链接。
- 不需要未经授权的高频批量抓取 —— 默认限速是风控保护，不要为了快而调高并发。
- 不需要像素级复刻公众号排版 —— 产出是结构化正文，不是版式还原。
- 不需要在未获授权时声称已完成飞书 / IMA 写入 —— 无权限时报错或降级为 handoff。
使命与触发条件
把用户有权访问的微信公众号文章、合集页和浏览器页面上下文，合规归档为
可长期保存、可检索、可增量更新、可写入知识库的资料库。
七类任务：A 当前文章 / B 批量归档 / C 历史文章 / D 合集页 /
E 浏览器上下文 / F 资料库发布 / G 增量更新。
何时触发：保存 / 下载 / 归档公众号文章；转 Markdown / Word / PDF；批量导出链接；
从文章页 / 合集页 / 历史页 / 浏览器上下文提取链接；整理为飞书文档或 IMA 知识库；
对已有资料库做增量更新。
性能与容量基线
所有数字与代码常量同源 —— tests/test_batch4_delivery.py 从本表提取数字与
batch_service / docx_service 的常量比对，不一致即测试失败。
| 项 | 值 | 代码出处 |
|---|---|---|
| 默认并发 | 4 |
batch_service.DEFAULT_CONCURRENCY |
| 请求间隔 | 120–300 毫秒 |
--interval-min/max 默认 |
| 吞吐上限 | 约 19 篇/秒 |
仅按间隔与并发推算，不含网络往返与图片下载 |
| 2000 篇参考耗时 | 约 2 分钟 |
同上，实际受网络影响 |
| Word 合集 | 超 1000 篇建议后台生成 |
docx_service.CAPACITY_THRESHOLD |
⚠️ 吞吐数是上限不是保证值 —— 图片下载、平台限流、429 重试都会显著拉低。
默认并发是 4 而非 5–6，是 PRD R1 风险表要求的保守起步（并发直接关系平台风控）。
详表与口径见 references/performance-baseline.md。
交付形态与命名
| 形态 | 触发 | 产物 |
|---|---|---|
| Markdown / HTML / JSON | --formats md,html,json（默认） |
articles/<账号>/<标题-hash>/ |
| 单文件 HTML 阅读器 | --formats reader |
reader.html（最推荐的阅读入口） |
| Word 合集 | --formats docx-all |
合集.docx（书签 + 可点目录） |
| TXT 文章包 | --formats txt |
文章包/<账号>/ |
每批必出的两份索引（各形态共用）：
| 产物 | 是什么 |
|---|---|
manifest.csv |
归档账本，每篇一行（URL / 标题 / 账号 / 状态 / 字数） |
catalog.json |
资料库索引（v2 十段结构，供检索系统消费） |
--deliver all 一次产出后三者，每种单独报告 [ok] 或 [skip] + 原因。
命名：文章目录 120 字上限；TXT 文件名 ≤ 60 字（Windows 路径限制），
重名加 (2)。详表见 references/delivery-formats.md。
常见问题
8 问见 references/faq.md。最常撞的三个：
$BOX_AGENT_PYTHON不能照抄 —— 先跑doctor拿可复制命令。- 依赖缺失的后果相反 ——
markdownify缺失是降级产出，reportlab缺失是不产出。 - 六态没抓到正文不是被丢弃 —— 仍进账本，带
status_reason，可按状态补救。
默认执行流程
# S1 环境确认 → S3 抓取归档（单篇）
<解释器> scripts/fetch_wechat_article.py doctor
<解释器> scripts/fetch_wechat_article.py current "<url>" \
--output output/wechat-archive --formats md,html,json
# S4 一次产出三样交付物
<解释器> scripts/fetch_wechat_article.py batch \
--links examples/batch-links.txt --output output/wechat-batch-archive \
--formats md,json --deliver all
完整参数组合、语义陷阱、限速映射、子命令速查见
references/cli-examples.md。
配套文档
| 文档 | 内容 |
|---|---|
| technical-notes.md | 技术决策记录：限速参数为何分两套、六态阈值、重试短路 |
| cli-examples.md | 各子命令完整示例、参数速查、限速映射表 |
| history-fetch-design.md | 历史文章接口的发现流程与凭据边界 |
| publish-integrations.md | 飞书 / IMA 写入的六步流程与四级目标解析 |
| performance-baseline.md | 性能与容量详表（含吞吐口径说明） |
| faq.md | 常见问题详答 |
| delivery-formats.md | 交付形态、六态徽标色、各形态打开方式 |
| platform-constraints.md | 平台待验证假设与 A-5 层级豁免的已知取舍（上架前必读） |
| platform-audit-table.md | 五条平台假设的逐条状态与回退手段 |
| reader-browser-verification.md | 阅读器 15 项人工验证步骤（自动化只保语法与元素，行为层需人眼） |
| source-map.md | 源材料覆盖矩阵：PRD 35 项 → 实现映射、缺陷修复继承、未覆盖项决定 |
| playbook-incremental-report.md | 增量报告五段怎么读、跳过与失败怎么区分、重试怎么处置（含反例） |
| reverse-verification-log.md | 反向验证清单：注入缺陷 → 变红 → 还原转绿，分已实测 / 真实捕获 / 待复核三类 |
示例与契约（读产物结构用）：
output-contract.md（全部 --formats 产物目录树、--deliver all 结构、catalog v2 七段）·
request.md（8 类典型请求写法）·
batch-links.txt（可直接改的批量链接样例）·
edge-cases.md（不完整 / 格式错误 / 高风险请求的处置与拒答措辞）
异常处理
- 找不到
#js_content：页面不可访问 / 需登录 / 结构变化 / 不是公众号文章。 - 图片下载失败：记入
metadata.json，正文仍输出。 - DOCX / PDF 依赖不可用：写 warning 文件，不影响 Markdown / HTML。
- 批量 / 历史模式失败：分别记入
failures.json与history-error.txt。 - 发布模式无授权：只生成 handoff 包，不声称已写入外部系统。
- 在线写入失败：返回非 0 退出码，明确说「线上未写入」。
质量门禁
交付前必须检查：
- 根目录
SKILL.md存在且 YAML front matter 可解析；scripts/fetch_wechat_article.py语法通过；本文档含全部七节（解释器解析、任务状态机、性能与容量基线、交付形态与命名、何时不用本 Skill、常见问题、首次使用）。 - 八个子命令均可展示
--help：current/batch/history/album/workflow/browser-context/publish/doctor。（数字须与实际一致，TestSelfConsistentNumbers实跑对账） references/十三份齐备并被本文正确引用（新增时同步改此数字）。- ZIP 根层含
wechat-article-archive/SKILL.md，不含运行态 artifacts、缓存或递归 ZIP。
合规边界
只处理用户有权访问的公开或授权内容。历史文章依赖用户自己的合法登录态，不绕过任何平台限制。浏览器上下文只处理用户主动提供的页面内容，不读取 Cookie 或敏感凭证。飞书 / IMA 在未获授权前只生成离线包与 handoff 清单，不声称已完成外部写入。对接口变化、Cookie 过期、验证码、风控、删除、付费内容，不做规避承诺，只做清晰失败报告与降级建议。本 Skill 不会自动安装任何依赖，交付物里出现的 pip install 仅为建议命令，由你自行决定是否执行。
