# Search API Playbook

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

## Default Pattern

v0.12 起，默认搜索路径收敛到项目内 Python 网关：

```bash
uv run python scripts/search.py "<query>" --route scholar --num-results 10 --year-low 2023
uv run python scripts/search.py "<query>" --route evidence --num-results 10 --json --trace
uv run python scripts/search.py "<query>" --route patents --num-results 10
uv run python scripts/search.py "<query>" --route news --num-results 10 --time-range m
uv run python scripts/search.py "<query>" --route general --num-results 10
uv run python scripts/ground.py "<query>" --json
```

其中 `scholar / patents / news` 默认走严格模式（Serper 失败不静默降级）；需要容错时显式加 `--no-strict-specialized`。`evidence` 是 v0.20.1 之后新增的受控证据发现路由，优先用 Exa highlights/text 为 evidence packet 提供候选来源。

MCP server 只作为交互式补漏和特殊工具能力，不作为文献、专利、新闻检索主路径。这样 OpenCode、Codex、Gemini CLI、Claude Code 都能复用同一套路由，减少每个平台单独配置 Tavily/Exa/Brave MCP 的依赖。

## Search Sources

### Tavily

- 优点：LLM 友好，摘要质量稳定，适合快速发现方向。
- 用法：初扫、普通网页、报告线索、交叉补漏；`research()` 更适合 Phase 1 初步扫描、薄弱章节补证据、Phase 3 回炉。
- 风险：不能把普通网页当结论支撑，必须追溯原始来源。
- 规则：Tavily Research 输出必须保存为过程文件，并经过 source-quality 评分、去重和 source_id 归一化；不要直接把 Tavily 的综合报告当作章节正文或最终证据。

### Exa

- 优点：neural/agent search，对官网、公司页、长尾专业内容召回好；highlights/text 适合喂给 agent 做证据筛选。
- 用法：`scripts/search.py --route evidence`、术语核查、公司/产品名纠错、专业网页发现、章节证据补强。
- 风险：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` 技巧，不等同官方专利库。
- 项目内调用：`scripts/search.py --route scholar|patents|news`。

### PubMed / NCBI

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

### ClinicalTrials.gov / ChiCTR

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

### openFDA / FDA / EMA / NMPA

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

### Patents

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

## Recommended Profiles

## v0.20 Routing Decision

- Phase 1 初步扫描：Tavily Research + Exa evidence，目标是形成假设、反证方向、章节任务切分。
- Phase 2 evidence packet：优先 `fda/scholar/patents/news` 等专用路由；需要补充候选证据时用 `evidence`，不要只用 `general`。
- Phase 3 回炉：按 critique 中的证据缺口定向调用 Tavily Research 或 Exa evidence，输出仍需进入 packet/schema。
- General route：只做宽泛发现和兜底，不作为“默认最佳搜索”。

## Recommended Profiles

### biomed_literature

PubMed / NCBI → ClinicalTrials → FDA/EMA/NMPA → `scripts/search.py --route scholar` → `scripts/search.py --route evidence` → Tavily/Brave 补漏。

### patent_heavy

`scripts/search.py --route patents` → USPTO/EPO/CNIPA → 公司年报/招股书 → Exa/Tavily 补同族专利线索。

### china_market

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

### investment

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

## Failure Handling

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