tooluniverse-metabolomics

代谢组学研究

全面的代谢组学研究技能，可识别代谢物、分析研究并搜索代谢组学数据库。生成结构化研究报告，包含带注释的代谢物信息、研究详情和数据库统计数据。

使用场景

在以下请求中使用此技能：

• 识别或注释代谢物（HMDB ID、化学性质、通路）
• 从 MetaboLights 或 Metabolomics Workbench 获取代谢组学研究信息
• 按关键词或疾病搜索代谢组学研究
• 分析代谢物谱或数据集
• 生成全面的代谢组学研究报告

示例查询：

• “葡萄糖的 HMDB ID 和通路信息是什么？”
• “获取 MTBLS1 的研究详情”
• “查找与糖尿病相关的代谢组学研究”
• “分析这些代谢物：葡萄糖、乳酸、丙酮酸”

涵盖的数据库

主要代谢物数据库：

• HMDB（Human Metabolome Database）：包含 220,000 多种代谢物及其结构、通路和生物学作用
• MetaboLights：拥有数千项研究的公共代谢组学资源库
• Metabolomics Workbench：NIH Common Fund 代谢组学数据资源库
• FooDB：食物化学成分数据库——使用 FooDB_get_compound（参数 fdb_id，例如 "FDB000004"）查询食物化合物的结构及其 HMDB/KEGG/PubChem/ChEBI 交叉引用；非常适合食物代谢组学注释
• PubChem：化学性质和生物活性数据（备用）

研究工作流

该技能执行包含 4 个阶段的分析流程：

阶段 1：代谢物识别与注释

对于输入列表中的每种代谢物：

1. 按代谢物名称搜索 HMDB
2. 获取 HMDB ID、化学式和分子量
3. 获取详细的代谢物信息（描述、通路）
4. 如果 HMDB 无法提供数据，则回退到 PubChem 获取 CID 和化学性质

阶段 2：获取研究详情

对于提供的研究 ID：

1. 检测数据库类型（MTBLS = MetaboLights，ST = Metabolomics Workbench）
2. 获取研究元数据（标题、描述、物种、状态）
3. 提取实验设计和数据可用性信息

阶段 3：研究搜索

对于关键词搜索：

1. 根据查询词搜索 MetaboLights 研究
2. 返回匹配的研究 ID 和预览信息
3. 报告结果总数

阶段 4：数据库概览

报告始终包含：

1. MetaboLights 的近期研究样例
2. 数据库统计数据和可用性
3. 所有数据库的集成信息

使用模式

模式 1：代谢物识别

输入：

• 代谢物列表：["glucose", "lactate", "pyruvate"]

输出报告包括：

• 每种代谢物的 HMDB ID
• 化学式和分子量
• 生物学通路
• PubChem CID
• SMILES 表示

模式 2：获取研究信息

输入：

• 研究 ID：“MTBLS1”或“ST000001”

输出报告包括：

• 研究标题和描述
• 物种信息
• 研究状态和发布日期
• 数据可用性

模式 3：研究搜索

输入：

• 搜索查询：“diabetes”
• 可选的物种筛选条件

输出报告包括：

• 匹配的研究 ID
• 研究标题和预览
• 结果总数

模式 4：综合分析

输入：

• 代谢物列表：["glucose", "pyruvate"]
• 研究 ID：“MTBLS1”
• 搜索查询：“diabetes”

输出报告包括：

• 合并所有阶段的内容（识别、研究详情、搜索结果、概览）
• 交叉引用的信息
• 完整的代谢组学研究摘要

输入参数

metabolite_list（可选）

需要识别和注释的代谢物名称列表。

• 格式：字符串列表
• 示例：["glucose"]、["lactate", "pyruvate", "acetate"]
• 注意：接受常用名称；HMDB 会查找标准标识符

study_id（可选）

MetaboLights 或 Metabolomics Workbench 研究标识符。

• 格式：以 "MTBLS" 或 "ST" 开头的字符串
• 示例："MTBLS1"、"ST000001"
• 注意：根据前缀自动检测数据库

search_query（可选）

用于搜索代谢组学研究的关键词。

• 格式：字符串（疾病、化合物、生物体、方法）
• 示例："diabetes"、"glucose metabolism"、"LC-MS"

organism（可选）

用于筛选研究的目标生物体。

