# Skill 自进化系统设计

> 日期: 2026-04-13
> 模块: netaclaw/skill-evolution
> 状态: 设计阶段
> 依赖: P0 长期记忆系统（共享 background review 模式）

## 1. 目标

为 NetaClaw Agent 添加 Skill 自进化能力：Agent 在对话中积累经验后，后台 review agent 自动提炼可复用的方法论为 Skill，或更新已有 Skill。同时提供 `skill_manage` 工具允许 Agent 在对话中主动创建/编辑 Skill。所有 Agent 创建的 Skill 经过安全扫描后才写入文件系统。

## 2. 核心决策

| 决策项 | 选择 | 理由 |
|--------|------|------|
| Review 触发方式 | 迭代计数（默认每 10 轮工具调用） | Hermes 验证过的模式，平衡频率和成本 |
| Review Agent 模型 | 复用主 Agent 同模型 | 保证提炼质量 |
| 安全校验 | 完整正则扫描（~84 条规则） | Agent 创建内容需要严格审查 |
| Skill 存储 | 文件系统 + DB 元数据 | 与现有架构一致 |
| Review 执行方式 | 异步不阻塞主对话 | 不影响用户体验 |

## 3. 系统架构

```
[Agent 对话循环 (attempt.ts)]
    ↓ toolCallCount 累计 >= N
[chat.ts 检测触发条件]
    ↓ 异步（不阻塞响应）
[spawnSkillReview()] → 独立 runAgent() 调用
    ↓ review agent 拥有 skill_manage + skill_list 工具
[skill_manage 工具]
    ↓ 写入前
[SkillGuard 安全扫描]
    ↓ 通过 → 原子写入
[文件系统 skills/{name}/SKILL.md] + [DB netaclaw_skill]
    ↓ 写入后
[SkillLoader.reloadSkill()] → 热更新内存缓存
    ↓ 下次对话
[system prompt 自动包含新 skill]
```

关键约束：
- Review agent 是一次性的：spawn → 分析 → 写入 → 结束
- Review agent 禁用自身的 nudge interval（防止递归 review）
- Review agent 最多 8 轮工具调用
- Skill 写入是原子的：先写临时文件，扫描通过后 rename
- Review agent 不产生用户可见输出

## 4. Skill Manager 工具

### 4.1 skill_manage 工具

```typescript
// tools/builtin/skill_manage.ts
interface SkillManageParams {
  action: 'create' | 'edit' | 'patch' | 'delete' | 'write_file' | 'remove_file';
  name: string;                    // skill 名称
  content?: string;                // SKILL.md 完整内容（create/edit）
  old_string?: string;             // patch: 要替换的文本
  new_string?: string;             // patch: 替换后的文本
  replace_all?: boolean;           // patch: 替换所有匹配
  category?: string;               // 可选分类目录
  file_path?: string;              // 支持文件路径（write_file/remove_file）
  file_content?: string;           // 支持文件内容（write_file）
}
```

| action | 用途 | 必需参数 |
|--------|------|---------|
| create | 创建新 skill | name, content |
| edit | 完整重写 SKILL.md | name, content |
| patch | 局部替换 | name, old_string, new_string |
| delete | 删除 skill 目录 | name |
| write_file | 写入支持文件 | name, file_path, file_content |
| remove_file | 删除支持文件 | name, file_path |

### 4.2 skill_list 工具

```typescript
// 只读工具，返回已有 skill 列表
interface SkillListParams {
  category?: string;  // 可选：按分类过滤
}
// 返回: [{ name, description, category }]
```

### 4.3 验证规则

| 规则 | 限制 |
|------|------|
| name | 最长 64 字符，`/^[a-z0-9][a-z0-9._-]*$/` |
| category | 单层目录，同 name 命名规则 |
| SKILL.md content | 最大 100,000 字符 |
| 支持文件 | 最大 1MB/文件 |
| 支持文件目录 | 仅 `references/`, `templates/`, `scripts/`, `assets/` |
| frontmatter | 必须包含 `name` 和 `description` 字段 |
| description | 最长 1024 字符 |
| 总文件数 | 每个 skill 最多 50 个文件 |
| 总大小 | 每个 skill 最大 1MB |

