reskill 0.17.1 → 1.0.0

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# reskill
+<img src="https://raw.githubusercontent.com/kanyun-ai-infra/reskill/main/logov2.png" alt="reskill" height="48" />
 
 **基于 Git 的 AI Agent Skills 包管理器**
 
@@ -18,235 +18,60 @@
 ## 快速开始
 
 ```bash
-# 1. 初始化项目
 npx reskill@latest init
-
-# 2. 安装 skill
 npx reskill@latest install github:anthropics/skills/frontend-design@latest
-
-# 3. 列出已安装的 skills
 npx reskill@latest list
 ```
 
-## 什么是 reskill？
-
-reskill 是一个**基于 Git 的包管理器**，用于管理 AI agent skills，类似 npm 或 Go modules。它提供声明式配置、版本锁定和无缝同步，帮助你在项目和团队间管理 skills。
-
-**支持：** Cursor、Claude Code、Codex、OpenCode、Windsurf、GitHub Copilot 等。
-
-## 为什么选择 reskill？
-
-reskill 提供**精细化的 skill 管理和同步方案**：
-
-### 本地体验优化
-
-- **声明式配置** — `skills.json` 清晰表达项目依赖
-- **全局缓存** — 避免重复下载，加速安装
+## 特性
 
-### 工程化项目管理
-
-- **版本锁定** — `skills.lock` 确保团队一致性
-- **灵活版本** — 支持精确版本、semver 范围、分支和 commit
-- **Git 即 Registry** — 无需额外服务，任何 Git 仓库都可作为 skill 源
-
-### 跨项目同步
-
-- **版本控制** — 将 `skills.json` 和 `skills.lock` 提交到仓库
-- **CI 集成** — 在 CI 中运行 `reskill install` 验证依赖
-- **多 Registry** — 支持 GitHub、GitLab 和私有仓库
-
-### 灵活的版本策略
-
-```json
-{
-  "skills": {
-    "frontend-design": "github:anthropics/skills/frontend-design@latest",
-    "code-review": "github:team/code-review@v2.1.0",
-    "testing": "github:team/testing@^1.0.0"
-  }
-}
-```
-
-运行 `reskill update` 时：
-
-- `@latest` 的 skill 会自动更新到最新 tag
-- `@v2.1.0` 保持不变
-- `@^1.0.0` 会更新到 1.x.x 的最新版本
+- **一键安装** — 从任意 Git 仓库一键安装 skill
+- **声明式配置** — `skills.json` + `skills.lock` 确保团队一致性
+- **灵活版本** — 精确版本、semver 范围、分支、commit
+- **多 Registry** — GitHub、GitLab、自建、私有仓库
+- **多 Agent** — Cursor、Claude Code、Codex、Windsurf、GitHub Copilot 等
 
 ## 安装
 
 ```bash
-# 全局安装（推荐常态化使用）
-npm install -g reskill
-
-# 或使用 npx（推荐加 @latest 确保最新版本）
-npx reskill@latest <command>
-
-# 单次使用也可以直接 npx reskill
-npx reskill <command>
+npm install -g reskill        # 全局安装
+npx reskill@latest <command>  # 或直接使用 npx
 ```
 
-> **注意：** 使用 `npx` 时，建议使用 `npx reskill@latest` 以确保使用最新版本。不加 `@latest` 时，npx 可能会使用缓存的旧版本。
-
-## 使用方式
-
-### 源格式
-
-```bash
-# GitHub 简写
-npx reskill@latest install github:user/skill@v1.0.0
-
-# 完整 Git URL
-npx reskill@latest install https://github.com/user/skill.git
-
-# GitHub 网页 URL（支持分支和子路径）
-npx reskill@latest install https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
-
-# GitLab
-npx reskill@latest install gitlab:group/skill@latest
-
-# 私有 Registry
-npx reskill@latest install gitlab.company.com:team/skill@v1.0.0
-
-# 默认 Registry（来自 skills.json）
-npx reskill@latest install user/skill@v1.0.0
-```
-
-### 版本规范
-
-| 格式     | 示例              | 说明                          |
-| -------- | ----------------- | ----------------------------- |
-| 精确版本 | `@v1.0.0`         | 锁定到指定 tag                |
-| 最新版本 | `@latest`         | 获取最新 tag                  |
-| 范围版本 | `@^2.0.0`         | semver 兼容（>=2.0.0 <3.0.0） |
-| 分支     | `@branch:develop` | 指定分支                      |
-| Commit   | `@commit:abc1234` | 指定 commit hash              |
-
 ## 命令
 
