🧬 Evolver.php：让 AI 越用越聪明的"进化引擎"

小凯 (C3P0) • 2026年02月27日 07:48

                        ## 什么是 Evolver.php？

**Evolver.php** 是一个基于 MCP（Model Context Protocol）协议的**能力演化引擎**，用 PHP 8.3+ 编写。它的核心思想很朴素：

> **让 AI 从每次修复和优化中学习，把经验沉淀下来，下次遇到类似问题时直接复用。**

简单来说，它就像给 AI 装了一个"记忆系统"，让 AI 不再是"鱼一样的七秒记忆"，而是能够不断积累、进化。

---

## 为什么需要它？

相信用过 AI 编程助手的朋友都有这种体验：

- 😤 **重复踩坑**：上次刚修好的 Bug，换个项目又犯了，AI 完全"失忆"
- 😵 **上下文限制**：项目太大，AI 记不住之前的修改逻辑
- 🔄 **低效循环**：同样的优化建议，每次都要重新解释一遍

**Evolver.php 要解决的就是这个问题。**

---

## 核心概念：Gene + Capsule 双轨制

Evolver.php 的进化产物分为两类，类比生物进化非常形象：

### 🧬 Gene（基因）— 可复用的策略模板

Gene 是**抽象的、可复用的策略**，定义了"遇到什么问题，用什么方法解决"。

比如默认就有一个 `gene_gep_repair_from_errors`：
- **匹配信号**：`error`, `exception`, `failed` 等
- **策略**：提取信号 → 选择 Gene → 估算影响范围 → 最小化修复 → 验证 → 固化
- **约束**：最多改 20 个文件，不能碰 `.git` 和 `vendor`

```json
{
  "id": "gene_gep_repair_from_errors",
  "category": "repair",
  "signals_match": ["error", "exception", "failed"],
  "strategy": ["提取信号", "选择Gene", "估算范围", "最小修复", "验证", "固化"],
  "constraints": {
    "max_files": 20,
    "forbidden_paths": [".git", "vendor"]
  }
}
```

### 💊 Capsule（胶囊）— 成功的具体案例

Capsule 是**具体的、成功的修复记录**，包含完整的上下文和解决方案。

```json
{
  "id": "cap_php_syntax_fix_001",
  "problem_hash": "sha256:abc123...",
  "solution_diff": "--- a/src/Foo.php\n+++ b/src/Foo.php\n@@ -40 +40 @@\n-        return $value\n+        return $value;",
  "context_summary": "Missing semicolon in return statement",
  "metadata": {"language": "php", "confidence": 0.95}
}
```

**关键特性**：通过 `problem_hash` 可以快速匹配相似问题，实现"秒级复用"。

---

## 工作流程：GEP 协议

Evolver.php 使用标准化的 **GEP（Gene Expression Protocol）协议**，一次完整的演化周期包含 5 个步骤：

```
信号提取 → Gene选择 → 提示生成 → LLM执行 → 结果固化
```

### 1️⃣ 信号提取（Signal Extraction）
从错误日志、用户输入中提取结构化信号，比如：
- `error_php_syntax` — PHP 语法错误
- `test_fail` — 测试失败
- `perf_bottleneck` — 性能瓶颈

### 2️⃣ Gene 选择（Gene Selection）
根据信号匹配最合适的 Gene。比如遇到 SQL 错误，就选 `gene_gep_repair_sqlite`。

### 3️⃣ GEP 提示生成（Prompt Building）
组合以下元素生成给 LLM 的提示：
- 选中的 Gene（策略模板）
- 相关的 Capsules（历史成功案例）
- 父事件（相关的演化历史）

### 4️⃣ LLM 执行演化
LLM 按 GEP 协议输出 **恰好 5 个 JSON 对象**：
1. **Mutation** — 变更触发器（风险等级、理由）
2. **PersonalityState** — 演化心态（严谨度、创造力等）
3. **EvolutionEvent** — 审计记录（信号、影响范围）
4. **Gene** — 更新后的策略模板
5. **Capsule** — 新的成功快照

### 5️⃣ 结果固化（Solidification）
验证通过后，将结果存入数据库：
- 更新/创建 Gene
- 存储 Capsule
- 记录 EvolutionEvent（审计日志）

---

## 数据存储：完全私有化

所有进化产物都存储在 **本地 SQLite 数据库**，默认路径：
```
~/.evolver/evolver.db
```

### 数据库表结构

| 表名 | 内容 |
|------|------|
| `genes` | 策略模板（JSON 格式） |
| `capsules` | 成功案例（含 diff、hash、置信度） |
| `events` | 完整的审计日志 |
| `failed_capsules` | 失败案例（用于学习） |

**特性**：
- ✅ WAL 模式 + mmap 优化，性能优秀
- ✅ 自动迁移，版本兼容
- ✅ 完全离线，数据不上云

---

## 使用场景

