feat: add master agent evolution engine core

2026-04-16 05:21:50 +08:00
parent f496838ced
commit de6257a819
14 changed files with 1551 additions and 8 deletions
--- a/docs/architecture/ai_handoff_index_cn.md
+++ b/docs/architecture/ai_handoff_index_cn.md
@@ -24,6 +24,7 @@
 7. `docs/architecture/thread_context_budget_and_handoff_protocol_cn.md`
 8. `prompts/codex_fullstack_build_and_deploy_prompt_cn.md`
 9. `docs/superpowers/specs/2026-04-16-master-agent-fast-path-design.md`
+10. `docs/superpowers/specs/2026-04-16-master-agent-evolution-engine-design.md`

 ## 3. 当前有效实现边界

@@ -36,6 +37,7 @@
 - `src/lib/boss-device-auth.ts`：设备 token / 登录会话混合鉴权辅助
 - `src/lib/boss-events.ts`：SSE 事件总线
 - `src/lib/boss-master-agent.ts`：主 Agent 真实回复链路、Master Codex Node relay 与 API 容灾逻辑
+- `src/lib/master-agent-evolution.ts`：主 Agent 自动进化引擎，负责 signal、proposal、rule 与 controlled / autonomous 模式
 - `src/lib/boss-attachments.ts`：附件类型识别、分析状态决策和下载头
 - `src/lib/boss-storage.ts`：附件存储抽象、配置校验和脱敏输出
 - `src/lib/boss-storage-server-file.ts`：服务器文件存储上传 / 读取
--- a/docs/architecture/current_runtime_and_deploy_status_cn.md
+++ b/docs/architecture/current_runtime_and_deploy_status_cn.md
@@ -163,6 +163,7 @@ cd /Users/kris/code/boss
 - 主 Agent 当前真实对话链路已验证通过：`Boss Web -> /api/v1/projects/master-agent/messages -> master-agent task queue -> local-agent -> codex exec -> /complete -> 项目消息账本`
 - 主 Agent 单聊当前已改成“快速入队 + 异步回流”：`POST /api/v1/projects/master-agent/messages` 会先返回 `masterReplyState + task`，真实回复随后再回写消息账本
 - 当前对话级 `agentControls` 已经生效：`master-agent` 会话支持 `modelOverride / reasoningEffortOverride` 强制覆盖，也支持 `fastModelOverride / fastReasoningEffortOverride / smartModelOverride / smartReasoningEffortOverride` 这组策略默认值；主 Agent 普通对话默认按 fast 档选模型，深度任务可按 smart 档选模型，手动强制覆盖仍然优先级最高
+- 当前主 Agent 自动进化引擎已接入第一阶段共享内核：`masterAgentEvolutionConfig / Signals / Proposals / Rules / RunLogs` 已进入状态模型，`GET /api/v1/master-agent/evolution` 可查看进化状态，`POST /api/v1/master-agent/evolution/config` 可在 `controlled / autonomous` 间切换，提案支持 approve / reject；`controlled` 只生成待审批提案，`autonomous` 可自动采纳低风险 `memory_patch / routing_preference_patch / fast_path_rule`
 - 当前 `group_dispatch_plan / device_import_resolution / attachment_analysis` 三类深度任务已经会把 `smart*` 策略下发到任务队列，并随任务持久化 `executionModel / executionReasoningEffort`；local-agent 执行这类任务时会优先吃任务级模型，不再只依赖本机固定默认模型
 - 当前对话级 `agentControls` 也已支持 `backendOverride`：`master-agent` 会话可在 `Claw Runtime` 或 `Hermes Runtime` 可用时显式选择 `claw-runtime / hermes-runtime`，普通单线程会话当前只开放 `hermes-runtime`；不可用时保存接口会直接拒绝，并返回人类可读原因
 - 原生 Android 当前会把 `master-agent` 的等待态保留在消息流里：发送后常驻显示“主 Agent 思考中”，超时后改成“主 Agent 回复超时 + 重试等待”，收到新回复后会自动清掉，不再只靠 toast 提示
