Safe Evolver

A safe AI agent evolution engine that analyzes runtime history to identify improvements and applies protocol-constrained evolution with comprehensive safety...

Security Scan

The skill's code and instructions are generally consistent with its stated purpose: it analyzes and logs agent interactions and suggests simple improvements; there are no network calls or secret requests, but it writes history/log files to disk and the SKILL.md describes some advanced features that the shipped code does not implement.

Purpose & Capability

The package implements history recording, local analysis, suggestion generation, and logging which matches the described 'evolver' purpose. However, SKILL.md documents more advanced features (LLM integration, audit export formats, in-depth reports) that are not implemented in index.js — this is a feature-documentation mismatch but not evidence of malicious intent.

Instruction Scope

SKILL.md includes examples that reference tool calls and file reads (e.g., 'ls -la', reading '/etc/passwd') as part of recorded interaction data. The instructions do not themselves instruct the agent to perform system-wide reads or exfiltrate data, but the skill will store any interaction data you provide. Users should avoid recording sensitive file contents into the evolver's history/logs.

Install Mechanism

This is an instruction-and-code skill with no install spec beyond normal npm usage; there are no external downloads or install scripts. package.json references a GitHub repo and a homepage URL, which is normal.

Credentials

The skill requests no environment variables or credentials. SKILL.md shows an optional llm.apiKey example, but the shipped code does not use external LLM APIs or require credentials.

Persistence & Privilege

The module creates directories and writes logs/history to disk (defaults: ./logs/evolution.log and ./data/evolution_history.json). This is expected for a history-based tool but means it will persist whatever interaction data you send it—consider controlling the paths and file permissions.

Assessment

This package appears to do what it says: record interactions, analyze local history, and generate suggestions. Before installing or using it: - Expect it to create ./logs and ./data directories and to persist interaction data; do not record sensitive secrets or file contents into the evolver. Change logPath/historyFile to a safe location and set restrictive file permissions if needed. - Note that SKILL.md mentions LLM integration and export features that are not implemented in the provided index.js; if you need those capabilities, verify the upstream source or implement them yourself. - Because it writes files, run it in a controlled environment (or container) first and review the created files to confirm no unexpected behavior. If you plan to use it in production, inspect the repository (homepage/repo) and confirm provenance before trusting logs/history data.

📖 功能描述

Safe Evolver 是一个安全的 AI 代理自我进化引擎，通过分析运行时历史来识别改进机会，并应用受控的协议约束进化。

核心价值：帮助 AI 代理从执行历史中学习，持续优化行为模式，同时确保进化过程的安全可控。

---

✨ 核心功能

1. 历史分析 📊

• 记录工具调用、响应、错误等信息
• 分析行为模式和效率指标
• 识别优化机会

2. 改进识别 🔍

• 自动检测低效操作
• 识别常见错误模式
• 建议行为改进

3. 安全进化 🔄

• 应用协议约束的进化机制
• 确保所有改进都经过安全检查
• 提供透明的进化过程

4. 风险控制 ⚠️

• 防止有害的进化路径
• 审计所有改进建议
• 支持人类审核

---

🚀 快速开始

安装

# 通过 ClawHub 安装
clawhub install safe-evolver

# 或本地安装
npm install safe-evolver

基本使用

const SafeEvolver = require('safe-evolver');
const evolver = new SafeEvolver({
  mode: 'auto',  // 'auto' | 'manual' | 'disabled'
  logPath: './logs/evolution.log'
});

// 记录一次交互
evolver.recordInteraction({
  toolCalls: 6,
  responses: 4,
  errors: 0,
  efficiency: 0.85
});

// 获取进化报告
const report = evolver.getReport();
console.log(report);

---

📚 详细使用方法

1. 初始化配置

基础配置

const evolver = new SafeEvolver({
  // 进化模式
  mode: 'auto',  // 'auto' | 'manual' | 'disabled'

  // 日志路径
  logPath: './logs/evolution.log',

  // 是否启用审计
  enableAudit: true,

  // 进化频率（记录多少次后建议改进）
  evolutionFrequency: 10,

  // 安全级别
  safetyLevel: 'high'  // 'low' | 'medium' | 'high'
});

高级配置

