joyskills-cli 0.1.3 → 0.2.0

package/README.md

@@ -19,29 +19,29 @@
 
 ### 🚀 团队协作增强（OpenSkills 缺失的）
 - ✅ **版本锁定**：joySkills.lock 确保团队版本统一
-- ✅ **团队 Registry**：基于 Git 的内部 skill 仓库
+- ✅ **团队 Registry**：从 Git 仓库安装内部 skill
 - ✅ **安全审计**：自动检测废弃和有风险的 skill
 - ✅ **状态管理**：draft → review → approved → deprecated
-- ✅ **使用追踪**：了解哪些 skill 被使用、被谁使用
 
 ## ✨ 核心特性
 
 ### 📦 公开 + 内部 Skill 统一管理
 ```bash
-# 项目级安装（默认）
-joySkills install team://your-team/rc-onboarding
-# → 安装到 .agent/skills/rc-onboarding
+# 安装公开 skill
+joySkills install anthropics/skills/pdf
 
-# 全局安装
-joySkills install -g anthropics/skills/pdf
-# → 安装到 ~/.agent/skills/pdf
+# 安装内部 skill（需配置 Registry）
+joySkills install team://your-team/rc-onboarding
 
-# 统一同步（扫描所有路径）
-joySkills sync
-# 扫描: .agent/skills, ~/.agent/skills, .claude/skills, ~/.claude/skills
-# 生成: AGENTS.md + joySkills.lock
+# 统一同步
+joySkills sync  # 生成 AGENTS.md + joySkills.lock
 ```
 
+**核心价值**：
+- ✅ 公开 + 内部 skill 统一管理，一个命令搞定
+- ✅ 版本锁定（joySkills.lock），团队环境一致
+- ✅ 100% 兼容 OpenSkills，随时可回退
+
 **路径设计**：
 | 安装方式 | joySkills | OpenSkills |
 |---------|-----------|------------|
@@ -105,30 +105,54 @@ joySkills list
 
 ### 场景 2：团队协作（内部 skill）
 
-```bash
-# 1. 安装
-npm install -g joyskills-cli
+**痛点**：
+- 😓 内部 skill 群里发 zip，手动下载 + 解压
+- 😓 新人 onboarding，问“哪些 skill 必须装”
+- 😓 skill 更新后，通知所有人重新下载
 
-# 2. 配置团队 Registry
-echo '{
+**解决方案**：
+```bash
+# 1. Tech Lead 搭建团队 Registry（Git 仓库）
+mkdir team-skills && cd team-skills
+mkdir rc-onboarding rc-commit-lint
+# 将 SKILL.md 放入对应目录
+git init && git add . && git commit -m "init"
+git remote add origin https://git.yourcompany.com/team-skills.git
+git push
+
+# 2. 团队成员配置（一次）
+cat > .joyskillrc << 'EOF'
+{
   "registries": [{
     "id": "team://your-team",
-    "url": "https://your-git/team-skills.git",
+    "url": "https://git.yourcompany.com/team-skills.git",
     "type": "git"
   }]
-}' > .joyskillrc
+}
+EOF
 
-# 3. 安装团队 skill
+# 3. 安装 skill（像 npm 一样）
 joySkills install team://your-team/rc-onboarding
-
-# 4. 生成 AGENTS.md + joySkills.lock
+joySkills install team://your-team/rc-commit-lint
 joySkills sync
 
-# 5. 团队成员同步
-git pull  # 拉取 joySkills.lock
-joySkills install  # 自动安装锁定版本
+# 4. 团队同步（自动化）
+git add AGENTS.md joySkills.lock .joyskillrc
+git commit -m "setup team skills"
+git push
+
+# 5. 新成员加入（1 分钟）
+git clone <project-repo>
+joySkills install  # 自动安装所有锁定版本
 ```
 
+**效果对比**：
+| 场景 | 之前 | 现在 |
+|------|------|------|
+| 新人 onboarding | 群里找 8 个 zip，手动装（30分钟） | `joySkills install`（1分钟） |
+| skill 更新 | 群发通知 + 手动更新（15分钟） | `git pull && joySkills install`（1分钟） |
+| 版本不一致 | 频繁出现，难排查 | joySkills.lock 锁定，不会出现 |
+
 ### 场景 3：从 OpenSkills 迁移
 
 ```bash
