@morehao/dsh-skills-console 0.2.3 → 0.3.0

package/lib/core/service.js

@@ -2,10 +2,11 @@ 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 { readLockFile, updateLock } from './lock.js';
+import { readBackup, restoreBackup, trashSkill } from './trash.js';
+import { parseSkillFrontmatter } from './skill-md.js';
 import {
   checkSkill,
   fetchDefaultBranch,
@@ -18,6 +19,7 @@ import {
   skillTreeSha,
   snapshotId,
 } from './updates.js';
+import { fetchAtomCommit, snapshotFromTarball } from './remote.js';
 
 const QUEUE_LIMIT = 8;
 
@@ -33,6 +35,48 @@ function nowIso() {
   return new Date().toISOString();
 }
 
+/** 路由参数里的技能名：在拼任何路径之前先校验，拒绝穿越/分隔符/控制字符。 */
+function assertSafeSkillName(name) {
+  if (
+    typeof name !== 'string' ||
+    name.length === 0 ||
+    name.length > 120 ||
+    name.includes('/') ||
+    name.includes('\\') ||
+    name.includes('..') ||
+    // eslint-disable-next-line no-control-regex
+    /[\u0000-\u001f\u007f]/.test(name)
+  ) {
+    throw new ServiceError('error.skills.not-found', `技能名非法: ${String(name)}`);
+  }
+  return name;
+}
+
+/** Native installer 的失败 → 现有通用错误码（不新增前端交互，只换 toast 文案）。 */
+function installerFailure(error, source, action = '安装') {
+  const code = error?.code || null;
+  const status = error?.status ?? null;
+  const detail = { reason: code, status, ...(error?.available ? { available: error.available } : {}) };
+  if (code === 'bad-source') return new ServiceError('error.skills.bad-source', '只接受 owner/repo 或 GitHub URL（公开源）');
+  if (code === 'no-skills') return new ServiceError('error.skills.no-skills', error.message, detail);
+  if (code === 'skill-not-found') {
+    return new ServiceError('error.skills.no-skills', error.message, detail);
+  }
+  if (code === 'timeout') {
+    return new ServiceError('error.skills.network', '下载技能包超时，请检查网络或代理后重试', detail);
+  }
+  if (code === 'tarball-too-large') {
+    return new ServiceError('error.skills.install-failed', '技能包超过大小上限，已中止安装', detail);
+  }
+  if (code === 'http-error' && status) {
+    return upstreamError(source, { status, error: error.message });
+  }
+  if (['lock-unsupported', 'lock-corrupt', 'lock-unreadable', 'lock-conflict', 'lock-write-failed'].includes(code)) {
+    return new ServiceError('error.skills.install-failed', `${action}失败：lock 不可写或已被其他进程修改（${code}）`, detail);
+  }
+  return new ServiceError('error.skills.install-failed', `${action}失败：${error?.message || error}`, detail);
+}
+
 /** 本机时区的 `HH:mm`。手写而不是 `toLocaleTimeString`：不受 ICU / locale 差异影响。 */
 function formatClock(ms) {
   const at = new Date(ms);
@@ -68,51 +112,6 @@ function upstreamError(source, failure) {
   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);
@@ -175,10 +174,19 @@ function createQueue(logger) {
 
 
 
-export function createService({ paths, store, registry, cli, logger, env = process.env, fetchImpl = fetch, visibleProvider = async () => ({ skills: [], complete: true }), workspacesProvider = async () => [] }) {
+export function createService({
+  paths,
+  store,
+  registry,
+  installer = null,
+  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;
@@ -192,6 +200,34 @@ export function createService({ paths, store, registry, cli, logger, env = proce
     if (store.readOnly) throw new StateReadOnlyError(store.problem);
   }
 
+  /** `/state.cli` 兼容字段：`usable` 由 native installer 与 lock 的可写性决定。 */
+  function nativeCapabilities() {
+    const capabilities = installer?.readiness?.() || {
+      usable: false,
+      source: 'missing',
+      version: null,
+      json: false,
+      fullDepth: false,
+      problem: 'installer-missing',
+    };
+    return capabilities;
+  }
+
+  /** 安装/更新/删除写操作的就绪门禁：只看 native installer 与 lock 的可写性。 */
+  async function requireInstaller() {
+    const capabilities = nativeCapabilities();
+    if (!capabilities.usable) {
+      throw new ServiceError(
+        'error.skills.installer-unavailable',
+        '本地安装器不可用（lock 版本/权限异常），写操作已禁用',
+        capabilities,
+      );
+    }
+    return capabilities;
+  }
+
+
+
   function detectedTargets() {
     return registry.detected();
   }
@@ -274,16 +310,23 @@ export function createService({ paths, store, registry, cli, logger, env = proce
    * 上游失败一律抛 ServiceError —— 添加订阅必须先读到快照再记账，
    * 否则会留下「订阅存在但一个 skill 都没有」的空壳（上游 404 时还会显示添加成功）。
    *
-   * T4：REST 因**限流**或 **404** 失败时先试 git（零配额）；git 也不行才抛 T1 的错误。
+   * 数据源：REST 优先；403/429 限流时用 Atom 取 commit，再下 codeload tarball 本地扫描，
+   * 不启动任何外部进程。`allowUnchanged=false` 供更新计划使用：即使 commit 没变也要拿完整树。
    */
-  async function readSnapshot(subscription, { force = false, withCommit = true, persistRef = false } = {}) {
+  async function readSnapshot(
+    subscription,
+    { force = false, withCommit = true, persistRef = false, allowUnchanged = true } = {},
+  ) {
     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;
+        if (failure?.rateLimited) {
+          return await atomSnapshot(subscription, {
+            ref: subscription.ref || null,
+            allowUnchanged,
+            rateLimit: failure,
+          });
         }
         throw upstreamError(source, failure);
       }
@@ -295,16 +338,9 @@ export function createService({ paths, store, registry, cli, logger, env = proce
         fetchImpl,
       });
       if (result.error) {
-        // 元数据已经通了，树再 404 说明是 ref 没了（不是仓库不存在）；只有限流值得转 git
+        // 元数据已经通了，树再 404 说明是 ref 没了（不是仓库不存在）；只有限流降级
         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,
-          });
+          return await atomSnapshot(subscription, { ref: branch, allowUnchanged, rateLimit: result });
         }
         throw new ServiceError('error.skills.upstream-failed', `读取 ${source}@${branch} 失败：${result.error}`, {
           source,
@@ -312,7 +348,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
           status: result.status ?? null,
         });
       }
-      if (result.notModified) return { notModified: true, branch };
+      if (result.notModified) return { notModified: true, branch, via: 'rest' };
       const entries = listSkillsFromTree({
         tree: result.tree,
         rootSha: result.rootSha,
@@ -347,161 +383,91 @@ export function createService({ paths, store, registry, cli, logger, env = proce
   }
 
   /**
-   * T4：用 git 组装一份与 REST 同形的快照。`etag` 恒为 `null` —— 下次刷新会完整读一次，
-   * 绝不会拿旧 ETag 去冒充 304。失败返回 `null`，由调用方抛 T1 的错误。
+   * 限流兜底：Atom 取 commit，与上次一致就短路；否则 codeload tarball 解压扫描。
+   * 失败统一翻成 T1 的四类错误（限流保留原始 reset 信息）。
    */
-  async function gitSnapshot(subscription, { ref = null, purpose = 'snapshot' } = {}) {
+  async function atomSnapshot(subscription, { ref = null, allowUnchanged = true, rateLimit = null } = {}) {
     const source = subscription.source;
-    const event = purpose === 'probe' ? 'git.probe' : 'git.snapshot';
-    if (!git.enabled()) return null;
     const startedAt = Date.now();
-    let url;
+    let atom;
     try {
-      url = git.url(source);
+      atom = await fetchAtomCommit({ source, ref: ref || null, token: tokenOf, fetchImpl });
     } catch (error) {
-      logger('git.fallback', { source, kind: error.kind || 'invalid-url', purpose });
-      return null;
+      logger('atom.failed', { source, kind: error.code || 'atom-failed', message: error.message });
+      throw upstreamError(source, {
+        status: rateLimit?.status ?? error.status ?? null,
+        rateLimited: Boolean(rateLimit?.rateLimited),
+        resetAt: rateLimit?.resetAt ?? null,
+        error: error.message,
+      });
     }
-    if (!(await git.isAvailable())) {
-      logger('git.fallback', { source, kind: 'git-missing', purpose });
-      return null;
+    const branch = ref || subscription.ref || null;
+    const previous = subscription.snapshot || null;
+    if (allowUnchanged && previous?.commit && previous.commit === atom.commit && Array.isArray(previous.entries)) {
+      logger('atom.unchanged', { source, commit: atom.commit, ms: Date.now() - startedAt });
+      return { branch, changed: false, notModified: true, via: 'atom', snapshot: previous };
     }
+    let scan;
     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, {
+      scan = await snapshotFromTarball({
         source,
+        commit: atom.commit,
         ref: branch,
-        commit: tree.commit,
-        entries: entries.length,
-        changed,
-        ms: Date.now() - startedAt,
+        subpath: subscription.subpath,
+        token: tokenOf,
+        fetchImpl,
       });
-      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,
+      logger('codeload.failed', { source, kind: error.code || 'scan-failed', message: error.message });
+      throw upstreamError(source, {
+        status: rateLimit?.status ?? error.status ?? null,
+        rateLimited: Boolean(rateLimit?.rateLimited),
+        resetAt: rateLimit?.resetAt ?? null,
+        error: error.message,
       });
-      return null;
     }
+    const changed =
+      !previous ||
+      previous.rootSha !== scan.rootSha ||
+      JSON.stringify(previous.entries) !== JSON.stringify(scan.snapshot.entries);
+    logger('atom.snapshot', {
+      source,
+      ref: branch,
+      commit: atom.commit,
+      entries: scan.snapshot.entries.length,
+      changed,
+      ms: Date.now() - startedAt,
+    });
+    return { ...scan, branch, changed };
   }
 
   /**
-   * T4 commit 短路：订阅快照的 commit 与远端 HEAD 一致 → 没变化，不必请求 REST。
-   * 只对「跟着默认分支」的订阅生效：盯 tag / 其他分支时 HEAD 不代表它。
+   * commit 短路：Atom feed 的 HEAD 与订阅快照一致 → 没变化，不请求 REST。
+   * Atom 不可用时返回 false，照常走 REST（只增不减）。
    */
   async function remoteCommitUnchanged(subscription) {
     const commit = subscription.snapshot?.commit;
-    if (!commit || !git.enabled()) return false;
-    if (!(await git.isAvailable())) return false;
+    if (!commit) 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;
+      const atom = await fetchAtomCommit({
+        source: subscription.source,
+        ref: subscription.ref || null,
+        token: tokenOf,
+        fetchImpl,
+      });
+      return atom.commit === commit;
     } catch (error) {
-      logger('git.fallback', {
+      logger('atom.failed', {
         source: subscription.source,
-        kind: error.kind || 'clone-failed',
+        kind: error.code || 'atom-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;
+  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;
@@ -646,7 +612,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
       const visible = await visibleSkills(cwd);
       const visibleNames = new Map(visible.skills.map((item) => [item.name, item.source || item.provider || 'unknown']));
       const ledger = buildLedger({ paths, state: state(), registry, lock, visibleNames });
-      const capabilities = await cli.capabilities();
+      const capabilities = nativeCapabilities();
       return {
         ok: true,
         readOnly: store.readOnly,
@@ -674,7 +640,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
     },
 
     async diagnostics() {
-      const capabilities = await cli.capabilities({ force: true });
+      const capabilities = nativeCapabilities();
       const lock = readLock(paths);
       reconcileTracking(lock);
       const rows = buildLedger({ paths, state: state(), registry, lock, visibleNames: new Map() }).rows;
@@ -789,6 +755,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
     },
 
     async setMode({ name, mode }) {
+      assertSafeSkillName(name);
       assertWritable();
       if (mode !== 'on' && mode !== 'off') throw new ServiceError('error.skills.bad-mode', 'mode 只能是 on / off');
       const install = store.findInstall(name);
@@ -831,12 +798,9 @@ 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);
-      }
-      // 技能名可留空：有订阅快照就装快照里的条目，否则交给 CLI 的 `--skill '*'`（整仓全部）
+      await requireInstaller();
       const requested = (skills || []).filter(Boolean);
+      for (const name of requested) assertSafeSkillName(name);
 
       return enqueue('install', async () => {
         const subscription = subscriptionId
@@ -844,77 +808,94 @@ export function createService({ paths, store, registry, cli, logger, env = proce
           : null;
         if (subscriptionId && !subscription) throw new ServiceError('error.skills.no-subscription', '订阅不存在');
         const resolvedSource = subscription ? subscription.source : source;
-        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: 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 (!parseSource(resolvedSource)) {
+          throw new ServiceError('error.skills.bad-source', '只接受 owner/repo 或 GitHub URL（公开源）');
+        }
+
+        // 有快照就沿用（含 commit/entries）；否则现场解析默认分支、commit 与技能清单。
+        let snapshot = subscription?.snapshot || null;
+        let branch = subscription?.ref || null;
+        if (!commit && !snapshot?.commit) {
+          const subject = subscription || { source: resolvedSource, ref: null, subpath: null, snapshot: null };
+          const read = await readSnapshot(subject, { withCommit: true, force: true });
+          snapshot = read.snapshot;
+          branch = read.branch;
+        }
+
+        const pin = commit || snapshot?.commit || branch || subscription?.ref || null;
+        if (!pin) {
+          throw new ServiceError('error.skills.upstream-failed', `无法解析 ${resolvedSource} 的 commit，请稍后重试`, {
+            source: resolvedSource,
           });
         }
-        // 留空时实际装了哪些技能以 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 sourceArg = `${resolvedSource}#${pin}`;
+
+        let result;
+        try {
+          result = await installer.install({
+            source: resolvedSource,
+            // pin 是 commit 时按 commit 下载；只有分支时让 installer 用分支
+            commit: commit || snapshot?.commit || null,
+            ref: pin,
+            subpath: subscription?.subpath || null,
+            names: requested,
+            expectedEntries: snapshot?.entries || null,
           });
+        } catch (error) {
+          logger('install.failed', { source: sourceArg, code: error?.code || null });
+          throw installerFailure(error, resolvedSource, '安装');
         }
 
-        const lock = readLock(paths);
         const installed = [];
-        const warnings = [];
-        for (const name of names) {
-          const canonicalPath = path.join(paths.canonical, name);
+        const warnings = [...(result.warnings || [])];
+        const recordedAt = nowIso();
+        for (const item of result.installed) {
+          const canonicalPath = path.join(paths.canonical, item.name);
           if (!fs.existsSync(canonicalPath)) {
-            warnings.push({ name, warning: 'add 成功但 canonical 里没有该目录（可能被目录发现提前终止）' });
+            warnings.push({ name: item.name, warning: '安装成功但 canonical 里没有该目录，未能记账' });
             continue;
           }
-          const lockEntry = lock.skills?.[name];
-          if (!lockEntry) {
-            warnings.push({ name, warning: 'lock 里没有该技能的记录（来源形态不支持记账）' });
-          }
-          const expected = snapshot?.entries?.find((entry) => entry.name === name);
-          const lockHash = lockEntry?.skillFolderHash || null;
+          const installedHash = item.contentHash || contentHash(canonicalPath);
+          const expected = snapshot?.entries?.find((entry) => entry.name === item.name) || null;
+          const lockHash = item.lockHash ?? item.treeSha ?? 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: lockHash,
-            });
-          }
-          const installedHash = fs.statSync(canonicalPath).isDirectory() ? contentHash(canonicalPath) : null;
           const record = {
-            name,
+            name: item.name,
             subscriptionId: subscription ? subscription.id : null,
-            skillPath: lockEntry?.skillPath || expected?.skillPath || `${name}/SKILL.md`,
+            skillPath: item.skillPath,
             ref: pin,
-            commit: snapshot?.commit || null,
-            // 安装那一刻的 tree 基线：lock 被写成内容哈希时，更新判定靠它（T2）
-            treeSha: expected?.treeSha || null,
+            commit: commit || snapshot?.commit || null,
+            // native installer 只写 40 位 tree SHA；旧 lock 的 64 位形态仍由 checkSkill 兼容
+            treeSha: item.treeSha || expected?.treeSha || null,
             installedHash,
-            installedAt: nowIso(),
-            updatedAt: nowIso(),
+            installedAt: recordedAt,
+            updatedAt: recordedAt,
             mode: 'on',
             scopeProjects: scopeProjects || [],
-            backup: null,
+            backup: item.backup
+              ? { key: item.backup, hash: item.backupHash || null, treeSha: item.backupTreeSha || null }
+              : null,
           };
           store.update((draft) => {
-            const index = draft.installs.findIndex((item) => item.name === name);
-            if (index >= 0) draft.installs[index] = { ...draft.installs[index], ...record, installedAt: draft.installs[index].installedAt };
-            else draft.installs.push(record);
+            const index = draft.installs.findIndex((row) => row.name === item.name);
+            if (index >= 0) {
+              draft.installs[index] = {
+                ...draft.installs[index],
+                ...record,
+                installedAt: draft.installs[index].installedAt || record.installedAt,
+              };
+            } else {
+              draft.installs.push(record);
+            }
+          });
+          installed.push({
+            name: item.name,
+            lockHash,
+            lockHashShape: shape,
+            treeSha: record.treeSha,
+            installedHash,
+            backup: item.backup || null,
           });
-          installed.push({ name, lockHash, lockHashShape: shape, installedHash });
         }
 
         const linkTargets = Array.isArray(targets) && targets.length > 0 ? targets : defaultTargets(state());
@@ -926,15 +907,7 @@ 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 });
+        logger('install', { source: sourceArg, skills: installed.map((item) => item.name), installed: installed.length });
         return {
           ok: true,
           installed,
@@ -946,14 +919,16 @@ export function createService({ paths, store, registry, cli, logger, env = proce
     },
 
     async remove({ name }) {
+      assertSafeSkillName(name);
       assertWritable();
+      await requireInstaller(); // 快照与体检之前就拒绝，避免留下孤儿 trash
       return enqueue(`remove:${name}`, async () => {
         const canonicalPath = path.join(paths.canonical, name);
         if (!fs.existsSync(canonicalPath)) {
           throw new ServiceError('error.skills.not-found', `${name} 不在 canonical 里`);
         }
 
-        // ① 体检：CLI 的 remove 会把所有 agent 目录下的同名条目 rm -rf，不区分是谁建的
+        // ① 体检：只动自己建的链接；真实目录/外来链接先拦下（前端弹窗依赖 detail.conflicts）
         const conflicts = [];
         for (const target of detectedTargets()) {
           const linkPath = path.join(target.dir, name);
@@ -971,13 +946,35 @@ export function createService({ paths, store, registry, cli, logger, env = proce
           );
         }
 
-        // ② 快照进回收站（默认开，保留 7 天）
+        // ② 快照进回收站；lock 写失败时用它把 canonical 恢复回来
         const hash = fs.statSync(canonicalPath).isDirectory() ? contentHash(canonicalPath) : null;
         const trash = trashSkill({ paths, skill: name, fromDir: canonicalPath, hash });
 
-        // ③ 调 CLI：绝不带 -a
-        const result = await cli.remove({ names: [name] });
-        const cliOk = result.code === 0 && !result.timedOut;
+        // ③ installer 删 lock 条目 + canonical；失败时不留“目录没了 lock 还在”的半状态
+        try {
+          await installer.remove({ name });
+        } catch (error) {
+          if (!fs.existsSync(canonicalPath)) {
+            try {
+              restoreBackup({
+                backup: { contentDir: path.join(trash.dir, 'content') },
+                toDir: canonicalPath,
+              });
+            } catch (restoreError) {
+              logger('remove.restore.failed', { name, message: restoreError.message });
+            }
+          }
+          const failure = installerFailure(error, name, '删除');
+          logger('remove.failed', { name, code: error?.code || null });
+          const kept = fs.existsSync(canonicalPath);
+          return {
+            ok: false,
+            code: failure.code,
+            message: `${failure.message}；${kept ? '真身仍在 canonical，回收站已留快照' : '已从回收站恢复真身'}`,
+            detail: failure.detail,
+            trash: trash.key,
+          };
+        }
 
         // ④ 清自家链接
         const cleaned = [];
@@ -993,16 +990,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
           delete draft.checks[name];
         });
 
-        logger('remove', { name, cliOk, trash: trash.key });
-        if (!cliOk) {
-          return {
-            ok: false,
-            code: 'error.skills.cli-failed',
-            message: 'skills remove 失败；已断开本插件建立的软链，真身可能仍在 canonical',
-            detail: { code: result.code, stderr: result.stderr.slice(-2000) },
-            trash: trash.key,
-          };
-        }
+        logger('remove', { name, trash: trash.key });
         return { ok: true, name, trash: trash.key, removedLinks: cleaned };
       });
     },
@@ -1022,24 +1010,17 @@ export function createService({ paths, store, registry, cli, logger, env = proce
         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 },
-          ));
+        // REST 优先；限流时 readSnapshot 内部用 Atom + codeload 兜底
+        const probe = 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({
@@ -1170,19 +1151,19 @@ 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 都不发。
+      // 短路：最常见的情况是「什么都没变」。先用 Atom 比 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' });
+        logger('subscription.refresh', { id, notModified: true, via: 'atom' });
         return {
           ok: true,
           changed: false,
           notModified: true,
-          via: 'git',
+          via: 'atom',
           subscription: state().subscriptions.find((item) => item.id === id),
         };
       }
@@ -1240,11 +1221,11 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
       const results = [];
       for (const { subscription, installs: groupInstalls } of groups.values()) {
-        // T4：与 readSnapshot 同一套语义 —— 限流 / 404 时先试 git，都失败才逐个标 unknown
+        // 与 readSnapshot 同一套语义：限流时 Atom/codeload 兜底，失败才逐个标 unknown
         // withCommit: false：判定只需要树，别为 check 多付一次 /commits 请求
         let probe;
         try {
-          probe = await readSnapshot(subscription, { withCommit: false, persistRef: true });
+          probe = await readSnapshot(subscription, { withCommit: false, persistRef: true, allowUnchanged: false });
         } catch (error) {
           for (const install of groupInstalls) {
             results.push({
@@ -1309,8 +1290,8 @@ 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', '该技能不属于任何订阅，无法生成更新计划');
-      // 与 checkUpdates 共用一套取数语义：限流时同样能靠 git 出计划（否则「查得到更新却更不了」）
-      const probe = await readSnapshot(subscription, { force: true });
+      // 与 checkUpdates 共用一套取数语义；计划必须拿到完整树，所以不允许 commit 相同就短路
+      const probe = await readSnapshot(subscription, { force: true, allowUnchanged: false });
       const ref = probe.branch;
       const lock = readLock(paths);
       const skillPath = lock.skills?.[name]?.skillPath || install.skillPath;
@@ -1341,6 +1322,7 @@ export function createService({ paths, store, registry, cli, logger, env = proce
 
     async applyUpdate({ name, token, overwrite = false }) {
       assertWritable();
+      await requireInstaller();
       return enqueue(`apply:${name}`, async () => {
         const plan = await this.planUpdate({ name });
         if (token && token !== plan.token) {
@@ -1348,7 +1330,6 @@ export function createService({ paths, store, registry, cli, logger, env = proce
         }
         const install = store.findInstall(name);
         if (!install) throw new ServiceError('error.skills.not-managed', `${name} 没有安装记录`);
-        const canonicalPath = path.join(paths.canonical, name);
         if (plan.localModified && !overwrite) {
           throw new ServiceError('error.skills.locally-modified', '本地有改动，更新会覆盖它们；确认后带 overwrite 重试', {
             plan,
@@ -1356,48 +1337,79 @@ export function createService({ paths, store, registry, cli, logger, env = proce
         }
 
         const subscription = state().subscriptions.find((item) => item.id === install.subscriptionId);
-        const backup = fs.existsSync(canonicalPath)
-          ? createBackup({ paths, skill: name, fromDir: canonicalPath, hash: install.installedHash })
-          : null;
+        if (!subscription) throw new ServiceError('error.skills.no-subscription', '该技能不属于任何订阅，无法更新');
 
-        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;
-        const verified = Boolean(lockHash) && lockHash === plan.targetTreeSha;
-        const present = fs.existsSync(canonicalPath);
-
-        if (result.code !== 0 || !present || !verified) {
-          if (backup) restoreBackup({ backup, toDir: canonicalPath });
-          logger('updates.apply.failed', { name, code: result.code, verified, present });
+        let result;
+        try {
+          result = await installer.install({
+            source: subscription.source,
+            commit: plan.toCommit || null,
+            ref: plan.toCommit || plan.ref || subscription.ref || null,
+            subpath: subscription.subpath,
+            names: [name],
+            expectedEntries: plan.targetTreeSha ? [{ name, treeSha: plan.targetTreeSha }] : [],
+            strict: true,
+          });
+        } catch (error) {
+          logger('updates.apply.failed', { name, reason: error?.code || null });
           return {
             ok: false,
             code: 'error.skills.update-failed',
-            message: backup ? '更新失败，已回滚到上一版' : '更新失败，没有可回滚的备份',
-            detail: { cliCode: result.code, verified, present, stderr: result.stderr.slice(-2000) },
-            backup: backup?.key || null,
+            message: '更新失败；安装器已回滚到操作前状态',
+            detail: { reason: error?.code || null, status: error?.status ?? null },
+            backup: null,
           };
         }
 
-        const installedHash = contentHash(canonicalPath);
+        const item = result.installed?.find((row) => row.name === name);
+        if (!item) {
+          // 理论不可达（names 已选中且 discovery 成功）；绝不把「没装上」报成成功
+          logger('updates.apply.failed', { name, reason: 'missing-installed-item' });
+          return {
+            ok: false,
+            code: 'error.skills.update-failed',
+            message: '更新失败；安装器没有返回该技能的结果',
+            detail: { reason: 'missing-installed-item' },
+            backup: null,
+          };
+        }
+        const installedHash = item.contentHash || contentHash(path.join(paths.canonical, name));
         store.update((draft) => {
-          const row = draft.installs.find((item) => item.name === name);
+          const row = draft.installs.find((entry) => entry.name === name);
           if (!row) return;
-          row.commit = plan.toCommit;
-          // 更新后基线跟着走：lock 若仍是内容哈希形态，下一次判定要用新的 tree SHA
-          row.treeSha = plan.targetTreeSha || row.treeSha || null;
+          row.commit = plan.toCommit || null;
+          row.treeSha = item.treeSha || plan.targetTreeSha || null;
           row.installedHash = installedHash;
           row.updatedAt = nowIso();
-          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 };
+          row.backup = item.backup
+            ? {
+                key: item.backup,
+                hash: item.backupHash || null,
+                treeSha: item.backupTreeSha || null,
+                commit: install.commit || null,
+              }
+            : row.backup;
+          draft.checks[name] = {
+            name,
+            status: 'current',
+            detail: null,
+            wouldCommit: null,
+            checkedAt: nowIso(),
+            installCommit: plan.toCommit || null,
+          };
         });
 
         // 复验软链：更新重建的是目录，链接理论上不受影响，断一条就补一条
         const relinked = linkSkill(name, ['dsh-global'], { scopeProjects: install.scopeProjects || [] });
-        logger('updates.apply', { name, from: plan.fromCommit, to: plan.toCommit, backup: backup?.key });
-        return { ok: true, name, fromCommit: plan.fromCommit, toCommit: plan.toCommit, backup: backup?.key || null, relinked };
+        logger('updates.apply', { name, from: plan.fromCommit, to: plan.toCommit, backup: item.backup || null });
+        return {
+          ok: true,
+          name,
+          fromCommit: plan.fromCommit,
+          toCommit: plan.toCommit || null,
+          backup: item.backup || null,
+          relinked,
+        };
       });
     },
 
@@ -1409,7 +1421,26 @@ export function createService({ paths, store, registry, cli, logger, env = proce
         const backup = readBackup({ paths, key: install.backup.key });
         if (!backup) throw new ServiceError('error.skills.no-backup', '备份目录已不存在');
         const canonicalPath = path.join(paths.canonical, name);
+        // 先读 lock 再动盘：lock 损坏时直接失败，避免只回滚一半
+        const lockBefore = readLockFile(paths.lockFile);
+        const lockEntry = lockBefore.data?.skills?.[name] || null;
         restoreBackup({ backup, toDir: canonicalPath });
+        if (lockEntry) {
+          updateLock({
+            lockPath: paths.lockFile,
+            expectedDigest: lockBefore.digest,
+            mutate: (draft) => {
+              const previous = draft.skills[name];
+              if (!previous) return;
+              draft.skills[name] = {
+                ...previous,
+                ...(install.backup.treeSha ? { skillFolderHash: install.backup.treeSha } : {}),
+                ...(install.backup.commit ? { ref: install.backup.commit } : {}),
+                updatedAt: nowIso(),
+              };
+            },
+          });
+        }
         const installedHash = contentHash(canonicalPath);
         store.update((draft) => {
           const row = draft.installs.find((item) => item.name === name);