### 场景一：修复 Bug
```
用户：报错了！Parse error: unexpected '}' in Foo.php

AI → 调用 evolver_run → 匹配 gene_gep_repair_from_errors 
    → 生成 GEP 提示 → LLM 修复 → 固化结果

下次遇到 PHP 语法错误 → 直接复用 Capsule → 秒级修复
```

### 场景二：性能优化
```
用户：这段代码太慢了

AI → 匹配 gene_gep_optimize_prompt_and_assets
    → 查找历史优化 Capsules → 给出针对性建议
```

### 场景三：功能创新
```
用户：想加一个用户认证功能

AI → 匹配 gene_gep_innovate_from_opportunity
    → 参考已有 Capsules → 设计最小可行实现
```

---

## 安全设计

Evolver.php 内置了多层安全保护：

| 限制 | 说明 |
|------|------|
| **爆炸半径** | 单次演化最多 60 个文件 / 20,000 行 |
| **命令白名单** | 只允许 `php`, `composer`, `phpunit` 等 |
| **禁止路径** | 每个 Gene 可配置 `forbidden_paths` |
| **Shell 防护** | 禁止 `;`, `&&`, `\|\|`, `\|`, `>` 等操作符 |
| **自修改模式** | `never` / `review` / `always` 三档控制 |

---

## 快速开始

```bash
# 1. 克隆项目
git clone https://github.com/linkerlin/Evolver.php.git
cd Evolver.php

# 2. 安装依赖
composer install

# 3. 验证安装
php evolver.php --validate

# 4. 配置 MCP（以 Kimi Code CLI 为例）
# 编辑 ~/.kimi/mcp.json
{
  "mcpServers": {
    "evolver": {
      "command": "php",
      "args": ["/path/to/Evolver.php/evolver.php"],
      "env": {
        "EVOLVER_DB_PATH": "~/.evolver/evolver.db",
        "EVOLVE_ALLOW_SELF_MODIFY": "review"
      }
    }
  }
}
```

---

## 总结

Evolver.php 的核心理念是 **"让演化可积累"**：

- 🔁 不是每次都从零开始
- 🧠 而是基于历史经验智能决策
- 📈 用得越多，AI 越懂你的项目

它就像给 AI 装了一个"外脑"，把零散的经验变成结构化的知识，真正实现**持续进化**。

---

**项目地址**：https://github.com/linkerlin/Evolver.php

**许可证**：MIT

---

*本文基于 Evolver.php 源码分析整理，如有不准确之处欢迎指正！*                    

讨论回复

1 条回复

✨步子哥 (steper) #1

03-04 06:35

                                        # 🧬 Evolver.php 项目深度分析报告

## 📋 执行摘要

**Evolver.php** 是一个功能完备的 **Capability Evolver 引擎**的 PHP 8.3+ 实现，通过 **MCP (Model Context Protocol) stdio 服务器**方式暴露，采用 **SQLite** 进行本地化数据存储。这是一个成熟的、生产就绪的自演化系统，具有完善的安全模型和测试覆盖。

---

## 1️⃣ 项目概览

### 核心定位
- **纯 PHP 移植版**：1:1 移植自 EvoMap/evolver (JavaScript 版本)
- **MCP stdio 服务器**：零平台依赖，通过 stdin/stdout 进行 JSON-RPC 2.0 通信
- **信号驱动的演化引擎**：从日志/上下文提取信号，自动触发基因选择和演化
- **双轨知识系统**：Genes（可复用策略模板）+ Capsules（成功结果快照）

### 技术栈
| 组件 | 技术选型 |
|------|---------|
| **语言** | PHP 8.3+ (严格类型模式) |
| **数据库** | SQLite3 (WAL 模式 + mmap 优化) |
| **通信协议** | MCP (Model Context Protocol) JSON-RPC 2.0 |
| **测试框架** | PHPUnit 11.4+ |
| **自动加载** | PSR-4 |

---

## 2️⃣ 架构设计

### 2.1 核心架构图

```
┌─────────────────────────────────────────────────────┐
│  MCP Client (Claude Desktop / Kimi CLI / Gemini)    │
│  - JSON-RPC 2.0 over stdio                          │
└────────────────────┬────────────────────────────────┘
                     │ stdin/stdout
┌────────────────────▼────────────────────────────────┐
│  evolver.php (入口文件)                              │
│  - MCP 服务器引导                                    │
│  - CLI 参数解析 (--validate, --loop, --daemon)       │
└────────────────────┬────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────┐
│  McpServer.php (MCP 协议层)                          │
│  - JSON-RPC 消息处理                                 │
│  - 工具分发 (tools/list, tools/call)                │
│  - 资源管理 (resources/read)                         │
└────────────────────┬────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────┐
│  核心引擎层                                          │
│  ┌──────────────┐  ┌──────────────┐                │
│  │ Signal       │  │ Gene         │                │
│  │ Extractor    │  │ Selector     │                │
│  └──────┬───────┘  └──────┬───────┘                │
│         │                 │                         │
│         └────────┬────────┘                         │
│                  ▼                                  │
│  ┌───────────────────────────┐                      │
│  │ PromptBuilder             │                      │
│  │ (GEP 1.6.0 协议提示构建)     │                      │
│  └───────────┬───────────────┘                      │
│              │                                      │
│  ┌───────────▼───────────────┐                      │
│  │ SolidifyEngine            │                      │
│  │ (验证 + 固化 + 爆炸半径计算)  │                      │
│  └───────────┬───────────────┘                      │
└──────────────┼──────────────────────────────────────┘
               │
┌──────────────▼──────────────────────────────────────┐
│  数据持久化层                                        │
│  ┌─────────────────────────────────────────────┐   │
│  │ GepAssetStore + Database                    │   │
│  │ - Genes / Capsules / Events                 │   │
│  │ - SQLite WAL + mmap (128MB)                 │   │
│  │ - 自动 Schema 迁移 (1.5.0 → 1.6.0)            │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
```

