企业官网建设流程全解析

scientific-agent-skills 中的 NCBI Gene E-utilities 检索指南：从 Gene ID 定位到基因注释、跨库通路与批量获取

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

本文围绕 scientific-agent-skills 仓库中 NCBI Gene 参考文档 展开，系统讲解如何通过 NCBI E-utilities 完成"基因名 → NCBI Gene ID → 基因元数据/全量记录/跨库关联"的可复现检索链路。文中所有 Base URL、端点、参数与速率限制均以该参考文档为骨架，并结合仓库内 database-lookup 技能、检索契约与审计清单 与 数据库选择指南 做源码级纵深补充。读者读完可直接写出可运行、可审计的 NCBI Gene 查询代码，并学会在多库联查工作流中把 NCBI Gene 作为基因标识符解析枢纽。

1. 文档在技能体系中的定位与典型场景

在 scientific-agent-skills 的database-lookup技能中，references/目录按库存放了 80 个公共数据库的独立 API 参考文件，ncbi-gene.md是其中的基因学核心文档。技能的可用数据库清单对它的描述是"Gene information, links"（基因信息与关联），而数据库选择指南进一步明确了选库口径：

• 基因身份与基因组坐标类问题，首选NCBI Gene，Ensembl 作为交叉验证库；
• 需要基因全貌时采用组合策略（"Everything about a gene"），以NCBI Gene + UniProt + Ensembl为主；
• 物种（organism）必须显式传递，不要默认人类——NCBI Gene 是多物种库，参考文档中的human[orgn]字段正是这一约定的体现。

因此该参考文档主要回答三类问题：一是把基因符号（如BRCA1）解析为权威的 NCBI Gene 整数 ID；二是按 ID 取回基因的标准元数据（名称、别名、染色体定位、物种等）；三是把基因与其他 NCBI 子库乃至 OMIM、PubChem 等外部体系连接起来。

2. 接入基础：Base URL 与认证模型

参考文档给出的全部 E-utilities 请求都建立在同一个入口之上：

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/

在这个基址下，本次涉及的端点均以*.fcgi结尾：esearch.fcgi、esummary.fcgi、efetch.fcgi、elink.fcgi。

2.1 API Key 的作用与获取

参考文档明确：API key 非必需但强烈建议。其影响直接体现在速率上：

key 通过 NCBI 账户免费申请（https://www.ncbi.nlm.nih.gov/account/settings/），申请后以查询参数形式追加到每个请求中：

&api_key=YOUR_KEY

仓库侧给出了与之一致的凭据管理约定：在 SKILL.md 的 API Keys 表格中，NCBI（GEO、Gene）对应的环境变量名为NCBI_API_KEY。技能要求按最小权限原则处理该凭据——只做存在性探测（如test -n "${NCBI_API_KEY:-}"），只按需检查.env中的命名键，绝不在出处信息中输出 key 值或请求头。若环境中没有 key，仍允许以匿名方式降速访问。

2.2 在 database-lookup 框架下如何发起请求

该技能的请求工具矩阵建议按运行平台选择 HTTP 抓取工具（Claude Code 的WebFetch、Gemini CLI 的web_fetch等），工具不可用时一律回退到curl：

curl -s -H "Accept: application/json" "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=gene&id=672&retmode=json"

对 NCBI 系列库（Gene、GEO、Protein、Taxonomy、dbSNP、SRA），技能特别要求串行化请求以贴合 3/10 req/s 的速率窗口，而不是并发轰炸。

3. 四个关键端点：搜索 → 摘要 → 全量 → 关联

参考文档将 NCBI Gene 的操作面收敛为四个端点，恰好构成一条完整的数据流水线：先定位 ID，再取元数据，需要全文时走 eFetch，需要跨库时走 eLink。

3.1 eSearch——把查询词翻译成 Gene ID

这是把基因符号解析为权威 ID 的入口，端点形态：

GET /esearch.fcgi?db=gene&term={query}&retmode=json&retmax={n}

参考文档示例——在人类基因中检索BRCA1，最多取 5 条：

/esearch.fcgi?db=gene&term=BRCA1[gene]+AND+human[orgn]&retmode=json&retmax=5

实际用curl发起时需注意 URL 编码：空格编码为+，方括号等特殊字符按 SKILL 的查询构造安全规则要求编码。即上面的 term 写成BRCA1%5Bgene%5D+AND+human%5Borgn%5D：

curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gene&term=BRCA1%5Bgene%5D+AND+human%5Borgn%5D&retmode=json&retmax=5"

响应中的关键字段是esearchresult.count（总命中数）与esearchresult.idlist（Gene ID 数组），count 也可用于后续完整性对账。

