admin/PlantAI-dev

Fork 0

Files

T

potaser f745ee9d7e Initial commit: PlantAI-dev

2026-08-03 18:42:47 +08:00

78 KiB

Executable File

Raw Permalink Blame History

基因家族阶段统一命名完整修订方案

日期：2026-05-27
适用项目：bbav5_0502_Yang_Tihuan.7880
关联文档：

docs/gene_family_stage_naming_scope_rules_2026-05-26.md
docs/stage_requirements_agent_refactor_plan_2026-05-26.md
docs/gene_family_unified_rules_summary_2026-05-26.md

1. 本方案要解决的问题

当前命名混乱不是单个脚本的问题，而是以下几层同时在拼接名称：

前端规划弹窗和执行弹窗把 targetSpecies/referenceSpecies/comparativeSpecies/scopeMode/analysisRoute/memberSetId 展示和传递混在一起。
PlanningAgentV2、apps/web/vue3/main.py、pipeline_backend.py 分别有自己的文件名推断逻辑。
CLI 阶段脚本既接收 prefix，又接收 scope_id/scope_file/analysis_route，部分阶段把 prefix + scope_id 直接拼到产物名。
stage_status.py、stage_requirements.py、result_parser.py、前端结果接口又通过文件名反推阶段身份。

因此不能只改某个 run 脚本。必须统一“分析身份”和“用户可读文件名”的边界：

scope 保留，用于表达分析范围、依赖、复现和状态判断。
用户主产物文件名不再直接拼完整 scope_id。
identify 是单物种成员确认阶段，不应被多物种 scope 命名污染。
传统基因家族分析的主产物应保持清爽，例如 Lc.SPL.structure.png。
亚家族预测、亚家族确认、比较/参考参与的分析需要在文件名中体现必要上下文，但不能出现 Lc.SPL.SPL.target-Lc... 这种重复拼接。

2. 总体判定

2.1 scope 是否保留

保留。scope 是必要的，不是命名混乱的根源。它负责：

区分单物种、多个目标物种、目标加参考、目标加比较、确认后子集等分析场景。
支撑依赖判断，例如某个 motif 是基于原始成员、亚家族预测成员，还是确认后的成员。
支撑可复现记录和结果分组。

真正的问题是：当前把 scope_id 当成用户主文件名前缀直接拼接，导致重复和难读。

2.2 identify 的语义

identify 必须特殊处理：

无论用户是“单目标”还是“多目标”，成员确认本质上都是逐物种完成。
参考物种通常提供已知家族或参考证据，不应被当成目标物种执行成员确认。
比较物种如果需要鉴定，也应作为单独物种生成自己的成员文件。
目标/比较/参考角色应写入 manifest，不应写进主要成员文件名。

因此 identify 主产物应以单物种稳定前缀为准：

Lc.SPL.final_members.pep.fa
Lc.SPL.final_members.id
Lc.SPL.identify.manifest.json

不推荐继续把主成员文件命名为：

Target.Lc.SPL.final_members.pep.fa
Target.SPL.target-Lc-Dl.final_members.pep.fa
Lc.SPL.SPL.target-Lc.target_only.final_members.pep.fa

过渡期可以保留兼容副本，但不能把它们作为新逻辑的主入口。

3. 当前代码链路审计结论

3.1 从用户请求到执行的链路

当前链路大致为：

用户自然语言
  -> 前端 /api/agent/plan
  -> Intent/PlanningAgentV2
  -> apps/web/vue3/main.py 的确定性补丁
  -> StageIdentity / StageRequirements shadow
  -> pipeline_backend.py 提交执行
  -> apps/cli/run_*.py
  -> final/ 产物与 manifest
  -> stage_status/result_parser/results API
  -> 前端弹窗和结果展示

命名修订必须贯穿以上链路。只改 CLI 会导致前端状态判断找不到结果；只改前端会导致后端继续生成旧名；只改 result API 会导致执行和依赖仍混乱。

上面只是主执行链路，不是完整关联面。命名修订还必须覆盖下面这些旁路，否则会出现“阶段能跑、但智能体解释/诊断/复现/契约仍按旧文件名找结果”的问题。

3.2 完整关联面

3.2.1 MAS 多 Agent 与编排层

当前项目不是单 PlanningAgent 架构，至少包含以下会受命名影响的模块：

模块	关联原因	命名修订要求
`gfa_core/mas/agents/router.py`	路由用户请求到规划、执行、解释等模式	不应把旧 `prefix.scope_id` 当作阶段识别依据
`gfa_core/mas/agents/intent_v2.py`	识别用户意图、阶段、物种、家族	必须输出 target/reference/comparative 的角色语义，而不是把角色写进成员文件名前缀
`gfa_core/mas/core/fast_intent.py`	快速意图识别，可能绕过完整 LLM 规划	需同步物种规范化、阶段别名和 subfamily route 规则
`gfa_core/mas/agents/planning.py`	旧 PlanningAgent，仍可能被旧入口调用	要么标记废弃，要么同步命名 helper，不能保留旧路径判断
`gfa_core/mas/agents/planning_v2.py`	当前核心规划	只决定阶段和身份，不私自猜文件名
`gfa_core/mas/agents/execution.py`	MAS 执行 Agent	如果仍调用 stage tools，需要使用统一 StageIdentity 和 artifact resolver
`gfa_core/mas/agents/diagnosis.py`	失败诊断、自动修复、manifest 恢复	诊断缺输入时必须按新 species-main 和 scope-readable 规则查找
`gfa_core/mas/agents/knowledge.py`	未知错误时被 DiagnosisAgent 查询	知识案例中记录的路径和建议不能继续推荐旧命名
`gfa_core/mas/agents/discovery.py`	结果发现/知识发现	发现结果时应读 manifest artifacts，而不是按旧文件名 glob
`gfa_core/mas/agents/result_parser.py`	单次结果解析	静态 `EXPECTED_OUTPUTS` 只能作为老结果兜底
`gfa_core/mas/agents/result_parser_cumulative.py`	累积阶段解读	读取 manifest 时必须按 output_prefix/scope_id/result_group 归类
`gfa_core/mas/agents/interpretation_evidence.py`	证据驱动深度解读	`build_cumulative_interpretation()` 需要按新 identity 收集阶段证据
`gfa_core/mas/core/orchestrator.py`	旧 Orchestrator 编排	如果仍可被入口调用，需同步诊断/执行/结果解析的命名规则
`gfa_core/mas/core/langgraph_orchestrator.py`	LangGraph 编排	workflow state 中的 `stage_interpretations/diagnosis_result/execution_results` 需要记录 StageIdentity
`gfa_core/mas/core/message_bus.py`	Agent 间消息	消息 payload 应携带 `stage_identity`，避免只传 `prefix/stage`
`gfa_core/mas/core/state.py`	图状态	state schema 应允许保存 `scope_id/output_prefix/member_set_id/result_group`

3.2.2 语义索引、能力表、artifact resolver

这些模块会决定“已有文件能不能复用”和“某阶段缺什么输入”：

模块	当前关联	修订要求
`gfa_core/mas/stage_catalog.py`	阶段列表、依赖、队列、资源配置	依赖关系需要区分 identify、subfamily_prediction、subfamily_evidence、confirmed_subfamily、pairwise
`gfa_core/mas/stage_capabilities.py`	结构化能力层，定义 ArtifactNeed/ArtifactProduct	产物 pattern 不能只写 `{prefix}.{stage}`；需要支持 `species_prefix` 和 `scope_prefix`
`gfa_core/mas/artifact_resolver.py`	规划和诊断使用的语义产物解析	必须成为 StageRequirements 的底层能力之一，优先读 manifest artifacts
`gfa_core/mas/context_index.py`	扫描 workspace、manifest、artifact	`_split_prefix()` 不能把 `Target.SPL.target-Lc...` 误拆成物种 Target、家族 `SPL.target-Lc...`
`gfa_core/mas/tools/stage_registry.py`	阶段注册	注册信息应包含命名策略和 identity 类型
`gfa_core/mas/tools/stage_tools.py`	stage tool 执行/注册	如果仍使用，需停止内部拼旧文件名
`gfa_core/mas/tools/workflow.py`	工作流工具	workflow 节点应传 StageIdentity，而不是松散 params
`gfa_core/mas/tools/executor.py`	工具执行结果	ExecutionResult 应返回 manifest path 和 output_prefix

3.2.3 契约和 schema 层

命名修订必须同步 contract，否则“代码输出”和“契约验收”会冲突。涉及：

文件/目录	作用	修订要求
`gfa_core/schemas/core/workspace_contract_v1.md`	workspace/final/input 归属	增加 species-main、scope-readable、legacy 三类路径的规则
`gfa_core/schemas/core/manifest_v1.schema.json`	manifest 结构约束	增加或允许 `output_prefix/legacy_output_prefix/canonical_member_prefix/species_role/result_group/upstream_manifests`
`gfa_core/schemas/stages/*_contract_v1.md`	每阶段输入输出契约	每个基因家族阶段都要替换旧 `{prefix}.{scope_id}` 主命名
`gfa_core/schemas/outputs/figure_spec.yaml`	图件命名规范	`motif/domain/structure/combo` 图名需区分 traditional/subfamily_evidence/confirmed_subfamily
`gfa_core/schemas/outputs/report_spec.yaml`	报告和 manifest 命名规范	manifest 命名要从单一 `{prefix}.{stage}` 扩展为 identity-aware
`gfa_core/schemas/inputs/gene_family.yaml`	输入语义	target/reference/comparative 角色必须和 identify 语义一致
`gfa_core/schemas/skill.yaml`	skill 契约	skill 输出和 reproducibility 字段要同步新 manifest 字段

优先更新的 stage contracts：

identify_contract_v1.md
phylogeny_contract_v1.md
reference_classification_contract_v1.md
subfamily_confirm 当前没有独立 contract，需要补齐或并入 reference_classification contract
motif_contract_v1.md
domain_contract_v1.md
structure_contract_v1.md
combo_contract_v1.md
promoter_contract_v1.md
synteny_contract_v1.md
interspecies_synteny_contract_v1.md
karyotype_contract_v1.md
pep_contract_v1.md
expression_contract_v1.md
ortholog_contract_v1.md
kaks_contract_v1.md
ppi_contract_v1.md
summary_contract_v1.md

RNA-seq contracts 暂不属于本轮基因家族命名主改范围，但不能被破坏；expression 阶段跨 gene-family/RNA-seq，必须特别验证。

3.2.4 Project skills 层

项目内 skills/ 目录不是装饰文档，部分 skill wrapper 会写自己的输出、报告和可复现包。命名修订至少要审计：