### 2.2 目录结构分析

```
Evolver.php/
├── evolver.php              # 主入口 (MCP 服务器引导)
├── composer.json            # 依赖管理 (仅 PHPUnit)
├── phpunit.xml              # 测试配置
│
├── src/                     # 核心源代码 (47 个文件)
│   ├── McpServer.php        # MCP 协议实现
│   ├── Database.php         # SQLite 封装 + 自动迁移
│   ├── GepAssetStore.php    # Gene/Capsule/Event 存储
│   ├── SignalExtractor.php  # 信号提取 (35+ 种信号类型)
│   ├── GeneSelector.php     # 基因选择引擎 (漂移算法)
│   ├── PromptBuilder.php    # GEP 提示构建 (1.6.0 协议)
│   ├── SolidifyEngine.php   # 固化引擎 + 安全验证
│   ├── SafetyController.php # 安全模式控制
│   ├── SourceProtector.php  # 源文件保护
│   ├── BlastRadiusCalculator.php # 爆炸半径计算
│   ├── ContentHash.php      # SHA-256 资产哈希
│   ├── MemoryGraph.php      # 知识图谱
│   ├── A2A.php              # Agent-to-Agent 协议
│   ├── EvolutionLoop.php    # 连续演化循环
│   │
│   └── Ops/                 # 运维工具 (14 个文件)
│       ├── LifecycleManager.php
│       ├── HealthCheck.php
│       ├── DiskCleaner.php
│       ├── SignalDeduplicator.php
│       ├── SecurityAuditLogger.php
│       └── ...
│
├── tests/                   # 测试套件 (44 个测试文件)
│   ├── DatabaseTest.php
│   ├── SignalExtractorTest.php
│   ├── McpServerTest.php
│   ├── GepAssetStoreTest.php
│   └── ...
│
├── data/
│   └── default_genes.json   # 默认基因种子数据 (6 个基因)
│
└── scripts/                 # 工具脚本
    ├── evolver-validate.php # 安装验证工具
    ├── evolver-report.php   # 报告生成
    └── ...
```

---

## 3️⃣ 核心功能模块深度分析

### 3.1 MCP 服务器 ([`McpServer.php`](file:///Volumes/SSD/GitHub/Evolver.php/src/McpServer.php))

**职责**：实现 MCP 协议，处理 JSON-RPC 2.0 消息

**关键特性**：
- ✅ 完整的 MCP 能力：`tools/list`, `tools/call`, `resources/list`, `resources/read`
- ✅ 12 个可用工具：
  - `evolver_run` - 运行演化周期
  - `evolver_solidify` - 固化结果
  - `evolver_extract_signals` - 提取信号
  - `evolver_upsert_gene/delete_gene` - 基因管理
  - `evolver_stats` - 统计信息
  - `evolver_safety_status` - 安全状态
  - `evolver_sync_to_hub` - 同步到 EvoMap Hub

**代码质量**：
- 严格类型声明
- 错误处理完善 (try-catch + error_log)
- 生命周期管理 (startup/shutdown hooks)

---

### 3.2 数据库层 ([`Database.php`](file:///Volumes/SSD/GitHub/Evolver.php/src/Database.php))

**Schema 版本**：1.6.0

**核心表结构**：

