dsh-plugin-t-expert 0.4.26 → 0.4.37

package/lib/index.js

@@ -14,12 +14,14 @@ import { homedir } from "node:os";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { mkdir, stat, rmdir } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import schema from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import {
   CUSTOM_DIVISION,
   CUSTOM_LIMITS,
   catalogDivisions,
+  countExperts,
   customExpertPath,
   divisionOf,
   fileFingerprint,
@@ -38,6 +40,15 @@ import {
   truncate,
   writeFileAtomic,
 } from "./catalog.js";
+// 云端附件分发（2026-09-29）：人格留在本地，技能与数据文件按需从 OBS 拉取。
+import { annotatePersona, assetsState, ensureAssets, kickoffAssets, loadRoster, packInfoFor, ASSETS_READY } from "./fetch-assets.js";
+
+/**
+ * 插件根目录（`lib/` 的上一级）。
+ * 云端分发清单 `data/roster.json` 就放在它下面 —— 清单一律**随包走**，
+ * 不从用户数据目录读：它描述的是「哪些专家包有大附件」，与用户自己的增删无关。
+ */
+const HERE = dirname(dirname(fileURLToPath(import.meta.url)));
 // 技能开关（2026-09-28 从 dsh-plugin-skill-gate 整体搬来）：包装 ctx.skills，把名单里的技能
 // 从模型目录里摘掉。装配入口是动态 inject 调的 —— 宿主没有 skills 服务时只少这一块。
 import { installSkillGate } from "./skill-gate/install.js";
@@ -133,6 +144,8 @@ export const Config = schema.object({
   enabledSeeded: volatileField(schema.boolean().default(false)),
   /** 「默认全部启用」已按哪一版策略播种过；+1 即对所有用户重新播种一次。 */
   enabledSeedVersion: volatileField(schema.number().default(0)),
+  /** 上一次播种时见到的名册（slug）。有了它才能区分「用户停用」与「名册新增」，见 seedDefaultEnabled。 */
+  enabledSeedRoster: volatileField(schema.array(schema.string()).default([])),
   /**
    * 技能开关的名单文件（技能开关那部分的配置，2026-09-28 随它一起搬进来）。
    *
@@ -174,6 +187,18 @@ const settingsSchema = schema.object({
    * 而且置了 true 之后连改逻辑都救不回来。换成版本号后，+1 就能对所有人重新播种一次。
    */
   enabledSeedVersion: schema.number().default(0),
+  /**
+   * 上一次播种时见到的名册（slug 列表）。
+   *
+   * 为什么需要它：enabled 是白名单 —— 某位专家不在里面时，光看名单**分不清**「用户主动停用了它」
+   * 还是「当时名册里压根还没有它」。有了名册基线就能区分：只有**名册新增**的才补进 enabled，
+   * 用户停用过的（已在基线里）不会被重新打开。
+   *
+   * 2026-09-29 实测到的缺陷：导入 322 位 WorkBuddy 专家后，老用户的 enabledSeedVersion 早已是 1，
+   * 播种被版本号挡住，于是这 322 位永远进不了 @ 菜单（面板显示名册 645、@ 弹窗只有 323）。
+   * 光把版本号 +1 能修，但会连带把用户手动停用的专家全部重新打开 —— 所以改成按名册基线做增量。
+   */
+  enabledSeedRoster: schema.array(schema.string()).default([]),
 });
 
 /**
@@ -221,6 +246,13 @@ function logSeedReport(logger, seeded, dataHome) {
  * 字面量之后，名册增删或改分区之后那个 N/M 就对模型说谎，且没有任何东西会红
  * （2026-09-13 定性的恒存缺陷之一：数据更新了，模型看到的事实还是旧的）。现算 + 按目录
  * 缓存：一次 readdir 的开销，换来提示永远等于该名册的真实规模。
+ *
+ * 口径交给 `catalog.countExperts` —— 与名册扫描严格一致（目录形态专家包算 1 位、
+ * **不递归进包内**）。旧实现在这里直接 `readdirSync(root, {recursive:true})` 数所有 `.md`，
+ * 把附件里的 agents 提示词、skills 下的 SKILL.md 也算成了专家：645 位会显示成 6838 位。
+ * 当时包内快照与运行时目录都有完整附件、**两边错得一样**，所以自检没红；
+ * 2026-09-29 附件上云、包内快照瘦身后两边口径分叉，这个问题才暴露出来。
+ *
  * @param root - 名册目录（包内快照或用户数据目录）。
  * @returns 规模；目录读不到时 `experts` 为 0（调用方据此改用不带数字的说法，而不是报 0 位）。
  */
@@ -229,18 +261,7 @@ function rosterScale(root) {
   const key = typeof root === "string" ? root : "";
   const cached = rosterScaleCache.get(key);
   if (cached !== undefined) return cached;
-  let scale = { experts: 0, divisions: 0 };
-  try {
-    const divisions = readdirSync(key, { withFileTypes: true }).filter((entry) => entry.isDirectory());
-    // **递归**数 `.md`：名册里存在 `game-development/unity/<slug>.md` 这类二级分组，
-    // 只数一层会少算（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 {
-    scale = { experts: 0, divisions: 0 };
-  }
+  const scale = countExperts(key);
   rosterScaleCache.set(key, scale);
   return scale;
 }
@@ -530,31 +551,48 @@ export function apply(ctx, config) {
     }
   }
   /**
-   * 按当前策略把「默认全部启用」落到 enabled 名单上（同一策略版本对同一用户只做一次）。
+   * 把「默认启用」落到 enabled 名单上：**名册新增的专家补进去，用户自己的启停原样保留**。
    *
-   * enabled 是白名单，缺省 [] 本意是"一个都没启用"，这让新装用户得逐个开关 323 个专家。
-   * 现在只要还没按当前策略播种过，就把**全部可用专家**写进 enabled —— 不再看 enabled 是否为空：
-   * "非空"并不等于用户刻意挑过（早期版本留下的部分记录同样非空），拿它当挡箭牌会让老用户永远
-   * 停在部分启用（用户实测报过）。用户之后自己的启用/禁用不会被覆盖 —— 那时版本号已经追上来了。
+   * enabled 是白名单，缺省 [] 本意是"一个都没启用"，这让新装用户得逐个开关几百个专家。
+   * 历史上这里只看"策略版本号有没有追上"，追上就再不管了 —— 于是 2026-09-29 导入 322 位
+   * WorkBuddy 专家后，老用户（enabledSeedVersion 早就是 1）那 322 位永远进不了 @ 菜单：
+   * 面板显示名册 645，@ 弹窗只有 323。那时只能把版本号 +1 逼所有人重新播种，代价是
+   * **把用户手动停用过的专家也全部重新打开**。
+   *
+   * 现在改成按名册基线做增量：只有 `名册 - 上次见到的名册` 才补进 enabled，
+   * 用户停用过的（已在基线里）不会被重新打开；名册没变化时什么都不写。
    */
   async function seedDefaultEnabled() {
     if (settingsService === undefined) return;
     const state = readPrefs();
-    if (state === undefined || (state.enabledSeedVersion ?? 0) >= ENABLED_SEED_VERSION) return;
-    const nextEnabled = usable().map((expert) => expert.slug);
+    if (state === undefined) return;
+    const roster = usable().map((expert) => expert.slug);
     // 名册残缺（例如分区目录暂时读不到）时绝不写：否则等于用一份空名单把用户的启用项抹掉。
-    if (nextEnabled.length === 0) return;
+    if (roster.length === 0) return;
+
+    const current = state.enabled ?? [];
+    const seen = state.enabledSeedRoster ?? [];
+    // 首次运行（还没记过名册基线）拿现有 enabled 当基线：那时 enabled 里就是用户已经见过的全部，
+    // 于是「从未播种」= 整份名册都算新增（全启用），「老用户升级」= 只有新导入的那批算新增。
+    const baseline = new Set(seen.length > 0 ? seen : current);
+    const added = roster.filter((slug) => !baseline.has(slug));
+    const upToDate = (state.enabledSeedVersion ?? 0) >= ENABLED_SEED_VERSION;
+    // 名册没变化且策略版本已追上 → 不写。用户自己的启停必须原样保留。
+    if (upToDate && added.length === 0) return;
+
+    const nextEnabled = [...new Set([...current, ...added])];
     try {
       await settingsService.mutate(SETTINGS_NAMESPACE, [
         { op: "set", path: ["enabled"], value: nextEnabled },
         // 老键一并置 true：保持它在语义上的"已播种"，也免得多版本并存时两边打架。
         { op: "set", path: ["enabledSeeded"], value: true },
         { op: "set", path: ["enabledSeedVersion"], value: ENABLED_SEED_VERSION },
+        { op: "set", path: ["enabledSeedRoster"], value: roster },
       ], revision());
-      ctx.logger?.info?.(`[t-team] 已按默认策略 v${ENABLED_SEED_VERSION} 启用全部 ${nextEnabled.length} 位专家`);
+      ctx.logger?.info?.(`[t-team] 已启用 ${nextEnabled.length} 位专家（本次补入 ${added.length} 位，名册共 ${roster.length} 位）`);
     } catch (error) {
       // 写不进（并发 / 服务暂不可用）不致命：下次 ensureReady 还会再试。
-      ctx.logger?.warn?.(`[t-team] 默认启用全部专家写入失败：${String(error)}`);
+      ctx.logger?.warn?.(`[t-team] 默认启用写入失败：${String(error)}`);
     }
   }
   /** 可召唤/可展示的专家（排除重名冲突项）。 */