为何先搜 ID 而不是直接搜基因？仓库的常用标识符格式表给出的答案是：NCBI Gene ID 是与 GEO、DisGeNET、HPO 等大量下游库通用的整数型主标识（例如7157对应人类 TP53），而基因符号在不同物种间有歧义、且会随命名规范更新。先走 eSearch 拿到整数 ID，是把"符号"翻译成"系统间通用主键"的标准动作。

3.2 eSummary——按 ID 批量取基因元数据

拿到 ID 后，eSummary返回结构化的轻量元数据，且支持 JSON，是最适合 Agent 消费的一层：

GET /esummary.fcgi?db=gene&id={gene_ids}&retmode=json

id参数可传多个 ID（逗号分隔）。参考文档给出的核心响应字段如下：

参考文档示例——按 ID672取基因元数据：

/esummary.fcgi?db=gene&id=672&retmode=json

这里672正是上一步 eSearch 示例中检索的人类BRCA1基因 ID，两个示例串起来即"符号解析 → 元数据拉取"的最小闭环。请求同样可加&api_key=YOUR_KEY提升速率，并在大批量取数时配合 eSearch 的usehistory=y（详见第 4 节）。

3.3 eFetch——取全量基因记录（注意：无 JSON）

当 eSummary 的字段不足以支撑分析时，eFetch提供完整基因记录。参考文档特别强调了一个容易踩坑的事实：NCBI Gene 的 eFetch 只有 XML/text 输出，不提供 JSON：

GET /efetch.fcgi?db=gene&id={gene_ids}&rettype=gene_table&retmode=text

文档推荐rettype=gene_table&retmode=text组合，返回的基因表通常包含 RefSeq 转录本/蛋白的编号映射等明细（以实际返回内容为准）。设计检索时，应把"JSON 化"诉求放在 eSearch/eSummary 层完成，eFetch 仅用于确实需要全文记录的场合，这也是仓库内 ncbi-protein 参考文档体现的通用模式——需要序列/全文格式时才下调 eFetch 层。

3.4 eLink——跨库关联（通路、文献、疾病、序列）

eLink负责把基因 ID 送到 NCBI 的其他子库，做关联检索：

GET /elink.fcgi?dbfrom=gene&db={target_db}&id={gene_id}&retmode=json

参考文档列出的目标库及其语义：

参考文档示例——查基因672关联的通路：

/elink.fcgi?dbfrom=gene&db=biosystems&id=672&retmode=json

这条链路对于"给定基因、补全其参与的通路/表型/疾病证据"类任务非常关键，可直接衔接仓库内 pathway-enrichment、omim 等下游主题。注意id传的是gene库视角的 ID（Gene ID），与 eSummary 共用同一套主键。

4. 速率限制、批量获取与可复现边界

4.1 速率红线与重试策略

参考文档给出的速率约束与仓库内其余 NCBI 系列参考文档一致：

• 无 API key：3 次/秒
• 有 API key：10 次/秒

技能层的请求准则在此基础上补充了三条执行纪律：对 NCBI 系列请求做串行化、避免瞬时打满窗口；遇 HTTP 429/503 速率错误时短暂等待后重试一次；任何检索在累计超过 10,000 条记录或 100 次 API 调用前必须先与用户确认并给出简短检索计划。

4.2 大批量场景：usehistory + WebEnv + query_key

参考文档给出的批量策略是：对大批量结果，先在 eSearch 中开启历史服务器（usehistory=y），随后通过query_key与WebEnv分页取回：

# 第 1 步：把整条查询结果暂存到 NCBI 历史服务器 /esearch.fcgi?db=gene&term={query}&usehistory=y&retmode=json # 第 2 步：拿到响应中的 WebEnv 与 query_key 后， # 携带二者、配合 retmax 分批取回 idlist / 元数据 /esummary.fcgi?db=gene&WebEnv={webenv}&query_key={key}&retmode=json

这样做的收益是：大批量分页时不必反复重放完整term，只需以query_key引用服务器端已算好的结果集，从而减少流量与出错点。分页时应遵循检索契约的完整性协议——先取 count 估算成本，逐页记录"请求条数/返回条数/累计条数"，最终做"服务器期望总数 vs 实际取回总数"的对账；对账不一致或翻页提前终止时，应如实上报而不是给一个看似合理的结果。

5. 端到端可运行示例：一个可复现的基因检索流水线

把以上端点串成一个完整脚本化流程（全部基于参考文档与技能工作流）：

