dsh-plugin-t-expert 0.3.92 → 0.4.9

package/lib/index.js

@@ -38,6 +38,9 @@ import {
   truncate,
   writeFileAtomic,
 } from "./catalog.js";
+// 技能开关（2026-09-28 从 dsh-plugin-skill-gate 整体搬来）：包装 ctx.skills，把名单里的技能
+// 从模型目录里摘掉。装配入口是动态 inject 调的 —— 宿主没有 skills 服务时只少这一块。
+import { installSkillGate } from "./skill-gate/install.js";
 import { localized, NS, readLocale, renderList, renderSummonResults, t, toRenderableGroups, toRenderableSummonResults } from "./i18n.js";
 import { seedData } from "./bootstrap.js";
 import { installBundledSkills } from "./skill.js";
@@ -130,14 +133,19 @@ export const Config = schema.object({
   enabledSeeded: volatileField(schema.boolean().default(false)),
   /** 「默认全部启用」已按哪一版策略播种过；+1 即对所有用户重新播种一次。 */
   enabledSeedVersion: volatileField(schema.number().default(0)),
-  /** 是否显示侧栏「定时事项」按钮（关掉 = 定时功能整体停用）。 */
-  /** 是否显示窗口右上角的「活跃指示」。 */
-  showActivePulse: volatileField(schema.boolean().default(true)),
+  /**
+   * 技能开关的名单文件（技能开关那部分的配置，2026-09-28 随它一起搬进来）。
+   *
+   * 默认仍是原来的 `~/.dsh/skill-gate.json` —— **刻意不改路径**：用户的名单就在那里，
+   * 换路径等于把已有的开关状态清零。字段类型与其它 Config 一致（普通 string，
+   * 不需要 volatile：它不属于「用户偏好」那套 profile patch 机制）。
+   */
+  skillGateStore: schema.string().default(join(homedir(), ".dsh", "skill-gate.json")),
 });
 
 /** 供 remote 服务读取名册的服务名。 */
 export const CATALOG_SERVICE = "tTeamCatalog";
-/**
+
 /** 设置命名空间（= 插件名）。 */
 export const SETTINGS_NAMESPACE = NS;
 
@@ -166,20 +174,6 @@ const settingsSchema = schema.object({
    * 而且置了 true 之后连改逻辑都救不回来。换成版本号后，+1 就能对所有人重新播种一次。
    */
   enabledSeedVersion: schema.number().default(0),
-  /**
-   * 是否显示侧栏「定时事项」按钮（界面偏好）。
-   *
-   * 语义（用户口径）：**关掉 = 定时事项功能整体停用** —— 不只是藏按钮，还要停掉全部定时触发
-   * 任务数据完整保留，重新打开即恢复调度。
-   */
-  /**
-   * 是否显示窗口右上角的「活跃指示」（心电图图标，界面偏好）。
-   *
-   * 彩色 = 有会话正在活动（自己在跑、或子代理在跑）**或**有待查看的完成提醒；
-   * 灰色 = 全部空闲且没有待看。它是**全局**的（挂会话标题栏的 utilities 槽），
-   * 不受"当前打开哪个会话"影响。
-   */
-  showActivePulse: schema.boolean().default(true),
 });
 
 /**
@@ -223,10 +217,10 @@ function logSeedReport(logger, seeded, dataHome) {
 /**
  * 包内名册的规模（专家数 / 分区数），**从名册目录现算**并按目录缓存。
  *
- * 为什么不能写死：提示段是**模型可见的事实**。「a 316-expert, 22-division roster」这类字面量
- * 在名册增删改分区之后就对模型说谎，而且没有任何东西会红（2026-09-13 定性的恒存缺陷之一：
- * 数据更新了，模型看到的事实还是旧的）。现算 + 按目录缓存：一次 readdir 的开销，换来提示
- * 永远等于该名册的真实规模。
+ * 为什么不能写死：提示段是**模型可见的事实**。把「a N-expert, M-division roster」写成
+ * 字面量之后，名册增删或改分区之后那个 N/M 就对模型说谎，且没有任何东西会红
+ * （2026-09-13 定性的恒存缺陷之一：数据更新了，模型看到的事实还是旧的）。现算 + 按目录
+ * 缓存：一次 readdir 的开销，换来提示永远等于该名册的真实规模。
  * @param root - 名册目录（包内快照或用户数据目录）。
  * @returns 规模；目录读不到时 `experts` 为 0（调用方据此改用不带数字的说法，而不是报 0 位）。
  */
