🧬 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（成功结果快照）

技术栈

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)

职责：实现 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)

Schema 版本：1.6.0

核心表结构：

-- 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
);

性能优化：

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)

信号类型 (35+ 种)：

// 修复循环检测 (连续 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)

选择算法：

// 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);
}

漂移强度计算：

$driftIntensity = min(1.0, 1.0 / sqrt($effectivePopulationSize));
// 基因池越大，漂移强度越小

---

3.5 GEP 协议构建器 (PromptBuilder.php)

GEP 1.6.0 协议 - 强制输出 5 个 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)

安全验证：

// 硬限制
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 = [
    ';', '&&', '||', '|', '>', '<', '`', '$('
];

关键路径保护：

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)

三种安全模式：

操作          | never | review | always
-------------|-------|--------|--------
read         |   ✅   |   ✅   |   ✅
diagnose     |   ✅   |   ✅   |   ✅
propose      |   ❌   |   ✅   |   ✅
modify       |   ❌   |   ❌   |   ✅

---

3.8 内容哈希 (ContentHash.php)

SHA-256 资产 ID：

// 规范化 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% 利用率 → 严重警告 (可能批量误操作)

// 自动分析哪些目录贡献最多变更文件
$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 测试示例

// 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 可用工具

6.2 命令行工具

# 验证安装
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 协议版本演进

• ⚠️ ContentHash::SCHEMA_VERSION = '1.6.0'
• ⚠️ PromptBuilder::SCHEMA_VERSION = '1.5.0' (在代码中未明确，需检查)

8️⃣ 默认基因分析

8.1 种子基因 (6 个)

data/default_genes.json

8.2 基因结构

{
  "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

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

9.2 同步机制

// 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)

10.1 功能

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

10.2 错误签名规范化

// 路径替换
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 优点 ✅

11.2 潜在问题 ⚠️

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

• ✅ 零 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 部署配置

# 推荐环境变量
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. 定期备份数据库：

   cp ~/.evolver/evolver.db ~/.evolver/evolver.db.backup.$(date +%Y%m%d)
   

2. 监控健康状态：

   php evolver.php --validate
   php evolver.php --ops health
   

3. 清理旧数据：

   php evolver.php --ops cleanup
   php evolver.php --ops gc
   

4. 审查安全日志：

   cat ~/.evolver/security_audit.log
   

14.3 开发建议

1. 始终运行测试：

   composer test  # 或 phpunit --testdox
   

2. 使用 review 模式：

• 开发环境：EVOLVE_ALLOW_SELF_MODIFY=review
• 生产环境：EVOLVE_ALLOW_SELF_MODIFY=never

• 在 data/default_genes.json 添加
• 或使用 evolver_upsert_gene 工具

• 定期检查 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 模块

---

📊 综合评分

---

🎯 结论

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

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

推荐使用场景：

• AI 辅助开发环境的后端引擎
• 需要自修复能力的代码库
• 知识积累和经验复用系统

• 生产环境建议使用 review 或 never 模式
• 定期备份 SQLite 数据库
• 监控爆炸半径和演化频率

https://github.com/linkerlin/Evolver.php