技能介绍

要解决什么问题

做生信或临床注释时，你经常要在 NCBI Gene 里按符号、ID 或染色体位置查基因，还要拿到 RefSeq、GO、定位和同义名，并在几十上百个基因上重复同一套请求。手工在网页上点查既慢，也容易因未指定物种而把同名基因混在一堆结果里。

技能如何工作

本技能围绕 NCBI 的两条访问路径组织脚本与参考文档：

E-utilities：ESearch / ESummary / EFetch，适合复杂 Entrez 查询、跨库检索和多种输出格式（JSON、XML、文本等）。
NCBI Datasets API：面向「按 ID 拉一整包基因数据」，一次返回命名、转录本/蛋白 RefSeq、染色体位置、GO 与相关文献等结构化结果。

常见步骤可以概括为：用 scripts/query_gene.py 按符号或名称（务必带上物种，例如 insulin[gene name] AND human[organism]）解析基因 ID；用 scripts/fetch_gene_data.py 对已知 ID 做 Datasets 全量拉取；多个符号或 ID 时用 scripts/batch_gene_lookup.py 做批量处理，并在脚本侧处理速率限制。需要按功能或表型找基因时，可走 GO 术语、表型关键词或通路名称等 Entrez 查询模式。更细的端点与示例见技能内的 references/api_reference.md 与 references/common_workflows.md。

适用边界与注意点

无 API 密钥时 E-utilities 约 3 次/秒、Datasets 约 5 次/秒；注册 NCBI 密钥后可提高到约 10 次/秒。遇到 429 应对临时限流做指数退避重试。
按符号搜索时始终指定物种；能直接用 Gene ID 时优先 ID，减少歧义。
批量任务前建议先校验符号列表，避免拼写错误放大无效请求；重复查询宜本地缓存，减少 API 调用。