@morehao/dsh-skills-console 0.2.4 → 0.3.0

package/README.md

@@ -8,7 +8,7 @@
 
 DSH（DeepSeek Harness）的**技能控制台**：装、更新、删除、接入其他 Agent、随时启停，外加一份订阅清单。
 
-它不搬技能。技能真身始终由 [`skills`](https://www.npmjs.com/package/skills) CLI 写进 `~/.agents/skills`；本插件只在 DSH 这一侧做控制台：决定**哪些技能、对谁、在哪一层可见**，并把每次改动做成可回滚的事务。
+它不搬技能。技能真身由插件内的 **native installer** 写进 `~/.agents/skills`，并维护 v3 lock；本插件只在 DSH 这一侧做控制台：决定**哪些技能、对谁、在哪一层可见**，并把每次改动做成可回滚的事务。安装、更新、删除都由 native installer 完成，不依赖 `skills` CLI 或系统 git。
 
 ## 为什么需要它
 
@@ -22,10 +22,10 @@ DSH（DeepSeek Harness）的**技能控制台**：装、更新、删除、接入
 
 | 能力 | 说明 |
 | --- | --- |
-| 清单 | canonical 扫描 + CLI lock 对账 + DSH 实际可见性对账；canonical 里已有的技能首次读取自动纳入追踪，不必逐个「接管」 |
-| 安装 | 填 `owner/repo`（可只装其中几个技能），下载、落盘、写 lock 全部交给 CLI；来自订阅快照时核对 lock 哈希，不一致会提示 |
+| 清单 | canonical 扫描 + v3 lock 对账 + DSH 实际可见性对账；canonical 里已有的技能首次读取自动纳入追踪，不必逐个「接管」 |
+| 安装 | 填 `owner/repo`（可只装其中几个技能），native installer 下载 codeload tarball → 安全解压 → 本地计算 tree SHA → 原子落盘 canonical + v3 lock；来自订阅快照时核对哈希，不一致会提示 |
 | 更新 | GitHub Trees 检测上游新 commit → 计划（commit 区间 + 影响范围 + 防抖 token）→ 应用前备份，失败自动回滚上一版 |
-| 删除 | 先体检（真实目录 / 外部链接直接中止）→ 快照进回收站 → 只删本插件建的链接与记账，CLI 的 `remove` 不带 `-a` |
+| 删除 | 先体检（真实目录 / 外部链接直接中止）→ 快照进回收站 → installer 删 lock 条目与真身（lock 写失败从回收站恢复）→ 只清本插件建的链接与记账 |
 | 接入 | 软链四态判定（`managed` / `managed-external` / `foreign-link` / `real`），**绝不覆盖**别人创建的东西；只列本机已安装目录，已删的 Agent 自动从列表消失 |
 | 启停 | `mode: on/off` 只摘或重建 DSH 侧链接，不动 `SKILL.md`，其他 Agent 的链接也不受影响 |
 | 作用范围 | 全局 `~/.dsh/skills`，或仅指定项目；项目可直接勾选 DSH 已登记的工作区，也可手动选目录 |
@@ -41,7 +41,7 @@ DSH（DeepSeek Harness）的**技能控制台**：装、更新、删除、接入
 
 ## 安装
 
-插件依赖里自带 `skills@1.7.4`，**不需要用户预装 Node / npm / npx**：CLI 由宿主自带的 Node 启动，装插件时随依赖一起落盘。安装技能仍需要**本机有 git**（CLI 会 `git clone` 仓库）；首次装插件需要联网拉取依赖。
+插件只带 `tar@7.5.22`（native installer 解压），**不需要用户预装 Node / npm / npx / git**。首次装插件需要联网拉取依赖。
 
 在 Harness 里装本地 link：
 
@@ -57,7 +57,7 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
       name: '@morehao/dsh-skills-console'
 ```
 
-客户端 half 只注册 `platform: web`，面板出现在 DSH Web 的设置页 / 侧栏。本地 `link:` 开发时，先在仓库跑一次 `npm install`（装上 `skills`），否则 CLI 依赖层不会命中。
+客户端 half 只注册 `platform: web`，面板出现在 DSH Web 的设置页 / 侧栏。本地 `link:` 开发时，先在仓库跑一次 `npm install`（装上 `tar`），否则 native installer 的解压依赖层不会命中。
 
 ## 快速上手
 
@@ -68,9 +68,9 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 
 ## 可靠性
 
-- **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。
+- **canonical 与 v3 lock 的写入口**：安装、更新、删除由 native installer 统一处理（下载/解压/发现/tree SHA/原子 promote/lock 事务）；插件其他模块只读。限流兜底的 codeload 扫描只在 `os.tmpdir()` 里解压，结果绝不落进 canonical 或 lock。
 - **只动自己的东西**：只处理本插件创建的 `managed` 链接，以及已记账的 `managed-external`；`real` 目录和 `foreign-link` 永不改写，删除前体检直接中止。
-- **启停不改正文**：`mode` 只增删 DSH 侧链接，避免本地修改被下一次 `add` 覆盖。
+- **启停不改正文**：`mode` 只增删 DSH 侧链接，避免本地修改被下一次安装/更新覆盖。
 - **可回滚**：删除进回收站（7 天）；更新前快照到 `backups/`，失败自动还原（接口另提供手动回滚）。
 - **状态坏了就只读**：`state.json` 是坏 JSON 或版本未知时，插件降级为只读并让写接口返回 409，不猜结构、不自动修复。
 - **不做任意路径**：请求里的目标一律走注册表反查，软链目标恒为 canonical 下同名目录。
@@ -79,8 +79,8 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 
 | 项 | 路径 | 归属 |
 | --- | --- | --- |
-| canonical 真身 | `~/.agents/skills` | `skills` CLI 独占 |
-| CLI lock | `~/.agents/.skill-lock.json`（设了 `XDG_STATE_HOME` 时为 `$XDG_STATE_HOME/skills/.skill-lock.json`） | `skills` CLI 独占（本插件只读） |
+| canonical 真身 | `~/.agents/skills` | native installer（安装/删除/更新） |
+| v3 lock | `~/.agents/.skill-lock.json`（设了 `XDG_STATE_HOME` 时为 `$XDG_STATE_HOME/skills/.skill-lock.json`） | native installer（安装/更新/删除） |
 | DSH 全局根 | `~/.dsh/skills` | 本插件写软链 |
 | 插件状态 | `$DSH_HOME/skills-console/state.json` | 本插件（`DSH_SKILLS_CONSOLE_HOME` 可覆盖） |
 | 备份 / 回收站 | `$DSH_HOME/skills-console/{backups,trash}` | 本插件 |
@@ -91,17 +91,12 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 | 变量 | 默认 | 作用 |
 | --- | --- | --- |
 | `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_TOKEN` / `GH_TOKEN` | 无 | 只读环境变量；带上后 REST 配额从匿名 60 次/小时提到 5000 次/小时，私有仓库安装也靠它 |
+| `XDG_STATE_HOME` | 未设置 | 设置后 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`。
+关于 GitHub 配额：**匿名 REST 是 60 次/小时，按出口 IP 共享**（公司、校园网出口常被同网段的人一起打满），打满后探测与更新会收到 403。本插件先走 REST；403/429 时改用 **Atom commit feed** 取 commit，再用 **codeload tarball** 在临时目录解压、扫描并本地计算 tree SHA，不占 REST 配额、也不需要 git。兜底也失败时，错误文案会给出恢复时间，并提示设置 `GITHUB_TOKEN`（5000 次/小时）。
 
-> git 通道只在 `os.tmpdir()` 里读一份临时仓库，用完即删 —— 不写 canonical、不写 CLI lock，落盘始终只交给 `skills` CLI。
+> Atom/codeload 兜底只在 `os.tmpdir()` 里解压，用完即删；结果不会落进 canonical 或 lock。
 
 
 ## 开发与发布

package/lib/core/archive.js

@@ -0,0 +1,246 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import * as tar from 'tar';
+
+/**
+ * 安全解压 codeload tarball。分两遍：**先全量校验，再解压**。
+ *
+ * 为什么不在解压时用 filter 跳过坏条目：filter 返回 false 只是“不落盘”，进程仍然算成功，
+ * 恶意归档会被静默忽略而不是拒绝。安装器需要 fail closed，所以先 list 一遍：
+ * - 只接受普通文件与目录；symlink/hardlink/设备/FIFO/未知类型直接拒绝。
+ * - 拒绝绝对路径、盘符、反斜杠、`.` / `..` / 空段。
+ * - 整个归档必须只有一个顶层目录（codeload 的 `repo-ref/`），用 strip:1 剥掉。
+ * - 文件数 ≤ maxFiles、解压总量 ≤ maxBytes；超限立即中止。
+ *
+ * 解压后再扫一遍目录，确认没有符号链接或特殊文件落盘（防御性复核）。
+ * 所有失败抛 ArchiveError，调用方负责清理 staging。
+ */
+
+export const DEFAULT_MAX_FILES = 10_000;
+export const DEFAULT_MAX_EXTRACTED_BYTES = 200 * 1024 * 1024;
+
+export class ArchiveError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.name = 'ArchiveError';
+    this.code = code;
+    Object.assign(this, extra);
+  }
+}
+
+function isGzipFile(file) {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const head = Buffer.alloc(2);
+    const read = fs.readSync(fd, head, 0, 2, 0);
+    return read === 2 && head[0] === 0x1f && head[1] === 0x8b;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * 归一化并校验一个 tar 条目路径。返回 `{ value, segments }`：
+ * - `value` 去掉末尾 `/` 后的 POSIX 路径；
+ * - 根目录条目（`repo-ref/`）的 segments 为 `['repo-ref']`。
+ */
+function parseEntryPath(raw) {
+  if (typeof raw !== 'string' || raw.length === 0) {
+    throw new ArchiveError('unsafe-entry', `条目路径为空或不是字符串: ${String(raw)}`);
+  }
+  if (raw.includes('\0')) throw new ArchiveError('unsafe-entry', '条目路径含 NUL');
+  if (raw.includes('\\')) {
+    throw new ArchiveError('unsafe-entry', `条目路径含反斜杠: ${JSON.stringify(raw)}`);
+  }
+  if (raw.startsWith('/')) throw new ArchiveError('unsafe-entry', `条目是绝对路径: ${raw}`);
+  if (/^[A-Za-z]:/.test(raw)) throw new ArchiveError('unsafe-entry', `条目带盘符: ${raw}`);
+
+  let value = raw;
+  while (value.endsWith('/')) value = value.slice(0, -1);
+
+  const segments = value.split('/');
+  for (const segment of segments) {
+    if (segment === '' || segment === '.' || segment === '..') {
+      throw new ArchiveError('unsafe-entry', `条目路径含非法段: ${JSON.stringify(raw)}`);
+    }
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f\u007f]/.test(segment)) {
+      throw new ArchiveError('unsafe-entry', `条目路径含控制字符: ${JSON.stringify(raw)}`);
+    }
+  }
+  return { raw, value, segments };
+}
+
+/** 扫一遍 tar 头，全部合法才允许进入解压。 */
+async function scanArchive({ tarball, gzip, maxFiles, maxBytes }) {
+  let root = null;
+  let files = 0;
+  let dirs = 0;
+  let bytes = 0;
+  let failure = null;
+  const warnings = [];
+
+  // 注意：tar 把 onReadEntry 里的异常当同步异常抛到事件循环，不会 reject list 的 Promise。
+  // 所以这里先记下第一个校验错误，扫完再抛；有错误时后续条目直接跳过。
+  const onReadEntry = (entry) => {
+    if (failure) return;
+    try {
+      const pathInfo = parseEntryPath(entry.path);
+      const [top] = pathInfo.segments;
+      if (root === null) root = top;
+      if (top !== root) {
+        throw new ArchiveError('unsafe-entry', `归档里有多个顶层目录: ${root} / ${top}`);
+      }
+
+      if (pathInfo.value === root) {
+        // 顶层目录本身；codeload 里它总是 Directory。
+        if (entry.type !== 'Directory') {
+          throw new ArchiveError('unsafe-entry', `顶层条目不是目录: ${entry.path}`);
+        }
+        dirs += 1;
+        return;
+      }
+
+      if (entry.type === 'File') {
+        if (!Number.isFinite(entry.size) || entry.size < 0) {
+          throw new ArchiveError('invalid-archive', `条目 size 非法: ${entry.path}`);
+        }
+        files += 1;
+        bytes += entry.size;
+        if (files > maxFiles) {
+          throw new ArchiveError('too-many-files', `文件数超过 ${maxFiles} 上限`, { maxFiles });
+        }
+        if (bytes > maxBytes) {
+          throw new ArchiveError('archive-too-large', `解压总量超过 ${maxBytes} 字节上限`, {
+            maxBytes,
+            bytes,
+          });
+        }
+        return;
+      }
+
+      if (entry.type === 'Directory') {
+        dirs += 1;
+        return;
+      }
+
+      throw new ArchiveError('unsafe-entry', `拒绝的条目类型 ${entry.type}: ${entry.path}`, {
+        entryType: entry.type,
+        entryPath: entry.path,
+      });
+    } catch (error) {
+      failure = error;
+    }
+  };
+
+  const onwarn = (code) => {
+    // 校验和失败 / 无法识别的归档 / 解压比例异常都说明归档不完整或伪造。
+    if (code === 'TAR_BAD_ARCHIVE' || code === 'TAR_ENTRY_INVALID' || code === 'TAR_ABORT') {
+      warnings.push(code);
+    }
+  };
+
+  try {
+    await tar.list({ file: tarball, gzip, onReadEntry, onwarn });
+  } catch (error) {
+    if (failure) throw failure;
+    throw new ArchiveError('invalid-archive', `不是合法的 tar 归档: ${error.message}`, { cause: error });
+  }
+  if (failure) throw failure;
+  if (warnings.length > 0) {
+    throw new ArchiveError('invalid-archive', `归档有损坏条目: ${warnings[0]}`, { warnings });
+  }
+
+  if (root === null) throw new ArchiveError('empty-archive', '归档里没有任何条目');
+  if (files === 0) throw new ArchiveError('empty-archive', '归档里没有普通文件');
+  return { root, files, dirs, bytes };
+}
+
+/** 解压后复核：不允许任何 symlink / 设备 / FIFO 落盘。 */
+function verifyExtracted(dest) {
+  let files = 0;
+  let dirs = 0;
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      const stat = fs.lstatSync(full);
+      if (stat.isSymbolicLink()) {
+        throw new ArchiveError('unsafe-entry', `解压后出现符号链接: ${full}`);
+      }
+      if (stat.isDirectory()) {
+        dirs += 1;
+        walk(full);
+        continue;
+      }
+      if (stat.isFile()) {
+        files += 1;
+        continue;
+      }
+      throw new ArchiveError('unsafe-entry', `解压后出现特殊文件: ${full}`);
+    }
+  };
+  walk(dest);
+  return { files, dirs };
+}
+
+/**
+ * 解压 tarball 到 `dest`。`dest` 必须是空目录或不存在（不存在会自动创建）。
+ * 成功返回 `{ dir, root, files, dirs, bytes }`；失败抛 ArchiveError，由调用方清理。
+ */
+export async function extractTarball({
+  tarball,
+  dest,
+  maxFiles = DEFAULT_MAX_FILES,
+  maxBytes = DEFAULT_MAX_EXTRACTED_BYTES,
+  gzip,
+} = {}) {
+  if (typeof tarball !== 'string' || typeof dest !== 'string') {
+    throw new ArchiveError('invalid-argument', 'extractTarball 需要 tarball 与 dest 路径');
+  }
+  if (!Number.isInteger(maxFiles) || maxFiles <= 0) {
+    throw new ArchiveError('invalid-argument', 'maxFiles 必须是正整数');
+  }
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0) {
+    throw new ArchiveError('invalid-argument', 'maxBytes 必须是正数');
+  }
+  let stat;
+  try {
+    stat = fs.statSync(tarball);
+  } catch (error) {
+    throw new ArchiveError('invalid-archive', `tarball 不存在: ${tarball}`, { cause: error });
+  }
+  if (!stat.isFile()) throw new ArchiveError('invalid-archive', `tarball 不是文件: ${tarball}`);
+
+  fs.mkdirSync(dest, { recursive: true });
+  const destStat = fs.lstatSync(dest);
+  if (destStat.isSymbolicLink() || !destStat.isDirectory()) {
+    throw new ArchiveError('invalid-dest', `staging 必须是真实目录: ${dest}`);
+  }
+  if (fs.readdirSync(dest).length > 0) {
+    throw new ArchiveError('dest-not-empty', `staging 目录必须为空: ${dest}`);
+  }
+
+  const compressed = gzip === undefined ? isGzipFile(tarball) : Boolean(gzip);
+  const scanned = await scanArchive({ tarball, gzip: compressed, maxFiles, maxBytes });
+
+  try {
+    await tar.extract({
+      file: tarball,
+      cwd: dest,
+      strip: 1,
+      gzip: compressed,
+      preservePaths: false,
+    });
+  } catch (error) {
+    throw new ArchiveError('extract-failed', `解压失败: ${error.message}`, { cause: error });
+  }
+
+  const verified = verifyExtracted(dest);
+  return {
+    dir: dest,
+    root: scanned.root,
+    files: verified.files,
+    dirs: verified.dirs,
+    bytes: scanned.bytes,
+  };
+}