```sql
-- Genes 表 (策略模板)
CREATE TABLE genes (
    id TEXT PRIMARY KEY,
    category TEXT NOT NULL DEFAULT 'repair',
    asset_id TEXT,              -- SHA-256 内容哈希
    schema_version TEXT DEFAULT '1.6.0',
    data TEXT NOT NULL,         -- JSON 编码的完整基因数据
    created_at TEXT,
    updated_at TEXT
);

-- Capsules 表 (成功快照)
CREATE TABLE capsules (
    id TEXT PRIMARY KEY,
    gene_id TEXT,
    asset_id TEXT,
    data TEXT NOT NULL,
    confidence REAL DEFAULT 0.5,
    outcome_status TEXT,
    outcome_score REAL,
    env_fingerprint TEXT,       -- 环境指纹
    success_streak INTEGER,
    content TEXT,
    created_at TEXT
);

-- Events 表 (演化事件记录)
CREATE TABLE events (
    id TEXT PRIMARY KEY,
    intent TEXT NOT NULL,
    signals TEXT,
    genes_used TEXT,
    outcome_status TEXT,
    outcome_score REAL,
    data TEXT NOT NULL,
    env_fingerprint TEXT,
    mutations_tried INTEGER,
    total_cycles INTEGER,
    created_at TEXT
);

-- Failed Capsules 表 (失败记录)
CREATE TABLE failed_capsules (
    id TEXT PRIMARY KEY,
    gene_id TEXT,
    trigger_signals TEXT,
    failure_reason TEXT,
    diff_snapshot TEXT,
    created_at TEXT
);

-- Sync Status 表 (Hub 同步状态)
CREATE TABLE sync_status (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    asset_type TEXT NOT NULL,
    local_id TEXT NOT NULL,
    asset_id TEXT,
    sync_status TEXT DEFAULT 'pending',
    last_sync_attempt TEXT,
    sync_error TEXT,
    created_at TEXT,
    updated_at TEXT
);
```

**性能优化**：
```php
PRAGMA journal_mode=WAL;           // WAL 模式 (并发读写)
PRAGMA mmap_size=134217728;        // 128MB 内存映射
PRAGMA synchronous=NORMAL;         // 平衡性能和安全
PRAGMA cache_size=-65536;          // 64MB 缓存
PRAGMA wal_autocheckpoint=1000;    // 自动检查点
```

**自动迁移机制**：
- 版本检测 → 增量迁移 → 版本更新
- 支持从 1.5.0 → 1.6.0 的平滑升级
- 迁移日志记录

---

### 3.3 信号提取器 ([`SignalExtractor.php`](file:///Volumes/SSD/GitHub/Evolver.php/src/SignalExtractor.php))

**信号类型** (35+ 种)：

| 分类 | 信号示例 |
|------|---------|
| **错误信号** | `log_error`, `recurring_error`, `errsig:...` |
| **机会信号** | `user_feature_request`, `user_improvement_suggestion` |
| **性能信号** | `perf_bottleneck`, `timeout`, `high_cpu` |
| **能力缺口** | `capability_gap`, `unsupported_input_type` |
| **协议信号** | `protocol_drift`, `memory_missing` |
| **高级检测** | `repair_loop_detected`, `evolution_stagnation_detected` |

**高级检测算法**：

```php
// 修复循环检测 (连续 3 次修复失败)
if ($history['consecutiveRepairCount'] >= 3) {
    $signals[] = 'repair_loop_detected';
}

// 强制创新阈值 (连续 5 次修复)
if ($history['consecutiveRepairCount'] >= 5) {
    $signals[] = 'force_innovation_after_repair_loop';
}

// 停滞检测 (连续 3 次空周期)
if ($history['consecutiveEmptyCycles'] >= 3) {
    $signals[] = 'evolution_stagnation_detected';
}

// 失败率检测 (60% 以上失败)
if ($history['recentFailureRatio'] >= 0.6) {
    $signals[] = 'high_failure_rate';
}
```

**代码亮点**：
- ✅ 正则 + 关键词双重匹配
- ✅ 错误签名规范化 (路径/数字/十六进制替换)
- ✅ 历史事件分析 (consecutive patterns)

---

### 3.4 基因选择器 ([`GeneSelector.php`](file:///Volumes/SSD/GitHub/Evolver.php/src/GeneSelector.php))

**选择算法**：

```php
// 1. 模式匹配 (支持正则)
public function matchPatternToSignals(string $pattern, array $signals): bool
{
    // /regex/i 格式支持
    // 或简单子字符串匹配
}

// 2. 评分系统
public function scoreGene(array $gene, array $signals): int
{
    $score = 0;
    foreach ($gene['signals_match'] as $pattern) {
        if ($this->matchPatternToSignals($pattern, $signals)) {
            $score++;
        }
    }
    return $score;
}

// 3. 漂移选择 (Drift Selection)
// 在最高分基因中随机选择，增加多样性
if ($driftIntensity > 0 && mt_rand() / mt_getrandmax() < $driftIntensity) {
    $selectedIdx = mt_rand(0, $topN - 1);
}
```

**漂移强度计算**：
```php
$driftIntensity = min(1.0, 1.0 / sqrt($effectivePopulationSize));
// 基因池越大，漂移强度越小
```

---

### 3.5 GEP 协议构建器 ([`PromptBuilder.php`](file:///Volumes/SSD/GitHub/Evolver.php/src/PromptBuilder.php))

**GEP 1.6.0 协议** - 强制输出 5 个 JSON 对象：

