288 lines
10 KiB
Markdown
288 lines
10 KiB
Markdown
# 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
|
||
```
|