# 进化引擎 — 架构与使用指南

## 文件结构

```
server/
├── config/
│   └── backends.json              # Launcher 配置 (ACP 长连接用)
├── db/
│   ├── knex.js                    # PostgreSQL 连接
│   ├── schema-evolution.sql       # 进化系统表结构
│   └── seed-agents.js             # 四维配置 Seed (Clients + Agents + Groups)
├── services/
│   └── evolution-queries.js       # 数据库 CRUD (evolution_runs, skill_genomes, ...)
├── logs/
│   └── evolution-<skill>-<ts>.log # NDJSON 运行日志
└── src/
    ├── core/
    │   ├── agent-manager.js       # 四维正交入口: callAgent()
    │   └── runtime-resolver.js    # (agent, client) → { protocol, transport, launcher }
    ├── engine/
    │   ├── process-guard.js       # 超时看门狗
    │   ├── idle-timer.js          # 流式空闲超时
    │   └── failover-error.js      # 错误分类
    └── evolution/
        ├── run-controller.js      # 编排器：Phase 1 + Phase 2
        ├── steps.js               # Phase 2 四步循环
        ├── evaluator.js           # LLM 调用核心 (callEvaluator)
        ├── evolution-logger.js    # NDJSON 结构化日志
        ├── forager.js             # Skill 扫描 → 基因组入库
        ├── smoke-test.js          # 端到端冒烟测试
        ├── genome/
        │   ├── serializer.js      # SKILL.md → 6维基因组 JSON
        │   ├── deserializer.js    # 6维基因组 JSON → SKILL.md
        │   └── seeder.js          # 策略变体生成 (judgment/scar 增强)
        ├── operators/
        │   ├── fitness-calculator.js  # 6维适应度评估
        │   ├── selector.js            # 精英选择 + 淘汰
        │   ├── crossover.js           # 交叉重组
        │   └── mutator.js             # 变异 (扰动 / Agent 驱动)
        ├── arena/
        │   ├── arena.js               # Arena 场景评估
        │   └── benchmark-executor.js  # Benchmark 探针执行器
        └── benchmark/
            ├── generator.js           # LLM 自动生成 Benchmark
            └── evolver.js             # Benchmark 自进化 (红皇后)
```

## 四维正交集成

进化引擎的 LLM 调用通过四维正交架构完成，不绕过 `AgentManager`。

### evaluator Agent 定义

```
agent = { name: 'evaluator', type: 'executor', client: 'kimi', deploy: 'local' }
client = { name: 'kimi', command: 'kimi', acpArgs: ['acp'], acpProtocol: 'acp' }
```

- 换 AI 后端：只需改 evaluator 的 `client` 字段（如 `'claude'`）
- 换部署方式：只需改 `deploy`（如 `'docker'`）
- Client 配置来源：`seed-agents.js` 中的 `CLIENTS` 常量

## 调用链路

### LLM 调用链（四维正交）

```
evaluator.callEvaluator(systemContext, task)
  ├─ LRU 缓存检查 (md5 key)
  ├─ AgentManager.callAgent('evaluator', fullPrompt)
  │   ├─ getAgentConfig('evaluator')
  │   │   → { agent: { client: 'kimi', deploy: 'local' },
  │   │       client: { command: 'kimi', acpArgs: ['acp'] } }
  │   │
  │   ├─ runtimeResolver.resolve(agent, client)
  │   │   → { protocol: 'acp', transport: 'pipe', launcherType: 'process',
  │   │       launcherConfig: { type: 'process', command: 'kimi', args: ['acp'] } }
  │   │
  │   └─ _runViaProtocol(agent, prompt, resolved)
  │       └─ factory.createConnection() → ProcessLauncher + PipeTransport
  │           └─ AcpProtocol.connect() → initialize → newSession → sendPrompt
  │
  ├─ extractJSON(output)  ← 括号深度匹配
  ├─ _emit('llm_parsed', { parsed })
  └─ setCache(key, parsed)
```

### Phase 1: 初始化