package/lib/core/discovery.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readSkillFrontmatter } from './skill-md.js';
+
+/**
+ * 解压目录里的技能发现（纯只读，不落盘）。
+ *
+ * 规则与设计 §槽位一致：
+ * - 遍历（含 subpath 前缀）所有 `SKILL.md`，每个所在目录算一个技能；
+ * - 名字优先 frontmatter `name`，没有则用目录名，根级用仓库名；
+ * - 名字必须非空且不含 `/`、`\`、`..`、控制字符；
+ * - 重名直接报错，绝不静默择一；
+ * - 根级 `SKILL.md` 的 `skillPath` 是 `SKILL.md`，嵌套的是相对仓库根的 POSIX 路径。
+ *
+ * 返回 `[{ name, skillPath, dirPath, description }]`，按 name 排序。
+ */
+
+const SKIP_DIRS = new Set(['.git', 'node_modules']);
+
+export class DiscoveryError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.name = 'DiscoveryError';
+    this.code = code;
+    Object.assign(this, extra);
+  }
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}
+
+function normalizeSubpath(subpath) {
+  if (subpath === null || subpath === undefined || subpath === '') return null;
+  if (typeof subpath !== 'string') throw new DiscoveryError('invalid-subpath', 'subpath 必须是字符串');
+  const cleaned = subpath.trim().replace(/^\/+|\/+$/g, '');
+  if (!cleaned) return null;
+  if (cleaned.includes('\\') || /^[A-Za-z]:/.test(cleaned)) {
+    throw new DiscoveryError('invalid-subpath', `subpath 不是 POSIX 相对路径: ${subpath}`);
+  }
+  const segments = cleaned.split('/');
+  if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    throw new DiscoveryError('invalid-subpath', `subpath 含非法段: ${subpath}`);
+  }
+  return segments.join('/');
+}
+
+function assertSkillName(name, dirPath) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new DiscoveryError('invalid-name', `技能名为空: ${dirPath}`, { dirPath });
+  }
+  if (name.length > 120) {
+    throw new DiscoveryError('invalid-name', `技能名过长: ${name}`, { name, dirPath });
+  }
+  if (name.includes('/') || name.includes('\\') || name.includes('..')) {
+    throw new DiscoveryError('invalid-name', `技能名含路径分隔符: ${name}`, { name, dirPath });
+  }
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/.test(name)) {
+    throw new DiscoveryError('invalid-name', `技能名含控制字符: ${JSON.stringify(name)}`, { name, dirPath });
+  }
+  return name;
+}
+
+/**
+ * @param {{ dir: string, subpath?: string|null, repoName?: string|null }} options
+ */
+export function discoverSkills({ dir, subpath = null, repoName = null } = {}) {
+  if (typeof dir !== 'string' || dir.length === 0) {
+    throw new DiscoveryError('invalid-dir', 'discoverSkills 需要解压目录');
+  }
+  const root = path.resolve(dir);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new DiscoveryError('invalid-dir', `不是目录: ${dir}`);
+  }
+
+  const normalizedSubpath = normalizeSubpath(subpath);
+  const scanRoot = normalizedSubpath ? path.join(root, ...normalizedSubpath.split('/')) : root;
+  let scanStat;
+  try {
+    scanStat = fs.statSync(scanRoot);
+  } catch {
+    throw new DiscoveryError('subpath-not-found', `subpath 不存在: ${normalizedSubpath}`, {
+      subpath: normalizedSubpath,
+    });
+  }
+  if (!scanStat.isDirectory()) {
+    throw new DiscoveryError('subpath-not-found', `subpath 不是目录: ${normalizedSubpath}`, {
+      subpath: normalizedSubpath,
+    });
+  }
+
+  const fallbackRootName = repoName || path.basename(root);
+  const found = [];
+
+  const walk = (current) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch (error) {
+      throw new DiscoveryError('read-failed', `无法读取 ${current}: ${error.message}`, { cause: error });
+    }
+
+    const skillFile = entries.find((entry) => entry.name === 'SKILL.md' && entry.isFile());
+    if (skillFile) {
+      const skillDir = current;
+      const skillMd = path.join(skillDir, 'SKILL.md');
+      const frontmatter = readSkillFrontmatter(skillDir);
+      const fallback = skillDir === root ? fallbackRootName : path.basename(skillDir);
+      const name = assertSkillName(
+        typeof frontmatter.name === 'string' && frontmatter.name.trim()
+          ? frontmatter.name.trim()
+          : fallback,
+        skillDir,
+      );
+      found.push({
+        name,
+        skillPath: toPosix(path.relative(root, skillMd)),
+        dirPath: skillDir,
+        description: typeof frontmatter.description === 'string' ? frontmatter.description : null,
+      });
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (SKIP_DIRS.has(entry.name)) continue;
+      // 隐藏目录（.github、.vscode 等）里不会有技能；跳过也能避开 macOS 的 .DS_Store 目录
+      if (entry.name.startsWith('.')) continue;
+      walk(path.join(current, entry.name));
+    }
+  };
+
+  walk(scanRoot);
+
+  const byName = new Map();
+  for (const skill of found) {
+    const previous = byName.get(skill.name);
+    if (previous) {
+      throw new DiscoveryError('duplicate-name', `发现重名技能 ${skill.name}`, {
+        name: skill.name,
+        paths: [previous.skillPath, skill.skillPath],
+      });
+    }
+    byName.set(skill.name, skill);
+  }
+
+  return found.sort((a, b) => a.name.localeCompare(b.name));
+}

