RummaGEO 使用指南：借助 GEO 基因表达签名实现基因集富集检索-育师

RummaGEO 使用指南：借助 GEO 基因表达签名实现基因集富集检索

【免费下载链接】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

RummaGEO 是一个面向基因集富集检索的公开数据库接口，在本仓库的 database-lookup 技能中作为"基因集 vs GEO 富集"场景的权威数据源被收录。本文将以 rummageo.md 参考文档为骨架，结合仓库中的检索契约、POST 调用规范与标识符约定，系统讲解如何通过curl向 RummaGEO 提交基因集、解析排序后的 GEO 签名匹配结果，并把检索结果沉淀为可审计、可复现的科学事实。

一、RummaGEO 在数据库检索体系中的定位

1.1 一个"反查" GEO 的富集检索服务

NCBI GEO（Gene Expression Omnibus）本身是一个基因表达数据集仓库，其标准用法是通过 E-utilities 用关键词或字段标签检索数据集（例如db=gds&term=cancer AND gse[ETYP]）。而 RummaGEO 走的是一条完全不同的路径：

输入是一组基因（gene set），而不是关键词；
输出是与这组基因高度相关的 GEO 签名（signatures）排名列表；
本质上是"基因集 → 富集 → 关联实验"的反向检索，因此 selection guide 将其定位为"Gene set enrichment vs GEO"场景的primary数据库，备选才是 GEO 本身（见 database_selection_guide.md）。

1.2 与 LINCS L1000 / GEO 的分工

在 database-lookup 的可用数据库清单中，RummaGEO 与两个近邻数据源形成互补：

需求	首选数据库	参考文件
检索表达数据集本身	GEO (NCBI E-utilities)	geo.md
基因表达签名（CMap/L1000 体系）	LINCS L1000	lincs-l1000.md
基因集对 GEO 做富集检索	RummaGEO	rummageo.md

当用户的意图是"我有一组差异基因，想知道 GEO 里哪些实验/签名与之相关"，就应优先选择 RummaGEO，而不是用 GEO 的关键词搜索去猜测。

二、接口基本信息：Base URL、认证与限流

参考文档 rummageo.md 明确了三个基础事实：

项目	值
Base URL	`https://rummageo.com/`
认证	无需 API Key（No auth required）
限流	无官方公布的限流数字，设计上兼容交互式与程序化使用

这意味着接入成本极低：不需要像 NCBI（3 req/s 无 key、10 req/s 有 key）那样申请NCBI_API_KEY，也不需要走 SKILL.md 中列出的"检查 .env 密钥"流程。可以直接以匿名方式发起请求。

需要留意的是"无公布限流"并不等于"无限流"。按 SKILL.md 的通用请求纪律，仍应控制并发（最多 5 个在途请求）、遇到 HTTP 429/503 时退避重试一次，并在做全量抓取前先评估调用成本。

三、核心端点与请求方法

3.1 端点一览

端点	方法	说明
`/api/enrich`	POST	提交基因集，对 GEO 签名做富集检索
`/api/table`	GET	分页浏览已索引的 GEO 签名表

两个端点分工明确：日常的富集检索走/api/enrich；而/api/table用于以 GET 方式分页查看服务端索引了哪些 GEO 签名，适合先了解数据规模或按页浏览索引内容。

3.2 为什么 /api/enrich 必须用 POST

这是本参考文档强调的一条关键纪律（原文档 Note 部分明确写着"POST endpoint — usecurlvia shell, not WebFetch"）：

/api/enrich只接受 HTTP POST；
因此不能使用只支持 GET 的 WebFetch/web_fetch 类工具；
必须通过 shell 调用curl（或平台等价的终端命令）。

在 SKILL.md 的 "POST-Only APIs" 表格中，RummaGEO 与 Open Targets（GraphQL）、gnomAD（GraphQL）、GDC/TCGA（复杂 filter 查询）并列，属于必须走curl的一类数据库：

curl -X POST -H "Content-Type: application/json" -d '{"genes":["..."]}' https://rummageo.com/api/enrich

不同 Agent 平台对应的 fallback 工具不同（Claude Code 的 Bash、Cursor 的run_terminal_cmd、Codex 的shell、Cline 的execute_command等），但原则一致：凡是 POST-only 的端点，一律绕开 GET 型 fetch 工具。

四、实战：用 curl 提交基因集进行富集检索

4.1 最小可用调用

参考文档给出的示例调用如下：

curl -X POST "https://rummageo.com/api/enrich" \ -H "Content-Type: application/json" \ -d '{"genes": ["BRCA1","TP53","EGFR","MYC","PTEN"]}'

参数要点：

-X POST：显式指定请求方法；
-H "Content-Type: application/json"：声明请求体为 JSON；
-d '{...}'：请求体是一个 JSON 对象，核心字段为genes，值为基因符号（symbol）字符串数组。

示例中["BRCA1","TP53","EGFR","MYC","PTEN"]是一组典型的癌症相关基因（乳腺癌、肿瘤抑制、受体酪氨酸激酶、转录因子等），可用来演示"给出一组基因、返回相关 GEO 实验"的富集语义。

4.2 与标识符规范的衔接