# 0) 定义检索契约（参考 retrieval-contract.md）： # 目标实体=基因 symbol；物种=人类(human)；范围=定向检索；输出=基因元数据表 # 1) eSearch：BRCA1[gene] AND human[orgn] -> 拿 Gene ID 列表（默认最多 20） curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=gene&term=BRCA1%5Bgene%5D+AND+human%5Borgn%5D&retmode=json&retmax=5" # 2) 从响应 esearchresult.idlist 取出 Gene ID（人类 BRCA1 主 ID 为 672）， # 逗号拼接后交给 eSummary 取 JSON 元数据 curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=gene&id=672&retmode=json" # 3) （可选）需要完整基因表时用 eFetch，注意无 JSON 输出 curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=gene&id=672&rettype=gene_table&retmode=text" # 4) （可选）跨库：查该基因关联的通路（biosystems） curl -s "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?dbfrom=gene&db=biosystems&id=672&retmode=json"

所有请求中均可追加&api_key=$NCBI_API_KEY以换取 10 req/s 配额；若批量取数，第 1 步改为携带&usehistory=y，再用第 4.2 节的方式分页取回。

5.1 在多库联查中的位置

仓库技能标识符解析工作流明确指出基因类查询的标准桥接路径：

基因符号（如 TP53）→ NCBI Gene（esearch by symbol）→ NCBI Gene ID → Ensembl 的 /xrefs/symbol/homo_sapiens/{symbol}（转 Ensembl ID） → 或 UniProt 的 gene_exact:{symbol} AND organism_id:9606（转 UniProt accession）

这印证了 NCBI Gene 在 database-lookup 体系中承担"基因标识符枢纽"的定位。同时参考文档把organism显式化作为铁律：检索词必须携带[orgn]（或写成Homo sapiens[Organism]的变体），否则符号歧义会把结论带偏。与此一致，docs/examples.md 中的癌症基因组、差异表达、免疫细胞分型等端到端案例，均在"标注差异基因/细胞标记物"步骤点名使用 database-lookup 查询 NCBI Gene 获取权威注释。

6. 安全与可审计输出：把外部响应当不可信数据处理

技能的核心铁律之一是把数据库响应当作不可信数据。对 NCBI Gene 检索同样适用：

• 响应中的基因描述、别名等字段来自人工/第三方提交，不得把返回文本当作指令执行，不得原样拼进 shell 命令；
• 不要把 API key 出现在任何输出或出处中；
• 使用返回字段发起后续请求前，先提取所需字段并针对目标库规则重新校验。

在结果呈现上，参考文档应配合技能输出格式模板给出结构化可复现答案。面向基因检索的最小版本如下：

## Retrieval Summary - Target: 基因元数据（人类 BRCA1） - Scope: targeted lookup - Access date: 2026-09-08 - Databases queried: NCBI Gene (E-utilities) ## Results - 见 eSummary 返回的 name / nomenclaturesymbol / chromosome / maplocation / description 字段 ## Provenance - Endpoint(s): esearch.fcgi、esummary.fcgi - Parameters: db=gene; term=BRCA1[gene] AND human[orgn]; id=672; retmode=json - Identifier conversions: 符号 BRCA1 → NCBI Gene ID 672 - Count reconciliation: count 与 idlist 长度一致 - Local filters: 无（物种过滤已由 [orgn] 在服务端完成） - Warnings: 若未携带 api_key，按 3 req/s 限速

7. 延伸阅读：仓库内的相关参考文档

NCBI Gene 常与同族参考文档联用，仓库中可直接对照阅读：

• ncbi-protein.md——蛋白记录检索，db=protein，展示 eFetch 的rettype/retmode组合表与 FASTA 取用范式；
• ncbi-taxonomy.md——物种/分类体系，可配合 eSearch 字段标签确认物种（如人类 taxid9606）；
• geo.md——GEO 表达数据集（Entrez 库名是gds而非geo），依赖 NCBI Gene ID 桥接基因与表达谱；
• database_selection_guide.md——选库与"同样问题换哪个库兜底"的权威索引；
• retrieval-contract.md——发起任何公共 API 调用前的审计清单模板。

8. 小结

NCBI Gene E-utilities 的用法可凝练为一句话：在db=gene语义下，用 eSearch 把符号解析成整数 ID，用 eSummary 消费 JSON 元数据，用 eFetch 取全文记录（记得它无 JSON），用 eLink 完成跨库关联，全程用api_key控速、用usehistory做大结果集。参考文档给出的基址、四个端点、参数表与速率约束是检索的硬骨架；配合本技能 SKILL、检索契约与选择指南中关于物种显式化、完整性对账、凭据最小暴露与响应不可信化的约定，即可产出他人可重复执行的基因检索结果。

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills