@morehao/dsh-skills-console 0.2.1 → 0.2.3

package/lib/core/service.js

@@ -2,12 +2,15 @@ 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';
 import {
   checkSkill,
+  fetchDefaultBranch,
   fetchTree,
+  hashShape,
   listSkillsFromTree,
   parseSource,
   planToken,
@@ -30,6 +33,118 @@ function nowIso() {
   return new Date().toISOString();
 }
 
+/** 本机时区的 `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 {
+    const parsed = JSON.parse(stdout);
+    const rows = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.installed) ? parsed.installed : [];
+    const names = rows.map((row) => (typeof row === 'string' ? row : row?.name)).filter(Boolean);
+    return [...new Set(names)];
+  } catch {
+    return [];
+  }
+}
+
+/** 极简 frontmatter 解析：只取 CLI 安装必需的两项（name / description）。 */
+function parseSkillFrontmatter(text) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(String(text || ''));
+  if (!match) return {};
+  const lines = match[1].split(/\r?\n/);
+  const fields = {};
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line || /^\s/.test(line)) continue;
+    const colon = line.indexOf(':');
+    if (colon <= 0) continue;
+    const key = line.slice(0, colon).trim();
+    if (key !== 'name' && key !== 'description') continue;
+    let value = line.slice(colon + 1).trim();
+    const block = /^([|>])[+-]?$/.exec(value);
+    if (block) {
+      const folded = block[1] === '>';
+      const rows = [];
+      while (index + 1 < lines.length && /^\s+/.test(lines[index + 1])) {
+        rows.push(lines[index + 1].replace(/^\s+/, ''));
+        index += 1;
+      }
+      value = folded ? rows.join(' ') : rows.join('\n');
+    } else if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      const quote = value[0];
+      value = value.slice(1, -1);
+      if (quote === '"') value = value.replace(/\\"/g, '"').replace(/\\n/g, '\n');
+    }
+    fields[key] = value.trim();
+  }
+  return fields;
+}
+
+/** 用 raw 内容补 frontmatter 里的真实技能名/描述（CLI 按 name 安装）；取不到就回落目录名。 */
+async function enrichSkillEntries({ source, ref, entries, token, fetchImpl, concurrency = 8 }) {
+  const results = new Array(entries.length);
+  let cursor = 0;
+  const worker = async () => {
+    while (cursor < entries.length) {
+      const index = cursor;
+      cursor += 1;
+      results[index] = await inspectSkillEntry({ source, ref, entry: entries[index], token, fetchImpl });
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, entries.length) }, worker));
+  return results;
+}
+
+async function inspectSkillEntry({ source, ref, entry, token, fetchImpl }) {
+  const fallback = { name: entry.name, description: '', skillPath: entry.skillPath, valid: true };
+  try {
+    const url = `https://raw.githubusercontent.com/${source}/${ref}/${entry.skillPath.split('/').map(encodeURIComponent).join('/')}`;
+    const response = await fetchImpl(url, {
+      headers: { 'user-agent': 'dsh-skills-console', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+    });
+    if (!response?.ok) return fallback;
+    const fields = parseSkillFrontmatter(await response.text());
+    // CLI 要求 name + description 都在，缺一个就整个跳过：这里同步标成 invalid，别让用户选了才发现装不上
+    if (!fields.name || !fields.description) return { ...fallback, valid: false };
+    return { name: fields.name, description: fields.description, skillPath: entry.skillPath, valid: true };
+  } catch {
+    return fallback;
+  }
+}
+
 /** 写操作全局单写者队列：`add` 会同时改 canonical 与 lock，按技能分桶没有意义（设计 §14.3）。 */
 function createQueue(logger) {
   let chain = Promise.resolve();
@@ -63,6 +178,11 @@ 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;
+  const PROBE_MAX = 50;
 
   function state() {
     return store.state;
@@ -121,8 +241,267 @@ export function createService({ paths, store, registry, cli, logger, env = proce
     return { created, skipped, failed };
   }
 
-  function recordLink(name, target, linkPath, mode, created) {
-    if (store.readOnly) return;
+  /**
+   * 订阅的分支：显式 ref > 记录里的 ref > 仓库默认分支。解析成功后顺手记住，省掉下次请求。
+   * 返回 `{ branch, failure }`：`failure` 原样透出 `fetchDefaultBranch` 的结构化失败，
+   * 由 `readSnapshot` 决定报哪种错误（T1）。
+   */
+  async function branchOf(subscription, { persist = false } = {}) {
+    if (subscription.ref) return { branch: subscription.ref, failure: null };
+    let resolved;
+    try {
+      resolved = await fetchDefaultBranch({
+        source: subscription.source,
+        token: tokenOf,
+        fetchImpl,
+      });
+    } catch (error) {
+      return { branch: null, failure: { status: null, rateLimited: false, resetAt: null, error: error?.message || String(error) } };
+    }
+    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, failure: null };
+  }
+
+  /**
+   * 读一次订阅快照：只有网络与纯计算，**不写 store**（`persistRef` 例外，只补订阅的 ref）。
+   * 上游失败一律抛 ServiceError —— 添加订阅必须先读到快照再记账，
+   * 否则会留下「订阅存在但一个 skill 都没有」的空壳（上游 404 时还会显示添加成功）。
+   *
+   * T4：REST 因**限流**或 **404** 失败时先试 git（零配额）；git 也不行才抛 T1 的错误。
+   */
+  async function readSnapshot(subscription, { force = false, withCommit = true, persistRef = false } = {}) {
+    const source = subscription.source;
+    try {
+      const { branch, failure } = await branchOf(subscription, { persist: persistRef });
+      if (!branch) {
+        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,
+        ref: branch,
+        etag: force ? null : subscription.snapshot?.etag || null,
+        token: tokenOf,
+        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,
+          status: result.status ?? null,
+        });
+      }
+      if (result.notModified) return { notModified: true, branch };
+      const entries = listSkillsFromTree({
+        tree: result.tree,
+        rootSha: result.rootSha,
+        subpath: subscription.subpath,
+        repoName: source.split('/').pop(),
+      });
+      const previousRoot = subscription.snapshot?.rootSha || null;
+      // 探测只需要文件树，不付 resolveCommit 那一次请求
+      const commit = !withCommit
+        ? null
+        : previousRoot && previousRoot === result.rootSha && subscription.snapshot?.commit
+          ? subscription.snapshot.commit
+          : await resolveCommit({ source, ref: branch, token: tokenOf, fetchImpl });
+      const changed =
+        !subscription.snapshot ||
+        previousRoot !== result.rootSha ||
+        JSON.stringify(entries) !== JSON.stringify(subscription.snapshot.entries);
+      return {
+        branch,
+        changed,
+        via: 'rest',
+        tree: result.tree,
+        rootSha: result.rootSha,
+        snapshot: { commit, rootSha: result.rootSha, entries, fetchedAt: nowIso(), etag: result.etag },
+      };
+    } catch (error) {
+      if (error instanceof ServiceError) throw error;
+      throw new ServiceError('error.skills.upstream-failed', `读取 ${source} 失败：${error?.message || error}`, {
+        source,
+      });
+    }
+  }
+
+  /**
+   * 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;
@@ -203,6 +582,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(),
@@ -455,8 +835,8 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       if (!capabilities.usable) {
         throw new ServiceError('error.skills.cli-missing', 'skills CLI 不可用或不支持 --json/--full-depth，写操作已禁用', capabilities);
       }
-      const names = (skills || []).filter(Boolean);
-      if (names.length === 0) throw new ServiceError('error.skills.bad-request', 'skills 不能为空');
+      // 技能名可留空：有订阅快照就装快照里的条目，否则交给 CLI 的 `--skill '*'`（整仓全部）
+      const requested = (skills || []).filter(Boolean);
 
       return enqueue('install', async () => {
         const subscription = subscriptionId
@@ -467,10 +847,11 @@ export function createService({ paths, store, registry, cli, logger, env = proce
         if (!parseSource(resolvedSource)) throw new ServiceError('error.skills.bad-source', '只接受 owner/repo 或 GitHub URL（公开源）');
 
         const snapshot = subscription?.snapshot || null;
+        const planned = requested.length > 0 ? requested : (snapshot?.entries || []).map((entry) => entry.name);
         const pin = commit || snapshot?.commit || subscription?.ref || null;
         const sourceArg = pin ? `${resolvedSource}#${pin}` : resolvedSource;
 
-        const result = await cli.add({ source: sourceArg, skills: names });
+        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 失败', {
@@ -478,6 +859,13 @@ export function createService({ paths, store, registry, cli, logger, env = proce
             stderr: result.stderr.slice(-2000),
           });
         }
+        // 留空时实际装了哪些技能以 CLI 的 JSON 输出为准（可能不止一个）
+        const names = planned.length > 0 ? planned : installedNamesFrom(result.stdout);
+        if (names.length === 0) {
+          throw new ServiceError('error.skills.cli-failed', 'skills add 成功，但输出里没有安装结果，无法记账', {
+            stdout: result.stdout.slice(-2000),
+          });
+        }
 
         const lock = readLock(paths);
         const installed = [];
@@ -493,12 +881,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;
@@ -508,6 +900,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(),
@@ -520,7 +914,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());
@@ -532,6 +926,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,
@@ -605,26 +1007,148 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       });
     },
 
+    /** 只读探测来源里的 SKILL.md，供「添加技能」多选；不写 state、不建订阅。 */
+    async probeSource({ source, ref, subpath }) {
+      const parsed = parseSource(source);
+      if (!parsed) throw new ServiceError('error.skills.bad-source', '只接受 owner/repo 或 GitHub URL（公开源）');
+      const canonicalSource = `${parsed.owner}/${parsed.repo}`;
+      const requestedRef = typeof ref === 'string' && ref.trim() ? ref.trim() : null;
+      const requestedSubpath = typeof subpath === 'string' && subpath.trim()
+        ? subpath.trim().replace(/^\/+|\/+$/g, '') || null
+        : null;
+      const key = `${canonicalSource}@${requestedRef || ''}#${requestedSubpath || ''}`;
+      const cached = probeCache.get(key);
+      if (cached && (cached.pending || Date.now() - cached.at < PROBE_TTL_MS)) {
+        return cached.pending || cached.value;
+      }
+      const pending = (async () => {
+        // 优先 git（零配额）；不启用 / 不可用 / 失败都回落到原 REST 路径
+        const viaGit = await probeViaGit({
+          source: canonicalSource,
+          ref: requestedRef,
+          subpath: requestedSubpath,
+        });
+        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: enrichRef,
+          entries: probe.snapshot.entries,
+          token: tokenOf,
+          fetchImpl,
+        });
+        const skills = enriched
+          .filter((skill) => skill.valid)
+          .map(({ name, description, skillPath }) => ({ name, description, skillPath }));
+        return {
+          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;
+        probeCache.set(key, { value, at: Date.now() });
+        for (const oldest of probeCache.keys()) {
+          if (probeCache.size <= PROBE_MAX) break;
+          probeCache.delete(oldest);
+        }
+        return value;
+      } catch (error) {
+        // 失败不留缓存，用户改一下来源或重试就能重新探测
+        probeCache.delete(key);
+        throw error;
+      }
+    },
+
     async addSubscription({ source, ref, subpath, skills = '*' }) {
       assertWritable();
       const parsed = parseSource(source);
       if (!parsed) throw new ServiceError('error.skills.bad-source', '订阅只接受 owner/repo 或 GitHub URL');
-      const id = snapshotId({ source, ref, subpath });
-      const existing = state().subscriptions.find((item) => item.id === id);
-      if (existing) return { ok: true, subscription: existing, existing: true };
-      const record = {
-        id,
-        source: `${parsed.owner}/${parsed.repo}`,
-        ref: ref || null,
-        subpath: subpath || null,
+      const canonicalSource = `${parsed.owner}/${parsed.repo}`;
+      const requestedRef = typeof ref === 'string' && ref.trim() ? ref.trim() : null;
+      const requestedSubpath = typeof subpath === 'string' && subpath.trim()
+        ? subpath.trim().replace(/^\/+|\/+$/g, '') || null
+        : null;
+      const id = snapshotId({ source: canonicalSource, ref: requestedRef, subpath: requestedSubpath });
+      // 老记录可能用 URL / 原始字符串算过 id：按来源+ref+子目录再找一遍，避免同一仓库出现两条订阅
+      const existing =
+        state().subscriptions.find((item) => item.id === id) ||
+        state().subscriptions.find(
+          (item) =>
+            item.source === canonicalSource &&
+            (item.ref || null) === requestedRef &&
+            (item.subpath || null) === requestedSubpath,
+        );
+      // 已有快照的重复添加直接返回；空壳（旧版本失败留下的）要走一次真实拉取，成功后再补全
+      if (existing?.snapshot) return { ok: true, subscription: existing, existing: true };
+
+      const candidate = {
+        id: existing?.id || id,
+        source: canonicalSource,
+        ref: requestedRef || existing?.ref || null,
+        subpath: requestedSubpath,
         skills,
         lastCheck: null,
         snapshot: null,
       };
+
+      // 先读快照再落盘：上游失败时 state 里不能留下订阅，接口也必须如实报错
+      const probe = await readSnapshot(candidate, { force: true });
+      // 一条 skill 都没有 = 订阅了也没东西可装（多半是 subpath/ref 写错），同样不能算添加成功
+      if (probe.snapshot.entries.length === 0) {
+        throw new ServiceError(
+          'error.skills.no-skills',
+          `${canonicalSource}@${probe.branch}${requestedSubpath ? `/${requestedSubpath}` : ''} 里没有找到 SKILL.md`,
+          { source: canonicalSource, ref: probe.branch, subpath: requestedSubpath },
+        );
+      }
+
+      const record = {
+        ...candidate,
+        ...(existing?.adopted ? { adopted: true } : {}),
+        ref: probe.branch,
+        snapshot: probe.snapshot,
+        lastCheck: {
+          at: nowIso(),
+          commit: probe.snapshot.commit,
+          treeEtag: probe.snapshot.etag,
+          status: 'changed',
+        },
+      };
       store.update((draft) => {
-        draft.subscriptions.push(record);
+        const index = draft.subscriptions.findIndex((item) => item.id === record.id);
+        if (index >= 0) draft.subscriptions[index] = { ...draft.subscriptions[index], ...record };
+        else draft.subscriptions.push(record);
+      });
+      logger('subscription.add', {
+        id: record.id,
+        source: record.source,
+        ref: record.ref,
+        entries: record.snapshot.entries.length,
       });
-      return { ok: true, subscription: record, ...(await this.refreshSubscription({ id, force: true })) };
+      return {
+        ok: true,
+        changed: true,
+        entries: record.snapshot.entries.length,
+        subscription: state().subscriptions.find((item) => item.id === record.id),
+      };
     },
 
     async removeSubscription({ id, keepInstalled = true }) {
@@ -646,55 +1170,56 @@ 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', '订阅不存在');
-      const ref = subscription.ref || 'main';
-      const previous = subscription.snapshot?.etag || null;
-      const result = await fetchTree({
-        source: subscription.source,
-        ref,
-        etag: force ? null : previous,
-        token: tokenOf,
-        fetchImpl,
-      });
-      if (result.error) {
+      // 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 = { at: nowIso(), status: 'unknown', detail: result.error };
+          if (row) row.lastCheck = { ...(row.lastCheck || {}), at, status: 'unchanged' };
         });
-        return { ok: false, code: 'error.skills.upstream-failed', message: result.error };
+        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),
+        };
       }