### 4.4 原子写入流程

```
1. 验证参数 → 失败则返回错误
2. 写入临时文件 skills/{name}/.tmp_SKILL.md
3. 调用 SkillGuard.scan() 扫描临时文件
4. 如果 verdict === 'dangerous' → 删除临时文件，返回错误
5. rename 临时文件 → SKILL.md
6. 同步 DB 元数据（netaclaw_skill 表）
7. 调用 SkillLoader.reloadSkill(name) 热更新缓存
8. 清除 skill prompt 缓存
```

## 5. Skill Guard 安全扫描

### 5.1 威胁模式分类

参考 Hermes skills_guard.py 的 84 条正则规则，按类别组织：

| 类别 | 规则数 | severity | 示例模式 |
|------|--------|----------|---------|
| 数据泄露 (exfiltration) | 18 | critical | `process\.env`, `\.ssh/`, `credentials`, DNS exfil |
| 提示注入 (prompt_injection) | 16 | critical | `ignore.*instructions`, `you are now`, `system prompt` |
| 破坏性操作 (destructive) | 8 | critical | `rm\s+-rf\s+/`, `mkfs`, `dd\s+if=`, `chmod\s+777` |
| 持久化 (persistence) | 10 | high | `crontab`, `authorized_keys`, `systemd`, `sudoers` |
| 网络 (network) | 9 | high | reverse shells, tunnels, hardcoded IPs |
| 混淆 (obfuscation) | 14 | high | `eval\(`, `Buffer\.from.*base64`, hex encoding |
| 代码执行 (execution) | 6 | high | `child_process`, `exec\(`, `spawn\(` |
| 路径穿越 (path_traversal) | 5 | high | `\.\.\/`, `/etc/passwd`, `/proc/` |
| 加密挖矿 (crypto_mining) | 2 | critical | `stratum+tcp`, `xmrig` |
| 供应链 (supply_chain) | 6 | critical | `curl.*\|.*bash`, unpinned deps |
| 权限提升 (privilege_escalation) | 5 | high | `sudo`, `setuid`, `NOPASSWD` |
| 凭证暴露 (credential_exposure) | 5 | critical | hardcoded secrets, private keys |

### 5.2 扫描接口

```typescript
// skill_evolution/guard.ts
interface ScanFinding {
  category: string;
  severity: 'critical' | 'high' | 'medium';
  pattern: string;
  match: string;
  file: string;
  line: number;
}

interface ScanResult {
  verdict: 'safe' | 'caution' | 'dangerous';
  findings: ScanFinding[];
  summary: string;
}

function scanSkill(skillPath: string): ScanResult;
```

### 5.3 判定逻辑

```
findings 中有 critical → verdict = 'dangerous'
findings 中有 high → verdict = 'caution'
无 findings → verdict = 'safe'
```

Agent 创建的 skill 策略：
- safe → 允许
- caution → 允许（记录日志）
- dangerous → 阻止，回滚，返回错误信息给 agent

### 5.4 二进制文件拦截

禁止的文件扩展名：`.exe`, `.dll`, `.so`, `.dylib`, `.bin`, `.dat`, `.com`, `.msi`, `.dmg`, `.app`, `.deb`, `.rpm`

## 6. Background Review 机制

### 6.1 触发条件

在 `controller/chat.ts` 中，`runAgent()` 返回后：

```typescript
// 从 Agent 配置读取
const evoConfig = agentEntity?.config?.skillEvolution;
const skillEvolutionEnabled = evoConfig?.enabled ?? false;
const nudgeInterval = evoConfig?.nudgeInterval ?? 10;

// 累计工具调用计数（跨同一会话的多次请求）
const totalCalls = (sessionMeta.toolCallsSinceReview ?? 0) + result.toolCallCount;

const shouldReview = (
  skillEvolutionEnabled &&
  totalCalls >= nudgeInterval &&
  result.toolCallCount > 0
);

if (shouldReview) {
  sessionMeta.toolCallsSinceReview = 0;
  // 异步触发，不阻塞响应
  spawnSkillReview({
    conversationHistory: history,
    parentAgentConfig: agentConfig,
    skillLoader: this.skillLoader,
    linkedSkills: agentEntity?.skills ?? [],
    allowOptimize: evoConfig?.allowOptimizeLinked ?? true,
    allowCreateNew: evoConfig?.allowCreateNew ?? true,
  }).catch(err => logger.warn('Skill review failed:', err));
} else {
  sessionMeta.toolCallsSinceReview = totalCalls;
}
```

