# 基因家族进化树与结构类分析场景设计

本文档用于统一基因家族分析中 `phylogeny`、`reference_classification`、`motif`、`domain`、`structure` 等阶段的分析身份、输出命名、manifest、报告、复现命令、前端结果归类和自然语言规划逻辑。

核心原则：

- 不能再只用 `prefix + stage` 判断一个阶段是否完成。
- 必须用 `analysis_route + scope_id + member_set_id + subfamily_source + parameter_signature` 描述一次真实分析。
- 同一个 `phylogeny/motif/domain/structure` 阶段，在基因家族分析中可能对应多种不同目的和不同物种范围，必须在文件名、manifest、前端结果区和完成状态判断中明确区分。

## 统一身份字段

| 字段 | 作用 | 示例 | 必须进入哪里 |
|---|---|---|---|
| `analysis_route` | 区分分析目的 | `single_species` / `multi_species` / `subfamily_prediction` / `confirmed_subfamily` / `subset_subfamily` / `replot_only` | manifest、报告、前端结果分类、复现命令 |
| `prefix` | 输出主标签 | `Target.SPL` / `Target.Lc.SPL` | 所有输出文件、manifest、报告 |
| `scope_id` | 区分物种组合 | `target-Lc-Dl.ref-At.comp-Os` | scope.json、manifest、文件名、stage-status |
| `member_set_id` | 区分成员集合 | `all_members` / `domain_filtered` / `confirmed_v1` / `subfamily-SPL7` | manifest、报告、复现命令、前端版本展示 |
| `subfamily_source` | 亚家族标签来源 | `none` / `predicted` / `confirmed` / `user_uploaded` | 绘图阶段 manifest、报告、前端标记 |
| `action` | 是计算还是重绘 | `compute` / `replot` | manifest、复现命令、stage-status |
| `parameter_signature` | 参数变化判断 | MAFFT/IQ-TREE/MEME/hmmscan/GFF映射参数 hash | manifest、stage-status、复现记录 |
| `tree_source` | 当前阶段使用哪棵树 | `final/Target.SPL.target-Lc-Dl.ref-At.tree.nwk` | motif/domain/structure manifest |
| `protein_fasta` | 当前阶段实际使用的蛋白 FASTA | `phylogeny/analysis/Target.SPL.target-Lc-Dl.input.pep.fa` | manifest、报告、复现命令 |
| `gene_id_file` | 当前阶段实际使用的成员 ID | `final/Target.Lc.SPL.final_members.id` | structure/domain/motif manifest |
| `upstream_manifests` | 上游依赖清单 | identify、phylogeny、reference_classification manifest | manifest、复现记录 |

## 进化树场景总表

