PlantAI-dev/docs/gene_family_scope_revision_plan.md

本轮修订计划：基因家族进化树与结构类分析作用域

本文档记录本轮实际修订方案、验收标准和真实数据验证矩阵。目标是修复 phylogeny、reference_classification、motif、domain、structure 在单物种、多物种、亚家族分类和确认亚家族后分析之间互相混淆的问题。

修订原则

1. 尽量在原代码上小步修订，不重写框架。
2. 复用现有 scope_file/scope_id、stage_status、pipeline_backend、run_*.py。
3. 不再只用 prefix + stage 判断完成状态。
4. 对不同物种范围、成员集合和亚家族标签来源进行明确区分。
5. 每个关键修订必须用后端 API 或真实 CLI 数据验证，不只做编译检查。

总体目标

目标	当前问题	修订方向	验收标准
scope 完成状态隔离	请求带 scope_id 时仍可能回退到旧 unscoped manifest	stage_status 对 scoped 请求只认 scoped manifest	已有 Target.SPL.phylogeny.manifest.json 时，请求新 scope 返回 not_found
单物种分析隔离	Lc 分析可能被 Target.SPL 结果误判完成	单物种 prefix 与 scope 均参与判断	Lc.SPL / Target.Lc.SPL 不被 Target.SPL 跳过
phylogeny 输出隔离	多个 scope 可能覆盖 {prefix}.tree.*	scoped 运行输出带 scope_id，manifest 记录真实输入	不同 scope 生成不同 tree/msa/report/manifest
reference classification 绑定同 scope 树	亚家族分类可能使用错误树	后端执行和 CLI 均读取同 scope phylogeny manifest	分类 manifest 中 tree_source 指向同 scope tree
motif/domain/structure 隔离	证据图、单物种图、多物种图混放	输出、manifest、结果接口区分 route/scope	前端结果 API 可区分亚家族证据图与正式结构图
confirmed subfamily 优先	后续图可能仍用 predicted label	subfamily 查找顺序 confirmed > reference_classification > legacy	确认标签存在时 structure/domain/motif manifest 记录 confirmed

分阶段修订方案

阶段 1：完成状态判断

文件	修订点
gfa_core/mas/tools/stage_status.py	scope_id 存在时只检查 scoped manifest，不回退 unscoped manifest
apps/web/vue3/main.py	/api/stage-status 继续支持 scope_file 推断 scope_id
gfa_core/mas/agents/planning_v2.py	后续接入 scope-aware status，避免计划阶段误判

验证：

GET /api/stage-status?job_id=...&stage=phylogeny&prefix=Target.SPL&scope_id=target-Lc-Dl.ref-At

如果 scoped manifest 不存在，即使 unscoped manifest 存在，也必须返回 completed=false。

阶段 2：phylogeny scoped 输出

文件	修订点
apps/cli/run_phylogeny.py	scoped 运行时使用 output_stem = {prefix}.{scope_id} 或 {prefix}.{route}.{scope_id}，避免覆盖
apps/web/pipeline_backend.py	执行返回优先返回 scoped manifest
apps/web/vue3/main.py	执行前完成状态检查使用生成的 scope_id

验证场景：

场景	API 参数	预期
Lc 单物种树	targetSpecies=["Lc"]	生成 Lc 独立 manifest 和 tree
Lc+Dl 多物种树	targetSpecies=["Lc","Dl"]	生成 target-Lc-Dl scoped tree
Lc+Dl+At 分类树	targetSpecies=["Lc","Dl"], referenceSpecies=["At"]	生成 target-Lc-Dl.ref-At scoped tree

阶段 3：reference classification

文件	修订点
apps/web/pipeline_backend.py	reference_classification 必须通过同 scope phylogeny manifest 找树
apps/cli/run_reference_classification.py	manifest 记录 analysis_route=subfamily_prediction、tree_source、subfamily_source=predicted

验证：

• 执行亚家族分类时，manifest 中 tree_source 指向同 scope tree。
• 结果图带亚家族分类。

阶段 4：motif/domain/structure

文件	修订点
apps/cli/run_motif.py	scoped 输出命名、manifest 增加 scope_id/subfamily_source/member_set_id
apps/cli/run_domain.py	同上，并记录 e-value/coverage/Pfam/CDD 设置
apps/cli/run_structure.py	同上，并记录 id_mapping_policy、GFF 来源
apps/web/pipeline_backend.py	三阶段返回 scoped manifest；传入 confirmed subfamily 优先

验证：

• 单物种 Lc 的 structure 不被 Target.SPL 的 structure 跳过。
• 亚家族证据图和正式 structure 图文件名不同。
• confirmed subfamily 存在时，manifest 记录 subfamily_source=confirmed。

阶段 5：结果接口与自然语言规划

文件	修订点
apps/web/vue3/main.py	/api/results 根据 result_group/analysis_route/scope_id 分区
apps/web/vue3/index.html	展示区区分“亚家族确认”“进化树”“Motif/Domain/Structure”
gfa_core/mas/agents/planning_v2.py	自然语言映射到 single_species / multi_species / subfamily_prediction

