读懂 Harvester 输出:valid-keys 等 7 种结果文件的含义与用法

原创2026-11-15 12:07:192,565 阅读

读懂 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-* 文件夹虽自动保留,但长期任务仍应自行留档。

🧭 上手三步:拿到结果后怎么用

  1. 定位目录:进入 data/providers/<你的provider>/。
  2. 看有效产出:优先读 valid-keys.txt 与 summary.json,确认可用 Key 与模型。
  3. 判断复查:把 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 实现。

登录后查看全文
harvester