skills/gene-identify/
skills/phylogeny/
skills/motif-analysis/
skills/domain-analysis/
skills/structure/
skills/promoter-analysis/
skills/synteny/
skills/interspecies/
skills/karyotype/
skills/kaks/
skills/ppi/
skills/expression/
skills/summary/
skills/annotation/

修订要求：

config.yaml 中的 output pattern、include_reproducibility、默认 prefix 必须与统一命名一致。
run.py 中如果生成 report.md/commands.sh/environment.yml/checksums.sha256，要把真实 output_prefix 和 manifest path 写进去。
如果某个 CLI 绕过 skill，仍需保证 skill 文档不再宣传旧命名。
RNA-seq skills 保持自身 prefix 体系，但不要被 gene-family scope 规则误改。

3.2.5 复现与 provenance 层

涉及：

模块	当前关联	修订要求
`gfa_core/reproducibility_v2.py`	`ReproducibilityManager.finalize()` 生成 `commands.sh/environment.yml/checksums.sha256/provenance.json`	provenance 必须记录 StageIdentity、output_prefix、legacy_output_prefix、scope_file hash、upstream manifest
`gfa_core/reproducibility.py`	旧 ReproducibilityBundle	若仍被旧 pipeline 调用，需要兼容新字段或标记弃用
`gfa_core/pipeline_with_repro.py`	旧 pipeline wrapper	如果仍可运行，需同步 manifest path 规则
`apps/web/pipeline_backend.py`	初始化并 finalize ReproducibilityManager	提交执行时传入的 prefix 不能只代表用户原始 prefix，还要保存 identity
`skills/*/run.py`	多个 skill 自写 reproducibility bundle	skill 复现包要写入统一 output_prefix，不得只写 demo/内部短名

3.2.6 诊断、自动修复和失败恢复

DiagnosisAgent 对命名高度敏感。当前代码中存在多处：

_load_stage_manifest(final_dir, stage, prefix, scope_id)
_protein_fasta_for_prefix()
_read_final_member_ids()
_build_recovered_identify_manifest()
_repair_missing_manifest_from_artifacts()
_audit_generic_gene_family_stage()
_gate_identify() / _gate_protein_stage() / _gate_gff_member_stage() / _gate_combo()

修订要求：

诊断必须通过统一 manifest candidate resolver 找 manifest。
identify 恢复 manifest 时，应恢复 {Species}.{Family}.identify.manifest.json，不是 Target.{Species}.{Family}。
报错文案必须区分“缺目标物种输入”“参考物种只是参考”“比较物种需要单独鉴定”。
自动修复不得生成违反新契约的 manifest。
诊断记忆 memory/diagnosis_cases.jsonl 中的新案例必须保存 StageIdentity，避免以后从旧路径学习错误模式。

3.2.7 深度解读、报告和前端解释层

涉及：

模块/API	当前关联	修订要求
`apps/web/vue3/main.py:/api/agent/interpret`	生成或读取解读报告	读取 manifest 时按 StageIdentity/result_group 过滤，不能只按 prefix glob
`gfa_core/mas/agents/interpretation_evidence.py`	证据驱动解读	evidence bundle 要使用 manifest artifacts，不直接猜 `Lc.SPL.structure.png`
`gfa_core/mas/agents/result_parser_cumulative.py`	累积解读	`stage_interpretations` key 应避免同 stage 不同 scope 互相覆盖
`gfa_core/mas/prompts/prompt_builder.py`	解读 prompt 构建	prompt 中的阶段名称和文件引用应使用 display_name/output_prefix
`gfa_core/mas/prompts/stage_examples/*`	阶段解释模板	不一定需要立刻改，但不能内嵌旧命名作为事实
`apps/web/vue3/static/interpretation-modal-demo.html`	前端解释展示样例	如果展示文件名，需要同步新命名

3.2.8 记忆、RAG、成本和会话层

这些不是第一优先级，但会影响智能体长期行为：

模块	修订要求
`gfa_core/mas/memory/*`	记忆中保存 job/stage 时带 StageIdentity，避免只记 prefix
`gfa_core/mas/rag.py`	如果检索历史案例，索引字段应包含 output_prefix/scope_id/result_group
`gfa_core/mas/context_index.py`	作为 RAG/诊断/规划共享上下文，应先于 Agent 私有 glob 修订
`gfa_core/mas/cost_tracker.py`	无直接命名逻辑，但报告 agent cost 时可按 result_group 统计
`gfa_core/mas/api/conversation_routes.py`	会话接口若返回阶段卡片，应返回 StageIdentity 摘要

3.2.9 旁路入口、辅助 CLI、测试和历史资产

反向扫描 prefix/scope_id/manifest/final_members/output_prefix 后，还需要纳入以下边缘但真实存在的关联面。它们不一定都要改运行逻辑，但必须逐项判定，否则后续会出现旁路入口继续生成旧名。

类别	文件/目录	处理要求
Celery/异步任务入口	`celery_app.py`、可能的 `tasks.py` 备份入口	确认可运行入口是否仍调用旧 pipeline；活动入口必须传 StageIdentity，不活动备份只记录不改
自然语言直接执行	`gfa_core/nl_executor.py`、`gfa_core/pipeline_api_integration.py`	若仍被 API 或脚本调用，返回结果必须包含 manifest path、output_prefix、stage_identity
旧 workflow/tool 层	`gfa_core/tools/identify_tool.py`、`gfa_core/workflows/identify_workflow.py`	identify 主产物命名同步 species-main；若已废弃，应在文档中标记不作为修订对象
pipeline 基础模块	`gfa_core/pipelines/*`	HMM、merge、domain scan、fasta utils 等通常不产出 final 主名，但如果写报告/中间文件，需要记录 canonical_member_prefix
scope 辅助解析	`apps/cli/resolve_scope.py`、`gfa_core/gene_family_scope.py`	作为 scope 数据源，必须输出统一字段：family、target/reference/comparative、scope_id、scope_mode
autofill/配置辅助	`apps/cli/run_config_autofill.py`、`run_samples_autofill.py`、`autofill_common.py`	不直接改 gene-family 主命名，但生成的配置不能把 reference 写成 target
refine/prepare 辅助阶段	`run_identify_refine.py`、`run_prepare_substep.py`、`run_sequence_extract_by_id.py`	如果产物会进入后续阶段，manifest 必须记录与 identify species-main 的关系
重绘/区域图阶段	`run_tree_plot.py`、`run_msa_region_plot.py`、`scripts/tree_domain.R`	属于 replot/subset/region 结果，命名必须避免覆盖主 phylogeny/motif/domain/structure
PPI/PEP 变体	`run_ppi_v2.py`、backup 中 `run_ppi_v2_with_repro.py`、legacy pep skill	活动脚本纳入命名；backup/legacy 只确认不会被调度
前端静态文件	`apps/web/vue3/index.html`、`agent_status_component.html`、`conversation-sidebar.js/css`、`static/*`	弹窗、任务卡片、结果卡片、诊断确认弹窗都要展示 StageIdentity 摘要
Vue3 copy/backup	`apps/web/vue3copy0416/`、`apps/web/vue3copy0417/`、`backups/`	不作为运行代码修订，但不能用于验证；文档中标为历史副本
资源治理	`gfa_core/mas/resource_governor.py`、`workspace/resource_governor/*.json`	通常不命名产物，但任务状态若显示 stage/prefix，应带 output_prefix
LLM 配置和 provider	`gfa_core/mas/llm/*`、`config/llm.yaml`、`config/api_config.yaml`	不改命名；只确认 prompt 中没有硬编码旧路径
API clients	`gfa_core/api_clients/*`	NCBI/Pfam/PlantCARE 输入输出如写 final 文件，需纳入 artifact resolver
R/绘图脚本	`scripts/*.R`	接收 output_prefix 的脚本必须由 CLI 传统一 output_prefix；R 脚本不自行拼 scope
测试体系	`tests/`、`scripts/test_.py`、`skills//tests/`、`apps/web/test_stage_integration.py`	新增命名单元测试、StageRequirements 测试、API 计划测试、真实 workspace 回归测试
文档和历史记录	`docs/`、`项目记录/`、根目录旧报告	历史记录不回改；当前规范文档需互相索引，避免旧方案被误当现行规则
workspace/final 历史结果	`workspace/*/final/.manifest.json`	不批量改历史结果；通过 legacy manifest 兼容和 manifest 内容扫描支持读取
graphify/cache	`graphify-out/`	只作为代码图缓存，不作为命名规则来源

处理原则：

活动执行入口必须改。
历史备份、copy、workspace 结果不批量改，但验证时不能误用它们作为当前代码依据。
所有可被前端/API/Agent 调用的入口，都必须传递或解析 StageIdentity。
所有测试和示例必须增加新命名样例，避免旧样例在后续修订中把代码拉回旧规则。

3.3 已确认的关键代码点

模块	当前职责	当前问题	修订方向
`gfa_core/gene_family_stage_context.py`	构建阶段上下文、scope、输出前缀	新旧命名函数并存，兼容逻辑还未完全收束	作为唯一命名入口
`gfa_core/mas/tools/stage_identity.py`	解析阶段身份	会把 scope/route/member_set 套到所有阶段	identify 需要单物种身份例外
`gfa_core/mas/stage_requirements.py`	解析阶段输入需求	当前主要覆盖 `phylogeny/pep`，且还优先搜索 `Target.{species}.{family}`	扩展为所有核心阶段，优先 species-main
`gfa_core/mas/tools/stage_status.py`	判断阶段是否完成	仍优先旧 scoped manifest，但已有等价 manifest 搜索能力	新短名优先，旧名兼容
`gfa_core/mas/agents/planning_v2.py`	规划阶段和依赖	存在私有文件名判断，如 direct combo、subfamily 文件检查	改为调用 StageRequirements/StageStatus
`apps/web/vue3/main.py`	API、规划补丁、状态、结果	规则很多，部分和 PlanningAgent 重复；结果展示还有文件名启发式	只做 UI 参数规范化，结果 manifest-first
`apps/web/pipeline_backend.py`	执行调度	大量阶段私有 scoped manifest 路径和文件名查找	统一走 StageIdentity + artifact resolver
`apps/cli/run_identify.py`	成员确认	仍生成 `Target.{species}.{family}` 和 batch/effective 前缀	主产物改为 `{Species}.{Family}`
`apps/cli/run_phylogeny.py` 等	传统分析	部分已接入新用户前缀，仍需统一 manifest 兼容策略	以统一 helper 为准
`apps/cli/run_reference_classification.py`	亚家族预测	已开始使用新前缀，但与后端查找仍未完全统一	固化为 subfamily_prediction 命名
`apps/cli/run_subfamily_confirm.py`	亚家族确认	主要按 `{prefix}.confirmed_subfamily.tsv`	明确 per species 与 aggregate 规则
`gfa_core/mas/agents/result_parser.py`	结果解析	静态 `EXPECTED_OUTPUTS` 和 scoped glob 仍存在	manifest artifacts 为唯一权威

4. 统一概念模型

4.1 三类前缀必须分清

名称	用途	示例	是否进入用户主文件名
`species_prefix`	单物种成员和传统分析主体	`Lc.SPL`	是
`scope_prefix`	用户可读的范围前缀	`Target.SPL.target-Lc.ref-At.subfamily_prediction`	特定场景进入
`legacy_scope_prefix`	旧系统兼容前缀	`Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference`	只做过渡兼容

不能再出现这种拼法：

prefix = Lc.SPL
scope_id = SPL.target-Lc.target_only
output_prefix = Lc.SPL.SPL.target-Lc.target_only

4.2 manifest 承担完整身份

文件名只保留用户需要识别的上下文，完整身份写入 manifest：

{
  "stage": "structure",
  "prefix": "Lc.SPL",
  "output_prefix": "Lc.SPL",
  "legacy_output_prefix": "Lc.SPL.SPL.target-Lc.target_only",
  "scope_id": "SPL.target-Lc.target_only",
  "scope_mode": "target_only",
  "analysis_route": "single_species",
  "member_set_id": "SPL.target-Lc.target_only:single_species:all_members",
  "result_group": "traditional",
  "family": "SPL",
  "target_species": ["Lc"],
  "reference_species": [],
  "comparative_species": [],
  "selected_species": ["Lc"],
  "artifacts": {}
}

状态判断、结果展示、依赖解析必须读 manifest 字段，不能再依赖文件名是否包含 target_plus_reference。

5. 分析场景分类与命名规则

5.1 单物种成员确认 identify

适用：

目标物种成员确认。
比较物种成员确认。
用户后续要拿这些成员做进化树、motif、domain、structure、expression 等传统分析。

主命名：

{Species}.{Family}.final_members.pep.fa
{Species}.{Family}.final_members.id
{Species}.{Family}.identify.manifest.json

示例：

Lc.SPL.final_members.pep.fa
Lc.SPL.final_members.id
Lc.SPL.identify.manifest.json
Os.SPL.final_members.pep.fa
Os.SPL.final_members.id
Os.SPL.identify.manifest.json

角色写 manifest：

{
  "species": "Os",
  "species_role": "comparative",
  "family": "SPL"
}

参考物种如果只是参考，不生成 identify 主成员文件。参考已知家族输入使用：

At.SPL.pep.fa
At.SPL.fasta
At.SPL.known_family.pep.fa

5.2 单物种传统基因家族分析

适用阶段：

phylogeny
motif
domain
structure
promoter
synteny
karyotype
combo
ppi 中的单物种模式
expression
pep
summary 的单物种汇总

主命名：

{Species}.{Family}.{stage}.{ext}

示例：

Lc.SPL.phylogeny.treefile
Lc.SPL.motif.png
Lc.SPL.domain.tsv
Lc.SPL.structure.png
Lc.SPL.promoter.cis.tsv
Lc.SPL.synteny.png
Lc.SPL.combo.png
Lc.SPL.expression.heatmap.pdf
Lc.SPL.pep.properties.tsv

这类结果的 scope_id 仍写入 manifest，例如 SPL.target-Lc.target_only，但不进入主文件名。

5.3 多目标物种传统分析

适用：

用户明确要求多个目标物种联合建树、联合 motif、联合 domain 或联合 combo。
不是 identify 的主成员文件。

主命名：

Target.{Family}.target-{SpeciesA}-{SpeciesB}.{stage}.{ext}

示例：

Target.SPL.target-Lc-Dl.phylogeny.treefile
Target.SPL.target-Lc-Dl.motif.png
Target.SPL.target-Lc-Dl.combo.png

每个物种的 identify 仍然是：

Lc.SPL.final_members.pep.fa
Dl.SPL.final_members.pep.fa

联合分析的 manifest 记录输入来源：

{
  "scope_mode": "multi_target",
  "analysis_route": "multi_target",
  "scope_input_fasta": "input/scoped/Target.SPL.target-Lc-Dl.members.pep.fa",
  "upstream_manifests": [
    "final/Lc.SPL.identify.manifest.json",
    "final/Dl.SPL.identify.manifest.json"
  ]
}

5.4 目标加参考的亚家族预测

适用：

用户说“执行某物种亚家族分类/确认前分类”。
需要目标物种成员加参考物种已知家族或已知分类证据。
参考物种参与证据构建，但不被当成目标成员确认对象。

主命名：

Target.{Family}.target-{Species}.ref-{Reference}.subfamily_prediction.reference_classification.{ext}

示例：

Target.SPL.target-Lc.ref-At.subfamily_prediction.reference_classification.tree.png
Target.SPL.target-Lc.ref-At.subfamily_prediction.reference_classification.subfamily.tsv
Target.SPL.target-Lc.ref-At.subfamily_prediction.reference_classification.manifest.json

不再使用：

Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.reference_classification.subfamily.tsv

5.5 亚家族证据图

适用：

亚家族预测后、人工确认前，为辅助判断生成的 structure/motif/domain/combo 证据图。
这些图不是传统最终分析主结果，应该和传统 Lc.SPL.structure.png 区分。

主命名：

Target.{Family}.target-{Species}.ref-{Reference}.subfamily_evidence.{stage}.{ext}

示例：

Target.SPL.target-Lc.ref-At.subfamily_evidence.structure.png
Target.SPL.target-Lc.ref-At.subfamily_evidence.motif.png
Target.SPL.target-Lc.ref-At.subfamily_evidence.domain.tsv
Target.SPL.target-Lc.ref-At.subfamily_evidence.combo.png

5.6 亚家族确认后传统分析

适用：

人工确认后，用户继续做进化树、motif、domain、structure、combo、表达等正式分析。
这些结果已经属于用户要使用的传统分析结果，只是带有确认后的亚家族标签。

推荐命名：

{Species}.{Family}.confirmed_subfamily.tsv
{Species}.{Family}.confirmed_subfamily.{stage}.{ext}

示例：

Lc.SPL.confirmed_subfamily.tsv
Lc.SPL.confirmed_subfamily.phylogeny.treefile
Lc.SPL.confirmed_subfamily.structure.png
Lc.SPL.confirmed_subfamily.combo.png

如果同一物种同一阶段既有“未确认成员集”的传统结果，又有“确认后亚家族标签”的结果，必须用 confirmed_subfamily 区分。

5.7 目标加比较物种分析

适用：

用户要求目标物种与比较物种共同分析，但比较物种不是参考物种。
比较物种可以有自己的 identify 主成员文件。

联合产物命名：

Target.{Family}.target-{TargetSpecies}.comp-{ComparativeSpecies}.{stage}.{ext}

示例：

Target.SPL.target-Lc.comp-Os.phylogeny.treefile
Target.SPL.target-Lc.comp-Os.combo.png

比较物种自己的成员文件仍然是：

Os.SPL.final_members.pep.fa
Os.SPL.final_members.id

5.8 两两或跨物种阶段

适用阶段：

interspecies_synteny
ortholog
kaks_v2
部分 ppi

命名应体现 pair 身份：

Target.{Family}.target-{TargetSpecies}.ref-{ReferenceSpecies}.{stage}.{ext}
Target.{Family}.target-{TargetSpecies}.comp-{ComparativeSpecies}.{stage}.{ext}

示例：

Target.SPL.target-Lc.ref-At.interspecies_synteny.png
Target.SPL.target-Lc.ref-At.kaks.tsv
Target.SPL.target-Lc.comp-Os.ortholog.tsv

6. 阶段级修订表

阶段	当前主要问题	新主命名	依赖解析要求
`identify`	`Target.{species}.{family}` 与 batch/scoped prefix 混用	`{Species}.{Family}.final_members.*`	按物种查找成员，角色在 manifest
`phylogeny`	单物种与 scoped 联合分析混在文件名	单物种 `{Species}.{Family}.phylogeny.`；联合 `Target.{Family}.target-...phylogeny.`	从 identify species outputs 或 scoped FASTA
`motif`	已部分改短名，但后端查找仍旧	同 phylogeny	读取 phylogeny/member_set identity
`domain`	已部分改短名，但后端查找仍旧	同 phylogeny	同上
`structure`	已部分改短名，但后端查找仍旧	同 phylogeny	需要 genome/gff 与 member ids
`combo`	组合图有 legacy copy，状态逻辑已放宽	单物种 `{Species}.{Family}.combo.`；证据图 `subfamily_evidence.combo.`	从 motif/domain/structure/phylogeny manifest
`reference_classification`	旧名过长，前后端候选不一致	`Target.{Family}.target-{Species}.ref-{Reference}.subfamily_prediction.reference_classification.*`	目标成员 + 参考家族/分类
`subfamily_confirm`	输入候选散落	`{Species}.{Family}.confirmed_subfamily.tsv`	输入 prediction tsv，输出确认标签
`promoter`	只按 `{prefix}.final_members.id` 不够	`{Species}.{Family}.promoter.*`；确认后加 `confirmed_subfamily`	species-main member id
`synteny`	搜索顺序兼容旧 Target 前缀	`{Species}.{Family}.synteny.*`	species-main member id
`interspecies_synteny`	pair 身份不够清晰	`Target.{Family}.target-{T}.ref-{R}.interspecies_synteny.*`	target/ref pair manifest
`karyotype`	单物种/多物种图未分清	单物种 `{Species}.{Family}.karyotype.*`；联合按 Target prefix	物种 genome/gff
`ppi`	单物种与跨物种模式需区分	单物种 `{Species}.{Family}.ppi.*`；pair 用 Target prefix	按阶段参数
`expression`	依赖 `{prefix}.final_members.id`	`{Species}.{Family}.expression.*`	species-main member id
`pep`	候选路径有旧 Target 优先	`{Species}.{Family}.pep.*`	species-main member pep
`summary`	按文件名是否含 scope_id 分组	`{output_prefix}.summary.*`	manifest identity 分组

7. 需要同步修订的代码模块

7.1 `gfa_core/gene_family_stage_context.py`

目标：成为唯一命名入口。

需要补齐：

species_prefix_for(species, family) -> Lc.SPL
user_output_prefix_for(stage, prefix, scope_data, analysis_route, member_set_id)
legacy_output_prefix_for(...)
manifest_path_candidates_for(stage_identity)
artifact_basename_for(stage_identity, artifact_kind)

原则：

CLI、后端、状态、结果展示不得再自己拼 prefix.scope_id.stage。
旧名只在这里生成兼容候选。

7.2 `gfa_core/mas/tools/stage_identity.py`

目标：明确阶段身份，不让所有阶段被同一套 scope 过度套用。

需要补齐：

