skill-isolator

# skill-isolator

为不同项目提供独立的技能配置和隔离管理，实现技能按需加载、项目间完全隔离。

快速开始

1️⃣ 创建项目配置

在项目根目录创建 `.openclaw-skills.json`：

```bash # 使用交互向导 node scripts/init-project-config.js

# 或手动创建（最小配置） echo '{"skills":["weather"],"excludeGlobal":true}' > .openclaw-skills.json ```

2️⃣ 同步技能

```bash # 自动检测并安装缺失技能 node scripts/sync-project-skills.js ```

3️⃣ 验证配置

```bash node scripts/validate-config.js ```

---

核心功能

| 功能 | 说明 | |------|------| | 🔒 项目隔离 | 每个项目独立技能配置，切换项目自动切换技能 | | 🌐 多源支持 | clawhub / local / git / url，优先级可配置 | | 📦 版本控制 | 支持锁定特定版本或 `latest` 自动更新 | | ⚡ 自动同步 | 进入项目时自动检测并安装缺失技能 | | 💾 智能缓存 | 减少重复下载，可配置 TTL | | 🎯 冲突解决 | 项目配置 > 全局配置，同名技能取高优先级源 |

---

配置文件详解

完整示例

```json { "name": "my-project", "skills": [ { "name": "feishu-doc", "version": "latest" }, { "name": "weather", "version": "1.2.0" }, "stock-analyzer" ], "excludeGlobal": true, "sources": [ { "name": "clawhub", "type": "registry", "priority": 1, "enabled": true }, { "name": "local", "type": "filesystem", "priority": 2, "paths": ["~/.openclaw/skills", "~/my-skills"] } ], "cache": { "enabled": true, "ttlHours": 24 }, "autoSync": { "onProjectEnter": true, "onSkillMissing": true } } ```

字段说明

| 字段 | 类型 | 必需 | 说明 | |------|------|------|------| | `name` | string | ❌ | 项目名称（用于显示） | | `skills` | array | ✅ | 技能列表，支持字符串或对象格式 | | `excludeGlobal` | boolean | ❌ | `true` 只用项目技能，`false` 项目 + 全局（默认 false） | | `sources` | array | ❌ | 技能来源列表，按优先级排序 | | `cache.enabled` | boolean | ❌ | 是否启用缓存（默认 true） | | `cache.ttlHours` | number | ❌ | 缓存过期时间（小时，默认 24） | | `autoSync.onProjectEnter` | boolean | ❌ | 进入项目时自动同步（默认 true） | | `autoSync.onSkillMissing` | boolean | ❌ | 发现缺失技能时自动安装（默认 true） |

技能格式

```json { "skills": [ "weather", // 简单格式 - 最新版本的技能 { "name": "feishu-doc" }, // 对象格式 - 最新版本 { "name": "stock-analyzer", "version": "1.2.0" } // 锁定版本 ] } ```

来源类型

| type | 说明 | 必需字段 | 示例 | |------|------|----------|------| | `registry` | 技能市场（clawhub） | - | `{"name":"clawhub","type":"registry"}` | | `filesystem` | 本地目录 | `paths` | `{"type":"filesystem","paths":["~/.openclaw/skills"]}` | | `git` | Git 仓库 | `repos` | `{"type":"git","repos":["user/repo"]}` | | `url` | HTTP 下载 | `baseUrl` | `{"type":"url","baseUrl":"https://..."}` |

---

命令接口

同步与状态

| 命令 | 说明 | |------|------| | `node scripts/sync-project-skills.js` | 同步项目技能 | | `node scripts/sync-project-skills.js --force` | 强制重新同步 | | `node scripts/sync-project-skills.js --verbose` | 显示详细信息 | | `node scripts/validate-config.js` | 验证配置格式 |

配置管理

| 命令 | 说明 | |------|------| | `node scripts/init-project-config.js` | 交互式创建配置 |

---

工作流程

项目加载流程

1. ```
2. 检测当前工作目录
3. ↓
4. 向上查找最近的 .openclaw-skills.json
5. ↓
6. 解析技能列表和来源配置
7. ↓
8. 检查每个技能是否已安装
9. ↓
10. 缺失技能 → 按源优先级查找并安装
11. ↓
12. 激活配置的技能
13. ↓
14. 缓存加载状态
15. ```

技能安装流程

