| name | wechat-download |
| description | Use when the user asks to download, archive, crawl, scrape, or export articles from a WeChat official account (公众号). |
| version | 1.0.1 |
微信公众号文章下载
通过本地部署的 wechat-download-api 服务，批量下载任意微信公众号的全部历史文章（含完整内容）。
触发条件
- 用户要求下载/爬取微信公众号文章
- 用户要求搜索公众号并获取文章
- 用户说「下载 XX 公众号的文章」
- 用户提到 wechat-download / 公众号下载 / 微信文章抓取
架构
本 skill (调用脚本) → wechat-download-api (本地 HTTP 服务 :8765) → 微信公众平台 API
- wechat-download-api：第三方开源服务，使用 Chrome TLS 指纹（curl_cffi）模拟浏览器，通过微信公众平台后台凭证调用接口
- 本 skill 脚本：封装了 API 的搜索、列表、下载功能，带限频自适应和断点续传
使用方式
用户安装本 skill 后，只需要在 agent 里说「下载 XXX 的公众号文章」。除扫码登录外，不要要求用户手动部署底层服务；agent 应优先自动运行本目录脚本完成环境准备。
1. 启动服务
从 skill 目录运行：
cd ~/.claude/skills/wechat-download
bash scripts/start_wechat_api.sh
脚本会自动发现 ./wechat-download-api、../wechat-download-api，也支持通过 WECHAT_API_REPO 环境变量定位。找不到时会自动 clone wechat-download-api 到当前 skill 目录，并安装底层服务依赖。
端口说明：本 skill 默认使用 8765 而非 upstream 的 5000，因为 macOS 上 5000 常被系统服务占用。如果你用 upstream 的 start.sh 启动了服务（端口 5000），请在命令前加 WECHAT_API_URL=http://localhost:5000。
脚本会自动：
- 查找或下载 wechat-download-api 仓库
- 创建
.env（如果不存在）
- 安装缺失的 Python 依赖
- 后台启动服务
2. 扫码登录
前提：用户需要有一个微信公众号（订阅号/服务号均可）。
- 浏览器打开
http://localhost:8765/login.html
- 用公众号管理员微信扫码
- 登录成功后凭证自动保存到
.env，有效期约 4 天
如果用户没有公众号，见下方「备选方案」。
操作流程
第一步：检查/启动服务
如果服务还没启动，先运行：
bash scripts/start_wechat_api.sh
然后检查服务状态：
python3 scripts/download_wechat.py status
第二步：检查登录
curl -s http://localhost:8765/api/admin/status
如果 isExpired: true → 重新扫码登录。
第三步：搜索公众号
python3 scripts/download_wechat.py search "公众号名称"
从输出中获取 fakeid。
第四步：下载文章
python3 scripts/download_wechat.py download "fakeid" 200 ./output_dir
功能：
- 自动分页获取全部文章列表
- 逐篇下载完整内容，保存为
.txt 文件
- 断点续传：已下载的文件自动跳过
- 限频自适应：检测到 Rate limited 自动等待
- 失败记录保存到
failures.json
其他命令
python3 scripts/download_wechat.py list "fakeid" 0 50
python3 scripts/download_wechat.py rss "fakeid"
常见错误及解决方法
错误 1：端口被占用
ERROR: [Errno 48] address already in use
解决：换一个端口：bash scripts/start_wechat_api.sh 9876
错误 2：文章 URL 字段名（关键）
url = a.get("url", "")
url = a.get("link", "")
API 返回的文章列表使用 link 字段，不是 url。
错误 3：Rate Limited（限频）
Rate limited: 请求过于频繁，请X秒后重试
解决：脚本已内置自适应退避。如果仍然频繁触发，增大 MIN_DELAY（默认 3.2 秒）。
错误 4：触发微信安全验证
触发微信安全验证。
解决：
- 降低请求频率
- 在浏览器中打开提示的文章 URL 完成人机验证
- 等待 30 分钟后重试
- 如频繁触发，在
.env 中配置 PROXY_URLS（SOCKS5 代理池）
错误 5：无法获取文章内容
无法获取文章内容。可能原因：文章被删除、访问受限或需要验证。
原因：文章已被删除 / 是广告推广 / 图片分享 / 微信风控。跳过即可，通常占 30-50%。
错误 6：登录过期
原因：微信凭证有效期约 4 天。
解决：重新访问 http://localhost:8765/login.html 扫码。
错误 7：curl_cffi 编译失败
ModuleNotFoundError: No module named 'curl_cffi'
解决：需要可用的 C 编译器。macOS 需安装 Xcode CLT（xcode-select --install），Linux 需 build-essential 和 libcurl4-openssl-dev。预编译 wheel 在 PyPI 上覆盖主流平台。
备选方案：无公众号时下载
如果用户没有微信公众号无法登录，可以用以下方法：
- 搜索引擎反查：搜索
"公众号名" mp.weixin.qq.com/s 获取文章链接，直接访问 mp.weixin.qq.com 提取 #js_content 中的内容
- 转载平台：在 guancha.cn（观察者网）、36kr、新浪财经等平台搜索转载文章
- 镜像站：jintiankansha.me 等平台有文章列表（但通常需要 VIP 才能看全文）
参考
- wechat-download-api — 底层 API 服务，AGPL 3.0
- 文章 URL 格式说明：
https://mp.weixin.qq.com/s/{short_id} 或带 __biz/mid/idx/sn 参数的完整链接