-      if (result.notModified) {
-        store.update((draft) => {
-          const row = draft.subscriptions.find((item) => item.id === id);
-          // 304 只刷新时间，绝不把 entries 置空
-          if (row) row.lastCheck = { ...(row.lastCheck || {}), at: nowIso(), status: 'unchanged' };
-        });
-        return { ok: true, notModified: true, subscription: state().subscriptions.find((item) => item.id === id) };
+      let probe;
+      try {
+        probe = await readSnapshot(subscription, { force });
+      } catch (error) {
+        // 失败留痕（清单里能看到 lastCheck），但接口必须报错，不能把失败伪装成成功
+        if (!store.readOnly) {
+          store.update((draft) => {
+            const row = draft.subscriptions.find((item) => item.id === id);
+            if (row) row.lastCheck = { at: nowIso(), status: 'unknown', detail: error.message };
+          });
+        }
+        throw error;
       }
-
-      const entries = listSkillsFromTree({
-        tree: result.tree,
-        rootSha: result.rootSha,
-        subpath: subscription.subpath,
-        repoName: subscription.source.split('/').pop(),
-      });
-      const previousRoot = subscription.snapshot?.rootSha || null;
-      const commit =
-        previousRoot && previousRoot === result.rootSha && subscription.snapshot?.commit
-          ? subscription.snapshot.commit
-          : await resolveCommit({ source: subscription.source, ref, token: tokenOf, fetchImpl });
-
-      const changed =
-        !subscription.snapshot ||
-        previousRoot !== result.rootSha ||
-        JSON.stringify(entries) !== JSON.stringify(subscription.snapshot.entries);
+      const at = nowIso();
       store.update((draft) => {
         const row = draft.subscriptions.find((item) => item.id === id);
         if (!row) return;
-        row.snapshot = { commit, rootSha: result.rootSha, entries, fetchedAt: nowIso(), etag: result.etag };
-        row.lastCheck = { at: nowIso(), commit, treeEtag: result.etag, status: changed ? 'changed' : 'unchanged' };
+        if (!row.ref && probe.branch) row.ref = probe.branch;
+        if (probe.notModified) {
+          // 304 只刷新时间，绝不把 entries 置空
+          row.lastCheck = { ...(row.lastCheck || {}), at, status: 'unchanged' };
+          return;
+        }
+        row.snapshot = probe.snapshot;
+        row.lastCheck = { at, commit: probe.snapshot.commit, treeEtag: probe.snapshot.etag, status: probe.changed ? 'changed' : 'unchanged' };
       });
-      logger('subscription.refresh', { id, entries: entries.length, changed });
-      return { ok: true, changed, subscription: state().subscriptions.find((item) => item.id === id) };
+      if (!probe.notModified) logger('subscription.refresh', { id, entries: probe.snapshot.entries.length, changed: probe.changed });
+      return {
+        ok: true,
+        changed: !probe.notModified && probe.changed,
+        ...(probe.notModified ? { notModified: true } : {}),
+        via: probe.via || 'rest',
+        subscription: state().subscriptions.find((item) => item.id === id),
+      };
     },
 
     async checkUpdates({ names, subscriptionId } = {}) {
@@ -708,27 +1233,31 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       for (const install of installs) {
         const subscription = state().subscriptions.find((item) => item.id === install.subscriptionId);
         if (!subscription) continue;
-        const key = `${subscription.source}#${subscription.ref || 'main'}`;
-        if (!groups.has(key)) groups.set(key, { subscription, installs: [] });
-        groups.get(key).installs.push(install);
+        // 按订阅（id 已含 source/ref/subpath）分组：不能用 `ref || 'main'` 当键，否则 null-ref 与 main 会撞车
+        if (!groups.has(subscription.id)) groups.set(subscription.id, { subscription, installs: [] });
+        groups.get(subscription.id).installs.push(install);
       }
 
       const results = [];
       for (const { subscription, installs: groupInstalls } of groups.values()) {
-        const tree = await fetchTree({
-          source: subscription.source,
-          ref: subscription.ref || 'main',
-          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({
@@ -742,16 +1271,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() });
         }
       }
 
@@ -779,19 +1309,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 tree = await fetchTree({
-        source: subscription.source,
-        ref: subscription.ref || 'main',
-        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: subscription.ref || 'main', 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,
@@ -806,6 +1332,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
         token,
         fromCommit: install.commit || null,
         toCommit: targetCommit,
+        ref,
         targetTreeSha,
         skillPath,
         localModified: Boolean(install.installedHash) && contentHash(path.join(paths.canonical, name)) !== install.installedHash,
@@ -833,7 +1360,9 @@ export function createService({ paths, store, registry, cli, logger, env = proce
           ? createBackup({ paths, skill: name, fromDir: canonicalPath, hash: install.installedHash })
           : null;
 
-        const sourceArg = plan.toCommit ? `${subscription.source}#${plan.toCommit}` : `${subscription.source}#${subscription.ref || 'main'}`;
+        const sourceArg = plan.toCommit
+          ? `${subscription.source}#${plan.toCommit}`
+          : `${subscription.source}#${plan.ref || subscription.ref || 'main'}`;
         const result = await cli.add({ source: sourceArg, skills: [name] });
         const lock = readLock(paths);
         const lockHash = lock.skills?.[name]?.skillFolderHash || null;
@@ -857,9 +1386,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 };
         });
 
@@ -886,6 +1417,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 });