identify 使用 species_member_identity，逐物种生成。
传统单物种阶段使用 single_species route。
亚家族预测使用 subfamily_prediction route。
亚家族确认后分析使用 confirmed_subfamily 或 confirmed_subfamily_analysis route。
pairwise 阶段使用 pairwise_reference 或 pairwise_comparative route。

7.3 `gfa_core/mas/stage_requirements.py`

目标：把“输入文件怎么找”从 PlanningAgent 和 pipeline_backend 中抽出来。

必须扩展：

identify：检查 target proteome/genome/gff/hmm 等必要输入，支持物种名大小写规范化。
phylogeny/motif/domain/structure/combo：按 StageIdentity 解析成员 FASTA、GFF、上游 manifest。
reference_classification：解析目标成员、参考家族、参考分类、参考树/结构证据。
subfamily_confirm：解析 prediction tsv 和人工编辑文件。
promoter/synteny/expression/pep：优先使用 {Species}.{Family}.final_members.*。
interspecies_synteny/ortholog/kaks：解析 target-reference 或 target-comparative pair。

搜索顺序必须改为：

1. 新 species-main 或 scope-readable 主路径
2. manifest artifacts 中记录的路径
3. 旧 Target.{species}.{family} 兼容路径
4. 旧 prefix.scope_id.stage 兼容路径

7.4 `gfa_core/mas/agents/planning_v2.py`

目标：规划只决定“要做哪些阶段”，不再私自猜文件名。

需要修订：

_combo_target_member_ready() 改为调用 StageRequirements。
_combo_prediction_file() 改为调用 StageRequirements 或 result resolver。
_apply_direct_combo_subfamily_stage_details() 只负责设置阶段语义，不负责下游文件名。
规划中 identify 阶段只传待鉴定物种列表，不把 reference 变成 target。
当用户说“PPy/PPY/Ppy”时，规划应通过物种规范化解析到真实物种，而不是造成 target_proteome 缺失误判。

7.5 `apps/web/vue3/main.py`

目标：前端 API 保留必要确定性修正，但不再复制后端命名规则。

需要修订：

/api/agent/plan 中 reference_classification 的 scope/route 设置可以保留，但必须调用统一 identity builder。
identify 参数只显示“待鉴定物种”，参考物种单独显示为“参考证据”，不要上下重复列物种。
第二个执行确认弹窗应显示 StageIdentity 摘要：

阶段：亚家族预测
目标物种：Lc
参考物种：At
输出前缀：Target.SPL.target-Lc.ref-At.subfamily_prediction
输入成员：Lc.SPL.final_members.pep.fa

不再让用户在第二个弹窗重复勾选已经由第一步规划确定的目标/参考/比较物种。
结果接口优先读 manifest artifacts/result_group/stage/analysis_route，文件名启发式只作为无 manifest 老结果兜底。

7.6 `apps/web/pipeline_backend.py`

目标：执行调度只根据 StageIdentity 和 StageRequirements 提交 CLI。

需要修订：

去掉每个阶段私有的 final/{prefix}.{scope_id}.{stage}.manifest.json 查找。
执行前调用 StageRequirements 得到输入路径。
调用 CLI 时传 --scope-file/--analysis-route/--member-set-id，但输出名由 CLI 统一 helper 决定。
resolve_subfamily_for_plotting() 改为从 reference_classification/subfamily_confirm manifest artifacts 找文件。

7.7 CLI 阶段脚本

目标：所有 run_*.py 都按统一 helper 命名和写 manifest。

第一批已经部分接入的阶段需要收口：

run_phylogeny.py
run_reference_classification.py
run_motif.py
run_domain.py
run_structure.py
run_combo.py

第二批需要迁移：

run_identify.py
run_subfamily_confirm.py
run_pep.py
run_promoter.py
run_synteny.py
run_interspecies_synteny.py
run_karyotype.py
run_expression.py
run_summary.py
run_ppi.py
run_ortholog.py
run_kaks_v2.py

每个 CLI 必须写：

{
  "output_prefix": "...",
  "legacy_output_prefix": "...",
  "canonical_member_prefix": "Lc.SPL",
  "scope_id": "...",
  "analysis_route": "...",
  "member_set_id": "...",
  "result_group": "...",
  "artifacts": {
    "main": {"path": "final/...", "type": "..."}
  }
}

7.8 `stage_status.py`

目标：状态判断按 identity，不按文件名猜测。

需要修订：

新主 manifest 优先：

final/{output_prefix}.{stage}.manifest.json

旧 manifest 兼容：

final/{prefix}.{scope_id}.{stage}.manifest.json

如果路径不匹配，允许扫描 manifest 内容，只要 stage/scope_id/analysis_route/member_set_id 等价即可。
identify 的 target/reference/comparative 要特殊匹配：参考物种不是 identify 缺失条件。

7.9 `result_parser.py` 与结果 API

目标：结果展示按 manifest，不按文件名硬过滤。

需要修订：

EXPECTED_OUTPUTS 只能作为老结果兜底，不能作为新结果权威。
结果分组使用 manifest：

traditional
subfamily_prediction
subfamily_evidence
confirmed_subfamily
pairwise
summary

隐藏中间产物时按 result_group 或 display_policy，不按文件名含不含 reference_classification。

8. 弹窗设计修订原则

8.1 第一个规划弹窗

只回答三件事：

用户要执行哪些阶段。
每个阶段的分析身份是什么。
预计会产生什么用户可读输出前缀。

示例：

阶段：亚家族预测
家族：SPL
目标物种：Lc
参考物种：At
比较物种：无
输出前缀：Target.SPL.target-Lc.ref-At.subfamily_prediction

不要在上面列一遍物种、下面又列一遍同样物种让用户勾选。

8.2 第二个执行确认弹窗

只确认运行参数，不再重新决定物种范围。

示例：

阶段 1/1：亚家族预测
输入成员：Lc.SPL.final_members.pep.fa
参考证据：At.SPL.pep.fa
输出：
  Target.SPL.target-Lc.ref-At.subfamily_prediction.reference_classification.subfamily.tsv
  Target.SPL.target-Lc.ref-At.subfamily_prediction.reference_classification.tree.png

如果必须允许修改物种，应提供“返回规划修改”，而不是在执行弹窗继续勾选。

9. 分阶段实施计划

Phase 0：冻结规则文档

产物：

本文档。
更新 gene_family_stage_naming_scope_rules_2026-05-26.md 中与本文冲突的条目。

完成标准：

identify 的单物种主命名明确。
传统分析和亚家族预测/证据/确认后分析区分明确。
scope 保留但不污染用户主文件名。

Phase 1：核心命名 helper 与测试

修改：

gfa_core/gene_family_stage_context.py
新增或扩展命名单元测试。

测试例：

identify Lc/SPL -> Lc.SPL
structure single_species Lc/SPL -> Lc.SPL.structure.png
reference_classification Lc+At -> Target.SPL.target-Lc.ref-At.subfamily_prediction.reference_classification.subfamily.tsv
combo subfamily_evidence Lc+At -> Target.SPL.target-Lc.ref-At.subfamily_evidence.combo.png
phylogeny Lc+Dl -> Target.SPL.target-Lc-Dl.phylogeny.treefile

Phase 2：identify 主产物迁移

修改：

apps/cli/run_identify.py
stage_status.py identify 匹配。
stage_requirements.py 成员解析。

要求：

新主产物写 {Species}.{Family}.final_members.*。
旧 Target.{Species}.{Family} 可写兼容副本。
batch 文件只作为聚合输入或 manifest artifacts，不作为单物种成员主文件。

Phase 3：StageRequirements 全阶段化

修改：

gfa_core/mas/stage_requirements.py
相关测试或诊断脚本。

要求：

所有核心阶段都能通过 StageIdentity 解析输入。
PlanningAgent 和 pipeline_backend 不再各自查同一类文件。
PPy/Ppy/PPY 这类物种名大小写问题在需求解析层统一处理。

Phase 4：PlanningAgentV2 与 web plan 收口

修改：

gfa_core/mas/agents/planning_v2.py
apps/web/vue3/main.py

要求：

规划负责阶段和语义，不负责文件名猜测。
identify 只处理待鉴定物种。
reference/comparative 分开显示。
第一个弹窗和第二个弹窗不重复要求用户勾选同一批物种。

Phase 5：pipeline_backend 执行链路收口

修改：

apps/web/pipeline_backend.py

要求：

执行前统一调用 StageIdentity + StageRequirements。
CLI 参数传语义，不传旧文件名假设。
所有 manifest 路径候选来自统一 helper。

Phase 6：CLI 第二批阶段迁移

修改：

run_pep.py
run_promoter.py
run_synteny.py
run_interspecies_synteny.py
run_karyotype.py
run_expression.py
run_summary.py
run_ppi.py
run_ortholog.py
run_kaks_v2.py
run_subfamily_confirm.py

要求：

输出主文件名按本文规则。
manifest 字段完整。
旧名只做兼容，不作为新逻辑入口。

Phase 7：契约、schema、能力表同步

修改：

