joyskills-cli 0.2.10 → 0.3.1

package/README.md

@@ -1,256 +1,40 @@
-# joySkills - 新一代团队 Skill 治理平台
+# joySkills CLI
 
-> 在协议层兼容 open skill / Claude Skills，在能力层扩展企业级治理能力
+> 团队级 Skill 治理，像 npm 一样简单
 
 [![npm version](https://badge.fury.io/js/joyskills-cli.svg)](https://www.npmjs.com/package/joyskills-cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**🔗 Links:** [npm Package](https://www.npmjs.com/package/joyskills-cli) | [Git Repository](https://coding.jd.com/rc-ai/joyskill)
+## 一句话介绍
 
-## 💡 为什么需要 joySkills？
+joySkills 帮你把 Skill 安装到正确目录、锁定版本、团队分发。100% 兼容 Claude Skills。
 
-在 AI 原生开发时代，**Skill**（技能）成为了比 function 更友好的能力抽象单元。然而当团队规模扩大，单纯的本地 skill 管理会遇到：
-
-- ❌ **版本混乱**：不同项目使用不同版本的 skill，难以统一升级
-- ❌ **安全风险**：无法及时发现和处理已废弃或有风险的 skill 版本
-- ❌ **缺乏治理**：谁在用什么 skill？如何审批新版本？
-- ❌ **协作困难**：团队成员各自维护 skill，无法共享和复用
-
-joySkills 提供了一套**完整的团队级 Skill 治理方案**，同时保持与现有生态的 100% 兼容。
-
-## ✨ 核心特性
-
-### 📦 统一 Skill 源（Registry）
-- 团队/组织级 Skill 仓库
-- 基于 Git 的版本管理
-- 支持私有部署和权限控制
-
-### 🔒 版本锁定（joySkills.lock）
-- 项目级版本锁定，确保环境一致
-- 自动记录安装历史
-- 支持 semver 版本策略
-
-### ✅ 发布审批流程
-- `draft` → `pending_review` → `approved` → `deprecated` → `archived`
-- 完整的状态机管理
-- CI/CD 友好
-
-### 🔐 权限与可见性
-- `public` / `restricted` / `internal` 三级可见性
-- 基于角色的访问控制（RBAC）
-- 与 Git 权限无缝集成
-
-### 📊 使用追踪与审计
-- 实时监控 skill 使用情况
-- 安全风险预警
-- 自动生成升级建议
-
-### 🤝 100% 兼容现有生态
-- 兼容 Claude Code / Cursor / Windsurf / Aider
-- 不改变 `skills/` 目录结构
-- 不改变 `SKILL.md` 文件格式
-
-## 🚀 快速开始
-
-### 安装
-
-joySkills 支持**全局安装**和**项目级安装**两种方式：
+## 30 秒上手
 
 ```bash
-# 全局安装
+# 安装
 npm install -g joyskills-cli
-joySkills --version
-
-# 或：项目级安装
-npm install joyskills-cli
-npx joySkills --version
-```
-
-### 5 分钟上手
-
-```bash
-# 1. 进入你的项目目录
-cd your-project
-
-# 2. 安装一个 skill
-joySkills install web-search
-# 或使用 npx（如果是项目级安装）
-npx joySkills install web-search
-
-# 3. 查看已安装的 skills
-joySkills list
 
-# 4. 检查状态
-joySkills status
+# 安装一个 Skill（默认到 .joycode/skills/）
+joySkills install pdf
 
-# 5. 审计安全性
-joySkills audit
+# 完成！打开 JoyCode/Claude Code 即可使用
 ```
 
-完成！你的 Claude Code / Cursor 等编辑器会自动识别 `skills/` 目录中的技能。
+## 核心能力
 
-## 📋 完整命令参考
-
-### `joySkills list`
-列出可用的 skills
-
-**选项：**
-- `-a, --all-versions` - 显示所有版本
-- `-c, --category <category>` - 按分类过滤
-- `-s, --search <query>` - 搜索 skill 名称或描述
-- `-i, --installed` - 只显示已安装的 skills
-- `-l, --local` - 只显示本地 skills
-- `-r, --registry <name>` - 显示指定 registry 的 skills
-
-### `joySkills install <skill>`
-安装一个 skill
-
-```bash
-# 安装最新版本
-joySkills install web-search
-
-# 安装指定版本
-joySkills install web-search@1.0.0
-
-# 从指定 registry 安装
-joySkills install web-search --registry my-team
-```
-
-### `joySkills remove <skill>`
-删除已安装的 skill
-
-```bash
-joySkills remove web-search
-```
-
-### `joySkills team <subcommand>`
-管理团队 registry
-
-```bash
-# 添加团队 registry
-joySkills team add my-team /path/to/registry
-
-# 列出所有 registries
-joySkills team list
-
-# 删除 registry
-joySkills team remove my-team
-```
+| 场景 | 命令 |
+|------|------|
+| 安装 Skill | `joySkills install <skill>` |
+| 查看已安装 | `joySkills list` |
+| 检查更新 | `joySkills check` |
+| 一键更新 | `joySkills update` |
+| 团队共享 | `joySkills team add <name> <git-url>` |
 
-### `joySkills status`
-显示当前项目的 skills 状态
+## 文档
 
-```bash
-joySkills status
-```
-
-### `joySkills audit`
-审计已安装 skills 的安全性和弃用状态
-
-```bash
-joySkills audit
-```
-
-## 📖 核心概念
-
-### Skill Registry（技能注册表）
-
-Registry 是团队统一管理的 Skill 仓库，通常是一个 Git 仓库 + `registry.yaml` 索引文件：
-
-```yaml
-registryVersion: 1
-registryId: team://your-team
-skills:
-  - id: web-search
-    name: "Web 搜索"
-    visibility: public
-    versions:
-      - version: 1.2.0
-        state: approved
-        recommended: true
-```
-
-### joySkills.lock（锁文件）
-
-项目级锁文件，记录实际使用的 skill 版本：
-
-```yaml
-lockVersion: 1
-projectId: "your-project"
-skills:
-  web-search:
-    version: 1.2.0
-    registry: team://your-team
-    installedAt: 2026-02-02T10:00:00Z
-```
-
-### 版本状态机
-
-```
-draft → pending_review → approved → deprecated → archived
-  ↓         ↓              ↓           ↓           ↓
-开发中    待审核         可用        不推荐      归档
-```
-
-## 🏗️ 项目结构
-
-```
-joySkills/
-├── src/
-│   ├── index.js              # CLI 入口点
-│   ├── types.js              # 类型定义
-│   ├── registry.js           # Registry 管理
-│   ├── lockfile.js           # 锁文件操作
-│   ├── local.js              # 本地 skill 管理
-│   └── commands/             # CLI 命令
-│       ├── list.js           # 列出 skills
-│       ├── install.js        # 安装 skill
-│       ├── remove.js         # 删除 skill
-│       ├── team.js           # Registry 管理
-│       ├── status.js         # 状态检查
-│       └── audit.js          # 安全审计
-├── spec/                     # 规范文档
-│   ├── cli-spec.md           # CLI 规范
-│   ├── registry-spec.md      # Registry 规范
-│   └── lockfile-spec.md      # 锁文件规范
-├── test/                     # 测试文件
-├── .joyskill/                # 示例 registry
-├── package.json
-├── INSTALL.md
-└── README.md
-```
-
-## 🤝 贡献指南
-
-### 开发环境搭建
-
-```bash
-# 克隆仓库
-git clone https://coding.jd.com/rc-ai/joyskill.git
-cd joyskill
-
-# 安装依赖
-npm install
-
-# 本地开发链接
-npm link
-
-# 测试命令
-joySkills --version
-joySkills list
-```
-
-### 运行测试
-
-```bash
-# 运行 registry 测试
-node test/test-registry.js
-
-# 测试 CLI 命令
-joySkills list --search "test"
-joySkills list --category "utility"
-```
+- [📖 完整文档](./docs/yuanshi.md) - 原理、使用场景、最佳实践
+- [📋 详细说明](./docs/详细说明.md) - 所有命令和选项
 
-## 📝 License
+## License
 
-MIT © joySkills Team
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "joyskills-cli",
-  "version": "0.2.10",
-  "description": "Team-level skill governance compatible with open skill / Claude Skills",
+  "version": "0.3.1",
+  "description": "JoySkills CLI v2.0 - Multi-agent skill management with JoyCode native support",
   "main": "src/index.js",
   "bin": {
     "joySkills": "src/index.js"
@@ -9,9 +9,16 @@
   "scripts": {
     "build": "echo 'No build needed for JavaScript version'",
     "start": "node src/index.js",
-    "test": "jest",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
     "dev": "node src/index.js"
   },
+  "jest": {
+    "testEnvironment": "node",
+    "transform": {},
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    }
+  },
   "keywords": [
     "claude",
     "skills",

package/src/agents.js

@@ -0,0 +1,198 @@
+/**
+ * Agent 配置系统 - 支持多编辑器
+ * 定义各编辑器的项目级和用户级 Skill 目录
+ */
+
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+
+/**
+ * Agent 定义
+ * id: 唯一标识
+ * name: 显示名称
+ * projectPath: 项目级目录（相对路径）
+ * globalPath: 用户级目录（绝对路径，使用 ~ 表示 home）
+ * detectFiles: 用于自动检测的文件/目录
+ */
+export const AGENTS = [
+  {
+    id: 'joycode',
+    name: 'JoyCode',
+    projectPath: '.joycode/skills',
+    globalPath: '~/.joycode/skills',
+    detectFiles: ['.joycode'],
+    priority: 100, // 最高优先级，默认使用
+  },
+  {
+    id: 'claude-code',
+    name: 'Claude Code',
+    projectPath: '.claude/skills',
+    globalPath: '~/.claude/skills',
+    detectFiles: ['.claude', '.claude-plugin'],
+    priority: 90,
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    projectPath: '.agents/skills',
+    globalPath: '~/.cursor/skills',
+    detectFiles: ['.cursor', '.agents'],
+    priority: 80,
+  },
+  {
+    id: 'codex',
+    name: 'Codex',
+    projectPath: '.agents/skills',
+    globalPath: '~/.codex/skills',
+    detectFiles: ['.codex'],
+    priority: 70,
+  },
+  {
+    id: 'qoder',
+    name: 'Qoder',
+    projectPath: '.qoder/skills',
+    globalPath: '~/.qoder/skills',
+    detectFiles: ['.qoder'],
+    priority: 60,
+  },
+  {
+    id: 'opencode',
+    name: 'OpenCode',
+    projectPath: '.agents/skills',
+    globalPath: '~/.config/opencode/skills',
+    detectFiles: ['.opencode'],
+    priority: 50,
+  },
+  {
+    id: 'universal',
+    name: 'Universal',
+    projectPath: '.agents/skills',
+    globalPath: '~/.config/agents/skills',
+    detectFiles: ['.agents'],
+    priority: 10,
+  },
+];
+
+/**
+ * 获取 Agent 配置
+ */
+export function getAgent(agentId) {
+  return AGENTS.find(a => a.id === agentId) || AGENTS[0]; // 默认返回 joycode
+}
+
+/**
+ * 获取所有 Agent
+ */
+export function getAllAgents() {
+  return AGENTS;
+}
+
+/**
+ * 解析路径中的 ~ 为 home 目录
+ */
+export function resolvePath(pathWithTilde) {
+  if (pathWithTilde.startsWith('~/')) {
+    return path.join(os.homedir(), pathWithTilde.slice(2));
+  }
+  return pathWithTilde;
+}
+
+/**
+ * 获取 Agent 的项目级目录（绝对路径）
+ */
+export function getAgentProjectPath(agentId, projectRoot) {
+  const agent = getAgent(agentId);
+  return path.join(projectRoot, agent.projectPath);
+}
+
+/**
+ * 获取 Agent 的用户级目录（绝对路径）
+ */
+export function getAgentGlobalPath(agentId) {
+  const agent = getAgent(agentId);
+  return resolvePath(agent.globalPath);
+}
+
+/**
+ * 检测项目中存在的 Agent
+ * 返回按优先级排序的 Agent ID 列表
+ */
+export function detectAgents(projectRoot) {
+  const detected = [];
+  
+  for (const agent of AGENTS) {
+    // 检查项目级目录是否存在
+    const projectPath = getAgentProjectPath(agent.id, projectRoot);
+    if (fs.existsSync(projectPath)) {
+      detected.push(agent.id);
+      continue;
+    }
+    
+    // 检查检测文件是否存在
+    for (const detectFile of agent.detectFiles) {
+      const detectPath = path.join(projectRoot, detectFile);
+      if (fs.existsSync(detectPath)) {
+        detected.push(agent.id);
+        break;
+      }
+    }
+  }
+  
+  // 按优先级排序
+  detected.sort((a, b) => {
+    const agentA = getAgent(a);
+    const agentB = getAgent(b);
+    return agentB.priority - agentA.priority;
+  });
+  
+  return detected;
+}
+
+/**
+ * 获取默认 Agent
+ * 始终返回 joycode 作为默认，不管检测到什么其他 Agent
+ * 这是 JoyCode 的品牌策略
+ */
+export function getDefaultAgent(projectRoot) {
+  // 始终返回 joycode 作为默认
+  return getAgent('joycode');
+}
+
+/**
+ * 获取所有 Skill 目录（项目级 + 用户级）
+ * 用于 SkillLoader 加载
+ */
+export function getAllSkillPaths(projectRoot, agentId = null) {
+  const paths = [];
+  const agents = agentId ? [getAgent(agentId)] : AGENTS;
+  
+  for (const agent of agents) {
+    // 项目级目录
+    const projectPath = getAgentProjectPath(agent.id, projectRoot);
+    if (fs.existsSync(projectPath)) {
+      paths.push({
+        path: projectPath,
+        scope: 'project',
+        agent: agent.id,
+        priority: agent.priority,
+      });
+    }
+    
+    // 用户级目录
+    const globalPath = getAgentGlobalPath(agent.id);
+    if (fs.existsSync(globalPath)) {
+      paths.push({
+        path: globalPath,
+        scope: 'global',
+        agent: agent.id,
+        priority: agent.priority - 1, // 用户级优先级略低
+      });
+    }
+  }
+  
+  // 按优先级排序
+  paths.sort((a, b) => b.priority - a.priority);
+  
+  return paths;
+}

package/src/commands/check.js

@@ -0,0 +1,69 @@
+/**
+ * Check Command - 检查技能更新
+ */
+
+import { Command } from 'commander';
+import { checkAllSkills, getUpdatableSkills } from '../version-checker.js';
+import chalk from 'chalk';
+
+export function checkCommand(program) {
+  program
+    .command('check')
+    .description('Check for available skill updates')
+    .option('-u, --updatable', 'Show only skills with updates')
+    .action(async (options) => {
+      try {
+        const projectRoot = process.cwd();
+        
+        console.log(chalk.blue('Checking for skill updates...'));
+        console.log(chalk.gray('==============================\n'));
+
+        const results = options.updatable 
+          ? await getUpdatableSkills(projectRoot)
+          : await checkAllSkills(projectRoot);
+
+        if (results.length === 0) {
+          if (options.updatable) {
+            console.log(chalk.green('✅ All skills are up to date!'));
+          } else {
+            console.log(chalk.yellow('No skills found.'));
+          }
+          return;
+        }
+
+        let updatableCount = 0;
+
+        for (const result of results) {
+          if (result.hasUpdate) {
+            updatableCount++;
+            console.log(chalk.yellow(`📦 ${result.name}`));
+            console.log(`   Current: v${result.currentVersion}`);
+            console.log(chalk.green(`   ${result.commitsBehind} commit(s) behind`));
+            if (result.latestCommit) {
+              console.log(chalk.gray(`   Latest: ${result.latestCommit.message.substring(0, 50)}...`));
+            }
+            console.log();
+          } else if (!options.updatable) {
+            console.log(chalk.green(`✅ ${result.name} v${result.currentVersion}`));
+            if (result.error) {
+              console.log(chalk.gray(`   ${result.error}`));
+            } else {
+              console.log(chalk.gray('   Up to date'));
+            }
+            console.log();
+          }
+        }
+
+        if (updatableCount > 0) {
+          console.log(chalk.blue(`\nFound ${updatableCount} skill(s) with updates.`));
+          console.log(chalk.gray('Run `joySkills update` to update all skills.'));
+        } else if (!options.updatable) {
+          console.log(chalk.green('\n✅ All skills are up to date!'));
+        }
+
+      } catch (error) {
+        console.error(chalk.red('❌ Failed to check updates:'), error.message);
+        process.exit(1);
+      }
+    });
+}