功能说明

July 4, 2026 · View on GitHub

本文说明项目当前主要功能。安装步骤请看 install.md。

1. 主服务采集

主服务用于从微信 PC 客户端的公众号、服务号或订阅号主页中识别文章，并按指定数量自动打开文章进行采集。

基本流程：

  1. 打开微信 PC 客户端并登录。
  2. 在微信中打开目标公众号、服务号或订阅号主页。
  3. 在程序主服务页面设置采集记录数量。
  4. 点击“开始运行”。
  5. 程序识别主页文章候选，逐篇点击并等待 MITM 捕获文章请求。
  6. 保存文章结构化信息、原始 HTML、请求证据和评论信息。

主流程会优先识别真实公众号/服务号主页，避免误选微信聊天主窗口、隐藏壳窗口或文章详情窗口。

2. 代理工具

代理工具用于启动本地 MITM 代理，并配合系统代理捕获微信内置浏览器的文章请求。

默认监听：

127.0.0.1:18000

相关能力：

  • 启动 MITM 代理
  • 停止 MITM 代理
  • 开启系统代理
  • 恢复系统代理
  • 测试代理连接
  • 查看 MITM 运行状态

程序退出或手动关闭代理时，恢复原本的系统代理，避免影响浏览器和其他软件联网。

3. 证书安装

微信文章页为 HTTPS 页面，MITM 抓包需要安装 mitmproxy CA 证书。

证书相关能力：

  • 检测当前证书是否已安装
  • 一键安装当前项目 .mitmproxy/ 下的 CA 证书
  • 列出系统中 mitmproxy 相关证书
  • 删除用户确认的 mitmproxy 证书

安装证书时 Windows 可能弹出确认窗口，按提示确认即可。

4. 文章本地归档

采集成功后，文章数据会保存到：

storages/公众号名/文章发布时间 文章标题/

主要文件：

  • article_detail.json：文章标题、公众号、发布时间、短链接、阅读量、点赞量、转发量、推荐量、评论量等结构化信息
  • 评论相关 JSON：按当前评论采集能力保存

MITM 原始捕获内容属于运行排查数据，默认位于 data/logs/article_capture/，可能包含短时间有效的 key、pass_ticket、appmsg_token 等本地敏感临时信息，不建议对外分享。

5. 数据档案

数据档案页用于查看和管理已经采集入库的公众号与文章记录。

主要能力：

  • 查看公众号列表
  • 查看公众号下的文章记录
  • 查看文章归档状态和本地占用
  • 删除选中文章记录及对应本地归档
  • 删除某个公众号及其全部文章归档
  • 打开项目 storages/ 目录

数据档案读取的索引来自：

data/awa_public.sqlite3

6. 文章缓存

文章缓存用于从 SQLite 中读取文章短链接，再使用 Playwright 打开网页并保存离线页面。

输出位置：

storages/公众号名/文章发布时间 文章标题/index.html
storages/公众号名/文章发布时间 文章标题/assets/

特点：

  • 使用随机浏览器请求头
  • 不附带 MITM key 参数
  • 短文章快速完成
  • 长文章按自适应滚动策略尽量保存完整
  • 只保存页面实际引用的资源
  • 默认批量并行限制为 3

如果文章底部存在“阅读原文”，离线页面会尽量保留对应链接。

7. Excel 导出

数据档案页支持按公众号批量导出 Excel。

导出规则：

  • 每个公众号单独生成一个 Excel 文件
  • 文件名格式为 公众号名_文章记录_N篇_YYYYMMDD_HHMMSS.xlsx
  • 文章按发布时间倒序排列
  • 缺少 article_detail.json 时仍导出 SQLite 中已有字段
  • 缺失统计字段留空，并在“记录状态”中说明原因

Excel 表头：

序号、记录状态、发布时间、文章标题、文章短链接、听众量、阅读量、点赞量、转发量、推荐量、评论量、记录获取时间

导出会先写入临时目录：

data/tmp/archive_excel_export_*/

然后复制到用户选择的保存目录。

8. 系统配置

系统配置页用于查看和修改当前运行配置。

常见配置：

  • 代理监听地址和端口
  • 代理启动延时
  • 是否自动接管系统代理
  • 是否自动清理临时文件
  • 日志等级
  • 请求间隔时间
  • 重试次数
  • 代理测试地址

配置文件位置：

data/custom.yaml

9. 运行日志

运行日志保存在：

data/logs/yyyy-mm-dd/*.log

主服务页面也会展示最近运行日志。日志可用于排查：

  • MITM 是否启动
  • 系统代理是否开启
  • 主页窗口是否识别成功
  • 文章候选是否读取到
  • 文章请求是否被捕获
  • 本地归档是否写入成功
  • 缓存或导出是否失败

10. 临时文件清理

程序使用 data/tmp/ 保存运行临时文件，例如缓存任务、导出中间文件、窗口探针结果等。

自动清理临时文件开关开启后，程序启动时会清理 data/tmp/ 范围内可安全删除的内容，并保留当前运行需要的文件。

11. 常见功能问题

代理启动了但网页无法访问

优先检查：

  • MITM 代理是否正在运行
  • 系统代理是否指向 127.0.0.1:18000
  • mitmproxy CA 证书是否已安装并受信任
  • 是否有其他代理软件占用了系统代理
  • 程序退出前是否正确恢复系统代理

程序识别到微信聊天窗口

请确认微信中打开的是公众号、服务号或订阅号主页，而不是聊天页或文章详情页。当前主流程会优先识别主页窗口，但如果微信窗口焦点和可见内容异常，建议重新打开主页后再运行。

采集失败后在哪里看原因

查看：

data/logs/yyyy-mm-dd/*.log

也可以在主服务页面运行日志区域查看最近错误。