boss/docs/superpowers/specs/2026-04-16-master-agent-evolution-engine-design.md

主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 分支同一套信号与提案只记录、不自动采纳