npx skills check 的工作原理

`npx skills check` 原理

这个命令核心功能是**检查已安装的 skill 是否有更新版本**。

整体流程

```

读取 lock 文件 → 分类/过滤 → 调用 GitHub API 获取最新 hash → 与本地 hash 对比 → 输出结果

```

详细步骤

1. 读取 Lock 文件

首先读取 `~/.agents/.skill-lock.json`（即 `$HOME/.agents/.skill-lock.json`）。这个文件在安装 skill 时自动生成，记录了所有已安装 skill 的元数据。

你当前的 lock 文件内容类似：

javascript 复制代码

{
  "version": 3,
  "skills": {
    "find-skills": {
      "source": "vercel-labs/skills",
      "sourceType": "github",
      "sourceUrl": "https://github.com/vercel-labs/skills.git",
      "skillPath": "skills/find-skills/SKILL.md",
      "skillFolderHash": "3013fdeb8a11b10b1eb795ec3ae8bfca38f7c26d",
      "installedAt": "2026-01-28T08:41:46.011Z",
      "updatedAt": "2026-03-14T10:21:36.154Z"
    }
  }
}

关键字段：

**`source`** --- GitHub 仓库 `owner/repo` 格式
**`sourceType`** --- `"github"` / `"git"` / `"local"` 等
**`skillPath`** --- skill 在仓库中的路径（如 `skills/find-skills/SKILL.md`）
**`skillFolderHash`** --- 安装时记录的 Git tree SHA hash

2. 过滤与分类

遍历 lock 中的每个 skill，按以下规则分类：

**可检查**：必须同时具有 `skillFolderHash` 和 `skillPath`
**跳过**（skipped）：不满足条件的 skill，原因包括：
`sourceType === "local"` --- 本地路径安装的
`sourceType === "git"` --- 纯 Git URL（非 GitHub），不支持 hash 追踪
缺少 `skillFolderHash` --- 安装时没有记录版本 hash
缺少 `skillPath` --- 没有记录 skill 路径

例如你的 `qwencloud-update-check` 因为 `skillFolderHash` 为空，就会被跳过。

3. 获取 GitHub Token

通过以下优先级获取认证令牌：

环境变量 GITHUB_TOKEN → 环境变量 GH_TOKEN → 执行 `gh auth token` 命令

Token 用于 GitHub API 认证（可选，但无 Token 时有速率限制）。

4. 调用 GitHub API 获取最新 Hash

核心函数 `fetchSkillFolderHash` 的工作方式：

javascript 复制代码

GET https://api.github.com/repos/{owner}/{repo}/git/trees/{branch}?recursive=1

它会依次尝试 `main` 和 `master` 分支，请求仓库的完整 Git tree。然后在返回的 tree 结构中，找到对应 skill 文件夹的 `sha` 值。

这里的 **sha 就是 Git 的 tree object hash** --- 只要该文件夹下任何文件有变动（新增、修改、删除），这个 sha 就会改变。这是一种非常轻量的方式来判断远端是否有更新，不需要 clone 整个仓库。

5. 对比 Hash

javascript 复制代码

if (latestHash !== entry.skillFolderHash) {
    updates.push({ name, source });
}

简单的字符串比较：

**相等** → skill 是最新的
**不相等** → 有更新可用

6. 输出结果

如果全部一致：`✓ All skills are up to date`
如果有差异：列出哪些 skill 有更新，并提示运行 `npx skills update`
如果有错误：提示无法检查某些 skill
如果有被跳过的：列出跳过原因

核心设计思想

| 设计点 | 说明 |

|--------|------|

| **Git tree SHA 对比** | 不下载文件，只比较 hash，非常快速轻量 |

| **Lock 文件机制** | 类似 `package-lock.json`，记录安装时的精确版本 |

| **仅支持 GitHub** | `check` 只能检查 `sourceType: "github"` 的 skill，其他来源会被跳过 |

| **分支回退** | 先尝试 `main`，失败则尝试 `master` |

| **只读操作** | `check` 不修改任何文件，只是查询和报告 |

与 `npx skills update` 的关系

`check` 只做检查报告，`update` 则在检查基础上真正执行更新 --- 对有更新的 skill 重新执行 `add` 操作，拉取最新版本并更新 lock 文件中的 hash。