@dsh-bio/human-microbiome-function-mining

Usage examples / 使用示例

以下示例按三种常见输入类型排列，均改写自真实可复现场的案例，方便你直接复制相近句式发起分析：

输入类型	触发点	举例
已知代谢反应	有底物/产物，但没有明确模板序列或 EC。	神经酰胺合成 → ceramide + phosphocholine
已知酶名/EC	有酶功能或功能类别注释。	neutral sphingomyelinase / EC 3.1.4.12
已知参考序列	有模板蛋白 FASTA 或 UniProt accession。	DDC / P20711

每个示例都给出“用户可以直接发送的一句话 prompt”和“Agent 按插件 skill 实际会走的分析链”。实际运行时，把工具和数据路径替换成你自己的即可。

Example 1: 从代谢反应出发，预测人体微生物是否编码相关基因

User:
"已知代谢反应的产物为神经酰胺和磷酸胆碱，预测皮肤微生物
表皮葡萄球菌（GCF_038181645.1）是否含有相关代谢基因，
并给出可以验证的实验方案。"

Agent:
- 用 `build-target-function-card` 把
  sphingomyelin -> ceramide + phosphocholine 写成
  `target_function_card.json`
- 用 `genome-search` / `genome-download` / `genome-annotation` 解析
  `GCF_038181645.1` 并准备候选 proteome
- 用 `screen-sequence-candidates` 先做 CD-HIT 去冗余（单基因组 100%，多基因组
  95%），再 DIAMOND 序列筛选
- 用 `parse_source_annotations.py` 收集 `.faa`/`.gbff` 已带的 protein/gene、EC、
  Pfam/InterPro/KEGG 等注释证据
- 检查候选结构文件是否存在：没有就先跑 `structure-prediction`
  （PDB > AlphaFold DB > homology model > de novo），有则用
  `screen-structure-candidates` 对全部候选结构直接 US-align
- US-align 候选不足时，明确原因后，经用户同意再跑 DEER fallback
- 合并 FedKEA、文献证据和已有注释，按结构优先原则排序
- 输出 `scored_candidates_full.tsv`、`experimental_hypotheses.tsv`
  和 `experimental_design.md`

回答会明确：
- 是否检出候选基因
- 代表候选 accession/locus_tag
- 证据链和置信度
- 可执行的实验验证方案

Example 2: 从已知酶出发，预测人体微生物是否编码相关的代谢基因

User:
"预测给出的三个皮肤微生物基因组（Streptococcus pyogenes、
Streptococcus thermophilus、Staphylococcus xylosus）是否含有
neutral sphingomyelinase 相关的代谢基因，并给出可以验证的
实验方案。"

Agent:
- 用 `build-target-function-card` 以 neutral sphingomyelinase /
  EC 3.1.4.12 建目标卡片
- 自动或手动准备参考酶集合，优先写明来源（NCBI/PDB/UniProt）
- 对三个基因组分别跑 `screen-sequence-candidates`：先 CD-HIT 去冗余
  （单基因组 100%，多基因组 95%），再 DIAMOND 筛选
- 每个基因组先看有没有候选结构；没有就跑 `structure-prediction`，有则
  用 `screen-structure-candidates` 直接对所有候选结构 US-align
- 按基因组分别判断是否 US-align 合格候选不足；不足且用户同意时，
  才跑 DEER fallback（例如 Staphylococcus_xylosus 之前就是这样）
- 用 FedKEA 对最终候选做酶/EC 验证，并保留 binary/enzyme/probability 结果
- 用 `literature-evidence` 补充可验证的 PMID/DOI 证据链
- 用 `score_candidates.py` 排序，输出每个物种的候选表、代表候选与实验设计

回答会明确：
- 每个物种是否有候选
- 有候选/无候选的关键证据
- DEER fallback 是否被使用及其原因
- 后续实验建议

Example 3: 从已知序列出发，预测人体微生物是否编码类似的代谢基因

User:
"预测肠道微生物青春双歧杆菌 Bifidobacterium adolescentis
是否可能编码褪黑素合成的关键酶 DDC（P20711），并给出
可以验证的实验方案。"

Agent:
- 用 `build-target-function-card` 以 DDC / aromatic L-amino acid
  decarboxylase（EC 4.1.1.28）建目标卡片，UniProt 参考 = P20711
- 没有用户提供的 FASTA 时，先给 UniProt 获取命令，不要自己编序列
- 用 `genome-search` / `genome-download` / `genome-annotation` 准备
  Bifidobacterium adolescentis 候选 proteome
- 用 `screen-sequence-candidates` 先 CD-HIT 去冗余（单基因组 100%，多基因组
  95%），再 DIAMOND 筛选
- 检查候选结构是否存在；无则跑 `structure-prediction`，有则用
  `screen-structure-candidates` 直接 US-align
- US-align 候选不足时，经用户同意再跑 DEER fallback
- 用 FedKEA 和已有注释/Pfam/InterPro 交叉核对
- 结合 `literature-evidence` 输出带 PMID/DOI 的证据链与最终排序

回答会明确：
- 是否检出 DDC 类候选
- 代表候选 accession/locus_tag
- 候选的序列/结构/FedKEA 证据链
- 验证 DDC/褪黑素合成的实验路径

---

如何把这些示例变成你自己的 demo

1. 在 project.json 中填入用户自己的数据路径和工具路径。
2. 如果目标不是 NSMase/DDC，修改 inputs.target_sequence_fasta、reference_enzyme.enzyme_name、reference_enzyme.ec，或用底物/产物起动。
3. 让 Agent 按主 skill 先跑 light 流程：CD-HIT + DIAMOND -> US-align -> 已有注释/FedKEA -> 文献证据/实验假设 -> 最终排序。
4. 实验方案由 Agent 结合已验证文献和实验体系生成；没有文献支持时不要伪造引用。

---