boss/docs/superpowers/specs/2026-04-16-master-agent-fast-path-design.md

主 Agent Fast Path 设计

更新时间：2026-04-16

1. 背景

主 Agent 当前同时承担两类请求：

• 需要深度理解、规划、协调的慢路径问题
• 只需要读取本地状态、快速执行配置变更的快路径问题

在原实现里，只有少量模型切换命令会本地直答。大量高频问题，例如“你现在是什么大模型”“当前后端是什么”，仍会落入主推理链，导致：

• 回复延迟明显偏高
• 消耗不必要的 token
• 用户需要记忆更机械的命令句式

2. 设计目标

• 把“状态查询 / 配置操作 / 枚举类问题”从主推理链中剥离出来
• 对高频确定性问题提供本地直答，不进入异步队列
• 保持自然语言容错，不要求用户输入完全标准化命令
• 为后续继续扩展快路径意图提供统一入口

3. 方案

3.1 Fast Path Router

在 src/lib/boss-master-agent.ts 中新增主 Agent 快路径路由层：

• 统一先构造 MasterAgentFastIntentContext
• 上下文内聚合：
  • 当前登录用户作用域下的 agentControls
  • 可见模型列表
  • 可用模型列表
  • 当前聊天意图的实际模型策略
  • 深度任务意图的实际模型策略
  • 当前 runtime 主控来源
• replyToMasterAgentUserMessage() 在进入主链前先尝试 tryHandleMasterAgentFastIntent()

3.2 第一批接入意图

• 模型列表查询
  • 例：“有哪些模型可以用”
• 模型切换
  • 例：“把快模型切到 gpt5.4mini”
• 当前模型状态查询
  • 例：“你现在是什么大模型”
  • 例：“当前主模型是什么”
  • 例：“快模型是什么”
  • 例：“强模型是什么”
• 当前后端状态查询
  • 例：“当前后端是什么”

3.3 自然语言归一化

模型名解析新增轻量归一化：

• 忽略 - / _ / 空格 / .
• 兼容 gpt5.4、gpt 5.4、gpt_5_4
• 仍然会回落到系统当前可选模型列表做映射

4. 展示规则

主 Agent 快路径回复的发送者名称改成：

• 主Agent·<当前模型名>

Android 主 Agent 会话页顶部标题同步显示：

• 主Agent·<当前模型名>

如果当前拿不到显式模型，则退回：

• 主Agent

5. 当前收益

• “查状态 / 查配置 / 改模型”这一类问题能直接秒回
• 主 Agent 不再因为低价值查询进入慢路径
• 用户不用死记标准句式
• 后续扩展更多快路径意图时，只需要继续往 router 中追加 handler

6. 后续扩展建议

下一批适合继续接入 Fast Path 的问题：

• 当前绑定设备 / 在线设备查询
• 当前会话 / 当前线程运行状态查询
• GUI / CLI 默认执行模式查询
• 当前接管开关状态查询
• 最近活跃项目 / 最近活跃线程查询

7. 验证基线

本次落地至少要求以下验证通过：

• npx tsx --test tests/master-agent-message-queue.test.ts tests/master-agent-chat-controls.test.ts
• npm run build
• ./gradlew :app:compileDebugJavaWithJavac :app:assembleDebug
• 真机安装并验证主 Agent 名称与模型查询行为