Skip to content

API.md

Latest commit

 

History

History
543 lines (385 loc) · 10.1 KB

API.md

File metadata and controls

543 lines (385 loc) · 10.1 KB

Skill Evolution Plugin - API 参考

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

📦 主入口

const { 
  SkillEvolutionPlugin,
  SkillInterceptor,
  SkillAnalyzer,
  PatchManager
} = require('./src/index');

🔌 SkillEvolutionPlugin

主类，整合所有功能模块。

构造函数

const plugin = new SkillEvolutionPlugin(options);

参数：

  • options (object, optional) - 配置选项
    • enabled (boolean, default: true) - 是否启用
    • logPath (string, default: '~/.openclaw/skills') - 日志路径
    • threshold (number, default: 3) - 建议阈值

示例：

const plugin = new SkillEvolutionPlugin({
  enabled: true,
  logPath: '~/.openclaw/skills',
  threshold: 3
});

startMonitoring(skillName, userRequest)

开始监控 Skill 执行。

参数：

  • skillName (string) - Skill 名称
  • userRequest (string) - 用户请求文本

返回：

  • sessionId (string) - 会话 ID

示例：

const sessionId = plugin.startMonitoring('agent-browser', '帮我登录 example.com');
// 返回："exec_1774620809181_jf3oj0"

recordToolCall(sessionId, toolName, params, result, options)

记录工具调用。

参数：

  • sessionId (string) - 会话 ID
  • toolName (string) - 工具名称
  • params (object) - 工具参数
  • result (object) - 工具执行结果
    • success (boolean) - 是否成功
    • error (string, optional) - 错误信息
  • options (object, optional) - 额外选项
    • correctedFrom (object, optional) - 原始参数（修正时）
    • correctionReason (string, optional) - 修正原因
    • retryCount (number, optional) - 重试次数
    • retryReason (string, optional) - 重试原因

示例：

// 记录成功调用
plugin.recordToolCall(sessionId, 'agent-browser.open', 
  { url: 'https://example.com' }, 
  { success: true }
);

// 记录失败调用
plugin.recordToolCall(sessionId, 'agent-browser.click', 
  { ref: '@e3' }, 
  { success: false, error: 'Element not found' }
);

// 记录修正
plugin.recordToolCall(sessionId, 'agent-browser.click', 
  { ref: '@e5' }, 
  { success: true },
  { 
    correctedFrom: { ref: '@e3' },
    correctionReason: 'Re-snapshot revealed new element'
  }
);

// 记录重试
plugin.recordToolCall(sessionId, 'agent-browser.snapshot', 
  {}, 
  { success: true },
  { 
    retryCount: 1,
    retryReason: 'Element not found'
  }
);

stopMonitoring(sessionId, outcome)

结束监控并保存日志。

参数：

  • sessionId (string) - 会话 ID
  • outcome (string, default: 'unknown') - 执行结果
    • 'success' - 成功
    • 'failed' - 失败
    • 'unknown' - 未知

返回：

  • report (object) - 执行报告

示例：

const report = plugin.stopMonitoring(sessionId, 'success');
// report:
// {
//   session_id: "exec_...",
//   skill: "agent-browser",
//   modifications: [...],
//   outcome: "success"
// }

analyze(skillName)

分析 Skill 使用模式。

参数：

  • skillName (string) - Skill 名称

返回：

  • analysis (object) - 分析结果

示例：

const analysis = plugin.analyze('agent-browser');
// {
//   skill: "agent-browser",
//   totalExecutions: 5,
//   successRate: "100.0%",
//   patterns: [...],
//   suggestions: [...]
// }

generateReport(skillName)

生成人类可读的报告。

参数：

  • skillName (string) - Skill 名称

返回：

  • report (string) - 格式化的报告文本

示例：

const report = plugin.generateReport('agent-browser');
console.log(report);
// 输出：
// ╔══════════════════════════════════════════════════════════╗
// ║  📊 Skill 进化报告 - agent-browser                  ║
// ╚══════════════════════════════════════════════════════════╝
// ...

createPatch(skillName, oldContent, newContent, description)

创建补丁文件。

参数：

  • skillName (string) - Skill 名称
  • oldContent (string) - 原始内容
  • newContent (string) - 修改后的内容
  • description (string) - 补丁描述

返回：

  • patchInfo (object) - 补丁信息

示例：

const patchInfo = plugin.createPatch(
  'agent-browser',
  originalSkillContent,
  modifiedSkillContent,
  'Add retry logic'
);
// {
//   path: "/path/to/patch.patch",
//   name: "20260327-add-retry-logic.patch",
//   metadata: {...}
// }

listPatches(skillName)

列出已应用的补丁。

参数：

  • skillName (string) - Skill 名称

