107 lines
5.0 KiB
Markdown
107 lines
5.0 KiB
Markdown
# 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，交人工复核。
|