@@ -239,8 +233,9 @@ function rosterScale(root) {
   try {
     const divisions = readdirSync(key, { withFileTypes: true }).filter((entry) => entry.isDirectory());
     // **递归**数 `.md`：名册里存在 `game-development/unity/<slug>.md` 这类二级分组，
-    // 只数一层会少算（2026-09-13 实测：一层 301 / 递归 316，与 README、source.json、
-    // zh/names.json 的 316 一致）。分区数只取一级目录 —— 二级目录是分组不是分区。
+    // 只数一层会少算（2026-09-13 实测：一层 vs 递归差几十；具体数随名册增长而变，
+    // 所以**不**把数字写在这里 —— 真源是 `data/source.json` 与 verify 的 [15] 名册工具，
+    // 本注释只解释"为什么必须递归"）。分区数只取一级目录 —— 二级目录是分组不是分区。
     const experts = readdirSync(key, { recursive: true }).filter((name) => String(name).endsWith(".md")).length;
     scale = { experts, divisions: divisions.length };
   } catch {
@@ -263,6 +258,41 @@ export function apply(ctx, config) {
     ctx.logger?.error?.(`[t-team] 名册快照同步失败，将按已有数据继续：${seeded.error}`);
   }
 
+  // ---- 技能开关（原 dsh-plugin-skill-gate）----
+  // ⚠️ 用**动态** ctx.inject 而不是静态 `inject = ["skills"]`：后者是强依赖，宿主某版本没有
+  // skills 服务时 T专家 会整个不激活 —— 连专家名册与召唤一起没。这里拿不到就只少技能开关。
+  if (typeof ctx.inject === "function") {
+    // ⚠️ 只装一次：`ctx.inject` 的回调在依赖服务**被重新提供**时会再次触发，重复装配会把
+    // `ctx.skills` 层层包装（wrapper 累积、卸载时的还原也会错位），而且 cordis 的
+    // `reflect.provide` 对同名服务是**硬冲突**（`service "skillGateHost" has been registered
+    // at <fiber>`，见 cordis 的 provide 实现：`if (this.store[key]) throw`）—— 第二次装配
+    // 必然抛在 provide 那一步。
+    //
+    // 但"只装一次"不能等于"之后什么都不说"：宿主真把 skills 换成新实例时（另一个插件重载并
+    // 重新 provide 了它），停用名单仍作用在**旧**实例上，新实例的技能不受约束 ——
+    // 那是静默失效，用户关掉技能却发现它照样能被召唤，且日志里一个字都没有。所以这里出声。
+    let installedSkills;   // undefined = 还没装过
+    ctx.inject(["skills"], (scoped) => {
+      const skillsCtx = scoped ?? ctx;
+      const skills = skillsCtx?.skills;
+      if (installedSkills === undefined) {
+        installedSkills = skills;
+        try {
+          installSkillGate(skillsCtx, { storePath: config.skillGateStore });
+        } catch (error) {
+          ctx.logger?.error?.("[t-team] 技能开关装配失败（专家名册不受影响）：", error);
+        }
+        return;
+      }
+      if (skills === installedSkills) return;   // 同一个实例：已经包过，幂等
+      ctx.logger?.warn?.("[t-team] 宿主的 skills 服务换了新实例，而技能开关仍作用在旧实例上："
+        + "此后新装/重载的技能可能不受停用名单约束。重载 T专家 插件（或重启宿主）即可恢复；"
+        + "专家名册与召唤不受影响。");
+    });
+  } else {
+    ctx.logger?.warn?.("[t-team] 上下文没有 inject：技能开关不可用（专家名册不受影响）。");
+  }
+
 
 
 
@@ -303,7 +333,7 @@ export function apply(ctx, config) {
       if (typeof settingsService?.register === "function") {
         // ── 旧宿主（≤0.1.6）：按命名空间注册，读写都走返回的句柄。
         scope = settingsService.register(SETTINGS_NAMESPACE, settingsSchema, {
-          base: { enabled: [], enabledSeeded: false, enabledSeedVersion: 0, showActivePulse: true },
+          base: { enabled: [], enabledSeeded: false, enabledSeedVersion: 0 },
           applies: "live",
           validate: (value) => {
             const list = value?.enabled;
@@ -329,15 +359,13 @@ export function apply(ctx, config) {
             "t-team: 设置页策略",
           );
         }
-        if (typeof ctx.on === "function") {
-        }
         return;
       }
       ctx.logger?.warn?.("[t-team] settings 服务既没有 register 也没有 mutate：专家启停不可用（名册与召唤不受影响）。");
     });
   }
   /**
-   * 读偏好段（专家启停 + 界面开关）。
+   * 读偏好段（专家启停）。
    *
    * 来源严格按 `prefsMode` 二选一（理由见 prefsMode 注释）；0.1.7 的 Config 字段是
    * volatile 引用，统一 unwrap 后再用。
@@ -351,7 +379,6 @@ export function apply(ctx, config) {
         enabled: unwrapVolatile(source.enabled),
         enabledSeeded: unwrapVolatile(source.enabledSeeded),
         enabledSeedVersion: unwrapVolatile(source.enabledSeedVersion),
-        showActivePulse: unwrapVolatile(source.showActivePulse),
       };
     }
     return undefined;
@@ -872,53 +899,10 @@ export function apply(ctx, config) {
     }
   }
 
-  /**
-   * 读界面偏好（定时事项按钮 + 活跃指示）。
-   * 读当前值统一走 `readPrefs()`（与 enabledSet() 同一来源）：旧宿主是 settings 命名空间句柄，
-   * 0.1.7+ 是本 entry Config 的 volatile 字段。
-   * 直接调 settingsService.get().value 在本机版本的设置服务上不成立（读到 undefined 抛错）。
-   *
-   * 两个键都**必有**且缺省为 true：设置文件里没有这个键时保持与默认一致，
-   * 客户端于是不必到处兜 undefined（wire schema 也是这么声明的）。
-   */
-  function getUiPrefs() {
-    const current = readPrefs();
-    return {
-      showActivePulse: current?.showActivePulse !== false,
-    };
-  }
-
-  /** 只取 patch 里**确实是 boolean** 的键（其余一律忽略：坏值不该被写成"关"）。 */
-  function normalizePrefsPatch(patch) {
-    const source = patch !== null && typeof patch === "object" ? patch : {};
-    return {
-      ...(typeof source.showActivePulse === "boolean" ? { showActivePulse: source.showActivePulse } : {}),
-    };
-  }
-
-  /**
-   * 写界面偏好（局部更新，不碰 enabled）。
-   *
-   * 写成功后再把「定时事项」那一位落到调度上：面板开关与后台定时器必须是同一个事实，
-   * 否则用户关了开关、cron 还在后台开新会话。
-   */
-  async function setUiPrefs(patch) {
-    const next = { ...getUiPrefs(), ...normalizePrefsPatch(patch) };
-    await settingsService.mutate(
-      SETTINGS_NAMESPACE,
-      [
-        { op: "set", path: ["showActivePulse"], value: next.showActivePulse },
-      ],
-      revision(),
-    );
-    return getUiPrefs();
-  }
-
   const catalogService = {
     snapshot, prompt, setEnabled, root: config.root,
     createExpert, updateExpert, deleteExpert,
     createCategory, updateCategory, deleteCategory,
-    getUiPrefs, setUiPrefs,
   };
   ctx.reflect.provide(CATALOG_SERVICE, catalogService);
 
@@ -980,23 +964,6 @@ export function apply(ctx, config) {
     }
   }
 
-  /** 预检报告的中文渲染。 */
-  function renderPlanReport(value) {
-    const lines = [value.ok === true ? "预检通过：这套任务可以按顺序创建。" : `预检未通过：${value.problems.length} 个问题。`];
-    for (const problem of value.problems ?? []) {
-      const where = problem.id === undefined ? "" : `[${problem.id}] `;
-      lines.push(`- ✗ ${where}${problem.subject === "" ? "" : `${problem.subject}：`}${problem.error}`);
-    }
-    if ((value.warnings ?? []).length > 0) {
-      lines.push("提示（不阻塞）：");
-      for (const warning of value.warnings) lines.push(`- ! ${warning}`);
-    }
-    if ((value.order ?? []).length > 0) {
-      lines.push(`建议创建/执行顺序：${value.order.join(" → ")}`);
-    }
-    return lines.join("\n");
-  }
-
   // ---- 工具 ----
   ctx.tools.register(defineTool({
     name: "list_t_experts",

package/lib/remote-schemas.js

@@ -55,6 +55,22 @@ export const catalogSnapshotSchema = z.object({
   // 漏声明时面板拿到的快照里根本没有它们，界面上表现为"分区标签是空的"。
   customDivision: z.string().optional(),
   customDivisionLabel: z.string().optional(),
+  /**
+   * 名册健康状态。
+   *
+   * ⚠️ 这个字段在 0.4.6 之前**一直没声明**：host 侧早就在快照里返回它、注释也写着
+   * 「面板可以据此提示『中文侧车没找到 / 有 N 个专家文件被跳过』」，但 zod 会把它剥掉 ——
+   * 面板永远收不到。于是"中文侧车没找到"这种会让整个名册**静默变全英文**的状况，
+   * 用户在界面上看不到任何线索，只能对着一片英文名猜。
+   * 与上面 `customDivision` 那两个字段是同一个坑（那里的注释已经警告过"漏声明会被剥掉"），
+   * 只是这次踩在一个嵌套对象上，更不容易被发现。
+   */
+  sidecar: z.object({
+    zhRoot: z.string(),
+    present: z.boolean(),
+    skippedFiles: z.number().int().min(0),
+    unreadableDivisions: z.array(z.string()),
+  }).optional(),
   /** 可选的落点分类（面板「分类」下拉与管理页）：官方在前，其余按目录/声明发现。 */
   categories: z.array(z.object({
     key: z.string(),
@@ -70,20 +86,4 @@ export const enabledStateSchema = z.object({
   revision: z.number().int().min(0),
 });
 
-/**
- * 界面偏好（宿主持久化，客户端只读展示 + 写入）。
- *
- * 两个键都是 `boolean` 且**必有**：host 侧读取时缺省一律补 true，客户端因此不必到处兜 undefined。
- * 加新键要同时改 host（lib/index.js 的 settingsSchema 与 getUiPrefs）与客户端消费处。
- */
-export const uiPrefsSchema = z.object({
-  // 窗口右上角「活跃指示」是否显示。宿主**总是**返回布尔（缺省按 true 算），所以这里必填。
-  showActivePulse: z.boolean(),
-});
-
-/** `setUiPrefs` 的入参：想改哪个传哪个（未传的键保持原值）。 */
-export const uiPrefsPatchSchema = z.object({
-  showActivePulse: z.boolean().optional(),
-});
-
 export const promptSchema = z.object({ prompt: z.string() });

package/lib/remote.js

@@ -28,9 +28,9 @@ import {
   enabledStateSchema,
   expertSchema,
   promptSchema,
-  uiPrefsPatchSchema,
-  uiPrefsSchema,
 } from "./remote-schemas.js";
+import { snapshotSchema as skillGateSnapshotSchema } from "./skill-gate/remote-schemas.js";
+import { GATE_SERVICE } from "./skill-gate/constants.js";
 
 
 /** 一个 direct 调用描述符。 */
@@ -48,17 +48,27 @@ function descriptor(method, parameters, typeSymbol, schema) {
 
 const DESCRIPTORS = [
   descriptor("getCatalog", [], "TTeamCatalog", catalogSnapshotSchema),
-  descriptor("getUiPrefs", [], "TTeamUiPrefs", uiPrefsSchema),
-  // 入参从「单个 boolean」改成 patch 对象：界面偏好不止一项，
-  // 加键不必再加方法（未传的键保持原值，host 侧做兜底）。
-  descriptor("setUiPrefs", [
+  // ---- 技能开关（2026-09-28 从 dsh-plugin-skill-gate 并入）----
+  // ⚠️ 它们挂在**本插件已有的 tTeam 命名空间**下，没有单开第二个 remote 入口。
+  // 起因：合并时先做成独立入口（`dsh-plugin-t-expert/skill-gate-remote` + `skillGate` 命名空间），
+  // 但同一个包再挂一份 remote 在实机上没能生效（客户端 `ctx.get("remote.skillGate")` 始终是
+  // undefined，面板显示「服务不可用」）。改挂到已被证明可用的 tTeam 通路上，确定性更高、
+  // 也少一个入口要维护。方法名沿用原插件的 getSnapshot / setDisabled。
+  descriptor("getSnapshot", [], "SkillGateSnapshot", skillGateSnapshotSchema),
+  descriptor("setDisabled", [
     {
-      name: "patch",
-      wire: "patch",
+      name: "disabled",
+      wire: "disabled",
       source: "json",
-      codec: { mode: "strict", typeSymbol: "TTeamUiPrefsPatch", schema: uiPrefsPatchSchema, create: () => uiPrefsPatchSchema },
+      codec: { mode: "strict", typeSymbol: "string[]", schema: z.array(z.string().max(128)).max(4000), create: () => z.array(z.string().max(128)).max(4000) },
     },
-  ], "TTeamUiPrefs", uiPrefsSchema),
+    {
+      name: "expectedRevision",
+      wire: "expectedRevision",
+      source: "json",
+      codec: { mode: "strict", typeSymbol: "number", schema: z.number().int().min(0), create: () => z.number().int().min(0) },
+    },
+  ], "SkillGateSnapshot", skillGateSnapshotSchema),
   descriptor("setEnabled", [
     {
       name: "enabled",
@@ -200,7 +210,11 @@ function exposeRemoteMethods(Class, methods) {
 }
 
 class TTeamRemote extends TypertRemoteService {
-  static inject = ["settings", "typert"];
+  // ⚠️ `settings` 此前在 inject 里但**未被读过**：cordis 要等 inject 里每一个服务就绪才实例化
+  // 这个类（见 cordis 的 inject 实现），宿主 settings 一旦晚到，定时任务面板就跟着报
+  // "服务暂时不可用"，排查的人却被引去查 typert 与调度引擎 —— 因为这才是表面报错处。
+  // [8c] 现在盯着：`static inject` 不能含任何未被读取的字段。
+  static inject = ["typert"];
 
   constructor(ctx) {
     super(ctx, "tTeam");
@@ -234,30 +248,36 @@ class TTeamRemote extends TypertRemoteService {
     return service;
   }
 
-  /** 动态名册：完整专家列表 + 已启用 slug + 修订号。 */
-  async getCatalog() {
+  /** 技能开关：完整快照（技能清单 + 计数 + 视角）。 */
+  async getSnapshot() {
     try {
-      return await this.catalog().snapshot();
+      return await skillGate.call(this).snapshot();
     } catch (error) {
-      // 服务缺失已在 catalog() 里铸成 tTeam/host-unavailable；这里只兜业务失败。
-      throw this.businessError(error, "tTeam/catalog-unreadable");
+      throw this.businessError(error, "tTeam/skill-gate-unreadable");
     }
   }
 
-  /** 整体替换启用列表；过期修订号由 settings 服务拒绝。 */
-  async getUiPrefs() {
+  /** 技能开关：整份替换停用名单（带乐观锁的修订号）。 */
+  async setDisabled(disabled, expectedRevision) {
+    const service = skillGate.call(this);
+    if (service.getRevision() !== expectedRevision) {
+// @ts-expect-error 上游类型缺口：同上，tTeam/* 业务码不在闭合的 RemoteErrorDetailsMap 里。
+      throw new RemoteError("tTeam/conflict", "设置已被其他窗口修改，请重试。", { expectedRevision: String(expectedRevision) });
+    }
     try {
-      return await this.catalog().getUiPrefs();
+      return await service.setDisabled(disabled);
     } catch (error) {
-      throw this.businessError(error, "tTeam/ui-prefs-unreadable");
+      throw this.businessError(error, "tTeam/skill-gate-unwritable");
     }
   }
 
-  async setUiPrefs(patch) {
+  /** 动态名册：完整专家列表 + 已启用 slug + 修订号。 */
+  async getCatalog() {
     try {
-      return await this.catalog().setUiPrefs(patch);
+      return await this.catalog().snapshot();
     } catch (error) {
-      throw this.businessError(error, "tTeam/ui-prefs-unwritable");
+      // 服务缺失已在 catalog() 里铸成 tTeam/host-unavailable；这里只兜业务失败。
+      throw this.businessError(error, "tTeam/catalog-unreadable");
     }
   }
 
@@ -307,13 +327,24 @@ class TTeamRemote extends TypertRemoteService {
    * `error.code` 只有**形如 `<domain>/<reason>`** 才能当 wire code 用：系统 errno
    * （`EACCES`/`ENOENT`/`EPERM`…）过线后被客户端按 code 分支时会误当领域码（D-17），
    * 所以形态不符一律回落 `fallbackCode`。
-   * @param error - 被捕获的原错误。
-   * @param fallbackCode - 该访问器的领域码。
+   * @param {unknown} error - 被捕获的原错误。
+   * @param {string} fallbackCode - 该访问器的领域码。
+   *
+   * ⚠️ 这两个类型标注不能省：`error` 缺标注时它是 `any`，`candidate` 跟着变 `any`，
+   * 于是下面 `new RemoteError(...)` 的类型检查整个失效（TS 对 any 一律放行）——
+   * 表现是这里**本该有**的那道「上游类型缺口」抑制指令根本不需要存在，
+   * 而一旦谁补上标注，tsc 就会立刻报它 unused。辅助补丁同一个方法踩过这个坑（0.13.0 修）。
    */
   businessError(error, fallbackCode) {
     if (error instanceof RemoteError) return error;
     const message = error instanceof Error ? error.message : String(error);
-    const candidate = typeof error === "object" && error !== null && typeof error.code === "string" ? error.code : undefined;
+    // `unknown` 经 `typeof === "object"` 收窄后在 TS 眼里仍是 `object`（上面没有 code），
+    // 所以显式当成「可能带 code 的未知对象」来读 —— 比把参数标成 any 好，any 会往下传染。
+    const maybeCode = /** @type {{ code?: unknown }} */ (
+      typeof error === "object" && error !== null ? error : {}
+    ).code;
+    const candidate = typeof maybeCode === "string" ? maybeCode : undefined;
+// @ts-expect-error 上游类型缺口：同上，tTeam/* 业务码不在闭合的 RemoteErrorDetailsMap 里。
     return new RemoteError(DOMAIN_CODE_PATTERN.test(candidate ?? "") ? candidate : fallbackCode, message, {});
   }
 
@@ -387,9 +418,22 @@ class TTeamRemote extends TypertRemoteService {
   }
 }
 
+/**
+ * host 侧的技能开关服务（由 lib/skill-gate/install.js 在 skills 就绪后 provide）。
+ * 与 catalog() 同样的口径：服务缺失给领域错误，不裸抛。
+ */
+function skillGate() {
+  const service = this.ctx.get(GATE_SERVICE);
+  if (service === undefined) {
+    throw this.hostUnavailable(GATE_SERVICE, "技能开关服务不可用（宿主没挂上 skills 服务，或技能开关装配失败）");
+  }
+  return service;
+}
+
 exposeRemoteMethods(TTeamRemote, [
   "getCatalog", "setEnabled", "getPrompt",
-  "getUiPrefs", "setUiPrefs",
+  // 技能开关（原 dsh-plugin-skill-gate 的两个方法，2026-09-28 并入）
+  "getSnapshot", "setDisabled",
   "createExpert", "updateExpert", "deleteExpert",
   "createCategory", "updateCategory", "deleteCategory",
 ]);

package/lib/skill-gate/constants.js

@@ -0,0 +1,4 @@
+// @ts-check
+export const name = "skill-gate";
+/** host 内部服务名；wire 命名空间是 remote 插件的 `skillGate`，两者不能撞。 */
+export const GATE_SERVICE = "skillGateHost";

package/lib/skill-gate/discover.js

@@ -0,0 +1,139 @@
+// @ts-check
+/**
+ * 扫描默认技能根（~/.dsh/skills、~/.agents/skills）。
+ *
+ * 设置页不能只靠 `ctx.skills.snapshot({})`：web 上 skill-filesystem 挂在 preset 层，
+ * 不带 scope 时全局层往往只剩宿主 runtime 注册的那几条。
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isSkillName } from "./overlay.js";
+
+/** @param {string} [configuredHome] */
+export function defaultSkillRoots(configuredHome) {
+  const dshHome = typeof configuredHome === "string" && configuredHome.trim() !== ""
+    ? configuredHome.trim()
+    : (process.env.DSH_HOME ?? join(homedir(), ".dsh"));
+  const agentsHome = process.env.DSH_AGENTS_HOME ?? join(homedir(), ".agents");
+  return [
+    { path: join(dshHome, "skills"), source: "user-dsh" },
+    { path: join(agentsHome, "skills"), source: "user-agents" },
+  ];
+}
+
+/**
+ * @param {Iterable<{ path: string, source: string }>} roots
+ * @returns {Promise<{ name: string, description: string, source: string, provider: string, invocation: { modelInvocable: boolean, userInvocable: boolean } }[]>}
+ */
+export async function scanSkillRoots(roots) {
+  /** @type {Map<string, { name: string, description: string, source: string, provider: string, invocation: { modelInvocable: boolean, userInvocable: boolean } }>} */
+  const found = new Map();
+  for (const root of roots) {
+    let entries;
+    try {
+      entries = await readdir(root.path, { withFileTypes: true });
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") continue;
+      throw error;
+    }
+    for (const entry of entries) {
+      if (entry.name === ".system" || entry.name.startsWith(".")) continue;
+      const full = join(root.path, entry.name);
+      const file = entry.isDirectory()
+        ? join(full, "SKILL.md")
+        : (entry.isFile() && entry.name.endsWith(".md") ? full : "");
+      if (file === "") continue;
+      const parsed = await readSkillSummary(file, entry.isDirectory() ? entry.name : entry.name.replace(/\.md$/u, ""));
+      if (parsed === undefined) continue;
+      if (!found.has(parsed.name)) {
+        found.set(parsed.name, {
+          ...parsed,
+          source: root.source,
+          provider: "filesystem",
+        });
+      }
+    }
+  }
+  return [...found.values()];
+}
+
+/**
+ * @param {Iterable<Iterable<{ name?: unknown } | undefined> | undefined | null>} lists
+ * @returns {object[]}
+ */
+export function mergeSkillLists(lists) {
+  /** @type {Map<string, object>} */
+  const byName = new Map();
+  for (const list of lists) {
+    if (list == null) continue;
+    for (const skill of list) {
+      if (skill === undefined || skill === null || typeof skill.name !== "string") continue;
+      if (!byName.has(skill.name)) byName.set(skill.name, skill);
+    }
+  }
+  return [...byName.values()];
+}
+
+/**
+ * @param {string} path
+ * @param {string} fallbackName
+ */
+async function readSkillSummary(path, fallbackName) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return undefined;
+    throw error;
+  }
+  const fields = parseFrontmatterScalars(raw);
+  const name = isSkillName(fields.name ?? "") ? fields.name : (isSkillName(fallbackName) ? fallbackName : "");
+  if (name === "") return undefined;
+  const nativeOff = truthy(fields["disable-model-invocation"]);
+  return {
+    name,
+    description: fields.description ?? "",
+    invocation: {
+      modelInvocable: !nativeOff,
+      userInvocable: !falsey(fields["user-invocable"]),
+    },
+  };
+}
+
+/** @param {string} raw */
+export function parseFrontmatterScalars(raw) {
+  const block = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(raw);
+  if (block === null) return {};
+  /** @type {Record<string, string>} */
+  const fields = {};
+  for (const line of block[1].split(/\r?\n/u)) {
+    const match = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/u.exec(line.trim());
+    if (match === null) continue;
+    fields[match[1]] = stripScalar(match[2]);
+  }
+  return fields;
+}
+
+/** @param {string} value */
+function stripScalar(value) {
+  const trimmed = value.trim();
+  if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+/** @param {string | undefined} value */
+function truthy(value) {
+  if (value === undefined) return false;
+  const lowered = value.trim().toLowerCase();
+  return lowered === "true" || lowered === "yes" || lowered === "1";
+}
+
+/** @param {string | undefined} value */
+function falsey(value) {
+  if (value === undefined) return false;
+  const lowered = value.trim().toLowerCase();
+  return lowered === "false" || lowered === "no" || lowered === "0";
+}