第十六章：扩展性设计
🔧 本章介绍 MiniClaw 的扩展机制，包括技能、工具和提示词的扩展方式。
16.1 技能扩展
16.1.1 新技能创建流程
┌─────────────────────────────────────────────────────────────────────┐
│ 技能创建流程 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 步骤 1：创建技能目录 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ mkdir -p ~/.miniclaw/skills/my-skill │ │
│ │ cd ~/.miniclaw/skills/my-skill │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 步骤 2：创建 SKILL.md 文件 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ --- │ │
│ │ name: my-skill │ │
│ │ description: "我的自定义技能" │ │
│ │ prompts: │ │
│ │ - name: help │ │
│ │ description: "显示帮助信息" │ │
│ │ tools: │ │
│ │ - name: do_something │ │
│ │ description: "执行某个操作" │ │
│ │ --- │ │
│ │ │ │
│ │ # My Skill │ │
│ │ │ │
│ │ 这是一个自定义技能的详细说明... │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 步骤 3：验证技能加载 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ # 重启 MCP 客户端或等待缓存过期 │ │
│ │ # 使用 miniclaw_status 检查技能是否加载 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘16.1.2 技能元数据定义
┌─────────────────────────────────────────────────────────────────────┐
│ 技能元数据定义 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ SKILL.md Frontmatter 结构： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ --- │ │
│ │ # 必需字段 │ │
│ │ name: string # 技能名称（唯一标识） │ │
│ │ description: string # 技能描述 │ │
│ │ │ │
│ │ # 可选字段 │ │
│ │ prompts: # 提示词声明列表 │ │
│ │ - name: string # 提示词名称 │ │
│ │ description: string # 提示词描述 │ │
│ │ │ │
│ │ tools: # 工具声明列表 │ │
│ │ - name: string # 工具名称 │ │
│ │ description: string # 工具描述 │ │
│ │ inputSchema: object # 输入参数 Schema │ │
│ │ │ │
│ │ resources: # 资源声明列表 │ │
│ │ - uri: string # 资源 URI │ │
│ │ name: string # 资源名称 │ │
│ │ description: string # 资源描述 │ │
│ │ │ │
│ │ exec: string # 可执行脚本路径 │ │
│ │ context: string # 上下文钩子文件 │ │
│ │ --- │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 完整示例： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ --- │ │
│ │ name: git-helper │ │
│ │ description: "Git 操作辅助技能" │ │
│ │ prompts: │ │
│ │ - name: commit_guide │ │
│ │ description: "提交信息编写指南" │ │
│ │ - name: branch_strategy │ │
│ │ description: "分支策略建议" │ │
│ │ tools: │ │
│ │ - name: analyze_diff │ │
│ │ description: "分析代码差异" │ │
│ │ resources: │ │
│ │ - uri: git-helper://conventions │ │
│ │ name: "Git 规范" │ │
│ │ --- │ │
│ │ │ │
│ │ # Git Helper Skill │ │
│ │ │ │
│ │ 提供Git操作的辅助功能... │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘16.1.3 可执行技能开发
┌─────────────────────────────────────────────────────────────────────┐
│ 可执行技能开发 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 目录结构： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ~/.miniclaw/skills/backup/ │ │
│ │ ├── SKILL.md # 技能定义 │ │
│ │ ├── backup.sh # 可执行脚本 │ │
│ │ └── references/ # 参考文件 │ │
│ │ └── config.json │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ SKILL.md 配置： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ --- │ │
│ │ name: backup │ │
│ │ description: "项目备份技能" │ │
│ │ exec: ./backup.sh # 指定执行脚本 │ │
│ │ tools: │ │
│ │ - name: run_backup │ │
│ │ description: "执行备份操作" │ │
│ │ --- │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ backup.sh 脚本： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ #!/bin/bash │ │
│ │ │ │
│ │ # 获取参数 │ │
│ │ ACTION=$1 │ │
│ │ TARGET=$2 │ │
│ │ │ │
│ │ case $ACTION in │ │
│ │ "create") │ │
│ │ tar -czf "backup_$(date +%Y%m%d).tar.gz" "$TARGET" │ │
│ │ echo "Backup created successfully" │ │
│ │ ;; │ │
│ │ "list") │ │
│ │ ls -la backup_*.tar.gz │ │
│ │ ;; │ │
│ │ *) │ │
│ │ echo "Unknown action: $ACTION" │ │
│ │ ;; │ │
│ │ esac │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘16.2 工具扩展
16.2.1 核心工具添加
┌─────────────────────────────────────────────────────────────────────┐
│ 核心工具添加 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 在 src/index.ts 中添加新工具： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ // 1. 定义工具 Schema │ │
│ │ const MyToolSchema = z.object({ │ │
│ │ param1: z.string().describe('参数1说明'), │ │
│ │ param2: z.number().optional().describe('参数2说明'), │ │
│ │ }); │ │
│ │ │ │
│ │ // 2. 在 ListToolsRequestSchema 中注册 │ │
│ │ server.setRequestHandler(ListToolsRequestSchema, async () => {│
│ │ return { │ │
│ │ tools: [ │ │
│ │ // ... 现有工具 │ │
│ │ { │ │
│ │ name: "miniclaw_my_tool", │ │
│ │ description: "我的自定义工具", │ │
│ │ inputSchema: { │ │
│ │ type: "object", │ │
│ │ properties: { │ │
│ │ param1: { type: "string", description: "..." },│ │
│ │ param2: { type: "number", description: "..." },│ │
│ │ }, │ │
│ │ required: ["param1"], │ │
│ │ }, │ │
│ │ }, │ │
│ │ ], │ │
│ │ }; │ │
│ │ }); │ │
│ │ │ │
│ │ // 3. 在 CallToolRequestSchema 中实现 │ │
│ │ server.setRequestHandler(CallToolRequestSchema, async (req) => {│
│ │ const { name, arguments: args } = req.params; │ │
│ │ │ │
│ │ switch (name) { │ │
│ │ case "miniclaw_my_tool": { │ │
│ │ const { param1, param2 } = MyToolSchema.parse(args); │ │
│ │ const result = await kernel.myTool(param1, param2); │ │
│ │ return { │ │
│ │ content: [{ type: "text", text: result }], │ │
│ │ }; │ │
│ │ } │ │
│ │ // ... 其他工具 │ │
│ │ } │ │
│ │ }); │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘16.2.2 动态工具注册
┌─────────────────────────────────────────────────────────────────────┐
│ 动态工具注册 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 技能工具自动发现机制： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ // 在 ListToolsRequestSchema 中动态添加技能工具 │ │
│ │ server.setRequestHandler(ListToolsRequestSchema, async () => {│
│ │ const baseTools = [ │ │
│ │ // 核心工具列表... │ │
│ │ ]; │ │
│ │ │ │
│ │ // 动态发现技能工具 │ │
│ │ const skillTools = await kernel.discoverSkillTools(); │ │
│ │ │ │
│ │ // 合并工具列表 │ │
│ │ const allTools = [...baseTools, ...skillTools.map(t => ({│ │
│ │ name: `skill_${t.skillName}_${t.name}`, │ │
│ │ description: t.description, │ │
│ │ inputSchema: t.inputSchema, │ │
│ │ }))]; │ │
│ │ │ │
│ │ return { tools: allTools }; │ │
│ │ }); │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 技能工具命名规范： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ skill_{skillName}_{toolName} │ │
│ │ │ │
│ │ 示例： │ │
│ │ • skill_git-helper_analyze_diff │ │
│ │ • skill_backup_run_backup │ │
│ │ • skill_code-review_check_style │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘16.3 提示词扩展
16.3.1 核心提示词添加
┌─────────────────────────────────────────────────────────────────────┐
│ 核心提示词添加 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 在 src/index.ts 中添加新提示词： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ // 1. 在 ListPromptsRequestSchema 中注册 │ │
│ │ server.setRequestHandler(ListPromptsRequestSchema, async () => {│
│ │ return { │ │
│ │ prompts: [ │ │
│ │ // ... 现有提示词 │ │
│ │ { │ │
│ │ name: "miniclaw_my_prompt", │ │
│ │ description: "我的自定义提示词", │ │
│ │ }, │ │
│ │ ], │ │
│ │ }; │ │
│ │ }); │ │
│ │ │ │
│ │ // 2. 在 GetPromptRequestSchema 中实现 │ │
│ │ server.setRequestHandler(GetPromptRequestSchema, async (req) => {│
│ │ const { name } = req.params; │ │
│ │ │ │
│ │ switch (name) { │ │
│ │ case "miniclaw_my_prompt": │ │
│ │ return { │ │
│ │ messages: [{ │ │
│ │ role: "user", │ │
│ │ content: { │ │
│ │ type: "text", │ │
│ │ text: generateMyPrompt(), │ │
│ │ }, │ │
│ │ }] │ │
│ │ }; │ │
│ │ // ... 其他提示词 │ │
│ │ } │ │
│ │ }); │ │
│ │ │ │
│ │ // 3. 提示词生成函数 │ │
│ │ function generateMyPrompt(): string { │ │
│ │ return `# 我的提示词 │ │
│ │ │ │
│ │ 请按照以下步骤执行： │ │
│ │ 1. 第一步... │ │
│ │ 2. 第二步... │ │
│ │ `; │ │
│ │ } │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘16.3.2 动态提示词注册
┌─────────────────────────────────────────────────────────────────────┐
│ 动态提示词注册 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 技能提示词自动发现机制： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ // 在 ListPromptsRequestSchema 中动态添加技能提示词 │ │
│ │ server.setRequestHandler(ListPromptsRequestSchema, async () => {│
│ │ const basePrompts = [ │ │
│ │ // 核心提示词列表... │ │
│ │ ]; │ │
│ │ │ │
│ │ // 动态发现技能提示词 │ │
│ │ const skillPrompts = await kernel.discoverSkillPrompts();│ │
│ │ │ │
│ │ // 合并提示词列表 │ │
│ │ const allPrompts = [...basePrompts, ...skillPrompts.map(p => ({│
│ │ name: `skill_${p.skillName}_${p.name}`, │ │
│ │ description: p.description, │ │
│ │ }))]; │ │
│ │ │ │
│ │ return { prompts: allPrompts }; │ │
│ │ }); │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 技能提示词命名规范： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ skill_{skillName}_{promptName} │ │
│ │ │ │
│ │ 示例： │ │
│ │ • skill_git-helper_commit_guide │ │
│ │ • skill_git-helper_branch_strategy │ │
│ │ • skill_code-review_check_list │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘16.4 扩展架构图
┌─────────────────────────────────────────────────────────────────────┐
│ 扩展架构图 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ │
│ │ MCP Client │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ MiniClaw Core │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Tools │ │ Prompts │ │ Resources │ │ │
│ │ │ (核心工具) │ │ (核心提示词)│ │ (核心资源) │ │ │
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │
│ │ │ │ │ │ │
│ │ └────────────────┼────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────┐ │ │
│ │ │ Skill Scanner │ │ │
│ │ │ (技能发现机制) │ │ │
│ │ └──────────┬──────────┘ │ │
│ │ │ │ │
│ └─────────────────────────┼─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Skills Directory │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ git-helper │ │ backup │ │ code-review │ ... │ │
│ │ │ SKILL.md │ │ SKILL.md │ │ SKILL.md │ │ │
│ │ │ *.sh │ │ *.sh │ │ refs/ │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘本章小结
┌─────────────────────────────────────────────────────────────────────┐
│ 第十六章 核心要点 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 🔧 技能扩展 │
│ • 创建目录：~/.miniclaw/skills/{skill-name}/ │
│ • 定义 SKILL.md（Frontmatter + 内容） │
│ • 可执行脚本支持 │
│ │
│ 🛠️ 工具扩展 │
│ • 核心工具：修改 src/index.ts │
│ • 动态工具：技能自动发现 │
│ • 命名规范：skill_{skill}_{tool} │
│ │
│ 📝 提示词扩展 │
│ • 核心提示词：修改 src/index.ts │
│ • 动态提示词：技能自动发现 │
│ • 命名规范：skill_{skill}_{prompt} │
│ │
│ 🏗️ 扩展架构 │
│ • Skill Scanner 自动发现 │
│ • 统一注册机制 │
│ • 插件化设计 │
│ │
└─────────────────────────────────────────────────────────────────────┘下一章：与 OpenClaw 的关系 →