devtu-optimize-skills

优化 ToolUniverse 技能

提供有关证据分级和来源归属的高质量研究技能最佳实践。

工具质量标准

1. 错误消息必须可执行 — 告诉用户出了什么问题，以及该怎么做
2. 架构必须符合 API 实际情况 — 运行 python3 -m tooluniverse.cli run <Tool> '<json>' 进行验证
3. 透明说明覆盖范围 — 说明未包含哪些数据
4. 在调用 API 前验证输入 — 不要悄悄发送无效值
5. 跨工具路由 — 查询超出范围时，指出正确的工具
6. 不得静默丢弃参数 — 如果忽略某个参数，请明确说明

核心原则（13 种模式）

完整详情：references/optimization-patterns.md

#	模式	核心理念
1	验证工具接口	首次调用前使用 get_tool_info()；维护修正表
2	基础数据层	首先查询聚合器（Open Targets、PubChem）
3	带版本的标识符	同时捕获 ENSG00000123456 和 .12 版本
4	优先消歧	解析 ID、检测冲突、构建负向过滤条件
5	仅输出报告	在报告中撰写叙述；仅在用户提出要求时，才在附录中说明方法
6	证据分级	T1（机制）→ T2（功能）→ T3（关联）→ T4（提及）
7	量化完整性	为各部分设定最低数量（>=20 个 PPI、前 10 种组织）
8	强制检查清单	所有部分都必须存在，即使内容是“证据有限”
9	汇总数据缺口	用单独部分汇总所有缺失数据
10	查询策略	高精度种子 → 引文扩展 → 经冲突过滤的广泛查询
11	工具故障处理	主工具 → 备用工具 1 → 备用工具 2 → 记录无法获取
12	可扩展输出	叙述性报告 + JSON/CSV 参考文献
13	综合分析部分	生物学模型 + 可检验假设，而不只是论文列表

优化后的技能工作流

Phase -1: Tool Verification (check params)
Phase  0: Foundation Data (aggregator query)
Phase  1: Disambiguation (IDs, collisions, baseline)
Phase  2: Specialized Queries (fill gaps)
Phase  3: Report Synthesis (evidence-graded narrative)

测试标准

完整详情：references/testing-standards.md

关键规则：未先测试所有工具调用，绝不能编写技能文档。

• 每项技能进行 30+ 项测试，通过率为 100%
• 所有测试都使用真实数据（不使用占位符）
• 包括阶段测试、集成测试和边缘案例测试
• SOAP 工具（IMGT、SAbDab、TheraSAbDab）需要 operation 参数
• 区分临时错误（重试）和实际错误（修复）
• API 文档经常有误 — 务必通过实际调用进行验证

模式 14：推理框架优于工具目录（重要）

只列出工具（“依次调用 A、B、C”）的技能，在实用性测试中的评分为 3-5/10。解释如何解读和组合数据的技能，评分为 7-9/10。每项技能都必须包含：

14a. 解读表

将原始 API 数据映射为生物学/临床意义。不要只获取数据 — 还要解释。

不佳（工具目录）	良好（推理框架）
“从 MGnify 获取 GO 术语”	GO 术语 → 解读表：丁酸基因 = 屏障完整性，LPS 基因 = 炎症
“获取 DepMap 依赖性评分”	评分 < -0.5 = 必需基因，但泛必需基因 = 不良药物靶点（毒性）；选择性靶点 = 良好靶点
“获取 FAERS 计数”	PRR > 5 = 强信号，但信号 ≠ 因果关系（渠道偏倚、知名度偏倚）

14b. 综合分析阶段

每项多阶段技能都需要一个最终阶段来回答“这意味着什么？” — 而不只是收集数据：

• “发生了什么变化，为什么重要？”
• “这是原因还是结果？”
• “有什么可执行的建议？”

14c. 如实说明局限

如果工具 API 无法实现技能承诺的功能，请明确说明。不要描述理想化的能力。例如：“DepMap_get_gene_dependencies 仅返回基因元数据，不返回各细胞系的 CRISPR 评分。”

模式 15：工具无法满足需求时的计算流程

有些科学分析需要进行计算，而不只是查询 API。如果某项能力没有对应工具，就直接在技能中嵌入 Python 代码流程，并使用 ToolUniverse 中提供的包（pandas、scipy、numpy、statsmodels、biopython、networkx）。

何时使用计算流程：

缺口	流程	包
API 未返回所需数据（例如 DepMap 评分）	下载 CSV + 使用 pandas 分析	pandas
统计检验（差异丰度、富集分析）	scipy.stats + FDR 校正	scipy、statsmodels
序列分析（比对、保守性）	Biopython SeqIO + 成对比对	biopython
化学相似性（类似物搜索、指纹）	RDKit 指纹 + Tanimoto	rdkit（可选可视化扩展）
网络分析（枢纽基因、聚类）	NetworkX 图指标	networkx
评分算法（ACMG 分类、活力评分）	自定义 Python 函数	内置
剂量可行性（Cmax 与 IC50 比较）	数值比较 + PK 数据	pandas、numpy

