PlantAI-dev/.planning/ppi_kaks_enablement_20260808/plan.md

PPI/KaKs 最小可用修订计划（Karpathy 审核版）

唯一目标

让正常家族分析中的 PPI 和 KaKs 能从前端真实提交并完成；任一阶段失败时，后续无关阶段仍继续调度。

明确假设

1. 本轮生产环境是 5090；现有 /home/xzq KaKs 工具路径在该环境可用，因此不处理可移植性。
2. KaKs 的 scope + Ortholog + run_kaks_v2.py 路径已经有 Os→At 17/17 成功证据，除非标准前端请求没有进入这条路径，否则不改 KaKs 后端或算法。
3. 当前必须支持用户实际失败的 Gm/TCP PPI；Gm ID 映射只能使用 STRING 官方接口/别名证据，不接受字符串猜测。
4. “不阻塞后续”只指调度隔离，不要求本轮重构诊断、Manifest 或状态体系。

最终验收标准

1. Gm/TCP 的 56 个真实 ID 能完成 PPI，而不是 0/56。
2. Os→At PEBP KaKs 仍完成 17/17 pairs。
3. 前端手动与批量执行都会向 /api/execute 提交 PPI/KaKs，不再标记临时 paused。
4. ppiSpecies 不再改变 motif 等无关阶段的 biological scope。
5. 分别模拟 PPI 和 KaKs 执行失败，后续无关阶段仍被提交。

第 0 步：只读确认两个执行前提

PPI 映射前提

• 用现有 Gm/TCP 56 个 ID 调用当前 STRING 官方映射入口/检查官方 alias 数据。
• 记录原始 ID、提交 ID、STRING ID 和来源。
• 只有确认一条可重复的官方映射路径后才写代码；如果 STRING 官方证据不能映射这些 ID，停止实施并报告数据前提，不制造启发式规则。

KaKs 路由前提

• 从正常前端请求体追到 /api/execute 和 pipeline_backend.py，确认是否携带 scope、reference species 和 Ortholog mapping。
• 若已进入现有成功 scope 路径，KaKs 代码零修改。
• 若只缺一个现有参数，只修该参数传递点；不改 CLI 和分析方法。

第 1 步：修复 PPI scope 污染

必要修改

• gfa_core/mas/agents/planning_v2.py
  • 移除把 ppiSpecies 写入共享 referenceSpecies/refSpeciesList/scopeMode 的逻辑。
  • 保留 PPI stage 自己的 ppiSpecies 参数。
  • 不改主 Agent、IntentAgent、其他 stage 规划和 scope 生成。

验证

• 回归用例：target=Gm、scopeMode=target_only、ppiSpecies=gma、stages=motif,ppi。
• motif 保持 target-only；PPI 收到 ppiSpecies=gma。
• 只增加这一条回归测试，并运行相关现有规划测试。

第 2 步：接入已证实的 Gm→STRING 映射

必要修改

• 优先只改 apps/web/pipeline_backend.py，在现有 PPI 命令构造点把第 0 步确认的映射证据传给现有 resolver。
• 只有现有 resolver 无法读取该证据格式时，才最小修改 gfa_core/ppi_string_policy.py。
• 不新增通用映射框架，不扩展其他物种，不做 ID 猜测规则。

验证

• 完整运行 job_1785919737565_421af1 的 56 个 Gm/TCP ID。
• 验证映射数不再是 0/56、PPI stage 成功且产生网络产物。
• 回归 Sv/HKL 已成功路线，防止破坏现有 projected PPI。

第 3 步：解除熔断并验证调度隔离

必要修改

• apps/web/vue3/index.html
  • 将 PPI/KaKs 临时熔断关闭；优先采用最小开关变更，不删除现有辅助代码。
  • 不在前端补规划，不改变阶段列表或下游 Agent。
• KaKs 仅在第 0 步确认标准请求参数丢失时，修改那个唯一传递点。
• 如果现有“单阶段失败后继续循环”逻辑已经通过测试，不修改调度实现。

验证

• 手动执行 PPI、KaKs：确认真实 /api/execute 请求。
• 批量正常场景：Gm PPI 和 Os→At KaKs 分别通过真实数据完成。
• 前端调度回归：分别让 PPI、KaKs 的执行请求失败，断言下一无关阶段仍被提交；若现有代码已满足，只保留测试、不改实现。
• 最后检查相关单测、业务 diff，并重启 9010 后用实际 API 再验证一次。

本轮明确不做

• 不修 PPI Reset 自然语言入口。
• 不改失败 Manifest 合并、DiagnosisAgent 或通用状态体系；它们不阻止阶段执行和后续调度。
• 不实现 KaKs placeholder skill。
• 不统一 /home/xzq 路径，不做跨机器可移植性重构。
• 不修改 KaKs 算法、模型、图表、方法文档或 legacy 路径。
• 不扩展更多 STRING 物种映射。
• 不重构主 Agent、IntentAgent、下游 Agent 或前端规划。
• 不清理无关技术债。

顺序约束

必须按 0 → 1 → 2 → 3 执行。只有 PPI scope 和 Gm 映射都通过真实数据后才关闭前端熔断。