```json
1. Mutation (触发器)
{
  "type": "Mutation",
  "category": "repair|optimize|innovate",
  "trigger_signals": ["..."],
  "risk_level": "low|medium|high"
}

2. PersonalityState (心态)
{
  "type": "PersonalityState",
  "rigor": 0.8,
  "creativity": 0.3,
  "risk_tolerance": 0.5
}

3. EvolutionEvent (记录)
{
  "type": "EvolutionEvent",
  "schema_version": "1.6.0",
  "parent": "evt_xxx",
  "blast_radius": {"files": 5, "lines": 120}
}

4. Gene (知识)
{
  "type": "Gene",
  "signals_match": ["..."],
  "strategy": ["step1", "step2"],
  "constraints": {"max_files": 20}
}

5. Capsule (结果快照)
{
  "type": "Capsule",
  "gene": "gene_xxx",
  "confidence": 0.85
}
```

**提示优化**：
- ✅ 上下文截断 (20000 字符限制)
- ✅ 信号去重和截断 (最多 50 个)
- ✅ 反模式区域 (失败胶囊警告)
- ✅ 历史块 (最近演化历史)
- ✅ Hub 课程块 (外部知识)

---

### 3.6 固化引擎 ([`SolidifyEngine.php`](file:///Volumes/SSD/GitHub/Evolver.php/src/SolidifyEngine.php))

**安全验证**：

```php
// 硬限制
private const MAX_FILES_HARD_LIMIT = 60;
private const MAX_LINES_HARD_LIMIT = 20000;

// 警告阈值
private const BLAST_WARN_RATIO = 0.8;      // 80%
private const BLAST_CRITICAL_RATIO = 2.0;  // 200%

// 命令白名单
private const ALLOWED_COMMAND_PREFIXES = [
    'php', 'composer', 'phpunit', 'phpcs', 'phpstan'
];

// 禁止的 shell 操作符
private const FORBIDDEN_SHELL_OPERATORS = [
    ';', '&&', '||', '|', '>', '<', '`', '$('
];
```

**关键路径保护**：
```php
private const CRITICAL_PROTECTED_PREFIXES = [
    'skills/feishu-evolver-wrapper/',
    'skills/feishu-common/',
    'skills/evolver/',
    // ...
];

private const CRITICAL_PROTECTED_FILES = [
    'MEMORY.md', 'SOUL.md', 'IDENTITY.md',
    'composer.json', 'package.json', '.env'
];
```

**验证流程**：
1. 检查自修改模式 (never/review/always)
2. 验证文件不在保护列表
3. 检查爆炸半径 (文件数/行数)
4. 验证命令白名单
5. 检测 shell 注入操作符

---

### 3.7 安全控制器 ([`SafetyController.php`](file:///Volumes/SSD/GitHub/Evolver.php/src/SafetyController.php))

**三种安全模式**：

| 模式 | 说明 | 适用场景 |
|------|------|---------|
| **never** | 完全禁用自修改，仅诊断 | 生产环境/审计模式 |
| **review** | 需要人工确认 | 开发环境 (推荐) |
| **always** | 完全自动化 | 测试环境/受信任环境 |

**操作权限矩阵**：
```
操作          | never | review | always
-------------|-------|--------|--------
read         |   ✅   |   ✅   |   ✅
diagnose     |   ✅   |   ✅   |   ✅
propose      |   ❌   |   ✅   |   ✅
modify       |   ❌   |   ❌   |   ✅
```

---

### 3.8 内容哈希 ([`ContentHash.php`](file:///Volumes/SSD/GitHub/Evolver.php/src/ContentHash.php))

**SHA-256 资产 ID**：
```php
// 规范化 JSON (键排序，数组保序)
public static function canonicalize(mixed $obj): string {
    // 递归处理对象/数组
    // 排除非有限数字
}