package/lib/core/git-tree.js

@@ -0,0 +1,132 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 本地计算 Git tree SHA（40 位），与 `git write-tree` / GitHub Trees API 的 `sha` 同一算法。
+ *
+ * 用途：native installer 落盘后算技能目录的 `skillFolderHash`，与旧 CLI lock 的 40 位基线对齐。
+ * 语义边界（与 git 一致）：
+ * - 文件 mode 只区分 `100644` / `100755`，目录 `40000`；不保留其他权限位。
+ * - 目录名排序按 git 的 `base_name_compare`：目录视作名字末尾多一个 `/` 再按字节比较。
+ * - 空目录不进 tree（git 根本不跟踪空目录），否则会与上游 tree SHA 对不上。
+ * - symlink、hardlink、设备、FIFO 等无法用普通 blob/tree 表示的类型**直接拒绝**，
+ *   绝不用内容 hash 冒充，避免写进 lock 的基线是猜的。
+ *
+ * 纯函数：只读传入目录，不写任何东西；失败抛 GitTreeError。
+ */
+
+export const EMPTY_TREE_SHA = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+
+const MODE_FILE = '100644';
+const MODE_EXEC = '100755';
+const MODE_DIR = '40000';
+
+export class GitTreeError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.name = 'GitTreeError';
+    this.code = code;
+    Object.assign(this, extra);
+  }
+}
+
+function blobSha(content) {
+  const header = Buffer.from(`blob ${content.length}\0`, 'utf8');
+  return crypto.createHash('sha1').update(header).update(content).digest();
+}
+
+function treeShaOf(payload) {
+  const header = Buffer.from(`tree ${payload.length}\0`, 'utf8');
+  return crypto.createHash('sha1').update(header).update(payload).digest();
+}
+
+/** git 的 tree 排序：目录名末尾补 `/` 后按字节比较。 */
+function compareEntries(left, right) {
+  const a = Buffer.from(left.dir ? `${left.name}/` : left.name, 'utf8');
+  const b = Buffer.from(right.dir ? `${right.name}/` : right.name, 'utf8');
+  return Buffer.compare(a, b);
+}
+
+function modeOf(stat) {
+  return (stat.mode & 0o111) !== 0 ? MODE_EXEC : MODE_FILE;
+}
+
+/**
+ * 递归读取目录，返回 `{ sha: Buffer, empty: boolean }`。
+ * `empty` 表示这个目录在 git 意义上是空的（没有文件，或只有空子目录）。
+ */
+function hashDir(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (error) {
+    throw new GitTreeError('read-failed', `无法读取目录 ${dir}: ${error.message}`, { cause: error });
+  }
+
+  const items = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    let stat;
+    try {
+      stat = fs.lstatSync(full);
+    } catch (error) {
+      throw new GitTreeError('read-failed', `无法读取 ${full}: ${error.message}`, { cause: error });
+    }
+
+    if (stat.isSymbolicLink()) {
+      throw new GitTreeError('unsupported-entry', `符号链接无法进 git tree: ${full}`, { path: full });
+    }
+    if (stat.isDirectory()) {
+      const nested = hashDir(full);
+      if (!nested.empty) items.push({ name: entry.name, dir: true, sha: nested.sha });
+      continue;
+    }
+    if (stat.isFile()) {
+      let content;
+      try {
+        content = fs.readFileSync(full);
+      } catch (error) {
+        throw new GitTreeError('read-failed', `无法读取 ${full}: ${error.message}`, { cause: error });
+      }
+      items.push({ name: entry.name, dir: false, mode: modeOf(stat), sha: blobSha(content) });
+      continue;
+    }
+    // FIFO / socket / 块设备 / 字符设备：git 里都不是普通条目，直接拒绝。
+    throw new GitTreeError('unsupported-entry', `不支持的文件类型，无法进 git tree: ${full}`, {
+      path: full,
+    });
+  }
+
+  items.sort(compareEntries);
+
+  const chunks = [];
+  for (const item of items) {
+    chunks.push(Buffer.from(`${item.mode || MODE_DIR} ${item.name}\0`, 'utf8'), item.sha);
+  }
+  const payload = Buffer.concat(chunks);
+  return { sha: treeShaOf(payload), empty: items.length === 0 };
+}
+
+/**
+ * 计算目录的 Git tree SHA（40 位小写 hex）。
+ * 目录不存在 / 不可读 / 含不可表示条目时抛 GitTreeError，调用方不得写 lock。
+ */
+export function gitTreeSha(dir) {
+  if (typeof dir !== 'string' || dir.length === 0) {
+    throw new GitTreeError('invalid-path', 'gitTreeSha 需要非空目录路径');
+  }
+  let stat;
+  try {
+    stat = fs.lstatSync(dir);
+  } catch (error) {
+    throw new GitTreeError('read-failed', `目录不存在或不可读 ${dir}: ${error.message}`, { cause: error });
+  }
+  if (stat.isSymbolicLink()) {
+    throw new GitTreeError('unsupported-entry', `技能目录本身是符号链接: ${dir}`, { path: dir });
+  }
+  if (!stat.isDirectory()) {
+    throw new GitTreeError('invalid-path', `不是目录: ${dir}`);
+  }
+  return hashDir(dir).sha.toString('hex');
+}