返回：

  • patches (array) - 补丁列表

示例：

const patches = plugin.listPatches('agent-browser');
// [
//   {
//     file: "001-20260327-add-retry-logic.patch",
//     created: "2026-03-27T22:00:00Z",
//     description: "Add retry logic"
//   }
// ]

applyPatch(skillName, patchPath)

应用补丁。

参数：

  • skillName (string) - Skill 名称
  • patchPath (string) - 补丁文件路径

返回：

  • result (object) - 应用结果

示例：

const result = plugin.applyPatch('agent-browser', '/path/to/patch.patch');
// {
//   skillFile: "/path/to/SKILL.md",
//   originalContent: "...",
//   patchFile: "/path/to/patch.patch",
//   status: "pending_review"
// }

🔍 SkillInterceptor

拦截器类，用于监控 Skill 执行。

构造函数

const interceptor = new SkillInterceptor(options);

参数：

  • options (object, optional)
    • enabled (boolean, default: true)
    • logPath (string, default: '~/.openclaw/skills')

startSession(sessionId, skillName, userRequest)

创建监控会话。

参数：

  • sessionId (string)
  • skillName (string)
  • userRequest (string)

返回：sessionId (string)

recordToolCall(sessionId, toolName, params, result, options)

记录工具调用。

参数：同上

endSession(sessionId, outcome)

结束会话。

参数：

  • sessionId (string)
  • outcome (string)

返回：report (object)

setExpectedPlan(sessionId, plan)

设置预期执行计划。

参数：

  • sessionId (string)
  • plan (array) - 预期执行步骤

示例：

interceptor.setExpectedPlan(sessionId, [
  { tool: 'open', params: { url: '...' } },
  { tool: 'snapshot', params: {} },
  { tool: 'fill', params: { ref: '@e1' } }
]);

📊 SkillAnalyzer

分析器类，用于分析执行日志。

构造函数

const analyzer = new SkillAnalyzer(options);

参数：

  • options (object, optional)
    • logPath (string, default: '~/.openclaw/skills')
    • threshold (number, default: 3)

readExecutionLogs(skillName, limit)

读取执行日志。

参数：

  • skillName (string)
  • limit (number, default: 100)

返回：logs (array)

analyze(skillName)

分析模式。

参数：skillName (string)
返回：analysis (object)

clusterModifications(logs)

聚类修改记录。

参数：logs (array)
返回：clusters (array)

generateSuggestion(cluster)

生成优化建议。

参数：cluster (object)
返回：suggestion (object)

generateReport(skillName)

生成报告。

参数：skillName (string)
返回：report (string)

📦 PatchManager

补丁管理类。

构造函数

const patchManager = new PatchManager(options);

参数：

  • options (object, optional)
    • logPath (string, default: '~/.openclaw/skills')

createPatch(skillName, oldContent, newContent, description)

创建补丁。

参数：同上
返回：patchInfo (object)

listPatches(skillName)

列出补丁。

参数：skillName (string)
返回：patches (array)

updateManifest(skillName, patchInfo)

更新 manifest。

参数：

  • skillName (string)
  • patchInfo (object)

返回：manifest (object)

applyPatch(skillName, patchPath)

应用补丁。

参数：

  • skillName (string)
  • patchPath (string)

返回：result (object)

🎯 完整示例

基础用法

const { SkillEvolutionPlugin } = require('skill-evolution-plugin');

// 创建插件实例
const plugin = new SkillEvolutionPlugin();

// 开始监控
const sessionId = plugin.startMonitoring('agent-browser', '帮我登录网站');

// 记录工具调用
plugin.recordToolCall(sessionId, 'agent-browser.open', 
  { url: 'https://example.com' }, 
  { success: true }
);

// 记录修正
plugin.recordToolCall(sessionId, 'agent-browser.click', 
  { ref: '@e5' }, 
  { success: true },
  { correctedFrom: { ref: '@e3' }, correctionReason: 'Element not found' }
);

// 结束监控
plugin.stopMonitoring(sessionId, 'success');

// 生成报告
const report = plugin.generateReport('agent-browser');
console.log(report);

与 OpenClaw 集成

const { evolutionPlugin } = require('skill-evolution-plugin');

// 在 SkillExecutor 中
async executeTool(skillName, toolName, params) {
  const sessionId = getCurrentSessionId();
  
  if (!sessionId) {
    sessionId = evolutionPlugin.startMonitoring(skillName, getUserRequest());
    setCurrentSessionId(sessionId);
  }
  
  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 {
    if (isLastToolCall()) {
      evolutionPlugin.stopMonitoring(sessionId, 'success');
      clearCurrentSessionId();
    }
  }
}

📚 相关文档

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