@morehao/dsh-skills-console 0.2.2 → 0.2.4

package/README.md

@@ -41,6 +41,8 @@ DSH（DeepSeek Harness）的**技能控制台**：装、更新、删除、接入
 
 ## 安装
 
+插件依赖里自带 `skills@1.7.4`，**不需要用户预装 Node / npm / npx**：CLI 由宿主自带的 Node 启动，装插件时随依赖一起落盘。安装技能仍需要**本机有 git**（CLI 会 `git clone` 仓库）；首次装插件需要联网拉取依赖。
+
 在 Harness 里装本地 link：
 
 ```bash
@@ -55,7 +57,7 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
       name: '@morehao/dsh-skills-console'
 ```
 
-客户端 half 只注册 `platform: web`，面板出现在 DSH Web 的设置页 / 侧栏。
+客户端 half 只注册 `platform: web`，面板出现在 DSH Web 的设置页 / 侧栏。本地 `link:` 开发时，先在仓库跑一次 `npm install`（装上 `skills`），否则 CLI 依赖层不会命中。
 
 ## 快速上手
 
@@ -66,7 +68,7 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 
 ## 可靠性
 
-- **canonical 与 CLI lock 只读**：`~/.agents/skills`、`~/.agents/.skill-lock.json` 的增删改只经 `skills` CLI，插件不直接写、不克隆仓库、不代理来源。
+- **canonical 与 CLI lock 只读**：`~/.agents/skills`、`~/.agents/.skill-lock.json`（设了 `XDG_STATE_HOME` 时为 `$XDG_STATE_HOME/skills/.skill-lock.json`）的增删改只经 `skills` CLI，插件不直接写；探测 / 更新检查会把仓库临时 clone 到 `os.tmpdir()`（只读、用完即删），结果绝不落进 canonical 或 lock。
 - **只动自己的东西**：只处理本插件创建的 `managed` 链接，以及已记账的 `managed-external`；`real` 目录和 `foreign-link` 永不改写，删除前体检直接中止。
 - **启停不改正文**：`mode` 只增删 DSH 侧链接，避免本地修改被下一次 `add` 覆盖。
 - **可回滚**：删除进回收站（7 天）；更新前快照到 `backups/`，失败自动还原（接口另提供手动回滚）。
@@ -78,13 +80,29 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 | 项 | 路径 | 归属 |
 | --- | --- | --- |
 | canonical 真身 | `~/.agents/skills` | `skills` CLI 独占 |
-| CLI lock | `~/.agents/.skill-lock.json` | `skills` CLI 独占（本插件只读） |
+| CLI lock | `~/.agents/.skill-lock.json`（设了 `XDG_STATE_HOME` 时为 `$XDG_STATE_HOME/skills/.skill-lock.json`） | `skills` CLI 独占（本插件只读） |
 | DSH 全局根 | `~/.dsh/skills` | 本插件写软链 |
 | 插件状态 | `$DSH_HOME/skills-console/state.json` | 本插件（`DSH_SKILLS_CONSOLE_HOME` 可覆盖） |
 | 备份 / 回收站 | `$DSH_HOME/skills-console/{backups,trash}` | 本插件 |
 | 事件日志 | `$DSH_HOME/skills-console/dsh-skills-console.log` | 本插件（JSONL，1MB 滚动） |
 
-环境变量：`DSH_SKILLS_CONSOLE_HOME`、`DSH_SKILLS_CONSOLE_CLI`、`DSH_SKILLS_CONSOLE_NPX_SPEC`、`DSH_SKILLS_CONSOLE_TIMEOUT_MS`、`GITHUB_TOKEN` / `GH_TOKEN`。
+### 环境变量
+
+| 变量 | 默认 | 作用 |
+| --- | --- | --- |
+| `DSH_SKILLS_CONSOLE_HOME` | `$DSH_HOME/skills-console` | 状态、备份、回收站与事件日志的根 |
+| `DSH_SKILLS_CONSOLE_CLI` | 自动定位 | 覆盖 `skills` CLI（测试桩也走这里） |
+| `DSH_SKILLS_CONSOLE_NPX_SPEC` | `skills` | 仅 legacy `npx` 兜底用；桌面端没有 npx，正常应显示 `dependency` |
+| `DSH_SKILLS_CONSOLE_TIMEOUT_MS` | `120000` | 单次 CLI 调用超时 |
+| `DSH_SKILLS_CONSOLE_GIT` | `auto` | 设为 `off` 关闭 git 通道，强制只走 GitHub REST |
+| `DSH_SKILLS_CONSOLE_GIT_TIMEOUT_MS` | `60000` | git 单次操作（`ls-remote` / `clone`）超时 |
+| `GITHUB_TOKEN` / `GH_TOKEN` | 无 | 只读环境变量；带上后 REST 配额从匿名 60 次/小时提到 5000 次/小时 |
+| `XDG_STATE_HOME` | 未设置 | 设置后 CLI lock 移到 `$XDG_STATE_HOME/skills/.skill-lock.json`，插件跟随读取 |
+
+关于 GitHub 配额：**匿名 REST 是 60 次/小时，按出口 IP 共享**（公司、校园网出口常被同网段的人一起打满），打满后探测与更新会收到 403。本插件默认让探测、更新检查与 git 兜底走系统 `git`（`ls-remote` + `clone --filter=blob:none --no-checkout`），不占 REST 配额、也不需要 token；git 不可用时才回退 REST，所以原本能用的环境不会因为这条路径变坏。限流且 git 也不可用时，错误文案会给出恢复时间，并提示设置 `GITHUB_TOKEN`。
+
+> git 通道只在 `os.tmpdir()` 里读一份临时仓库，用完即删 —— 不写 canonical、不写 CLI lock，落盘始终只交给 `skills` CLI。
+
 
 ## 开发与发布
 

package/lib/core/cli.js

@@ -40,10 +40,15 @@ function findInPath(command, envPath) {
 }
 
 /**
- * CLI 定位四层（设计 §8.2）：显式覆盖 → 插件/宿主自带依赖 → PATH → npx。
+ * CLI 定位顺序：显式覆盖 → 本插件依赖 → 宿主 profile → PATH → npx（legacy）。
+ * 插件依赖排在 profile 前面：版本随插件锁死，不被 PATH 或别的插件带的旧版抢占。
  * 每一层都记来源，诊断页要展示"这次到底跑的哪一个"。
  */
