dsh-plugin-t-expert 0.2.9 → 0.2.12

package/lib/index.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * T专家 host 插件：把 ~/.t-team/experts 里的专家名册接到 DSH。
  *
@@ -10,7 +11,7 @@
  * 与其它专家插件并存：工具名、设置命名空间、服务名、remote 服务名都不重叠。
  */
 import { homedir } from "node:os";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { stat, rmdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import schema from "@deepseek-ai/schemastery";
@@ -60,7 +61,14 @@ import { collectArchivedTeamsActivity, collectTeamsActivity } from "./teams/snap
 import { haltTeamWork } from "./teams/tools.js";
 
 export const name = NS;
-export const inject = ["tools", "subagents", "systemPrompt", "settings", "commands"];
+/**
+ * 静态注入的**只有硬依赖**：少了它们，名册功能本身就不成立（工具表、子代理、提示段）。
+ *
+ * `settings` 与 `commands` 刻意**不在这里**：它们是可选能力，cordis 遇到缺失的静态 inject
+ * 会让整个 fiber 静默 pending —— 插件一行日志都不会打，用户既看不到工具也得不到原因。
+ * 两者改为在 `apply` 里做同步能力检查（缺了只降级对应功能并 warn）。
+ */
+export const inject = ["tools", "subagents", "systemPrompt"];
 
 /**
  * 插件配置。
@@ -125,36 +133,143 @@ const settingsSchema = schema.object({
   enabled: schema.array(schema.string()).default([]),
 });
 
+/**
+ * 把启动期名册同步的结果写进日志：**送达的内容要留痕，送不到的内容要出声**。
+ *
+ * 为什么单独成函数：旧实现只有一句 `copied.length > 0` 才打印的 info —— 于是「升级后
+ * 包内新增的专家/小队/译文一个都没到达」这件事在日志里**完全不存在**（2026-09-13 定性的
+ * 恒存缺陷）。这里把「漂移状态变化」变成唯一告警条件：既不静默，也不每次启动刷屏。
+ * @param logger - `ctx.logger`（可能缺席）。
+ * @param seeded - `seedData` 的报告。
+ * @param dataHome - 数据目录（日志里给人看的位置）。
+ */
+function logSeedReport(logger, seeded, dataHome) {
+  const sample = (list) => (list.length === 0 ? "" : `，如 ${list.slice(0, 3).join("、")}${list.length > 3 ? " 等" : ""}`);
+  const mergedKeys = seeded.merged.reduce((sum, item) => sum + item.keys.length, 0);
+  const delivered = seeded.copied.length + seeded.updated.length + mergedKeys;
+  const versionNote = seeded.previousVersion !== "" && seeded.previousVersion !== seeded.version
+    ? `（包内快照 v${seeded.previousVersion} → v${seeded.version}）`
+    : "";
+
+  if (delivered > 0 || versionNote !== "") {
+    const parts = [];
+    if (seeded.copied.length > 0) parts.push(`新增 ${seeded.copied.length} 项${sample(seeded.copied)}`);
+    if (seeded.updated.length > 0) parts.push(`对齐只读条目 ${seeded.updated.length} 项${sample(seeded.updated)}`);
+    if (mergedKeys > 0) parts.push(`补齐键 ${mergedKeys} 个${sample(seeded.merged.flatMap((item) => item.keys))}`);
+    logger?.info?.(`[t-team] 名册快照已同步到 ${dataHome}${versionNote}：${parts.join("；") || "无内容变更"}`);
+  }
+
+  // 送不到的必须出声：只在「与上次记录相比有变化」时告警一次，避免每次启动刷屏。
+  if ((seeded.kept.length > 0 || seeded.stale.length > 0) && seeded.driftChanged) {
+    const parts = [];
+    if (seeded.kept.length > 0) parts.push(`${seeded.kept.length} 项与包内快照不同${sample(seeded.kept)}`);
+    if (seeded.stale.length > 0) parts.push(`${seeded.stale.length} 项包内已移除${sample(seeded.stale)}`);
+    logger?.warn?.(
+      `[t-team] 名册快照有${parts.join("、")}；已按「不覆盖你的内容」保留盘上那份，未做任何覆盖。`
+      + "若这些不是你改的，删掉对应文件后重启即可重新播种。",
+    );
+  }
+}
+
+/**
+ * 包内名册的规模（专家数 / 分区数），**从名册目录现算**并按目录缓存。
+ *
+ * 为什么不能写死：提示段是**模型可见的事实**。「a 316-expert, 22-division roster」这类字面量
+ * 在名册增删改分区之后就对模型说谎，而且没有任何东西会红（2026-09-13 定性的恒存缺陷之一：
+ * 数据更新了，模型看到的事实还是旧的）。现算 + 按目录缓存：一次 readdir 的开销，换来提示
+ * 永远等于该名册的真实规模。
+ * @param root - 名册目录（包内快照或用户数据目录）。
+ * @returns 规模；目录读不到时 `experts` 为 0（调用方据此改用不带数字的说法，而不是报 0 位）。
+ */
+const rosterScaleCache = new Map();
+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 实测：一层 301 / 递归 316，与 README、source.json、
+    // zh/names.json 的 316 一致）。分区数只取一级目录 —— 二级目录是分组不是分区。
+    const experts = readdirSync(key, { recursive: true }).filter((name) => String(name).endsWith(".md")).length;
+    scale = { experts, divisions: divisions.length };
+  } catch {
+    scale = { experts: 0, divisions: 0 };
+  }
+  rosterScaleCache.set(key, scale);
+  return scale;
+}
+
 export function apply(ctx, config) {
   const locale = () => readLocale(ctx);
   const maxDepth = config.maxDepth;
 
-  // ---- 首次启动播种：包内自带名册快照 → 可写数据目录（非破坏性，已有内容不动）----
+  // ---- 启动期同步：包内自带名册快照 → 可写数据目录（缺失就补、只读对齐、用户内容不动）----
   // 必须在下面同步读取 t-team.config.json / teams.json 之前完成，否则首次安装会读到空配置。
   const seeded = seedData({ root: config.root, zhRoot: config.zhRoot });
-  if (seeded.copied.length > 0) {
-    ctx.logger?.info?.(`[t-team] 已把包内名册快照播种到 ${dirname(config.root)}（${seeded.copied.join(", ")}）`);
-  }
+  logSeedReport(ctx.logger, seeded, dirname(config.root));
   if (!seeded.ok) {
-    // 播种失败不当作致命：名册目录若因此缺失，第一次读名册会在 ensureReady() 里**响亮地**抛出
+    // 同步失败不当作致命：名册目录若因此缺失，第一次读名册会在 ensureReady() 里**响亮地**抛出
     // （error.rootMissing），那才是最早可解析点。这里只保证失败一定会出现在日志里。
-    ctx.logger?.error?.(`[t-team] 名册快照播种失败，将按已有数据继续：${seeded.error}`);
+    ctx.logger?.error?.(`[t-team] 名册快照同步失败，将按已有数据继续：${seeded.error}`);
   }
 
   // ---- 设置段（T专家 自己的命名空间，与其它插件不冲突）----
-  const scope = ctx.settings.register(SETTINGS_NAMESPACE, settingsSchema, {
-    base: { enabled: [] },
-    applies: "live",
-    validate: (value) => {
-      const list = value?.enabled;
-      if (!Array.isArray(list) || list.some((item) => typeof item !== "string")) {
-        throw new Error("t-team.enabled 必须是字符串数组");
+  // `settings` 是**可选**服务（见文件顶部的 inject 注释）：宿主没挂它时本插件仍要能加载并工作，
+  // 所以不在静态 `inject` 里。
+  //
+  // ⚠️ 但**不能**用 `ctx.get("settings")` 做同步探测（2026-09-13 实测踩到）：把 settings 移出静态
+  // inject 之后，`apply` 不再等待 settings 就绪，于是那一刻 `ctx.get("settings")` 是 undefined；
+  // 而 cordis 的 `provide` **不会回溯通知**已经跑过的同步代码，于是这个判断**永久**为假 ——
+  // 真实 GUI 里表现为「设置段没注册 → 点 T专家 是白板」（host 日志有对应 warn）。
+  //
+  // 正解是用 cordis 的 `ctx.inject`：它等的就是「该服务就绪」这件事，服务迟到也能补上。
+  // `ctx.inject(["settings"])` 同时保留了「宿主真没有 settings 就不注册、只降级」的语义。
+  /** @type {undefined | { get: () => any }} 设置段句柄；由下面的 inject 在 settings 就绪时赋值。 */
+  let scope;
+  /** @type {any} settings 服务本体；就绪后由 inject 赋值，`requireSettings()` 用它。 */
+  let settingsService;
+  if (typeof ctx.inject !== "function") {
+    // 只可能出现在极简/测试上下文里：如实说明，不要静默。
+    ctx.logger?.warn?.("[t-team] 上下文没有 inject：无法等待 settings 就绪，专家启停不可用。");
+  } else {
+    // 先如实说一句"在等 settings"：`ctx.inject` 对**永不出现**的服务不会有任何回调，
+    // 所以只在回调里告警的话，宿主真没给 settings 时用户/日志里**什么都看不到**（实测如此）。
+    // 服务随后到了就正常注册；一直没到，这行就是唯一的原因线索。
+    ctx.logger?.warn?.("[t-team] 正在等待 settings 服务就绪以注册设置段；若宿主不提供它，专家启停与设置页的 T专家 段将不可用。");
+    ctx.inject(["settings"], (scoped) => {
+      settingsService = scoped.settings ?? scoped.get?.("settings");
+      if (typeof settingsService?.register !== "function") {
+        ctx.logger?.warn?.("[t-team] settings 服务没有 register：专家启停不可用（名册与召唤不受影响）。");
+        return;
       }
-    },
-  });
+      scope = settingsService.register(SETTINGS_NAMESPACE, settingsSchema, {
+        base: { enabled: [] },
+        applies: "live",
+        validate: (value) => {
+          const list = value?.enabled;
+          if (!Array.isArray(list) || list.some((item) => typeof item !== "string")) {
+            throw new Error("t-team.enabled 必须是字符串数组");
+          }
+        },
+      });
+    });
+  }
   const enabledSet = () => new Set(
-    (scope.get()?.enabled ?? []).filter((value) => typeof value === "string"),
+    (scope?.get?.()?.enabled ?? []).filter((value) => typeof value === "string"),
   );
+  /**
+   * 需要读写「专家启停」的路径在 settings 缺席时必须**响亮失败**。
+   *
+   * 为什么不能给个空集合凑合：那样 `list_t_experts` 会返回 `total=0`、readonly 工具报「未启用」，
+   * 用户与模型都以为「名册是空的 / 什么都没开」，而不是「宿主没挂 settings」—— 正是要被消灭的
+   * 那类静默错误。异常经工具错误面报出，原因可读（A-4）。
+   */
+  const requireSettings = () => {
+    if (settingsService === undefined) throw new Error(t(locale(), "error.settingsServiceMissing"));
+    return settingsService;
+  };
 
   // ---- 花名册加载 ----
   let entries = [];
@@ -249,6 +364,36 @@ export function apply(ctx, config) {
       await loading;
     }
     if (loadError !== null) throw loadError;
+    await pruneStaleEnabled();
+  }
+  /**
+   * 清掉设置里**名册已不存在**的 slug（C-6）。
+   *
+   * 为什么必须清：`enabled` 只是 slug 列表，专家被删（自建专家删除、名册升级）后旧 slug 会留下。
+   * 后果不是"多一条无用配置"，而是 `list_t_experts` 的 `total` 取 `enabled.size`、与真正展示出来的
+   * 条数**对不上**（用户看到「共 3 位」却只列出 2 位），而且没有任何地方会说明原因。
+   *
+   * 只在 settings 可用时清；清完写回并留一条 warn（用户的启用列表被改动过，应该看得见）。
+   * 防误清靠「名册为空就不动」那条判断（见下），不靠"只清一次"。
+   */
+  async function pruneStaleEnabled() {
+    if (settingsService === undefined) return;
+    const known = new Set(entries.map((expert) => expert.slug));
+    const list = [...enabledSet()];
+    const stale = list.filter((slug) => !known.has(slug));
+    if (stale.length === 0) return;
+    // 名册为空说明这次 load 是残缺的（例如分区目录暂时读不到），此时**不要**清 ——
+    // 否则一次临时故障会把用户全部启用项抹掉。
+    if (known.size === 0) return;
+    try {
+      const next = list.filter((slug) => known.has(slug));
+      await settingsService.mutate(SETTINGS_NAMESPACE, [{ op: "set", path: ["enabled"], value: next }], revision());
+      ctx.logger?.warn?.(`[t-team] 已从启用列表移除 ${stale.length} 个名册里不存在的 slug：${stale.slice(0, 5).join(", ")}`
+        + `${stale.length > 5 ? " …" : ""}（名册升级或自建专家删除后的收尾）`);
+    } catch (error) {
+      // 清不掉不影响可用性（那些 slug 本来也不会被展示），但不能因为并发冲突把加载搞挂。
+      ctx.logger?.warn?.(`[t-team] 启用列表里的失效 slug 未能清理：${String(error)}`);
+    }
   }
   /** 可召唤/可展示的专家（排除重名冲突项）。 */
   const usable = () => entries.filter((expert) => expert.conflict !== true);
@@ -271,7 +416,9 @@ export function apply(ctx, config) {
 
   // ---- 设置段修订号与写入 ----
   const revision = () => {
-    const descriptor = ctx.settings.describe().find((item) => item.ns === SETTINGS_NAMESPACE);
+    // settings 是可选服务：缺它时给出同一个可读错误（error.settingsMissing），
+    // 而不是 `Cannot read properties of undefined` 这种对用户毫无意义的 TypeError。
+    const descriptor = settingsService?.describe?.().find((item) => item.ns === SETTINGS_NAMESPACE);
     if (descriptor === undefined) throw new Error(t(locale(), "error.settingsMissing"));
     return descriptor.revision;
   };
@@ -279,7 +426,13 @@ export function apply(ctx, config) {
   /** 客户端面板用的名册快照。 */
   async function snapshot() {
     await ensureReady();
-    const enabled = enabledSet();    const experts = await Promise.all(usable().map(async (expert) => ({
+    // 走工具面的读路径在 settings 缺席时响亮失败（见 requireSettings 的说明）：
+    // 返回一套 "全部未启用" 的空快照会让用户以为是名册空了，而不是宿主少挂了一个服务。
+    requireSettings();
+    const enabled = enabledSet();
+    // 映射本身是同步的；只有**自建**专家需要读文件算内容指纹（await）。所以不要为了形式
+    // 统一给所有专家都套 async —— 这里保留 Promise.all 是因为 custom 分支确实要 await。
+    const experts = await Promise.all(usable().map(async (expert) => ({
       // 面板按 locale 取字段：name/description 为中文（缺译回退英文），nameEn/descriptionEn 恒为英文。
       slug: expert.slug,
       name: expert.nameZh ?? expert.name,
@@ -344,6 +497,7 @@ export function apply(ctx, config) {
   // 往里写自建专家会在下次同步时被当成"意外文件"删掉。
   /** 带业务码的错误：remote 的 businessError 会原样透传 code 给面板。 */
   function customError(codeKey, params = {}) {
+    /** @type {Error & { code?: string }} */
     const error = new Error(t(locale(), codeKey, params));
     error.code = `tTeam/${codeKey.replace(/^error\./, "").replace(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`)}`;
     return error;
@@ -549,7 +703,7 @@ export function apply(ctx, config) {
     // 删除后把该专家从启用列表里摘掉，否则设置段会留下一个指向空气的 slug
     const enabled = [...enabledSet()].filter((item) => item !== slug);
     if (enabled.length !== enabledSet().size) {
-      await ctx.settings.mutate(SETTINGS_NAMESPACE, [{ op: "set", path: ["enabled"], value: enabled }], revision());
+      await settingsService.mutate(SETTINGS_NAMESPACE, [{ op: "set", path: ["enabled"], value: enabled }], revision());
     }
     await refreshCatalog();
     return await snapshot();
@@ -564,12 +718,13 @@ export function apply(ctx, config) {
       // 稳定 code（不是显示文案）：remote 侧按它分类成 tTeam/unknown-expert，与 locale 无关（D-3）。
       // 文案走正确的 t() 通道（过去这里也是硬编码中文，非中文 locale 下会中英混排）。
       const slugs = unknown.slice(0, 5);
+      /** @type {Error & { code?: string, details?: { slugs: string[] } }} */
       const error = new Error(t(locale(), "error.customUnknownSlug", { slugs: slugs.join(", ") }));
       error.code = UNKNOWN_SLUG_ERROR_CODE;
       error.details = { slugs };
       throw error;
     }
-    await ctx.settings.mutate(SETTINGS_NAMESPACE, [{ op: "set", path: ["enabled"], value: list }], expectedRevision);
+    await settingsService.mutate(SETTINGS_NAMESPACE, [{ op: "set", path: ["enabled"], value: list }], expectedRevision);
     return { enabled: [...enabledSet()], revision: revision() };
   }
 
@@ -586,11 +741,13 @@ export function apply(ctx, config) {
     snapshot, prompt, setEnabled, root: config.root,
     createExpert, updateExpert, deleteExpert,
     createCategory, updateCategory, deleteCategory,
-  };  ctx.reflect.provide(CATALOG_SERVICE, catalogService);
+  };
+  ctx.reflect.provide(CATALOG_SERVICE, catalogService);
 
   // ---- 召唤 ----
   async function runExpert(query, task, exec) {
     const current = locale();
+    requireSettings();
     const taskText = String(task ?? "").trim();
     if (taskText === "") throw new Error(t(current, "error.taskEmpty"));
     if ([...taskText].length > config.summonTaskMaxChars) {
@@ -691,6 +848,7 @@ export function apply(ctx, config) {
     async execute(args) {
       await ensureReady();
       const current = locale();
+      requireSettings();
       const query = args.division === undefined ? "" : String(args.division).trim();
       const enabled = enabledSet();
       const groups = groupByDivision(usable(), enabled);
@@ -730,6 +888,10 @@ export function apply(ctx, config) {
   ctx.tools.register(defineTool({
     name: "summon_t_expert",
     description: "Summon one T专家 domain expert to complete a task: a specialist subagent runs with that expert's full persona and returns its result. Use it for tasks that clearly belong to a specialist domain. This call waits for the result. Call list_t_experts first when the expert name is unknown.",
+    // 预算声明：单次召唤给 10 分钟。**注意它只是声明**（`dsh-tools` 的 registry 不强制 deadline），
+    // 真正生效要宿主装配 `@deepseek-ai/dsh-tool-call-timeout-policy`；这里写出来是为了让
+    // 「最坏要等多久」有个明确契约，而不是无界挂起。
+    timeoutMs: 600_000,
     parameters: {
       expert: { type: "string", required: true, description: "Expert name to summon — the Chinese display name (e.g. \"前端开发者\"), the English name (e.g. \"Frontend Developer\"), or its slug (e.g. engineering-frontend-developer). Copy the name exactly as list_t_experts returned it." },
       task: { type: "string", required: true, description: "The complete, self-contained task to give the expert. Include all necessary context." },
@@ -754,6 +916,9 @@ export function apply(ctx, config) {
   ctx.tools.register(defineTool({
     name: "summon_t_experts",
     description: `Summon multiple T专家 experts in parallel for one mission. At most ${config.maxSummonBatch} experts run with concurrency ${config.summonConcurrency}; successful answers are returned even when some fail.`,
+    // 预算声明：批量最坏是 ceil(批大小 / 并发) 轮串行，给 20 分钟。
+    // 与单次召唤同理，它只是声明，强制 deadline 需要宿主装配 timeout-policy wrapper。
+    timeoutMs: 1_200_000,
     parameters: {
       experts: {
         type: "array",
@@ -825,32 +990,64 @@ export function apply(ctx, config) {
     : ["t-team.config.json", "agent-teams.config.json"]
       .map((file) => join(engineConfigDir, file))
       .find((candidate) => existsSync(candidate)) ?? join(engineConfigDir, "t-team.config.json");
-  let engineConfig = {};
-  let engineConfigDetail = "";
-  // 配置错误要响亮：**文件存在但内容不合法**属于自带的错配，直接让插件加载失败，
-  // 而不是带着空配置把团队功能静默降级。文件不存在是"还没生成小队"（自定义 root 时合法），
-  // 这种情况明确降级，并把原因送到所有可见面（日志 + /t + 下面的 engine-status 提示段）。
-  if (existsSync(engineConfigPath)) {
+  /**
+   * 读并解析引擎配置（**每次调用都重新读盘**）。
+   *
+   * 为什么必须是函数而不是启动期的一个常量：热重载要在保存小队后重新读这份文件。启动期快照
+   * 正是「改一项要重启」的成因（audit/01-spec-checklist.md:235）。
+   *
+   * 失败形态刻意分开（两条路径都不可静默）：
+   *   · 文件不存在 → `{ config: {}, detail: "..." }`：还没生成过小队是**合法状态**（自定义 root
+   *     的部署就是这样），降级但把原因送到日志/`/t`/系统提示段；
+   *   · 存在但内容不合法 → `{ config: null, failure: "..." }`：自带错配，**必须响亮**。
+   *     启动路径沿用旧行为（直接让插件加载失败），热重载路径见 `reloadEngine()`（失败则保留旧
+   *     引擎并留可诊断信号）。
+   */
+  const loadEngineConfig = () => {
+    if (!existsSync(engineConfigPath)) {
+      return { config: {}, failure: "", detail: `找不到团队引擎配置 ${engineConfigPath}（跑一次 team-profiles.py 生成小队后即可用 /t 拉起团队）` };
+    }
     let parsed;
     try {
       parsed = JSON.parse(readFileSync(engineConfigPath, "utf8"));
     } catch (error) {
-      throw new Error(`团队引擎配置无法解析：${engineConfigPath}（${error instanceof Error ? error.message : String(error)}）。它是 team-profiles.py 的产物，删掉后重跑一次即可重建。`);
+      return { config: null, failure: `团队引擎配置无法解析：${engineConfigPath}（${error instanceof Error ? error.message : String(error)}）。它是 team-profiles.py 的产物，删掉后重跑一次即可重建。`, detail: "" };
     }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-      throw new Error(`团队引擎配置必须是 JSON 对象：${engineConfigPath}`);
+      return { config: null, failure: `团队引擎配置必须是 JSON 对象：${engineConfigPath}`, detail: "" };
     }
     if (parsed.profiles !== undefined && (parsed.profiles === null || typeof parsed.profiles !== "object" || Array.isArray(parsed.profiles))) {
-      throw new Error(`团队引擎配置的 profiles 必须是对象：${engineConfigPath}`);
+      return { config: null, failure: `团队引擎配置的 profiles 必须是对象：${engineConfigPath}`, detail: "" };
     }
-    engineConfig = parsed;
-  } else {
-    engineConfigDetail = `找不到团队引擎配置 ${engineConfigPath}（跑一次 team-profiles.py 生成小队后即可用 /t 拉起团队）`;
-  }
+    return { config: parsed, failure: "", detail: "" };
+  };
+  const initialEngineConfig = loadEngineConfig();
+  if (initialEngineConfig.failure !== "") throw new Error(initialEngineConfig.failure);
   // 引擎与名册解耦：引擎挂载失败（例如 Harness 子代理契约不匹配）时，
   // T专家 的专家名册、@ 召唤、/t 列表仍然可用，只是团队功能不可用。
   // 这是**已声明的降级**，不是静默跳过：原因会写进日志、经 /t 报出，并进系统提示段。
-  const engineState = { ok: false, detail: engineConfigDetail };
+  //
+  // `engineConfig` / `engineFiber` 是热重载的**活状态**（不是启动期快照）：
+  //   · `engineConfig` —— 当前挂载所用的配置对象；每次成功重挂会换成新解析出来的对象；
+  //   · `engineFiber` —— 当前引擎 fiber；重载时 dispose 它，再用新配置 `ctx.plugin()` 重挂；
+  //   · `lastMountError` —— 最近一次挂载/重挂失败的原因，挂载成功时清空。
+  // 三者都刻意与 `Config` 分开：它们是**运行态**，`Config` 只提供不随小队定义变化的那几个标量。
+  let engineConfig = initialEngineConfig.config;
+  let engineFiber;
+  let lastMountError = "";
+  const engineState = {
+    ok: false,
+    detail: initialEngineConfig.detail,
+    /**
+     * 最近一次**热重载失败**的原因（成功时清空）。
+     *
+     * 与 `lastMountError` 分开是有意的：热重载失败时**旧引擎仍然可用**，所以不能把引擎整体报成
+     * "不可用"（那会让用户以为团队功能全没了）；但"盘上是新小队、运行中的引擎还是旧的"这件事
+     * 必须对模型/用户可见 —— 否则用户会看到 `/t` 列着新小队、却用它建不出队，正是本任务要消灭
+     * 的那个分叉。提示段靠它区分「引擎从未挂载过」与「挂载过、但这次热重载失败」。
+     */
+    reloadFailure: "",
+  };
   /** 首次探到「调度成功但工具没注册」时的告警只打一次（此后每轮都探，但不再刷日志）。 */
   let engineNotReadyWarned = false;
   const NOT_READY_DETAIL = "内置团队引擎的工具没有注册成功（引擎可能还在等待它声明的宿主服务）";
@@ -865,8 +1062,8 @@ export function apply(ctx, config) {
    *
    * **探测时机很关键**：宿主里子插件的 fiber 可能在同一同步段末尾、也可能更晚才激活，
    * 所以**不在 mount 的那一刻探**（那一刻必然探空，会把每次正常启动都误报成降级）。
-   * 探测发生在所有真实读取点（系统提示段 / `/t` 命令），那时引擎早已定局；且每一轮都重新探，
-   * 只在**第一次**探到假时补一条 warn，避免刷日志。两处可见面共用它，不会再分叉。
+   * 探测发生在所有真实读取点（系统提示段 / `/t` 命令 / 热重载收口），那时引擎早已定局；
+   * 且每一轮都重新探，只在**第一次**探到假时补一条 warn，避免刷日志。
    * @returns 引擎工具是否已注册。
    */
   const engineReady = () => {
@@ -884,34 +1081,125 @@ export function apply(ctx, config) {
     }
     return present;
   };
-  /** 给用户/模型的原因：挂载明明抛错就报那个错，否则报「工具没注册」。 */
-  const engineUnreadyDetail = () => (engineState.detail === "" ? NOT_READY_DETAIL : engineState.detail);
-  if (engineConfigDetail === "") {
-    try {
-      ctx.plugin(teamsEngine, {
-        stateDir: config.stateDir,
-        memberProvider: config.memberProvider,
-        ...(config.memberModel === undefined ? {} : { memberModel: config.memberModel }),
-        ...(engineConfig.memberMaxDepth === undefined ? {} : { memberMaxDepth: engineConfig.memberMaxDepth }),
-        maxMembers: config.maxMembers,
-        // 引擎自带命令必须关掉：T专家 自己注册 /t（带小队别名解析），否则两个同名命令相撞。
-        // 手势边界另外复用（见下），它是队长协议真正被触发的地方。
-        slashCommand: false,
-        profiles: engineConfig.profiles ?? {},
-      });
-      // 复用引擎导出的手势边界：把 `/t --profile <小队> <目标>` 这条用户消息翻成队长协议指令。
-      installTTeamGestureBoundary(ctx, () => engineConfig.profiles ?? {});
-      // 只记录「调度成功」。**不要**在这里同步探测工具是否已注册：cordis 的子插件 fiber
-      // 尚未激活，此刻必然探空 → 会把每一次正常启动都误报成降级（本改动实测踩到过）。
-      // 真机探测推迟到读取点（engineReady()）。
+  /** 给用户/模型的原因：挂载/重挂抛错就报那个错，否则报「工具没注册」。 */
+  const engineUnreadyDetail = () => (lastMountError !== "" ? lastMountError : engineState.detail !== "" ? engineState.detail : NOT_READY_DETAIL);
+  /** 引擎挂载参数。**每次挂载现算**：`profiles` 从活取的 `engineConfig` 里取，所以重挂必然带新小队。 */
+  const teamsEngineArgs = () => ({
+    stateDir: config.stateDir,
+    memberProvider: config.memberProvider,
+    ...(config.memberModel === undefined ? {} : { memberModel: config.memberModel }),
+    ...(engineConfig.memberMaxDepth === undefined ? {} : { memberMaxDepth: engineConfig.memberMaxDepth }),
+    maxMembers: config.maxMembers,
+    // 引擎自带命令必须关掉：T专家 自己注册 /t（带小队别名解析），否则两个同名命令相撞。
+    // 手势边界另外复用（见下），它是队长协议真正被触发的地方。
+    slashCommand: false,
+    profiles: engineConfig.profiles ?? {},
+  });
+  /**
+   * 安装手势边界（`/t --profile <小队> <目标>` → 队长协议指令），**恰好一次**。
+   *
+   * 只在引擎真的挂上之后装：边界生成的是"按这支小队建队"的指令，引擎不可用时装了也只会把用户
+   * 消息翻成一条建不成的指令（旧行为如此，这里刻意保持）。传的是**活取值函数**而不是当前
+   * profiles 对象：热重载后它立刻读到新小队目录，不必重装监听器。
+   */
+  let gestureBoundaryInstalled = false;
+  const installGestureBoundaryOnce = () => {
+    if (gestureBoundaryInstalled) return;
+    installTTeamGestureBoundary(ctx, () => engineConfig.profiles ?? {});
+    gestureBoundaryInstalled = true;
+  };
+  try {
+    // 首次挂载（启动期读不到配置就降级，不假装就绪；原因见 prompt 段与日志）。
+    if (initialEngineConfig.detail === "") {
+      engineFiber = ctx.plugin(teamsEngine, teamsEngineArgs());
       engineState.ok = true;
-    } catch (error) {
-      engineState.detail = error instanceof Error ? error.message : String(error);
-      ctx.logger?.error?.(`[t-team] 团队引擎挂载失败（专家名册功能不受影响）：${engineState.detail}`);
+      installGestureBoundaryOnce();
+    } else {
+      ctx.logger?.error?.(`[t-team] ${initialEngineConfig.detail}`);
     }
-  } else {
-    ctx.logger?.error?.(`[t-team] ${engineConfigDetail}`);
+  } catch (error) {
+    engineState.ok = false;
+    lastMountError = error instanceof Error ? error.message : String(error);
+    ctx.logger?.error?.(`[t-team] 团队引擎挂载失败（专家名册功能不受影响）：${lastMountError}`);
   }
+  /**
+   * 团队引擎热重载：保存小队（编译成功后）由小队服务敲门。
+   *
+   * 这是「不重启就能用新小队建队」的收口点。之所以能成立：引擎的 13 个工具、提示段与命令
+   * 都注册在自己的 fiber 下（走 effect），换配置重挂就是「先卸载旧的、再用新 profiles 跑一次
+   * apply」——引擎注册面与卸载面都不需要改代码。
+   *
+   * 为什么用 `dispose()` + 重新 `plugin()`，而不是 `fiber.update(config)`：两者在本仓库当前装的
+   * cordis 4.0.2 上**都实测可用**（同一份真机探针各跑一遍，见交付说明），区别只在语义强弱：
+   *   · `update()` 复用同一条 fiber，由框架按"先卸载旧 effect、再用新 config apply"重载，最贴近
+   *     框架本意（设置页与 HMR 走的就是它）；但它要求"插件注册的每一条都挂在同一条 fiber 的
+   *     effect 上"。本插件是"插件里又挂子插件"的形态（引擎的 apply 里还有工具/提示段/命令/子
+   *     fiber），注册面越大，越容易被后来新增的、不走 effect 的注册悄悄破坏 —— 本轮就真的被
+   *     误导过一次：探针桩漏了 effect 包裹，`update()` 立刻撞 `tool "t_team_create" is already
+   *     registered in this scope`，看着像框架缺陷、其实是被测面自己没走 effect。
+   *   · `dispose()` 会 await 整棵子树的卸载，之后再 `plugin()` 是一个全新的 fiber —— 不存在
+   *     "旧 effect 残留"这一类问题，代价只是多创建一次 fiber。
+   * 小队重载是低频操作（用户点一次保存），这里选**更难用错**的那条：以后注册面变大也不会悄悄失效。
+   * 若将来有理由改回 `update()`，探针（reload-probe.mjs）对两者都成立，换实现只需重跑它。
+   *
+   * 语义（对应任务的失败/并发要求）：
+   *   · 配置读不出来（不存在/解析失败/类型不对）→ **不重挂**，保留旧引擎继续可用，`ok:false`
+   *     带原因返回；下一次保存成功会重新对齐。
+   *   · `dispose()` 抛错 → 引擎此刻确实不在了，`ok:false` 且 `engineState.ok=false`（提示段会
+   *     报「引擎不可用」，不假装就绪）；但**已保存的配置不会回滚**（它不是坏定义，只是引擎没起来）。
+   *   · 重挂抛错 → 同上，但已经尝试过重新挂载，`engineState.ok` 如实反映结果。
+   *   · 全程不向上抛（保存已经成功，抛错会让用户以为没保存成）。
+   * @returns `{ ok, detail }`：`detail` 只在失败时非空，且必须是**可操作**的原因。
+   */
+  const reloadEngine = async () => {
+    /** 重载失败的统一收口：留在提示段与日志里（"引擎还在用旧小队"与"引擎整个没了"要分清）。 */
+    const reloadFailed = (detail) => {
+      engineState.reloadFailure = detail;
+      ctx.logger?.error?.(`[t-team] 小队已保存，但团队引擎热重载失败：${detail}`);
+      return { ok: false, detail };
+    };
+    const fresh = loadEngineConfig();
+    if (fresh.failure !== "" || fresh.config === null) {
+      // 不换 `engineConfig`：读不出来就当这次重载没发生过，旧引擎继续用旧配置，可用性不变。
+      return reloadFailed(fresh.failure);
+    }
+    engineConfig = fresh.config;   // 无论 mount 是否成功都换：新配置就是事实，否则会永远重装旧快照。
+    engineState.detail = fresh.detail;
+    const previousFiber = engineFiber;
+    if (previousFiber !== undefined) {
+      // 先断开引用：dispose 抛错时不能留着一个已死的 fiber 被后续重载再 dispose 一次。
+      engineFiber = undefined;
+      try {
+        await previousFiber.dispose();
+      } catch (error) {
+        engineState.ok = false;
+        engineState.reloadFailure = "";
+        return reloadFailed(`卸载旧引擎失败：${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    try {
+      const next = ctx.plugin(teamsEngine, teamsEngineArgs());
+      engineFiber = next;
+      await next;   // fiber 是 thenable：await 它等价于等 apply 落定。
+    } catch (error) {
+      engineFiber = undefined;
+      engineState.ok = false;
+      lastMountError = error instanceof Error ? error.message : String(error);
+      return reloadFailed(`重新挂载引擎失败：${lastMountError}`);
+    }
+    // 定局探测（engineReady 同样只报一次「工具未注册」的 warn，避免刷日志）。
+    if (ctx.tools.get("t_team_create") === undefined && engineState.ok !== true) {
+      // apply 抛过错 → 引擎真的没起来；服务不齐（正常生命周期）在这里不算失败：cordis 会在
+      // 服务回来时自己重载那条 fiber。
+      return reloadFailed(engineUnreadyDetail());
+    }
+    engineState.ok = true;
+    lastMountError = "";
+    engineState.reloadFailure = "";
+    // 启动期因"还没有小队配置"而没挂上时，这里补装手势边界：现在引擎已经起来了。
+    installGestureBoundaryOnce();
+    return { ok: true, detail: "" };
+  };
 
   // 已声明的降级也要**对模型可见**：否则"团队功能没了"这件事只留在日志里，
   // 用户问起来模型只能说不知道 —— 那正是规范禁止的"静默跳过缺失的引用对象"。
@@ -921,7 +1209,16 @@ export function apply(ctx, config) {
     order: 120,
     text: (context) => {
       if (context.agent?.session?.header?.parentSession !== undefined) return "";
-      if (engineReady()) return "";
+      if (engineReady()) {
+        // 引擎可用、但上一次热重载没成功：盘上的小队定义已经变了，运行中的引擎还是旧的。
+        return engineState.reloadFailure === ""
+          ? ""
+          : [
+            "## T专家 小队定义已保存，但团队引擎没有换成新配置",
+            `这次保存已经生效（/t 列表就是新定义），但引擎仍在使用上一次的小队配置，所以用新改的小队建队会失败。原因：${engineState.reloadFailure}`,
+            "需要重新保存一次小队定义让引擎再试一次，或重启 DSH。用户问起时请原样转述上面的原因。",
+          ].join("\n");
+      }
       return [
         "## T专家 团队引擎当前不可用",
         `团队功能（/t 建队、t_team_* 工具）现在不可用。原因：${engineUnreadyDetail()}`,
@@ -932,17 +1229,25 @@ export function apply(ctx, config) {
 
   // ---- 小队定义服务（设置页「小队」标签用；写回 teams.json 后自动重跑 team-profiles.py）----
   const teamsFile = join(dirname(config.root), "teams.json");
+  // 编译器**只认包内那份**（随插件版本走）。刻意**不再回退**数据目录里的 `team-profiles.py`：
+  // 那份是 bootstrap 播种的用户可写文件，会让「保存小队」变成「执行用户可写脚本」——
+  // 同用户权限下的代码执行面，且它与包内版本的漂移无法校验。裁剪安装（包内被删）时
+  // 小队编译会**响亮失败**（原因经 logger 与面板可见），而不是悄悄执行另一份文件（C-3）。
+  const packagedGenerator = join(SNAPSHOT_DIR, "team-profiles.py");
   const squads = createSquadService({
     teamsFile,
     catalog: catalogService,
-    // 编译器优先用包内那份（随插件版本走）；包内没有（例如被裁剪的安装）才回退数据目录。
-    generator: existsSync(join(SNAPSHOT_DIR, "team-profiles.py"))
-      ? join(SNAPSHOT_DIR, "team-profiles.py")
-      : undefined,
+    generator: packagedGenerator,
     // 成员上限**只有一个真源**：Config.maxMembers。它同时喂给引擎（成员上限）与小队编译器
     // （--max-members）。过去编译器把上限写死 8、这里又没透传，于是把 maxMembers 改大后保存小队
     // 必然编译失败并回滚（D-14）。编译器不认这个参数时由 squads.js 记 warn 并退回它内置默认值。
     maxMembers: config.maxMembers,
+    // 保存小队**编译成功后**的热重载钩子：让运行中的引擎立刻用新 profiles 重挂，不必重启 DSH。
+    // 注入的是回调而不是 `ctx`：数据层不该知道 cordis 的存在（它只负责在正确时机敲门）。
+    onReload: reloadEngine,
+    // 小队编译/重载的诊断出口（N-3）：过去 squads.js 直接写 console.error，桌面与 Web 里
+    // 用户看不见，等于「保存成功但重载失败」这条失败从来没被上报过。
+    logger: ctx.logger,
   });
   ctx.reflect.provide(SQUAD_SERVICE, squads);
 
@@ -1048,14 +1353,39 @@ export function apply(ctx, config) {
   });
 
   // ---- `/t` 小队短命令（把 /t <小队> <目标> 转成引擎认得的 /t --profile <key> <目标> 用户消息）----
-  registerTeamCommand(ctx, {
-    teamsFile,
-    // 与系统提示段共用同一个真机探测（engineReady），两条可见面不会再次分叉。
-    hasEngine: () => engineReady(),
-    // 报给用户的原因用 engineUnreadyDetail()：它区分「调度都没成功」与「调度成功但工具没注册」，
-    // 后者在旧文案里会指向一条永远不存在的 [t-team] error 行（N-5）。
-    engineError: () => engineUnreadyDetail(),
-  });
+  // `commands` 同为**可选**服务（见顶部 inject 注释）：与 settings 完全同理——
+  // 真实宿主里它也可能**晚于本插件就绪**，而 `ctx.get` 只在服务已就绪时才返回对象
+  // （2026-09-13 真实 GUI 实证：apply 时同步探测判负 → /t 根本没注册，而引擎自己那条
+  // `ctx.inject(['commands'])` 却正常）。所以这里也改成 `ctx.inject` 等就绪，不用同步探测。
+  if (typeof ctx.inject !== "function") {
+    ctx.logger?.warn?.("[t-team] 上下文没有 inject：无法等待 commands 就绪，/t 命令不可用。");
+  } else {
+    // 与 settings 同理：`ctx.inject` 对**永不出现**的服务不会有回调，只在回调里告警的话
+    // 宿主真没给 commands 时日志里什么线索都没有。所以申请时就先说一句。
+    ctx.logger?.warn?.("[t-team] 正在等待 commands 服务就绪以注册 /t 命令；若宿主不提供它，/t 将不可用。");
+    ctx.inject(["commands"], (scoped) => {
+      // `scoped` 是 cordis 的**作用域 ctx**。2026-09-13 用真 cordis 4.0.2 实测：
+      // 它是**完整 Context**（`effect` / `get` / `logger` / `inject` / `on` / `plugin` 全在），
+      // 所以「`scoped.effect` 是 undefined」属于**过时说法，别照抄**（自检 [8c] 已用真 cordis
+      // 把这条事实钉住，注释再漂就会被那条断言顶回来）。
+      // 分工照旧：服务从 `scoped` 解析（它保证服务已就绪），effect/logger 挂主 ctx —— 这是
+      // **生命周期上的选择**（注册点随插件 fiber 一起卸载），不是能力限制。
+      const commands = scoped?.commands ?? scoped?.get?.("commands");
+      if (typeof commands?.register !== "function") {
+        ctx.logger?.warn?.("[t-team] commands 服务没有 register：/t 命令不可用（@ 召唤与 summon_t_expert 不受影响）。");
+        return;
+      }
+      registerTeamCommand(ctx, {
+        commands,
+        teamsFile,
+        // 与系统提示段共用同一个真机探测（engineReady），两条可见面不会再次分叉。
+        hasEngine: () => engineReady(),
+        // 报给用户的原因用 engineUnreadyDetail()：它区分「调度都没成功」与「调度成功但工具没注册」，
+        // 后者在旧文案里会指向一条永远不存在的 [t-team] error 行（N-5）。
+        engineError: () => engineUnreadyDetail(),
+      });
+    });
+  }
 
   // ---- DAG 预检工具（只读）：把整套拟建任务一次跑完引擎校验，避免"边建边撞"留下半成品 ----
   ctx.tools.register(defineTool({
@@ -1065,7 +1395,7 @@ export function apply(ctx, config) {
       tasks: {
         type: "array",
         required: true,
-        description: "Tasks you intend to create, in intended order. Each item accepts: subject (required), id (optional label so later items can reference it), kind, description, dependencies (task ids: existing ones or earlier items' labels), assignee, inScope, outOfScope, verify, acceptance, objective, deliverables, nonGoals, round, reviewedTaskId, sourceTaskId, sourceFindingIds.",
+        description: "Tasks you intend to create, in intended order. Each item accepts: subject (required), id (optional label so later items can reference it), kind, description, dependencies, assignee, inScope, outOfScope, verify, acceptance, objective, deliverables, nonGoals, round, reviewedTaskId, sourceTaskId, sourceFindingIds. IMPORTANT: dependencies may only reference tasks that already exist — an earlier item's `id` label, or a task id returned by t_team_status. A reference to a LATER item fails both this pre-check and real creation, so order the batch so that dependencies come first.",
         items: { type: "json" },
       },
     },
@@ -1085,6 +1415,17 @@ export function apply(ctx, config) {
     async execute(args, exec) {
       const agent = exec?.agent;
       if (agent === undefined) return { ok: false, problems: [{ index: -1, id: "agent", subject: "", error: "这个工具需要在会话里调用" }], warnings: [], order: [] };
+      // 引擎就绪门控（C-1）：本工具由 T专家 自己注册，**即使团队引擎挂载失败也照常存在**。
+      // 不拦的话，引擎不在时会返回「先用 t_team_create 建队」——而那个工具此刻根本不在表里，
+      // 等于把模型指向一条死路。这里与 `/t`、系统提示段用同一个真机探测，口径一致。
+      if (!engineReady()) {
+        return {
+          ok: false,
+          problems: [{ index: -1, id: "engine", subject: "", error: `当前会话没有可用的团队引擎，t_team_plan_check 无法预检：${engineUnreadyDetail()}` }],
+          warnings: [],
+          order: [],
+        };
+      }
       const workspace = agent.session?.header?.cwd ?? process.cwd();
       const stateRoot = join(workspace, engineStateDir);
       let team;
@@ -1143,12 +1484,17 @@ export function apply(ctx, config) {
     order: 118,
     text: (context) => {
       if (context.agent?.session?.header?.parentSession !== undefined) return "";
+      // 名册规模与批量上限都**现算**：写死会在名册变更 / 用户改 Config 之后对模型说谎。
+      const scale = rosterScale(config.root);
+      const scope = scale.experts > 0
+        ? `The parent session has T专家 — a ${scale.experts}-expert, ${scale.divisions}-division roster with full Chinese translations, exposed as summonable domain experts.`
+        : "The parent session has T专家 — a curated roster of domain experts with full Chinese translations, exposed as summonable domain experts.";
       return [
         "## T专家 (T Expert) expert mode",
-        "The parent session has T专家 — a 316-expert, 22-division roster with full Chinese translations, exposed as summonable domain experts.",
+        scope,
         "Experts are individually enabled/disabled in the T专家 settings tab; ALL are disabled by default and a disabled expert cannot be summoned.",
         "A composer selection inserts one enabled expert as a native reference chip; the remaining draft text is that expert's task.",
-        "In the parent session, call `list_t_experts()` for enabled division names and counts, then `list_t_experts(division)` to pick a unique expert name, then `summon_t_expert(expert, task)` — or `summon_t_experts` for a small parallel team (at most 8; partial results when some fail).",
+        `In the parent session, call \`list_t_experts()\` for enabled division names and counts, then \`list_t_experts(division)\` to pick a unique expert name, then \`summon_t_expert(expert, task)\` — or \`summon_t_experts\` for a small parallel team (at most ${config.maxSummonBatch}; partial results when some fail).`,
         "For a long multi-step goal that needs a durable team (members, tasks with dependencies, review gates), the user can run a T专家 squad with the `/t <squad> <goal>` slash command (squad names and aliases come from the plugin's squad definitions; plain `/t` lists them); it activates the built-in T专家 team engine with a squad whose members already carry the experts' personas. Do not invent squad names when `/t` is available.",
       ].join("\n");
     },