1. ```
2. 遍历配置的技能列表
3. ↓
4. 检查技能是否已安装（多目录检测）
5. ↓
6. 未安装 → 按优先级遍历来源
7. ↓
8. 找到技能 → 下载/克隆
9. ↓
10. 验证技能格式（SKILL.md 必需）
11. ↓
12. 安装到本地技能目录
13. ↓
14. 更新缓存
15. ```

---

脚本工具

sync-project-skills.js

同步项目技能的主脚本。

```bash # 基本用法 node scripts/sync-project-skills.js

# 强制重新同步（忽略缓存） node scripts/sync-project-skills.js --force

# 显示详细信息 node scripts/sync-project-skills.js --verbose

# 组合使用 node scripts/sync-project-skills.js --force --verbose ```

• 参数：
• `--force`, `-f`: 强制重新同步，忽略缓存
• `--verbose`, `-v`: 显示详细信息

validate-config.js

验证配置文件格式和完整性。

```bash # 验证当前目录配置 node scripts/validate-config.js

# 验证指定文件 node scripts/validate-config.js path/to/config.json ```

• 验证内容：
• JSON 格式正确性
• 必需字段存在性
• 字段类型正确性
• 来源类型有效性
• 重复技能检测

init-project-config.js

交互式配置创建向导。

```bash node scripts/init-project-config.js ```

• 引导内容：
• 项目名称
• 技能列表
• 是否排除全局技能
• 技能来源配置
• 缓存设置
• 自动同步设置

---

缓存机制

缓存位置

``` ~/.openclaw/cache/skills.json ```

缓存内容

```json { "skills": { "weather": { "installed": true, "timestamp": 1710000000000 }, "feishu-doc": { "installed": true, "timestamp": 1710000000000 } }, "sources": { "clawhub": { "reachable": true, "lastCheck": 1710000000000 } }, "lastSync": 1710000000000 } ```

缓存策略

| 场景 | 行为 | |------|------| | 缓存有效 | 直接使用，跳过网络请求 | | 缓存过期 | 重新检查源，更新缓存 | | `--force` | 忽略缓存，强制重新检查 | | 缓存损坏 | 自动重建 |

---

错误处理

| 错误 | 原因 | 解决方案 | |------|------|----------| | `Config error` | JSON 格式错误 | 运行 `validate-config.js` 检查 | | `Skill not found` | 技能在配置源中不存在 | 检查技能名称，确认源配置 | | `Failed to install` | 安装失败（网络/权限） | 检查网络连接和目录权限 | | `Cache valid, skipping` | 缓存未过期 | 使用 `--force` 强制刷新 |

---

最佳实践

1️⃣ 配置最小化

只配置项目真正需要的技能：

```json { "skills": ["feishu-doc", "weather"], "excludeGlobal": true } ```

2️⃣ 版本锁定

生产项目锁定技能版本：

```json { "skills": [ { "name": "feishu-doc", "version": "2.1.0" }, { "name": "weather", "version": "1.0.3" } ] } ```

3️⃣ 本地开发

开发中的技能使用本地源：

```json { "sources": [ { "name": "local-dev", "type": "filesystem", "paths": ["~/dev/my-skills"], "priority": 1 } ] } ```

4️⃣ 团队共享

提交配置到版本控制：

```bash git add .openclaw-skills.json git commit -m "Add project skill configuration" ```

---

故障排查

技能未加载

```bash # 1. 检查配置文件是否存在 ls .openclaw-skills.json

# 2. 验证配置格式 node scripts/validate-config.js

# 3. 强制同步 node scripts/sync-project-skills.js --force --verbose ```

安装失败

```bash # 1. 检查网络连接 ping clawhub.com

# 2. 检查技能目录权限 ls -la ~/.openclaw/skills/

# 3. 查看详细日志 node scripts/sync-project-skills.js --verbose ```

配置错误

```bash # 验证配置并查看示例 node scripts/validate-config.js ```

---

文件位置

| 文件 | 位置 | |------|------| | 配置文件 | `项目根目录/.openclaw-skills.json` | | 缓存文件 | `~/.openclaw/cache/skills.json` | | 技能目录 | `~/.openclaw/skills/` | | 日志文件 | `~/.openclaw/logs/skills.log` |

---

与其他技能协作

clawhub

本技能依赖 `clawhub` 技能来安装 registry 源的技能。确保 clawhub 技能已安装。

skill-creator

创建新技能后，可以用本技能将新技能添加到项目配置中。

---

更新历史

| 版本 | 日期 | 变更 | |------|------|------| | 1.0.0 | 2026-03-10 | 初始版本，支持基础配置和多源安装 |

---

许可证

MIT License