@@ -152,7 +176,7 @@ joySkills sync
 
 ```bash
 joySkills sync
-# ✅ 扫描 skills/ 目录
+# ✅ 扫描 .agent/skills, ~/.agent/skills, .claude/skills, ~/.claude/skills
 # ✅ 生成 AGENTS.md（OpenSkills 兼容格式）
 # ✅ 生成 joySkills.lock（版本锁定）
 # ✅ 版本一致性检查
@@ -223,23 +247,43 @@ joySkills status
 
 ## 📖 核心概念
 
-### Skill Registry（技能注册表）
+### Skill Registry（团队 skill 仓库）
 
-Registry 是团队统一管理的 Skill 仓库，通常是一个 Git 仓库 + `registry.yaml` 索引文件：
+Registry 是团队统一管理 skill 的 Git 仓库，像 npm 私有源一样。
 
+**目录结构**：
+```
+team-skills/                    # Git 仓库
+├── registry.yaml              # 版本配置（可选）
+├── rc-onboarding/
+│   ├── SKILL.md            # 必须
+│   ├── scripts/             # 可选：脚本
+│   └── templates/           # 可选：模板
+└── rc-commit-lint/
+    └── SKILL.md
+```
+
+**registry.yaml 示例**（可选，用于版本管理）：
 ```yaml
 registryVersion: 1
 registryId: team://your-team
 skills:
-  - id: web-search
-    name: "Web 搜索"
-    visibility: public
+  - id: rc-onboarding
+    name: "搜推团队 Onboarding"
+    visibility: internal      # internal / public / restricted
     versions:
       - version: 1.2.0
-        state: approved
+        state: approved       # draft / pending_review / approved / deprecated
         recommended: true
+      - version: 1.1.0
+        state: deprecated
 ```
 
+**使用场景**：
+- ✅ 内部业务 skill（如 rc-onboarding、rc-commit-lint）
+- ✅ 公司级通用 skill（如 code-review、test-helper）
+- ✅ 项目级定制 skill（如 project-specific-tools）
+
 ### joySkills.lock（锁文件）
 
 项目级锁文件，记录实际使用的 skill 版本：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "joyskills-cli",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Team-level skill governance compatible with open skill / Claude Skills",
   "main": "src/index.js",
   "bin": {

package/src/commands/install.js

@@ -74,6 +74,13 @@ async function installPublicSkill(skillName, options, localManager, lockfileMana
   console.log(`💡 Using openskills install...\n`);
 
   try {
+    // 检查 openskills 是否可用
+    try {
+      execSync('npx openskills --version', { stdio: 'pipe' });
+    } catch (error) {
+      throw new Error('openskills not found. Please install: npm install -g openskills');
+    }
+
     // 调用 openskills install
     const cmd = `npx openskills install ${skillName}`;
     execSync(cmd, { stdio: 'inherit' });
@@ -101,88 +108,99 @@ async function installPublicSkill(skillName, options, localManager, lockfileMana
 async function installTeamSkill(skillName, options, projectRoot, localManager, lockfileManager) {
   console.log(`🏢 Installing team skill: ${skillName}`);
 
-  // Check for registry
-  let registryManager = null;
-  const registryPath = path.join(projectRoot, '.joyskill/registry');
-
-  if (fs.existsSync(registryPath)) {
-    try {
-      registryManager = new RegistryManager(registryPath);
-      await registryManager.load();
-    } catch (error) {
-      console.error('Warning: Could not load registry:', error.message);
-    }
+  // 解析 team:// URL
+  const teamUrl = skillName.replace(/^team:\/\//, '');
+  const parts = teamUrl.split('/');
+  if (parts.length !== 2) {
+    throw new Error('Invalid team skill format. Expected: team://registry-name/skill-name');
   }
+  const [registryName, skillId] = parts;
 
-  // Determine version to install
-  let targetVersion = options.version || '1.0.0';
-  let versionSource = 'default';
-
-  if (registryManager && registryManager.hasSkill(skillName)) {
-    if (!options.version) {
-      // Get recommended version from registry
-      const recommended = registryManager.getRecommendedVersion(skillName);
-      if (recommended) {
-        targetVersion = recommended.version;
-        versionSource = 'registry';
-      }
-    }
-
-    // Validate version
-    const validation = registryManager.validateVersion(skillName, targetVersion);
-    if (!validation.valid && !options.force) {
-      console.error(`❌ Version validation failed: ${validation.error}`);
-      return;
-    }
+  // 读取配置文件
+  const configPath = path.join(projectRoot, '.joyskillrc');
+  if (!fs.existsSync(configPath)) {
+    throw new Error('.joyskillrc not found. Please configure team registry first.');
+  }
 
-    if (validation.warning && !options.force) {
-      console.log(`⚠️  Warning: ${validation.warning}`);
-      console.log('   Use --force to install anyway.');
-      return;
-    }
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch (error) {
+    throw new Error(`Failed to parse .joyskillrc: ${error.message}`);
+  }
 
-    console.log(`Installing ${skillName} v${targetVersion} from registry`);
-  } else {
-    console.log(`Installing ${skillName} v${targetVersion} (local/custom)`);
+  // 查找 registry 配置
+  const registry = config.registries?.find(r => r.id === `team://${registryName}`);
+  if (!registry) {
+    throw new Error(`Registry "team://${registryName}" not found in .joyskillrc`);
   }
 
