NCBI Search — AI Agent 工具文档

> 一句话描述: NCBI 多数据库智能检索工具，使用官方 E-Utilities API，免费、可靠、零外部依赖。

目录

1. 快速决策树
2. 数据库总览
3. 使用方式
4. 参数详解
5. 完整示例集
6. 高级查询技巧
7. 结果解析说明
8. 错误处理指南
9. 批量处理能力
10. 缓存机制
11. API Key 配置
12. 文件结构

1. 快速决策树

AI Agent 请按以下优先级判断使用哪个数据库：

用户查询
│
├─ 包含 rs\d+ 模式（如 rs429358）? → dbSNP
│
├─ 包含 VCV\d+ 模式（如 VCV000242862）? → ClinVar
│
├─ 包含已知基因符号（APOE, BRCA1 等）或 4-8 位潜在基因正则（如 SHANK3）?
│   ├─ 同时包含文献关键字（paper/review/trial/文献/论文/临床等）? → PubMed
│   └─ 否则 → Gene
│
├─ 包含数据库关键词?
│   ├─ paper/article/review/journal/trial/文献/论文/临床/综述 → PubMed
│   ├─ protein/peptide/amino acid/蛋白/多肽/氨基酸/sequence → Protein
│   ├─ nucleotide/DNA/RNA/genome/cDNA/核酸/序列/基因组 → Nucleotide
│   ├─ SNP/variant/polymorphism/allele/变异/多态性/突变 → dbSNP
│   ├─ clinvar/clinical variant/pathogenic/致病/临床变异 → ClinVar
│   ├─ species/taxonomy/organism/classification/物种/分类 → Taxonomy
│   ├─ biosample/sample/样本 → BioSample
│   ├─ assembly/genome assembly/基因组组装 → Assembly
│   └─ SRA/sequencing/reads/测序数据 → SRA
│
└─ 以上都不匹配 → PubMed（默认）

触发规则优先级

Do / Don't

2. 数据库总览

2.1 完整数据库列表

2.2 数据库选择建议

3. 使用方式

3.1 脚本说明

项目包含 4 个脚本，各有侧重：

3.2 自动模式（推荐）

# 自动判断搜索意图
python scripts/ncbi_search.py "APOE gene"
python scripts/ncbi_search.py "Alzheimer disease review"
python scripts/ncbi_search.py "insulin protein"
python scripts/ncbi_search.py "rs429358"

3.3 指定数据库

python scripts/ncbi_search.py "APOE" --db gene
python scripts/ncbi_search.py "diabetes" --db pubmed
python scripts/ncbi_search.py "rs429358" --db snp

3.4 PubMed 专用脚本（自然语言检索）

# 自动将自然语言转换为 PubMed 检索式
python scripts/pubmed_search.py "Alzheimer disease cerebrovascular mechanisms"
python scripts/pubmed_search.py "APOE gene and Alzheimer disease" --years 5
python scripts/pubmed_search.py "Smith J author Alzheimer" --max 20

4. 参数详解

4.1 ncbi_search.py 参数

4.2 pubmed_search.py 参数

4.3 --type 参数可选值

4.4 参数组合规则

5. 完整示例集

5.1 基础示例

# 自动模式
python scripts/ncbi_search.py "APOE gene"                    # → Gene
python scripts/ncbi_search.py "Alzheimer disease review"     # → PubMed
python scripts/ncbi_search.py "rs429358"                     # → dbSNP
python scripts/ncbi_search.py "insulin protein"              # → Protein
python scripts/ncbi_search.py "Escherichia coli taxonomy"    # → Taxonomy

# 指定数据库
python scripts/ncbi_search.py "APOE" --db gene --organism human
python scripts/ncbi_search.py "insulin" --db protein
python scripts/ncbi_search.py "BRCA1" --db nucleotide

5.2 组合参数示例

# PubMed 高级过滤
python scripts/ncbi_search.py "diabetes treatment" --years 5 --type review --max 20
python scripts/ncbi_search.py "Alzheimer amyloid beta" --years 3 --max 5
python scripts/ncbi_search.py "COVID-19 vaccine" --type clinical_trial --max 50

# Gene 高级过滤
python scripts/ncbi_search.py "APOE" --db gene --organism human
python scripts/ncbi_search.py "TP53" --db gene --organism mouse

# JSON 格式输出
python scripts/ncbi_search.py "BRCA1" --db gene --format json

# 保存到文件
python scripts/ncbi_search.py "Alzheimer disease" --years 5 --max 100 -o results.txt

5.3 PubMed 自然语言检索示例

# 使用 pubmed_search.py 进行智能解析
python scripts/pubmed_search.py "Alzheimer disease cerebrovascular mechanisms"
python scripts/pubmed_search.py "APOE gene and Alzheimer disease" --years 5
python scripts/pubmed_search.py "Smith J author Alzheimer" --max 20
python scripts/pubmed_search.py "diabetes treatment review" --type review
python scripts/pubmed_search.py "cancer immunotherapy" --mesh "Neoplasms" --years 3

5.4 边界情况示例

# 无结果查询
python scripts/ncbi_search.py "xyzabc123nonexistent" --db gene

# 大量结果（仅返回前 N 条）
python scripts/ncbi_search.py "cancer" --db pubmed --max 5

# 特殊字符查询
python scripts/ncbi_search.py "IL-6 gene" --db gene
python scripts/ncbi_search.py "p53 protein" --db protein

# 中文查询
python scripts/ncbi_search.py "阿尔茨海默病 综述" --db pubmed
python scripts/ncbi_search.py "APOE 基因" --db gene

6. 高级查询技巧

