Skill Evolution Plugin - 架构设计

版本：0.1.0-mvp
最后更新：2026-03-27

🎯 系统概述

Skill Evolution Plugin 是一个 OpenClaw 插件，用于自动捕获 Skill 使用过程中的修正行为，通过模式识别生成优化建议，最终实现 Skill 的自进化。

🏗️ 架构概览

┌─────────────────────────────────────────────────────────────────┐
│                        用户 (User)                               │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                   OpenClaw Gateway                              │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │         Skill Evolution Plugin (我们的插件)                │  │
│  │  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐  │  │
│  │  │ Interceptor │  │  Analyzer    │  │  Patch Manager  │  │  │
│  │  │ (拦截器)    │  │  (分析器)    │  │  (补丁管理)     │  │  │
│  │  └─────────────┘  └──────────────┘  └─────────────────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                    文件系统 (File System)                        │
│  ~/.openclaw/skills/<skill-name>/.evolution/                    │
│  ├── execution-log.jsonl    (执行日志)                          │
│  ├── patches/               (用户补丁)                          │
│  ├── manifest.json          (版本管理)                          │
│  └── local-config.yaml     (本地配置)                          │
└─────────────────────────────────────────────────────────────────┘

📦 核心模块

1. Interceptor（拦截器）

职责：监控 Skill 执行过程，记录工具调用和修正行为

文件：src/interceptor.js

核心方法：

class SkillInterceptor {
  startSession(sessionId, skillName, userRequest)
  recordToolCall(sessionId, toolName, params, result, options)
  endSession(sessionId, outcome)
  setExpectedPlan(sessionId, plan)
}

数据流：

用户请求 → startSession() → recordToolCall() × N → endSession()
                ↓                ↓                      ↓
          创建会话对象      记录工具调用            保存日志到文件

关键设计：

使用 Map 存储活跃会话
支持检测修正行为（correctedFrom）
支持检测重试行为（retryCount）
日志格式：JSONL（便于流式处理）

2. Analyzer（分析器）

职责：分析执行日志，识别模式，生成优化建议

文件：src/analyzer.js

核心方法：

class SkillAnalyzer {
  readExecutionLogs(skillName, limit)
  analyze(skillName)
  clusterModifications(logs)
  generateSuggestion(cluster)
  generateReport(skillName)
}

算法流程：

读取日志 → 统计成功率 → 聚类修改 → 过滤模式 → 生成建议
   ↓          ↓           ↓          ↓          ↓
JSONL    successRate  clusterBy  threshold  suggestion
                     (type+tool)  (>=3)     object

聚类算法：

// 聚类键：修改类型 + 工具名称
const key = `${mod.type}_${mod.tool}`;

// 示例：
// "correction_agent-browser.click"
// "retry_agent-browser.snapshot"

阈值机制：

默认阈值：3 次相似修改
可配置：threshold 参数
目的：避免误报，确保模式可靠性

3. Patch Manager（补丁管理）

职责：管理补丁的生成、存储和应用

文件：src/patch-manager.js

核心方法：

class PatchManager {
  createPatch(skillName, oldContent, newContent, description)
  listPatches(skillName)
  applyPatch(skillName, patchPath)
  updateManifest(skillName, patchInfo)
}

补丁格式：

--- Skill Evolution Patch ---
{
  "created": "2026-03-27T22:00:00Z",
  "skill": "agent-browser",
  "description": "Add retry logic",
  "patch_file": "001-20260327-add-retry-logic.patch"
}
---
diff --git a/SKILL.md b/SKILL.md
--- a/SKILL.md
+++ b/SKILL.md
@@ -15,6 +15,12 @@
 ## Core Workflow
 1. Navigate: agent-browser open <url>
 2. Snapshot: agent-browser snapshot -i
+3. Retry Logic: If step fails, re-snapshot and retry
...

版本管理：