gfa_core/schemas/core/workspace_contract_v1.md
gfa_core/schemas/core/manifest_v1.schema.json
gfa_core/schemas/stages/*_contract_v1.md
gfa_core/schemas/outputs/figure_spec.yaml
gfa_core/schemas/outputs/report_spec.yaml
gfa_core/schemas/inputs/gene_family.yaml
gfa_core/schemas/skill.yaml
gfa_core/mas/stage_capabilities.py
gfa_core/mas/stage_catalog.py

要求：

contract 中的输入/输出命名和 CLI 实际产物一致。
manifest schema 允许并要求关键 identity 字段。
stage capabilities 的 ArtifactProduct 不再只依赖 {prefix}.{stage}。
stage catalog 的依赖关系能区分传统分析、亚家族预测、亚家族证据、确认后分析和 pairwise 分析。
subfamily_confirm 需要补 contract，或者在 reference_classification_contract_v1.md 中明确作为后续确认阶段；不应继续处于无契约状态。

Phase 8：结果展示、诊断和自动修复收口

修改：

gfa_core/mas/agents/result_parser.py
gfa_core/mas/agents/result_parser_cumulative.py
gfa_core/mas/agents/diagnosis.py
gfa_core/mas/artifact_resolver.py
gfa_core/mas/context_index.py
apps/web/vue3/main.py 结果 API / diagnosis API

要求：

结果展示以 manifest artifacts 为权威。
raw file glob 只兜底老结果。
诊断报告按 StageIdentity/Requirements 说明缺什么，不再只报“缺 target_proteome”。
自动修复和 manifest 恢复不得恢复成旧命名契约。
context index 和 artifact resolver 不能把 Target.SPL.target-Lc... 错拆成物种和家族。

Phase 9：Project skills 和复现系统同步

修改：

skills/gene-identify/
skills/phylogeny/
skills/motif-analysis/
skills/domain-analysis/
skills/structure/
skills/promoter-analysis/
skills/synteny/
skills/interspecies/
skills/karyotype/
skills/kaks/
skills/ppi/
skills/expression/
skills/summary/
gfa_core/reproducibility_v2.py
gfa_core/reproducibility.py
gfa_core/pipeline_with_repro.py

要求：

skill 文档、config、wrapper 输出不再宣传或生成旧主命名。
skill 自带 commands.sh/environment.yml/checksums.sha256 时，记录真实 output_prefix 和 manifest path。
ReproducibilityManager.finalize() 生成的 provenance.json 包含 StageIdentity、scope_file hash、upstream manifests 和 legacy copy 说明。
旧 reproducibility API 若仍被调用，至少能读新 manifest 字段；不能静默丢失 scope/route/member_set。

Phase 10：深度解读、知识、记忆和编排层同步

修改：

gfa_core/mas/agents/interpretation_evidence.py
gfa_core/mas/agents/result_parser_cumulative.py
gfa_core/mas/prompts/prompt_builder.py
gfa_core/mas/agents/knowledge.py
gfa_core/mas/agents/discovery.py
gfa_core/mas/core/orchestrator.py
gfa_core/mas/core/langgraph_orchestrator.py
gfa_core/mas/core/message_bus.py
gfa_core/mas/core/state.py
gfa_core/mas/memory/*
gfa_core/mas/rag.py
gfa_core/mas/api/conversation_routes.py

要求：

深度解读按 stage + output_prefix + result_group 建 key，避免同一 stage 不同 scope 覆盖。
interpretation evidence 从 manifest artifacts 取证据，不直接按文件名猜。
Agent 间消息和 workflow state 携带 StageIdentity 摘要。
诊断案例、RAG 案例、会话阶段卡片记录新 identity 字段，避免长期记忆继续传播旧命名。

Phase 11：旁路入口、辅助脚本、前端静态和测试体系收口

修改/审计：

celery_app.py 和活动任务入口
gfa_core/nl_executor.py
gfa_core/pipeline_api_integration.py
gfa_core/tools/identify_tool.py
gfa_core/workflows/identify_workflow.py
apps/cli/resolve_scope.py
gfa_core/gene_family_scope.py
apps/cli/run_config_autofill.py
apps/cli/run_samples_autofill.py
apps/cli/run_identify_refine.py
apps/cli/run_tree_plot.py
apps/cli/run_msa_region_plot.py
apps/web/vue3/index.html
apps/web/vue3/agent_status_component.html
apps/web/vue3/static/*
tests/、scripts/test_*.py、skills/*/tests/

要求：

活动入口全部传递 StageIdentity 或调用统一 resolver。
辅助阶段不覆盖主结果，使用 replot/subset/region 明确命名。
前端静态弹窗、任务卡片、诊断确认弹窗显示 output_prefix 和角色语义。
测试覆盖新命名、legacy 兼容、结果展示、诊断、解读、复现。
backup/copy/legacy 目录只标记为历史副本，不作为当前运行入口。

Phase 12：真实数据验证与兼容清理

验证通过后再考虑减少 legacy copy。

不建议立刻删除旧名兼容，因为历史 job、前端结果页、诊断记忆和解读缓存仍可能依赖旧 manifest。

10. 真实数据验证矩阵

验证工作区：

workspace/job_1779614808704_edb235

必须覆盖：

场景	验证点	期望
Lc 单物种 identify	成员主产物	`Lc.SPL.final_members.*`
PPy/Ppy 亚家族分类	物种名规范化	不再误报缺 `target_proteome`
Lc 单物种传统 structure/domain/combo	短名输出和状态	`Lc.SPL.structure.png` 等，status success
Lc + At 亚家族预测	参考不当 target	输出 `Target.SPL.target-Lc.ref-At.subfamily_prediction...`
亚家族证据图	与传统图区分	输出 `subfamily_evidence.structure/motif/domain/combo`
人工确认后传统分析	使用确认标签	输出 `Lc.SPL.confirmed_subfamily.*`
Lc + Os 比较分析	comparative 单独显示	比较物种不混进 reference
interspecies/kaks	pair identity	`target-Lc.ref-At` 或 `target-Lc.comp-Os`
前端规划弹窗	不重复物种列表	第一弹窗说明身份，第二弹窗确认输入输出
结果页	manifest-first	不因短名缺 scope_id 被过滤
stage contracts	契约和实际输出一致	contract 不再把旧 `{prefix}.{scope_id}` 当主命名
project skills	skill 文档和 wrapper	不再宣传旧主命名，复现包记录 output_prefix
reproducibility	provenance/commands/checksums	记录 StageIdentity、upstream manifest、scope_file hash
DiagnosisAgent	preflight/postflight/repair	按新成员路径诊断，不恢复旧 manifest
interpretation	深度解读和累积报告	同 stage 多 scope 不互相覆盖，证据来自 manifest artifacts
context_index/artifact_resolver	workspace 扫描	不误拆 Target scope 前缀，优先 manifest artifacts
memory/RAG	历史案例记录	新案例包含 StageIdentity，不把旧路径作为推荐模式
celery/nl/workflow 旁路入口	非主 API 调用	不再绕过 StageIdentity 生成旧名
refine/replot/region 辅助阶段	辅助产物命名	不覆盖主阶段结果，manifest 记录来源
前端静态文件	弹窗和任务卡片	显示 output_prefix/roles，不显示混乱 scope 串
测试体系	单元/集成/e2e/skill tests	新命名和 legacy 兼容都有测试
历史副本/backup/workspace	回归兼容	不作为当前代码依据，不批量改历史结果

验证命令类型：

python -m py_compile <modified files>
pytest <naming and requirements tests>
python apps/cli/run_identify.py ...
python apps/cli/run_reference_classification.py ...
python apps/cli/run_structure.py ...
python apps/cli/run_domain.py ...
python apps/cli/run_combo.py ...
curl /api/agent/plan
curl /api/stage-status
curl /api/results
curl /api/agent/diagnose_job_stage
curl /api/agent/interpret
python -m py_compile gfa_core/mas/agents/diagnosis.py gfa_core/mas/agents/interpretation_evidence.py
python -m py_compile gfa_core/mas/artifact_resolver.py gfa_core/mas/context_index.py
python apps/cli/validate_manifest.py ...

11. 风险和取舍

11.1 是否在文件名中写 Comparative

不建议把比较物种自己的单物种主产物写成：

Comparative.Os.SPL.final_members.pep.fa

原因：

同一物种在另一个任务中可能是 target。
成员文件本身应稳定，角色是任务上下文，不是物种成员本身属性。

11.2 是否立刻删除旧命名

不建议。

原因：

历史 workspace 仍有旧 manifest。
前端结果页和诊断工具可能还会扫描旧文件。
一次性删除会把命名修订和兼容性问题混在一起，难以定位错误。

建议至少保留一个版本周期的 legacy manifest/artifact copy。

11.3 reference species 是否要勾选

在 UI 上应分开：

目标/比较物种：决定是否执行 identify 和传统分析。
参考物种：提供参考证据，不参与目标鉴定，除非用户明确要求“也鉴定参考物种”。

所以参考物种不应在 identify 目标列表里默认勾选。

12. 验收标准

这次命名修订完成后，应满足：

单物种传统分析主文件名保持清爽：Lc.SPL.structure.png。
identify 主成员文件稳定：Lc.SPL.final_members.pep.fa。
亚家族预测能看出目标和参考：Target.SPL.target-Lc.ref-At.subfamily_prediction...。
亚家族证据图能和传统结果区分：subfamily_evidence。
确认后分析能和未确认传统结果区分：confirmed_subfamily。
scope_id 保留在 manifest 和状态判断中，但不直接污染用户主文件名。
PlanningAgent、web backend、CLI、stage_status、requirements、result_parser 使用同一套命名 helper。
前端两个弹窗不再重复列物种，也不让用户在执行确认阶段重新猜该不该勾选参考物种。
真实数据验证通过后，再由用户在前端执行验证。

13. 推荐执行顺序

最优顺序是：

先统一命名体系
  -> 再推进 stage_requirements_agent_refactor_plan_2026-05-26.md

原因：

阶段需求智能体最终也要回答“某阶段缺什么输入、已有哪个输出、能否复用哪个结果”。
如果命名规则未统一，需求智能体会继续继承旧的混乱路径判断。
先把 identity/naming/artifact resolver 定下来，再做需求智能体重构，返工最少。

但两者不能完全割裂。执行时应把命名 helper、StageIdentity、StageRequirements 作为同一条主线修订，只是验收顺序上先验收命名，再验收完整需求智能体。

14. 2026-05-27 Phase 1/2 实施进展

已完成首轮代码落地，范围限定为命名核心和 identify 主产物，不涉及前端弹窗。

修改文件：

gfa_core/gene_family_stage_context.py
gfa_core/mas/tools/stage_status.py
gfa_core/mas/stage_requirements.py
apps/cli/run_identify.py

已落地规则：

identify 的 analysis_route 不再因为参考物种存在而变成 multi_species；单目标 identify 固定为 single_species。
新增 species_prefix_for(species, family)，单物种成员主前缀为 {Species}.{Family}。
identify 的用户输出前缀强制回到 species-main，例如 Ppy.SPL。
stage_status 对 identify 优先读取 final/{Species}.{Family}.identify.manifest.json，同时兼容旧 scoped/aggregate manifest。
StageRequirements 已加入 identify 输入解析，能识别真实输入 Ppy.pep.fasta，并在 phylogeny/pep 成员解析中优先使用 {Species}.{Family}.final_members.pep.fa。
run_identify.py 现在为每个物种生成 species-main 主文件，并保留旧 Target.{Species}.{Family} 兼容副本。

真实数据验证：

input:     input/job_1779614808704_edb235
workspace: /tmp/bbav5_identify_naming_test_ppy_20260527
command:   python apps/cli/run_identify.py --input-dir input/job_1779614808704_edb235 --workspace /tmp/bbav5_identify_naming_test_ppy_20260527 --prefix Target.SPL --target-species Ppy --required-pfams PF03110 --cpu 2 --skip-ref-warning --force

验证结果：

/tmp/bbav5_identify_naming_test_ppy_20260527/final/Ppy.SPL.final_members.pep.fa
/tmp/bbav5_identify_naming_test_ppy_20260527/final/Ppy.SPL.final_members.id
/tmp/bbav5_identify_naming_test_ppy_20260527/final/Ppy.SPL.identify.manifest.json
/tmp/bbav5_identify_naming_test_ppy_20260527/final/Target.Ppy.SPL.final_members.pep.fa
/tmp/bbav5_identify_naming_test_ppy_20260527/final/Target.Ppy.SPL.final_members.id
/tmp/bbav5_identify_naming_test_ppy_20260527/final/Target.SPL.identify.manifest.json