| 情况 | 用户自然语言 | 需要分析 | 推荐命名 | manifest | 报告 | 前端结果区 | 关键代码配合 |
|---|---|---|---|---|---|---|---|
| 单物种进化树 | “执行 Lc 的进化树” | 如果已有单物种成员则跳过 `identify`；执行 `phylogeny` | `Target.Lc.SPL.tree.nwk/png/pdf` | `Target.Lc.SPL.phylogeny.manifest.json` | `Target.Lc.SPL.phylogeny_report.md` | 进化树 / 单物种 | `planning_v2.py` 不能被 `Target.SPL` 误判完成；`run_phylogeny.py` 使用 `Target.Lc.SPL.final_members.pep.fa` |
| 多目标物种树 | “执行 Lc、Dl 的进化树” | `phylogeny`，输入 Lc + Dl 成员 | `Target.SPL.target-Lc-Dl.tree.*` | `Target.SPL.target-Lc-Dl.phylogeny.manifest.json` | `Target.SPL.target-Lc-Dl.phylogeny_report.md` | 进化树 / 多物种 | scope 生成、stage-status 传 `scope_id` |
| 目标 + 参考树 | “用 At 参考给 Lc/Dl 做亚家族分类” | `phylogeny` + `reference_classification` | `Target.SPL.target-Lc-Dl.ref-At.subfamily_prediction.tree.*` | `Target.SPL.target-Lc-Dl.ref-At.phylogeny.manifest.json` | 同 scope report | 亚家族确认 / 预测树 | `reference_classification` 必须读取同 scope 树 |
| 目标 + 比较物种树 | “Lc、Dl、Os 做多物种进化树” | `phylogeny` | `Target.SPL.target-Lc-Dl.comp-Os.tree.*` | `Target.SPL.target-Lc-Dl.comp-Os.phylogeny.manifest.json` | 同 scope report | 进化树 / 多物种 | 不应归入亚家族确认，除非用户明确要分类 |
| 目标 + 参考 + 比较树 | “Lc/Dl/Os/At 一起建树并分类” | `phylogeny` + 可选 `reference_classification` | `Target.SPL.target-Lc-Dl.ref-At.comp-Os.tree.*` | 同 scope manifest | 同 scope report | 若用于分类放亚家族确认，否则放多物种树 | route 由 intent 决定，不只看物种组成 |
| 参考物种 only 树 | “只画 At 的 SPL 参考树” | `phylogeny` | `Reference.At.SPL.tree.*` 或 `At.SPL.tree.*` | `Reference.At.SPL.phylogeny.manifest.json` | 同名 report | 参考资源 / 进化树 | 不能被当作 target 结果 |
| 亚家族预测树 | “执行亚家族分类分析” | `phylogeny` + `reference_classification` | 带 `subfamily_prediction` 或 scope_id | `...reference_classification.manifest.json` | `...reference_classification_report.md` | 亚家族确认 | 这是证据树，不是普通 phylogeny |
| 确认亚家族后重绘树 | “用确认后的亚家族重新画树” | 通常只 `tree_plot/replot`；成员变了才重跑 `phylogeny` | `Target.SPL.confirmed_subfamily.tree.*` | `Target.SPL.confirmed_subfamily.phylogeny_replot.manifest.json` | replot report | 进化树 / 确认亚家族 | `action=replot`，不应重复 MAFFT/IQ-TREE |
| 子家族/子集树 | “只画 SPL7 亚家族树” | 从 confirmed/predicted subfamily 过滤后 `phylogeny` 或 replot | `Target.SPL.subfamily-SPL7.tree.*` | `Target.SPL.subfamily-SPL7.phylogeny.manifest.json` | 同名 report | 进化树 / 子集 | 需要 `member_set_id=subfamily-SPL7` |
| 参数重跑树 | “bootstrap 改成 1000 再跑” | `phylogeny` 全量重跑 | `...param-{hash}.tree.*` 或 manifest 记录参数版本 | manifest 记录 `parameter_signature` | report 记录参数 | 进化树 / 参数重跑 | stage-status 比较参数，不能简单跳过 |

## motif / domain / structure 场景总表