{
  "skill": "agent-browser",
  "base_version": "1.2.3",
  "local_patches": ["001", "002"],
  "last_updated": "2026-03-27T22:10:00Z"
}

4. CLI（命令行工具）

职责：提供用户交互界面

文件：bin/cli.js

命令：

skill-evolution demo              # 运行演示
skill-evolution analyze <skill>   # 分析模式（JSON 输出）
skill-evolution report <skill>    # 生成人类可读报告
skill-evolution status <skill>    # 查看状态
skill-evolution list-patches <skill>  # 列出补丁

实现：

使用 Commander.js 解析命令行
使用 Chalk 美化输出
支持配置参数（--threshold, --limit）

📊 数据模型

Execution Log（执行日志）

格式：JSONL（每行一个 JSON 对象）

结构：

{
  "session_id": "exec_1774620809181_jf3oj0",
  "skill": "agent-browser",
  "timestamp": "2026-03-27T14:13:29.181Z",
  "duration_ms": 150,
  "user_request": "帮我登录 example.com",
  "expected_plan": [],
  "actual_execution": [
    {
      "timestamp": 1774620809179,
      "tool": "agent-browser.open",
      "params": {"url": "https://example.com/login"},
      "result": "success",
      "error": null
    }
  ],
  "modifications": [
    {
      "type": "correction",
      "step": 6,
      "tool": "agent-browser.click",
      "original": "@e3",
      "corrected": "@e5",
      "reason": "Re-snapshot revealed new element"
    }
  ],
  "outcome": "success"
}

字段说明：

session_id: 唯一会话标识
skill: Skill 名称
timestamp: ISO 8601 时间戳
duration_ms: 执行耗时（毫秒）
user_request: 用户原始请求
expected_plan: 预期执行计划（暂未实现）
actual_execution: 实际执行轨迹
modifications: 检测到的修改行为
outcome: 最终结果（success/failed/unknown）

Modification（修改记录）

类型：

correction: 参数修正（如选择器变化）
retry: 重试行为
timeout_adjust: 超时调整（未来）
step_skip: 步骤跳过（未来）

结构：

{
  "type": "correction",
  "step": 6,
  "tool": "agent-browser.click",
  "original": "@e3",
  "corrected": "@e5",
  "reason": "Re-snapshot revealed new element"
}

Pattern（模式）

生成方式：聚类相似的 Modification

结构：

{
  "type": "correction",
  "tool": "agent-browser.click",
  "count": 3,
  "frequency": "60.0%",
  "examples": [...],
  "suggestion": {
    "title": "为 agent-browser.click 添加容错逻辑",
    "description": "检测到 3 次 agent-browser.click 需要自动修正",
    "action": "添加重试和自动修正逻辑",
    "example": {...}
  }
}

🔄 工作流程

完整流程

1. 用户发起请求
   ↓
2. Interceptor 创建会话
   ↓
3. Skill 执行（工具调用被拦截）
   ↓
4. 记录到 actual_execution
   ↓
5. 检测修正行为 → 记录到 modifications
   ↓
6. 执行完成 → 保存到 JSONL 文件
   ↓
7. Analyzer 定期分析日志
   ↓
8. 识别模式（超过阈值）
   ↓
9. 生成优化建议
   ↓
10. 用户确认 → Patch Manager 生成补丁
   ↓
11. 应用补丁 → Skill 进化完成

🔌 集成点

OpenClaw 集成

集成位置：OpenClaw Skill 执行层

集成方式：

// 在 SkillExecutor.js 中
const { evolutionPlugin } = require('skill-evolution-plugin');

async executeTool(skillName, toolName, params) {
  // 开始监控
  const sessionId = evolutionPlugin.startMonitoring(skillName, userRequest);
  
  try {
    const result = await originalExecute(toolName, params);
    evolutionPlugin.recordToolCall(sessionId, toolName, params, result);
    return result;
  } catch (error) {
    evolutionPlugin.recordToolCall(sessionId, toolName, params, { error });
    throw error;
  } finally {
    evolutionPlugin.stopMonitoring(sessionId);
  }
}

