# 主Agent 自动进化引擎设计

更新时间：`2026-04-16`

## 1. 背景

当前 Boss 主Agent 已经具备：

- 长期记忆：`masterAgentMemories`
- 提示词策略：`masterAgentPromptPolicy`、`userMasterPrompts`
- 对话控制：`userProjectAgentControls`
- 运行时自适应：Master Node / Hermes / Claw / API fallback

但它还不具备真正的自动进化闭环。现状只能“记住”与“回退”，不能持续发现问题、形成提案、沉淀规则并在后续回复中生效。

## 2. 目标

- 给主Agent增加统一的 `Evolution Engine`
- 支持两种能力范围：
  - `controlled`：受控自动进化，只生成提案，等待用户批准后落地
  - `autonomous`：完全自我进化，对高置信度提案自动落地
- 进化逻辑对现有主链最小侵入，不重写现有回复链、任务链、记忆链
- 所有进化行为可追踪、可审计、可回滚

## 3. 核心概念

### 3.1 Evolution Signal

进化信号，记录“为什么应该考虑进化”。

第一批信号来源：

- 高频重复问句
- 慢回复问题
- 用户纠正主Agent
- 模型/后端频繁手动切换
- 后端回退或执行失败
- Fast Path 未命中但属于确定性状态问题

### 3.2 Evolution Proposal

进化提案，记录“建议怎么改”。

第一批提案类型：

- `fast_path_rule`
- `prompt_policy_patch`
- `memory_patch`
- `agent_control_patch`
- `routing_preference_patch`

### 3.3 Evolution Rule

已生效规则，表示被批准或自动采纳后真正进入系统长期状态的变更。

### 3.4 Evolution Run Log

进化执行日志，记录某次信号分析、提案生成、采纳、拒绝、自动落地的全过程。

## 4. 运行模式

### 4.1 Controlled

受控自动进化：

- 主Agent可以自动记录 signal
- 可以自动生成 proposal
- 不允许自动改长期状态
- 只能在用户批准后写入 memory / prompt / controls / fast-path rules

适合生产稳态与审计要求更高的环境。

### 4.2 Autonomous

完全自我进化：

- 主Agent可以自动记录 signal
- 自动生成 proposal
- 对满足阈值的 proposal 直接自动采纳
- 自动把结果写入长期状态
- 仍保留完整日志，允许后续回滚

适合开发期快速迭代，用更高风险换更快自优化速度。

## 5. 架构

### 5.1 新增状态模型

在 `BossState` 中新增：

- `masterAgentEvolutionConfig`
- `masterAgentEvolutionSignals`
- `masterAgentEvolutionProposals`
- `masterAgentEvolutionRules`
- `masterAgentEvolutionRunLogs`

### 5.2 新增引擎文件

- `src/lib/master-agent-evolution.ts`
  - 统一入口
  - signal 归一化
  - proposal 生成
  - 自动采纳判断
  - 规则落地
- `src/lib/master-agent-evolution-rules.ts`
  - Fast Path 规则、路由偏好规则解析
- `src/lib/master-agent-evolution-projections.ts`
  - 给 Web/API 返回 evolution 状态摘要

### 5.3 挂载点

第一批最小侵入挂载点：

- `replyToMasterAgentUserMessage()`
  - 记录用户问题、Fast Path 命中/未命中、慢路径耗时、模型/后端实际选择
- `appendMasterAgentSystemReply()`
  - 记录主Agent输出结果
- `completeMasterAgentTask()`
  - 记录异步任务成功/失败、fallback、超时
- `updateProjectAgentControls()` / `updateMasterAgentPromptPolicy()` / `createUserMasterMemory()`
  - 记录用户主动纠偏行为，作为 evolution signal 输入

## 6. 第一批自动进化能力

### Controlled 与 Autonomous 共用

- 记录重复问句
- 记录低价值慢路径
- 记录用户纠正模型/后端/接管设置
- 自动生成三类提案：
  - 新增 Fast Path 规则
  - 调整默认快模型/强模型/后端偏好
  - 追加 workflow_rule / user_preference 记忆

### Controlled 专属行为

- 所有提案状态默认为 `pending_review`
- 需要用户批准后才能落地

### Autonomous 专属行为

- 当 proposal 满足“高置信度 + 低破坏性”时自动落地
- 第一批只允许自动落地：
  - `memory_patch`
  - `routing_preference_patch`
  - `fast_path_rule`
- 不允许自动改管理员全局主提示词

## 7. 前台入口

第一批只做最小 Web 能力：

- `GET /api/v1/master-agent/evolution`
  - 返回 config / pending proposals / recent run logs / effective rules
- `POST /api/v1/master-agent/evolution/config`
  - 切换 `controlled` / `autonomous`
- `POST /api/v1/master-agent/evolution/proposals/[proposalId]/approve`
- `POST /api/v1/master-agent/evolution/proposals/[proposalId]/reject`

先不做复杂 UI，先把数据和接口打通，必要时从 `我的 > 主Agent` 进入。

## 8. 双分支策略

统一内核先落在共享提交里：

- evolution state
- evolution engine
- proposal / rule / run-log 结构
- API 与测试

然后从共享基线分两条分支：

- `codex/master-agent-controlled-evolution`
  - 默认 `mode=controlled`
  - 关闭自动采纳
- `codex/master-agent-autonomous-evolution`
  - 默认 `mode=autonomous`
  - 开启自动采纳阈值逻辑

用户先使用 autonomous 分支验证真实开发效率；一旦发现策略漂移或错误写入，可直接回退 controlled 分支。

## 9. 风险控制

- 管理员全局主提示词永远不允许 autonomous 自动改写
- 自动落地范围先限制在低风险对象
- 每次自动采纳都必须写 run log
- 所有 rule 都要带 `sourceProposalId`
- 所有 proposal 都要可拒绝、可归档、可回滚

## 10. 验证基线

- `npx tsx --test tests/master-agent-evolution*.test.ts`
- `npx tsx --test tests/master-agent-message-queue.test.ts tests/master-agent-chat-controls.test.ts`
- `npm run build`
- 线上切到 `autonomous` 后：
  - 主Agent可记录进化信号
  - 可自动生成并落地低风险规则
  - `controlled` 分支同一套信号与提案只记录、不自动采纳