### 6.2 Review Agent 配置

```typescript
// skill_evolution/review.ts
interface SkillReviewContext {
  conversationHistory: LLMMessage[];
  parentAgentConfig: AgentConfig;
  skillLoader: SkillLoaderService;
  skillRepo: Repository<NetaClawSkillEntity>;   // DB 同步用
  agentRepo: Repository<NetaClawAgentEntity>;   // 自动关联新 skill 用
  agentName: string;                             // 当前 Agent 名称
  linkedSkills: string[];           // Agent 已勾选的 skill 名称
  allowOptimize: boolean;
  allowCreateNew: boolean;
}

async function spawnSkillReview(ctx: SkillReviewContext): Promise<void> {
  const reviewPrompt = buildSkillReviewPrompt(
    ctx.linkedSkills, ctx.allowOptimize, ctx.allowCreateNew,
  );

  const reviewConfig: AgentConfig = {
    ...ctx.parentAgentConfig,
    name: `${ctx.parentAgentConfig.name}_skill_reviewer`,
    systemPrompt: SKILL_REVIEW_SYSTEM_PROMPT,
    maxToolRounds: 8,
  };

  // skill_manage 工具接收 SkillWriter 实例（非 SkillLoader）
  const writer = new SkillWriter(ctx.skillLoader.getSkillsDir(), ctx.skillRepo, ctx.skillLoader);
  const tools = [
    createSkillManageTool(writer, {
      allowedEditSkills: ctx.allowOptimize ? ctx.linkedSkills : [],
      allowCreateNew: ctx.allowCreateNew,
    }),
    createSkillListTool(ctx.skillLoader),
  ];

  await runAgent({
    agentConfig: reviewConfig,
    tools,
    userMessage: reviewPrompt,
    history: ctx.conversationHistory,
  });
}
```

### 6.3 Review Prompt

Review prompt 是动态生成的，根据 Agent 的 skillEvolution 配置和已勾选 skill 列表拼接：

```typescript
function buildSkillReviewPrompt(
  linkedSkills: string[],       // Agent 已勾选的 skill 名称列表
  allowOptimize: boolean,
  allowCreateNew: boolean,
): string {
  let prompt = '回顾上面的对话，考虑是否需要保存或更新 skill。\n\n';
  prompt += '关注：\n';
  prompt += '1. 是否使用了非显而易见的方法来完成任务？\n';
  prompt += '2. 是否经历了试错或因实际发现而改变了方案？\n';
  prompt += '3. 用户是否期望或希望不同的方法或结果？\n\n';

  if (allowOptimize && linkedSkills.length > 0) {
    prompt += `当前 Agent 已关联以下 skill：${linkedSkills.join(', ')}\n`;
    prompt += '请优先检查这些已有 skill 是否可以根据本次对话的经验进行优化（用 patch 更新）。\n\n';
  }

  if (allowCreateNew) {
    prompt += '如果发现了全新的可复用方法论且没有相关 skill，请创建新 skill。\n\n';
  }

  prompt += '操作指南：\n';
  prompt += '- 先用 skill_list 查看已有 skill，避免重复创建\n';
  prompt += '- 优化已有 skill 时优先用 patch（局部替换），避免 edit 全量重写\n';
  prompt += '- Skill 内容应聚焦于可复用的方法论，而非具体的业务数据\n';
  prompt += '- 如果没有值得保存的内容，直接说"无需保存"并停止\n';
  return prompt;
}

### 6.4 Review System Prompt

```
你是一个 Skill 提炼专家。你的任务是分析对话历史，提取可复用的方法论并保存为 Skill。

