scientific-agent-skills 数据查询实战KEGG REST API 参考速查与可审计检索指南【免费下载链接】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-skillsKEGGKyoto Encyclopedia of Genes and Genomes是生物信息学中最常被引用的通路与分子数据库之一本仓库的 database-lookup 技能将其封装为标准化的可重复检索流程。本篇以 database-lookup 技能 中的 KEGG 参考文档 为主体讲解 KEGG REST API 的全部核心操作、数据库代码约定、响应格式与限流规则并结合仓库内的源码、跨技能工作流与检索契约给出可直接复制的查询示例与审计化输出的实战方法。读完你将掌握如何用 URL 路径式端点完成通路列表、条目拉取、关键字/分子式/精确质量检索、跨库关联与 ID 换算如何在 Agent 环境下通过 curl 稳定调用 KEGG以及如何将结果组织成可溯源、可复现的检索报告。KEGG 在 database-lookup 技能中的定位database-lookup 技能目前收录了约 78 个公开数据库的 API 访问档案每个数据库在references/目录下拥有独立参考文件KEGG 对应 references/kegg.md。该技能将数据库按领域归类KEGG 归入 “Chemistry Drugs / Biology Genomics” 双重覆盖范围官方描述为覆盖 “Pathways, genes, compounds”通路、基因与化合物。从技能选库指南database_selection_guide.md可以看出 KEGG 的典型回答面“哪个基因/蛋白质参与了哪些通路”→ 首选 Reactomemapping或KEGG“酶动力学/催化活性”→ 首选 BRENDA备选KEGG涉及多种生物的通路问题中KEGG 使用生物体代码如人hsa、小鼠mmu区分物种。技能的核心流程见 SKILL.md要求先界定检索契约实体、标识符、物种/版本、过滤条件再读对应参考文件确认端点格式然后做有界、限速的 API 调用最后返回带溯源的结果。KEGG 参考文件就是整个检索链中“端点细节、查询格式与示例调用”的权威依据。值得注意的是仓库另外提供了 bioservices 技能它以 Python 库方式统一封装了 40 生物服务含 KEGG 的通路与化合物数据。二者的分工是需要跨数据库一致的 Python API 与结果对象时用 bioservices快速、单次、可审计的原始端点查询用 database-lookup。两条路径最终都落在同一个 KEGG REST 服务上因此理解本文的端点约定对两类使用方式都适用。服务基础Base URL、认证与许可KEGG REST API 的服务根地址固定为https://rest.kegg.jp关于访问权限参考文件明确三点无需 API Key请求不携带密钥即可访问学术用途免费免费适用于学术研究商业用途需许可商用前需向 KEGG 申请商业授权。也就是说Agent 在科学检索场景中可以零配置直接发起 GET 请求。这一点也解释了为什么 KEGG 没有出现在技能文档的 “Databases requiring API keys” 表格中该表列出的 FRED、NCBI、OpenFDA、OMIM、DisGeNET 等都需要注册密钥同时技能在“付费/受限访问数据库”一节中推荐当 BRENDA 等酶学数据库因注册限制不可用时用 KEGG 作为酶/通路数据的免费替代源——这正是 KEGG 在技能生态中扮演的兜底角色。响应格式tabular 文本与 flat-file没有 JSON使用 KEGG REST 前必须先建立一个心智模型该 API 只返回制表符分隔的纯文本与 flat-file 格式不支持 JSON。具体区分如下端点类型返回格式list/find/link/conv/ddi制表符分隔文本tab-delimited一行一条记录列之间以\t分隔getflat-file 格式条目详情类键值文本块get/.../imagePNG 通路图get/.../kgmlKGML XMLKEGG Markup Language这一约束直接影响 Agent 的解析策略不要试图对返回体做JSON.parse而应使用文本流处理。例如用 curl 拉取后交给cut、head、grep或在后续脚本里按行按\t切分。参考文件还特别提醒从多个数据库聚合数据时KEGG 这类非 JSON 响应正是 “小的过滤差异可能改变下游结论” 的高危环节必须逐字段核对列含义而不是笼统地把整行文本当作答案。端点设计哲学全部基于 URL 路径而非查询参数KEGG REST 的一个重要特征是URL-path-based操作、数据库、目标全部通过路径段表达基本不依赖?keyvalue查询参数。这意味着URL 天然稳定、易缓存、易审计端点和参数可以完整记录在溯源信息中不能依赖通用 HTTP 客户端的 query 参数机制必须用正确的路径拼接中文/特殊字符出现频率低但含冒号的条目 ID如hsa:10458在作为文本处理时要注意不要被工具当作协议前缀误解析。核心操作一览完整继承自 references/kegg.mdURL 模式说明/list/{database}列出某数据库全部条目/list/{database}/{organism}列出某生物体的条目如人类全部通路/get/{dbentries}获取条目数据flat-file 格式/get/{dbentries}/image获取通路图片PNG/get/{dbentries}/kgml获取通路 KGML XML/find/{database}/{query}按关键字搜索/find/{database}/{query}/formula按分子式搜索/find/{database}/{value}/exact_mass按精确质量搜索/link/{target_db}/{source_db}查找两个数据库之间的关联条目/link/{target_db}/{dbentries}查询指定 ID 的关联/conv/{target_db}/{dbentries}跨库 ID 换算/ddi/{dbentries}药物-药物相互作用下面按用途对每个操作做深度展开。枚举条目/list/list用于批量枚举。最常用的是按物种列通路与基因# 列出人类hsa全部 KEGG 通路 https://rest.kegg.jp/list/pathway/hsa # 列出人类全部基因超长结果建议配合有界策略使用 https://rest.kegg.jp/list/hsa该端点返回 tab 分隔的两列KEGG ID 与描述。在仓库的多组学流程中见 docs/examples.md 第 1526–1540 行的 “Step 5: Map all features to KEGG pathways”第一步就是把基因与代谢物映射为 KEGG 通路 ID随后再做富集——而list正是获取某物种全通路清单以核对覆盖度的入口。同样思路也体现在 pathway-enrichment 技能 中它把 KEGG 视为人工注释、紧凑的代谢/信号通路集合建议在富集前先明确 “有哪些可用基因集”。获取条目详情/get/get返回 flat-file 文本是查看单一实体全部注释的核心端点# 获取人类糖酵解/糖异生通路条目 https://rest.kegg.jp/get/hsa00010 # 获取化合物条目 https://rest.kegg.jp/get/C00001 # 一次获取多个条目最多 10 个用 连接 https://rest.kegg.jp/get/C00001C00002C00003多条批取的上限为10 个 ID这正是 KEGG 提供的“批量”手段——相比逐个请求把 2–10 个 ID 拼进一次/get能成倍降低请求频率。通路与化学反应型条目还可追加后缀# 通路图片PNG https://rest.kegg.jp/get/hsa00010/image # 通路 KGML机器可读的路径图 XML https://rest.kegg.jp/get/hsa00010/kgmlkgml后缀在仓库中具有实际用途bioservices 技能的 pathway_analysis.py 就通过解析 KGML 提取通路内的基因节点与边parse_kgml_pathway后再对每个节点补充kegg.get用于下游网络构建。需要注意KGML 按通路返回成百上千的基因节点逐个二次 GET 会放大请求量——该脚本因此提供了--limit参数仓库安全报告中也将这种“无默认限流地逐个拉取通路”标记为资源占用层面的隐患。对 Agent 而言这提示KDML 拉取属于典型的“先评估再批量”场景应遵循技能设定的有界调用规则见下文限流节。关键字检索/find/find面向按名称/关键字找条目的需求支持多数据库# 按名称搜索化合物阿司匹林 https://rest.kegg.jp/find/compound/aspirin # 按分子式搜索阿司匹林 C9H8O4 https://rest.kegg.jp/find/compound/C9H8O4/formula # 按精确质量搜索 https://rest.kegg.jp/find/compound/180.0423/exact_mass三条路径分别对应三种检索维度名称弱校验、易出现同义词歧义、分子式注意同分异构问题参考仓库在代谢物鉴定中强调“仅凭精确质量无法区分异构体”、精确质量适合与质谱实验数据对接。find返回 tab 分隔文本每行以数据库前缀 ID 开头如cpd:C00001再接名称与注释字段。分子式/质量检索的一个直接落地场景来自 bioservices 的 compound_cross_reference.py它先以KEGG.find定位化合物并取回以cpd:开头的 KEGG IDparts[0]再调用kegg.get(cpd: kegg_id)拉取详情抽取公式、精确质量、分子量与所属通路最后换算到 ChEMBL/ChEBI 并落盘。这展示了把/find与/get串成“检索 → 取详情 → 换算”完整链路的典型模式。跨库关联/link/link解决“一个实体在另一个数据库中对应什么”这类问题方向参数写为目标库/源# 一个基因参与哪些通路 https://rest.kegg.jp/link/pathway/hsa:10458 # 一个基因关联哪些疾病 https://rest.kegg.jp/link/disease/hsa:672 # 基因→KO 直系同源分组多组学映射的基础 https://rest.kegg.jp/link/ko/hsa:10458该操作能回答 docs/examples.md “药物重定位”示例的第一步——查询疾病相关通路与关键蛋白——以及多组学工作流中的“基因→KO 术语”“蛋白→KEGG 反应”等映射步骤。由于link一次输入多个条目连接会返回多条关联Agent 应在拿到结果后做计数核对防止遗漏分页。ID 换算/conv不同数据库标识体系不同/conv负责无损换算# KEGG 化合物 → PubChem https://rest.kegg.jp/conv/pubchem/C00001技能文档中标识符换算的推荐链路如 NCBI Gene ID→Ensembl→UniProt、PubChem CID→ChEMBL与 KEGG 的conv思路一致当用户给出的是 KEGG 侧 ID如C00001而下游数据库需要 PubChem CID 时/conv/pubchem/C00001即为最直接的桥接。反之也可用conv把外部 ID 转回 KEGG 再走link/get。药物-药物相互作用/ddi# 查询两种药物的相互作用 https://rest.kegg.jp/ddi/D00564D00110/ddi接受药物条目 IDD 前缀支持多条连接。在药物重定位与安全性评估类查询中这是 KEGG 区别于纯通路数据库的独特能力。注意返回的是 KEGG 注释的相互作用信息属于数据库第三方注释文本参考文件的安全原则要求将其视为不可信内容摘要引用而非直接当作临床结论。数据库代码与标识符约定请求路径中的{database}与条目前缀必须使用官方代码。参考文件给出的速查表如下Code数据库示例 IDpathway通路hsa00010compound化合物C00001drug药物D00001enzyme酶ec:1.1.1.1genes/hsa基因物种代码按生物体不同hsa:10458disease疾病H00001reaction反应R00001koKO 直系同源K00001需要进一步注意的三点约定物种代码即数据库维度基因相关查询用物种代码人hsa、小鼠mmu代替抽象库名例如/list/hsa等价于枚举人类genes库。技能选库指南强调“物种很重要不要默认假设人类”KEGG 侧必须显式传递hsa/mmu/eco等代码。genes/hsa双写法文档表格用genes/hsa并列表述说明在以hsa为例时它既代表库名也代表物种过滤。请求若返回空或 404先检查物种代码是否写对。内部前缀差异KEGG 的 flat-file 中化合物 ID 常带cpd:前缀、酶带ec:、基因带物种前缀hsa:但 URL 端点对C00001、ec:1.1.1.1这类带前缀 ID 都能直接接受。从源码可见解析返回体时普遍需要剥离cpd:等前缀parts[0].replace(cpd:, )拼回请求时则需要决定是否补回前缀——这是 Agent 在“读结果 → 发下一个请求”循环中最容易踩的坑。复合检索实战把操作串成可回答科研问题的链路单个端点只能解决单步问题真正的科研查询需要串联。下面结合仓库示例docs/examples.md给出三条代表性链路其中均为 KEGG REST 路径形式可直接在 curl/浏览器/Agent HTTP 工具中执行。链路 A疾病相关通路梳理药物重定位示例的起点# 1) 疾病条目及其关联通路/基因 https://rest.kegg.jp/get/H00001 # 2) 指定基因在哪些通路里 https://rest.kegg.jp/link/pathway/hsa:10458 # 3) 通路详情与组成 https://rest.kegg.jp/get/hsa00010对应仓库中“查询 KEGG 与 Reactome 的疾病相关通路 → 识别关键蛋白/酶 → 映射上下游通路组分”的研究流程。链路 B基因→蛋白→代谢物多组学通路映射# 基因映射到 KO 直系同源 https://rest.kegg.jp/link/ko/hsa:10458 # 蛋白/酶映射到反应 https://rest.kegg.jp/link/reaction/hsa:10458 # 代谢物映射到所属通路化合物 C 前缀检索 https://rest.kegg.jp/get/C00001链路 C分子式出发的未知物归属质谱场景# 1) 精确质量/分子式命中候选化合物 https://rest.kegg.jp/find/compound/180.0423/exact_mass # 2) 对候选逐个取详情比对名称与通路 https://rest.kegg.jp/get/C00001 # 3) 候选换算到 PubChem 便于对照实验库 https://rest.kegg.jp/conv/pubchem/C00001这类跨库组合查询完成后检索契约模板retrieval-contract.md要求记录目标实体、范围定向 vs 穷尽、访问日期、端点到参数、ID 换算关系、服务端过滤与本地过滤、计数核对及局限性警告。KEGG 由于不支持 count 端点穷尽性检索时应明确说明“无法独立验证完整性”并以停止条件如某个物种通路清单的分页遍历完毕作为完成标志。调用方式与限流Agent 环境下的稳定实践用 curl 而非专用 fetch 工具KEGG 是纯 GET、无 JSON 的文本接口curl 是最通用且唯一必要的手段。技能文档的“Making API Calls”一节指出各平台 HTTP 抓取工具并不一致Claude Code 的WebFetch、Gemini 的web_fetch、Cursor/Codex/Cline 无专用抓取工具但统一回退方案都是 curl# 基本形态 curl -s https://rest.kegg.jp/list/pathway/hsa # 关键字检索并直接查看前几行 curl -s https://rest.kegg.jp/find/compound/aspirin | head -5 # flat-file 详情 curl -s https://rest.kegg.jp/get/hsa00010 # 批量多条目 curl -s https://rest.kegg.jp/get/C00001C00002C00003限流与有界调用规则KEGG 官方没有公布硬性速率上限参考文件给出的操作性约定是每秒保持几次请求以内请求过密时服务端可能返回 HTTP 403需退避重试/get单次最多拼 10 个 ID这是内置的批量手段应优先使用以减少请求次数官方建议以“对学术友好”的方式使用商用需授权。叠加 database-lookup 技能的通用有界规则Agent 应大规模检索前先预估成本穷尽式任务超过 10,000 条记录或 100 次 API 调用前先向用户确认并给出简短计划对 KEGG 这类限流敏感的服务串行请求避免并行风暴遇到 429/403/503短暂等待后重试一次仍失败则显式报告失败而非“看起来成功”通路图谱类批量任务逐个 KGML 逐个get先跑小样本验证耗时再决定是否全量可参考 bioservices/scripts/pathway_analysis.py 的--limit设计。错误恢复参考文件总结了错误恢复顺序适配到 KEGG检查标识符格式hsa:10458、C00001、H00001、K00001各自属于不同库把基因符号TP53直接拼进/get会失败需要先换算成hsa:10458形式的 KEGG 基因 ID。尝试替代标识符化合物名检索失败时改试分子式、精确质量或直接跳C00001编号查询。换库兜底KEGG 不可用时按选库指南在 Reactome通路映射、BRENDA酶学之间切换——技能文档与 pathway-enrichment 的库说明 均明确把 KEGG 与 Reactome 列为可互备的通路源。显式报告失败告知用户哪个库失败、报什么错、改用了什么替代不得静默返回空结果。返回结果的审计化输出模板KEGG 查询结果不是终点可复现才是 database-lookup 技能的验收标准。对任何非平凡 KEGG 查询最终答复应结构化呈现模板见 SKILL.md 的 Output Format 与 retrieval-contract.md 的 Provenance Template## Retrieval Summary - Target: 化合物 C00001 所属通路及其与疾病 H00001 的关联 - Scope: targeted lookup - Access date: 2026-09-08 - Databases queried: KEGG ## Results - /link/pathway/C00001 → pathway:hsa00010 (Glycolysis / Gluconeogenesis) 等 N 条 - /get/hsa00010 → 通路标题、基因组分摘要 ## Provenance - Endpoint(s): https://rest.kegg.jp/link/pathway/C00001; https://rest.kegg.jp/get/hsa00010 - Parameters: 路径式无查询参数 - Identifier conversions: C00001 无换算如需 PubChem 可 /conv/pubchem/C00001 - Count reconciliation: KEGG 无 count 端点无法独立核对穷尽性 - Warnings: 通路注释含第三方文本引用时摘要化处理特别地由于 KEGG 响应是纯文本若用户要求原始输出应只引用有界切片并在回复中标注为“不可信的第三方数据”绝不可将整段返回体直接喂给后续 shell/Python 命令技能文档与检索契约都明确禁止把响应原文拼进命令。小结KEGG REST API 以“路径即参数”的简洁设计和免费学术访问成为通路、基因、化合物与药物检索的首选免费源之一。其要点可归纳为四句话base 固定为https://rest.kegg.jp、无需密钥返回 tab 分隔文本与 flat-file绝无 JSON物种靠hsa/mmu等代码显式表达批量靠/get的 10 个连接与/link组合完成。把 references/kegg.md 这份端点档案与 database-lookup 技能 的检索契约、有界调用、溯源输出结合Agent 就能把 “某基因在哪些通路、某代谢物属于哪条代谢途径、两种药物是否相互影响” 这类问题转成一段可复现、可审计、可交回给用户核对的查询记录——这正是仓库把数据库档案与检索纪律并列封装的用意所在。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考