Ppy.SPL.identify.manifest.json 关键字段：

prefix = Ppy.SPL
output_prefix = Ppy.SPL
canonical_member_prefix = Ppy.SPL
legacy_output_prefix = Target.Ppy.SPL
analysis_route = single_species
result_group = gene_family_identify
species_role = target
target_species = [Ppy]
reference_species = [At]

额外验证：

python -m py_compile 通过：上述 4 个修改文件加 stage_identity.py。
StageRequirements 对 identify/Ppy 返回 ready，并解析到 input/job_1779614808704_edb235/Ppy.pep.fasta。
stage_status 对隔离运行的 Ppy.SPL identify 返回 completed=True, status=success。

下一步应进入 Phase 3：把 StageRequirements/ArtifactResolver/ContextIndex 扩展到核心传统阶段和亚家族预测阶段，再收口 phylogeny/motif/domain/structure/combo/reference_classification/subfamily_confirm。

15. 2026-05-27 Phase 3 实施进展

已完成解析层扩展，范围限定为 StageRequirements / ArtifactResolver / ContextIndex，仍未改前端弹窗和各阶段 CLI 主输出命名。

修改文件：

gfa_core/mas/context_index.py
gfa_core/mas/artifact_resolver.py
gfa_core/mas/stage_requirements.py

已落地规则：

ContextIndex 不再把 Target.SPL.target-Lc.ref-At.target_plus_reference 误解析为物种 Target、家族 SPL.target-Lc...；role-scope 前缀只用于 scope 身份，species-main 前缀才用于物种/家族身份。
manifest 索引保留 output_prefix / canonical_member_prefix / legacy_output_prefix / analysis_route / result_group / member_set_id / stage_context / target_species / reference_species / comparative_species / selected_species，供后续 agent、诊断和结果展示统一使用。
修正旧 manifest 中 member_set_id 被当作普通前缀导致 species=SPL 的错误。
ArtifactResolver 扩展并收紧语义角色：tree / reference_subfamily / family_members_id / target_gff / gene_subfamily / motif_result / domain_result / structure_result / pfam_database。
reference_subfamily 只接受参考标签输入，例如 At.SPL.subfamily，不再误选目标物种的 reference_classification 预测结果。
domain_result 不再把 identify 阶段的 domain_review.tsv 当成 domain 阶段 combo 面板。
tree 解析会按单目标 scope 优先选择 target-Lc 而不是 target-Dl-Lc 这类联合历史树。
StageRequirements 从 3 个阶段扩展到 9 个阶段：identify / phylogeny / pep / reference_classification / motif / domain / structure / combo / subfamily_confirm。

真实 workspace 只读验证：

workspace/job_1779614808704_edb235
input/job_1779614808704_edb235

验证结果：

Lc reference_classification ready=True -> tree=Lc...target-Lc.ref-At...tree.nwk, reference_subfamily=At.SPL.subfamily
Lc motif/domain/structure/combo/subfamily_confirm ready=True
Os reference_classification ready=True -> tree=Os...target-Os.ref-At...tree.nwk, reference_subfamily=At.SPL.subfamily
Os motif/domain/structure/combo/subfamily_confirm ready=True
Dl reference_classification ready=True -> tree=Dl...target-Dl.ref-At...tree.nwk, reference_subfamily=At.SPL.subfamily
Dl motif/domain/structure/combo/subfamily_confirm ready=True
identify Ppy ready=True -> target_proteome=Ppy.pep.fasta
phylogeny Os ready=True -> target_family_pep=Os.SPL.final_members.pep.fa, reference_family_pep=At.SPL.pep.fa

语法验证：

python -m py_compile gfa_core/mas/context_index.py gfa_core/mas/artifact_resolver.py gfa_core/mas/stage_requirements.py

下一步进入 Phase 4：修订 phylogeny / reference_classification / motif / domain / structure / combo / subfamily_confirm 的 CLI 与 backend 调用层，让用户主输出从历史长 scope 文件名过渡到简洁主文件名，同时保留 legacy 兼容副本和 manifest 里的完整 scope 身份。

16. 2026-05-27 Phase 4 部分实施进展

已开始修订执行层，当前完成 backend manifest/path 预期统一，以及 subfamily_confirm 的确认输出命名修订。尚未重新执行完整真实数据全链路。

修改文件：

apps/web/pipeline_backend.py
apps/cli/run_subfamily_confirm.py

已落地规则：

backend 新增统一 helper：stage_output_prefix()、stage_manifest_candidates()、first_existing_stage_manifest()。
backend 的 scoped phylogeny tree/protein resolver 不再只查 {prefix}.{scope_id} legacy manifest，也会查 user_output_prefix_for() 产生的新短 manifest。
backend 对 phylogeny / reference_classification / motif / domain / structure / combo / subfamily_confirm 的成功判断改为优先识别新短 manifest，并兼容 legacy manifest。
reference_classification 的内部 evidence 子链不再硬编码 species_prefix.scope_id.tree.nwk，而是用统一输出前缀查找 evidence tree。
subfamily_confirm 输出命名改为确认态：Lc.SPL.confirmed_subfamily.tsv、Lc.SPL.confirmed_subfamily.review.tsv、Lc.SPL.confirmed_subfamily.subfamily_confirm.manifest.json。
subfamily_confirm 的输入源查找与输出命名分离：输入优先查 reference_classification 的 subfamily_prediction 前缀，输出使用 confirmed_subfamily 前缀。
subfamily_confirm 写入 analysis_route / result_group / member_set_id / output_prefix / legacy_output_prefix / scope_id / scope_mode / target_species / reference_species，并保留 legacy manifest copy。

验证：

python -m py_compile apps/web/pipeline_backend.py apps/cli/run_subfamily_confirm.py apps/cli/run_phylogeny.py apps/cli/run_reference_classification.py apps/cli/run_motif.py apps/cli/run_domain.py apps/cli/run_structure.py apps/cli/run_combo.py

真实 workspace 只读验证：

workspace/job_1779614808704_edb235/final/Lc.SPL.target_plus_reference.scope.json
workspace/job_1779614808704_edb235/final/Os.SPL.target_plus_reference.scope.json
workspace/job_1779614808704_edb235/final/Dl.SPL.target_plus_reference.scope.json

结果：backend 能为 Lc/Os/Dl 推导新短前缀，例如 Target.SPL.target-Lc.ref-At.subfamily_prediction，同时回退找到历史 legacy phylogeny/reference_classification manifest 和 tree。

隔离真实数据执行验证：

workspace: /tmp/bbav5_phase4_subfamily_confirm_lc2
source:    真实 Lc reference_classification subfamily/assignment 表
command:   python apps/cli/run_subfamily_confirm.py --workspace /tmp/bbav5_phase4_subfamily_confirm_lc2 --input-dir /tmp/bbav5_phase4_subfamily_confirm_lc2/input --prefix Lc.SPL --scope-file /tmp/bbav5_phase4_subfamily_confirm_lc2/final/Lc.SPL.target_plus_reference.scope.json

生成文件：

Lc.SPL.confirmed_subfamily.tsv
Lc.SPL.confirmed_subfamily.review.tsv
Lc.SPL.confirmed_subfamily_report.md
Lc.SPL.confirmed_subfamily.subfamily_confirm.manifest.json
Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.subfamily_confirm.manifest.json

关键 manifest 字段：

prefix = Lc.SPL
output_prefix = Lc.SPL.confirmed_subfamily
legacy_output_prefix = Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference
analysis_route = confirmed_subfamily
result_group = gene_family_subfamily_confirm
scope_id = SPL.target-Lc.ref-At.target_plus_reference
scope_mode = target_plus_reference
confirmed artifact = final/Lc.SPL.confirmed_subfamily.tsv

下一步：继续 Phase 4，执行真实小链路 phylogeny -> reference_classification -> motif/domain/structure -> combo 的隔离验证，重点确认新短主文件和 legacy manifest 同时存在，且 backend 返回的 manifest 与结果展示一致。

17. 2026-05-27 Phase 4 隔离真实小链路验证

已完成一条真实 Lc + At 的隔离执行链验证，workspace 为：

workspace/job_phase4_lc_chain
input/job_phase4_lc_chain

输入来源：

Lc 成员蛋白/ID：workspace/job_1779614808704_edb235/final/Target.Lc.SPL.final_members.*
At 参考蛋白：input/job_1779614808704_edb235/At.SPL.pep.fa
At 亚家族标签：input/job_1779614808704_edb235/At.SPL.subfamily
Lc/At target_plus_reference scope：workspace/job_1779614808704_edb235/final/Lc.SPL.target_plus_reference.scope.json

执行链：

phylogeny -> reference_classification -> subfamily_confirm -> motif -> domain -> structure -> combo

执行环境：

phylogeny 首次用当前 shell Python 跑通，但提示缺 Bio 仅影响 tree tip 计数；后续阶段使用 /home/xia-lab/miniconda3/envs/test4py311/bin/python。
phylogeny 为节省验证时间使用轻量 IQ-TREE 参数 -m JTT -nt 2，不是正式默认 MFP + bootstrap 参数；本次验证目标是命名和调用链，不替代最终生物学参数验证。

验证通过的主输出命名：

Target.SPL.target-Lc.ref-At.subfamily_prediction.phylogeny.manifest.json
Target.SPL.target-Lc.ref-At.subfamily_prediction.tree.nwk
Target.SPL.target-Lc.ref-At.subfamily_prediction.reference_classification.manifest.json
Target.SPL.target-Lc.ref-At.subfamily_prediction.reference_classification.subfamily.tsv
Target.SPL.target-Lc.ref-At.subfamily_prediction.reference_classification.tree.png
Lc.SPL.confirmed_subfamily.subfamily_confirm.manifest.json
Lc.SPL.confirmed_subfamily.tsv
Target.SPL.target-Lc.ref-At.subfamily_prediction.motif.manifest.json
Target.SPL.target-Lc.ref-At.subfamily_prediction.motif.png
Target.SPL.target-Lc.ref-At.subfamily_prediction.domain.manifest.json
Target.SPL.target-Lc.ref-At.subfamily_prediction.domain.png
Target.SPL.target-Lc.ref-At.subfamily_prediction.structure.manifest.json
Target.SPL.target-Lc.ref-At.subfamily_prediction.structure.png
Target.SPL.target-Lc.ref-At.subfamily_prediction.combo.manifest.json
Target.SPL.target-Lc.ref-At.subfamily_prediction.combo.pdf

同时确认每个核心阶段均保留 legacy manifest：

Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.phylogeny.manifest.json
Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.reference_classification.manifest.json
Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.subfamily_confirm.manifest.json
Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.motif.manifest.json
Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.domain.manifest.json
Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.structure.manifest.json
Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.combo.manifest.json