| 情况 | 需要分析 | 输入 | 推荐命名 | manifest | 前端结果区 | 关键代码配合 |
|---|---|---|---|---|---|---|
| 单物种 motif/domain/structure | 若缺失同 scope 树，先 `phylogeny`；再执行 `motif/domain/structure` | `Target.Lc.SPL.final_members.*` + `Target.Lc.SPL.tree.nwk` | `Target.Lc.SPL.motif.*` / `Target.Lc.SPL.domain.*` / `Target.Lc.SPL.structure.*` | `Target.Lc.SPL.{stage}.manifest.json` | Motif/Domain/Structure / 单物种 | 不能被 `Target.SPL.{stage}.manifest.json` 误判完成 |
| 多物种 motif/domain/structure | 同 scope 的 `phylogeny` 后执行三阶段 | scope FASTA + scope tree | `Target.SPL.target-Lc-Dl.comp-Os.{stage}.*` | `Target.SPL.target-Lc-Dl.comp-Os.{stage}.manifest.json` | Motif/Domain/Structure / 多物种 | `run_motif/domain/structure.py` 已有 scope 支持，但最终文件名需带 scope |
| 亚家族预测证据图 | `motif/domain/structure/combo` | 预测用 tree + predicted subfamily | `Target.SPL.target-Lc-Dl.ref-At.subfamily_prediction.{stage}.*` | `...subfamily_prediction.{stage}.manifest.json` | 亚家族确认 / 证据图 | 不能和正式结构图混放 |
| 确认亚家族后正式图 | `replot` 或必要时重跑 | confirmed_subfamily.tsv + 原始结果/树 | `Target.SPL.confirmed_subfamily.{stage}.*` | `Target.SPL.confirmed_subfamily.{stage}.manifest.json` | Motif/Domain/Structure / 确认亚家族 | 后续 summary/combo/promoter 应优先使用 confirmed |
| 子家族/子集图 | motif/domain/structure 子集重跑或重绘 | subset members | `Target.SPL.subfamily-SPL7.{stage}.*` | `Target.SPL.subfamily-SPL7.{stage}.manifest.json` | 子集分析 | motif 若成员变了建议重跑 MEME |
| 只换亚家族标签重绘 | `replot_only` | 原始 motif/domain/structure 表 + 新 subfamily | `...replot.{stage}.png/pdf` | `...{stage}_replot.manifest.json` | 对应阶段 / 重绘版本 | 不应重新跑 MEME/hmmscan/GFF 解析 |
| domain 参数重跑 | `domain` | 同成员、同树，改 e-value/coverage/Pfam库 | 文件名或 manifest 记录参数 hash | `parameter_signature` 不同则重跑 | Domain / 参数版本 | stage-status 必须比较参数 |
| motif 参数重跑 | `motif` | 同成员，改 `nmotifs/minw/maxw` | 文件名或 manifest 记录参数 hash | `parameter_signature` 不同则重跑 | Motif / 参数版本 | MEME 结果依赖参数，不能复用旧图 |
| structure ID 映射修复 | `structure` 或 `structure_repair` | GFF + gene IDs + mapping policy | `...structure.*` | 记录 `id_mapping_policy` | Structure / 修复版 | 需记录 gene/transcript/CDS/Parent 映射规则 |
| 成员集合变化后全量重跑 | `phylogeny` + motif/domain/structure | domain review 或用户筛选后的成员 | `...member_set-{id}.{stage}.*` | `member_set_id` 新版本 | 对应阶段 / 筛选成员版 | 不能复用旧树和旧 motif |

## 命名规则建议

| 类型 | 推荐规则 | 示例 |
|---|---|---|
| 单物种 | `Target.{Species}.{Family}.{stage}.*` | `Target.Lc.SPL.phylogeny.manifest.json` |
| 多物种 scope | `{Prefix}.{scope_id}.{stage}.*` | `Target.SPL.target-Lc-Dl.comp-Os.phylogeny.manifest.json` |
| 亚家族预测 | `{Prefix}.{scope_id}.subfamily_prediction.{stage}.*` | `Target.SPL.target-Lc-Dl.ref-At.subfamily_prediction.structure.png` |
| 确认亚家族 | `{Prefix}.confirmed_subfamily.{stage}.*` | `Target.SPL.confirmed_subfamily.domain.png` |
| 子集/子家族 | `{Prefix}.subfamily-{Name}.{stage}.*` | `Target.SPL.subfamily-SPL7.tree.nwk` |
| 重绘 | `{Prefix}.{scope/member}.replot.{stage}.*` | `Target.SPL.confirmed_subfamily.replot.tree.png` |
| 参数版本 | `{Prefix}.{scope/member}.param-{hash}.{stage}.*` | `Target.SPL.target-Lc-Dl.param-a1b2c3.phylogeny.manifest.json` |

## manifest 必须补充的字段