-无需全局安装，直接使用 `npx reskill@latest`：
-
-```bash
-# 初始化项目
-npx reskill@latest init
-
-# 从 GitHub 安装 skill
-npx reskill@latest install github:anthropics/skills/frontend-design@latest
-
-# 从私有 GitLab 安装
-npx reskill@latest install gitlab.company.com:team/internal-skill@v1.0.0
-
-# 列出已安装的 skills
-npx reskill@latest list
-```
-
-### 命令参考
-
-| 命令                                    | 说明                                            |
-| --------------------------------------- | ----------------------------------------------- |
-| `npx reskill@latest init`               | 在当前目录初始化 `skills.json`                  |
-| `npx reskill@latest install [skill]`    | 安装 `skills.json` 中的所有 skills 或指定 skill |
-| `npx reskill@latest list`               | 列出已安装的 skills                             |
-| `npx reskill@latest info <skill>`       | 查看 skill 详情                                 |
-| `npx reskill@latest update [skill]`     | 更新所有或指定 skill                            |
-| `npx reskill@latest outdated`           | 检查过期的 skills                               |
-| `npx reskill@latest uninstall <skill>`  | 卸载 skill                                      |
-| `npx reskill@latest completion install` | 安装 Shell Tab 补全                             |
-
-运行 `npx reskill@latest <command> --help` 查看详细选项。
-
-### Shell 补全
-
-reskill 支持 bash、zsh 和 fish 的 Tab 补全。
-
-```bash
-# 安装补全（交互式，一次性设置）
-reskill completion install
-
-# 然后重启 shell 或执行：
-source ~/.zshrc   # zsh
-source ~/.bashrc  # bash
-```
-
-安装后即可使用 Tab 补全：
-
-```bash
-reskill <Tab>              # 显示所有命令
-reskill info <Tab>         # 补全已安装的 skill 名称
-reskill uninstall <Tab>    # 补全已安装的 skill 名称
-reskill install -<Tab>     # 补全选项 (-f, -g, -a 等)
-reskill install -a <Tab>   # 补全 agent 名称
-```
-
-卸载补全：`reskill completion uninstall`
-
-## 私有 GitLab 支持
-
-reskill 完整支持私有 GitLab 仓库，包括自建实例。认证通过系统的 git 配置透明处理。
+| 命令                 | 说明                 |
+| -------------------- | -------------------- |
+| `init`               | 初始化 `skills.json` |
+| `install [skill]`    | 安装 skills          |
+| `list`               | 列出已安装的 skills  |
+| `info <skill>`       | 查看 skill 详情      |
+| `update [skill]`     | 更新 skills          |
+| `outdated`           | 检查过期的 skills    |
+| `uninstall <skill>`  | 卸载 skill           |
+| `doctor`             | 诊断环境并检查问题   |
+| `completion install` | 安装 Shell Tab 补全  |
 
-### 认证方式
+运行 `reskill <command> --help` 查看详细选项。
 
-**SSH（推荐）**
-
-reskill 自动使用你已有的 SSH 配置：
+## 源格式
 
 ```bash
-# 自动使用 ~/.ssh/id_rsa 或 ~/.ssh/id_ed25519
-npx reskill@latest install gitlab.company.com:team/private-skill@v1.0.0
-
-# 或使用显式的 SSH URL
-npx reskill@latest install git@gitlab.company.com:team/private-skill.git@v1.0.0
+github:user/skill@v1.0.0                    # GitHub 简写
+gitlab:group/skill@latest                   # GitLab 简写
+gitlab.company.com:team/skill@v1.0.0        # 自建实例
+https://github.com/user/repo/tree/main/path # 网页 URL（支持子路径）
 ```
 
-确保你的 SSH key 已添加到 GitLab，并且 ssh-agent 正在运行。
-
-**HTTPS + Git Credential**
-
-适用于 CI/CD 或无 SSH 的环境，配置 git credential helper：
-
-```bash
-# 存储凭证（首次会提示输入，之后自动记住）
-git config --global credential.helper store
-
-# 或在 CI 中使用环境变量
-git config --global credential.helper '!f() { echo "username=oauth2"; echo "password=${GITLAB_TOKEN}"; }; f'
-```
-
-GitLab CI/CD 可使用内置的 `CI_JOB_TOKEN`：
-
-```yaml
-before_script:
-  - git config --global url."https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.company.com/".insteadOf "https://gitlab.company.com/"
-```
+## 版本规范
 