const evolver = new SafeEvolver({
  mode: 'manual',

  // LLM 配置（用于智能分析）
  llm: {
    enabled: true,
    model: 'qwen2.5:3b',
    apiKey: 'your-api-key'
  },

  // 分析维度
  analysis: {
    efficiency: true,      // 效率分析
    errorPatterns: true,   // 错误模式
    resourceUsage: true,   // 资源使用
    responseQuality: true, // 响应质量
    toolOptimization: true // 工具使用优化
  },

  // 改进建议阈值
  thresholds: {
    minImprovement: 0.05,  // 最小改进率
    maxSuggestions: 10     // 最多建议数量
  },

  // 审计配置
  audit: {
    includeAllData: true,
    exportFormat: 'json'
  }
});

2. 记录交互

基础交互记录

// 单次交互
evolver.recordInteraction({
  toolCalls: 6,
  responses: 4,
  errors: 0,
  efficiency: 0.85,
  duration: 23.5
});

// 详细交互记录
evolver.recordInteraction({
  interactionId: 'sess-123',  // 交互ID
  startTime: '2026-04-06T10:00:00Z',
  endTime: '2026-04-06T10:00:23Z',

  // 工具调用
  toolCalls: [
    {
      tool: 'exec',
      command: 'ls -la',
      success: true,
      duration: 0.1
    },
    {
      tool: 'read',
      path: '/etc/passwd',
      success: true,
      duration: 0.05
    }
  ],

  // 响应
  responses: [
    {
      content: '这是执行结果...',
      quality: 0.8
    }
  ],

  // 错误
  errors: [],

  // 资源使用
  resources: {
    memory: 120,  // MB
    cpu: 15,      // %
    disk: 0       // MB
  },

  // 效率评分
  efficiency: 0.85,

  // 上下文
  context: {
    task: '列出用户目录内容',
    sessionType: 'general'
  }
});

3. 获取进化报告

基础报告

const report = evolver.getReport();

console.log(report);

// 输出示例:
/*
{
  interactionCount: 50,
  avgEfficiency: 0.78,
  totalErrors: 3,
  lastReport: '2026-04-06T22:00:00Z',

  improvements: [
    {
      category: '效率',
      issue: '工具调用过多',
      suggestion: '减少不必要的 ls 命令',
      priority: 'high',
      estimatedImpact: 0.15
    }
  ],

  warnings: [
    {
      category: '资源',
      issue: '内存使用偏高',
      current: 120,
      threshold: 100,
      advice: '考虑使用轻量级工具'
    }
  ],

  safetyScore: 0.95
}
*/

详细报告

const detailedReport = evolver.getDetailedReport();

console.log(detailedReport);

// 输出示例:
/*
{
  summary: { ... },

  efficiencyAnalysis: {
    score: 0.78,
    breakdown: [
      { metric: '工具效率', score: 0.75 },
      { metric: '响应效率', score: 0.82 },
      { metric: '错误恢复', score: 0.90 }
    ],
    opportunities: [
      '可以合并多个 ls 命令',
      '减少重复的文件读取'
    ]
  },

  errorAnalysis: {
    totalErrors: 3,
    errorTypes: {
      'Permission Denied': 2,
      'File Not Found': 1
    },
    recommendations: [
      '添加文件存在检查',
      '使用更安全的权限模式'
    ]
  },

  resourceAnalysis: {
    memoryUsage: {
      avg: 120,
      peak: 150,
      trend: 'stable'
    },
    cpuUsage: {
      avg: 15,
      peak: 25,
      pattern: 'sporadic'
    }
  },

  suggestions: [
    {
      id: 1,
      category: '效率',
      title: '减少重复的文件读取',
      description: '检测到多次读取同一个文件，建议缓存或批量读取',
      priority: 'medium',
      implementation: '需要修改代码',
      estimatedBenefit: 0.10
    }
  ]
}
*/

4. 手动触发分析

主动分析

// 触发深度分析
evolver.analyze(
  {
    efficiency: true,
    errorPatterns: true,
    toolOptimization: true
  },
  (report) => {
    console.log('分析完成:', report);
  }
);

// 获取特定维度的报告
const efficiencyReport = evolver.getEfficiencyReport();
const errorReport = evolver.getErrorReport();
const resourceReport = evolver.getResourceReport();

5. 应用于改进

获取改进建议

const suggestions = evolver.getSuggestions({
  category: 'efficiency',  // 可选: 'efficiency' | 'errors' | 'all'
  limit: 5,
  priority: 'high'        // 可选: 'low' | 'medium' | 'high' | 'all'
});

console.log(suggestions);

// 输出示例:
/*
[
  {
    id: 'eff-001',
    category: '效率',
    title: '减少工具调用数量',
    description: '当前每次任务平均调用 6 次工具，建议优化到 4 次',
    priority: 'high',
    estimatedImpact: 0.20,
    actions: [
      '合并多个 ls 命令',
      '批量读取文件内容'
    ]
  }
]
*/

