1211 lines
50 KiB
Markdown
1211 lines
50 KiB
Markdown
# Skill 自进化系统 Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 为 NetaClaw Agent 添加 Skill 自进化能力——后台 review agent 自动提炼/优化 Skill，skill_manage 工具支持运行时创建/编辑，SkillGuard 安全扫描保护。
|
||
|
||
**Architecture:** 4 层模块：guard_patterns（威胁规则定义）→ guard（扫描引擎）→ skill_writer（原子写入 + 验证 + DB 同步）→ tools（skill_manage/skill_list 工具）。review.ts 编排后台 review agent，chat.ts 中迭代计数触发。
|
||
|
||
**Tech Stack:** TypeScript, Node.js fs, @sinclair/typebox (tool schema), 纯正则安全扫描
|
||
|
||
**Spec:** `docs/superpowers/specs/2026-04-13-skill-evolution-design.md`
|
||
|
||
---
|
||
|
||
## File Structure
|
||
|
||
```
|
||
src/modules/netaclaw/
|
||
├── skill_evolution/
|
||
│ ├── guard_patterns.ts # 威胁模式定义（~84 条正则规则）
|
||
│ ├── guard.ts # scanSkill() 扫描引擎
|
||
│ ├── skill_writer.ts # 原子写入 + 验证 + DB 同步 + 文件锁
|
||
│ └── review.ts # spawnSkillReview() + buildSkillReviewPrompt()
|
||
├── tools/builtin/
|
||
│ ├── skill_manage.ts # skill_manage 工具（create/edit/patch/delete/write_file/remove_file）
|
||
│ └── skill_list.ts # skill_list 只读工具
|
||
```
|
||
|
||
Modified files:
|
||
- `src/modules/netaclaw/service/skill_loader.ts` — 新增 reloadSkill() + getSkillSummaries()
|
||
- `src/modules/netaclaw/controller/chat.ts` — 触发条件检测 + 异步 review 调用
|
||
|
||
---
|
||
|
||
### Task 1: Create guard_patterns.ts — threat pattern definitions
|
||
|
||
**Files:**
|
||
- Create: `src/modules/netaclaw/skill_evolution/guard_patterns.ts`
|
||
|
||
- [ ] **Step 1: Create the threat pattern definitions file**
|
||
|
||
Create `src/modules/netaclaw/skill_evolution/guard_patterns.ts`:
|
||
|
||
```typescript
|
||
/**
|
||
* Skill Guard 威胁模式定义
|
||
* 参考 Hermes skills_guard.py，84 条正则规则按类别组织
|
||
*/
|
||
|
||
export type Severity = 'critical' | 'high' | 'medium';
|
||
|
||
export interface ThreatPattern {
|
||
id: string;
|
||
category: string;
|
||
severity: Severity;
|
||
pattern: RegExp;
|
||
description: string;
|
||
}
|
||
|
||
export const BLOCKED_EXTENSIONS = new Set([
|
||
'.exe', '.dll', '.so', '.dylib', '.bin', '.dat', '.com',
|
||
'.msi', '.dmg', '.app', '.deb', '.rpm',
|
||
]);
|
||
|
||
export const ALLOWED_SUBDIRS = new Set([
|
||
'references', 'templates', 'scripts', 'assets',
|
||
]);
|
||
|
||
export const LIMITS = {
|
||
maxNameLength: 64,
|
||
maxContentLength: 100_000,
|
||
maxFileSize: 1_048_576, // 1MB per file
|
||
maxTotalSize: 1_048_576, // 1MB per skill
|
||
maxFileCount: 50,
|
||
maxDescriptionLength: 1024,
|
||
namePattern: /^[a-z0-9][a-z0-9._-]*$/,
|
||
} as const;
|
||
|
||
// --- 威胁模式 ---
|
||
|
||
const exfiltration: ThreatPattern[] = [
|
||
{ id: 'exf-01', category: 'exfiltration', severity: 'critical', pattern: /process\.env\b/, description: '访问环境变量' },
|
||
{ id: 'exf-02', category: 'exfiltration', severity: 'critical', pattern: /\.ssh\//, description: '访问 SSH 目录' },
|
||
{ id: 'exf-03', category: 'exfiltration', severity: 'critical', pattern: /credentials?[._-]?(json|yaml|yml|xml|conf|cfg|ini)\b/i, description: '访问凭证文件' },
|
||
{ id: 'exf-04', category: 'exfiltration', severity: 'critical', pattern: /\.(aws|gcloud|azure)\//, description: '访问云凭证目录' },
|
||
{ id: 'exf-05', category: 'exfiltration', severity: 'critical', pattern: /keychain|keyring|gnome-keyring/i, description: '访问系统密钥链' },
|
||
{ id: 'exf-06', category: 'exfiltration', severity: 'critical', pattern: /\/etc\/(shadow|passwd|master\.passwd)/, description: '访问系统密码文件' },
|
||
{ id: 'exf-07', category: 'exfiltration', severity: 'high', pattern: /dns.*exfil|exfil.*dns/i, description: 'DNS 数据泄露' },
|
||
{ id: 'exf-08', category: 'exfiltration', severity: 'high', pattern: /\!\[.*\]\(https?:\/\/[^)]*\$\{/, description: 'Markdown 图片链接注入' },
|
||
{ id: 'exf-09', category: 'exfiltration', severity: 'critical', pattern: /\.netrc\b/, description: '访问 .netrc 凭证' },
|
||
{ id: 'exf-10', category: 'exfiltration', severity: 'critical', pattern: /\.docker\/config\.json/, description: '访问 Docker 凭证' },
|
||
{ id: 'exf-11', category: 'exfiltration', severity: 'critical', pattern: /\.kube\/config/, description: '访问 Kubernetes 凭证' },
|
||
{ id: 'exf-12', category: 'exfiltration', severity: 'critical', pattern: /\.npmrc\b/, description: '访问 npm 凭证' },
|
||
{ id: 'exf-13', category: 'exfiltration', severity: 'critical', pattern: /\.pypirc\b/, description: '访问 PyPI 凭证' },
|
||
{ id: 'exf-14', category: 'exfiltration', severity: 'high', pattern: /webhook[_.]?url/i, description: '引用 webhook URL' },
|
||
{ id: 'exf-15', category: 'exfiltration', severity: 'high', pattern: /api[_.]?key\s*[:=]\s*['"][^'"]{10,}/i, description: '硬编码 API key' },
|
||
{ id: 'exf-16', category: 'exfiltration', severity: 'critical', pattern: /BEGIN\s+(RSA|DSA|EC|OPENSSH)\s+PRIVATE\s+KEY/, description: '包含私钥' },
|
||
{ id: 'exf-17', category: 'exfiltration', severity: 'high', pattern: /localStorage|sessionStorage/i, description: '访问浏览器存储' },
|
||
{ id: 'exf-18', category: 'exfiltration', severity: 'high', pattern: /document\.cookie/i, description: '访问 cookie' },
|
||
];
|
||
|
||
// PLACEHOLDER_PATTERNS_CONTINUE
|
||
```
|
||
|
||
Note: This file will be very long (~300 lines). The remaining pattern categories follow the same structure. I'll continue in Step 2.
|
||
|
||
- [ ] **Step 2: Add remaining threat pattern categories**
|
||
|
||
Append to `guard_patterns.ts`, replacing `// PLACEHOLDER_PATTERNS_CONTINUE`:
|
||
|
||
```typescript
|
||
const promptInjection: ThreatPattern[] = [
|
||
{ id: 'pi-01', category: 'prompt_injection', severity: 'critical', pattern: /ignore\s+(all\s+)?(previous|prior|above)\s+(instructions|prompts)/i, description: '忽略指令注入' },
|
||
{ id: 'pi-02', category: 'prompt_injection', severity: 'critical', pattern: /you\s+are\s+now\s+(a|an|the)\b/i, description: '角色劫持' },
|
||
{ id: 'pi-03', category: 'prompt_injection', severity: 'critical', pattern: /system\s*prompt/i, description: '引用系统提示词' },
|
||
{ id: 'pi-04', category: 'prompt_injection', severity: 'critical', pattern: /\bDAN\b.*mode/i, description: 'DAN 越狱' },
|
||
{ id: 'pi-05', category: 'prompt_injection', severity: 'critical', pattern: /pretend\s+you\s+(are|have|can)/i, description: '伪装指令' },
|
||
{ id: 'pi-06', category: 'prompt_injection', severity: 'critical', pattern: /act\s+as\s+(if|though)\s+you/i, description: '行为覆盖' },
|
||
{ id: 'pi-07', category: 'prompt_injection', severity: 'critical', pattern: /override\s+(your|the|all)\s+(rules|instructions|guidelines)/i, description: '规则覆盖' },
|
||
{ id: 'pi-08', category: 'prompt_injection', severity: 'critical', pattern: /jailbreak/i, description: '越狱关键词' },
|
||
{ id: 'pi-09', category: 'prompt_injection', severity: 'high', pattern: /\[INST\]|\[\/INST\]|<\|im_start\|>|<\|im_end\|>/i, description: '模型标记注入' },
|
||
{ id: 'pi-10', category: 'prompt_injection', severity: 'high', pattern: /\bHuman:|Assistant:|<\|system\|>/i, description: '对话角色注入' },
|
||
{ id: 'pi-11', category: 'prompt_injection', severity: 'critical', pattern: /forget\s+(everything|all|your)/i, description: '遗忘指令' },
|
||
{ id: 'pi-12', category: 'prompt_injection', severity: 'critical', pattern: /new\s+instructions?\s*:/i, description: '新指令注入' },
|
||
{ id: 'pi-13', category: 'prompt_injection', severity: 'high', pattern: /do\s+not\s+follow\s+(any|the|your)/i, description: '不遵循指令' },
|
||
{ id: 'pi-14', category: 'prompt_injection', severity: 'high', pattern: /reveal\s+(your|the)\s+(system|initial|original)\s+(prompt|instructions)/i, description: '提示词泄露' },
|
||
{ id: 'pi-15', category: 'prompt_injection', severity: 'high', pattern: /repeat\s+(the|your)\s+(system|initial)\s+(prompt|message)/i, description: '提示词重复' },
|
||
{ id: 'pi-16', category: 'prompt_injection', severity: 'high', pattern: /bypass\s+(safety|content|security)\s+(filter|check|guard)/i, description: '安全绕过' },
|
||
];
|
||
|
||
const destructive: ThreatPattern[] = [
|
||
{ id: 'des-01', category: 'destructive', severity: 'critical', pattern: /rm\s+-rf\s+\//, description: '递归删除根目录' },
|
||
{ id: 'des-02', category: 'destructive', severity: 'critical', pattern: /mkfs\b/, description: '格式化文件系统' },
|
||
{ id: 'des-03', category: 'destructive', severity: 'critical', pattern: /dd\s+if=/, description: 'dd 磁盘写入' },
|
||
{ id: 'des-04', category: 'destructive', severity: 'critical', pattern: /chmod\s+777\s+\//, description: '根目录权限开放' },
|
||
{ id: 'des-05', category: 'destructive', severity: 'critical', pattern: /:(){ :\|:& };:/, description: 'Fork bomb' },
|
||
{ id: 'des-06', category: 'destructive', severity: 'high', pattern: /truncate\s+-s\s+0/, description: '文件截断' },
|
||
{ id: 'des-07', category: 'destructive', severity: 'high', pattern: />\s*\/dev\/sd[a-z]/, description: '磁盘设备写入' },
|
||
{ id: 'des-08', category: 'destructive', severity: 'high', pattern: /DROP\s+(TABLE|DATABASE)/i, description: 'SQL 删除操作' },
|
||
];
|
||
|
||
const persistence: ThreatPattern[] = [
|
||
{ id: 'per-01', category: 'persistence', severity: 'high', pattern: /crontab\s+-[el]/, description: '定时任务操作' },
|
||
{ id: 'per-02', category: 'persistence', severity: 'high', pattern: /authorized_keys/, description: 'SSH 授权密钥' },
|
||
{ id: 'per-03', category: 'persistence', severity: 'high', pattern: /systemd|systemctl\s+enable/, description: 'systemd 服务' },
|
||
{ id: 'per-04', category: 'persistence', severity: 'high', pattern: /\/etc\/sudoers/, description: 'sudoers 修改' },
|
||
{ id: 'per-05', category: 'persistence', severity: 'high', pattern: /\.bashrc|\.zshrc|\.profile|\.bash_profile/, description: 'Shell 配置修改' },
|
||
{ id: 'per-06', category: 'persistence', severity: 'high', pattern: /launchd|LaunchAgent|LaunchDaemon/i, description: 'macOS 启动项' },
|
||
{ id: 'per-07', category: 'persistence', severity: 'high', pattern: /HKEY_|reg\s+add/i, description: 'Windows 注册表' },
|
||
{ id: 'per-08', category: 'persistence', severity: 'high', pattern: /init\.d\//, description: 'init.d 服务' },
|
||
{ id: 'per-09', category: 'persistence', severity: 'high', pattern: /at\s+-f\s+/, description: 'at 定时任务' },
|
||
{ id: 'per-10', category: 'persistence', severity: 'high', pattern: /rc\.local/, description: 'rc.local 启动脚本' },
|
||
];
|
||
|
||
const network: ThreatPattern[] = [
|
||
{ id: 'net-01', category: 'network', severity: 'high', pattern: /\/bin\/(bash|sh)\s+-i\s+>&?\s*\/dev\/tcp/, description: '反向 shell' },
|
||
{ id: 'net-02', category: 'network', severity: 'high', pattern: /nc\s+-[elp]/, description: 'netcat 监听' },
|
||
{ id: 'net-03', category: 'network', severity: 'high', pattern: /socat\b.*TCP/, description: 'socat 隧道' },
|
||
{ id: 'net-04', category: 'network', severity: 'high', pattern: /ssh\s+-[RLD]\s/, description: 'SSH 隧道' },
|
||
{ id: 'net-05', category: 'network', severity: 'high', pattern: /ngrok|localtunnel|serveo/i, description: '隧道服务' },
|
||
{ id: 'net-06', category: 'network', severity: 'high', pattern: /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}:\d{2,5}\b/, description: '硬编码 IP:端口' },
|
||
{ id: 'net-07', category: 'network', severity: 'high', pattern: /python\s+-m\s+http\.server/, description: 'Python HTTP 服务' },
|
||
{ id: 'net-08', category: 'network', severity: 'high', pattern: /nmap\b/, description: '端口扫描' },
|
||
{ id: 'net-09', category: 'network', severity: 'high', pattern: /tcpdump|wireshark|tshark/i, description: '网络抓包' },
|
||
];
|
||
|
||
const obfuscation: ThreatPattern[] = [
|
||
{ id: 'obf-01', category: 'obfuscation', severity: 'high', pattern: /eval\s*\(/, description: 'eval 执行' },
|
||
{ id: 'obf-02', category: 'obfuscation', severity: 'high', pattern: /Buffer\.from\s*\([^)]*,\s*['"]base64['"]/, description: 'Base64 解码' },
|
||
{ id: 'obf-03', category: 'obfuscation', severity: 'high', pattern: /atob\s*\(/, description: 'atob 解码' },
|
||
{ id: 'obf-04', category: 'obfuscation', severity: 'high', pattern: /String\.fromCharCode/, description: 'charCode 构建' },
|
||
{ id: 'obf-05', category: 'obfuscation', severity: 'high', pattern: /\\x[0-9a-f]{2}\\x[0-9a-f]{2}\\x[0-9a-f]{2}/i, description: '十六进制编码' },
|
||
{ id: 'obf-06', category: 'obfuscation', severity: 'high', pattern: /\\u[0-9a-f]{4}\\u[0-9a-f]{4}/i, description: 'Unicode 编码' },
|
||
{ id: 'obf-07', category: 'obfuscation', severity: 'high', pattern: /new\s+Function\s*\(/, description: 'Function 构造器' },
|
||
{ id: 'obf-08', category: 'obfuscation', severity: 'high', pattern: /exec\s*\(\s*['"`]/, description: 'exec 字符串执行' },
|
||
{ id: 'obf-09', category: 'obfuscation', severity: 'high', pattern: /\$\{.*`.*`.*\}/, description: '模板字符串嵌套' },
|
||
{ id: 'obf-10', category: 'obfuscation', severity: 'high', pattern: /unescape\s*\(/, description: 'unescape 解码' },
|
||
{ id: 'obf-11', category: 'obfuscation', severity: 'high', pattern: /decodeURIComponent\s*\(\s*['"]%/, description: 'URI 解码混淆' },
|
||
{ id: 'obf-12', category: 'obfuscation', severity: 'high', pattern: /\['\\x/, description: '属性名十六进制' },
|
||
{ id: 'obf-13', category: 'obfuscation', severity: 'high', pattern: /globalThis\[/, description: 'globalThis 动态访问' },
|
||
{ id: 'obf-14', category: 'obfuscation', severity: 'high', pattern: /Reflect\.apply/, description: 'Reflect 调用' },
|
||
];
|
||
|
||
const execution: ThreatPattern[] = [
|
||
{ id: 'exe-01', category: 'execution', severity: 'high', pattern: /child_process/, description: 'child_process 模块' },
|
||
{ id: 'exe-02', category: 'execution', severity: 'high', pattern: /require\s*\(\s*['"]child_process['"]/, description: 'require child_process' },
|
||
{ id: 'exe-03', category: 'execution', severity: 'high', pattern: /execSync\s*\(/, description: 'execSync 调用' },
|
||
{ id: 'exe-04', category: 'execution', severity: 'high', pattern: /spawnSync\s*\(/, description: 'spawnSync 调用' },
|
||
{ id: 'exe-05', category: 'execution', severity: 'high', pattern: /os\.system\s*\(/, description: 'Python os.system' },
|
||
{ id: 'exe-06', category: 'execution', severity: 'high', pattern: /subprocess\.(run|call|Popen)/, description: 'Python subprocess' },
|
||
];
|
||
|
||
const pathTraversal: ThreatPattern[] = [
|
||
{ id: 'pt-01', category: 'path_traversal', severity: 'high', pattern: /\.\.\/\.\.\//, description: '路径穿越' },
|
||
{ id: 'pt-02', category: 'path_traversal', severity: 'high', pattern: /\/etc\/passwd/, description: '系统密码文件' },
|
||
{ id: 'pt-03', category: 'path_traversal', severity: 'high', pattern: /\/proc\/self/, description: 'proc 自身信息' },
|
||
{ id: 'pt-04', category: 'path_traversal', severity: 'high', pattern: /\/proc\/\d+\//, description: 'proc 进程信息' },
|
||
{ id: 'pt-05', category: 'path_traversal', severity: 'high', pattern: /\/dev\/(tcp|udp)\//, description: '设备文件网络' },
|
||
];
|
||
|
||
const cryptoMining: ThreatPattern[] = [
|
||
{ id: 'cm-01', category: 'crypto_mining', severity: 'critical', pattern: /stratum\+tcp:\/\//, description: '矿池协议' },
|
||
{ id: 'cm-02', category: 'crypto_mining', severity: 'critical', pattern: /xmrig|cpuminer|cgminer|bfgminer/i, description: '挖矿软件' },
|
||
];
|
||
|
||
const supplyChain: ThreatPattern[] = [
|
||
{ id: 'sc-01', category: 'supply_chain', severity: 'critical', pattern: /curl\s+[^|]*\|\s*(ba)?sh/, description: 'curl pipe to shell' },
|
||
{ id: 'sc-02', category: 'supply_chain', severity: 'critical', pattern: /wget\s+[^|]*\|\s*(ba)?sh/, description: 'wget pipe to shell' },
|
||
{ id: 'sc-03', category: 'supply_chain', severity: 'high', pattern: /pip\s+install\s+--index-url\s+http:/, description: '不安全 pip 源' },
|
||
{ id: 'sc-04', category: 'supply_chain', severity: 'high', pattern: /npm\s+install\s+--registry\s+http:/, description: '不安全 npm 源' },
|
||
{ id: 'sc-05', category: 'supply_chain', severity: 'high', pattern: /install.*@latest\b/, description: '未固定版本依赖' },
|
||
{ id: 'sc-06', category: 'supply_chain', severity: 'high', pattern: /postinstall|preinstall.*curl|wget/i, description: '安装钩子远程获取' },
|
||
];
|
||
|
||
const privilegeEscalation: ThreatPattern[] = [
|
||
{ id: 'pe-01', category: 'privilege_escalation', severity: 'high', pattern: /sudo\s+-[sS]/, description: 'sudo shell' },
|
||
{ id: 'pe-02', category: 'privilege_escalation', severity: 'high', pattern: /setuid|setgid|seteuid/, description: '设置 UID/GID' },
|
||
{ id: 'pe-03', category: 'privilege_escalation', severity: 'high', pattern: /NOPASSWD/, description: '免密 sudo' },
|
||
{ id: 'pe-04', category: 'privilege_escalation', severity: 'high', pattern: /chmod\s+[u+]*s\s/, description: 'setuid 位' },
|
||
{ id: 'pe-05', category: 'privilege_escalation', severity: 'high', pattern: /capability.*cap_sys_admin/i, description: 'Linux capability' },
|
||
];
|
||
|
||
const credentialExposure: ThreatPattern[] = [
|
||
{ id: 'ce-01', category: 'credential_exposure', severity: 'critical', pattern: /password\s*[:=]\s*['"][^'"]{8,}/i, description: '硬编码密码' },
|
||
{ id: 'ce-02', category: 'credential_exposure', severity: 'critical', pattern: /secret\s*[:=]\s*['"][^'"]{8,}/i, description: '硬编码密钥' },
|
||
{ id: 'ce-03', category: 'credential_exposure', severity: 'critical', pattern: /token\s*[:=]\s*['"][A-Za-z0-9_\-]{20,}/i, description: '硬编码 token' },
|
||
{ id: 'ce-04', category: 'credential_exposure', severity: 'critical', pattern: /AKIA[0-9A-Z]{16}/, description: 'AWS Access Key' },
|
||
{ id: 'ce-05', category: 'credential_exposure', severity: 'critical', pattern: /ghp_[A-Za-z0-9]{36}/, description: 'GitHub PAT' },
|
||
];
|
||
|
||
export const ALL_PATTERNS: ThreatPattern[] = [
|
||
...exfiltration,
|
||
...promptInjection,
|
||
...destructive,
|
||
...persistence,
|
||
...network,
|
||
...obfuscation,
|
||
...execution,
|
||
...pathTraversal,
|
||
...cryptoMining,
|
||
...supplyChain,
|
||
...privilegeEscalation,
|
||
...credentialExposure,
|
||
];
|
||
```
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add src/modules/netaclaw/skill_evolution/guard_patterns.ts
|
||
git commit -m "feat(skill-evolution): add 84 threat pattern definitions for SkillGuard"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: Create guard.ts — scan engine
|
||
|
||
**Files:**
|
||
- Create: `src/modules/netaclaw/skill_evolution/guard.ts`
|
||
|
||
- [ ] **Step 1: Implement scanSkill()**
|
||
|
||
Create `src/modules/netaclaw/skill_evolution/guard.ts`:
|
||
|
||
```typescript
|
||
import * as fs from 'fs';
|
||
import * as path from 'path';
|
||
import { ALL_PATTERNS, BLOCKED_EXTENSIONS, ALLOWED_SUBDIRS, LIMITS, Severity } from './guard_patterns.js';
|
||
|
||
export interface ScanFinding {
|
||
category: string;
|
||
severity: Severity;
|
||
pattern: string;
|
||
match: string;
|
||
file: string;
|
||
line: number;
|
||
}
|
||
|
||
export interface ScanResult {
|
||
verdict: 'safe' | 'caution' | 'dangerous';
|
||
findings: ScanFinding[];
|
||
summary: string;
|
||
}
|
||
|
||
function scanFileContent(content: string, filePath: string): ScanFinding[] {
|
||
const findings: ScanFinding[] = [];
|
||
const lines = content.split('\n');
|
||
for (let i = 0; i < lines.length; i++) {
|
||
for (const tp of ALL_PATTERNS) {
|
||
const m = lines[i].match(tp.pattern);
|
||
if (m) {
|
||
findings.push({
|
||
category: tp.category,
|
||
severity: tp.severity,
|
||
pattern: tp.id,
|
||
match: m[0].slice(0, 80),
|
||
file: filePath,
|
||
line: i + 1,
|
||
});
|
||
}
|
||
}
|
||
}
|
||
return findings;
|
||
}
|
||
|
||
function checkStructure(skillDir: string): ScanFinding[] {
|
||
const findings: ScanFinding[] = [];
|
||
let fileCount = 0;
|
||
let totalSize = 0;
|
||
|
||
function walk(dir: string, depth: number) {
|
||
if (!fs.existsSync(dir)) return;
|
||
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
||
const fullPath = path.join(dir, entry.name);
|
||
if (entry.isDirectory()) {
|
||
if (depth === 0 && !ALLOWED_SUBDIRS.has(entry.name)) {
|
||
findings.push({
|
||
category: 'structure', severity: 'high',
|
||
pattern: 'disallowed_dir', match: entry.name,
|
||
file: fullPath, line: 0,
|
||
});
|
||
}
|
||
walk(fullPath, depth + 1);
|
||
} else {
|
||
fileCount++;
|
||
const ext = path.extname(entry.name).toLowerCase();
|
||
if (BLOCKED_EXTENSIONS.has(ext)) {
|
||
findings.push({
|
||
category: 'structure', severity: 'critical',
|
||
pattern: 'blocked_extension', match: ext,
|
||
file: fullPath, line: 0,
|
||
});
|
||
}
|
||
const stat = fs.statSync(fullPath);
|
||
totalSize += stat.size;
|
||
if (stat.size > LIMITS.maxFileSize) {
|
||
findings.push({
|
||
category: 'structure', severity: 'high',
|
||
pattern: 'file_too_large', match: `${stat.size} bytes`,
|
||
file: fullPath, line: 0,
|
||
});
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
walk(skillDir, 0);
|
||
|
||
if (fileCount > LIMITS.maxFileCount) {
|
||
findings.push({
|
||
category: 'structure', severity: 'high',
|
||
pattern: 'too_many_files', match: `${fileCount} files`,
|
||
file: skillDir, line: 0,
|
||
});
|
||
}
|
||
if (totalSize > LIMITS.maxTotalSize) {
|
||
findings.push({
|
||
category: 'structure', severity: 'high',
|
||
pattern: 'total_size_exceeded', match: `${totalSize} bytes`,
|
||
file: skillDir, line: 0,
|
||
});
|
||
}
|
||
|
||
return findings;
|
||
}
|
||
|
||
function determineVerdict(findings: ScanFinding[]): ScanResult['verdict'] {
|
||
if (findings.length === 0) return 'safe';
|
||
if (findings.some(f => f.severity === 'critical')) return 'dangerous';
|
||
return 'caution';
|
||
}
|
||
|
||
export function scanSkill(skillDir: string): ScanResult {
|
||
const findings: ScanFinding[] = [];
|
||
|
||
// 结构检查
|
||
findings.push(...checkStructure(skillDir));
|
||
|
||
// 内容扫描
|
||
function scanDir(dir: string) {
|
||
if (!fs.existsSync(dir)) return;
|
||
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
||
const fullPath = path.join(dir, entry.name);
|
||
if (entry.isDirectory()) {
|
||
scanDir(fullPath);
|
||
} else {
|
||
const ext = path.extname(entry.name).toLowerCase();
|
||
if (BLOCKED_EXTENSIONS.has(ext)) continue;
|
||
try {
|
||
const content = fs.readFileSync(fullPath, 'utf-8');
|
||
const relPath = path.relative(skillDir, fullPath);
|
||
findings.push(...scanFileContent(content, relPath));
|
||
} catch {
|
||
// 二进制文件读取失败，跳过
|
||
}
|
||
}
|
||
}
|
||
}
|
||
scanDir(skillDir);
|
||
|
||
const verdict = determineVerdict(findings);
|
||
const summary = findings.length === 0
|
||
? 'No threats detected.'
|
||
: `Found ${findings.length} issue(s): ${findings.filter(f => f.severity === 'critical').length} critical, ${findings.filter(f => f.severity === 'high').length} high.`;
|
||
|
||
return { verdict, findings, summary };
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Verify no TypeScript errors**
|
||
|
||
```bash
|
||
cd packages/backend && npx tsc --noEmit
|
||
```
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add src/modules/netaclaw/skill_evolution/guard.ts
|
||
git commit -m "feat(skill-evolution): implement SkillGuard scan engine"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: Create skill_writer.ts — atomic write + validation + DB sync
|
||
|
||
**Files:**
|
||
- Create: `src/modules/netaclaw/skill_evolution/skill_writer.ts`
|
||
|
||
- [ ] **Step 1: Implement SkillWriter**
|
||
|
||
Create `src/modules/netaclaw/skill_evolution/skill_writer.ts`:
|
||
|
||
```typescript
|
||
import * as fs from 'fs';
|
||
import * as path from 'path';
|
||
import { Repository } from 'typeorm';
|
||
import { NetaClawSkillEntity } from '../entity/skill.js';
|
||
import { SkillLoaderService } from '../service/skill_loader.js';
|
||
import { scanSkill, ScanResult } from './guard.js';
|
||
import { LIMITS } from './guard_patterns.js';
|
||
|
||
export interface WriteResult {
|
||
success: boolean;
|
||
message: string;
|
||
scanResult?: ScanResult;
|
||
}
|
||
|
||
function validateName(name: string): string | null {
|
||
if (!name || name.length > LIMITS.maxNameLength) return `名称长度须在 1-${LIMITS.maxNameLength} 字符`;
|
||
if (!LIMITS.namePattern.test(name)) return '名称只允许小写字母、数字、连字符、下划线、点，且必须以字母或数字开头';
|
||
return null;
|
||
}
|
||
|
||
function validateFrontmatter(content: string): string | null {
|
||
const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
|
||
if (!fmMatch) return 'SKILL.md 必须包含 YAML frontmatter (--- ... ---)';
|
||
const fm = fmMatch[1];
|
||
if (!/^name:\s*.+$/m.test(fm)) return 'frontmatter 必须包含 name 字段';
|
||
if (!/^description:\s*.+$/m.test(fm)) return 'frontmatter 必须包含 description 字段';
|
||
const descMatch = fm.match(/^description:\s*(.+)$/m);
|
||
if (descMatch && descMatch[1].length > LIMITS.maxDescriptionLength) {
|
||
return `description 最长 ${LIMITS.maxDescriptionLength} 字符`;
|
||
}
|
||
return null;
|
||
}
|
||
|
||
function acquireLock(lockPath: string, timeoutMs = 5000): boolean {
|
||
const start = Date.now();
|
||
while (Date.now() - start < timeoutMs) {
|
||
try {
|
||
fs.mkdirSync(lockPath);
|
||
return true;
|
||
} catch {
|
||
// lock exists, wait
|
||
const elapsed = Date.now() - start;
|
||
if (elapsed >= timeoutMs) return false;
|
||
// busy wait 50ms
|
||
const end = Date.now() + 50;
|
||
while (Date.now() < end) { /* spin */ }
|
||
}
|
||
}
|
||
return false;
|
||
}
|
||
|
||
function releaseLock(lockPath: string): void {
|
||
try { fs.rmdirSync(lockPath); } catch { /* ignore */ }
|
||
}
|
||
|
||
export class SkillWriter {
|
||
constructor(
|
||
private skillsDir: string,
|
||
private skillRepo: Repository<NetaClawSkillEntity>,
|
||
private skillLoader: SkillLoaderService,
|
||
) {}
|
||
|
||
async createSkill(name: string, content: string, category?: string): Promise<WriteResult> {
|
||
const nameErr = validateName(name);
|
||
if (nameErr) return { success: false, message: nameErr };
|
||
if (content.length > LIMITS.maxContentLength) {
|
||
return { success: false, message: `内容超过 ${LIMITS.maxContentLength} 字符限制` };
|
||
}
|
||
const fmErr = validateFrontmatter(content);
|
||
if (fmErr) return { success: false, message: fmErr };
|
||
|
||
const skillDir = category
|
||
? path.join(this.skillsDir, category, name)
|
||
: path.join(this.skillsDir, name);
|
||
|
||
if (fs.existsSync(path.join(skillDir, 'SKILL.md'))) {
|
||
return { success: false, message: `Skill "${name}" 已存在，请用 edit 或 patch` };
|
||
}
|
||
|
||
return this.atomicWrite(skillDir, name, content);
|
||
}
|
||
|
||
async editSkill(name: string, content: string): Promise<WriteResult> {
|
||
if (content.length > LIMITS.maxContentLength) {
|
||
return { success: false, message: `内容超过 ${LIMITS.maxContentLength} 字符限制` };
|
||
}
|
||
const fmErr = validateFrontmatter(content);
|
||
if (fmErr) return { success: false, message: fmErr };
|
||
|
||
const skillDir = this.findSkillDir(name);
|
||
if (!skillDir) return { success: false, message: `Skill "${name}" 不存在` };
|
||
|
||
return this.atomicWrite(skillDir, name, content);
|
||
}
|
||
|
||
async patchSkill(name: string, oldStr: string, newStr: string, filePath?: string, replaceAll = false): Promise<WriteResult> {
|
||
const skillDir = this.findSkillDir(name);
|
||
if (!skillDir) return { success: false, message: `Skill "${name}" 不存在` };
|
||
|
||
const targetFile = filePath
|
||
? path.join(skillDir, filePath)
|
||
: path.join(skillDir, 'SKILL.md');
|
||
|
||
if (!fs.existsSync(targetFile)) {
|
||
return { success: false, message: `文件不存在: ${filePath ?? 'SKILL.md'}` };
|
||
}
|
||
|
||
let content = fs.readFileSync(targetFile, 'utf-8');
|
||
if (!content.includes(oldStr)) {
|
||
return { success: false, message: '未找到要替换的文本' };
|
||
}
|
||
|
||
if (replaceAll) {
|
||
content = content.split(oldStr).join(newStr);
|
||
} else {
|
||
const idx = content.indexOf(oldStr);
|
||
content = content.slice(0, idx) + newStr + content.slice(idx + oldStr.length);
|
||
}
|
||
|
||
// 如果是 SKILL.md，验证 frontmatter
|
||
if (!filePath || filePath === 'SKILL.md') {
|
||
const fmErr = validateFrontmatter(content);
|
||
if (fmErr) return { success: false, message: fmErr };
|
||
}
|
||
|
||
return this.atomicWrite(skillDir, name, content, filePath);
|
||
}
|
||
|
||
async deleteSkill(name: string): Promise<WriteResult> {
|
||
const skillDir = this.findSkillDir(name);
|
||
if (!skillDir) return { success: false, message: `Skill "${name}" 不存在` };
|
||
|
||
fs.rmSync(skillDir, { recursive: true, force: true });
|
||
await this.skillRepo.delete({ name });
|
||
await this.skillLoader.reloadSkill(name);
|
||
return { success: true, message: `Skill "${name}" 已删除` };
|
||
}
|
||
|
||
async writeFile(name: string, filePath: string, fileContent: string): Promise<WriteResult> {
|
||
const skillDir = this.findSkillDir(name);
|
||
if (!skillDir) return { success: false, message: `Skill "${name}" 不存在` };
|
||
|
||
// 验证子目录
|
||
const firstSegment = filePath.split('/')[0];
|
||
const allowed = new Set(['references', 'templates', 'scripts', 'assets']);
|
||
if (!allowed.has(firstSegment)) {
|
||
return { success: false, message: `只允许写入 references/, templates/, scripts/, assets/ 子目录` };
|
||
}
|
||
|
||
if (Buffer.byteLength(fileContent) > LIMITS.maxFileSize) {
|
||
return { success: false, message: `文件超过 ${LIMITS.maxFileSize} 字节限制` };
|
||
}
|
||
|
||
const lockPath = path.join(skillDir, '.lock');
|
||
if (!acquireLock(lockPath)) {
|
||
return { success: false, message: '无法获取文件锁，请稍后重试' };
|
||
}
|
||
|
||
try {
|
||
const fullPath = path.join(skillDir, filePath);
|
||
fs.mkdirSync(path.dirname(fullPath), { recursive: true });
|
||
fs.writeFileSync(fullPath, fileContent, 'utf-8');
|
||
|
||
// 扫描整个 skill 目录
|
||
const scanResult = scanSkill(skillDir);
|
||
if (scanResult.verdict === 'dangerous') {
|
||
fs.unlinkSync(fullPath);
|
||
return { success: false, message: `安全扫描未通过: ${scanResult.summary}`, scanResult };
|
||
}
|
||
|
||
return { success: true, message: `文件已写入: ${filePath}`, scanResult };
|
||
} finally {
|
||
releaseLock(lockPath);
|
||
}
|
||
}
|
||
|
||
async removeFile(name: string, filePath: string): Promise<WriteResult> {
|
||
const skillDir = this.findSkillDir(name);
|
||
if (!skillDir) return { success: false, message: `Skill "${name}" 不存在` };
|
||
|
||
const fullPath = path.join(skillDir, filePath);
|
||
if (!fs.existsSync(fullPath)) {
|
||
return { success: false, message: `文件不存在: ${filePath}` };
|
||
}
|
||
fs.unlinkSync(fullPath);
|
||
return { success: true, message: `文件已删除: ${filePath}` };
|
||
}
|
||
|
||
private findSkillDir(name: string): string | null {
|
||
// 直接查找
|
||
const direct = path.join(this.skillsDir, name);
|
||
if (fs.existsSync(path.join(direct, 'SKILL.md'))) return direct;
|
||
// 在分类子目录中查找
|
||
if (!fs.existsSync(this.skillsDir)) return null;
|
||
for (const cat of fs.readdirSync(this.skillsDir, { withFileTypes: true })) {
|
||
if (!cat.isDirectory()) continue;
|
||
const nested = path.join(this.skillsDir, cat.name, name);
|
||
if (fs.existsSync(path.join(nested, 'SKILL.md'))) return nested;
|
||
}
|
||
return null;
|
||
}
|
||
|
||
private async atomicWrite(skillDir: string, name: string, content: string, filePath?: string): Promise<WriteResult> {
|
||
const lockPath = path.join(skillDir, '.lock');
|
||
fs.mkdirSync(skillDir, { recursive: true });
|
||
|
||
if (!acquireLock(lockPath)) {
|
||
return { success: false, message: '无法获取文件锁，请稍后重试' };
|
||
}
|
||
|
||
try {
|
||
const targetFile = filePath
|
||
? path.join(skillDir, filePath)
|
||
: path.join(skillDir, 'SKILL.md');
|
||
const tmpFile = targetFile + '.tmp';
|
||
|
||
// 写入临时文件
|
||
fs.mkdirSync(path.dirname(targetFile), { recursive: true });
|
||
fs.writeFileSync(tmpFile, content, 'utf-8');
|
||
|
||
// 安全扫描（扫描临时文件，在 rename 之前）
|
||
// 临时将 tmp 文件 rename 为正式名以便 scanSkill 扫描整个目录
|
||
// 但先备份原文件，扫描后根据结果决定保留还是回滚
|
||
const origExists = fs.existsSync(targetFile);
|
||
let origContent: string | null = null;
|
||
if (origExists) {
|
||
origContent = fs.readFileSync(targetFile, 'utf-8');
|
||
fs.unlinkSync(targetFile);
|
||
}
|
||
fs.renameSync(tmpFile, targetFile);
|
||
|
||
const scanResult = scanSkill(skillDir);
|
||
|
||
if (scanResult.verdict === 'dangerous') {
|
||
// 回滚：恢复原文件或删除新文件
|
||
if (origContent !== null) {
|
||
fs.writeFileSync(targetFile, origContent, 'utf-8');
|
||
} else {
|
||
fs.unlinkSync(targetFile);
|
||
}
|
||
return { success: false, message: `安全扫描未通过: ${scanResult.summary}`, scanResult };
|
||
}
|
||
|
||
// 同步 DB
|
||
await this.syncDb(name, content);
|
||
// 热更新缓存
|
||
await this.skillLoader.reloadSkill(name);
|
||
|
||
const level = scanResult.verdict === 'caution' ? ' (有警告)' : '';
|
||
return { success: true, message: `Skill "${name}" 已保存${level}`, scanResult };
|
||
} finally {
|
||
releaseLock(lockPath);
|
||
}
|
||
}
|
||
|
||
private async syncDb(name: string, content: string): Promise<void> {
|
||
const descMatch = content.match(/^description:\s*(.+)$/m);
|
||
const description = descMatch?.[1]?.trim() ?? '';
|
||
const existing = await this.skillRepo.findOneBy({ name });
|
||
if (existing) {
|
||
await this.skillRepo.update({ name }, { description });
|
||
} else {
|
||
await this.skillRepo.save({ name, label: name, description, status: 1 } as any);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Verify no TypeScript errors**
|
||
|
||
```bash
|
||
cd packages/backend && npx tsc --noEmit
|
||
```
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add src/modules/netaclaw/skill_evolution/skill_writer.ts
|
||
git commit -m "feat(skill-evolution): implement SkillWriter with atomic write, validation, and security scan"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: Extend SkillLoaderService — add reloadSkill() and getSkillSummaries()
|
||
|
||
**Files:**
|
||
- Modify: `src/modules/netaclaw/service/skill_loader.ts`
|
||
|
||
- [ ] **Step 1: Add reloadSkill() method**
|
||
|
||
In `src/modules/netaclaw/service/skill_loader.ts`, add the following methods inside the class body, before the closing `}` of the class (before line 137, after the `setSkillStatus` method):
|
||
|
||
```typescript
|
||
/** 热更新单个 Skill（skill_manage 写入后调用） */
|
||
async reloadSkill(name: string): Promise<void> {
|
||
// 先从缓存中移除
|
||
this.skills.delete(name);
|
||
|
||
// 尝试重新加载
|
||
const findInDir = async (dir: string): Promise<boolean> => {
|
||
try {
|
||
const entries = await fs.readdir(dir, { withFileTypes: true });
|
||
for (const entry of entries) {
|
||
if (!entry.isDirectory()) continue;
|
||
const skillMdPath = path.join(dir, entry.name, 'SKILL.md');
|
||
if (entry.name === name) {
|
||
try {
|
||
const raw = await fs.readFile(skillMdPath, 'utf-8');
|
||
const skill = this.parseSkillMd(raw);
|
||
if (skill) {
|
||
this.skills.set(skill.name, skill);
|
||
this.logger.info('[SkillLoader] 已重新加载 Skill: %s', skill.name);
|
||
return true;
|
||
}
|
||
} catch { /* file not found */ }
|
||
}
|
||
// 检查分类子目录
|
||
const nestedPath = path.join(dir, entry.name, name, 'SKILL.md');
|
||
try {
|
||
const raw = await fs.readFile(nestedPath, 'utf-8');
|
||
const skill = this.parseSkillMd(raw);
|
||
if (skill) {
|
||
this.skills.set(skill.name, skill);
|
||
this.logger.info('[SkillLoader] 已重新加载 Skill: %s (分类: %s)', skill.name, entry.name);
|
||
return true;
|
||
}
|
||
} catch { /* not in this category */ }
|
||
}
|
||
} catch { /* dir not found */ }
|
||
return false;
|
||
};
|
||
|
||
await findInDir(this.skillsDir);
|
||
}
|
||
|
||
/** 获取 Skill 列表摘要（给 review agent 用） */
|
||
getSkillSummaries(): { name: string; description: string }[] {
|
||
return Array.from(this.skills.values()).map(s => ({
|
||
name: s.name,
|
||
description: s.description,
|
||
}));
|
||
}
|
||
|
||
/** 获取 skills 目录路径 */
|
||
getSkillsDir(): string {
|
||
return this.skillsDir;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Verify no TypeScript errors**
|
||
|
||
```bash
|
||
cd packages/backend && npx tsc --noEmit
|
||
```
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add src/modules/netaclaw/service/skill_loader.ts
|
||
git commit -m "feat(skill-evolution): add reloadSkill(), getSkillSummaries(), getSkillsDir() to SkillLoader"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: Create skill_manage tool
|
||
|
||
**Files:**
|
||
- Create: `src/modules/netaclaw/tools/builtin/skill_manage.ts`
|
||
|
||
- [ ] **Step 1: Implement createSkillManageTool**
|
||
|
||
Create `src/modules/netaclaw/tools/builtin/skill_manage.ts`:
|
||
|
||
```typescript
|
||
import { Type, Static } from '@sinclair/typebox';
|
||
import { AnyAgentTool } from '../common.js';
|
||
import { SkillWriter } from '../../skill_evolution/skill_writer.js';
|
||
|
||
const skillManageParams = Type.Object({
|
||
action: Type.Union([
|
||
Type.Literal('create'), Type.Literal('edit'), Type.Literal('patch'),
|
||
Type.Literal('delete'), Type.Literal('write_file'), Type.Literal('remove_file'),
|
||
]),
|
||
name: Type.String({ description: 'Skill 名称（小写字母数字连字符）' }),
|
||
content: Type.Optional(Type.String({ description: 'SKILL.md 完整内容（create/edit 时必需）' })),
|
||
old_string: Type.Optional(Type.String({ description: 'patch: 要替换的文本' })),
|
||
new_string: Type.Optional(Type.String({ description: 'patch: 替换后的文本' })),
|
||
replace_all: Type.Optional(Type.Boolean({ description: 'patch: 替换所有匹配', default: false })),
|
||
category: Type.Optional(Type.String({ description: '可选分类目录' })),
|
||
file_path: Type.Optional(Type.String({ description: '支持文件路径（write_file/remove_file）' })),
|
||
file_content: Type.Optional(Type.String({ description: '支持文件内容（write_file）' })),
|
||
});
|
||
|
||
type SkillManageParams = Static<typeof skillManageParams>;
|
||
|
||
export interface SkillManageToolOpts {
|
||
allowedEditSkills?: string[]; // 允许编辑的已有 skill 列表
|
||
allowCreateNew?: boolean; // 是否允许创建新 skill
|
||
}
|
||
|
||
export function createSkillManageTool(
|
||
writer: SkillWriter,
|
||
opts: SkillManageToolOpts = {},
|
||
): AnyAgentTool {
|
||
const { allowedEditSkills = [], allowCreateNew = true } = opts;
|
||
|
||
return {
|
||
name: 'skill_manage',
|
||
label: '管理 Skill',
|
||
description: '创建、编辑、修补或删除 Skill。支持写入/删除支持文件。',
|
||
parameters: skillManageParams,
|
||
async execute(_id: string, params: SkillManageParams): Promise<string> {
|
||
const { action, name } = params;
|
||
|
||
// 权限检查
|
||
if ((action === 'edit' || action === 'patch') && allowedEditSkills.length > 0) {
|
||
if (!allowedEditSkills.includes(name)) {
|
||
return `错误: 不允许编辑 Skill "${name}"，只能编辑: ${allowedEditSkills.join(', ')}`;
|
||
}
|
||
}
|
||
if (action === 'create' && !allowCreateNew) {
|
||
return '错误: 当前配置不允许创建新 Skill';
|
||
}
|
||
|
||
switch (action) {
|
||
case 'create': {
|
||
if (!params.content) return '错误: create 操作需要 content 参数';
|
||
const r = await writer.createSkill(name, params.content, params.category);
|
||
return r.message;
|
||
}
|
||
case 'edit': {
|
||
if (!params.content) return '错误: edit 操作需要 content 参数';
|
||
const r = await writer.editSkill(name, params.content);
|
||
return r.message;
|
||
}
|
||
case 'patch': {
|
||
if (!params.old_string || params.new_string === undefined) {
|
||
return '错误: patch 操作需要 old_string 和 new_string 参数';
|
||
}
|
||
const r = await writer.patchSkill(name, params.old_string, params.new_string, params.file_path, params.replace_all);
|
||
return r.message;
|
||
}
|
||
case 'delete': {
|
||
const r = await writer.deleteSkill(name);
|
||
return r.message;
|
||
}
|
||
case 'write_file': {
|
||
if (!params.file_path || !params.file_content) {
|
||
return '错误: write_file 操作需要 file_path 和 file_content 参数';
|
||
}
|
||
const r = await writer.writeFile(name, params.file_path, params.file_content);
|
||
return r.message;
|
||
}
|
||
case 'remove_file': {
|
||
if (!params.file_path) return '错误: remove_file 操作需要 file_path 参数';
|
||
const r = await writer.removeFile(name, params.file_path);
|
||
return r.message;
|
||
}
|
||
default:
|
||
return `错误: 未知操作 "${action}"`;
|
||
}
|
||
},
|
||
};
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Commit**
|
||
|
||
```bash
|
||
git add src/modules/netaclaw/tools/builtin/skill_manage.ts
|
||
git commit -m "feat(skill-evolution): add skill_manage tool with permission checks"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 6: Create skill_list tool
|
||
|
||
**Files:**
|
||
- Create: `src/modules/netaclaw/tools/builtin/skill_list.ts`
|
||
|
||
- [ ] **Step 1: Implement createSkillListTool**
|
||
|
||
Create `src/modules/netaclaw/tools/builtin/skill_list.ts`:
|
||
|
||
```typescript
|
||
import { Type, Static } from '@sinclair/typebox';
|
||
import { AnyAgentTool } from '../common.js';
|
||
import { SkillLoaderService } from '../../service/skill_loader.js';
|
||
|
||
const skillListParams = Type.Object({
|
||
category: Type.Optional(Type.String({ description: '按分类过滤' })),
|
||
});
|
||
|
||
type SkillListParams = Static<typeof skillListParams>;
|
||
|
||
export function createSkillListTool(skillLoader: SkillLoaderService): AnyAgentTool {
|
||
return {
|
||
name: 'skill_list',
|
||
label: '查看 Skill 列表',
|
||
description: '列出所有已有的 Skill 及其描述，用于避免重复创建。',
|
||
parameters: skillListParams,
|
||
async execute(_id: string, _params: SkillListParams): Promise<string> {
|
||
const summaries = skillLoader.getSkillSummaries();
|
||
if (summaries.length === 0) return '当前没有任何 Skill。';
|
||
return summaries.map(s => `- ${s.name}: ${s.description}`).join('\n');
|
||
},
|
||
};
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Commit**
|
||
|
||
```bash
|
||
git add src/modules/netaclaw/tools/builtin/skill_list.ts
|
||
git commit -m "feat(skill-evolution): add skill_list read-only tool"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 7: Create review.ts — background review agent
|
||
|
||
**Files:**
|
||
- Create: `src/modules/netaclaw/skill_evolution/review.ts`
|
||
|
||
- [ ] **Step 1: Implement spawnSkillReview and buildSkillReviewPrompt**
|
||
|
||
Create `src/modules/netaclaw/skill_evolution/review.ts`:
|
||
|
||
```typescript
|
||
import { LLMMessage } from '../plugins/plugin_entry.js';
|
||
import { AgentConfig, runAgent } from '../runtime/agent.js';
|
||
import { AnyAgentTool } from '../tools/common.js';
|
||
import { SkillLoaderService } from '../service/skill_loader.js';
|
||
import { SkillWriter } from './skill_writer.js';
|
||
import { createSkillManageTool, SkillManageToolOpts } from '../tools/builtin/skill_manage.js';
|
||
import { createSkillListTool } from '../tools/builtin/skill_list.js';
|
||
import { Repository } from 'typeorm';
|
||
import { NetaClawSkillEntity } from '../entity/skill.js';
|
||
import { NetaClawAgentEntity } from '../entity/agent.js';
|
||
|
||
const SKILL_REVIEW_SYSTEM_PROMPT = `你是一个 Skill 提炼专家。你的任务是分析对话历史，提取可复用的方法论并保存为 Skill。
|
||
|
||
Skill 格式要求：
|
||
- SKILL.md 必须包含 YAML frontmatter（name + description）
|
||
- 正文用 Markdown，包含：触发条件、工作流程、规则约束
|
||
- name 使用小写字母、数字、连字符（如 nginx-deploy-config）
|
||
- description 一句话描述 skill 的用途
|
||
|
||
你只有 8 轮工具调用机会，请高效行动。`;
|
||
|
||
export function buildSkillReviewPrompt(
|
||
linkedSkills: string[],
|
||
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;
|
||
}
|
||
|
||
export interface SkillReviewContext {
|
||
conversationHistory: LLMMessage[];
|
||
parentAgentConfig: AgentConfig;
|
||
skillLoader: SkillLoaderService;
|
||
skillRepo: Repository<NetaClawSkillEntity>;
|
||
agentRepo: Repository<NetaClawAgentEntity>; // 用于自动关联新 skill
|
||
agentName: string;
|
||
linkedSkills: string[];
|
||
allowOptimize: boolean;
|
||
allowCreateNew: boolean;
|
||
}
|
||
|
||
export 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,
|
||
skills: [], // 清除继承的 skills，review agent 不需要父 agent 的 skill prompts
|
||
};
|
||
|
||
const writer = new SkillWriter(
|
||
ctx.skillLoader.getSkillsDir(),
|
||
ctx.skillRepo,
|
||
ctx.skillLoader,
|
||
);
|
||
|
||
const toolOpts: SkillManageToolOpts = {
|
||
allowedEditSkills: ctx.allowOptimize ? ctx.linkedSkills : [],
|
||
allowCreateNew: ctx.allowCreateNew,
|
||
};
|
||
|
||
const tools: AnyAgentTool[] = [
|
||
createSkillManageTool(writer, toolOpts),
|
||
createSkillListTool(ctx.skillLoader),
|
||
];
|
||
|
||
// 快照当前 skill 列表，用于 review 后检测新增
|
||
const skillsBefore = new Set(ctx.skillLoader.getSkillSummaries().map(s => s.name));
|
||
|
||
await runAgent({
|
||
agentConfig: reviewConfig,
|
||
tools,
|
||
userMessage: reviewPrompt,
|
||
history: ctx.conversationHistory,
|
||
});
|
||
|
||
// 自动关联新创建的 skill 到当前 Agent
|
||
if (ctx.allowCreateNew) {
|
||
const skillsAfter = ctx.skillLoader.getSkillSummaries().map(s => s.name);
|
||
const newSkills = skillsAfter.filter(s => !skillsBefore.has(s));
|
||
if (newSkills.length > 0) {
|
||
const agent = await ctx.agentRepo.findOneBy({ name: ctx.agentName });
|
||
if (agent) {
|
||
const updated = [...(agent.skills ?? []), ...newSkills];
|
||
await ctx.agentRepo.update({ name: ctx.agentName }, { skills: updated });
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Verify no TypeScript errors**
|
||
|
||
```bash
|
||
cd packages/backend && npx tsc --noEmit
|
||
```
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add src/modules/netaclaw/skill_evolution/review.ts
|
||
git commit -m "feat(skill-evolution): implement background skill review agent"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 8: Integrate skill evolution trigger into controller/chat.ts
|
||
|
||
**Files:**
|
||
- Modify: `src/modules/netaclaw/controller/chat.ts`
|
||
|
||
- [ ] **Step 1: Add imports and inject dependencies**
|
||
|
||
In `src/modules/netaclaw/controller/chat.ts`, add new imports at the top (after existing imports, avoid duplicating already-present ones):
|
||
|
||
```typescript
|
||
import { InjectEntityModel } from '@midwayjs/typeorm';
|
||
import { Repository } from 'typeorm';
|
||
import { NetaClawSkillEntity } from '../entity/skill.js';
|
||
import { spawnSkillReview } from '../skill_evolution/review.js';
|
||
```
|
||
|
||
Note: `NetaClawAgentService` and `@Inject()` are already imported in the file. Only add the above new imports.
|
||
|
||
Add injections inside the class (after `skillLoader`):
|
||
|
||
```typescript
|
||
@Inject()
|
||
agentService: NetaClawAgentService;
|
||
|
||
@InjectEntityModel(NetaClawSkillEntity)
|
||
skillRepo: Repository<NetaClawSkillEntity>;
|
||
```
|
||
|
||
Note: If `agentService` is already injected (check the file first), skip that injection.
|
||
|
||
- [ ] **Step 2: Add skill evolution trigger after runAgent()**
|
||
|
||
In the `chat` method, after `await this.sessionService.saveMessage(sessionId, { role: 'assistant', ... })` and before the `return` statement, add:
|
||
|
||
```typescript
|
||
// --- Skill 进化触发 ---
|
||
const agentEntity = await this.agentService.agentRepo.findOneBy({ name: agentName });
|
||
const evoConfig = (agentEntity?.config as any)?.skillEvolution;
|
||
if (evoConfig?.enabled && result.toolCallCount > 0) {
|
||
const session = await this.sessionService.sessionRepo.findOneBy({ sessionId });
|
||
const meta = (session?.metadata ?? {}) as Record<string, any>;
|
||
const totalCalls = (meta.toolCallsSinceReview ?? 0) + result.toolCallCount;
|
||
const nudgeInterval = evoConfig.nudgeInterval ?? 10;
|
||
|
||
if (totalCalls >= nudgeInterval) {
|
||
// 重置计数器
|
||
await this.sessionService.sessionRepo.update({ sessionId }, {
|
||
metadata: { ...meta, toolCallsSinceReview: 0 },
|
||
});
|
||
// 异步触发 review，不阻塞响应
|
||
spawnSkillReview({
|
||
conversationHistory: history,
|
||
parentAgentConfig: agentConfig,
|
||
skillLoader: this.skillLoader,
|
||
skillRepo: this.skillRepo,
|
||
agentRepo: this.agentService.agentRepo,
|
||
agentName,
|
||
linkedSkills: agentEntity?.skills ?? [],
|
||
allowOptimize: evoConfig.allowOptimizeLinked ?? true,
|
||
allowCreateNew: evoConfig.allowCreateNew ?? true,
|
||
}).catch(err => this.logger.warn('[SkillEvolution] Review failed:', err));
|
||
} else {
|
||
await this.sessionService.sessionRepo.update({ sessionId }, {
|
||
metadata: { ...meta, toolCallsSinceReview: totalCalls },
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Verify no TypeScript errors**
|
||
|
||
```bash
|
||
cd packages/backend && npx tsc --noEmit
|
||
```
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add src/modules/netaclaw/controller/chat.ts
|
||
git commit -m "feat(skill-evolution): integrate skill review trigger into chat controller"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 9: Final verification
|
||
|
||
- [ ] **Step 1: Verify full TypeScript compilation**
|
||
|
||
```bash
|
||
cd packages/backend && npx tsc --noEmit
|
||
```
|
||
Expected: No errors.
|
||
|
||
- [ ] **Step 2: Verify all new files exist**
|
||
|
||
```bash
|
||
ls -la src/modules/netaclaw/skill_evolution/
|
||
ls -la src/modules/netaclaw/tools/builtin/skill_manage.ts
|
||
ls -la src/modules/netaclaw/tools/builtin/skill_list.ts
|
||
```
|
||
|
||
Expected: guard_patterns.ts, guard.ts, skill_writer.ts, review.ts in skill_evolution/; skill_manage.ts and skill_list.ts in tools/builtin/.
|
||
|
||
- [ ] **Step 3: Verify skill_loader has new methods**
|
||
|
||
```bash
|
||
cd packages/backend && grep -n "reloadSkill\|getSkillSummaries\|getSkillsDir" src/modules/netaclaw/service/skill_loader.ts
|
||
```
|
||
|
||
Expected: All three methods found.
|
||
|
||
- [ ] **Step 4: Final commit**
|
||
|
||
```bash
|
||
git add -A && git status
|
||
git commit -m "feat(skill-evolution): complete skill self-evolution system"
|
||
```
|