@morehao/dsh-skills-console 0.2.4 → 0.3.1

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/client.js

@@ -138,7 +138,7 @@ var DICT = {
     "links.hint": "保存后按勾选建立或移除接入；技能本体保留在原位置，不会移动。",
     "autoLink.detected": "安装后自动接入",
     "autoLink.none": "本机没有检测到其他 Agent",
-    "autoLink.hint": "dsh（全局）始终接入；这里只影响之后安装时的自动接入，已安装的技能请在「接入设置」里改。",
+    "autoLink.hint": "列表里的「dsh（全局）」固定勾选、不能取消；这里只影响之后安装时的自动接入，已安装的技能请在「接入设置」里改。",
     "empty.skills": "还没有安装任何技能",
     "empty.skillsHint": "在终端跑 `npx skills add owner/repo`，或点右上角「添加技能」",
     "empty.subs": "还没有添加订阅",
@@ -268,7 +268,7 @@ var DICT = {
     "links.hint": "Saving only adds or removes links; the skill itself stays where it is.",
     "autoLink.detected": "Auto-link after install",
     "autoLink.none": "No other agents detected on this machine",
-    "autoLink.hint": 'dsh (global) is always linked; this only affects future installs. Change existing skills under "Link settings".',
+    "autoLink.hint": 'The "dsh (global)" entry is always checked and cannot be unchecked; this only affects future installs. Change existing skills under "Link settings".',
     "empty.skills": "No skills installed yet",
     "empty.skillsHint": 'Run `npx skills add owner/repo` or use "Add skill".',
     "empty.subs": "No subscriptions yet",
@@ -945,6 +945,9 @@ var CSS = `
   .dshsc-panel { border: 1px solid var(--dsw-alias-border-l1); border-radius: 10px; background: var(--dsw-alias-bg-layer-1);
     padding: 4px; max-height: 300px; overflow: auto; display: flex; flex-direction: column; }
   .dshsc-panel .dshsc-check:hover { background: var(--dsw-alias-bg-layer-2); }
+  /* 必选项（dsh 全局）：勾着但不可改，别让它看起来能点 */
+  .dshsc-panel .dshsc-check.locked { cursor: default; }
+  .dshsc-panel .dshsc-check.locked:hover { background: transparent; }
 
   .dshsc-modal-foot { display: flex; justify-content: flex-end; gap: 8px; padding-top: 12px; border-top: 1px solid var(--dsw-alias-border-l1); }
   .dshsc-toast { position: fixed; right: 18px; bottom: 18px; z-index: 70; font-size: 12px; padding: 10px 13px; border-radius: 9px;
@@ -1976,7 +1979,7 @@ function LinksModal({ t, row, agents, workspaces, pickDirectory, onCancel, onSav
     h("p", { className: "dshsc-sub" }, t("links.canonical").replace("{path}", `~/.agents/skills/${row.name}`)),
     ...candidates.map((agent) => h(
       "label",
-      { className: "dshsc-check", key: agent.target },
+      { className: `dshsc-check${agent.target === "dsh-global" ? " locked" : ""}`, key: agent.target },
       h("input", {
         type: "checkbox",
         checked: agent.target === "dsh-global" ? true : targets.has(agent.target),
@@ -2034,7 +2037,7 @@ function LinksModal({ t, row, agents, workspaces, pickDirectory, onCancel, onSav
     h("p", { className: "dshsc-sub" }, t("links.hint"))
   );
 }
-function AutoLinkModal({ t, settings, agents, onCancel, onSave }) {
+function AutoLinkModal({ t, settings, agents, dsh, onCancel, onSave }) {
   const [targets, setTargets] = import_react3.default.useState(() => new Set(
     Array.isArray(settings.autoLinkTargets) ? settings.autoLinkTargets : agents.map((agent) => agent.target)
   ));
@@ -2055,19 +2058,39 @@ function AutoLinkModal({ t, settings, agents, onCancel, onSave }) {
         h("button", { key: "s", className: "dshsc-btn primary", onClick: () => onSave([...targets]) }, t("action.save"))
       ]
     },
-    h("p", { className: "dshsc-sub" }, t("links.dshGlobal") + " · " + t("links.required")),
     h("div", { className: "dshsc-group" }, t("autoLink.detected")),
-    agents.length === 0 ? h("p", { className: "dshsc-sub" }, t("autoLink.none")) : h("div", { className: "dshsc-panel" }, agents.map((agent) => h(
-      "label",
-      { className: "dshsc-check", key: agent.target },
-      h("input", {
-        type: "checkbox",
-        checked: targets.has(agent.target),
-        onChange: () => toggle(agent.target)
-      }),
-      h("span", null, agent.label),
-      h("small", null, agent.dir)
-    ))),
+    h(
+      "div",
+      { className: "dshsc-panel" },
+      // dsh（全局）始终接入：列表里也勾上，只是不能改，勾选数与页头的计数器才对得上
+      h(
+        "label",
+        { className: "dshsc-check locked", key: "dsh-global" },
+        h("input", {
+          type: "checkbox",
+          checked: true,
+          disabled: true,
+          readOnly: true,
+          onChange: () => {
+          }
+        }),
+        h("span", null, dsh?.label || t("links.dshGlobal")),
+        h("small", null, t("links.required")),
+        dsh?.dir ? h("small", { title: dsh.dir }, dsh.dir) : null
+      ),
+      ...agents.map((agent) => h(
+        "label",
+        { className: "dshsc-check", key: agent.target },
+        h("input", {
+          type: "checkbox",
+          checked: targets.has(agent.target),
+          onChange: () => toggle(agent.target)
+        }),
+        h("span", null, agent.label),
+        h("small", null, agent.dir)
+      ))
+    ),
+    agents.length === 0 ? h("p", { className: "dshsc-sub" }, t("autoLink.none")) : null,
     h("p", { className: "dshsc-sub" }, t("autoLink.hint"))
   );
 }
@@ -2211,7 +2234,7 @@ function AddSkillModal({ t, onCancel, onProbe, onInstall }) {
     h("p", { className: "dshsc-sub" }, t("form.hint"))
   );
 }
-function Modals({ t, modal, data, autoLinkAgents, pickDirectory, actions, onClose, onSaveAutoLink }) {
+function Modals({ t, modal, data, autoLinkAgents, autoLinkDsh, pickDirectory, actions, onClose, onSaveAutoLink }) {
   if (modal.type === "add-skill") {
     return h(AddSkillModal, {
       t,
@@ -2253,6 +2276,7 @@ function Modals({ t, modal, data, autoLinkAgents, pickDirectory, actions, onClos
       t,
       settings: data?.settings || {},
       agents: autoLinkAgents,
+      dsh: autoLinkDsh,
       onCancel: onClose,
       onSave: (targets) => void onSaveAutoLink(targets)
     });
@@ -2327,6 +2351,7 @@ function Section({ t, page = false, pickDirectory, onPlacementChange }) {
   const autolinkTargets = (data?.agents?.detected || []).filter((agent) => agent.kind === "agent");
   const autoLinkSelection = data?.settings?.autoLinkTargets;
   const autoLinkAgents = Array.isArray(autoLinkSelection) ? autolinkTargets.filter((agent) => autoLinkSelection.includes(agent.target)) : autolinkTargets;
+  const autoLinkDsh = (data?.agents?.all || []).find((agent) => agent.target === "dsh-global") || null;
   const autoLinkLabel = [t("links.dshGlobal"), ...autoLinkAgents.map((agent) => agent.label)].join("、");
   const placement = (placementOverride ?? data?.settings?.placement) === "sidebar" ? "sidebar" : "settings";
   async function changePlacement(next) {
@@ -2442,6 +2467,7 @@ function Section({ t, page = false, pickDirectory, onPlacementChange }) {
       modal,
       data,
       autoLinkAgents: autolinkTargets,
+      autoLinkDsh,
       pickDirectory,
       actions: {
         probeSkills: actions.probeSkills,

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));
+}