```
RunController.runPhase1(skillName)
  │  → 创建 AgentManager (evaluator agent + kimi client)
  │  → setAgentManager(agentManager)
  │
  ├─ 1. Forage ─────────── forager.forageOneSkill()
  ├─ 2. Seed ───────────── seeder.seedRunPopulation()
  ├─ 3. Benchmark 生成 ── callEvaluator() → AgentManager → kimi CLI
  └─ 4. 初始适应度 ────── callEvaluator() → AgentManager → kimi CLI
```

### Phase 2: 自然选择循环 (每代)

```
RunController.runPhase2(runId, generations)
  └→ for each generation:
       ├─ Evaluate ─── Arena + Benchmark + Fitness (各走 callEvaluator)
       ├─ Select ───── selector.selectGeneration()
       ├─ Reproduce ── crossover + mutation (mutation 走 callEvaluator)
       └─ BenchmarkEvolve ── evolver.evolveAllBenchmarks()
```

### 6 维基因组结构

```
Genome = {
  mentalModels     # 因果推理模型：框架、约束、推理链
  patternLibrary   # 模式库：识别模式、反模式、上下文适用性
  judgment         # 决策判断：触发条件、权衡、边界
  toolFluency      # 工具使用：工具链、参数、组合策略
  taste            # 品味标准：质量判据、风格偏好
  scarTissue       # 失败教训：踩坑记录、规避规则
}
```

## 数据库依赖

PostgreSQL，表结构在 `server/db/schema-evolution.sql`：

| 表                     | 用途                             |
| ---------------------- | -------------------------------- |
| `evolution_runs`       | 进化运行记录 (每 Skill 一个 Run) |
| `skill_genomes`        | 基因组存储 (6 维 JSON)           |
| `fitness_evaluations`  | 适应度评估记录                   |
| `evolution_benchmarks` | Benchmark 测试场景               |
| `learning_events`      | 学习事件日志                     |

## 使用方法

### 前置条件

1. PostgreSQL 运行中，evolution 表已创建
2. kimi CLI 已安装 (`pip install kimi-cli`)

### 冒烟测试

```bash
# 完整测试：Phase 1 (初始化) + Phase 2 (1 代自然选择)
node server/src/evolution/smoke-test.js code-review

# 只跑 Phase 2 (需要已有 runId)
node server/src/evolution/smoke-test.js --phase2 <runId>

# 多代进化
node server/src/evolution/smoke-test.js code-review --gens=5
```

### 单独步骤

```bash
# 1. 扫描 Skill 入库
node server/src/evolution/forager.js code-review

# 2. 序列化/反序列化测试
node server/src/evolution/genome/test-serializer.js
node server/src/evolution/genome/test-deserializer.js
```

### 日志查看

每次运行生成 NDJSON 日志文件：

```bash
# 查看所有 LLM 调用
cat server/logs/evolution-*.log | jq 'select(.event=="llm_request")'

# 查看 LLM 返回
cat server/logs/evolution-*.log | jq 'select(.event=="llm_response") | {backend, durationMs, outputLength}'

# 查看适应度
cat server/logs/evolution-*.log | jq 'select(.event=="genome" and .action=="fitness")'
```

### 环境变量

| 变量                   | 默认值 | 说明         |
| ---------------------- | ------ | ------------ |
| `EVOLUTION_LLM_BUDGET` | 500    | LLM 调用上限 |

## 冒烟测试验证结果 (2026-02-25)

```
Phase 1: 140.8s
  ├─ Forage: 41 条目
  ├─ Seed: 3 基因组 (1 原始 + 2 变体)
  ├─ Benchmark: 12 个探针 ✅
  └─ bestFitness: 0.43

Phase 2 (进行中):
  ├─ Arena: 3 基因组评估 ✅
  ├─ Benchmark 探针: 持续运行 ✅
  ├─ 适应度: 70% (最高 genome)
  └─ 全部 JSON 解析成功 ✅

链路: evaluator → AgentManager.callAgent() → runtimeResolver → AcpProtocol → kimi acp
```