-  // Create sample SKILL.md content
-  const skillMdContent = `---
-name: ${skillName}
-description: Auto-generated skill for ${skillName}
-version: ${targetVersion}
----
+  console.log(`📦 Fetching from ${registry.url}...`);
 
-# ${skillName}
+  // 临时目录
+  const tmpDir = path.join(projectRoot, '.joyskill', 'tmp', `${Date.now()}`);
+  fs.mkdirSync(tmpDir, { recursive: true });
 
-This skill was automatically generated by joySkills.
+  try {
+    // Git clone
+    console.log('🔄 Cloning registry...');
+    execSync(`git clone --depth 1 ${registry.url} ${tmpDir}`, { 
+      stdio: 'pipe',
+      encoding: 'utf-8'
+    });
 
-## Examples
-- Example usage 1
-- Example usage 2
+    // 检查 skill 是否存在
+    const skillPath = path.join(tmpDir, skillId);
+    if (!fs.existsSync(skillPath)) {
+      throw new Error(`Skill "${skillId}" not found in registry`);
+    }
 
-## Guidelines
-- Guideline 1
-- Guideline 2
-`;
+    // 检查 SKILL.md
+    const skillMdPath = path.join(skillPath, 'SKILL.md');
+    if (!fs.existsSync(skillMdPath)) {
+      throw new Error(`SKILL.md not found for "${skillId}"`);
+    }
 
-  // Install the skill
-  localManager.installSkill(skillName, skillMdContent);
+    // 读取 SKILL.md 内容
+    const skillMdContent = fs.readFileSync(skillMdPath, 'utf-8');
+
+    // 安装 skill
+    localManager.installSkill(skillId, skillMdContent);
+
+    // 复制其他文件（如果有）
+    const skillFiles = fs.readdirSync(skillPath);
+    const targetDir = path.join(localManager.getSkillsDir(), skillId);
+    
+    for (const file of skillFiles) {
+      if (file === 'SKILL.md') continue;
+      const srcFile = path.join(skillPath, file);
+      const destFile = path.join(targetDir, file);
+      
+      if (fs.statSync(srcFile).isDirectory()) {
+        fs.cpSync(srcFile, destFile, { recursive: true });
+      } else {
+        fs.copyFileSync(srcFile, destFile);
+      }
+    }
 
-  // Update lockfile
-  lockfileManager.updateSkill(skillName, {
-    version: targetVersion,
-    source: 'team',
-    registry: options.registry || 'local',
-    installedAt: new Date().toISOString()
-  });
+    // 更新 lockfile
+    lockfileManager.updateSkill(skillId, {
+      version: options.version || 'latest',
+      source: 'team',
+      registry: `team://${registryName}`,
+      installedAt: new Date().toISOString()
+    });
 
-  await lockfileManager.save();
+    await lockfileManager.save();
 
-  console.log(`✅ Successfully installed ${skillName} v${targetVersion}`);
+    console.log(`✅ Successfully installed ${skillId}`);
+    console.log(`💡 Run 'joySkills sync' to update AGENTS.md`);
 
-  if (versionSource === 'registry') {
-    console.log('   Version selected from registry recommendations.');
+  } finally {
+    // 清理临时目录
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
   }
 }
 

package/src/commands/sync.js

@@ -2,6 +2,7 @@
 
 import fs from 'fs';
 import path from 'path';
+import * as YAML from 'yaml';
 import { fileURLToPath } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -122,20 +123,15 @@ function parseSkillMetadata(content) {
   const match = content.match(/^---\n([\s\S]*?)\n---/);
   if (!match) return {};
 
-  const yaml = match[1];
-  const metadata = {};
-
-  // 简单的 YAML 解析（关键字段）
-  const lines = yaml.split('\n');
-  for (const line of lines) {
-    const [key, ...valueParts] = line.split(':');
-    if (!key || !valueParts.length) continue;
-
-    const value = valueParts.join(':').trim().replace(/^["']|["']$/g, '');
-    metadata[key.trim()] = value;
+  const yamlContent = match[1];
+  
+  try {
+    // 使用 yaml 包解析（支持完整 YAML 语法）
+    return YAML.parse(yamlContent) || {};
+  } catch (error) {
+    console.warn(`⚠️  YAML 解析失败: ${error.message}`);
+    return {};
   }
-
-  return metadata;
 }
 
 /**