PlantAI-dev/docs/gene_family_unified_rules_summary_2026-05-26.md

Gene-Family Unified Rules Summary - 2026-05-26

本文记录 2026-05-26 对 bbav5 gene-family / RNA-seq 交叉入口的统一修订原则。重点是避免同一业务规则散落在多个入口中，后续修订必须优先复用统一规则层，不能在前端或 load_from_path 中再写第二套判断。

1. 自动填表只保留一条规则来源

config.xlsx

config.xlsx 是基因家族/基因组资源配置表，唯一识别规则入口是：

• apps/cli/run_config_autofill.py

职责：

• 扫描 genome / gff / cds / pep / hmm / Excel 等基因家族资源。
• 推断 Species_Code、File_Type、Gene_Family、Ref、Species_Role、File_Scope。
• 识别 known-family seed 文件，例如 At.SPL.pep.fa 必须填成：
  • Species_Code=At
  • Gene_Family=SPL
  • File_Type=pep
  • Ref=TRUE
  • Species_Role=seed_reference
  • File_Scope=known_family

禁止事项：

• 不允许在 /api/load_from_path 里再手写一套 Species/File_Type/Gene_Family/Role/Scope 推断。
• 不允许前端根据文件名直接推断 config 行内容。

当前后端规则：

• /api/load_from_path 只负责把路径中的文件复制/软链接到当前 job input。
• 发现基因家族资源后，统一调用 run_config_autofill.py 的 build_rows / merge_rows / write_workbook / write_report 生成草稿。
• 纯上传已有 config.xlsx 时只规范化为正式配置，不额外弹草稿；如果同目录还有 pep/gff/cds/genome/hmm，则仍生成草稿以纳入新增资源。

samples.yaml

samples.yaml 是 RNA-seq FASTQ 样本分组表，唯一识别规则入口是：

• apps/cli/run_samples_autofill.py

职责：

• 只处理 .fastq/.fq/.fastq.gz/.fq.gz 或已有 samples.yaml/samples.yml。
• 通过 build_samples() 配对 R1/R2，生成 sample_id / fastq_1 / fastq_2 / condition / replicate / control_group 等行。
• 没有 FASTQ 或没有解析出真实 rows 时，不能生成有效 samples 草稿。

禁止事项：

• 基因组/GFF/CDS/PEP 目录不能弹 Auto-fill samples.yaml。
• 不能把 {} 这种空对象当成有效 samples 草稿。

当前前端分流规则：

• 必须用 draft.rows.length > 0 判断草稿是否有效。
• samples_draft_created=true 但没有 rows，不能打开 samples 弹窗。
• config_draft_created=true 且有 rows，才打开 config 弹窗。

2. 前端弹窗必须允许人工补救

自动识别可能漏行或低置信，因此 config/samples 两个弹窗都必须提供：

• 添加行
• 每行 删除
• 表格内直接编辑字段

这不是 UI 装饰，而是数据质量闭环。用户发现漏识别时，必须能在确认写入正式 config.xlsx 或 samples.yaml 前补充。

3. 明确物种选择优先于默认/最近上下文

今天发现：用户说“做 Os 和 Cp 的亚家族分类确认”，规划中 targetSpecies 已经是 ['Os', 'Cp']，但 identifySpeciesSelection.defaultSelected 仍沿用 config 默认 target 或最近上下文，导致弹窗出现 Lc。

统一规则：

• 自然语言明确点名物种时，该物种列表优先级最高。
• 后端不仅要设置 targetSpecies，还要同步 identifySpeciesSelection.defaultSelected。
• 不允许默认 target、最近确认物种、历史 scope 覆盖显式请求。

当前修订点：

• /api/agent/plan 在存在显式物种时，将 identifySpeciesSelection.defaultSelected 同步为显式物种。
• 验证案例：做Os和Cp的亚家族分类确认 返回：
  • targetSpecies=['Os', 'Cp']
  • defaultSelected=['Os', 'Cp']

4. stage requirements / artifact resolver 的统一方向

后续阶段依赖不能继续散落在执行代码里临时补丁。当前方向是：

• PlanningAgentV2 调统一 requirements resolver 判断是否需要补上游。
• pipeline_backend.py 和 CLI 只做最后 contract check 与实际执行。
• 阶段特殊规则保留，但应作为数据化能力/需求进入 resolver，而不是散落到各个提交入口。

已开始的统一文件：

• gfa_core/mas/stage_requirements.py
• gfa_core/mas/artifact_resolver.py

当前 Phase 1 是 shadow resolver，不改变执行行为，用于验证 phylogeny/pep 等阶段需求解析。

5. structure 长基因显示问题的统一处理

用户反馈 Cp evm.model.supercontig_149.10 structure 很长。真实检查结果：

• GFF 坐标：245685-247462
• 跨度约 1,778 bp
• 3 个 CDS
• 在 Cp/At structure 数据中不属于最长前 10，也不是 outlier。

判断：

• 当前证据不支持“注释错误”。
• 图上显长更可能是正常内含子间隔相对紧凑基因更明显。

已统一到 CLI QC：

• apps/cli/run_structure.py
• report/manifest 增加 Structure Length QC：
  • 平均/中位/最大结构长度
  • long-gene outlier 阈值
  • 最长 10 个 gene structure
  • 超阈值时提示检查 GFF3
  • 未超阈值时提示视觉较长多为真实内含子间隔

验证案例：

• Cp/At structure 数据中位数约 3,130 bp
• 最大约 5,731 bp
• outlier 阈值约 15,650 bp
• outlier 数量 0

6. 后续修订检查清单

后续任何涉及自动填表、scope、stage 依赖、物种选择的修订，必须先回答：

1. 这条规则是否已经有唯一来源？
2. 是否在前端、load_from_path、CLI、PlanningAgent 中重复写了第二套规则？
3. 如果用户自然语言显式指定物种/家族，是否覆盖默认上下文？
4. 弹窗展示的默认选择是否和计划参数一致？
5. 空对象、空 rows、旧草稿是否会被误判为有效草稿？
6. 是否用真实 job/API 做过验证，而不是只看语法？

7. 本次关键验证

已验证的真实场景：

• 单个 At.SPL.pep.fa 上传后生成 config 草稿，识别为 seed_reference / known_family。
• 完整基因组资源目录只生成 config 草稿，不弹 samples。
• FASTQ 目录只生成 samples 草稿，不生成 config。
• “做 Os 和 Cp 的亚家族分类确认”规划中 targetSpecies 与 defaultSelected 均为 ['Os', 'Cp']。
• Cp evm.model.supercontig_149.10 的 structure 长度不是 outlier。

8. 维护原则

一句话原则：

路径加载只搬运，CLI/autofill 只识别，PlanningAgent 只规划，执行层只校验和执行，前端只展示和收集用户确认。

不要再把识别规则、规划规则、执行规则混写在同一个入口里。