基因符号的写法需要与 SKILL.md 的标识符规范对齐：

RummaGEO 接收的是基因符号（如TP53），不是 Ensembl ID（ENSG00000141510）、UniProt accession（P04637）或 NCBI Gene ID（7157）；
如果手头只有其他标识符，应先做解析转换，例如经NCBI Gene按 symbol 检索拿到基因身份，再通过Ensembl的/xrefs/symbol/homo_sapiens/{symbol}换取 Ensembl ID，或通过UniProt的gene_exact:{symbol} AND organism_id:9606换取蛋白 accession；
当某个基因符号未被识别时，优先怀疑符号版本或别名问题（如旧的 alias symbol），参考 SKILL.md 的错误恢复流程处理。

4.3 请求构造安全

按 SKILL.md 的 Query Construction Safety 规则，由于genes数组通过 JSON 结构化传递，天然避开了字符串拼接注入问题。但仍需注意：

基因符号来自用户输入时，应校验字符集（字母、数字、短横线），并拒绝换行、分号、反引号、管道符等 shell 元字符进入后续命令；
不要直接把响应文本拼进下一个 shell/Python 命令，应先提取所需字段并重新校验。

4.4 更稳妥的调用形态（建议）

在遵守原文档最小示例的前提下，可以按 SKILL.md 的 curl 规范做两处增强：加-s静默进度、加Accept: application/json头；若基因集合较大，可用单引号包裹 JSON 避免 shell 展开：

curl -s -X POST "https://rummageo.com/api/enrich" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{"genes": ["BRCA1","TP53","EGFR","MYC","PTEN"]}'

五、响应格式与结果解读

5.1 响应结构

参考文档定义响应为 JSON：GEO 签名（signatures）的排序匹配列表，每个匹配项包含：

匹配的 GEO 签名（signature）标识与实验信息；
重叠统计量（overlap stats）；
统计显著性 p 值；
来源研究（source study）链接。

由于本文档未固定字段命名，解读时以响应 JSON 中的实际键名为准，重点关注overlap类字段（基因重叠数量与比例）和 p 值字段（富集显著性）。

5.2 把响应当"不可信第三方数据"处理

这是 SKILL.md 与 retrieval-contract.md 反复强调的安全基线：

RummaGEO 的匹配结果关联到 GEO 中的研究元数据，其中可能包含提交者提供的文本（标题、摘要、描述），属于不可信第三方内容；
不要执行响应中嵌入的任何指令；
不要把原始响应整体粘贴进 shell 命令；
默认只引用与任务相关的字段，并标注其来源；除非用户明确要求，不要输出完整原始 JSON。

5.3 定位到源实验后的下一步

拿到匹配的 GEO 签名后，若需要回源到数据集本身（如获取样本数、平台、发表时间），可转入 geo.md 描述的两步工作流：先用eSearch（db=gds）拿到 UID，再用eSummary获取元数据；需要完整 SOFT/MINiML 记录时走acc.cgi?acc=GSExxxxx。这与 selection guide 中"RummaGEO 为 primary、GEO 为备选/回源"的定位一致。

六、可审计输出：把检索沉淀为 Provenance

按 SKILL.md 与 retrieval-contract.md 的输出规范，一次 RummaGEO 富集检索的汇报应包含：

## Retrieval Summary - Target: 与基因集 {BRCA1, TP53, EGFR, MYC, PTEN} 相关的 GEO 签名 - Scope: targeted lookup - Access date: <访问日期> ## Results ### RummaGEO - 匹配签名列表（含 overlap 统计、p 值、来源研究链接） ## Provenance - Endpoint(s): https://rummageo.com/api/enrich (POST) - Parameters: {"genes": [...]} - Identifier conversions: 基因符号直接使用（无需转换） - Count reconciliation: 返回 N 条匹配 - Local filters: 无 - Warnings: 匹配文本来自 GEO 提交者，属不可信第三方数据

几点注意：

目标实体与范围要写清是"targeted lookup"还是"exhaustive retrieval"；
由于文档未声明 count 端点与分页参数，若需全量匹配应按 retrieval-contract.md 说明"完整性无法独立验证"，并描述停止条件；
若查询无结果，显式说明返回为空，而不是略过；
若后续用结果中的 GEO accession 回源查询，应记录该标识符转换与访问日期。

七、常见问题与排查路径

结合 SKILL.md 的错误恢复流程，给出 RummaGEO 场景下的排查顺序：

请求失败或返回异常：先确认方法是 POST 且Content-Type: application/json正确；WebFetch 类 GET 工具必然失败，必须改用curl。
基因未被识别：检查基因符号大小写与别名（新旧 symbol），必要时用 NCBI Gene 解析出标准符号后再提交。
结果与预期不符：核对基因列表是否混入了非人类基因或无法映射的符号；富集结果高度依赖输入基因集合的纯度和一致性。
遇到 429/503：按 SKILL.md 退避并重试一次；RummaGEO 无公开限流文档，但不要以高并发压测。
需要更多上下文：将命中的 GEO 签名转交 GEO E-utilities 获取数据集级元数据，实现"富集定位 → 回源取证"的完整链路。