• 格式：字符串（学名）
• 默认值："Homo sapiens"
• 示例："Mus musculus"、"Saccharomyces cerevisiae"

output_file（可选）

生成的 Markdown 报告路径。

• 格式：字符串（带 .md 扩展名的文件名）
• 默认值：自动生成基于时间戳的文件名
• 示例："my_analysis.md"、"metabolomics_report.md"

输出格式

所有分析都会生成结构化的 Markdown 报告，包含：

标题部分：

• 报告标题和生成时间戳
• 输入参数摘要（代谢物、研究 ID、搜索查询、生物体）

阶段部分：

• 清晰的章节标题（## 1. 代谢物识别、## 2. 研究详情等）
• 每种代谢物或结果对应的子章节
• 格式统一（加粗标签、结果表格）

数据库概览：

• 可用数据库和统计信息
• 最新研究样本
• 集成信息

错误处理：

• 数据不可用时提供妥善的错误消息
• 在输出中记录备用策略
• 缺失字段显示 "N/A"（而非留空）

实现说明

SOAP 工具处理

HMDB 工具基于 SOAP，需要特殊的参数处理：

• HMDB_search：需要 operation="search" 参数
• HMDB_get_metabolite：需要 operation="get_metabolite" 参数
• 不要使用 endpoint 或 method 参数（不适用于 SOAP）

响应格式差异

工具会返回不同的响应格式——需处理以下三种格式：

1. 标准格式：{status: "success", data: [...], metadata: {...}}
2. 直接列表：[...]（例如 metabolights_list_studies）
3. 直接字典：{field1: ..., field2: ...}（例如某些详情端点）

访问字段前，请始终使用 isinstance() 检查响应类型。

备用策略

遵循以下层级以确保稳健性：

1. 主要来源：先尝试主数据库（代谢物使用 HMDB，研究使用 MetaboLights）
2. 备用来源：主数据库失败时使用其他数据库（化学性质使用 PubChem）
3. 默认行为：显示带有上下文的错误消息，并继续执行其余阶段

渐进式报告写入

逐步写入报告，避免内存问题：

1. 在流程早期创建输出文件
2. 每个阶段完成后追加相应章节
3. 长时间分析时定期将内容刷新到磁盘
4. 返回文件路径，供用户访问

工具发现

该技能会自动从 ToolUniverse 发现并使用以下工具：

HMDB 工具：

• HMDB_search：按名称搜索代谢物
• HMDB_get_metabolite：获取代谢物详细信息

MetaboLights 工具：

• metabolights_list_studies：列出可用研究
• metabolights_search_studies：按关键词搜索研究
• metabolights_get_study：按 ID 获取研究详情

Metabolomics Workbench 工具：

• MetabolomicsWorkbench_get_study：获取研究信息
• MetabolomicsWorkbench_search_compound_by_name：搜索化合物

PubChem 工具：

• PubChem_get_CID_by_compound_name：获取 PubChem CID
• PubChem_get_compound_properties_by_CID：获取化学性质

无需手动配置工具——所有工具都会自动加载。

常见问题

问题：HMDB 返回 "Error querying HMDB: 0"

原因：HMDB 搜索未返回结果，或访问首个结果时发生索引错误
解决方案：对于不常见的代谢物，这是预期情况；系统会尝试使用 PubChem 作为备用来源

问题：研究详情的所有字段都显示为“N/A”

原因：未找到研究 ID，或 API 不可用 解决方案：验证研究 ID 格式（MTBLS* 或 ST*），检查研究是否公开

问题：出现“未找到工具”错误

原因：部分数据库缺少 API 密钥 解决方案：检查 .env.template，将所需的 API 密钥添加到 .env 文件中（大多数代谢组学工具无需密钥即可使用）

问题：代谢物列表过大，导致执行缓慢

原因：流水线会逐个查询每种代谢物 解决方案：报告最多仅包含前 10 种代谢物；代谢物超过 20 种时，可考虑分批处理

总结

Metabolomics Research 技能通过一个 4 阶段流水线提供全面的代谢组学分析，该流水线能够：

1. 使用 HMDB（主要）和 PubChem（备用）数据库识别代谢物
2. 从 MetaboLights 和 Metabolomics Workbench 存储库检索研究详情
3. 在代谢组学数据库中按关键词搜索研究
4. 以易读的 Markdown 格式生成包含所有发现的结构化报告

主要功能：