6.1 PubMed 检索式构建

pubmed_search.py 会自动将自然语言转换为标准 PubMed 检索式。转换逻辑如下：

6.2 手动构建检索式

如果自动转换不满足需求，可以直接传入标准 PubMed 检索式：

# 复杂布尔检索
python scripts/ncbi_search.py "(Alzheimer[Title/Abstract]) AND (APOE[Title/Abstract]) AND (Review[pt])"

# 多字段组合
python scripts/ncbi_search.py "(diabetes[MeSH]) AND (insulin[Title/Abstract]) AND (2020[PDat]:2025[PDat])"

# 排除检索
python scripts/ncbi_search.py "(Alzheimer[Title/Abstract]) NOT (mouse[Title/Abstract])"

6.3 常用 PubMed 字段标签

6.4 布尔运算符

7. 结果解析说明

7.1 PubMed 结果字段

7.2 Gene 结果字段

7.3 dbSNP 结果字段

7.4 结果排序规则

• 默认排序: 按相关性（relevance）降序
• PubMed 特殊排序: 相关性与时间综合排序
• 无 API Key 限制: 最多返回 20 条（NCBI 限制）
• 有 API Key 限制: 最多返回 100 条

8. 错误处理指南

8.1 常见错误码

8.2 速率限制

8.3 降级策略

当 API Key 缺失或请求失败时：

# 1. 无 API Key 时自动降速（脚本自动处理）
# 2. 减少请求量
python scripts/ncbi_search.py "query" --max 5

# 3. 使用更精确的查询减少结果数
python scripts/ncbi_search.py "Alzheimer APOE" --db pubmed --max 10

# 4. 检查 API Key 是否配置
echo $env:NCBI_API_KEY  # Windows PowerShell

8.4 无结果时的应对策略

9. 批量处理能力

9.1 批量获取文献详情

使用 pubmed_fetch.py 通过 PMID 列表批量获取：

# 通过 PMID 列表获取
python scripts/pubmed_fetch.py 33597265 34239348 35022842

# 从文件读取 PMID 列表
python scripts/pubmed_fetch.py -f pmids.txt

# 指定输出格式
python scripts/pubmed_fetch.py 33597265 34239348 --format json

# 保存到文件
python scripts/pubmed_fetch.py 33597265 34239348 -o articles.json

9.2 多次查询结果合并

# 分步查询不同数据库
python scripts/ncbi_search.py "APOE" --db gene --format json -o gene_result.json
python scripts/ncbi_search.py "APOE" --db pubmed --max 5 --format json -o pubmed_result.json

# 使用 pubmed_search.py 获取详细信息
python scripts/pubmed_search.py "APOE gene Alzheimer" --max 10 -o detailed_results.txt

9.3 数据导出格式

10. 缓存机制

10.1 缓存说明

脚本内置了零依赖的 SQLite 本地持久化缓存，可自动优化检索速度并防止触发 NCBI 速率限制：

1. 自动缓存机制: ESearch、ESummary 和 EFetch 的所有 HTTP 响应都会被自动持久化存储在工作区下的 .ncbi_cache/cache.db。
2. 零网络延迟: 重复进行相同的查询时，数据会瞬间从本地数据库返回（耗时由数百毫秒缩短至数毫秒），完全无网络请求。
3. 缓存有效期: 缓存默认有效期为 24 小时。可以通过 NCBI_CACHE_EXPIRE_HOURS 环境变量调整过期时长。

10.2 缓存控制与配置

# 1. 调整缓存有效期（例如设为 48 小时）
# Windows PowerShell
$env:NCBI_CACHE_EXPIRE_HOURS = "48"

# 2. 临时禁用缓存（绕过缓存，强制向网络发起实时请求）
# Windows PowerShell
$env:NCBI_NO_CACHE = "1"
python scripts/ncbi_search.py "APOE gene"

10.3 速率限制（内置）

即使在缓存未命中（Cache Miss）时，脚本也会自动处理 NCBI 的速率限制：

• 无 API Key: 每次请求间隔 ≥ 0.34 秒（≤ 3 次/秒）
• 有 API Key: 每次请求间隔 ≥ 0.11 秒（≤ 10 次/秒）
• 自动重试: 遇到 429/500/502/503/504 错误时自动重试 3 次

11. API Key 配置

11.1 获取 API Key

1. 注册 NCBI 账号
2. 进入 Settings → API Key Management → Create API Key
3. 复制生成的 API Key

11.2 配置方式

# Windows PowerShell（当前会话）
$env:NCBI_API_KEY = "your-api-key-here"

# Windows PowerShell（永久）
[Environment]::SetEnvironmentVariable("NCBI_API_KEY", "your-api-key", "User")

# 命令行指定
python scripts/ncbi_search.py "query" --api-key "your-api-key"

11.3 速率对比

12. 文件结构

ncbi-search/
├── SKILL.md                    # 本文档（AI Agent 技能说明）
├── README.md                   # 用户文档
├── LICENSE                     # MIT License
├── scripts/
│   ├── ncbi_search.py          # 主脚本：多数据库智能搜索
│   ├── pubmed_search.py        # PubMed 专用：自然语言转检索式
│   ├── pubmed_fetch.py         # 批量获取：通过 PMID 获取文献详情
│   └── ncbi_utils.py           # 工具函数
└── references/
    └── query_syntax.md         # PubMed 检索语法指南

参考链接

• NCBI E-Utilities 官方文档
• NCBI 数据库列表
• PubMed 检索语法

技能状态: 就绪

API 要求: NCBI API Key（免费，推荐配置）

费用: 完全免费

依赖: 仅需 Python 3.7+ 和 requests 库