应用改进

// 应用单个建议
evolver.applyImprovement('eff-001', {
  tool: 'exec',
  command: 'ls -la /tmp/*',
  comment: '合并多个 ls 命令'
});

// 应用多个建议
const improvements = evolver.getImprovementsReadyToApply();
improvements.forEach(improvement => {
  evolver.applyImprovement(improvement.id);
});

---

🎯 使用场景

场景 1: AI 代理性能优化

const evolver = new SafeEvolver({
  mode: 'auto',
  safetyLevel: 'high'
});

// 在交互循环中使用
async function runAgent(task) {
  let interactionCount = 0;

  while (true) {
    // 记录当前状态
    const metrics = {
      toolCalls: currentToolCalls,
      responses: currentResponses,
      errors: currentErrors,
      efficiency: calculateEfficiency()
    };

    // 记录交互
    evolver.recordInteraction(metrics);
    interactionCount++;

    // 检查是否需要建议
    if (interactionCount % evolver.config.evolutionFrequency === 0) {
      const report = evolver.getReport();
      if (report.needsImprovement) {
        const suggestions = evolver.getSuggestions();

        // 显示给用户或自动应用
        console.log('改进建议:', suggestions);

        // 应用最佳建议
        const best = suggestions.find(s => s.priority === 'high');
        if (best) {
          applySuggestion(best);
        }
      }
    }

    // 执行任务...
  }
}

场景 2: 错误模式分析

const evolver = new SafeEvolver({
  mode: 'manual',
  analysis: {
    errorPatterns: true
  }
});

// 记录交互
evolver.recordInteraction({
  errors: [
    { type: 'FileNotFound', path: '/etc/config' },
    { type: 'PermissionDenied', path: '/root/.ssh' }
  ]
});

// 获取错误报告
const errorReport = evolver.getErrorReport();

console.log('常见错误:', errorReport.commonErrors);
console.log('错误模式:', errorReport.patterns);
console.log('建议:', errorReport.suggestions);

// 根据建议改进代码
if (errorReport.patterns.includes('FileNotFound')) {
  addFileExistCheck();
}

场景 3: 资源使用优化

const evolver = new SafeEvolver({
  mode: 'manual',
  analysis: {
    resourceUsage: true
  }
});

// 监控资源使用
setInterval(() => {
  const metrics = {
    resources: {
      memory: getMemoryUsage(),
      cpu: getCPUUsage(),
      disk: getDiskUsage()
    }
  };

  evolver.recordInteraction(metrics);

  const resourceReport = evolver.getResourceReport();

  // 如果资源使用超过阈值，给出建议
  if (resourceReport.issues.some(i => i.severity === 'high')) {
    console.warn('资源警告:', resourceReport.issues);
  }
}, 60000); // 每分钟记录一次

---

⚙️ 配置文件

Safe Evolver 支持通过配置文件初始化。

配置文件格式 (config.json)

{
  "mode": "auto",
  "safetyLevel": "high",
  "logPath": "./logs/evolution.log",

  "llm": {
    "enabled": true,
    "model": "qwen2.5:3b"
  },

  "analysis": {
    "efficiency": true,
    "errorPatterns": true,
    "resourceUsage": true,
    "responseQuality": true,
    "toolOptimization": true
  },

  "thresholds": {
    "minImprovement": 0.05,
    "maxSuggestions": 10
  },

  "audit": {
    "enabled": true,
    "exportFormat": "json"
  }
}

使用配置文件

const evolver = new SafeEvolver('./config.json');

---

🔒 安全特性

特性	说明
安全进化	所有改进都经过安全检查
审计追踪	完整的进化历史记录
手动审核	支持人类审核改进建议
风险控制	防止有害的进化路径
透明可追溯	所有建议都可审查

---

📊 效率评分

Evolver 会计算效率评分（0-1）：

效率评分 = (工具效率 × 0.4) + (响应效率 × 0.3) + (错误恢复 × 0.3)

评分等级：

• ✅ 优秀 (0.85-1.0): 表现卓越
• ✅ 良好 (0.7-0.84): 表现良好
• ⚠️ 一般 (0.5-0.69): 需要改进
• ❌ 较差 (0-0.49): 需要大幅改进

---

🛠️ 开发与测试

运行测试

# 安装依赖
npm install

# 运行测试
npm test

测试示例

// test.js
const evolver = new SafeEvolver();

// 模拟交互
evolver.recordInteraction({
  toolCalls: 5,
  responses: 3,
  errors: 0,
  efficiency: 0.8
});