本轮验证中发现并已修正的问题：

reference_classification 的 per-species tree plot 仍使用旧主前缀 Lc.SPL.target_plus_reference.reference_classification.tree.*；已改为使用 Target.SPL.target-Lc.ref-At.subfamily_prediction.reference_classification.tree.*。
subfamily_confirm 初始输出出现 confirmed_subfamily.confirmed_subfamily.tsv 重复后缀；已改为 Lc.SPL.confirmed_subfamily.tsv。
subfamily_confirm 输入源与输出前缀不能共用同一 prefix；已分离为输入查 subfamily_prediction，输出写 confirmed_subfamily。

仍需继续的工作：

前端弹窗和结果展示层尚未完成统一：需要让 UI 显示阶段名、执行范围、参考物种说明、结果文件名与当前命名一致。
backend 真实 API 执行还未通过浏览器/前端触发验证；目前是 CLI 隔离链路验证。
传统 target_only 输出还需做同样的隔离执行验证，确认 Lc.SPL.structure.png 这类传统命名不受亚家族支线影响。

18. 2026-05-27 Phase 5 传统 target_only 隔离验证

已完成一条真实 Lc 传统单物种 target_only 执行链验证，workspace 为：

workspace/job_phase5_lc_target_only
input/job_phase5_lc_target_only

输入来源：

Lc 成员蛋白/ID：workspace/job_1779614808704_edb235/final/Target.Lc.SPL.final_members.*
Lc GFF3：input/job_1779614808704_edb235/Lc_final.gff3
识别 manifest：沿用真实 job 的 identify manifest，但 CLI 已修正为优先使用当前 workspace 内的单物种成员文件，避免被旧 manifest 中的历史绝对路径带偏。

执行链：

phylogeny -> motif -> domain -> structure -> combo

验证通过的传统主输出命名：

Lc.SPL.tree.nwk
Lc.SPL.phylogeny.manifest.json
Lc.SPL.motif.png
Lc.SPL.motif.manifest.json
Lc.SPL.domain.png
Lc.SPL.domain.manifest.json
Lc.SPL.structure.png
Lc.SPL.structure.manifest.json
Lc.SPL.combo.pdf
Lc.SPL.combo.manifest.json

关键 manifest 验证结果：

phylogeny output_prefix/prefix = Lc.SPL, stage = phylogeny, status = success
motif     output_prefix/prefix = Lc.SPL, stage = motif,     status = success
domain    output_prefix/prefix = Lc.SPL, stage = domain,    status = success
structure output_prefix/prefix = Lc.SPL, stage = structure, status = success
combo     output_prefix/prefix = Lc.SPL, stage = combo,     status = success

本轮验证中发现并已修正的问题：

run_motif.py 传统无 scope 分支只查 Lc.SPL.final_members.pep.fa，无法兼容 identify 历史输出 Target.Lc.SPL.final_members.pep.fa；已加入单物种 legacy fallback。
run_motif.py 读取 gene id 时同样缺少 Target.Lc.SPL.final_members.id fallback；已修正。
run_domain.py 传统无 scope 分支存在 candidates 未初始化风险；已修正。
run_domain.py 读取 identify manifest 时曾优先使用旧 manifest 中的历史 absolute path，导致 Lc 传统验证误读 51 条 aggregate 蛋白；已改为优先当前 workspace 的 Lc.SPL.final_members.pep.fa / Target.Lc.SPL.final_members.pep.fa，manifest artifact 只作为后备。
run_structure.py 传统无 scope 分支读取 gene id 时已补充 Target.Lc.SPL.final_members.id fallback。

真实数据验证结果：

domain protein file = workspace/job_phase5_lc_target_only/final/Target.Lc.SPL.final_members.pep.fa
domain proteins_total = 17
structure genes_total = 17
combo generated = workspace/job_phase5_lc_target_only/final/Lc.SPL.combo.pdf

结论：

传统单物种确认成员后的基因家族分析可以保持清爽命名：Lc.SPL.*。
亚家族预测支线使用区分场景的命名：Target.SPL.target-Lc.ref-At.subfamily_prediction.*。
亚家族确认最终表使用确认态命名：Lc.SPL.confirmed_subfamily.*。
当前阶段不需要把传统 target_only 文件名也改成长 scope 名；scope 身份应留在 manifest/stage_context 中，而不是强行拼进用户主输出文件名。

19. 2026-05-27 Phase 5 前端弹窗与 Ppy 规划修订

已完成第一批前端弹窗和后端规划修订。

前端弹窗修订：

批量确认弹窗标题统一为 批量执行确认。
批量确认弹窗保留本次分析范围选择，作为执行前唯一主要可编辑入口。
批量执行后的单阶段确认弹窗不再重复显示可编辑物种勾选区；改为只读展示 Family / Scope / 目标物种 / 参考物种 / 比较物种 和本阶段输出命名说明。
Identify 物种选择拆分为 Target 角色物种 和 Comparative 角色物种 两组，Reference 继续只显示为参考，不进入鉴定目标。
弹窗输出命名提示改成按阶段展示用户可理解的文件名模式，例如：
- identify：Ppy.SPL.final_members.*
- reference_classification：Target.SPL.target-Ppy.ref-At.subfamily_prediction.*
- subfamily_confirm：Ppy.SPL.confirmed_subfamily.*
- 传统分析：Ppy.SPL.structure.* / Ppy.SPL.motif.* 等。

后端规划修订：

修正 PPy/Ppy 被解析为 Py 的问题，物种代码映射已加入 Ppy，且优先于短码 Py 匹配。
_load_identify_species_selection() 增加标准化蛋白文件 fallback：即使 config.xlsx 中 Ppy 只记录 genome/GFF，只要 input/{job_id}/Ppy.pep.fasta 存在，就把 Ppy 识别为可鉴定 comparative 物种。
亚家族预测请求中，如果存在 reference 物种，则 reference_classification / phylogeny / motif / domain / structure / combo 的 scope 强制保持 target_plus_reference，避免从“只提到一个物种”的自然语言中继承错误的 target_only。
identify 阶段仍保持 target_only，并且不把 reference 写入 identify 的目标鉴定 scope。

API 验证：

POST /api/agent/plan
message = 帮我执行PPy的亚家族分类分析
job_id = job_1779614808704_edb235
prefix = Ppy.SPL

验证结果：

plan species = Ppy
target_species = [Ppy]
reference_species = [At]
plan scopeMode = target_plus_reference
identify targetSpecies = [Ppy]
identify referenceSpecies = []
identify scopeMode = target_only
identify output_prefix = Ppy.SPL
reference_classification targetSpecies = [Ppy]
reference_classification referenceSpecies = [At]
reference_classification scopeMode = target_plus_reference
reference_classification output_prefix = Target.SPL.target-Ppy.ref-At.subfamily_prediction

静态前端验证：

curl http://127.0.0.1:7880/ | rg "批量执行确认|Identify 本阶段鉴定物种|本阶段使用范围|亚家族预测输出"

已确认当前 7880 服务加载了新前端文本，并已重启到 PID 350323。

20. 2026-05-27 Phase 5 真实前端请求链补丁

用户前端复测报错：

帮我执行PPy的亚家族分类分析
无法执行分析：缺少 identify 所需输入: target_proteome (protein_fasta); 缺少 reference_classification 所需输入: reference_subfamily (table)

实际原因不是文件缺失，而是前端真实链路和单独 /api/agent/plan 验证不同：

/api/agent/chat -> 返回 intent: targetSpecies=[Ppy], referenceSpecies=[], scopeMode=target_only
/api/agent/plan -> 带着这个旧 intent 进入 PlanningAgentV2
PlanningAgentV2 在确定性补丁运行前先做预检，因 referenceSpecies 为空报缺 reference_subfamily

已修复：

/api/agent/plan 在进入 PlanningAgentV2 之前，对“亚家族分类/预测 + 前端传入 intent”的请求做确定性归一化。
如果用户明确提到 Ppy/PPy，固定目标为 Ppy，不会回退到 config 默认 Target 物种。
如果请求是亚家族预测，自动补入 config 中的 reference 物种 At，并把非 identify 阶段 scope 设置为 target_plus_reference。
新增 deterministic_subfamily_from_intent 分支，直接生成：identify -> phylogeny -> reference_classification，避免 PlanningAgentV2 在旧 intent 上提前失败。
identify 阶段仍保持 target_only，输出 Ppy.SPL；phylogeny/reference_classification 使用 Target.SPL.target-Ppy.ref-At.subfamily_prediction。

真实前端请求链验证：

chat_intent ['Ppy'] [] target_only
plan_success True deterministic_subfamily_from_intent
plan_scope ['identify', 'phylogeny', 'reference_classification'] ['Ppy'] ['At'] target_plus_reference
identify ['Ppy'] [] target_only Ppy.SPL
phylogeny ['Ppy'] ['At'] target_plus_reference Target.SPL.target-Ppy.ref-At.subfamily_prediction
reference_classification ['Ppy'] ['At'] target_plus_reference Target.SPL.target-Ppy.ref-At.subfamily_prediction
identify_ready True
ref_subfamily /home/xia-lab/wutx/00test/bbav5_0502_Yang_Tihuan.7880/input/job_1779614808704_edb235/At.SPL.subfamily

服务状态：已重启 7880 web 服务并加载该补丁。

21. 2026-05-27 Phase 5 Lc 前端执行失败根因与兜底修复

用户前端复测：

帮我执行Lc 的亚家族分类分析
Identify 运行失败: IndexError: list index out of range
log = workspace/job_1779806881787_16006d/logs/20260527_133821_identify.log

根因确认：

这不是 Lc 蛋白文件缺失。
前端执行阶段生成的 identify scope 文件为空目标物种：
- scope_id = SPL.target_only
- target_species = []
- reference_species = []
- comparative_species = []
run_identify.py 收到空 target scope 后，退回到扫描整个 input 目录。
扫描过程中把 Cp 的 genome-like FASTA 也当作待鉴定蛋白输入处理，遇到空 FASTA header 后在 header[1:].strip().split()[0] 处触发 IndexError。
诊断面板显示 manifest_missing_stage_incomplete 是结果现象，不是主因；阶段已经因 traceback 崩溃，所以此时优先恢复 manifest 会误导用户。

已修复：

apps/web/vue3/main.py
- _ensure_gene_family_scope_file() 增加 prefix 兜底。
- 如果 targetSpecies 为空但 prefix 是 Lc.SPL 这种单物种前缀，则自动回填 targetSpecies = [Lc]。
- 生成 scope 文件时不再产生 SPL.target_only 这种缺少物种身份的 identify scope。
apps/cli/run_identify.py
- identify CLI 增加第二层兜底：如果命令行和 scope 都没有目标物种，但 prefix 是 Lc.SPL，则从 prefix 推断目标物种 Lc。
- prepare_fasta_for_hmmsearch() 增加空 FASTA header 防护，避免以后异常输入直接触发 IndexError。