Hook 点：

Skill 执行前 → startMonitoring()
工具调用后 → recordToolCall()
Skill 执行后 → stopMonitoring()

🔒 安全与隐私

数据安全

本地存储：所有数据存储在 ~/.openclaw/skills/<skill>/.evolution/
不上传云端：无网络请求，完全离线
用户控制：用户可随时删除 .evolution/ 目录

隐私保护

不记录敏感信息：仅记录工具调用，不记录用户数据
匿名分析：模式识别不涉及用户身份
可选分享：用户可选择是否分享改进建议

📈 性能考虑

时间复杂度

记录工具调用：O(1) - 直接追加到 Map
保存日志：O(1) - 追加写入文件
分析日志：O(n) - 遍历所有日志，n 为日志数量
聚类修改：O(m) - m 为修改记录数量

空间复杂度

内存：O(s) - s 为活跃会话数量（通常 < 10）
磁盘：O(e) - e 为执行记录数量（每条 ~1KB）

优化策略

异步写入：日志写入不阻塞主流程
限制日志数量：默认只分析最近 100 条
批量分析：定期批量分析，非实时

🧪 测试策略

单元测试

测试框架：Jest（计划）

测试覆盖：

Interceptor: 会话管理、工具调用记录
Analyzer: 日志读取、模式识别、建议生成
PatchManager: 补丁创建、manifest 更新

集成测试

测试场景：

完整执行流程
OpenClaw 集成
CLI 命令

E2E 测试

测试脚本：test/demo.js

验证点：

演示运行成功
日志文件生成
报告生成正确

🚀 扩展性

插件化设计

独立模块：Interceptor、Analyzer、PatchManager 可独立使用
可配置：阈值、日志路径等可配置
可扩展：支持添加新的 Modification 类型

未来扩展

更多 Skill 类型：目前支持所有 OpenClaw Skill
跨 Skill 学习：从多个 Skill 学习通用模式
社区分享：改进建议共享池
企业版：团队共享、统一配置

📚 相关文档

README.md - 项目介绍
API.md - API 参考
INTEGRATION.md - 集成指南
PROJECT_SUMMARY.md - 项目总结

最后更新：2026-03-27
维护者：Skill Evolution Plugin Contributors

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Skill Evolution Plugin - 架构设计

🎯 系统概述

🏗️ 架构概览

📦 核心模块

1. Interceptor（拦截器）

2. Analyzer（分析器）

3. Patch Manager（补丁管理）

4. CLI（命令行工具）

📊 数据模型

Execution Log（执行日志）

Modification（修改记录）

Pattern（模式）

🔄 工作流程

完整流程

🔌 集成点

OpenClaw 集成

🔒 安全与隐私

数据安全

隐私保护

📈 性能考虑

时间复杂度

空间复杂度

优化策略

🧪 测试策略

单元测试

集成测试

E2E 测试

🚀 扩展性

插件化设计

未来扩展

📚 相关文档

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History

ARCHITECTURE.md

File metadata and controls

Skill Evolution Plugin - 架构设计

🎯 系统概述

🏗️ 架构概览

📦 核心模块

1. Interceptor（拦截器）

2. Analyzer（分析器）

3. Patch Manager（补丁管理）

4. CLI（命令行工具）

📊 数据模型

Execution Log（执行日志）

Modification（修改记录）

Pattern（模式）

🔄 工作流程

完整流程

🔌 集成点

OpenClaw 集成

🔒 安全与隐私

数据安全

隐私保护

📈 性能考虑

时间复杂度

空间复杂度

优化策略

🧪 测试策略

单元测试

集成测试

E2E 测试

🚀 扩展性

插件化设计

未来扩展

📚 相关文档