docs: define main agent analysis handoff boundary

2026-08-07 21:15:00 +08:00
parent 941673519f
commit bfbddb544c
1 changed files with 47 additions and 0 deletions
@@ -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 仍运行旧代码，必须如实报告并在获得当前服务操作权限后复验。