# 外部检索 crawl-hub 预检修复
## 诊断流程样例
### 场景
用户问：`Pi Agent 是什么？有没有官方来源和 GitHub 线索？`
### Before
1. Agent 直接调用 crawl-hub 的 google-search 路由。
2. Apify 运行时才报错：`input.queries must be string` 或缺少 `APIFY_TOKEN`。
3. Agent 临时改用普通网页搜索/GitHub 搜索，并在最终答案里解释来源限制。
问题：失败发生在研究流程中段，浪费时间；fallback 靠临场判断，没有稳定输出。
### After
1. 先运行：
```bash
python tools/crawl_hub_source_preflight.py \
--query "Pi Agent" \
--source google-search \
--fallback github,web \
--dry-run
```
2. 工具读取 `secret.env`、crawl-hub source 配置和 actor schema cache。
3. 如果 token 缺失，输出：
```json
{
"status": "fail",
"reason": "missing_token",
"next_route": "web",
"message": "APIFY_TOKEN/APIFY_API_TOKEN not loaded; use official docs, GitHub Search API, and stable web sources."
}
```
4. 如果 schema 不匹配，输出：
```json
{
"status": "fail",
"reason": "schema_mismatch",
"source": "google-search",
"expected": "input.queries: string",
"actual": "array/object from current wrapper",
"next_route": "github,web"
}
```
5. Agent 按 `next_route` 直接切到 GitHub Search API、官方文档或普通网页搜索，并在答案里声明 crawl-hub 未作为证据源。
### 通过标准
- 对同一类问题不再反复撞 `input.queries must be string`。
- 缺 token 时 5 秒内给出 fallback，而不是等待 runner 失败。
- 最终答案能清楚区分 crawl-hub 可用证据、GitHub API 证据和普通网页证据。