joyskills-cli 0.2.6 → 0.2.7

package/README.md

@@ -1,54 +1,29 @@
-# joySkills - OpenSkills 的增强替代品
+# joySkills - 新一代团队 Skill 治理平台
 
-> 100% 兼容 OpenSkills + 团队协作增强（版本锁定、团队 Registry、安全审计）
+> 在协议层兼容 open skill / Claude Skills，在能力层扩展企业级治理能力
 
 [![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://github.com/your-org/joyskills-cli)
+**🔗 Links:** [npm Package](https://www.npmjs.com/package/joyskills-cli) | [Git Repository](https://coding.jd.com/rc-ai/joyskill)
 
-## 💡 为什么选择 joySkills？
+## 💡 为什么需要 joySkills？
 
-**joySkills 是 OpenSkills 的超集**，提供：
+在 AI 原生开发时代，**Skill**（技能）成为了比 function 更友好的能力抽象单元。然而当团队规模扩大，单纯的本地 skill 管理会遇到：
 
-### 🎯 OpenSkills 的全部能力
-- ✅ 安装公开 skill（调用 `openskills install`）
-- ✅ 生成 AGENTS.md（`joySkills sync` = `openskills sync` + 增强）
-- ✅ 读取 skill 内容（`joySkills read` = `openskills read`）
-- ✅ 100% 兼容 Claude Code / Cursor / Windsurf
+- ❌ **版本混乱**：不同项目使用不同版本的 skill，难以统一升级
+- ❌ **安全风险**：无法及时发现和处理已废弃或有风险的 skill 版本
+- ❌ **缺乏治理**：谁在用什么 skill？如何审批新版本？
+- ❌ **协作困难**：团队成员各自维护 skill，无法共享和复用
 
-### 🚀 团队协作增强（OpenSkills 缺失的）
-- ✅ **版本锁定**：joySkills.lock 确保团队版本统一
-- ✅ **团队 Registry**：从 Git 仓库安装内部 skill
-- ✅ **安全审计**：自动检测废弃和有风险的 skill
-- ✅ **状态管理**：draft → review → approved → deprecated
+joySkills 提供了一套**完整的团队级 Skill 治理方案**，同时保持与现有生态的 100% 兼容。
 
 ## ✨ 核心特性
 
-### 📦 公开 + 内部 Skill 统一管理
-```bash
-# 安装公开 skill
-joySkills install anthropics/skills/pdf
-
-# 安装内部 skill（需配置 Registry）
-joySkills install team://your-team/rc-onboarding
-
-# 统一同步
-joySkills sync  # 生成 AGENTS.md + joySkills.lock
-```
-
-**核心价值**：
-- ✅ 公开 + 内部 skill 统一管理，一个命令搞定
-- ✅ 版本锁定（joySkills.lock），团队环境一致
-- ✅ 100% 兼容 OpenSkills，随时可回退
-
-**路径设计**：
-| 安装方式 | joySkills | OpenSkills |
-|---------|-----------|------------|
-| 项目级 | `.agent/skills` | `.agent/skills` (--universal) |
-| 全局 | `~/.agent/skills` | `~/.claude/skills` (--global) |
-
-**优先级**：项目级 > 全局，不同项目可用不同版本
+### 📦 统一 Skill 源（Registry）
+- 团队/组织级 Skill 仓库
+- 基于 Git 的版本管理
+- 支持私有部署和权限控制
 
 ### 🔒 版本锁定（joySkills.lock）
 - 项目级版本锁定，确保环境一致
@@ -70,220 +45,131 @@ joySkills sync  # 生成 AGENTS.md + joySkills.lock
 - 安全风险预警
 - 自动生成升级建议
 
-### 📋 OpenSkills 兼容命令
-```bash
-# sync 命令（扫描所有路径 + 生成 AGENTS.md）
-joySkills sync
-# 扫描路径：.agent/skills, ~/.agent/skills, .claude/skills, ~/.claude/skills
-# ✅ 生成 AGENTS.md（与 openskills sync 格式相同）
-# ✅ 额外生成 joySkills.lock（版本锁定）
-
-# read 命令（按优先级读取 skill）
-joySkills read rc-onboarding
-# ✅ 路径查找优先级与 openskills read 一致
-# ✅ 输出格式完全相同
-```
+### 🤝 100% 兼容现有生态
+- 兼容 Claude Code / Cursor / Windsurf / Aider
+- 不改变 `skills/` 目录结构
+- 不改变 `SKILL.md` 文件格式
 
 ## 🚀 快速开始
 
-### 场景 1：个人开发者（替代 OpenSkills）
+### 安装
+
+joySkills 支持**全局安装**和**项目级安装**两种方式：
 
 ```bash
-# 1. 安装
+# 全局安装
 npm install -g joyskills-cli
+joySkills --version
 
-# 2. 安装公开 skill
-joySkills install anthropics/skills/pdf
-joySkills install @skillforge/code-review
-
-# 3. 生成 AGENTS.md
-joySkills sync
-
-# 4. 查看已安装
-joySkills list
+# 或：项目级安装
+npm install joyskills-cli
+npx joySkills --version
 ```
 
-### 场景 2：团队协作（内部 skill）
-
-**痛点**：
-- 😓 内部 skill 群里发 zip，手动下载 + 解压
-- 😓 新人 onboarding，问“哪些 skill 必须装”
-- 😓 skill 更新后，通知所有人重新下载
+### 5 分钟上手
 
-**解决方案**：
 ```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://git.yourcompany.com/team-skills.git",
-    "type": "git"
-  }]
-}
-EOF
-
-# 3. 安装 skill（像 npm 一样）
-joySkills install team://your-team/rc-onboarding
-joySkills install team://your-team/rc-commit-lint
-joySkills sync
-
-# 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
-# 已经用 openskills 安装了很多 skills
-openskills install skill-a
-openskills install skill-b
-
-# 切换到 joySkills（无需重装）
-joySkills sync
-# ✅ 自动识别已有 skills
-# ✅ 生成 joySkills.lock
-# ✅ 后续用 joySkills install 安装新 skill
-```
-
-## 📋 完整命令参考
+# 1. 进入你的项目目录
+cd your-project
 
-### OpenSkills 兼容命令
+# 2. 安装一个 skill
+joySkills install web-search
+# 或使用 npx（如果是项目级安装）
+npx joySkills install web-search
 
-#### `joySkills sync`
-生成 AGENTS.md（100% 兼容 `openskills sync` + 增强）
-
-```bash
-joySkills sync
-# ✅ 扫描 .agent/skills, ~/.agent/skills, .claude/skills, ~/.claude/skills
-# ✅ 生成 AGENTS.md（OpenSkills 兼容格式）
-# ✅ 生成 joySkills.lock（版本锁定）
-# ✅ 版本一致性检查
-```
+# 3. 查看已安装的 skills
+joySkills list
 
-#### `joySkills read <skill-name>`
-读取 skill 内容（100% 兼容 `openskills read`）
+# 4. 检查状态
+joySkills status
 
-```bash
-joySkills read rc-onboarding
-# ✅ 路径查找优先级与 openskills 一致
-# ✅ 输出格式完全相同
+# 5. 审计安全性
+joySkills audit
 ```
 
-### joySkills 增强命令
+完成！你的 Claude Code / Cursor 等编辑器会自动识别 `skills/` 目录中的技能。
 
-#### `joySkills install <skill>`
-安装 skill（公开 + 团队 + 本地）
+## 📋 完整命令参考
 
-```bash
-# 公开 skill（自动调用 openskills）
-joySkills install anthropics/skills/pdf
+### `joySkills list`
+列出可用的 skills
 
-# 团队 skill
-joySkills install team://your-team/rc-onboarding
+**选项：**
+- `-a, --all-versions` - 显示所有版本
+- `-c, --category <category>` - 按分类过滤
+- `-s, --search <query>` - 搜索 skill 名称或描述
+- `-i, --installed` - 只显示已安装的 skills
+- `-l, --local` - 只显示本地 skills
+- `-r, --registry <name>` - 显示指定 registry 的 skills
 
-# 本地 skill
-joySkills install ./my-local-skill
+### `joySkills install <skill>`
+安装一个 skill
 
-# 指定版本
-joySkills install team://your-team/rc-onboarding@1.2.0
-```
+```bash
+# 安装最新版本
+joySkills install web-search
 
-#### `joySkills list`
-列出可用的 skills
+# 安装指定版本
+joySkills install web-search@1.0.0
 
-```bash
-joySkills list
-joySkills list --installed  # 只显示已安装
-joySkills list --search "web"  # 搜索
+# 从指定 registry 安装
+joySkills install web-search --registry my-team
 ```
 
-#### `joySkills remove <skill>`
+### `joySkills remove <skill>`
 删除已安装的 skill
 
 ```bash
-joySkills remove rc-onboarding
+joySkills remove web-search
 ```
 
-#### `joySkills team`
+### `joySkills team <subcommand>`
 管理团队 registry
 
 ```bash
+# 添加团队 registry
 joySkills team add my-team /path/to/registry
+
+# 列出所有 registries
 joySkills team list
+
+# 删除 registry
 joySkills team remove my-team
 ```
 
-#### `joySkills status`
+### `joySkills status`
 显示当前项目的 skills 状态
 
 ```bash
 joySkills status
 ```
 
-#### `joySkills audit`
+### `joySkills audit`
 审计已安装 skills 的安全性和弃用状态
 
-## 📖 核心概念
+```bash
+joySkills audit
+```
 
-### Skill Registry（团队 skill 仓库）
+## 📖 核心概念
 
-Registry 是团队统一管理 skill 的 Git 仓库，像 npm 私有源一样。
+### Skill Registry（技能注册表）
 
-**目录结构**：
-```
-team-skills/                    # Git 仓库
-├── registry.yaml              # 版本配置（可选）
-├── rc-onboarding/
-│   ├── SKILL.md            # 必须
-│   ├── scripts/             # 可选：脚本
-│   └── templates/           # 可选：模板
-└── rc-commit-lint/
-    └── SKILL.md
-```
+Registry 是团队统一管理的 Skill 仓库，通常是一个 Git 仓库 + `registry.yaml` 索引文件：
 
-**registry.yaml 示例**（可选，用于版本管理）：
 ```yaml
 registryVersion: 1
 registryId: team://your-team
 skills:
-  - id: rc-onboarding
-    name: "搜推团队 Onboarding"
-    visibility: internal      # internal / public / restricted
+  - id: web-search
+    name: "Web 搜索"
+    visibility: public
     versions:
       - version: 1.2.0
-        state: approved       # draft / pending_review / approved / deprecated
+        state: approved
         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 版本：
@@ -340,8 +226,8 @@ joySkills/
 
 ```bash
 # 克隆仓库
-git clone https://github.com/your-org/joyskills-cli.git
-cd joyskills-cli
+git clone https://coding.jd.com/rc-ai/joyskill.git
+cd joyskill
 
 # 安装依赖
 npm install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "joyskills-cli",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Team-level skill governance compatible with open skill / Claude Skills",
   "main": "src/index.js",
   "bin": {
@@ -10,9 +10,7 @@
     "build": "echo 'No build needed for JavaScript version'",
     "start": "node src/index.js",
     "test": "jest",
-    "dev": "node src/index.js",
-    "prepublishOnly": "npm run check-secrets",
-    "check-secrets": "! grep -rE 'jd\\.com|@jd\\.com|coding\\.jd' src/ README.md package.json spec/ || (echo '❌ 发现敏感信息，禁止发布！' && exit 1)"
+    "dev": "node src/index.js"
   },
   "keywords": [
     "claude",
@@ -28,24 +26,35 @@
   ],
   "author": "joySkills Team",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joyskills/joySkills.git"
+  },
+  "homepage": "https://github.com/joyskills/joySkills#readme",
+  "bugs": {
+    "url": "https://github.com/joyskills/joySkills/issues"
+  },
   "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "chalk": "^5.6.2",
     "commander": "^11.1.0",
+    "simple-git": "^3.32.3",
     "yaml": "^2.3.4",
     "zod": "^3.22.4"
   },
   "devDependencies": {
-    "@types/node": "^20.10.5",
     "@types/jest": "^29.5.11",
-    "typescript": "^5.3.3",
+    "@types/node": "^20.10.5",
     "jest": "^29.7.0",
     "ts-jest": "^29.1.1",
-    "ts-node": "^10.9.2"
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
   },
+  "type": "module",
   "files": [
-    "src/",
-    "spec/",
-    "README.md",
-    "LICENSE"
+    "src/"
   ],
-  "type": "module"
+  "engines": {
+    "node": ">=18.0.0"
+  }
 }