# 主 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 的问题：

- 当前会话 / 当前线程运行状态查询
- 最近活跃项目 / 最近活跃线程查询
- 更细粒度的线程级接管控制与作用域切换

## 6.1 第二批已接入意图

本次继续把主 Agent 的“控制面”高频问题接入快路径：

- 全局接管状态查询
  - 例：“当前有没有开启主agent接管”
- 全局接管开关
  - 例：“帮我开启全局接管”
  - 例：“关闭全局接管”
- 默认后端切换
  - 例：“把默认后端切到 Hermes”
  - 例：“切到 Claw 后端”
- 默认执行模式查询
  - 例：“现在默认走 GUI 还是 CLI”
- 当前主节点 / 绑定设备在线状态查询
  - 例：“当前主节点在线吗”

这批实现原则是：

- 只处理确定性、纯本地状态可回答的问题
- 不进入异步任务队列
- 先命中接管 / 后端 / 执行模式，再命中模型切换，避免“切到 Hermes 后端”被模型切换规则误判
- `GUI 还是 CLI` 与 `Hermes 还是 Claw` 分属不同意图，不再混用一个正则

## 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 名称与模型查询行为

第二批补充验证点：

- `npx tsx --test tests/master-agent-message-queue.test.ts`
- 覆盖全局接管查询 / 切换
- 覆盖默认后端切换
- 覆盖 GUI/CLI 执行模式查询
- 覆盖主节点设备在线状态查询