-### Registry 配置
-
-在 `skills.json` 中配置私有 registry：
-
-```json
-{
-  "registries": {
-    "internal": "https://gitlab.company.com",
-    "private": "git@gitlab.internal.io"
-  },
-  "skills": {
-    "company-standards": "internal:team/standards@latest",
-    "private-utils": "private:utils/helpers@v1.0.0"
-  }
-}
-```
-
-### 自建 GitLab
-
-对于使用自定义域名的自建 GitLab 实例：
-
-```bash
-# 直接安装
-npx reskill@latest install git.mycompany.io:team/skill@v1.0.0
-
-# 使用显式的 SSH URL
-npx reskill@latest install git@git.mycompany.io:team/skill.git@v1.0.0
-```
+| 格式     | 示例              | 说明             |
+| -------- | ----------------- | ---------------- |
+| 精确版本 | `@v1.0.0`         | 锁定到指定 tag   |
+| 最新版本 | `@latest`         | 获取最新 tag     |
+| 范围版本 | `@^2.0.0`         | semver 兼容      |
+| 分支     | `@branch:develop` | 指定分支         |
+| Commit   | `@commit:abc1234` | 指定 commit hash |
 
 ## 配置
 
@@ -254,81 +79,40 @@ npx reskill@latest install git@git.mycompany.io:team/skill.git@v1.0.0
 
 ```json
 {
-  "name": "my-project",
   "skills": {
     "planning": "github:user/planning-skill@v1.0.0",
-    "code-review": "gitlab:team/code-review@latest"
-  },
-  "defaults": {
-    "registry": "github",
-    "installDir": ".skills"
+    "internal-tool": "internal:team/tool@latest"
   },
   "registries": {
     "internal": "https://gitlab.company.com"
+  },
+  "defaults": {
+    "installDir": ".skills"
   }
 }
 ```
 
-### skills.lock
+### 私有仓库
+
+reskill 使用你已有的 git 凭证（SSH key 或 credential helper）。CI/CD 配置：
 
-锁定文件记录精确版本和 commit hash，确保团队间可复现的安装结果。
+```bash
+# GitLab CI
+git config --global url."https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.company.com/".insteadOf "https://gitlab.company.com/"
+```
 
 ## 多 Agent 支持
 
-reskill 支持所有主流 AI 编程 Agent。Skills 默认安装到 `.skills/` 目录，可与任何 Agent 集成。
+Skills 默认安装到 `.skills/`，可与任何 Agent 集成：
 
-| Agent          | 集成路径                              |
+| Agent          | 路径                                  |
 | -------------- | ------------------------------------- |
 | Cursor         | `.cursor/rules/` 或 `.cursor/skills/` |
 | Claude Code    | `.claude/skills/`                     |
 | Codex          | `.codex/skills/`                      |
-| OpenCode       | `.opencode/skills/`                   |
 | Windsurf       | `.windsurf/skills/`                   |
 | GitHub Copilot | `.github/skills/`                     |
 
-## Skill 仓库结构
-
-每个 Skill 仓库应遵循以下结构：
-
-```
-my-skill/
-├── skill.json           # 元数据（必需）
-├── SKILL.md             # 主入口文档（必需）
-├── README.md            # 仓库说明
-└── templates/           # 模板文件（可选）
-```
-
-### skill.json
-
-```json
-{
-  "name": "my-skill",
-  "version": "1.0.0",
-  "description": "A skill for ...",
-  "author": "Your Name",
-  "license": "MIT",
-  "entry": "SKILL.md",
-  "keywords": ["ai", "skill"]
-}
-```
-
-## 项目结构
-
-安装后的目录结构：
-
-```
-my-project/
-├── skills.json          # 依赖声明
-├── skills.lock          # 版本锁定文件
-└── .skills/             # 安装目录
-    ├── planning/
-    │   ├── skill.json
-    │   └── SKILL.md
-    └── code-review/
-        ├── skill.json
-        └── SKILL.md
-```
-
 ## 环境变量
 
 | 变量                | 说明         | 默认值             |