| 字段 | 目的 |
|---|---|
| `analysis_route` | 明确这是单物种、多物种、亚家族预测、确认后分析还是子集 |
| `scope_id` / `scope_file` | 保证同一物种组合可追踪 |
| `member_set_id` | 保证成员集合变化可追踪 |
| `member_source` | `identify` / `domain_review` / `confirmed_subfamily` / `user_uploaded` |
| `subfamily_source` | `none` / `predicted` / `confirmed` / `user_uploaded` |
| `tree_source` | 当前 motif/domain/structure 使用哪棵树 |
| `protein_fasta` | 当前阶段实际使用的 FASTA |
| `gene_id_file` | 当前阶段实际成员 ID |
| `parameter_signature` | 判断是否需要重跑 |
| `action` | `compute` 或 `replot` |
| `reproducibility.command` | 完整可复现命令 |
| `upstream_manifests` | 依赖了哪些上游 manifest |
| `id_mapping_policy` | structure 阶段 ID 匹配策略 |
| `result_group` | 前端结果页归类，如 `subfamily_confirm`、`phylogeny_single_species` |

## 前端结果放置

| 结果区 | 应包含 | 不应混入 |
|---|---|---|
| 亚家族确认 | `reference_classification`、预测树、预测 subfamily 表、证据图 motif/domain/structure/combo | 普通单物种树、普通多物种树 |
| 进化树 | 单物种树、多物种树、确认亚家族后树、子集树 | 亚家族确认证据图，除非带明确标记 |
| Motif | 单物种、多物种、确认亚家族版、子集版、参数重跑版 | 亚家族确认流程的证据图应优先展示在亚家族确认区 |
| Domain | 单物种、多物种、确认亚家族版、子集版、参数重跑版 | identify 阶段 domain review 表不应和正式 domain 图混淆 |
| Structure | 单物种、多物种、确认亚家族版、子集版、ID 修复版 | 预测证据图不应覆盖正式结构图 |
| 复现与报告 | 每个 route/scope/member_set 独立展示 manifest、report、command | 不应只展示最新 manifest |

## 自然语言命令映射

| 用户表达 | 应识别为 | 默认 stages | 默认 scope/route |
|---|---|---|---|
| “帮我执行亚家族分类分析” | 亚家族预测/确认前置 | `phylogeny -> reference_classification`，可追加证据图 | `analysis_route=subfamily_prediction`，默认 `target_plus_reference` |
| “帮我执行 Lc 的进化树分析” | 单物种进化树 | `phylogeny` | `analysis_route=single_species`，`targetSpecies=[Lc]` |
| “帮我执行 Lc/Dl 的进化树” | 多目标物种树 | `phylogeny` | `analysis_route=multi_species`，`targetSpecies=[Lc,Dl]` |
| “Lc、Dl、Os 做多物种进化树” | 目标 + 比较树 | `phylogeny` | `analysis_route=multi_species`，targets + comparative |
| “用 At 参考给 Lc/Dl 分类” | 目标 + 参考亚家族预测 | `phylogeny -> reference_classification` | `analysis_route=subfamily_prediction` |
| “用确认后的亚家族重新画树” | 确认标签重绘 | `tree_plot/replot` | `analysis_route=confirmed_subfamily`，`action=replot` |
| “只画 SPL7 亚家族” | 子集分析 | `phylogeny` 或 `replot` | `analysis_route=subset_subfamily`，`member_set_id=subfamily-SPL7` |
| “执行 Lc 的 motif/domain/structure” | 单物种结构类分析 | 缺树先 `phylogeny`，再目标阶段 | `analysis_route=single_species` |
| “执行多物种 motif/domain/structure” | 多物种结构类分析 | 同 scope `phylogeny` 后执行 | `analysis_route=multi_species` |
| “确认亚家族后重新画 structure/motif/domain” | 确认标签正式图 | `replot` 或必要时重跑 | `analysis_route=confirmed_subfamily` |

## 相关代码配合