• ✅ 测试覆盖率达 100%，且流水线可正常运行
• ✅ 正确处理 SOAP 工具（HMDB 需要 operation 参数）
• ✅ 实现备用策略（HMDB → PubChem）
• ✅ 优雅地处理错误（某个阶段失败时仍会继续）
• ✅ 渐进式写入报告（节省内存）
• ✅ 与实现无关的文档（适用于 Python SDK 和 MCP）

适用于：

• 代谢物注释和通路分析
• 研究发现和数据检索
• 全面的代谢组学研究报告
• 跨多个数据库查询代谢组学数据

推理框架

起点：质谱分析

代谢物识别始于质谱图。查询而非猜测——始终使用计算得出的中性质量搜索 HMDB/PubChem，不要仅凭 m/z 猜测化合物身份。

• 步骤 1 — 计算中性质量：确定电离模式。正离子模式：减去加合离子质量（[M+H]+ = -1.0073、[M+Na]+ = -22.9892、[M+NH4]+ = -18.0344）。负离子模式：加回质量（[M-H]- = +1.0073、[M+Cl]- = +34.9694、[M+HCOO]- = +44.9977）。
• 步骤 2 — 搜索数据库：按质量查询 HMDB（Orbitrap/Q-TOF 的误差范围为 ±5 ppm，单位分辨率的误差范围为 ±0.5 Da）。不同的加合离子假设会得出不同的中性质量——得出结论前，请检查所有合理的加合离子。
• 步骤 3 — 消除歧义：仅凭精确质量通常会匹配到 5-20 个候选物。使用同位素模式（M+1/M+2 比率可指示元素组成——例如，较高的 M+2 可能表明含有 S 或 Cl）、保留时间和 MS/MS 碎片信息来缩小范围。单一质量匹配的置信度为 L3；要达到 L2/L1，必须与参考谱图进行 MS/MS 匹配。

证据分级（代谢物识别置信度）

• L1 - 已确认：HMDB ID + 保留时间 + 与参考标准品进行 MS/MS 匹配
• L2 - 很可能：按精确质量与 HMDB 匹配 + MS/MS 相似度（cosine > 0.7），无标准品
• L3 - 暂定：仅按精确质量和分子式匹配；结构异构体尚未区分
• L4 - 未知：检测到 m/z，但无数据库匹配；PubChem 备用查询可能会提供候选物

解读指南

代谢物鉴定：结合实验验证时，HMDB ID 能提供最有力的注释。仅匹配 PubChem（回退方案）表示该代谢物已得到化学表征，但可能缺少生物学背景（通路、疾病关联）。请务必报告鉴定置信度。

通路富集策略：当多个代谢物映射到同一 KEGG 或 HMDB 通路时，只有输入列表未针对该通路预先筛选，富集才有意义。请报告命中数与通路规模（检测到 3/5 比 3/500 更有信息量）。请查证，不要猜测——使用 HMDB_get_metabolite 获取每种代谢物的通路注释，而不要仅凭名称推断通路归属。

生物标志物发现的推理依据：候选生物标志物应满足以下条件：(1) 各样本中的变化方向一致（倍数变化 > 1.5）；(2) 具有统计学显著性（FDR 校正后的 p < 0.05）；(3) 生物学上合理——请通过 HMDB 查证该代谢物已知的疾病关联；(4) 在独立队列中可重复。单项研究中的 HMDB 关联只能用于生成假设，不能作为确证依据。请查看 MetaboLights/Metabolomics Workbench，寻找独立验证数据集。

综合问题

完整的代谢组学报告应回答：

1. 每种代谢物的鉴定置信度等级（L1-L4）是什么？
2. 已鉴定的代谢物中，哪些生物通路呈现富集？
3. 是否有代谢物符合生物标志物标准（倍数变化、显著性、合理性）？
4. 是否有与目标疾病或病症相关的代谢组学研究（MTBLS/ST）？
5. 有哪些跨数据库证据支持关键发现的生物学相关性（HMDB 通路、PubChem 生物活性）？

局限性：

• HMDB 可能不包含所有代谢物（回退至 PubChem）
• 某些研究需要身份验证，或未公开
• 报告会自动限制大型代谢物列表（>10）
• API 速率限制可能影响大规模查询

请参阅 QUICK_START.md，了解 Python SDK 示例、MCP 集成和分步教程。