Skill 格式要求：
- SKILL.md 必须包含 YAML frontmatter（name + description）
- 正文用 Markdown，包含：触发条件、工作流程、规则约束
- name 使用小写字母、数字、连字符（如 nginx-deploy-config）
- description 一句话描述 skill 的用途

你只有 8 轮工具调用机会，请高效行动。
```

## 7. Agent 配置扩展

### 7.1 AgentEntity.config 扩展

```typescript
interface AgentConfig {
  // ...现有字段
  skillEvolution?: {
    enabled: boolean;
    nudgeInterval?: number;       // 触发 review 的工具调用间隔，默认 10
    allowOptimizeLinked?: boolean; // 是否允许优化已勾选的 skill，默认 true
    allowCreateNew?: boolean;     // 是否允许创建全新 skill，默认 true
  };
}
```

### 7.2 Skill 进化范围

Agent 的 skill 进化有两种模式，均可在 Agent 编辑页面独立开关：

**模式 1：优化已勾选 Skill（allowOptimizeLinked）**
- Agent 配置中已关联的 skill（`agent.skills[]` 列表）可以被 review agent 通过 patch/edit 更新
- 适用场景：电商运营 Agent 反复执行"上架商品"skill，在实践中发现更好的标题写法或定价策略，自动优化该 skill
- Review agent 在分析对话时，优先检查已勾选 skill 是否有改进空间

**模式 2：创建全新 Skill（allowCreateNew）**
- Review agent 可以发现对话中的新方法论并创建全新 skill
- 新创建的 skill 自动关联到当前 Agent（加入 `agent.skills[]`）
- 适用场景：投流 Agent 在实践中摸索出一套新的出价策略，提炼为独立 skill

### 7.3 多 Agent 协作场景考虑

电商运营系统中多个 Agent 各司其职（上架、下架、投流、产品管理等），skill 进化需要考虑：

- **Skill 共享**：一个 Agent 优化的 skill 如果被其他 Agent 也勾选了，优化会自动生效（因为 skill 存在文件系统，所有 Agent 共享同一份）
- **写入冲突**：多个 Agent 同时优化同一个 skill 时，用文件锁（lockfile）保证原子性，后写入的 patch 基于最新内容
- **进化隔离**：如果某个 Agent 的场景特殊，不希望它的优化影响其他 Agent，可以关闭 `allowOptimizeLinked`，只允许 `allowCreateNew`（新 skill 只关联到自己）

### 7.4 Agent 编辑页面配置

在 Agent 编辑页面新增"Skill 进化"配置区域：
- 总开关：启用/禁用 Skill 进化
- 子开关：允许优化已勾选 Skill（默认开）
- 子开关：允许创建新 Skill（默认开）
- 数字输入：Review 触发间隔（高级选项，默认 10）

### 7.5 SkillLoader 扩展

新增方法：

```typescript
// 热更新单个 skill（skill_manage 写入后调用）
async reloadSkill(name: string): Promise<void>;

// 获取 skill 列表摘要（给 review agent 用）
getSkillSummaries(): { name: string; description: string; category?: string }[];
```

## 8. 新增文件清单

```
src/modules/netaclaw/
├── skill_evolution/
│   ├── guard.ts              # SkillGuard 安全扫描（正则模式匹配）
│   ├── guard_patterns.ts     # 威胁模式定义（84 条规则）
│   ├── review.ts             # spawnSkillReview() 后台 review 逻辑
│   └── skill_writer.ts       # 原子写入 + 验证 + DB 同步
├── tools/builtin/
│   ├── skill_manage.ts       # skill_manage 工具
│   └── skill_list.ts         # skill_list 工具
```

## 9. 修改文件清单

| 文件 | 修改内容 |
|------|---------|
| `controller/chat.ts` | runAgent 返回后检测触发条件，异步调用 spawnSkillReview，通过 sessionRepo 直接更新 metadata |
| `service/skill_loader.ts` | 新增 reloadSkill()、getSkillSummaries()、getSkillsDir() 方法 |

## 10. 依赖

无新增外部依赖。安全扫描用纯正则实现，skill 文件读写用 Node.js fs 模块。