@@ -592,6 +630,7 @@ export function apply(ctx, config) {
     // 返回一套 "全部未启用" 的空快照会让用户以为是名册空了，而不是宿主少挂了一个服务。
     requireSettings();
     const enabled = enabledSet();
+    const roster = await rosterOnce();
     // 映射本身是同步的；只有**自建**专家需要读文件算内容指纹（await）。所以不要为了形式
     // 统一给所有专家都套 async —— 这里保留 Promise.all 是因为 custom 分支确实要 await。
     const experts = await Promise.all(usable().map(async (expert) => ({
@@ -609,6 +648,8 @@ export function apply(ctx, config) {
       custom: expert.custom === true,
       // 自建专家的内容指纹：编辑/删除时回传，拦住并发覆盖（内置专家不读文件、恒为空）。
       hash: expert.custom === true ? await fileFingerprint(expert.personaPath) : "",
+      // 云端附件状态：客户端据此给「附件未下载」的专家显示下载按钮。
+      assets: await assetsOf(expert, roster),
     })));
     return {
       experts,
@@ -646,12 +687,61 @@ export function apply(ctx, config) {
     };
   }
 
+  /** 云端分发清单只读一次（启动后不变）。读不到就当作「没有远程附件」。 */
+  let rosterPromise;
+  function rosterOnce() {
+    rosterPromise ??= loadRoster(join(HERE, "data", "roster.json"));
+    return rosterPromise;
+  }
+
+  /**
+   * 客户端要的附件状态三态：`local`（附件随包发布，没有要下载的）/ `ready`（已下载并校验）/
+   * `missing`（在云端、本地还没有 —— 面板与 `@` 弹窗据此显示「下载」按钮）。
+   */
+  async function assetsOf(expert, roster) {
+    if (expert.packDir === undefined) return "local";
+    const info = packInfoFor(roster, expert.division, expert.slug);
+    if (info === undefined) return "local";
+    return (await assetsState(expert.packDir, info)) === ASSETS_READY ? "ready" : "missing";
+  }
+
+  /**
+   * 取一位专家的 persona，并按需补两件事：
+   *
+   * 1. **路径改写**（目录形态专家）：正文里 `skills/xxx/SKILL.md` 这类相对路径的基准是
+   *    「当前会话的工作目录」而不是专家包目录，模型照抄去 Read **必然落空** —— 所以改写成
+   *    包内绝对路径，并在顶部补一段资源说明（细节见 fetch-assets.js 的 `annotatePersona`）。
+   * 2. **后台预取**（`kickoff: true` 时）：该专家有云端附件就异步拉取，**不 await** ——
+   *    人格在本地、立即可用，召唤不该被网络拖住。
+   */
+  async function preparePersona(expert, locale, { kickoff = false } = {}) {
+    const raw = await readPersona(expert, locale);
+    if (expert.packDir === undefined) return raw;   // 单文件形态：本来就没有附件
+    const roster = await rosterOnce();
+    const info = packInfoFor(roster, expert.division, expert.slug);
+    if (kickoff && info !== undefined) {
+      void kickoffAssets({
+        packDir: expert.packDir,
+        roster,
+        info,
+        onDone: (res) => ctx.logger?.info?.(`[t-team] ${expert.slug} 附件已就绪（${res.bytes ?? 0} 字节）`),
+        onError: (res) => ctx.logger?.warn?.(`[t-team] ${expert.slug} 附件拉取失败：${res.reason ?? res.status}`),
+      });
+    }
+    return annotatePersona({
+      text: raw,
+      packDir: expert.packDir,
+      slug: expert.slug,
+      remote: info !== undefined,
+    });
+  }
+
   /** 按需读取一位专家的 persona 正文。 */
   async function prompt(slug, division) {
     await ensureReady();
     const expert = usable().find((item) => item.slug === slug && item.division === division);
     if (expert === undefined) throw new Error(`找不到专家：${slug}`);
-    return { prompt: await readPersona(expert) };
+    return { prompt: await preparePersona(expert) };
   }
 
   // ---- 自建专家（面板「新建 / 编辑 / 删除」）----
@@ -899,8 +989,29 @@ export function apply(ctx, config) {
     }
   }
 
+  /**
+   * 拉取某位专家的云端附件（面板与 `@` 弹窗的「下载」按钮）。幂等：已就绪时不发网络请求。
+   * 返回 `{ status, bytes, reason }` —— `local` 表示这位专家本来就没有云端附件。
+   */
+  async function fetchAssets(slug) {
+    await ensureReady();
+    const expert = usable().find((item) => item.slug === slug);
+    if (expert === undefined) throw new Error(`找不到专家：${slug}`);
+    if (expert.packDir === undefined) return { status: "local", bytes: 0, reason: "" };
+    const roster = await rosterOnce();
+    const info = packInfoFor(roster, expert.division, expert.slug);
+    if (info === undefined) return { status: "local", bytes: 0, reason: "" };
+    const res = await ensureAssets({ packDir: expert.packDir, roster, info });
+    return {
+      status: res.status,
+      bytes: res.bytes ?? info.bytes ?? 0,
+      reason: res.reason ?? "",
+    };
+  }
+
   const catalogService = {
     snapshot, prompt, setEnabled, root: config.root,
+    fetchAssets,
     createExpert, updateExpert, deleteExpert,
     createCategory, updateCategory, deleteCategory,
   };
@@ -936,7 +1047,8 @@ export function apply(ctx, config) {
     if (!enabledSet().has(expert.slug)) {
       throw new Error(t(current, "error.expertDisabled", { name: localized(expert, current).name }));
     }
-    const persona = await readPersona(expert, current);
+    // 路径改写 + 后台预取附件（方案 A）：人格本地立即可用，技能/数据文件异步到位。
+    const persona = await preparePersona(expert, current, { kickoff: true });
     const run = await ctx.subagents.start(config.provider, {
       label: `t-team:${expert.slug}`,
       prompt: [{ type: "text", text: taskText }],
@@ -965,6 +1077,58 @@ export function apply(ctx, config) {
   }
 
   // ---- 工具 ----
+  ctx.tools.register(defineTool({
+    name: "fetch_expert_assets",
+    description: "Download a T专家 expert's companion assets (its skills, references and data files) from the cloud and unpack them locally, returning the resource root path. The expert's **persona is always available locally** — only large attachments are fetched on demand, and summoning an expert already kicks off that download in the background. Call this when you need an expert's skill or reference files and reading them from disk fails (file not found). Experts whose attachments are small ship entirely inside the package, and for those this returns immediately with status \"local\" — nothing to download.",
+    parameters: {
+      expert: {
+        type: "string",
+        required: true,
+        description: "Expert name — the Chinese display name, the English name, or its slug.",
+      },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          expert: { type: "string", required: true },
+          slug: { type: "string", required: true },
+          status: { type: "string", required: true },
+          root: { type: "string", required: true },
+          dirs: { type: "array", required: true, items: { type: "string" } },
+          bytes: { type: "number", required: true },
+          reason: { type: "string", required: true },
+        },
+      },
+      render: (args, value) => {
+        if (value.status === "ready") {
+          return [{ type: "text", text: `专家「${value.expert}」的配套资源已就绪（${value.bytes} 字节）。\n资源目录：${value.root}\n可用目录：${value.dirs.join("、") || "（无）"}\n现在可以按 persona 里给出的绝对路径读取其中的文件了。` }];
+        }
+        if (value.status === "local") {
+          return [{ type: "text", text: `专家「${value.expert}」没有云端附件 —— 它的全部内容（含技能与参考资料）本来就在本地。\n资源目录：${value.root}` }];
+        }
+        return [{ type: "text", text: `专家「${value.expert}」的配套资源拉取失败：${value.reason === "" ? "未知原因" : value.reason}\n人格不受影响、仍然可用；但依赖该专家技能或数据文件的步骤此刻做不了 —— 请如实告诉用户，不要假装读过那些文件。` }];
+      },
+    },
+    async execute(args) {
+      const current = locale();
+      await ensureReady();
+      const expert = resolveExpert(usable(), args.expert, current);
+      const name = localized(expert, current).name;
+      const base = { expert: name, slug: expert.slug, root: expert.packDir ?? config.root, dirs: [], bytes: 0, reason: "" };
+      if (expert.packDir === undefined) return { ...base, status: "local" };
+      const roster = await rosterOnce();
+      const info = packInfoFor(roster, expert.division, expert.slug);
+      if (info === undefined) return { ...base, status: "local" };
+      const res = await ensureAssets({ packDir: expert.packDir, roster, info });
+      if (res.status === ASSETS_READY) {
+        return { ...base, status: "ready", dirs: [...(info.dirs ?? [])], bytes: res.bytes ?? info.bytes ?? 0 };
+      }
+      return { ...base, status: "failed", reason: res.reason ?? res.status };
+    },
+  }));
+
   ctx.tools.register(defineTool({
     name: "list_t_experts",
     description: "List the enabled T专家 domain experts grouped by division. Without a division filter it returns division names and counts; pass a division to expand it with expert names, slugs and descriptions. Use this only to DISCOVER an expert when the user named none; if the user already named one (a leading `@专家名` chip, or an explicit name/slug), skip this and call summon_t_expert directly.",