deep_research/docs/search-playbook.md

Search API Playbook

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

Default Pattern

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

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，交人工复核。