--- a/docs/superpowers/plans/2026-04-16-master-agent-evolution-engine.md
+++ b/docs/superpowers/plans/2026-04-16-master-agent-evolution-engine.md
@@ -0,0 +1,287 @@
+# Master Agent Evolution Engine Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 给 Boss 主Agent 增加一套统一的自动进化引擎，并支持 `controlled` 与 `autonomous` 两种模式以及双分支交付。
+
+**Architecture:** 在现有 `boss-data` 与 `boss-master-agent` 上新增 evolution state、engine 和 API。共享内核一次实现，分支差异只保留在默认模式与自动采纳开关上，避免维护两份逻辑。
+
+**Tech Stack:** Next.js 16、TypeScript、文件型状态存储、Node test runner
+
+---
+
+### Task 1: 增加 Evolution 状态模型与持久化
+
+**Files:**
+- Modify: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/lib/boss-data.ts`
+- Test: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/tests/master-agent-evolution-state.test.ts`
+
+- [ ] **Step 1: 写失败测试，定义 evolution state 的默认结构与读写**
+
+```ts
+test("boss state 初始化时包含 master agent evolution 默认配置与空集合", async () => {
+  const state = await readState();
+  assert.deepEqual(state.masterAgentEvolutionConfig?.mode, "controlled");
+  assert.deepEqual(state.masterAgentEvolutionSignals, []);
+  assert.deepEqual(state.masterAgentEvolutionProposals, []);
+  assert.deepEqual(state.masterAgentEvolutionRules, []);
+  assert.deepEqual(state.masterAgentEvolutionRunLogs, []);
+});
+```
+
+- [ ] **Step 2: 运行测试，确认当前失败**
+
+Run: `npx tsx --test tests/master-agent-evolution-state.test.ts`
+Expected: FAIL，提示缺少 `masterAgentEvolution*` 字段或断言不匹配
+
+- [ ] **Step 3: 在 `boss-data.ts` 中新增类型和默认状态**
+
+```ts
+export type MasterAgentEvolutionMode = "controlled" | "autonomous";
+
+export interface MasterAgentEvolutionConfig {
+  mode: MasterAgentEvolutionMode;
+  autoApplyLowRiskRules: boolean;
+  updatedAt: string;
+}
+```
+
+- [ ] **Step 4: 扩展 `BossState`、normalize 逻辑和默认初始值**
+
+Run: `npx tsx --test tests/master-agent-evolution-state.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/lib/boss-data.ts tests/master-agent-evolution-state.test.ts
+git commit -m "feat: add master agent evolution state"
+```
+
+### Task 2: 实现 Evolution Engine 核心
+
+**Files:**
+- Create: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/lib/master-agent-evolution.ts`
+- Test: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/tests/master-agent-evolution-engine.test.ts`
+
+- [ ] **Step 1: 写失败测试，覆盖 signal -> proposal 的最小闭环**
+
+```ts
+test("recording repeated deterministic questions creates a fast_path_rule proposal", async () => {
+  await recordMasterAgentEvolutionSignal({
+    kind: "repeated_question",
+    projectId: "master-agent",
+    account: "17600003315",
+    content: "当前主节点在线吗",
+  });
+  const proposals = await listMasterAgentEvolutionProposals();
+  assert.equal(proposals[0]?.proposalType, "fast_path_rule");
+});
+```
+
+- [ ] **Step 2: 运行测试，确认失败**
+
+Run: `npx tsx --test tests/master-agent-evolution-engine.test.ts`
+Expected: FAIL，提示函数或 proposal 类型不存在
+
+- [ ] **Step 3: 实现最小 engine API**
+
+```ts
+export async function recordMasterAgentEvolutionSignal(...) {}
+export async function listMasterAgentEvolutionProposals(...) {}
+export async function applyMasterAgentEvolutionProposal(...) {}
+```
+
+- [ ] **Step 4: 实现第一批 proposal 生成规则**
+
+规则最小集：
+- repeated deterministic questions -> `fast_path_rule`
+- repeated backend/model corrections -> `routing_preference_patch`
+- repeated user preference statements -> `memory_patch`
+
+- [ ] **Step 5: 运行测试确认通过**
+
+Run: `npx tsx --test tests/master-agent-evolution-engine.test.ts`
+Expected: PASS
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/lib/master-agent-evolution.ts tests/master-agent-evolution-engine.test.ts
+git commit -m "feat: add master agent evolution engine"
+```
+
+### Task 3: 把 Evolution Engine 挂到主Agent主链
+
+**Files:**
+- Modify: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/lib/boss-master-agent.ts`
+- Test: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/tests/master-agent-evolution-integration.test.ts`
+
+- [ ] **Step 1: 写失败测试，验证快路径未命中后会记录 signal**
+
+```ts
+test("master agent slow deterministic query records evolution signal when fast path misses", async () => {
+  await replyToMasterAgentUserMessage({
+    requestText: "当前线程是不是正在运行",
+    requestedBy: "Boss 超级管理员",
+    requestedByAccount: "17600003315",
+    mode: "enqueue",
+  });
+  const signals = await listMasterAgentEvolutionSignals();
+  assert.ok(signals.some((item) => item.kind === "fast_path_candidate"));
+});
+```
+
+- [ ] **Step 2: 运行测试，确认失败**
+
+Run: `npx tsx --test tests/master-agent-evolution-integration.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: 在 `replyToMasterAgentUserMessage()` 和相关成功/失败路径中记录 signal**
+
+最小挂载点：
+- Fast Path 命中
+- Fast Path 未命中但命中确定性查询模式
+- 后端 fallback
+- 用户手动切模型/切后端/切接管
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `npx tsx --test tests/master-agent-evolution-integration.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/lib/boss-master-agent.ts tests/master-agent-evolution-integration.test.ts
+git commit -m "feat: integrate evolution engine into master agent"
+```
+
+### Task 4: 实现 Evolution API
+
+**Files:**
+- Create: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/app/api/v1/master-agent/evolution/route.ts`
+- Create: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/app/api/v1/master-agent/evolution/config/route.ts`
+- Create: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/app/api/v1/master-agent/evolution/proposals/[proposalId]/approve/route.ts`
+- Create: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/app/api/v1/master-agent/evolution/proposals/[proposalId]/reject/route.ts`
+- Test: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/tests/master-agent-evolution-routes.test.ts`
+
+- [ ] **Step 1: 写失败测试，定义 GET/POST contract**
+
+```ts
+test("GET /api/v1/master-agent/evolution returns config proposals and rules", async () => {
+  const response = await GET(request);
+  const payload = await response.json();
+  assert.equal(payload.ok, true);
+  assert.ok(Array.isArray(payload.proposals));
+});
+```
+
+- [ ] **Step 2: 运行测试，确认失败**
+
+Run: `npx tsx --test tests/master-agent-evolution-routes.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: 实现读接口和 config 切换接口**
+
+- [ ] **Step 4: 实现 approve / reject 接口**
+
+- [ ] **Step 5: 运行测试确认通过**
+
+Run: `npx tsx --test tests/master-agent-evolution-routes.test.ts`
+Expected: PASS
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/app/api/v1/master-agent/evolution src/app/api/v1/master-agent/evolution/config src/app/api/v1/master-agent/evolution/proposals tests/master-agent-evolution-routes.test.ts
+git commit -m "feat: add master agent evolution routes"
+```
+
+### Task 5: 加入 Controlled / Autonomous 自动采纳分界
+
+**Files:**
+- Modify: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/src/lib/master-agent-evolution.ts`
+- Test: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/tests/master-agent-evolution-autonomous.test.ts`
+
+- [ ] **Step 1: 写失败测试，验证 controlled 不自动采纳、autonomous 可自动采纳低风险 proposal**
+
+```ts
+test("controlled mode keeps proposal pending_review", async () => {
+  await setMasterAgentEvolutionMode("controlled");
+  // record signal...
+  assert.equal(proposals[0]?.status, "pending_review");
+});
+
+test("autonomous mode auto applies low risk routing preference patch", async () => {
+  await setMasterAgentEvolutionMode("autonomous");
+  // record signal...
+  assert.equal(proposals[0]?.status, "auto_applied");
+});
+```
+
+- [ ] **Step 2: 运行测试，确认失败**
+
+Run: `npx tsx --test tests/master-agent-evolution-autonomous.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: 实现 mode gating 与低风险自动采纳白名单**
+
+白名单：
+- `memory_patch`
+- `routing_preference_patch`
+- `fast_path_rule`
+
+黑名单：
+- 管理员全局主提示词修改
+- 高风险提示词覆盖
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `npx tsx --test tests/master-agent-evolution-autonomous.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/lib/master-agent-evolution.ts tests/master-agent-evolution-autonomous.test.ts
+git commit -m "feat: add controlled and autonomous evolution modes"
+```
+
+### Task 6: 更新交接文档并切双分支
+
+**Files:**
+- Modify: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/docs/architecture/ai_handoff_index_cn.md`
+- Modify: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/docs/architecture/current_runtime_and_deploy_status_cn.md`
+- Modify: `/Users/kris/.config/superpowers/worktrees/boss/codex-hermes-backend-mvp/docs/superpowers/specs/2026-04-16-master-agent-evolution-engine-design.md`
+
+- [ ] **Step 1: 文档中加入 evolution engine 与两种模式说明**
+
+- [ ] **Step 2: 运行组合验证**
+
+Run: `npx tsx --test tests/master-agent-evolution*.test.ts tests/master-agent-message-queue.test.ts tests/master-agent-chat-controls.test.ts`
+Expected: PASS
+
+Run: `npm run build`
+Expected: PASS
+
+- [ ] **Step 3: 提交共享内核**
+
+```bash
+git add docs/architecture/ai_handoff_index_cn.md docs/architecture/current_runtime_and_deploy_status_cn.md docs/superpowers/specs/2026-04-16-master-agent-evolution-engine-design.md
+git commit -m "docs: document master agent evolution engine"
+```
+
+- [ ] **Step 4: 创建 controlled 分支并推送**
+
+```bash
+git branch codex/master-agent-controlled-evolution
+git push gitea codex/master-agent-controlled-evolution
+```
+
+- [ ] **Step 5: 创建 autonomous 分支，在其上把默认 mode 切到 autonomous 并推送**
+
+```bash
+git checkout -b codex/master-agent-autonomous-evolution
+git push gitea codex/master-agent-autonomous-evolution
+```
--- a/docs/superpowers/specs/2026-04-16-master-agent-evolution-engine-design.md
+++ b/docs/superpowers/specs/2026-04-16-master-agent-evolution-engine-design.md
@@ -0,0 +1,198 @@
+# 主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` 分支同一套信号与提案只记录、不自动采纳