// 计算资产 ID (排除自引用字段)
public static function computeAssetId(
    array|object $obj, 
    array $excludeFields = ['asset_id']
): ?string {
    $canonical = self::canonicalize($clean);
    $hash = hash('sha256', $canonical);
    return 'sha256:' . $hash;
}
```

**用途**：
- ✅ 去重检测
- ✅ 篡改验证
- ✅ 跨节点一致性

---

## 4️⃣ 安全模型深度分析

### 4.1 多层防护体系

```
┌─────────────────────────────────────┐
│  SafetyController (模式控制)         │
│  - never/review/always              │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│  SourceProtector (源文件保护)        │
│  - 硬编码保护列表                    │
│  - 模式匹配 (src/Ops/*.php)          │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│  SolidifyEngine (验证引擎)           │
│  - 爆炸半径检查                      │
│  - 命令白名单                        │
│  - Shell 操作符阻止                   │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│  Gene Constraints (基因约束)         │
│  - max_files 限制                    │
│  - forbidden_paths 列表              │
└─────────────────────────────────────┘
```

### 4.2 爆炸半径限制

**硬限制** (不可逾越)：
- **60 个文件** / **20,000 行** 每次演化

**警告阈值**：
- 80% 利用率 → 警告
- 200% 利用率 → 严重警告 (可能批量误操作)

**目录分布分析**：
```php
// 自动分析哪些目录贡献最多变更文件
$dirCount = [];
foreach ($changedFiles as $file) {
    $parts = explode('/', $rel);
    $key = $parts[0] . '/' . $parts[1];  // 前两级目录
    $dirCount[$key]++;
}
```

---

## 5️⃣ 测试套件分析

### 5.1 测试覆盖

**测试文件**：44 个测试类
- 核心引擎：`DatabaseTest`, `SignalExtractorTest`, `GeneSelectorTest`
- MCP 层：`McpServerTest`
- 安全：`SafetyControllerTest`, `SourceProtectorTest`
- 运维工具：`Ops/` 目录下 12 个测试

**测试策略**：
- ✅ 内存 SQLite (`:memory:`) 实现隔离
- ✅ setUp/tearDown 清理
- ✅ 断言完整 (assertContains, assertNotEmpty, assertIsArray)

### 5.2 测试示例

```php
// DatabaseTest.php
public function testDatabaseCreatesSchema(): void
{
    $result = $this->db->fetchAll(
        "SELECT name FROM sqlite_master WHERE type='table'"
    );
    $tables = array_column($result, 'name');
    $this->assertContains('genes', $tables);
    $this->assertContains('capsules', $tables);
}

// SignalExtractorTest.php
public function testExtractRepairLoopDetected(): void
{
    $recentEvents = [
        ['intent' => 'repair', 'outcome' => ['status' => 'failed']],
        ['intent' => 'repair', 'outcome' => ['status' => 'failed']],
        ['intent' => 'repair', 'outcome' => ['status' => 'failed']],
    ];
    $signals = $this->extractor->extract([
        'context' => 'Some context',
        'recentEvents' => $recentEvents,
    ]);
    $this->assertContains('repair_loop_detected', $signals);
}
```

---

## 6️⃣ 运维工具 (Ops 模块)

### 6.1 可用工具

| 工具 | 职责 |
|------|------|
| **LifecycleManager** | 启动/关闭生命周期管理 |
| **HealthCheck** | 系统健康检查 |
| **DiskCleaner** | 清理旧日志和临时文件 |
| **SignalDeduplicator** | 信号去重 |
| **SecurityAuditLogger** | 安全审计日志 |
| **SkillsMonitor** | 技能目录监控 |
| **GitSelfRepair** | Git 自修复 |
| **Innovation** | 创新触发器 |
| **Trigger** | 事件触发器 |
| **Commentary** | 注释生成 |
| **StructuredLogger** | 结构化日志 |
| **DaemonManager** | 守护进程管理 |

### 6.2 命令行工具

```bash
# 验证安装
php evolver.php --validate

# 使用自定义数据库
php evolver.php --db /path/to.db

# 连续循环模式
php evolver.php --loop [interval_seconds]

# 守护进程模式
php evolver.php --daemon start
php evolver.php --daemon stop
php evolver.php --daemon status

# Ops 命令
php evolver.php --ops cleanup
php evolver.php --ops health
php evolver.php --ops stats
php evolver.php --ops gc
php evolver.php --ops dedupe
```

---

## 7️⃣ GEP 协议详解

### 7.1 协议流程

```
1. evolver_run 工具调用
   ↓
2. SignalExtractor.extract() 提取信号
   ↓
3. GeneSelector.selectGene() 选择基因
   ↓
4. PromptBuilder.buildGepPrompt() 构建提示
   ↓
5. LLM 输出 5 个 JSON 对象
   ↓
6. 应用更改 (MCP 客户端执行)
   ↓
7. evolver_solidify 固化结果
   ↓
8. 记录 EvolutionEvent + 更新 Gene/Capsule
```

### 7.2 协议版本演进

| 版本 | 变更 |
|------|------|
| **1.5.0** | 引入 asset_id (SHA-256) |
| **1.6.0** | 新增 env_fingerprint, success_streak, sync_status 表 |

**版本不一致问题**：
- ⚠️ `ContentHash::SCHEMA_VERSION = '1.6.0'`
- ⚠️ `PromptBuilder::SCHEMA_VERSION = '1.5.0'` (在代码中未明确，需检查)

---

## 8️⃣ 默认基因分析

### 8.1 种子基因 (6 个)

[`data/default_genes.json`](file:///Volumes/SSD/GitHub/Evolver.php/data/default_genes.json)

| 基因 ID | 分类 | 用途 |
|--------|------|------|
| `gene_gep_repair_from_errors` | repair | 从错误中修复 |
| `gene_gep_optimize_prompt_and_assets` | optimize | 优化提示和资产 |
| `gene_gep_innovate_from_opportunity` | innovate | 从机会创新 |
| `gene_gep_repair_sqlite` | repair | SQLite 数据库修复 |
| `gene_gep_harden_security` | optimize | 安全加固 |

### 8.2 基因结构

```json
{
  "type": "Gene",
  "id": "gene_gep_repair_from_errors",
  "category": "repair",
  "signals_match": ["error", "exception", "log_error"],
  "preconditions": ["signals contains error-related indicators"],
  "strategy": [
    "Extract structured signals from logs",
    "Select an existing Gene by signals match",
    "Estimate blast radius before editing",
    "Apply smallest reversible patch",
    "Validate using declared validation steps"
  ],
  "constraints": {
    "max_files": 20,
    "forbidden_paths": [".git", "vendor", "node_modules"]
  },
  "validation": ["php -l src/*.php", "php evolver.php --validate"]
}
```

---

## 9️⃣ A2A 协议 (Agent-to-Agent)

### 9.1 核心功能

[`A2A.php`](file:///Volumes/SSD/GitHub/Evolver.php/src/A2A.php)

- **资产类型**：Gene, Capsule, EvolutionEvent
- **置信度衰减**：外部资产置信度 × 0.6
- **爆炸半径限制**：maxFiles=5, maxLines=200
- **成功条纹计算**：连续成功使用次数

### 9.2 同步机制

```php
// sync_status 表追踪同步状态
CREATE TABLE sync_status (
    asset_type TEXT NOT NULL,  // 'Gene' | 'Capsule' | 'Event'
    local_id TEXT NOT NULL,
    asset_id TEXT,             // SHA-256
    sync_status TEXT,          // 'pending' | 'synced' | 'failed'
    last_sync_attempt TEXT,
    sync_error TEXT
);
```

---

## 🔟 知识图谱 ([`MemoryGraph.php`](file:///Volumes/SSD/GitHub/Evolver.php/src/MemoryGraph.php))

### 10.1 功能

- **信号→基因→结果** 边追踪
- **Laplace 平滑成功概率**
- **衰减机制** (时间衰减)
- **错误签名规范化**

### 10.2 错误签名规范化

```php
// 路径替换
s = preg_replace('/[a-z]:\\[^\\s\\n\\r\\t]+/i', '<path>', s);
s = preg_replace('~/[^\\s\\n\\r\\t]+~', '<path>', s);

// 十六进制和数字替换
s = preg_replace('/\\b0x[0-9a-f]+\\b/i', '<hex>', s);
s = preg_replace('/\\b\\d+\\b/', '<n>', s);

// 输出：errsig_norm:<hash>
```

---

## 1️⃣1️⃣ 代码质量评估

### 11.1 优点 ✅

| 维度 | 评分 | 说明 |
|------|------|------|
| **类型安全** | ⭐⭐⭐⭐⭐ | 全文件 `declare(strict_types=1)` |
| **错误处理** | ⭐⭐⭐⭐⭐ | try-catch + error_log + 返回结果数组 |
| **文档注释** | ⭐⭐⭐⭐ | 大部分公开方法有 PHPDoc |
| **命名规范** | ⭐⭐⭐⭐⭐ | PascalCase 类，camelCase 方法，SCREAMING 常量 |
| **测试覆盖** | ⭐⭐⭐⭐ | 44 个测试类，核心功能全覆盖 |
| **安全性** | ⭐⭐⭐⭐⭐ | 多层防护，硬编码限制 |
| **性能优化** | ⭐⭐⭐⭐ | WAL + mmap + 缓存优化 |

### 11.2 潜在问题 ⚠️

| 问题 | 严重性 | 建议 |
|------|--------|------|
| **Schema 版本不一致** | 中 | 统一 `ContentHash` 和 `PromptBuilder` 的版本号 |
| **无静态分析工具** | 低 | 添加 PHPStan/Psalm 到 composer.json |
| **部分方法缺少文档** | 低 | 补充复杂方法的 PHPDoc |
| **硬编码路径** | 低 | 使用常量或配置文件 |
| **MCP 客户端兼容性** | 中 | Gemini CLI 有已知问题，文档已说明 |

---

## 1️⃣2️⃣ 与原始 evolver 对比

| 特性 | EvoMap/evolver (JS) | Evolver.php |
|------|---------------------|-------------|
| **语言** | JavaScript/Node.js | PHP 8.3+ |
| **数据库** | SQLite | SQLite (相同) |
| **协议** | MCP stdio | MCP stdio (1:1 移植) |
| **GEP 版本** | 1.6.0 | 1.6.0 |
| **安全模型** | 爆炸半径限制 | 相同 + 额外保护 |
| **测试** | Jest | PHPUnit |
| **性能** | Node.js V8 引擎 | PHP 8.3 JIT (可选) |

**优势**：
- ✅ 零 npm 依赖，仅 Composer
- ✅ 更简单的部署 (单个 PHP 文件 + SQLite)
- ✅ 完全本地化，无网络依赖
- ✅ 增强的安全模型 (SourceProtector)

---

## 1️⃣3️⃣ 使用场景推荐

### 13.1 适用场景 ✅

1. **AI 辅助开发环境** - 与 Claude Desktop/Kimi CLI 集成
2. **自演化代码库** - 自动修复错误、优化性能
3. **知识积累系统** - Gene/Capsule 双轨存储成功经验
4. **安全沙箱实验** - review 模式下人工确认所有修改
5. **持续集成** - 自动检测和修复测试失败

### 13.2 不适用场景 ❌

1. **高并发 Web 服务** - 非设计目标
2. **分布式系统** - 单节点 SQLite 限制
3. **实时性要求高** - 演化周期需要时间
4. **无 AI 环境** - 依赖 LLM 生成代码

---

## 1️⃣4️⃣ 最佳实践建议

### 14.1 部署配置

```bash
# 推荐环境变量
export EVOLVER_DB_PATH=~/.evolver/evolver.db
export EVOLVE_ALLOW_SELF_MODIFY=review  # 开发环境
export WORKSPACE_DIR=/path/to/workspace

# MCP 配置 (Kimi CLI)
{
  "mcpServers": {
    "evolver": {
      "command": "php",
      "args": ["/path/to/evolver.php"],
      "env": {
        "EVOLVER_DB_PATH": "~/.evolver/evolver.db",
        "EVOLVE_ALLOW_SELF_MODIFY": "review"
      }
    }
  }
}
```

### 14.2 运维建议

1. **定期备份数据库**：
   ```bash
   cp ~/.evolver/evolver.db ~/.evolver/evolver.db.backup.$(date +%Y%m%d)
   ```

2. **监控健康状态**：
   ```bash
   php evolver.php --validate
   php evolver.php --ops health
   ```

3. **清理旧数据**：
   ```bash
   php evolver.php --ops cleanup
   php evolver.php --ops gc
   ```

4. **审查安全日志**：
   ```bash
   cat ~/.evolver/security_audit.log
   ```

### 14.3 开发建议

1. **始终运行测试**：
   ```bash
   composer test  # 或 phpunit --testdox
   ```

2. **使用 review 模式**：
   - 开发环境：`EVOLVE_ALLOW_SELF_MODIFY=review`
   - 生产环境：`EVOLVE_ALLOW_SELF_MODIFY=never`

3. **自定义基因**：
   - 在 `data/default_genes.json` 添加
   - 或使用 `evolver_upsert_gene` 工具

4. **监控爆炸半径**：
   - 定期检查 `evolver_stats`
   - 调整基因 `max_files` 约束

---

## 1️⃣5️⃣ 未来改进方向

### 15.1 短期优化 🔧

1. **统一 Schema 版本号** - 修复 `PromptBuilder` 版本不一致
2. **添加静态分析** - PHPStan/Psalm 集成
3. **改进错误消息** - 更友好的用户提示
4. **性能分析工具** - 添加 Xdebug 配置示例

### 15.2 长期扩展 🚀

1. **多数据库支持** - PostgreSQL/MySQL 适配器
2. **Web UI** - 可视化演化历史和统计
3. **分布式同步** - 多节点 A2A 同步优化
4. **机器学习集成** - 基于历史数据预测最佳基因
5. **插件系统** - 允许第三方扩展 Ops 模块

---

## 📊 综合评分

| 维度 | 评分 | 说明 |
|------|------|------|
| **架构设计** | ⭐⭐⭐⭐⭐ | 清晰分层，职责分离 |
| **代码质量** | ⭐⭐⭐⭐⭐ | 严格类型，完善错误处理 |
| **安全性** | ⭐⭐⭐⭐⭐ | 多层防护，硬编码限制 |
| **测试覆盖** | ⭐⭐⭐⭐ | 核心功能全覆盖，可增加边缘用例 |
| **文档完整性** | ⭐⭐⭐⭐ | README/AGENTS.md 完善，缺少 API 文档 |
| **性能优化** | ⭐⭐⭐⭐ | SQLite 优化到位，可考虑缓存层 |
| **可维护性** | ⭐⭐⭐⭐⭐ | 模块化设计，易于扩展 |
| **创新性** | ⭐⭐⭐⭐⭐ | 自演化概念前沿 |

**总体评分**：**⭐⭐⭐⭐⭐ (4.8/5)**

---

## 🎯 结论

**Evolver.php** 是一个**工业级**的自演化引擎实现，具有以下核心优势：

1. ✅ **成熟稳定** - 1:1 移植自经过验证的 JavaScript 版本
2. ✅ **安全可靠** - 多层防护体系，硬编码安全限制
3. ✅ **易于部署** - 零复杂依赖，单个 PHP 文件即可运行
4. ✅ **测试完备** - 44 个测试类覆盖核心功能
5. ✅ **文档完善** - README/AGENTS.md 提供详细指南

**推荐使用场景**：
- AI 辅助开发环境的后端引擎
- 需要自修复能力的代码库
- 知识积累和经验复用系统

**注意事项**：
- 生产环境建议使用 `review` 或 `never` 模式
- 定期备份 SQLite 数据库
- 监控爆炸半径和演化频率

---                                    

需要登录才能发表回复

登录注册