技能中计算流程的模板：

**Computational procedure: [Name]**
[When to use this: explain the gap it fills]

\`\`\`python
# [What this computes]
# Requires: [packages] (included in ToolUniverse dependencies)
import pandas as pd
from scipy.stats import mannwhitneyu

# Input: [describe expected input format]
# Output: [describe output]
# [Full working code with example data]
\`\`\`

[Interpretation guidance for the output]

计算流程的关键规则：

1. 仅使用 ToolUniverse 依赖项（pyproject.toml）中的包：pandas、scipy、numpy、networkx、requests、biopython（可选扩展）
2. 包含示例数据，以便立即测试该流程
3. 说明输出内容——没有解读的代码块毫无用处
4. 注明何时需要下载外部数据（例如，从 depmap.org 下载 DepMap CSV）

模式 15b：下载并处理没有 REST API 的数据集

许多重要的科学数据集没有 REST API，但提供批量下载文件。如果这是获取关键数据的唯一途径，技能应包含具体的下载和处理说明。

下载和处理流程的模板：

**Step 1: Download data files**
- URL: [exact download page URL]
- Files needed: [filename] (~[size]) — [what it contains]
- Registration: [required/not required]
- Update frequency: [quarterly/annually/etc.]

**Step 2: Process with Python**
[Working code with pandas/scipy that loads the CSV and produces the analysis]

**Step 3: Interpret results**
[Table mapping output values to biological/clinical meaning]

**When files are not available**: [Fallback strategy using API tools]

技能中引用的已知仅可下载数据集：

数据集	下载 URL	文件	使用方
DepMap CRISPR	depmap.org/portal/download/all/	CRISPRGeneEffect.csv（约 300MB）、Model.csv（约 2MB）	functional-genomics、cell-line-profiling
TCGA 临床数据	portal.gdc.cancer.gov	临床及突变 TSV 文件	cancer-genomics-tcga
GTEx 表达数据	gtexportal.org/home/downloads	GTEx_Analysis_v8_Annotations.csv	expression-data-retrieval
ClinGen 基因-疾病数据	clinicalgenome.org/docs/	gene_curation_list.tsv	variant-interpretation
gnomAD 约束数据	gnomad.broadinstitute.org/downloads	约束指标 TSV	functional-genomics

关键规则：下载不可用时，务必提供备用方案（用户可能没有注册账号，文件也可能过大等）。备用方案应使用可用的 API 工具，即使其提供的数据不够完整。

常见反模式

反模式	修正方法
报告“搜索日志”	将方法细节保留在内部；只报告发现
缺少消歧处理	添加冲突检测；构建负向过滤条件
未评估证据等级	应用 T1-T4 评级；标注每项主张
省略空白章节	加入该章节并注明“未发现”
缺少综合分析	添加生物学模型 + 假设
静默失败	在“数据缺口”中记录；实现备用方案
工具参数错误	调用前通过 get_tool_info() 核实
GTEx 未返回结果	尝试带版本的 ID ENSG*.version
缺少基础层	先查询聚合器
未测试工具调用	采用测试驱动：先编写测试脚本
工具目录缺少解读	添加解读表，说明数据含义
夸大能力	如实说明 API 无法提供的数据；改用计算流程
缺少统计分析	添加 scipy/pandas 代码流程，完成工具无法执行的计算

用户反馈的快速修复方案

反馈	修复方案
“报告太短”	添加阶段 0 基础内容 + 阶段 1 消歧
“噪声太多”	添加冲突过滤
“看不出什么内容重要”	添加 T1-T4 证据等级
“缺少章节”	添加包含最低要求的必备清单
“太长／难以阅读”	将叙述内容与 JSON 分开
“只是论文列表”	添加综合分析章节
“工具失败，没有数据”	添加重试 + 回退链

技能模板

---
name: [domain]-research
description: [What + when triggers]
---

# [Domain] Research

## Workflow
Phase -1: Tool Verification → Phase 0: Foundation → Phase 1: Disambiguate
→ Phase 2: Search → Phase 3: Report

## Phase -1: Tool Verification
[Parameter corrections table]

## Phase 0: Foundation Data
[Aggregator query]

## Phase 1: Disambiguation
[IDs, collisions, baseline]

## Phase 2: Specialized Queries
[Query strategy, fallbacks]

## Phase 3: Report Synthesis
[Evidence grading, mandatory sections]

## Output Files
- [topic]_report.md, [topic]_bibliography.json

## Quantified Minimums
[Numbers per section]

## Completeness Checklist
[Required sections with checkboxes]

其他参考资料

• 详细模式：references/optimization-patterns.md
• 测试标准：references/testing-standards.md
• 案例研究（4 个真实修复案例）：references/case-studies.md
• 清单（审查 + 发布）：references/checklists.md