真实数据验证：

输入 job: job_1779806881787_16006d
复测命令: 使用失败 job 的旧空 scope 文件重新运行 run_identify.py
结果: success
输出目录: /tmp/bbav5_lc_identify_scope_fallback_20260527/final

关键输出：

Lc.SPL.final_members.pep.fa
Lc.SPL.final_members.id
Lc.SPL.identify.manifest.json
Lc.SPL.SPL.target_only.identify.manifest.json

manifest 核心字段：

status = success
stage = identify
prefix = Lc.SPL
output_prefix = Lc.SPL
target_species = [Lchinesis_genome]

前端真实请求链验证：

message = 帮我执行Lc 的亚家族分类分析
job_id = job_1779806881787_16006d

chat_intent = targetSpecies [Lc], referenceSpecies [], scopeMode target_only, prefix Lc.SPL
plan_mode = deterministic_subfamily_from_intent
plan_stages = identify -> phylogeny -> reference_classification
plan_target = [Lc]
plan_reference = [At]
plan_scopeMode = target_plus_reference

identify scope_id = SPL.target-Lc.target_only
phylogeny scope_id = SPL.target-Lc.ref-At.target_plus_reference
reference_classification scope_id = SPL.target-Lc.ref-At.target_plus_reference

服务状态：

7880 web service restarted
current pid = 377069

后续诊断待修：

gfa_core/mas/agents/diagnosis.py 应补充 traceback 优先级：
- 如果日志中存在 Python traceback / IndexError / scope target 为空，应优先报告真实崩溃原因。
- manifest_missing_stage_incomplete 只能作为附带现象，不应成为主问题。

22. 2026-05-27 Phase 5 批量确认弹窗增加本次待分析对象

修订目的：

不新增后端 scope mode。
保留项目配置中的 Target / Reference / Comparative 角色。
前端允许用户在执行前明确选择“本次待分析对象”：仅目标物种、仅比较物种、目标+比较物种。
当用户选择“仅比较物种”时，Comparative 角色物种只在本次执行中转为 targetSpecies，不修改其配置角色。

已修复：

apps/web/vue3/index.html
- 批量执行确认弹窗的 Identify 区域新增“本次待分析对象”单选控件：
  - 仅目标物种
  - 仅比较物种
  - 目标+比较物种
- Target / Comparative 物种勾选区改为“可作为本次待分析物种”，避免让用户误以为在修改项目配置角色。
- 新增 setIdentifyExecutionSource()：根据用户选择批量勾选 Target 或 Comparative 角色物种。
- 新增 normalizeBatchExecutionSpeciesForStages()：开始批量执行前，把弹窗中的本次待分析物种同步回所有基因家族阶段的 stage.params.targetSpecies。
- identify 阶段继续使用 target_only，reference 不参与目标鉴定。
- phylogeny / reference_classification 等下游阶段使用同一批本次待分析物种；如果存在 reference，则保持 target_plus_reference。

验证：

node --check /tmp/bbav5_index_inline.js = pass
curl http://127.0.0.1:7880/ | rg "本次待分析对象|仅比较物种|目标\+比较物种" = pass

设计结论：

不采用“仅比较物种”作为新的 scope mode。
“仅比较物种”只作为前端执行对象选择，最终仍映射到本次运行的 targetSpecies。
这样既解决用户从 Comparative 物种发起亚家族分类时的选择歧义，也不破坏现有 scope / manifest / stage identity 体系。

23. 2026-05-27 Phase 5 前端复测问题二次修订

用户前端复测发现：

Lc 亚家族分类链路中，identify 阶段 InterProScan 域检查失败，导致默认成员确认表不能生成，下游直接使用 72 个 HMM/BLAST 候选成员。
Ppy/PPy 请求中，规划文本识别到 Ppy，但当前 job 的 config 真实物种代码是 PPY，导致批量弹窗的 Target/Comparative 分组与自动勾选不匹配。
Ppy identify 预检插入 genome_prepare 后，前端没有把当前 identify 阶段显式依赖到新插入的 genome_prepare，因此 genome_prepare 仍在运行时 identify 被再次提交，造成“数据准备弹窗/提交两次”和下游跳过。

已修复：

apps/web/vue3/main.py
- 新增 _canonicalize_species_codes_for_job()。
- /api/agent/plan 中亚家族预测确定性分支会把用户输入的 Ppy/PPy 映射为 config 中真实代码 PPY。
- deterministic subfamily plan 现在返回 identifySpeciesSelection，前端批量确认弹窗可显示 Target / Comparative 分组。
apps/web/vue3/index.html
- addSuggestedPreflightStagesToBatch() 插入上游阶段后，会把当前阶段 dependencies 更新为包含新插入阶段。
- 这样 identify 因缺少 target proteome 而插入 genome_prepare 后，必须等 genome_prepare 完成才会重新提交 identify。
apps/cli/run_identify.py
- sanitize_fasta_for_interproscan() 不再只移除 *，同时移除 . 等非氨基酸残基。
- InterProScan clean input 统计增加 written_sequences 和 removed_invalid_residues。

验证：

python -m py_compile apps/web/vue3/main.py apps/cli/run_identify.py = pass
node --check /tmp/bbav5_index_inline.js = pass

Ppy 计划 API 验证：

message = 帮我执行PPy的亚家族分类分析
job_id = job_1779806881787_16006d
plan_mode = deterministic_subfamily_from_intent
plan_target = [PPY]
plan_reference = [At]
prefix = PPY.SPL
identify scope_id = SPL.target-PPY.target_only
phylogeny scope_id = SPL.target-PPY.ref-At.target_plus_reference
reference_classification scope_id = SPL.target-PPY.ref-At.target_plus_reference
comparative_group includes PPY with validProteinFiles = [PPY.pep.fasta]
semantic_preflight identify PPY.SPL = valid True

Lc InterProScan 真实数据验证：

input = workspace/job_1779806881787_16006d/final/Lc.SPL.final_members.pep.fa
sequences = 72
written_sequences = 72
removed_invalid_residues = 70
InterProScan status = success
InterProScan rows = 81
proteins_with_hits = 64
default_keep_count = 48

结论：

Lc 之前“鉴定多少用多少”的直接原因是 InterProScan clean input 没有移除 .，导致域检查失败，默认成员集无法生成。
修复后同一批 Lc 72 个候选可生成 domain review，默认保留 48 个含目标域成员。后续重新跑 identify 时将基于默认域确认重建 final_members，而不是直接透传 72 个候选。
Ppy 前端应显示 PPY 为比较物种，并默认能够作为本次待分析物种进入执行链。

78 KiB Executable File Raw Permalink Blame History Unescape Escape

基因家族阶段统一命名完整修订方案

1. 本方案要解决的问题

2. 总体判定

2.1 scope 是否保留

2.2 identify 的语义

3. 当前代码链路审计结论

3.1 从用户请求到执行的链路

3.2 完整关联面

3.2.1 MAS 多 Agent 与编排层

3.2.2 语义索引、能力表、artifact resolver

3.2.3 契约和 schema 层

3.2.4 Project skills 层

3.2.5 复现与 provenance 层

3.2.6 诊断、自动修复和失败恢复

3.2.7 深度解读、报告和前端解释层

3.2.8 记忆、RAG、成本和会话层

3.2.9 旁路入口、辅助 CLI、测试和历史资产

3.3 已确认的关键代码点

4. 统一概念模型

4.1 三类前缀必须分清

4.2 manifest 承担完整身份

5. 分析场景分类与命名规则

5.1 单物种成员确认 identify

5.2 单物种传统基因家族分析

5.3 多目标物种传统分析

5.4 目标加参考的亚家族预测

5.5 亚家族证据图

5.6 亚家族确认后传统分析

5.7 目标加比较物种分析

5.8 两两或跨物种阶段

6. 阶段级修订表

7. 需要同步修订的代码模块

7.1 gfa_core/gene_family_stage_context.py

7.2 gfa_core/mas/tools/stage_identity.py

7.3 gfa_core/mas/stage_requirements.py

7.4 gfa_core/mas/agents/planning_v2.py

7.5 apps/web/vue3/main.py

7.6 apps/web/pipeline_backend.py

7.7 CLI 阶段脚本

7.8 stage_status.py

7.9 result_parser.py 与结果 API

8. 弹窗设计修订原则

8.1 第一个规划弹窗

8.2 第二个执行确认弹窗

9. 分阶段实施计划

Phase 0：冻结规则文档

Phase 1：核心命名 helper 与测试

Phase 2：identify 主产物迁移

Phase 3：StageRequirements 全阶段化

Phase 4：PlanningAgentV2 与 web plan 收口

Phase 5：pipeline_backend 执行链路收口

Phase 6：CLI 第二批阶段迁移

Phase 7：契约、schema、能力表同步

Phase 8：结果展示、诊断和自动修复收口

Phase 9：Project skills 和复现系统同步

Phase 10：深度解读、知识、记忆和编排层同步

Phase 11：旁路入口、辅助脚本、前端静态和测试体系收口

Phase 12：真实数据验证与兼容清理

10. 真实数据验证矩阵

11. 风险和取舍

11.1 是否在文件名中写 Comparative

11.2 是否立刻删除旧命名

11.3 reference species 是否要勾选

12. 验收标准

13. 推荐执行顺序

14. 2026-05-27 Phase 1/2 实施进展

15. 2026-05-27 Phase 3 实施进展

16. 2026-05-27 Phase 4 部分实施进展

17. 2026-05-27 Phase 4 隔离真实小链路验证

18. 2026-05-27 Phase 5 传统 target_only 隔离验证

19. 2026-05-27 Phase 5 前端弹窗与 Ppy 规划修订

20. 2026-05-27 Phase 5 真实前端请求链补丁

21. 2026-05-27 Phase 5 Lc 前端执行失败根因与兜底修复

22. 2026-05-27 Phase 5 批量确认弹窗增加本次待分析对象

23. 2026-05-27 Phase 5 前端复测问题二次修订

78 KiB

Executable File

Raw Permalink Blame History

7.1 `gfa_core/gene_family_stage_context.py`

7.2 `gfa_core/mas/tools/stage_identity.py`

7.3 `gfa_core/mas/stage_requirements.py`

7.4 `gfa_core/mas/agents/planning_v2.py`

7.5 `apps/web/vue3/main.py`

7.6 `apps/web/pipeline_backend.py`

7.8 `stage_status.py`

7.9 `result_parser.py` 与结果 API