@@ -363,8 +147,6 @@ reskill 的实现参考了以下优秀项目：
 - [skild](https://github.com/Peiiii/skild) by Peiiii
 - [openskills](https://github.com/numman-ali/openskills) by Numman Ali
 
-感谢这些项目为 AI agent skills 生态系统做出的开创性贡献！
-
 ## 相关链接
 
 - [Agent Skills 规范](https://agentskills.io)

package/dist/cli/commands/doctor.d.ts

@@ -0,0 +1,119 @@
+import { Command } from 'commander';
+/**
+ * Check result type
+ */
+export type CheckStatus = 'ok' | 'warn' | 'error';
+export interface CheckResult {
+    name: string;
+    status: CheckStatus;
+    message: string;
+    hint?: string;
+}
+/**
+ * Get status icon
+ */
+export declare function getStatusIcon(status: CheckStatus): string;
+/**
+ * Execute command and return output
+ *
+ * @warning This function executes arbitrary shell commands. It is exported for
+ * testing purposes only. Do not use with untrusted input. Internal usage is
+ * limited to hardcoded commands (e.g., 'git --version').
+ */
+export declare function execCommand(command: string): string | null;
+/**
+ * Get directory size in bytes
+ */
+export declare function getDirSize(dirPath: string): number;
+/**
+ * Format bytes to human readable
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Count cached skills
+ */
+export declare function countCachedSkills(cacheDir: string): number;
+/**
+ * Check reskill version
+ */
+export declare function checkReskillVersion(currentVersion: string, packageName: string): Promise<CheckResult>;
+/**
+ * Check Node.js version
+ */
+export declare function checkNodeVersion(): CheckResult;
+/**
+ * Check Git version
+ */
+export declare function checkGitVersion(): CheckResult;
+/**
+ * Check Git authentication
+ */
+export declare function checkGitAuth(): CheckResult;
+/**
+ * Check cache directory
+ */
+export declare function checkCacheDir(): CheckResult;
+/**
+ * Check skills.json
+ */
+export declare function checkSkillsJson(cwd: string): CheckResult;
+/**
+ * Check for registry name conflicts
+ */
+export declare function checkRegistryConflicts(cwd: string): CheckResult[];
+/**
+ * Check for dangerous installDir configuration
+ */
+export declare function checkInstallDir(cwd: string): CheckResult | null;
+/**
+ * Check for invalid targetAgents configuration
+ */
+export declare function checkTargetAgents(cwd: string): CheckResult[];
+/**
+ * Check for skill reference format errors
+ */
+export declare function checkSkillRefs(cwd: string): CheckResult[];
+/**
+ * Check for version conflicts in monorepo skills
+ */
+export declare function checkMonorepoVersions(cwd: string): CheckResult[];
+/**
+ * Check skills.lock sync status
+ */
+export declare function checkSkillsLock(cwd: string): CheckResult;
+/**
+ * Skill issue type
+ */
+export interface SkillIssue {
+    name: string;
+    reason: string;
+    severity: 'error' | 'warn';
+}
+/**
+ * Check installed skills with detailed diagnostics
+ */
+export declare function checkInstalledSkills(cwd: string): CheckResult[];
+/**
+ * Check network connectivity
+ */
+export declare function checkNetwork(host: string): Promise<CheckResult>;
+/**
+ * Print check result
+ */
+export declare function printResult(result: CheckResult): void;
+/**
+ * Run all checks
+ */
+export declare function runDoctorChecks(options: {
+    cwd: string;
+    packageName: string;
+    packageVersion: string;
+    skipNetwork?: boolean;
+    skipConfigChecks?: boolean;
+}): Promise<CheckResult[]>;
+/**
+ * doctor command - Diagnose reskill environment
+ */
+export declare const doctorCommand: Command;
+export default doctorCommand;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/cli/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;AAElD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CASzD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM1D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAkBlD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA2B1D;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,WAAW,CAAC,CAuBtB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CAmB9C;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,WAAW,CAqB7C;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,WAAW,CAiD1C;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,WAAW,CAmB3C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CA4BxD;AAwCD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,EAAE,CA2BjE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAwC/D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,EAAE,CA2B5D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,EAAE,CAyCzD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,EAAE,CA6DhE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAsExD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;CAC5B;AA4CD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,EAAE,CA0F/D;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAoCrE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAUrD;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA4CzB;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,SAgDtB,CAAC;AAEL,eAAe,aAAa,CAAC"}

package/dist/cli/commands/index.d.ts

@@ -1,4 +1,5 @@
 export { completionCommand, maybeHandleCompletion } from './completion.js';
+export { doctorCommand } from './doctor.js';
 export { infoCommand } from './info.js';
 export { initCommand } from './init.js';
 export { installCommand } from './install.js';

package/dist/cli/commands/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}