-export function locateCli({ env = process.env, logger = () => {} } = {}) {
+export function locateCli({
+  env = process.env,
+  logger = () => {},
+  resolvePackage = () => require.resolve('skills/package.json'),
+} = {}) {
   const override = env.DSH_SKILLS_CONSOLE_CLI;
   if (override && override.trim()) {
     const parts = override.trim().split(/\s+/);
@@ -51,7 +56,20 @@ export function locateCli({ env = process.env, logger = () => {} } = {}) {
     return { command: parts[0], prefixArgs: parts.slice(1), source: 'env-override', jsonCapable: true };
   }
 
-  // 宿主 profile 里的 skills 依赖（最常见的实际位置）。
+  // 插件自己的 runtime 依赖：装插件时由宿主 pnpm 一起装好，用户不需要 Node/npm/npx。
+  try {
+    const pkg = resolvePackage();
+    const bin = path.join(path.dirname(pkg), 'bin', 'cli.mjs');
+    if (fs.existsSync(bin)) {
+      return { command: process.execPath, prefixArgs: [bin], source: 'dependency', jsonCapable: true };
+    }
+    // 包在但入口丢了，说明安装不完整；交给后面的层兜底，但要留痕
+    logger('cli.dependency.bin-missing', { pkg, bin });
+  } catch {
+    // 没装在本插件可见范围内（例如 link: 开发仓库还没 npm install），继续往下走
+  }
+
+  // 宿主 profile 里的 skills 依赖（兼容旧插件 / 其他插件已经带进来的版本）。
   // 注意：GUI 启动的宿主进程常常拿不到 DSH_PROFILE_DIR，所以再按 DSH_HOME/profiles/* 兜一层探测。
   const profileDir = env.DSH_PROFILE_DIR;
   if (profileDir) {
@@ -74,16 +92,6 @@ export function locateCli({ env = process.env, logger = () => {} } = {}) {
     // 没有 profiles 目录就继续往下走
   }
 
-  try {
-    const pkg = require.resolve('skills/package.json');
-    const bin = path.join(path.dirname(pkg), 'bin', 'cli.mjs');
-    if (fs.existsSync(bin)) {
-      return { command: process.execPath, prefixArgs: [bin], source: 'dependency', jsonCapable: true };
-    }
-  } catch {
-    // 没有作为依赖装在本插件可见范围内，继续往下走
-  }
-
   const onPath = findInPath('skills', env.PATH);
   if (onPath) return { command: onPath, prefixArgs: [], source: 'path', jsonCapable: true };
 
@@ -105,8 +113,13 @@ export function runCli(location, args, { timeoutMs = 120000, signal, env = proce
       stdio: ['ignore', 'pipe', 'pipe'],
       env: {
         ...env,
+        // 桌面宿主本身就是 Electron 的 Node 模式；显式补上，避免调用方传了裁剪过的 env
+        ...(process.versions.electron && location.command === process.execPath ? { ELECTRON_RUN_AS_NODE: '1' } : {}),
         CI: '1',
         NO_COLOR: '1',
+        // CLI 的遥测只看这两个变量；CI=1 不会关闭，只会在上报里打 ci=1 标记
+        DO_NOT_TRACK: '1',
+        DISABLE_TELEMETRY: '1',
         TERM: 'dumb',
         GIT_TERMINAL_PROMPT: '0',
         GIT_HTTP_LOW_SPEED_LIMIT: '1',
@@ -151,12 +164,12 @@ export function runCli(location, args, { timeoutMs = 120000, signal, env = proce
   });
 }
 
-export function createCli({ env = process.env, logger = () => {} } = {}) {
+export function createCli({ env = process.env, logger = () => {}, resolvePackage } = {}) {
   let cached = null;
   let capabilities = null;
 
   function location() {
-    if (!cached) cached = locateCli({ env, logger });
+    if (!cached) cached = locateCli({ env, logger, resolvePackage });
     return cached;
   }
 
@@ -178,7 +191,16 @@ export function createCli({ env = process.env, logger = () => {} } = {}) {
     /** 能力位：`--json` 与 `--full-depth` 任一不支持都要在 UI 上禁用写操作（漏装比不可用更危险）。 */
     async capabilities({ force = false } = {}) {
       if (capabilities && !force) return capabilities;
-      const loc = location();
+      let loc;
+      try {
+        loc = location();
+      } catch (error) {
+        if (!(error instanceof CliUnavailableError)) throw error;
+        // 不缓存：用户补好依赖 / PATH 后，下一次 /state 就能恢复，不必重启宿主；
+        // 同时清掉旧的成功缓存，避免 force 探测到 missing 后又回落到上一轮的 usable。
+        capabilities = null;
+        return { version: null, json: false, fullDepth: false, source: 'missing', usable: false };
+      }
       if (!loc.jsonCapable) {
         capabilities = { version: null, json: false, fullDepth: false, source: loc.source, usable: false };
         return capabilities;

package/lib/core/git.js

@@ -0,0 +1,282 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * 只读 git 通道：`ls-remote` 拿默认分支与 HEAD，`clone --filter=blob:none --no-checkout` +
+ * `ls-tree` 拿整树。**不占 GitHub REST 配额**，也不需要 token / gh —— 这是「出口 IP 被
+ * 匿名配额打死」时唯一还通的路。
+ *
+ * 硬约束（见 AGENTS.md「数据边界」）：
+ * - 只读：只在 `os.tmpdir()` 里建临时仓库，`finally` 必删；不碰 canonical、不碰 lock；
+ * - 不接受任意 URL：只认 `https://github.com/<owner>/<repo>.git`（由 `repoUrl` 从
+ *   `parseSource` 的产物重建），拒绝以 `-` 开头的 ref（防 argv 注入成选项）；
+ * - 零依赖：只用 node:child_process / node:fs / node:os / node:path。
+ */
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const VERSION_TIMEOUT_MS = 10_000;
+const MAX_STDOUT = 8 * 1024 * 1024;
+const MAX_STDERR = 64 * 1024;
+const TMP_PREFIX = 'dsh-skills-git-';
+const REPO_URL_RE = /^https:\/\/github\.com\/[\w.-]+\/[\w.-]+\.git$/;
+const COMMIT_RE = /^[0-9a-f]{40}$/;
+// 分支/tag 名：足够覆盖真实用法，同时排除以 `-` 开头（会被 git 当成选项）
+const REF_RE = /^[\w][\w./-]{0,254}$/;
+
+/** `kind` 供上层决定是否回退 REST：`git-missing` / `git-timeout` / `auth` / `clone-failed` / `invalid-url`。 */
+export class GitError extends Error {
+  constructor(kind, message, detail) {
+    super(message);
+    this.name = 'GitError';
+    this.kind = kind;
+    this.detail = detail || null;
+  }
+}
+
+/** 从 `owner/repo`（`parseSource` 的产物）重建 URL，再做一次白名单断言。 */
+export function repoUrl(source) {
+  const match = /^([\w.-]+)\/([\w.-]+)$/.exec(String(source || '').trim());
+  if (!match) throw new GitError('invalid-url', `不是 owner/repo 形态：${source}`);
+  const repo = match[2].replace(/\.git$/, '');
+  const url = `https://github.com/${match[1]}/${repo}.git`;
+  if (!REPO_URL_RE.test(url)) throw new GitError('invalid-url', `拒绝不安全的仓库地址：${url}`);
+  return url;
+}
+
+function assertUrl(url) {
+  if (typeof url !== 'string' || !REPO_URL_RE.test(url)) {
+    throw new GitError('invalid-url', `拒绝不安全的仓库地址：${url}`);
+  }
+}
+
+function assertRef(ref) {
+  if (typeof ref !== 'string' || !(REF_RE.test(ref) || COMMIT_RE.test(ref))) {
+    throw new GitError('invalid-url', `拒绝不安全的 ref：${ref}`);
+  }
+}
+
+function withDefaults(env) {
+  return {
+    ...env,
+    // 私有仓库 / 需要凭据时立刻失败，绝不卡在交互提示上
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_HTTP_LOW_SPEED_LIMIT: '1',
+    GIT_HTTP_LOW_SPEED_TIME: '30',
+    LC_ALL: 'C',
+  };
+}
+
+/** 子进程封装：无 shell、argv 直传、硬超时 SIGKILL、stdout 上限。永不 reject。 */
+function runGit(args, { cwd, timeoutMs = DEFAULT_TIMEOUT_MS, env = process.env } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+    let child;
+    try {
+      child = spawn('git', args, {
+        cwd,
+        shell: false,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: withDefaults(env),
+      });
+    } catch (error) {
+      finish({ spawnError: error, code: null, stdout: '', stderr: '', timedOut: false, args });
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+      // 孙进程（git-remote-https 之类）可能还握着管道：不等它们退出，直接判超时
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      finish({ code: null, stdout, stderr, timedOut: true, args });
+    }, timeoutMs);
+    child.stdout.on('data', (chunk) => {
+      if (stdout.length >= MAX_STDOUT) return;
+      stdout += chunk.toString('utf8').slice(0, MAX_STDOUT - stdout.length);
+    });
+    child.stderr.on('data', (chunk) => {
+      if (stderr.length < MAX_STDERR) stderr += chunk.toString('utf8');
+    });
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      finish({ spawnError: error, code: null, stdout, stderr, timedOut, args });
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      finish({ code, stdout, stderr, timedOut, args });
+    });
+  });
+}
+
+/** 退出码非 0 → 分类。`auth` 涵盖「私有仓库 / 凭据不对 / 仓库不存在」这几种 git 都只说一句话的情况。 */
+function toGitError(result, fallbackMessage = 'git 失败') {
+  if (result.spawnError) {
+    return new GitError('git-missing', result.spawnError.message, { code: result.spawnError.code || null });
+  }
+  if (result.timedOut) {
+    return new GitError('git-timeout', `git ${result.args?.[0] || ''} 超时`, { args: result.args || [] });
+  }
+  const stderr = String(result.stderr || '').trim();
+  if (
+    /authentication failed|could not read username|terminal prompts disabled|permission denied|repository[^\n]*not found|invalid username or password|access denied/i.test(
+      stderr,
+    )
+  ) {
+    return new GitError('auth', stderr.slice(-400) || '认证失败', { code: result.code ?? null });
+  }
+  return new GitError('clone-failed', (stderr || fallbackMessage).slice(-400), { code: result.code ?? null });
+}
+
+/** `git --version` 探测。没有 git 的环境本来也装不了技能，回退 REST 即可。 */
+export async function gitAvailable({ env = process.env, timeoutMs = VERSION_TIMEOUT_MS } = {}) {
+  const result = await runGit(['--version'], { env, timeoutMs });
+  if (result.spawnError || result.timedOut || result.code !== 0) return false;
+  return /git version \d+/.test(result.stdout);
+}
+
+/** `git ls-remote --symref <url> HEAD` → `{ branch, commit }`。零配额拿默认分支 + HEAD。 */
+export async function lsRemote({ url, env = process.env, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  assertUrl(url);
+  const result = await runGit(['ls-remote', '--symref', url, 'HEAD'], { env, timeoutMs });
+  if (result.spawnError || result.timedOut || result.code !== 0) throw toGitError(result, 'ls-remote 失败');
+  let branch = null;
+  let commit = null;
+  for (const raw of result.stdout.split('\n')) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (line.startsWith('ref:')) {
+      const symref = /^ref:\s+refs\/heads\/(\S+)\s+HEAD$/.exec(line);
+      if (symref) branch = symref[1];
+      continue;
+    }
+    const head = /^([0-9a-f]{40})\s+HEAD$/.exec(line);
+    if (head) commit = head[1];
+  }
+  if (!commit) throw new GitError('clone-failed', 'ls-remote 没有返回 HEAD 指向的 commit');
+  return { branch, commit };
+}
+
+/** `git ls-tree -r -t -z` 的输出 → `[{ type, path, sha }]`，与 Trees API 同形。 */
+export function parseTreeEntries(stdout) {
+  const entries = [];
+  for (const record of String(stdout || '').split('\0')) {
+    if (!record) continue;
+    // 默认格式：`<mode> <type> <sha>\t<path>`；路径里的空格/中文都靠 tab 定位，不会被切错
+    const tab = record.indexOf('\t');
+    if (tab < 0) continue;
+    const meta = record.slice(0, tab).split(' ');
+    const type = meta[1];
+    if (type !== 'blob' && type !== 'tree') continue;
+    entries.push({ type, path: record.slice(tab + 1), sha: meta[2] });
+  }
+  return entries;
+}
+
+/**
+ * `git clone --depth 1 --filter=blob:none --no-checkout` + `ls-tree` → `{ entries, rootSha, commit }`。
+ * 临时目录用完必删；容器型 `<ref>`（commit SHA）走 fetch，分支/tag 走 `--branch`。
+ * `tmpRoot` 只是给测试一个隔离的临时目录根，生产走 `os.tmpdir()`。
+ */
+export async function lsTree({ url, ref = 'HEAD', env = process.env, timeoutMs = DEFAULT_TIMEOUT_MS, tmpRoot = os.tmpdir() } = {}) {
+  assertUrl(url);
+  assertRef(ref);
+  const isCommit = COMMIT_RE.test(ref);
+  fs.mkdirSync(tmpRoot, { recursive: true });
+  const dir = fs.mkdtempSync(path.join(tmpRoot, TMP_PREFIX));
+  const base = ['clone', '--depth', '1', '--no-checkout', '--quiet'];
+  const cloneArgs = [...base, '--filter=blob:none'];
+  if (!isCommit) cloneArgs.push('--branch', ref);
+  cloneArgs.push(url, dir);
+
+  try {
+    let cloned = await runGit(cloneArgs, { env, timeoutMs });
+    // 老 git（< 2.19）不认 --filter：去掉再试一次（慢一点，但能用）
+    if ((cloned.spawnError || cloned.timedOut || cloned.code !== 0) && /filter/i.test(cloned.stderr || '')) {
+      const retry = [...base];
+      if (!isCommit) retry.push('--branch', ref);
+      retry.push(url, dir);
+      cloned = await runGit(retry, { env, timeoutMs });
+    }
+    if (cloned.spawnError || cloned.timedOut || cloned.code !== 0) throw toGitError(cloned, 'clone 失败');
+
+    // HEAD 对应的 commit：分支/tag 克隆时是 HEAD，commit 形态直接用它自己
+    const revTarget = isCommit ? `${ref}^{commit}` : 'HEAD^{commit}';
+    let rev = await runGit(['-C', dir, 'rev-parse', '--verify', revTarget], { env, timeoutMs });
+    if (rev.code !== 0 && isCommit) {
+      // 默认分支的浅克隆里可能没有这个 commit：单独取一次
+      await runGit(['-C', dir, 'fetch', '--depth', '1', '--quiet', url, ref], { env, timeoutMs });
+      rev = await runGit(['-C', dir, 'rev-parse', '--verify', revTarget], { env, timeoutMs });
+    }
+    const commit = rev.code === 0 ? rev.stdout.trim() : '';
+    if (!COMMIT_RE.test(commit)) throw toGitError(rev, 'rev-parse 拿不到 commit');
+
+    const treeRev = await runGit(['-C', dir, 'rev-parse', '--verify', `${commit}^{tree}`], { env, timeoutMs });
+    const rootSha = treeRev.code === 0 ? treeRev.stdout.trim() : '';
+    if (!COMMIT_RE.test(rootSha)) throw toGitError(treeRev, 'rev-parse 拿不到根 tree');
+
+    const listed = await runGit(['-C', dir, 'ls-tree', '-r', '-t', '-z', commit], { env, timeoutMs });
+    if (listed.code !== 0) throw toGitError(listed, 'ls-tree 失败');
+    return { entries: parseTreeEntries(listed.stdout), rootSha, commit };
+  } finally {
+    if (dir.includes(TMP_PREFIX)) fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * 服务实例用的封装：进程内缓存 `git --version` 结论与 `(url, ref)` 的整树
+ * （一个仓库装多个技能时只 clone 一次），并统一读 `DSH_SKILLS_CONSOLE_GIT*`。
+ */
+export function createGit({ env = process.env, logger = () => {} } = {}) {
+  const TREE_TTL_MS = 60_000;
+  const TREE_MAX = 20;
+  const trees = new Map();
+  let available = null;
+
+  const enabled = () => String(env.DSH_SKILLS_CONSOLE_GIT || '').trim().toLowerCase() !== 'off';
+  const timeoutMs = () => {
+    const value = Number(env.DSH_SKILLS_CONSOLE_GIT_TIMEOUT_MS);
+    return Number.isFinite(value) && value > 0 ? value : DEFAULT_TIMEOUT_MS;
+  };
+
+  async function isAvailable() {
+    if (!enabled()) return false;
+    if (available === null) available = await gitAvailable({ env, timeoutMs: Math.min(timeoutMs(), VERSION_TIMEOUT_MS) });
+    if (!available) logger('git.missing');
+    return available;
+  }
+
+  async function tree({ url, ref }) {
+    const key = `${url}@${ref}`;
+    const cached = trees.get(key);
+    if (cached && Date.now() - cached.at < TREE_TTL_MS) return cached.value;
+    const value = await lsTree({ url, ref, env, timeoutMs: timeoutMs() });
+    trees.set(key, { value, at: Date.now() });
+    for (const oldest of trees.keys()) {
+      if (trees.size <= TREE_MAX) break;
+      trees.delete(oldest);
+    }
+    return value;
+  }
+
+  return {
+    enabled,
+    isAvailable,
+    timeoutMs,
+    url: repoUrl,
+    lsRemote: (options = {}) => lsRemote({ ...options, env, timeoutMs: options.timeoutMs || timeoutMs() }),
+    tree,
+    clearCache() {
+      trees.clear();
+    },
+  };
+}

package/lib/core/paths.js

@@ -12,6 +12,10 @@ export function createPaths(env = process.env, overrides = {}) {
   const dshHome = overrides.dshHome ?? env.DSH_HOME ?? path.join(home, '.dsh');
   const stateDir =
     overrides.stateDir ?? env.DSH_SKILLS_CONSOLE_HOME ?? path.join(dshHome, 'skills-console');
+  // 与 skills CLI 的 getSkillLockPath 对齐：设了 XDG_STATE_HOME 时 lock 在 XDG 下
+  const lockFile = env.XDG_STATE_HOME
+    ? path.join(env.XDG_STATE_HOME, 'skills', '.skill-lock.json')
+    : path.join(home, '.agents', '.skill-lock.json');
 
   return {
     home,
@@ -20,8 +24,8 @@ export function createPaths(env = process.env, overrides = {}) {
     stateDir,
     /** canonical 真身：CLI 唯一的落点（F1） */
     canonical: path.join(home, '.agents', 'skills'),
-    /** CLI 全局 lock（F4） */
-    lockFile: path.join(home, '.agents', '.skill-lock.json'),
+    /** CLI 全局 lock（F4）；XDG_STATE_HOME 优先，与 CLI 一致 */
+    lockFile,
     /** DSH 原生 user-dsh 根（rank 400） */
     dshGlobalSkills: path.join(dshHome, 'skills'),
     stateFile: path.join(stateDir, 'state.json'),

package/lib/core/service.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { StateReadOnlyError } from './state.js';
 import { contentHash } from './hash.js';
+import { createGit } from './git.js';
 import { ensureLink, inspectTarget, removeLink } from './links.js';
 import { buildLedger, readLock, scanCanonical } from './inventory.js';
 import { createBackup, readBackup, restoreBackup, trashSkill } from './trash.js';
@@ -9,6 +10,7 @@ import {
   checkSkill,
   fetchDefaultBranch,
   fetchTree,
+  hashShape,
   listSkillsFromTree,
   parseSource,
   planToken,
@@ -31,6 +33,62 @@ function nowIso() {
   return new Date().toISOString();
 }
 
+// skills CLI 对任意 GitHub 仓库走 git clone；没装 git 时它把错误打在 stdout（spinner）里
+const GIT_MISSING_RE = /spawn git ENOENT|git: command not found|not recognized as an internal or external command/i;
+
+/** 把 CLI 的 add 失败翻译成可执行错误；git 缺失时不要只给一句 spawn ENOENT。 */
+function cliAddFailure(result, action) {
+  const detail = {
+    code: result.code,
+    stderr: (result.stderr || '').slice(-2000),
+    stdout: (result.stdout || '').slice(-2000),
+  };
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`;
+  if (GIT_MISSING_RE.test(output)) {
+    return new ServiceError(
+      'error.skills.git-missing',
+      '安装/更新技能需要本机有 git（skills CLI 会 clone 仓库）；请安装 git 后重试',
+      detail,
+    );
+  }
+  return new ServiceError('error.skills.cli-failed', `skills ${action} 失败`, detail);
+}
+
+/** 本机时区的 `HH:mm`。手写而不是 `toLocaleTimeString`：不受 ICU / locale 差异影响。 */
+function formatClock(ms) {
+  const at = new Date(ms);
+  const pad = (value) => String(value).padStart(2, '0');
+  return `${pad(at.getHours())}:${pad(at.getMinutes())}`;
+}
+
+/**
+ * 上游失败 → 可执行错误（T1）。四类必须互不相同，否则用户只知道「读不到」，
+ * 不知道该等、该改来源，还是该查网络。
+ */
+function upstreamError(source, failure) {
+  const status = failure?.status ?? null;
+  const resetAt = failure?.resetAt ?? null;
+  const detail = { source, status, resetAt, error: failure?.error ?? null };
+  if (failure?.rateLimited) {
+    const resume = resetAt ? `约 ${formatClock(resetAt)} 后自动恢复；` : '';
+    return new ServiceError(
+      'error.skills.rate-limited',
+      `GitHub 接口已限流（匿名 60 次/小时，按出口 IP 共享）。${resume}设置 GITHUB_TOKEN 可提到 5000 次/小时`,
+      detail,
+    );
+  }
+  if (status === 404) {
+    return new ServiceError('error.skills.repo-not-found', `读不到 ${source}：仓库不存在或为私有`, detail);
+  }
+  if (status === 401 || status === 403) {
+    return new ServiceError('error.skills.repo-forbidden', `读取 ${source} 被拒绝（HTTP ${status}）`, detail);
+  }
+  if (status) {
+    return new ServiceError('error.skills.upstream-failed', `读取 ${source} 失败：HTTP ${status}`, detail);
+  }
+  return new ServiceError('error.skills.network', '无法连接 GitHub（网络或代理问题）', detail);
+}
+
 /** `skills add --json` 的输出：数组或 `{ installed: [...] }`，只取 name 并去重。 */
 function installedNamesFrom(stdout) {
   try {
@@ -141,6 +199,7 @@ function createQueue(logger) {
 export function createService({ paths, store, registry, cli, logger, env = process.env, fetchImpl = fetch, visibleProvider = async () => ({ skills: [], complete: true }), workspacesProvider = async () => [] }) {
   const enqueue = createQueue(logger);
   const tokenOf = (env.GITHUB_TOKEN || env.GH_TOKEN) || null;
+  const git = createGit({ env, logger });
   // 探测缓存：同一来源短时间内重复检测直接复用；并发的相同请求合并成一次（不重复烧 API 配额）
   const probeCache = new Map();
   const PROBE_TTL_MS = 60_000;
@@ -154,6 +213,19 @@ export function createService({ paths, store, registry, cli, logger, env = proce
     if (store.readOnly) throw new StateReadOnlyError(store.problem);
   }
 
+  /** 所有会调 CLI 的写操作共用；缺失时给 400，不要把裸 CliUnavailableError 漏成 500。 */
+  async function requireUsableCli() {
+    const capabilities = await cli.capabilities();
+    if (!capabilities.usable) {
+      throw new ServiceError(
+        'error.skills.cli-missing',
+        'skills CLI 不可用或不支持 --json/--full-depth，写操作已禁用',
+        capabilities,
+      );
+    }
+    return capabilities;
+  }
+
   function detectedTargets() {
     return registry.detected();
   }
@@ -203,44 +275,51 @@ export function createService({ paths, store, registry, cli, logger, env = proce
     return { created, skipped, failed };
   }
 
-  /** 订阅的分支：显式 ref > 记录里的 ref > 仓库默认分支。解析成功后顺手记住，省掉下次请求。 */
+  /**
+   * 订阅的分支：显式 ref > 记录里的 ref > 仓库默认分支。解析成功后顺手记住，省掉下次请求。
+   * 返回 `{ branch, failure }`：`failure` 原样透出 `fetchDefaultBranch` 的结构化失败，
+   * 由 `readSnapshot` 决定报哪种错误（T1）。
+   */
   async function branchOf(subscription, { persist = false } = {}) {
-    if (subscription.ref) return subscription.ref;
-    let branch = null;
+    if (subscription.ref) return { branch: subscription.ref, failure: null };
+    let resolved;
     try {
-      branch = await fetchDefaultBranch({
+      resolved = await fetchDefaultBranch({
         source: subscription.source,
         token: tokenOf,
         fetchImpl,
       });
-    } catch {
-      branch = null;
+    } catch (error) {
+      return { branch: null, failure: { status: null, rateLimited: false, resetAt: null, error: error?.message || String(error) } };
     }
-    if (!branch) return null;
+    const branch = resolved?.branch || null;
+    if (!branch) return { branch: null, failure: resolved || null };
     if (persist && !store.readOnly) {
       store.update((draft) => {
         const row = draft.subscriptions.find((item) => item.id === subscription.id);
         if (row && !row.ref) row.ref = branch;
       });
     }
-    return branch;
+    return { branch, failure: null };
   }
 
   /**
-   * 读一次订阅快照：只有网络与纯计算，**不写 store**。
+   * 读一次订阅快照：只有网络与纯计算，**不写 store**（`persistRef` 例外，只补订阅的 ref）。
    * 上游失败一律抛 ServiceError —— 添加订阅必须先读到快照再记账，
    * 否则会留下「订阅存在但一个 skill 都没有」的空壳（上游 404 时还会显示添加成功）。
+   *
+   * T4：REST 因**限流**或 **404** 失败时先试 git（零配额）；git 也不行才抛 T1 的错误。
    */
-  async function readSnapshot(subscription, { force = false, withCommit = true } = {}) {
+  async function readSnapshot(subscription, { force = false, withCommit = true, persistRef = false } = {}) {
     const source = subscription.source;
     try {
-      const branch = await branchOf(subscription);
+      const { branch, failure } = await branchOf(subscription, { persist: persistRef });
       if (!branch) {
-        throw new ServiceError(
-          'error.skills.upstream-failed',
-          `读不到 ${source} 的默认分支（仓库不存在、私有，或 GitHub 接口不可用/已限流）`,
-          { source },
-        );
+        if (failure?.rateLimited || failure?.status === 404) {
+          const viaGit = await gitSnapshot(subscription, { ref: subscription.ref || null });
+          if (viaGit) return viaGit;
+        }
+        throw upstreamError(source, failure);
       }
       const result = await fetchTree({
         source,
@@ -250,6 +329,17 @@ export function createService({ paths, store, registry, cli, logger, env = proce
         fetchImpl,
       });
       if (result.error) {
+        // 元数据已经通了，树再 404 说明是 ref 没了（不是仓库不存在）；只有限流值得转 git
+        if (result.rateLimited) {
+          const viaGit = await gitSnapshot(subscription, { ref: branch });
+          if (viaGit) return viaGit;
+          throw upstreamError(source, {
+            status: result.status ?? null,
+            rateLimited: true,
+            resetAt: result.resetAt ?? null,
+            error: result.error,
+          });
+        }
         throw new ServiceError('error.skills.upstream-failed', `读取 ${source}@${branch} 失败：${result.error}`, {
           source,
           ref: branch,
@@ -277,6 +367,9 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       return {
         branch,
         changed,
+        via: 'rest',
+        tree: result.tree,
+        rootSha: result.rootSha,
         snapshot: { commit, rootSha: result.rootSha, entries, fetchedAt: nowIso(), etag: result.etag },
       };
     } catch (error) {
@@ -287,8 +380,162 @@ export function createService({ paths, store, registry, cli, logger, env = proce
     }
   }
 
-  function recordLink(name, target, linkPath, mode, created) {
-    if (store.readOnly) return;
+  /**
+   * T4：用 git 组装一份与 REST 同形的快照。`etag` 恒为 `null` —— 下次刷新会完整读一次，
+   * 绝不会拿旧 ETag 去冒充 304。失败返回 `null`，由调用方抛 T1 的错误。
+   */
+  async function gitSnapshot(subscription, { ref = null, purpose = 'snapshot' } = {}) {
+    const source = subscription.source;
+    const event = purpose === 'probe' ? 'git.probe' : 'git.snapshot';
+    if (!git.enabled()) return null;
+    const startedAt = Date.now();
+    let url;
+    try {
+      url = git.url(source);
+    } catch (error) {
+      logger('git.fallback', { source, kind: error.kind || 'invalid-url', purpose });
+      return null;
+    }
+    if (!(await git.isAvailable())) {
+      logger('git.fallback', { source, kind: 'git-missing', purpose });
+      return null;
+    }
+    try {
+      let branch = ref || null;
+      if (!branch) {
+        const head = await git.lsRemote({ url });
+        branch = head.branch || 'main';
+      }
+      const tree = await git.tree({ url, ref: branch });
+      const entries = listSkillsFromTree({
+        tree: tree.entries,
+        rootSha: tree.rootSha,
+        subpath: subscription.subpath,
+        repoName: source.split('/').pop(),
+      });
+      const changed =
+        !subscription.snapshot ||
+        subscription.snapshot.rootSha !== tree.rootSha ||
+        JSON.stringify(entries) !== JSON.stringify(subscription.snapshot.entries);
+      logger(event, {
+        source,
+        ref: branch,
+        commit: tree.commit,
+        entries: entries.length,
+        changed,
+        ms: Date.now() - startedAt,
+      });
+      return {
+        branch,
+        changed,
+        via: 'git',
+        tree: tree.entries,
+        rootSha: tree.rootSha,
+        snapshot: { commit: tree.commit, rootSha: tree.rootSha, entries, fetchedAt: nowIso(), etag: null },
+      };
+    } catch (error) {
+      logger('git.fallback', {
+        source,
+        kind: error.kind || 'clone-failed',
+        message: error.message,
+        purpose,
+        ms: Date.now() - startedAt,
+      });
+      return null;
+    }
+  }
+
+  /**
+   * T4 commit 短路：订阅快照的 commit 与远端 HEAD 一致 → 没变化，不必请求 REST。
+   * 只对「跟着默认分支」的订阅生效：盯 tag / 其他分支时 HEAD 不代表它。
+   */
+  async function remoteCommitUnchanged(subscription) {
+    const commit = subscription.snapshot?.commit;
+    if (!commit || !git.enabled()) return false;
+    if (!(await git.isAvailable())) return false;
+    try {
+      const head = await git.lsRemote({ url: git.url(subscription.source) });
+      if (subscription.ref && head.branch && subscription.ref !== head.branch) return false;
+      return head.commit === commit;
+    } catch (error) {
+      logger('git.fallback', {
+        source: subscription.source,
+        kind: error.kind || 'clone-failed',
+        purpose: 'refresh',
+      });
+      return false;
+    }
+  }
+
+  /**
+   * 探测走 git：`ls-remote` 拿默认分支，`clone --filter=blob:none --no-checkout` 拿整树。
+   * 不占 GitHub REST 配额，也不需要 token / gh —— 出口 IP 匿名配额被耗尽时这条路仍然通。
+   * 失败一律返回 `null`，由调用方回退现有 REST 路径（默认开 = 只增不减）。
+   */
+  async function probeViaGit({ source, ref, subpath }) {
+    const result = await gitSnapshot({ source, subpath, snapshot: null }, { ref, purpose: 'probe' });
+    if (!result) return null;
+    return { branch: result.branch, via: 'git', snapshot: result.snapshot };
+  }
+
+  /**
+   * T3.7 安装后基线补录。CLI 在拿不到树时把 64 位内容哈希写进 lock（`add.ts:2254`），
+   * 「手填技能名」这条安装路径又没有快照可依 —— 装上之后用 git 把目录 tree SHA 补进
+   * `installs[].treeSha`，让 T2 的判定对这条路径同样生效。
+   *
+   * best effort：只读临时目录；任何失败只记日志，**不改安装结果**，`treeSha` 留 null。
+   */
+  async function backfillBaselines({ names, source, lock, ref }) {
+    if (!git.enabled() || names.length === 0) return [];
+    const targets = [];
+    for (const name of names) {
+      const lockEntry = lock.skills?.[name];
+      if (hashShape(lockEntry?.skillFolderHash || null) !== 'content') continue;
+      const install = store.findInstall(name);
+      if (!install || install.treeSha) continue;
+      targets.push({ name, skillPath: lockEntry?.skillPath || install.skillPath || null });
+    }
+    if (targets.length === 0) return [];
+    if (!(await git.isAvailable())) {
+      logger('git.error', { source, kind: 'git-missing', purpose: 'baseline' });
+      return [];
+    }
+    const startedAt = Date.now();
+    try {
+      const url = git.url(source);
+      let useRef = ref || null;
+      if (!useRef) useRef = (await git.lsRemote({ url })).commit;
+      // 与探测共用进程内缓存：同一 (url, ref) 只 clone 一次
+      const tree = await git.tree({ url, ref: useRef });
+      const updated = [];
+      for (const target of targets) {
+        const treeSha = target.skillPath
+          ? skillTreeSha({ tree: tree.entries, skillPath: target.skillPath, rootSha: tree.rootSha })
+          : null;
+        if (!treeSha) {
+          logger('git.error', { name: target.name, kind: 'no-tree-entry', purpose: 'baseline' });
+          continue;
+        }
+        store.update((draft) => {
+          const row = draft.installs.find((item) => item.name === target.name);
+          if (row && !row.treeSha) row.treeSha = treeSha;
+        });
+        updated.push({ name: target.name, treeSha });
+      }
+      if (updated.length > 0) logger('git.baseline', { source, ref: useRef, updated, ms: Date.now() - startedAt });
+      return updated;
+    } catch (error) {
+      logger('git.error', {
+        source,
+        kind: error.kind || 'clone-failed',
+        message: error.message,
+        purpose: 'baseline',
+      });
+      return [];
+    }
+  }
+
+  function recordLink(name, target, linkPath, mode, created) {    if (store.readOnly) return;
     const existing = state().links.find((item) => item.skill === name && item.target === target.target);
     if (existing) return;
     if (!created) return;
@@ -369,6 +616,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
           skillPath: record.skillPath,
           ref: record.ref,
           commit: null,
+          treeSha: null,
           installedHash: record.installedHash,
           installedAt: nowIso(),
           updatedAt: nowIso(),
@@ -617,10 +865,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
     async install({ source, subscriptionId, skills = [], commit, targets, scopeProjects = [] }) {
       assertWritable();
-      const capabilities = await cli.capabilities();
-      if (!capabilities.usable) {
-        throw new ServiceError('error.skills.cli-missing', 'skills CLI 不可用或不支持 --json/--full-depth，写操作已禁用', capabilities);
-      }
+      await requireUsableCli();
       // 技能名可留空：有订阅快照就装快照里的条目，否则交给 CLI 的 `--skill '*'`（整仓全部）
       const requested = (skills || []).filter(Boolean);
 
@@ -639,12 +884,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
         const result = await cli.add({ source: sourceArg, skills: planned });
         if (result.timedOut) throw new ServiceError('error.skills.cli-timeout', 'skills add 超时');
-        if (result.code !== 0) {
-          throw new ServiceError('error.skills.cli-failed', 'skills add 失败', {
-            code: result.code,
-            stderr: result.stderr.slice(-2000),
-          });
-        }
+        if (result.code !== 0) throw cliAddFailure(result, 'add');
         // 留空时实际装了哪些技能以 CLI 的 JSON 输出为准（可能不止一个）
         const names = planned.length > 0 ? planned : installedNamesFrom(result.stdout);
         if (names.length === 0) {
@@ -667,12 +907,16 @@ export function createService({ paths, store, registry, cli, logger, env = proce
             warnings.push({ name, warning: 'lock 里没有该技能的记录（来源形态不支持记账）' });
           }
           const expected = snapshot?.entries?.find((entry) => entry.name === name);
-          if (expected?.treeSha && lockEntry?.skillFolderHash && lockEntry.skillFolderHash !== expected.treeSha) {
+          const lockHash = lockEntry?.skillFolderHash || null;
+          const shape = hashShape(lockHash);
+          // 只有两边都是 40 位 tree SHA 才有可比性。限流安装时 CLI 写的是 64 位内容哈希
+          // （add.ts:2254），拿它比 tree SHA 必然不等 —— 那是形态问题，不是装错了。
+          if (expected?.treeSha && shape === 'tree' && hashShape(expected.treeSha) === 'tree' && lockHash !== expected.treeSha) {
             warnings.push({
               name,
               warning: 'lock 的 skillFolderHash 与快照 treeSha 不一致（可能装到了别的 commit）',
               expected: expected.treeSha,
-              actual: lockEntry.skillFolderHash,
+              actual: lockHash,
             });
           }
           const installedHash = fs.statSync(canonicalPath).isDirectory() ? contentHash(canonicalPath) : null;
@@ -682,6 +926,8 @@ export function createService({ paths, store, registry, cli, logger, env = proce
             skillPath: lockEntry?.skillPath || expected?.skillPath || `${name}/SKILL.md`,
             ref: pin,
             commit: snapshot?.commit || null,
+            // 安装那一刻的 tree 基线：lock 被写成内容哈希时，更新判定靠它（T2）
+            treeSha: expected?.treeSha || null,
             installedHash,
             installedAt: nowIso(),
             updatedAt: nowIso(),
@@ -694,7 +940,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
             if (index >= 0) draft.installs[index] = { ...draft.installs[index], ...record, installedAt: draft.installs[index].installedAt };
             else draft.installs.push(record);
           });
-          installed.push({ name, lockHash: lockEntry?.skillFolderHash || null, installedHash });
+          installed.push({ name, lockHash, lockHashShape: shape, installedHash });
         }
 
         const linkTargets = Array.isArray(targets) && targets.length > 0 ? targets : defaultTargets(state());
@@ -706,6 +952,14 @@ export function createService({ paths, store, registry, cli, logger, env = proce
           linkResult.failed.push(...one.failed);
         }
 
+        // T3.7：lock 被写成 64 位内容哈希形态（限流安装）时用 git 补一条 tree 基线，
+        // 否则「手填技能名」装出来的技能在更新检查里只能是 unknown。
+        const baselines = await backfillBaselines({ names, source: resolvedSource, lock, ref: pin });
+        for (const item of installed) {
+          const filled = baselines.find((row) => row.name === item.name);
+          if (filled) item.treeSha = filled.treeSha;
+        }
+
         logger('install', { source: sourceArg, skills: names, installed: installed.length });
         return {
           ok: true,
@@ -719,6 +973,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
     async remove({ name }) {
       assertWritable();
+      await requireUsableCli(); // 快照与体检之前就拒绝，避免留下孤儿 trash
       return enqueue(`remove:${name}`, async () => {
         const canonicalPath = path.join(paths.canonical, name);
         if (!fs.existsSync(canonicalPath)) {
@@ -793,19 +1048,30 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       if (cached && (cached.pending || Date.now() - cached.at < PROBE_TTL_MS)) {
         return cached.pending || cached.value;
       }
-      const pending = readSnapshot(
-        {
-          id: null,
+      const pending = (async () => {
+        // 优先 git（零配额）；不启用 / 不可用 / 失败都回落到原 REST 路径
+        const viaGit = await probeViaGit({
           source: canonicalSource,
           ref: requestedRef,
           subpath: requestedSubpath,
-          snapshot: null,
-        },
-        { force: true, withCommit: false },
-      ).then(async (probe) => {
+        });
+        const probe =
+          viaGit ||
+          (await readSnapshot(
+            {
+              id: null,
+              source: canonicalSource,
+              ref: requestedRef,
+              subpath: requestedSubpath,
+              snapshot: null,
+            },
+            { force: true, withCommit: false },
+          ));
+        // 描述优先按 commit 抓（不可变、可缓存），没有 commit 再退回分支名
+        const enrichRef = probe.snapshot?.commit || probe.branch;
         const enriched = await enrichSkillEntries({
           source: canonicalSource,
-          ref: probe.branch,
+          ref: enrichRef,
           entries: probe.snapshot.entries,
           token: tokenOf,
           fetchImpl,
@@ -817,10 +1083,11 @@ export function createService({ paths, store, registry, cli, logger, env = proce
           ok: true,
           source: canonicalSource,
           ref: probe.branch,
+          via: probe.via || 'rest',
           skills,
           skipped: enriched.length - skills.length,
         };
-      });
+      })();
       probeCache.set(key, { pending, at: Date.now() });
       try {
         const value = await pending;
@@ -930,6 +1197,22 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       assertWritable();
       const subscription = state().subscriptions.find((item) => item.id === id);
       if (!subscription) throw new ServiceError('error.skills.no-subscription', '订阅不存在');
+      // T4 短路：最常见的情况是「什么都没变」。先用 ls-remote 比 commit，一致就一次 REST 都不发。
+      if (await remoteCommitUnchanged(subscription)) {
+        const at = nowIso();
+        store.update((draft) => {
+          const row = draft.subscriptions.find((item) => item.id === id);
+          if (row) row.lastCheck = { ...(row.lastCheck || {}), at, status: 'unchanged' };
+        });
+        logger('subscription.refresh', { id, notModified: true, via: 'git' });
+        return {
+          ok: true,
+          changed: false,
+          notModified: true,
+          via: 'git',
+          subscription: state().subscriptions.find((item) => item.id === id),
+        };
+      }
       let probe;
       try {
         probe = await readSnapshot(subscription, { force });
@@ -961,6 +1244,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
         ok: true,
         changed: !probe.notModified && probe.changed,
         ...(probe.notModified ? { notModified: true } : {}),
+        via: probe.via || 'rest',
         subscription: state().subscriptions.find((item) => item.id === id),
       };
     },
@@ -983,22 +1267,24 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
       const results = [];
       for (const { subscription, installs: groupInstalls } of groups.values()) {
-        // 没写 ref 的订阅（旧版本/接管建的）按仓库默认分支检查，别硬套 main
-        const ref = (await branchOf(subscription, { persist: true })) || 'main';
-        const tree = await fetchTree({
-          source: subscription.source,
-          ref,
-          etag: subscription.snapshot?.etag || null,
-          token: tokenOf,
-          fetchImpl,
-        });
-        if (tree.error) {
+        // T4：与 readSnapshot 同一套语义 —— 限流 / 404 时先试 git，都失败才逐个标 unknown
+        // withCommit: false：判定只需要树，别为 check 多付一次 /commits 请求
+        let probe;
+        try {
+          probe = await readSnapshot(subscription, { withCommit: false, persistRef: true });
+        } catch (error) {
           for (const install of groupInstalls) {
-            results.push({ name: install.name, status: 'unknown', detail: tree.error, checkedAt: nowIso() });
+            results.push({
+              name: install.name,
+              status: 'unknown',
+              detail: error.message,
+              code: error.code || null,
+              checkedAt: nowIso(),
+            });
           }
           continue;
         }
-        if (tree.notModified) {
+        if (probe.notModified) {
           for (const install of groupInstalls) {
             const previousCheck = state().checks?.[install.name];
             results.push({
@@ -1012,16 +1298,17 @@ export function createService({ paths, store, registry, cli, logger, env = proce
         }
         for (const install of groupInstalls) {
           const skillPath = lock.skills?.[install.name]?.skillPath || install.skillPath;
-          const entry = tree.tree.some((item) => item.type === 'blob' && item.path === skillPath)
+          const entry = probe.tree.some((item) => item.type === 'blob' && item.path === skillPath)
             ? { skillPath }
             : null;
           const verdict = checkSkill({
             lockHash: lock.skills?.[install.name]?.skillFolderHash || null,
+            recordedTreeSha: install.treeSha ?? null,
             snapshotEntry: entry,
-            tree: tree.tree,
-            rootSha: tree.rootSha,
+            tree: probe.tree,
+            rootSha: probe.rootSha,
           });
-          results.push({ name: install.name, ...verdict, checkedAt: nowIso() });
+          results.push({ name: install.name, ...verdict, via: probe.via, checkedAt: nowIso() });
         }
       }
 
@@ -1049,20 +1336,15 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       if (!install) throw new ServiceError('error.skills.not-managed', `${name} 没有安装记录`);
       const subscription = state().subscriptions.find((item) => item.id === install.subscriptionId);
       if (!subscription) throw new ServiceError('error.skills.no-subscription', '该技能不属于任何订阅，无法生成更新计划');
-      const ref = (await branchOf(subscription)) || 'main';
-      const tree = await fetchTree({
-        source: subscription.source,
-        ref,
-        token: tokenOf,
-        fetchImpl,
-      });
-      if (tree.error) throw new ServiceError('error.skills.upstream-failed', tree.error);
+      // 与 checkUpdates 共用一套取数语义：限流时同样能靠 git 出计划（否则「查得到更新却更不了」）
+      const probe = await readSnapshot(subscription, { force: true });
+      const ref = probe.branch;
       const lock = readLock(paths);
       const skillPath = lock.skills?.[name]?.skillPath || install.skillPath;
-      const entry = tree.tree.find((item) => item.type === 'blob' && item.path === skillPath);
+      const entry = probe.tree.find((item) => item.type === 'blob' && item.path === skillPath);
       if (!entry) throw new ServiceError('error.skills.upstream-deleted', '上游已移除该技能');
-      const targetTreeSha = skillTreeSha({ tree: tree.tree, skillPath, rootSha: tree.rootSha });
-      const targetCommit = await resolveCommit({ source: subscription.source, ref, token: tokenOf, fetchImpl });
+      const targetTreeSha = skillTreeSha({ tree: probe.tree, skillPath, rootSha: probe.rootSha });
+      const targetCommit = probe.snapshot?.commit ?? null;
       const token = planToken({
         subscriptionId: subscription.id,
         from: install.commit || null,
@@ -1086,6 +1368,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
     async applyUpdate({ name, token, overwrite = false }) {
       assertWritable();
+      await requireUsableCli();
       return enqueue(`apply:${name}`, async () => {
         const plan = await this.planUpdate({ name });
         if (token && token !== plan.token) {
@@ -1116,12 +1399,21 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
         if (result.code !== 0 || !present || !verified) {
           if (backup) restoreBackup({ backup, toDir: canonicalPath });
+          const failure = result.code !== 0 ? cliAddFailure(result, 'add') : null;
+          const gitMissing = failure?.code === 'error.skills.git-missing';
           logger('updates.apply.failed', { name, code: result.code, verified, present });
+          const suffix = backup ? '；已回滚到上一版' : '；没有可回滚的备份';
           return {
             ok: false,
-            code: 'error.skills.update-failed',
-            message: backup ? '更新失败，已回滚到上一版' : '更新失败，没有可回滚的备份',
-            detail: { cliCode: result.code, verified, present, stderr: result.stderr.slice(-2000) },
+            code: gitMissing ? failure.code : 'error.skills.update-failed',
+            message: gitMissing ? `${failure.message}${suffix}` : `更新失败${suffix}`,
+            detail: {
+              cliCode: result.code,
+              verified,
+              present,
+              stderr: (result.stderr || '').slice(-2000),
+              ...(failure?.detail || {}),
+            },
             backup: backup?.key || null,
           };
         }
@@ -1131,9 +1423,11 @@ export function createService({ paths, store, registry, cli, logger, env = proce
           const row = draft.installs.find((item) => item.name === name);
           if (!row) return;
           row.commit = plan.toCommit;
+          // 更新后基线跟着走：lock 若仍是内容哈希形态，下一次判定要用新的 tree SHA
+          row.treeSha = plan.targetTreeSha || row.treeSha || null;
           row.installedHash = installedHash;
           row.updatedAt = nowIso();
-          row.backup = backup ? { key: backup.key, hash: install.installedHash || null } : row.backup;
+          row.backup = backup ? { key: backup.key, hash: install.installedHash || null, treeSha: install.treeSha ?? null } : row.backup;
           draft.checks[name] = { name, status: 'current', detail: null, wouldCommit: null, checkedAt: nowIso(), installCommit: plan.toCommit };
         });
 
@@ -1160,6 +1454,8 @@ export function createService({ paths, store, registry, cli, logger, env = proce
           row.installedHash = installedHash;
           row.updatedAt = nowIso();
           row.commit = null;
+          // 回滚回去的是备份那一刻的内容，tree 基线也得跟着退回去（不知道就置空，绝不沿用新版）
+          row.treeSha = install.backup.treeSha ?? null;
           draft.checks[name] = { name, status: 'unknown', detail: '已回滚，需重新检查', checkedAt: nowIso() };
         });
         logger('updates.rollback', { name, backup: install.backup.key });

package/lib/core/updates.js

@@ -25,6 +25,27 @@ export function githubToken(env = process.env) {
   return env.GITHUB_TOKEN || env.GH_TOKEN || null;
 }
 
+/**
+ * 限流相关响应头。GitHub 对匿名请求按**出口 IP** 记 60 次/小时，403 时这三个头是
+ * 用户唯一能拿到的可执行信息（还剩多少、什么时候恢复、要不要等）。
+ */
+function rateLimitOf(response) {
+  const read = (name) => {
+    const value = response?.headers?.get?.(name);
+    return value === null || value === undefined || value === '' ? null : String(value);
+  };
+  const reset = read('x-ratelimit-reset');
+  const retryAfter = read('retry-after');
+  const resetAt = reset && /^\d+$/.test(reset) ? Number(reset) * 1000 : null;
+  return { remaining: read('x-ratelimit-remaining'), resetAt, retryAfter };
+}
+
+/** 403 + 剩余 0，或 429 —— 与上游判定一致（blob.ts:147-152）。 */
+export function isRateLimited(status, rateLimit) {
+  if (status === 429) return true;
+  return status === 403 && rateLimit?.remaining === '0';
+}
+
 async function callJson(url, { token, etag, fetchImpl = fetch } = {}) {
   const headers = {
     accept: 'application/vnd.github+json',
@@ -34,13 +55,14 @@ async function callJson(url, { token, etag, fetchImpl = fetch } = {}) {
   if (token) headers.authorization = `Bearer ${token}`;
   if (etag) headers['if-none-match'] = etag;
   const response = await fetchImpl(url, { headers });
-  if (response.status === 304) return { status: 304, notModified: true, etag };
+  const rateLimit = rateLimitOf(response);
+  if (response.status === 304) return { status: 304, notModified: true, etag, rateLimit };
   if (!response.ok) {
     const text = await response.text().catch(() => '');
-    return { status: response.status, error: `HTTP ${response.status} ${text.slice(0, 200)}` };
+    return { status: response.status, error: `HTTP ${response.status} ${text.slice(0, 200)}`, rateLimit };
   }
   const body = await response.json();
-  return { status: response.status, body, etag: response.headers.get('etag') };
+  return { status: response.status, body, etag: response.headers.get('etag'), rateLimit };
 }
 
 /**
@@ -53,7 +75,15 @@ export async function fetchTree({ source, ref = 'main', etag, token, fetchImpl }
   const url = `${API}/repos/${parsed.owner}/${parsed.repo}/git/trees/${encodeURIComponent(ref)}?recursive=1`;
   const result = await callJson(url, { token, etag, fetchImpl });
   if (result.notModified) return { notModified: true, etag: result.etag };
-  if (result.error) return { error: result.error, status: result.status };
+  if (result.error) {
+    return {
+      error: result.error,
+      status: result.status,
+      rateLimited: isRateLimited(result.status, result.rateLimit),
+      resetAt: result.rateLimit?.resetAt ?? null,
+      rateLimit: result.rateLimit,
+    };
+  }
   const tree = Array.isArray(result.body?.tree) ? result.body.tree : [];
   return {
     tree,
@@ -67,13 +97,28 @@ export async function fetchTree({ source, ref = 'main', etag, token, fetchImpl }
 /**
  * 仓库默认分支。`ref` 缺省时以它为准：不少技能仓库默认是 `master`，
  * 硬套 `main` 只会得到 404（例如 alchaincyf/huashu-design）。
+ *
+ * 返回结构化结果而不是 `string | null`：调用方要靠 `status` / `rateLimited` / `resetAt`
+ * 把「仓库不存在」「被限流」「网络不通」拆成三句不同的话（T1）。
  */
 export async function fetchDefaultBranch({ source, token, fetchImpl } = {}) {
   const parsed = parseSource(source);
-  if (!parsed) return null;
-  const result = await callJson(`${API}/repos/${parsed.owner}/${parsed.repo}`, { token, fetchImpl });
-  if (result.error || !result.body?.default_branch) return null;
-  return result.body.default_branch;
+  if (!parsed) {
+    return { branch: null, status: null, rateLimited: false, resetAt: null, error: 'invalid-source' };
+  }
+  let result;
+  try {
+    result = await callJson(`${API}/repos/${parsed.owner}/${parsed.repo}`, { token, fetchImpl });
+  } catch (error) {
+    return { branch: null, status: null, rateLimited: false, resetAt: null, error: error?.message || String(error) };
+  }
+  const rateLimit = result.rateLimit || {};
+  const rateLimited = isRateLimited(result.status, rateLimit);
+  const base = { status: result.status ?? null, rateLimited, resetAt: rateLimit.resetAt ?? null };
+  if (result.error) return { ...base, branch: null, error: result.error };
+  const branch = result.body?.default_branch;
+  if (!branch) return { ...base, branch: null, error: 'response has no default_branch' };
+  return { ...base, branch, error: null };
 }
 
 /** 解析 ref 对应的 commit（只在安装/计划时需要，检测阶段不付这笔成本）。 */
@@ -88,6 +133,18 @@ export async function resolveCommit({ source, ref = 'main', token, fetchImpl } =
   return result.body.sha;
 }
 
+const TREE_SHA_RE = /^[0-9a-f]{40}$/;
+
+/**
+ * lock 的 `skillFolderHash` 形态。CLI 取不到树时（限流）会把 64 位内容哈希写进同一个字段
+ * （`add.ts:2254`），所以形态取决于**安装那一刻 API 通不通**，不是取决于来源类型。
+ * `tree` = 40 位 git tree SHA；`content` = 64 位内容哈希；`missing` = 没有这个字段。
+ */
+export function hashShape(value) {
+  if (!value || typeof value !== 'string') return 'missing';
+  return TREE_SHA_RE.test(value) ? 'tree' : 'content';
+}
+
 /** `KEY` + `/dir/SKILL.md` → `dir`（F18：`skillPath` 是文件路径，目录运算先 dirname）。 */
 export function skillDir(skillPath) {
   const parts = String(skillPath).split('/');
@@ -126,22 +183,41 @@ export function listSkillsFromTree({ tree, rootSha, subpath, repoName }) {
 }
 
 /**
- * 单技能判定（L2/L3）。哈希形态必须配对（F19）：
- * `sourceType=github` 时 lock 里应是 40 位 tree SHA；64 位内容哈希说明来源形态不对，直接给 `unknown`。
+ * 单技能判定（L2/L3）。
+ *
+ * 基线取「第一个 40 位 tree SHA」：优先 lock 的 `skillFolderHash`，其次安装时记下的
+ * `state.installs[].treeSha`。CLI 在限流时会退化成 64 位内容哈希（`add.ts:2236`/`2254`），
+ * 那玩意儿与上游 tree SHA 不同源，直接比必然不等 —— 既不能判 `current`，也不该判
+ * `update-available`，此时改用手边记下的基线；两样都没有才给 `unknown`（老状态，行为与以前一致）。
  */
-export function checkSkill({ lockHash, snapshotEntry, tree, rootSha }) {
+export function checkSkill({ lockHash, recordedTreeSha, snapshotEntry, tree, rootSha }) {
   if (!snapshotEntry) return { status: 'upstream-deleted', detail: '上游整树里已找不到这个 skillPath' };
-  if (!lockHash) return { status: 'unknown', detail: 'lock 里没有 skillFolderHash' };
-  if (!/^[0-9a-f]{40}$/.test(lockHash)) {
+  const baseline = TREE_SHA_RE.test(String(lockHash || ''))
+    ? { sha: lockHash, from: 'lock' }
+    : TREE_SHA_RE.test(String(recordedTreeSha || ''))
+      ? { sha: recordedTreeSha, from: 'recorded' }
+      : null;
+  if (!baseline) {
     return {
       status: 'unknown',
-      detail: 'lock 的哈希不是 40 位 tree SHA（形态不配对），无法按 tree 比对',
+      detail: 'lock 里没有 40 位 tree SHA，安装时也未记录基线，无法按 tree 比对',
     };
   }
   const target = skillTreeSha({ tree, skillPath: snapshotEntry.skillPath, rootSha });
   if (!target) return { status: 'unknown', detail: '整树里找不到该目录的 tree 条目' };
-  if (target === lockHash) return { status: 'current', detail: '与安装时的 tree SHA 一致' };
-  return { status: 'update-available', detail: 'tree SHA 已变化', targetTreeSha: target };
+  if (target === baseline.sha) {
+    return {
+      status: 'current',
+      detail: baseline.from === 'lock' ? '与安装时的 tree SHA 一致' : '与安装时记录的 tree SHA 一致',
+      baseline: baseline.from,
+    };
+  }
+  return {
+    status: 'update-available',
+    detail: `tree SHA 已变化（基线来自 ${baseline.from}）`,
+    targetTreeSha: target,
+    baseline: baseline.from,
+  };
 }
 
 /** 计划 → 应用的防换手 token：磁盘或上游在"计划"之后被改动就拒绝（设计 §7.4③）。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morehao/dsh-skills-console",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "统一管理本地技能的安装、更新、删除与接入，让同一份技能在多个 Agent 间复用。A skill manager for DeepSeek Harness: install, update, remove, link and toggle agent skills.",
   "license": "MIT",
   "author": "morehao <morehao@qq.com>",
@@ -68,6 +68,9 @@
     "dsh-plugin",
     "skills"
   ],
+  "dependencies": {
+    "skills": "1.7.4"
+  },
   "devDependencies": {
     "esbuild": "0.28.2"
   }