@dayinxisheng/skillctl 1.1.1 → 1.2.0

package/README.md

@@ -1,389 +1,389 @@
-# @dayinxisheng/skillctl
-
-> Claude Skills 管理工具 - 轻松管理你的 Claude Skills
-
-管理 Claude Skills 的激活状态和项目归档，通过软链接实现 skills 的灵活切换。
-
-## 📦 安装
-
-```bash
-npm install -g @dayinxisheng/skillctl
-```
-
-## 更新
-
-```bash
-npm update -g @dayinxisheng/skillctl
-```
-
-安装完成后，可以在任何目录使用 `skillctl` 命令。
-
-## 🚀 快速开始
-
-### 第一步：设置仓库路径
-
-告诉 skillctl 你的 skills 仓库在哪里（存储所有 skill 文件的目录）：
-
-```bash
-skillctl config set-repo ~/my-skills
-```
-
-### 第二步：查看可用的 skills
-
-```bash
-skillctl ls-all
-```
-
-输出示例：
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  项目中所有可用的 Skills
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Name                    Description
-─────────────────────────────────────────────────────────────
-brainstorming           Turn ideas into validated designs...
-frontend-design         Generate frontend code from UI...
-pdf-tools               PDF manipulation tools...
-
-ℹ 共找到 3 个 skills
-  位置: ~/my-skills
-```
-
-### 第三步：激活 skill
-
-```bash
-skillctl activate brainstorming
-```
-
-输出：
-```
-✓ 已激活: brainstorming (user)
-```
-
-## 📚 核心概念
-
-### User vs Project 两级作用域
-
-skillctl 支持两个作用域：
-
-| 作用域 | 路径 | 说明 |
-|--------|------|------|
-| **User** | `~/.claude/skills/` | 全局可用，所有项目共享 |
-| **Project** | `./.claude/skills/` | 仅当前项目可用 |
-
-**示例场景：**
-- 团队共享的技能 → 用 Project 级别
-- 个人常用技能 → 用 User 级别
-
-## 🎯 常用命令
-
-### 1. 激活 Skill
-
-```bash
-# 激活到 user 级别（默认）- 全局可用
-skillctl activate brainstorming
-
-# 激活到 project 级别 - 仅当前项目
-skillctl activate -p brainstorming
-
-# 批量激活所有 skills
-skillctl activate --all
-skillctl activate -u --all  # 明确指定 user 级别
-skillctl activate -p --all  # 明确指定 project 级别
-```
-
-### 2. 停用 Skill
-
-```bash
-# 停用 user 级别的 skill
-skillctl deactivate brainstorming
-
-# 停用 project 级别的 skill
-skillctl deactivate -p brainstorming
-
-# 批量停用所有
-skillctl deactivate --all
-```
-
-### 3. 查看状态
-
-```bash
-# 查看所有 skills 的激活状态（表格形式）
-skillctl status
-```
-
-输出示例：
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Skills 激活状态
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Skill                 User       Project
-──────────────────────────── ────────── ───────────
-brainstorming         ✓          ✗
-frontend-design       ✗          ✓
-pdf-tools             ✓          ✓
-
-ℹ 共 3 个 skills
-  ✓ = 已激活  ✗ = 未激活
-```
-
-```bash
-# 只看已激活的 skills
-skillctl list
-```
-
-输出示例：
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  当前激活的 Skills
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-全局 (~/.claude/skills):
-  brainstorming → ~/my-skills/brainstorming
-  pdf-tools → ~/my-skills/pdf-tools
-ℹ 共 2 个
-
-本地 (./.claude/skills):
-  frontend-design → ~/my-skills/frontend-design
-ℹ 共 1 个
-```
-
-### 4. 导入 Skill
-
-将外部开发的 skill 导入到你的项目仓库：
-
-```bash
-# 假设你有一个 skill 在 ~/.claude/skills/my-new-skill
-# 将其导入到项目仓库
-skillctl import my-new-skill
-```
-
-这会：
-1. 将 skill 移动到你的项目仓库
-2. 在原位置创建软链接
-
-### 5. 拉取 Skill
-
-从 Git 仓库（如 GitHub）拉取 skill 到本地：
-
-```bash
-# 拉取单个 skill
-skillctl pull https://github.com/owner/repo path/to/skill
-
-# 拉取多个 skills
-skillctl pull https://github.com/owner/repo \
-  path/to/skill1 \
-  path/to/skill2
-
-# 强制覆盖已存在的 skill（自动备份）
-skillctl pull <repo-url> <path> --force
-```
-
-**使用仓库别名：**
-
-```bash
-# 添加别名
-skillctl config add-repo anthropic https://github.com/anthropics/anthropic-quickstarts
-
-# 使用别名拉取
-skillctl pull anthropic typescript/search
-
-# 查看所有别名
-skillctl config show
-```
-
-**配置镜像加速：**
-
-```bash
-# 设置镜像（用于加速访问 GitHub）
-skillctl config set-mirror https://ghfast.top
-
-# 之后所有 pull 命令都会自动使用镜像
-skillctl pull https://github.com/owner/repo path/to/skill
-
-# 取消镜像设置
-skillctl config unset-mirror
-```
-
-**特性：**
-- 支持从 GitHub 仓库提取指定目录作为 skill
-- 严格验证 SKILL.md 文件及 name 字段
-- 下载进度显示
-- 跨平台支持（Linux/macOS 使用 tar.gz，Windows 使用 zip）
-- 支持仓库别名，简化常用仓库的拉取
-- 支持镜像加速配置
-
-### 6. 定位 Skill
-
-查找 skill 的实际存储位置：
-
-```bash
-skillctl locate brainstorming
-```
-
-输出示例：
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Skill 定位: brainstorming
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  全局: ~/.claude/skills/brainstorming → ~/my-skills/brainstorming (软链接)
-```
-
-## ⚙️ 配置管理
-
-```bash
-# 查看所有配置
-skillctl config
-# 或
-skillctl config show
-```
-
-输出示例：
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  配置信息
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-配置文件: ~/.config/skillctl/config.json
-
-仓库路径: ~/my-skills
-镜像加速: https://ghfast.top
-
-仓库别名:
-  anthropic    → https://github.com/anthropics/anthropic-quickstarts
-  my-skills    → https://github.com/dayinxisheng/skills
-```
-
-```bash
-# 设置仓库路径
-skillctl config set-repo /new/path/to/skills
-
-# 添加仓库别名
-skillctl config add-repo <别名名称> <仓库URL>
-
-# 删除仓库别名
-skillctl config remove-repo <别名名称>
-
-# 设置镜像加速
-skillctl config set-mirror https://ghfast.top
-
-# 取消镜像设置
-skillctl config unset-mirror
-```
-
-## 💡 实用场景
-
-### 场景 1：新项目设置
-
-```bash
-# 1. 进入项目目录
-cd ~/my-project
-
-# 2. 激活项目需要的 skills
-skillctl activate -p frontend-design
-skillctl activate -p brainstorming
-
-# 3. 验证
-skillctl list
-```
-
-### 场景 2：切换技能集
-
-```bash
-# 停用当前所有 skills
-skillctl deactivate --all
-
-# 激活新的技能集
-skillctl activate pdf-tools
-skillctl activate docx-tools
-```
-
-### 场景 3：分享你的 skill
-
-```bash
-# 1. 导入你的 skill 到项目仓库
-skillctl import my-awesome-skill
-
-# 2. 提交到 git
-cd ~/my-skills
-git add skills/my-awesome-skill
-git commit -m "Add my-awesome-skill"
-git push
-```
-
-## 🛠️ 开发
-
-```bash
-# 克隆项目
-git clone <repo-url>
-cd skillctl
-
-# 安装依赖
-npm install
-
-# 开发模式（监听文件变化）
-npm run dev
-
-# 构建
-npm run build
-
-# 本地测试
-npm link
-
-# 运行测试
-npm test
-
-# 代码检查
-npm run lint
-npm run lint:fix
-```
-
-## 📁 项目结构
-
-```
-src/
-├── index.ts           # CLI 入口
-├── commands/          # 命令处理器
-│   ├── activate.ts    # 激活命令
-│   ├── deactivate.ts  # 停用命令
-│   ├── import.ts      # 导入命令
-│   ├── pull.ts        # 拉取命令
-│   ├── locate.ts      # 定位命令
-│   ├── status.ts      # 状态命令
-│   ├── list.ts        # 列表命令
-│   ├── all-list.ts    # 全部列表命令
-│   ├── set-repo.ts    # 设置仓库命令
-│   └── config.ts      # 配置命令
-├── lib/              # 核心业务逻辑
-│   ├── config-manager.ts  # 配置管理
-│   ├── link-handler.ts    # 软链接处理
-│   ├── pull-handler.ts    # 拉取处理逻辑
-│   └── skill-manager.ts   # Skill 管理
-├── utils/            # 工具函数
-│   ├── output.ts      # 彩色输出
-│   ├── errors.ts      # 错误类型
-│   ├── platform.ts    # 平台检测
-│   ├── downloader.ts  # 下载工具
-│   ├── archive-extractor.ts  # 解压工具
-│   ├── skill-validator.ts    # Skill 验证
-│   ├── github-parser.ts      # GitHub URL 解析
-│   └── url-validator.ts      # URL 验证
-└── types/            # TypeScript 类型定义
-    └── index.ts
-```
-
-## 📄 许可证
-
-MIT License © 2026 hrjlab
-
-## 📝 变更日志
-
-查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新历史。
-
-## 🔗 相关链接
-
-- [npm 包](https://www.npmjs.com/package/@dayinxisheng/skillctl)
-- [问题反馈](<your-repo-issues>)
+# @dayinxisheng/skillctl
+
+> Claude Skills 管理工具 - 轻松管理你的 Claude Skills
+
+管理 Claude Skills 的激活状态和项目归档，通过软链接实现 skills 的灵活切换。
+
+## 📦 安装
+
+```bash
+npm install -g @dayinxisheng/skillctl
+```
+
+## 更新
+
+```bash
+npm update -g @dayinxisheng/skillctl
+```
+
+安装完成后，可以在任何目录使用 `skillctl` 命令。
+
+## 🚀 快速开始
+
+### 第一步：设置仓库路径
+
+告诉 skillctl 你的 skills 仓库在哪里（存储所有 skill 文件的目录）：
+
+```bash
+skillctl config set-repo ~/my-skills
+```
+
+### 第二步：查看可用的 skills
+
+```bash
+skillctl ls-all
+```
+
+输出示例：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  项目中所有可用的 Skills
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Name                    Description
+─────────────────────────────────────────────────────────────
+brainstorming           Turn ideas into validated designs...
+frontend-design         Generate frontend code from UI...
+pdf-tools               PDF manipulation tools...
+
+ℹ 共找到 3 个 skills
+  位置: ~/my-skills
+```
+
+### 第三步：激活 skill
+
+```bash
+skillctl activate brainstorming
+```
+
+输出：
+```
+✓ 已激活: brainstorming (user)
+```
+
+## 📚 核心概念
+
+### User vs Project 两级作用域
+
+skillctl 支持两个作用域：
+
+| 作用域 | 路径 | 说明 |
+|--------|------|------|
+| **User** | `~/.claude/skills/` | 全局可用，所有项目共享 |
+| **Project** | `./.claude/skills/` | 仅当前项目可用 |
+
+**示例场景：**
+- 团队共享的技能 → 用 Project 级别
+- 个人常用技能 → 用 User 级别
+
+## 🎯 常用命令
+
+### 1. 激活 Skill
+
+```bash
+# 激活到 user 级别（默认）- 全局可用
+skillctl activate brainstorming
+
+# 激活到 project 级别 - 仅当前项目
+skillctl activate -p brainstorming
+
+# 批量激活所有 skills
+skillctl activate --all
+skillctl activate -u --all  # 明确指定 user 级别
+skillctl activate -p --all  # 明确指定 project 级别
+```
+
+### 2. 停用 Skill
+
+```bash
+# 停用 user 级别的 skill
+skillctl deactivate brainstorming
+
+# 停用 project 级别的 skill
+skillctl deactivate -p brainstorming
+
+# 批量停用所有
+skillctl deactivate --all
+```
+
+### 3. 查看状态
+
+```bash
+# 查看所有 skills 的激活状态（表格形式）
+skillctl status
+```
+
+输出示例：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Skills 激活状态
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Skill                 User       Project
+──────────────────────────── ────────── ───────────
+brainstorming         ✓          ✗
+frontend-design       ✗          ✓
+pdf-tools             ✓          ✓
+
+ℹ 共 3 个 skills
+  ✓ = 已激活  ✗ = 未激活
+```
+
+```bash
+# 只看已激活的 skills
+skillctl list
+```
+
+输出示例：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  当前激活的 Skills
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+全局 (~/.claude/skills):
+  brainstorming → ~/my-skills/brainstorming
+  pdf-tools → ~/my-skills/pdf-tools
+ℹ 共 2 个
+
+本地 (./.claude/skills):
+  frontend-design → ~/my-skills/frontend-design
+ℹ 共 1 个
+```
+
+### 4. 导入 Skill
+
+将外部开发的 skill 导入到你的项目仓库：
+
+```bash
+# 假设你有一个 skill 在 ~/.claude/skills/my-new-skill
+# 将其导入到项目仓库
+skillctl import my-new-skill
+```
+
+这会：
+1. 将 skill 移动到你的项目仓库
+2. 在原位置创建软链接
+
+### 5. 拉取 Skill
+
+从 Git 仓库（如 GitHub）拉取 skill 到本地：
+
+```bash
+# 拉取单个 skill
+skillctl pull https://github.com/owner/repo path/to/skill
+
+# 拉取多个 skills
+skillctl pull https://github.com/owner/repo \
+  path/to/skill1 \
+  path/to/skill2
+
+# 强制覆盖已存在的 skill（自动备份）
+skillctl pull <repo-url> <path> --force
+```
+
+**使用仓库别名：**
+
+```bash
+# 添加别名
+skillctl config add-repo anthropic https://github.com/anthropics/anthropic-quickstarts
+
+# 使用别名拉取
+skillctl pull anthropic typescript/search
+
+# 查看所有别名
+skillctl config show
+```
+
+**配置镜像加速：**
+
+```bash
+# 设置镜像（用于加速访问 GitHub）
+skillctl config set-mirror https://ghfast.top
+
+# 之后所有 pull 命令都会自动使用镜像
+skillctl pull https://github.com/owner/repo path/to/skill
+
+# 取消镜像设置
+skillctl config unset-mirror
+```
+
+**特性：**
+- 支持从 GitHub 仓库提取指定目录作为 skill
+- 严格验证 SKILL.md 文件及 name 字段
+- 下载进度显示
+- 跨平台支持（Linux/macOS 使用 tar.gz，Windows 使用 zip）
+- 支持仓库别名，简化常用仓库的拉取
+- 支持镜像加速配置
+
+### 6. 定位 Skill
+
+查找 skill 的实际存储位置：
+
+```bash
+skillctl locate brainstorming
+```
+
+输出示例：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Skill 定位: brainstorming
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  全局: ~/.claude/skills/brainstorming → ~/my-skills/brainstorming (软链接)
+```
+
+## ⚙️ 配置管理
+
+```bash
+# 查看所有配置
+skillctl config
+# 或
+skillctl config show
+```
+
+输出示例：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  配置信息
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+配置文件: ~/.config/skillctl/config.json
+
+仓库路径: ~/my-skills
+镜像加速: https://ghfast.top
+
+仓库别名:
+  anthropic    → https://github.com/anthropics/anthropic-quickstarts
+  my-skills    → https://github.com/dayinxisheng/skills
+```
+
+```bash
+# 设置仓库路径
+skillctl config set-repo /new/path/to/skills
+
+# 添加仓库别名
+skillctl config add-repo <别名名称> <仓库URL>
+
+# 删除仓库别名
+skillctl config remove-repo <别名名称>
+
+# 设置镜像加速
+skillctl config set-mirror https://ghfast.top
+
+# 取消镜像设置
+skillctl config unset-mirror
+```
+
+## 💡 实用场景
+
+### 场景 1：新项目设置
+
+```bash
+# 1. 进入项目目录
+cd ~/my-project
+
+# 2. 激活项目需要的 skills
+skillctl activate -p frontend-design
+skillctl activate -p brainstorming
+
+# 3. 验证
+skillctl list
+```
+
+### 场景 2：切换技能集
+
+```bash
+# 停用当前所有 skills
+skillctl deactivate --all
+
+# 激活新的技能集
+skillctl activate pdf-tools
+skillctl activate docx-tools
+```
+
+### 场景 3：分享你的 skill
+
+```bash
+# 1. 导入你的 skill 到项目仓库
+skillctl import my-awesome-skill
+
+# 2. 提交到 git
+cd ~/my-skills
+git add skills/my-awesome-skill
+git commit -m "Add my-awesome-skill"
+git push
+```
+
+## 🛠️ 开发
+
+```bash
+# 克隆项目
+git clone <repo-url>
+cd skillctl
+
+# 安装依赖
+npm install
+
+# 开发模式（监听文件变化）
+npm run dev
+
+# 构建
+npm run build
+
+# 本地测试
+npm link
+
+# 运行测试
+npm test
+
+# 代码检查
+npm run lint
+npm run lint:fix
+```
+
+## 📁 项目结构
+
+```
+src/
+├── index.ts           # CLI 入口
+├── commands/          # 命令处理器
+│   ├── activate.ts    # 激活命令
+│   ├── deactivate.ts  # 停用命令
+│   ├── import.ts      # 导入命令
+│   ├── pull.ts        # 拉取命令
+│   ├── locate.ts      # 定位命令
+│   ├── status.ts      # 状态命令
+│   ├── list.ts        # 列表命令
+│   ├── all-list.ts    # 全部列表命令
+│   ├── set-repo.ts    # 设置仓库命令
+│   └── config.ts      # 配置命令
+├── lib/              # 核心业务逻辑
+│   ├── config-manager.ts  # 配置管理
+│   ├── link-handler.ts    # 软链接处理
+│   ├── pull-handler.ts    # 拉取处理逻辑
+│   └── skill-manager.ts   # Skill 管理
+├── utils/            # 工具函数
+│   ├── output.ts      # 彩色输出
+│   ├── errors.ts      # 错误类型
+│   ├── platform.ts    # 平台检测
+│   ├── downloader.ts  # 下载工具
+│   ├── archive-extractor.ts  # 解压工具
+│   ├── skill-validator.ts    # Skill 验证
+│   ├── github-parser.ts      # GitHub URL 解析
+│   └── url-validator.ts      # URL 验证
+└── types/            # TypeScript 类型定义
+    └── index.ts
+```
+
+## 📄 许可证
+
+MIT License © 2026 hrjlab
+
+## 📝 变更日志
+
+查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新历史。
+
+## 🔗 相关链接
+
+- [npm 包](https://www.npmjs.com/package/@dayinxisheng/skillctl)
+- [问题反馈](<your-repo-issues>)