# Search API Playbook

> v0.9 起，本文件作为搜索 API 选择攻略本。搜索返回本身多为发现入口，结论支撑仍以 AGENTS.md 的 Tier 1-2 信源为准。

## Search Sources

### Tavily

- 优点：LLM 友好，摘要质量稳定，适合快速发现方向。
- 用法：初扫、普通网页、报告线索、交叉补漏。
- 风险：不能把普通网页当结论支撑，必须追溯原始来源。

### Exa

- 优点：neural search，对官网、公司页、长尾专业内容召回好。
- 用法：术语核查、公司/产品名纠错、专业网页发现。
- 风险：macOS 代理环境容易 TLS EOF，项目内 `SearchClient` 已使用 `trust_env=False` 绕开系统代理。

### Brave

- 优点：独立搜索引擎，适合与 Tavily/Exa 交叉验证。
- 用法：Phase 1 初扫、反方证据、中文/英文混合搜索。
- 风险：结果质量波动，需要人工筛 Tier。

### Serper

- 优点：Google Search / Scholar / News 代理，免费额度较高。
- 用法：Google Scholar、Google Patents、新闻时效检索。
- 风险：专利是 `site:patents.google.com` 技巧，不等同官方专利库。

### PubMed / NCBI

- 优点：生物医药论文的一手入口。
- 用法：机制、临床、系统综述、meta 分析。
- 风险：无 API key 限流较低；摘要不足以替代全文判断。

### ClinicalTrials.gov / ChiCTR

- 优点：临床试验注册的一手来源。
- 用法：管线、适应症、试验阶段、终点设计、入组状态。
- 风险：注册信息不等于结果；需要结合论文、公司披露、监管文件。

### openFDA / FDA / EMA / NMPA

- 优点：监管公告与标签信息，Tier 1。
- 用法：批准状态、安全性、适应症、审评文件。
- 风险：不同监管地区口径不同，必须注明地区与日期。

### Patents

- 优点：IP 与工艺路线研究的核心证据。
- 用法：Google Patents、USPTO、EPO、CNIPA。
- 风险：专利文本难读，权利要求和实施例要分开判断。

## Recommended Profiles

### biomed_literature

PubMed / NCBI → ClinicalTrials → FDA/EMA/NMPA → Serper Scholar → Tavily/Exa 补漏。

### patent_heavy

Google Patents/Serper → USPTO/EPO/CNIPA → 公司年报/招股书 → Tavily/Exa 补同族专利线索。

### china_market

NMPA/CDE → 港交所/上交所/深交所披露 → 中文专业数据库/媒体 → Brave/Serper 中文搜索。

### investment

SEC/交易所披露 → Evaluate/IQVIA/咨询报告 → 公司公告 → 新闻仅作时效入口。

## Failure Handling

- 大量 SSL/TLS 错误：先把 workers 降到 3，再重跑。
- API 限流：保留缓存结果，断点续跑，不要强制 `--force`。
- 搜索返回普通网页：只做线索，继续追原始论文、监管、专利或公司披露。
- 中英文译名冲突：写入 glossary，标 medium/low confidence，交人工复核。