| 模块 | 需要配合的点 |
|---|---|
| `apps/web/vue3/index.html` | 自然语言确认弹窗、scope 勾选、执行参数、结果分区、stage-status 调用必须带 `scope_id/scope_file` |
| `apps/web/vue3/main.py` | `/api/agent/plan`、`/api/execute`、`/api/stage-status`、`/api/results` 都要按 route/scope/member_set 判断 |
| `gfa_core/mas/agents/planning_v2.py` | 规划阶段不能只查 `prefix.stage.manifest`，要查 scoped manifest 和 semantic artifact |
| `gfa_core/mas/tools/stage_status.py` | `get_stage_status()` 要支持 `analysis_route/member_set_id/parameter_signature` |
| `apps/web/pipeline_backend.py` | 执行每个阶段时传 `scope_file`、记录 repro、返回 scoped manifest |
| `apps/cli/run_phylogeny.py` | 输出文件名支持 scope/route，避免覆盖 `{prefix}.tree.*` |
| `apps/cli/run_motif.py` | scope 输入、subfamily 来源、参数签名、scoped 输出 |
| `apps/cli/run_domain.py` | scope 输入、Pfam/CDD/coverage/evalue 参数记录、scoped 输出 |
| `apps/cli/run_structure.py` | scope GFF、ID 映射策略、subfamily 来源、scoped 输出 |
| `gfa_core/gene_family_scope.py` | scope_id 生成规则要稳定，作为全局分析身份 |
| `gfa_core/schemas/stages/*contract*` | 契约中加入 route/scope/member_set/subfamily_source |
| `skills/*/SKILL.md` | skill 输入输出说明要同步这些命名和 manifest 字段 |
| `reproducibility_v2.py` 或相关复现模块 | 复现命令按 scoped manifest 记录，而不是只按 stage |

## 现有风险点

| 风险 | 表现 | 应修订方向 |
|---|---|---|
| 完成状态只看 `prefix + stage` | 单物种 Lc 树被 `Target.SPL` 树误判完成 | stage-status 增加 route/scope/member_set 判断 |
| scoped manifest 有但产物不带 scope | 多次运行不同 scope 会覆盖 `Target.SPL.tree.*` | CLI 输出文件名带 scope 或 route |
| 亚家族证据图和正式图混放 | 用户无法判断图是预测参考还是正式结果 | 前端结果分区增加 `result_group` |
| confirmed subfamily 未优先使用 | 后续图可能仍用 predicted labels | 绘图阶段 subfamily 查找顺序必须 confirmed 优先 |
| 成员集合变化后复用旧树/旧 motif | domain review 后结果不一致 | member_set_id 和 input FASTA hash 必须进入 manifest |
| structure ID 不一致 | GFF 能解析但画不出结构或覆盖率低 | 记录并执行 `id_mapping_policy` |
| 参数变化仍被跳过 | 用户改 bootstrap/evalue/nmotifs 但系统说已完成 | parameter_signature 参与完成判断 |

## 推荐落地顺序

| 顺序 | 修订内容 | 验证方式 |
|---|---|---|
| 1 | 统一 `scope_id/analysis_route/member_set_id` 生成和传递 | 用 Lc 单物种、Lc+Dl、Lc+Dl+At 三种规划检查 plan 参数 |
| 2 | 修订 `stage_status`，按 scope/route 判断完成 | 已有 `Target.SPL` 树时，`Lc.SPL` 不应被判完成 |
| 3 | 修订 `run_phylogeny.py` scoped 输出命名 | 真实跑 Lc 单物种和 target+reference，确认不覆盖 |
| 4 | 修订 `reference_classification` 使用同 scope 树 | 亚家族分类结果图带 subfamily 标签 |
| 5 | 修订 `motif/domain/structure` scoped 输出命名和 manifest | 单物种、多物种、亚家族证据图分别落在不同文件 |
| 6 | 修订前端 `/api/results` 结果归类 | 页面中能区分亚家族确认、单物种树、多物种结构图 |
| 7 | 修订契约、skill、复现命令 | 每个 scoped manifest 都能给出可复现命令 |
| 8 | 真实数据回归测试 | 使用 Lc、Dl、At、Os、SPL 依次测试单物种、多物种、亚家族确认和结构类图 |