joyskills-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joySkills Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,256 @@
+# joySkills - 新一代团队 Skill 治理平台
+
+> 在协议层兼容 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)
+
+## 💡 为什么需要 joySkills？
+
+在 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 支持**全局安装**和**项目级安装**两种方式：
+
+```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
+
+# 5. 审计安全性
+joySkills audit
+```
+
+完成！你的 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
+```
+
+### `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://github.com/your-org/joyskills-cli.git
+cd joyskills-cli
+
+# 安装依赖
+npm install
+
+# 本地开发链接
+npm link
+
+# 测试命令
+joySkills --version
+joySkills list
+```
+
+### 运行测试
+
+```bash
+# 运行 registry 测试
+node test/test-registry.js
+
+# 测试 CLI 命令
+joySkills list --search "test"
+joySkills list --category "utility"
+```
+
+## 📝 License
+
+MIT © joySkills Team

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "joyskills-cli",
+  "version": "0.1.1",
+  "description": "Team-level skill governance compatible with open skill / Claude Skills",
+  "main": "src/index.js",
+  "bin": {
+    "joySkills": "src/index.js"
+  },
+  "scripts": {
+    "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)"
+  },
+  "keywords": [
+    "claude",
+    "skills",
+    "agent",
+    "governance",
+    "team",
+    "registry",
+    "skill-management",
+    "openskills",
+    "claude-code",
+    "ai-skills"
+  ],
+  "author": "joySkills Team",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^11.1.0",
+    "yaml": "^2.3.4",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.5",
+    "@types/jest": "^29.5.11",
+    "typescript": "^5.3.3",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2"
+  },
+  "files": [
+    "src/",
+    "spec/",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module"
+}

package/spec/cli-spec.md

@@ -0,0 +1,167 @@
+## joySkills CLI 规范草案
+
+本规范定义 joySkills 命令行接口（CLI）的主要命令及其语义，重点说明：
+
+- 与 openskill 兼容的命令及行为。
+- joySkills 新增的团队治理相关命令。
+
+实现可以使用任意技术栈，但应遵守本规范中定义的输入/输出语义与副作用约束。
+
+### 1. 命令分类概览
+
+1. **基础管理命令（兼容 openskill）**：
+   - `joySkills list`
+   - `joySkills install`
+   - `joySkills remove`
+   - `joySkills update` / `joySkills upgrade`
+   - `joySkills read`
+
+2. **团队 / Registry 管理命令（joySkills 扩展）**：
+   - `joySkills team add`
+   - `joySkills team sync`
+   - `joySkills team use`
+
+3. **版本与锁定相关命令（joySkills 扩展）**：
+   - `joySkills status`
+   - `joySkills audit`
+
+4. **发布与审批命令（joySkills 扩展）**：
+   - `joySkills publish`
+   - `joySkills approve`
+   - `joySkills deprecate`
+
+### 2. 基础管理命令（兼容 openskill）
+
+#### 2.1 `joySkills list`
+
+- **用途**：列出当前 workspace 可用的 Skills。
+- **行为**：
+  - 聚合本地 `skills/` 目录和绑定 Registry 中的可用 Skill 信息。
+  - 默认仅展示每个 Skill 的名称、描述、当前推荐版本等。
+  - 典型选项：
+    - `--all-versions`：展示每个 Skill 的全部版本及状态。
+    - `--registry <name>`：仅查看指定 Registry 的 Skill 列表。
+
+#### 2.2 `joySkills install <skill>[@version]`
+
+- **用途**：安装某个 Skill 到当前项目的 `skills/` 目录。
+- **行为**：
+  - 未指定版本：
+    - 从当前绑定的 Registry 中选择该 Skill 的“推荐版本”（`recommended == true` 且 `state == approved`）。
+  - 指定版本：
+    - 尝试从 Registry 中查找该版本，默认要求 `state == approved`。
+  - 安装成功后：
+    - 在 `skills/<name>/` 下写入具体文件；
+    - 更新 `joySkills.lock` 中对应条目。
+
+#### 2.3 `joySkills remove <skill>`
+
+- **用途**：从当前项目移除一个 Skill。
+- **行为**：
+  - 删除 `skills/<name>/` 目录（或标记为已移除，具体细节由实现决定）。
+  - 更新 `joySkills.lock`，移除或标记该 Skill。
+
+#### 2.4 `joySkills update` / `joySkills upgrade`
+
+- **用途**：升级一个或多个 Skill 的版本。
+- **行为**：
+  - 不带参数时：
+    - 根据团队策略检查所有已安装 Skills 是否有可用升级版本。
+    - 可以提示用户按交互方式选择要升级的 Targets。
+  - 指定 Skill 时：
+    - 根据策略（如仅 minor/patch）选择目标版本并执行安装，更新 lock。
+
+#### 2.5 `joySkills read <skill>`
+
+- **用途**：查看某个 Skill 的元信息与文档（例如 SKILL.md 内容）。
+- **行为**：
+  - 从本地 `skills/` 目录或 Registry 中读取相关信息。
+  - 输出可读格式，便于在终端中快速了解 Skill 能力。
+
+### 3. 团队 / Registry 管理命令（joySkills 扩展）
+
+#### 3.1 `joySkills team add <name> <git-url>`
+
+- **用途**：在本地注册一个团队 Registry。
+- **行为**：
+  - 将 `<name> -> <git-url>` 记录到 joySkills 的本地配置中。
+  - 首次执行时尝试 clone 对应仓库，并解析其中的 `registry.yaml`。
+
+#### 3.2 `joySkills team sync [<name>]`
+
+- **用途**：同步指定或全部已注册 Registry。
+- **行为**：
+  - 执行 `git fetch/pull` 更新本地缓存。
+  - 重新解析 `registry.yaml`，更新本地索引。
+
+#### 3.3 `joySkills team use <name>`
+
+- **用途**：为当前 workspace 选择默认使用的团队 Registry。
+- **行为**：
+  - 将所选 Registry ID 写入当前 workspace 配置或 `joySkills.lock` 的 `registryBindings` 中。
+  - 后续 `list/install/upgrade` 等命令将默认使用该 Registry。
+
+### 4. 版本与锁定相关命令
+
+#### 4.1 `joySkills status`
+
+- **用途**：查看当前项目所有 Skills 的版本状态。
+- **行为**：
+  - 读取 `joySkills.lock` 与 Registry 索引，输出：
+    - Skill 名称。
+    - 当前版本号。
+    - 版本状态（approved/deprecated 等）。
+    - 是否存在可升级版本。
+
+#### 4.2 `joySkills audit`
+
+- **用途**：审计当前项目是否使用了已废弃或存在风险的 Skill 版本。
+- **行为**：
+  - 对比 `joySkills.lock` 中版本与 Registry 索引中的状态。
+  - 输出：
+    - 所有使用 `deprecated` / 标记安全风险版本的 Skill。
+    - 推荐的升级目标版本（如有）。
+
+### 5. 发布与审批命令
+
+#### 5.1 `joySkills publish <skill>@<version> --registry <name>`
+
+- **用途**：将某个 Skill 版本发布到指定 Registry。
+- **行为**（典型集成方式）：
+  - 通常由 CI 在合并代码后调用：
+    - 校验代码仓库中存在对应的 `skills/<name>/` 与 SKILL.md。
+    - 更新 Registry 仓库中的 `registry.yaml`，新增该版本条目（初始 `state` 可以是 `pending_review` 或 `approved`）。
+
+#### 5.2 `joySkills approve <skill>@<version> --registry <name>`
+
+- **用途**：将某个版本标记为 `approved`，允许团队使用。
+- **行为**：
+  - 校验调用者是否具备 `maintainer` 或以上权限。
+  - 更新 Registry 索引中对应版本的 `state` 与 `approvedBy/approvedAt`。
+
+#### 5.3 `joySkills deprecate <skill>@<version> --registry <name>`
+
+- **用途**：将某个版本标记为 `deprecated`。
+- **行为**：
+  - 更新 Registry 索引中 `state = deprecated`。
+  - 可选：增加推荐替代版本信息，供 `audit` 与升级逻辑使用。
+
+### 6. 与 openskill 的兼容策略
+
+- **命令级兼容**：
+  - joySkills 的基础管理命令（list/install/remove/update/read）应与 openskill 在语义上保持对齐，确保现有使用习惯不被破坏。
+
+- **行为级兼容**：
+  - 对于仅使用本地 `skills/` 目录的场景：
+    - joySkills 可以退化为一个简单的本地管理工具，不依赖 Registry / lockfile。
+  - 对于已有 openskill 的项目：
+    - 只要 joySkills 保证生成的 `skills/` 目录与 openskill 一致，编辑器侧（Claude Code 等）就不需要做任何改动。
+
+### 7. 未来扩展
+
+- 本规范聚焦 v1 所需的最小命令集合。
+- 后续如需扩展（例如：
+  - 更多团队级配置命令；
+  - 与企业 IAM/审计系统对接；
+  - 交互式 TUI / Web UI；
+ ），应在保持现有命令语义稳定的前提下新增子命令或选项。

package/spec/lockfile-spec.md

@@ -0,0 +1,108 @@
+## joySkills 锁文件（joySkills.lock）规范草案
+
+本规范定义 joySkills 在项目根目录使用的锁文件 `joySkills.lock`，用于记录当前项目实际使用的 Skills 版本与来源，以支持版本锁定、升级策略和审计能力。
+
+### 1. 概念与目标
+
+- **joySkills.lock 是什么？**
+  - 一个声明式文件，描述“当前项目在实际使用哪些 `skill@version`、这些版本来自哪个 Registry、何时安装的”。
+  - 类似于包管理器中的 lockfile（如 `package-lock.json` / `yarn.lock`），但对象是 AI Skills。
+
+- **设计目标**：
+  - 确保团队内不同成员 / 不同环境在同一项目中使用一致的 Skill 版本。
+  - 为审计工具提供稳定的数据源，用于构建 who-uses-what 视图。
+  - 在不破坏 open skill / openskill 行为的前提下引入版本锁定能力。
+
+### 2. 文件结构（示例）
+
+下面示例采用 YAML 表达，实际可根据技术栈选择 YAML/JSON 等格式，但字段语义应保持一致。
+
+```yaml
+lockVersion: 1
+projectId: "git@company:repo/path.git"   # 可选，用于跨项目聚合
+registryBindings:
+  - registryId: team://growth
+    alias: growth
+  - registryId: org://platform
+    alias: platform
+
+skills:
+  pdf:
+    version: 1.2.0
+    registry: team://growth
+    installedAt: 2025-01-03T09:00:00Z
+  web-testing:
+    version: 0.9.1
+    registry: org://platform
+    installedAt: 2025-01-05T14:30:00Z
+```
+
+### 3. 字段语义
+
+- **顶层字段**：
+  - `lockVersion`：
+    - 锁文件格式版本号，用于未来演进与迁移。
+  - `projectId`（可选）：
+    - 项目标识，用于跨仓库聚合审计数据，推荐使用仓库地址或唯一 ID。
+  - `registryBindings[]`（可选）：
+    - 当前项目绑定的 Registry 列表：
+      - `registryId`：Registry 的唯一标识，例如 `team://growth`。
+      - `alias`：本地别名，可用于 CLI 参数的简写。
+
+- **`skills` 映射**：
+  - key：
+    - Skill 名称，通常与 `skills/<name>/` 目录名一致。
+  - value：
+    - `version`：该项目实际使用的版本号。
+    - `registry`：该版本来源的 Registry ID。
+    - `installedAt`：该版本安装或升级到当前状态的时间戳。
+
+### 4. CLI 行为约定
+
+joySkills CLI 在读写 `joySkills.lock` 时应遵循以下约定：
+
+- `joySkills install <skill>`：
+  - 未指定版本时：
+    - 根据当前绑定 Registry 的推荐版本策略选择一个 `approved` 版本。
+    - 安装成功后，在 `skills` 映射中写入或更新对应条目。
+  - 指定版本时：
+    - 安装指定版本（通常要求版本状态为 `approved` 或显式允许 `deprecated`），并写入 lock。
+
+- `joySkills upgrade <skill>`：
+  - 根据团队策略（例如只允许 minor/patch 升级）与 Registry 索引选择目标版本。
+  - 完成安装后更新 `version` 和 `installedAt` 字段。
+
+- `joySkills status`：
+  - 读取 `joySkills.lock` 中的 `skills` 映射，结合 Registry 索引输出：
+    - 当前 Skill 版本。
+    - 版本状态（approved/deprecated 等）。
+    - 是否有可用升级。
+
+- `joySkills audit`：
+  - 读取 lockfile 与 Registry：
+    - 标记使用 `deprecated` 或被标记为安全风险的版本。
+    - 给出建议的升级目标（如果存在）。
+
+### 5. 生成与更新策略
+
+- 锁文件应当由 joySkills CLI 自动生成与更新，避免手动编辑导致不一致。
+- 当 `skills/` 目录发生变动（通过 joySkills 命令）时，必须同步更新 `joySkills.lock`：
+  - 新增 Skill：添加条目。
+  - 升级 Skill：更新版本号与时间戳。
+  - 移除 Skill：可以选择删除条目或标记为已移除（具体策略由实现决定）。
+
+### 6. 与 openskill / 现有行为的兼容
+
+- 在没有 `joySkills.lock` 的项目中：
+  - joySkills 可以在首次安装时自动生成锁文件；
+  - 若仅使用 openskill，则该文件不存在，不影响其正常工作。
+
+- 共存策略：
+  - 如果一个项目同时使用 openskill 和 joySkills：
+    - 由 joySkills 管理的安装/升级操作应保证与 openskill 期望的目录结构兼容；
+    - openskill 不需要理解 `joySkills.lock`，只要看到正确的 `skills/` 目录即可。
+
+### 7. 演进与迁移
+
+- 锁文件格式演进时，通过提升 `lockVersion` 并提供迁移工具完成升级。
+- 建议新增字段保持向后兼容，旧版本工具在遇到未知字段时应忽略之，而不是报错中止。