evolver.recordInteraction({
  toolCalls: 7,
  responses: 4,
  errors: 1,
  efficiency: 0.6
});

// 获取报告
const report = evolver.getReport();
console.log('效率评分:', report.avgEfficiency);
console.log('改进建议:', report.improvements);

// 获取建议
const suggestions = evolver.getSuggestions();
console.log('建议数量:', suggestions.length);

---

📝 API 参考

构造函数

new SafeEvolver(config?)

参数:

• config (Object): 配置对象

方法

方法	返回	说明
recordInteraction(data)	void	记录交互数据
getReport()	Object	获取进化报告
getDetailedReport()	Object	获取详细报告
getSuggestions(options?)	Array	获取改进建议
applyImprovement(id, data?)	void	应用改进
getEfficiencyReport()	Object	获取效率报告
getErrorReport()	Object	获取错误报告
getResourceReport()	Object	获取资源报告
analyze(config?, callback?)	void	触发分析
exportReport(path?)	void	导出报告

recordInteraction 参数

{
  interactionId?: string,
  startTime?: string,
  endTime?: string,
  toolCalls?: Array<{...}>,
  responses?: Array<{...}>,
  errors?: Array<{...}>,
  resources?: {...},
  efficiency?: number,
  context?: {...}
}

---

📖 使用示例

完整示例：智能优化系统

const SafeEvolver = require('safe-evolver');

// 初始化
const evolver = new SafeEvolver({
  mode: 'auto',
  safetyLevel: 'high',
  evolutionFrequency: 10
});

// 优化监控循环
function monitorOptimization() {
  setInterval(() => {
    const report = evolver.getReport();

    if (report.needsImprovement) {
      const suggestions = evolver.getSuggestions({ limit: 3 });

      console.log('\n🔍 进化分析:');
      suggestions.forEach((s, i) => {
        console.log(`${i + 1}. [${s.category}] ${s.title}`);
        console.log(`   建议效果: +${s.estimatedImpact}`);
      });

      // 应用高优先级建议
      const highPriority = suggestions.filter(s => s.priority === 'high');
      highPriority.forEach(s => {
        console.log(`\n✅ 应用改进: ${s.title}`);
        applySuggestion(s);
      });
    }
  }, 300000); // 每5分钟分析一次
}

// 应用建议函数
function applySuggestion(suggestion) {
  switch (suggestion.category) {
    case '效率':
      optimizeToolCalls(suggestion);
      break;
    case '错误':
      improveErrorHandling(suggestion);
      break;
    case '资源':
      optimizeResourceUsage(suggestion);
      break;
  }
}

function optimizeToolCalls(suggestion) {
  // 实现工具调用优化逻辑
  console.log('优化工具调用策略...');
}

function improveErrorHandling(suggestion) {
  // 实现错误处理改进逻辑
  console.log('改进错误处理机制...');
}

function optimizeResourceUsage(suggestion) {
  // 实现资源使用优化逻辑
  console.log('优化资源使用...');
}

// 启动监控
monitorOptimization();

---

🐛 常见问题

Q1: 什么时候触发进化分析？

A:

• auto 模式: 每 N 次交互后自动分析（可配置）
• manual 模式: 手动调用 analyze() 方法
• disabled 模式: 不自动分析

Q2: 改进建议如何应用到实际代码？

A:

1. 获取建议：evolver.getSuggestions()
2. 审查建议内容
3. 根据建议修改代码
4. 记录应用结果
5. Evolver 会学习这些改进

Q3: 如何禁用某个分析维度？

A:

const evolver = new SafeEvolver({
  analysis: {
    efficiency: false,    // 禁用效率分析
    errorPatterns: true,  // 启用错误分析
    resourceUsage: false  // 禁用资源分析
  }
});

Q4: 进化报告存储在哪里？

A:

• 内存中：evolver.getReport()
• 日志文件：evolver.config.logPath
• 可导出：evolver.exportReport('./report.json')

---

📄 许可证

MIT-0 License

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

📞 联系方式

• Issue: https://github.com/your-repo/safe-evolver/issues
• 文档: https://docs.your-repo.com/safe-evolver

---

🎉 更新日志

v1.1.0 (2026-04-06)

• ✨ 添加详细的中文文档和使用示例
• ✨ 改进报告生成算法
• ✨ 支持更多分析维度
• ✨ 优化建议的优先级算法
• 🐛 修复某些边缘情况

v1.0.0 (2026-04-05)

• 🎉 初始版本发布