16 KiB
Executable File
16 KiB
Executable File
基因家族进化树与结构类分析场景设计
本文档用于统一基因家族分析中 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 依次测试单物种、多物种、亚家族确认和结构类图 |