验证：

• “帮我执行 Lc 的进化树分析”不会提示已完成，除非 Lc scoped/single manifest 真存在。
• “帮我执行亚家族分类分析”规划出 phylogeny + reference_classification，且使用 target+reference scope。

真实数据验证矩阵

使用已有真实数据：

角色	物种
Target	Lc, Dl
Reference	At
Comparative	Os
Family	SPL

测试编号	场景	验证方式	必须检查
T1	Lc 单物种 phylogeny	后端 API /api/execute	completed=false 后执行；生成 Lc 独立结果
T2	Lc+Dl 多物种 phylogeny	后端 API /api/execute	生成 scoped tree，不覆盖 T1
T3	Lc+Dl+At 亚家族预测树	后端 API /api/execute	生成 target+ref scoped tree
T4	reference_classification	后端 API /api/execute	使用 T3 的 tree_source
T5	Lc 单物种 structure/motif/domain	后端 API /api/execute	不被 Target.SPL 旧结果跳过
T6	亚家族证据 structure/motif/domain	后端 API /api/execute	结果归入亚家族确认，不覆盖正式图
T7	/api/results	后端 API	结果分区正确

本轮已完成的真实验证记录

时间：2026-05-21

验证项	后端 API/方式	结果
scoped stage-status	/api/stage-status?stage=phylogeny&prefix=Target.SPL&scope_id=SPL.target-Lc.ref-At.comp-Cp-Os-PPY-Sl.target_only	正确命中 scoped phylogeny manifest，不再用 unscoped Target.SPL.phylogeny.manifest.json 冒充完成
Lc 单物种 phylogeny	/api/execute stage=phylogeny targetSpecies=["Lc"] scopeMode=target_only	成功生成 Target.SPL.SPL.target-Lc.ref-At.comp-Cp-Os-PPY-Sl.target_only.phylogeny.manifest.json/tree.nwk
Lc scoped reference_classification	/api/execute stage=reference_classification targetSpecies=["Lc"] referenceSpecies=["At"] scopeMode=target_only	成功生成 scoped assignment/subfamily/confidence/tree 图；状态接口检查 10 个 artifact 通过
Lc scoped structure	/api/execute stage=structure targetSpecies=["Lc"] scopeMode=target_only	成功生成 scoped structure png/pdf/manifest；使用 Lc GFF、37 个成员和同 scope subfamily 表
structure 诊断误报修复	DiagnosisAgent.diagnose_stage_gate(..., params={"scope_id": ...})	postflight 从 blocking 变为 pass；诊断读取 manifest 中的 gene_id_file 和 gff3_source，不再误用 Cp GFF
Lc scoped motif	/api/execute stage=motif targetSpecies=["Lc"] scopeMode=target_only	成功生成 scoped motif png/pdf/report/manifest；MEME 实际运行 37 条蛋白，postflight pass
Lc scoped domain	/api/execute stage=domain targetSpecies=["Lc"] scopeMode=target_only	成功生成 scoped domain png/pdf/report/manifest；hmmscan 实际扫描 37 条蛋白，postflight pass
StageContext 基础字段	新增 gfa_core/gene_family_stage_context.py，并接入 phylogeny/reference_classification/structure/motif/domain manifest	manifest 统一记录 analysis_route/result_group/member_set_id/subfamily_source/stage_context，后续规划、状态判断、结果分区可共享同一身份字段
route-aware stage-status	/api/stage-status?...&stage=domain&analysis_route=single_species	旧 manifest 缺少 analysis_route 时不再冒充完成；domain 重新执行后带 analysis_route=single_species 可正确判定完成
route-aware execute skip	/api/execute stage=domain ... analysisRoute=single_species 连续执行两次	第一次因旧 manifest 缺 route 真实重跑；第二次命中同 route manifest 后返回 already_completed
CLI route 透传	/api/execute stage=structure ... analysisRoute=single_species	后端命令包含 --analysis-route single_species --member-set-id ...；新 structure manifest 记录 structure_single_species、Lc GFF、scope member ID 和同 scope tree
计划端 Lc 单物种	/api/agent/plan message="帮我执行Lc 的进化树分析"	计划返回 analysisRoute=single_species，targetSpecies=["Lc"]，completed_stages=[]；旧 unscoped manifest 不再导致“所有相关阶段已完成”
计划端 Lc+Dl 多目标	/api/agent/plan message="帮我执行Lc和Dl的进化树分析"	计划返回 analysisRoute=multi_target，targetSpecies=["Lc","Dl"]，用于后续单独生成多目标 scoped tree
计划端亚家族分类	/api/agent/plan message="帮我执行亚家族分类分析"	自动从已识别物种选择 targetSpecies=["Dl","Lc"]、referenceSpecies=["At"]、scopeMode=target_plus_reference；phylogeny/reference_classification 均带 analysisRoute=subfamily_prediction
前端执行透传	apps/web/vue3/index.html 请求体构造	executeStageDirect、executeSingleStageWithParams、fetchStageCompleted 均透传 scopeMode/geneFamily/targetSpecies/referenceSpecies/comparativeSpecies/analysisRoute；不在前端提前伪造无 scope_id 的 memberSetId
结果端分区	/api/results?job_id=job_1779270590216_0038e5	新增 _result_groups；真实返回包含 domain_single_species、structure_single_species，且 analysis_route=single_species
route mismatch 验证	/api/stage-status?stage=phylogeny&prefix=Target.SPL&analysis_route=single_species	返回 completed=false，错误为 Manifest analysis_route mismatch，证明旧普通树不会冒充 Lc 单物种树

