diff --git a/docs/superpowers/specs/2026-08-07-main-agent-analysis-handoff-boundary-design.md b/docs/superpowers/specs/2026-08-07-main-agent-analysis-handoff-boundary-design.md new file mode 100644 index 000000000..3571cf7a5 --- /dev/null +++ b/docs/superpowers/specs/2026-08-07-main-agent-analysis-handoff-boundary-design.md @@ -0,0 +1,47 @@ +# Main Agent 分析请求传话边界设计 + +## 目标 + +主 Agent 收到分析相关请求后,只负责识别其属于新分析请求,并把用户原始请求及已确认上下文交给现有 IntentAgent。主 Agent 和前端不得选择工作流、分析模式或分析阶段;阶段识别、依赖展开和规划继续由现有下游 Agent 与分析链负责。 + +## 当前问题 + +`gfa_core/mas/agents/router_runtime.py` 的路由提示明确要求:未指定 RNA-seq 模式时,主 Agent 询问全基因组或基因家族成员模式。`RouterRuntime.run()` 又会在 `clarification_question` 非空时提前返回,导致原始请求没有进入 IntentAgent。用户回答模式后,新 proposal 以该模式回答作为请求,原始“执行 rnaseq”动作丢失。 + +同一文件还根据 RNA-seq 文本选择 `rnaseq_whole_genome` 或 `rnaseq_family_member`,并把 `workflow_id` 带入 proposal 和下游上下文。这超出了主 Agent 的传话职责。 + +## 设计 + +采用提示约束和确定性边界保护两层方案: + +1. 路由提示不再要求主 Agent 询问 RNA-seq 模式,改为明确规定:一旦判断为 `new_analysis`,不得询问分析模式、选择工作流或选择阶段,必须请求 `analysis_intent`。 +2. 在 `RouterRuntime` 中用一个窄范围规范化函数处理所有 `new_analysis` 决策:保留用户请求、subject、交互类型和 execution/guidance 语义;强制 `needs=["analysis_intent"]`、`workflow_id=None`、`clarification_question=None`。 +3. 删除 RNA-seq 专属的主 Agent 模式强制分支。显式写出的“全基因组”或“基因家族成员”仍作为用户原文传给下游,不由主 Agent解释。 +4. 保留现有 proposal 确认机制。确认消息只能重复原始请求并说明将交给现有分析系统,不得提出科学模式或阶段选择问题。 +5. 对历史 pending proposal 也应用相同边界,避免确认旧 proposal 时继续把 `workflow_id` 注入下游;不迁移、不重写已保存的历史文本。 + +## 不在本次范围 + +- 不修改前端。 +- 不修改 IntentAgent、PlanningAgentV2、阶段目录或依赖。 +- 不修改 RNA-seq YAML、CLI、后端执行器和 foreground 逻辑。 +- 不实现或接入 `rnaseq_family_projection`。 +- 不取消通用 proposal 确认机制。 + +## 测试设计 + +先增加会失败的主 Agent 边界测试,再修改生产代码: + +1. 泛化 `执行rnaseq` 即使路由模型返回模式澄清和 RNA workflow,也必须生成基于原文的 proposal,不出现模式问题,且 proposal 不含 `workflow_id`。 +2. 显式 `执行全基因组rnaseq` 和 `对已确认家族成员执行rnaseq` 也只传原文,不由主 Agent 固化 workflow。 +3. 非 RNA 分析请求同样遵守统一边界,防止形成 RNA 专属补丁。 +4. 普通问答、项目状态、结果查看和文件读取不受影响。 +5. 后端 API 验证 `执行rnaseq -> 确认 -> IntentAgent -> plan`:主 Agent 不询问模式;tool trace 中传给 IntentAgent 的请求保留原始执行动作;计划内容完全采用下游返回结果。 + +## 验收标准 + +- 主 Agent 不再提出全基因组/基因家族模式问题。 +- 主 Agent 不为新分析设置 `workflow_id`,也不选择或修改阶段。 +- 用户原始分析动作完整进入 IntentAgent。 +- 前端和所有下游分析代码零改动。 +- 单元测试和真实后端 API 验证通过;若服务未重启导致 API 仍运行旧代码,必须如实报告并在获得当前服务操作权限后复验。