【MiniClaw 深度解析】第七章：技能系统

# 第七章：技能系统 > 🔧 本章详细介绍 MiniClaw 的技能系统，包括技能发现、缓存机制和技能扩展。 --- ## 7.1 技能系统概述 ### 7.1.1 什么是技能系统？ 技能系统是 MiniClaw 的插件扩展机制，允许用户通过添加技能文件来扩展 Agent 的能力。 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 技能系统设计理念 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 传统 AI 助手 MiniClaw 技能系统 │ │ ┌───────────────────┐ ┌───────────────────┐ │ │ │ │ │ │ │ │ │ 固定功能 │ │ 插件化技能 │ │ │ │ 无法扩展 │ │ 用户可添加 │ │ │ │ 需要修改代码 │ │ 仅需添加文件 │ │ │ │ │ │ │ │ │ └───────────────────┘ └───────────────────┘ │ │ │ │ ❌ 功能固定 ✅ 灵活扩展 │ │ ❌ 需要编程知识 ✅ Markdown 即可 │ │ ❌ 升级困难 ✅ 热插拔 │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 7.1.2 技能系统架构 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 技能系统架构 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ │ │ │ 技能目录 │ │ │ │ ~/.miniclaw/ │ │ │ │ skills/ │ │ │ └──────┬──────┘ │ │ │ │ │ ┌───────────────┼───────────────┐ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │ │ 技能 A │ │ 技能 B │ │ 技能 C │ │ │ │ SKILL.md │ │ SKILL.md │ │ SKILL.md │ │ │ │ references/ │ │ script.sh │ │ prompts/ │ │ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │ │ │ │ │ │ └───────────────┼───────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ SkillCache │ │ │ │ • 扫描技能目录 │ │ │ │ • 解析 SKILL.md │ │ │ │ • 缓存技能元数据 │ │ │ │ • TTL = 5000ms │ │ │ └────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ MCP 暴露 │ │ │ │ • Prompts (提示词) │ │ │ │ • Tools (工具) │ │ │ │ • Resources (资源) │ │ │ └────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 7.2 技能目录结构 ### 7.2.1 标准技能目录 ``` ~/.miniclaw/skills/ │ ├── 📁 git-workflow/ # Git 工作流技能 │ ├── 📄 SKILL.md # 技能定义文件 │ └── 📁 references/ # 参考文档 │ ├── 📄 commit-style.md │ └── 📄 branch-strategy.md │ ├── 📁 code-review/ # 代码审查技能 │ ├── 📄 SKILL.md │ └── 📄 review-checklist.md │ ├── 📁 deployment/ # 部署技能 │ ├── 📄 SKILL.md │ ├── 📄 deploy.sh # 可执行脚本 │ └── 📁 references/ │ └── 📄 env-config.md │ └── 📁 api-testing/ # API 测试技能 ├── 📄 SKILL.md └── 📁 prompts/ # 提示词模板 ├── 📄 test-case.md └── 📄 report.md ``` ### 7.2.2 SKILL.md 文件结构 ```yaml --- name: git-workflow description: Git 工作流最佳实践 version: 1.0.0 author: user tags: [git, workflow, version-control] prompts: - name: commit_guide description: 提交信息编写指南 - name: branch_strategy description: 分支策略建议 tools: - name: analyze_diff description: 分析代码差异 resources: - uri: git-workflow://conventions name: Git 规范 --- # Git 工作流技能 ## 概述 本技能提供 Git 工作流的最佳实践指导。 ## 功能 - 分支命名规范 - 提交信息格式 - 合并策略建议 ## 使用场景 - 创建新分支时 - 编写提交信息时 - 解决合并冲突时 ``` --- ## 7.3 技能缓存机制 ### 7.3.1 SkillCache 实现 ```typescript class SkillCache { private cache: Map<string, SkillCacheEntry>; private lastScanTime: number = 0; private readonly TTL_MS = 5000; // 5 秒缓存有效期 async getAll(): Promise<Map<string, SkillCacheEntry>> { const now = Date.now(); // 缓存有效，直接返回 if (now - this.lastScanTime < this.TTL_MS) { return this.cache; } // 缓存过期，重新扫描 await this.refresh(); return this.cache; } private async refresh(): Promise<void> { // 1. 扫描 ~/.miniclaw/skills/ 目录 // 2. 读取每个子目录的 SKILL.md // 3. 解析 Frontmatter 和内容 // 4. 更新缓存 // 5. 更新 lastScanTime } } ``` ### 7.3.2 缓存策略说明 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 缓存策略说明 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ TTL = 5000ms (5 秒) │ │ │ │ 为什么选 5 秒？ │ │ • 足够短：新技能能快速被发现 │ │ • 足够长：避免频繁扫描文件系统 │ │ │ │ 性能影响： │ │ • 缓存命中：~1ms 返回结果 │ │ • 缓存未命中：~50-100ms 扫描目录 │ │ │ │ 调优建议： │ │ • 开发环境：可缩短到 1-2 秒 │ │ • 生产环境：可延长到 10-30 秒 │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 7.4 创建自定义技能 ### 7.4.1 技能创建步骤 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 技能创建步骤 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 步骤 1: 创建技能目录 │ │ $ mkdir -p ~/.miniclaw/skills/my-skill │ │ │ │ 步骤 2: 创建 SKILL.md │ │ $ cat > ~/.miniclaw/skills/my-skill/SKILL.md << 'EOF' │ --- │ name: my-skill │ description: 我的自定义技能 │ --- │ │ # My Skill │ │ 技能详细说明... │ EOF │ │ │ 步骤 3: 验证技能加载 │ │ • 重启 MCP 客户端 │ │ • 或使用 miniclaw_status 检查 │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 本章小结 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 第七章 核心要点 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 🔧 技能系统概念 │ │ • 插件化扩展机制 │ │ • Markdown 定义 │ │ • 热插拔支持 │ │ │ │ 📁 技能目录结构 │ │ • ~/.miniclaw/skills/ │ │ • 每个技能一个子目录 │ │ • SKILL.md 定义文件 │ │ │ │ 💾 技能缓存 │ │ • SkillCache 类 │ │ • TTL = 5000ms │ │ • 自动刷新机制 │ │ │ │ 🛠️ 创建技能 │ │ • 创建目录 │ │ • 编写 SKILL.md │ │ • 验证加载 │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- *本文档是《MiniClaw 深度解析》系列的第七章，下一章将详细介绍心跳与进化机制。*