仍需继续验证/修订：

• Lc+Dl 多目标 phylogeny、motif/domain/structure 的实际重跑输出。
• target+reference 亚家族证据路线的实际重跑输出及前端展示样式细分。

2026-05-21 追加修订：规划复用与 scope 顺序兼容

问题

真实运行后发现两个新的规划/复用边界：

1. targetSpecies=["Dl","Lc"] 与既有 manifest 文件中的 target-Lc-Dl 是同一批物种，但旧状态检查按字符串完全匹配，导致 completed_stages=[]。
2. 用户说“Lc 的进化树分析”时，规划只带 targetSpecies=["Lc"]，没有保留 config 中的 reference/comparative 角色上下文，无法复用既有 SPL.target-Lc.ref-At.comp-Cp-Os-PPY-Sl.target_only 结果。
3. 单物种请求依赖的 identify 可以由已有 Lc+Dl 批量 identify 满足，不能要求用户为了 Lc 再重跑 identify。

修订

文件	修订内容
apps/web/vue3/main.py	/api/agent/plan 在 scope-aware 基因家族阶段中始终从 config.xlsx 补齐 reference/comparative 角色上下文；reference_classification 计划沿用当前 job 的实际输出标签如 Target.SPL，不再显示 Multi.SPL
gfa_core/mas/tools/stage_status.py	增加 scope 集合签名匹配，target/ref/comp 物种顺序不同仍视为同一 scope
gfa_core/mas/tools/stage_status.py	scoped manifest 精确路径不存在时，扫描等价 scope manifest；必要时允许跨 prefix 复用同 scope 结果
gfa_core/mas/tools/stage_status.py	兼容旧 manifest 缺少 analysis_route 的情况；只在 manifest 明确写了不同 route 时判定不匹配
gfa_core/mas/tools/stage_status.py	identify 阶段允许已有 target 物种集合是当前请求 target 的超集，用于复用批量鉴定结果

真实 API 验证

场景	API/方式	结果
亚家族分类计划复用	/api/agent/plan message="帮我执行亚家族分类分析" prefix=Target.SPL	返回 prefix=Target.SPL，target_species=["Dl","Lc"]，reference_species=["At"]，comparative_species=["Cp","Os","PPY","Sl"]，completed_stages=["identify","phylogeny","reference_classification"]
target 顺序兼容	/api/stage-status?stage=phylogeny&scope_id=SPL.target-Dl-Lc.ref-At.comp-Cp-Os-PPY-Sl.target_plus_reference&analysis_route=subfamily_prediction	正确命中真实文件 Target.SPL.SPL.target-Lc-Dl.ref-At.comp-Cp-Os-PPY-Sl.target_plus_reference.phylogeny.manifest.json，completed=true
Lc 单物种计划复用	/api/agent/plan message="帮我执行Lc 的进化树分析" prefix=Target.SPL	返回 reference_species=["At"]、comparative_species=["Cp","Os","PPY","Sl"]，completed_stages=["identify","phylogeny"]；不会重跑已满足的 identify/phylogeny
Lc 单物种跨 prefix 复用	get_stage_status(job, prefix="Lc.SPL", stage="phylogeny", scope_id=SPL.target-Lc.ref-At.comp-Cp-Os-PPY-Sl.target_only, analysis_route=single_species)	正确复用 Target.SPL.SPL.target-Lc.ref-At.comp-Cp-Os-PPY-Sl.target_only.phylogeny.manifest.json
结果分区	/api/results?job_id=job_1779270590216_0038e5	返回分区包含 phylogeny_multi_target、structure_multi_target、structure_single_species、subfamily_confirmation，不同 route/scope 没有混在同一组

当前实事求是结论

进化树、亚家族分类、motif/domain/structure 的核心 identity 已经从单一 prefix+stage 推进到 prefix + scope_id + analysis_route + member_set_id。本轮真实 API 验证覆盖了：

• 单物种路线：Lc target_only single_species
• 多目标路线：Lc+Dl target_only multi_target
• 亚家族预测路线：Lc+Dl+At target_plus_reference subfamily_prediction

后续阶段继续修订时，应直接复用上述身份字段，不要重新发明一套命名或完成状态判断逻辑。