读懂 Harvester 输出:valid-keys 等 7 种结果文件的含义与用法
读懂 Harvester 输出:valid-keys 等 7 种结果文件的含义与用法
Harvester 是一个面向 GitHub 和 Web 数据源的智能数据采集框架,它的典型用途是从公开代码库中发现并验证 AI 服务商的 API Key。当你运行 python main.py 跑完一轮采集后,Harvester 会在 workspace 目录下为每个服务商(provider)生成 7 种结果文件。很多新手第一次看到 valid-keys.txt、no-quota-keys.txt 这些文件会一头雾水——本文带你把它们逐一讲透,让你真正读懂 Harvester 的输出。
🗂️ 结果文件存放位置:先看目录结构
所有结果都统一存放在 workspace/providers/<provider名>/ 下,每个被采集的服务商(如 openai、anthropic)对应一个独立文件夹。文件名由 provider/base.py 中的 filenames() 统一约定:
data/
└── providers/
└── openai/
├── material.txt # 采集到的候选 Key
├── links.txt # 处理过的代码链接
├── valid-keys.txt # ✅ 验证通过的有效 Key
├── no-quota-keys.txt # ⚠️ 有效但无额度
├── wait-check-keys.txt # ⏳ 待复查的 Key
├── invalid-keys.txt # ❌ 无效的 Key
├── summary.json # 📊 能力与模型汇总
├── shards/ # NDJSON 分片(断点恢复用)
└── backup-20261115-114800/ # 重启自动备份
📌 7 种结果文件速查表
先给一张总表,方便你对照。类型与统计字段的映射关系定义在 constant/runtime.py:
| 文件名 | 类型标识 | 含义 | 产生阶段 |
|---|---|---|---|
material.txt |
material |
从代码中提取出的候选 Key(原始素材) | Gather 采集 |
links.txt |
links |
已处理的代码链接 URL | Gather 采集 |
valid-keys.txt |
valid |
验证通过、真实可用的 Key | Check 校验 |
no-quota-keys.txt |
no_quota |
Key 有效但无额度/余额不足 | Check 校验 |
wait-check-keys.txt |
wait_check |
命中限流/无模型/无权限,建议稍后复查 | Check 校验 |
invalid-keys.txt |
invalid |
验证失败、不可用的 Key | Check 校验 |
summary.json |
summary |
服务商模型能力与统计汇总 | Inspect 检查 |
🔍 从采集到验证:4 个阶段如何对应到文件
理解文件最快的方式是理解流水线。Harvester 采用 4 阶段管道(Search → Gather → Check → Inspect),各阶段产出的数据流向见 stage/definition.py:
- Search 阶段:按配置里的
conditions到 GitHub 搜索代码片段,得到一批链接。 - Gather 阶段:抓取链接对应的文件内容,用正则(
patterns.key_pattern)提取候选 Key,写入material.txt,并把处理过的 URL 记入links.txt。 - Check 阶段:拿候选 Key 去真实服务商 API 做鉴权验证,根据结果分流到 4 个文件(见下文)。
- Inspect 阶段:对验证通过的 Key 探测可用模型,结果落到
summary.json。
💡 一句话记忆:
material是“原料”,valid/no-quota/wait-check/invalid是“验证分桶”,links和summary是辅助线索与汇总。
✅ valid-keys.txt:最有价值的产出
这是你最关心的文件——真正通过 API 鉴权、可以直接使用的 Key。每当 Check 阶段判定 result.available 为真时,对应的服务(含 address/endpoint/key/model 字段)就会写入此文件。每条记录的字段结构见 core/models.py 的 Service 模型。
用法:直接读取即可用于后续调用;如果带 endpoint/model 字段,说明 Key 还绑定了具体服务地址与默认模型。
⚠️ no-quota-keys.txt:有效但“没钱”
Key 本身能通过鉴权,但服务商返回了额度不足 / 余额为零(对应 ErrorReason.NO_QUOTA)。这类 Key 说明账号真实存在、格式正确,只是暂时无法消费。
用法:可留作观察名单,额度恢复后重试;也常被用来判断一个账号是否“真实有效”。
⏳ wait-check-keys.txt:先放一放,回头再验
当校验命中限流(RATE_LIMITED)、无模型(NO_MODEL)或无权限(NO_ACCESS) 时,Key 会被放入 wait-check。这不代表 Key 无效,只是当前时机/环境不适合立即判定。
用法:下一轮运行会自动重新校验;它也是断点恢复时会重新拉起的任务来源之一。
❌ invalid-keys.txt:已确认不可用
鉴权直接失败(token 无效、未授权、404 等),对应 ErrorReason.INVALID_KEY / UNAUTHORIZED 等。写入后可用于去重,避免下轮重复浪费请求。
🧪 material.txt 与 links.txt:原始素材与线索
material.txt:Gather 阶段提取出的所有候选 Key,是进入 Check 之前的“未验证池”。它比valid大得多,适合做样本分析或统计候选规模。links.txt:处理过的代码 URL 列表。它主要用于任务恢复——重启后 Harvester 会据此重建采集队列,避免重复抓取。
📊 summary.json:能力画像汇总
这是一个 JSON 汇总文件,包含服务商名称、更新时间、每个 Key 对应的可用模型列表,以及 total_keys、total_models 等统计,结构见 storage/persistence.py 的 _save_models()。
用法:想快速了解“这批有效 Key 能调哪些模型”,直接看 summary.json 即可,无需逐行解析 valid-keys.txt。
💾 数据不会丢:shards、snapshot 与自动备份
除了 7 个“主文件”,目录里还有几类辅助结构,共同保证数据可靠:
shards/<类型>/:以 NDJSON 分片存储,每个分片附带.index.json索引,用于增量写入与快速断点恢复(见 storage/persistence.py)。- 定期快照:默认每 300 秒构建一次,防止进程异常导致数据丢失。
backup-<时间戳>/:重启前自动把旧结果文件归档,防止覆盖历史数据。
🛡️ 建议:重要采集结果定期拷贝
workspace目录,backup-*文件夹虽自动保留,但长期任务仍应自行留档。
🧭 上手三步:拿到结果后怎么用
- 定位目录:进入
data/providers/<你的provider>/。 - 看有效产出:优先读
valid-keys.txt与summary.json,确认可用 Key 与模型。 - 判断复查:把
no-quota-keys.txt、wait-check-keys.txt当作“待观察池”,invalid-keys.txt用于去重,material.txt/links.txt用于样本与断点恢复。
小结
Harvester 的 7 种结果文件其实是一条**“提取 → 验证 → 分流 → 汇总”**的完整证据链:
material+links是采集侧的原始素材;valid/no-quota/wait-check/invalid是验证侧的四种结论;summary是能力侧的最终画像。
读懂它们,你就能把一次采集的运行结果,变成可复用的有效数据。想深入了解持久化与恢复机制,可继续阅读 storage/persistence.py 的 ResultManager 实现。