dsh-plugin-t-expert 0.2.9 → 0.2.12

package/lib/squads.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * T专家 小队数据层：读写 `teams.json`，并把改动编译成引擎配置。
  *
@@ -5,10 +6,16 @@
  * 编译交给既有的 `team-profiles.py`（它已内置成员名撞键预检、别名校验、人格注入）。
  * 这样 UI 编辑器不需要复制一份校验逻辑，生成器仍是唯一权威。
  */
-import { readFileSync, writeFileSync, statSync, existsSync } from "node:fs";
-import { execFileSync } from "node:child_process";
+import { readFileSync, statSync, existsSync } from "node:fs";
+import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+import { writeFileAtomic } from "./catalog.js";
+
+/** 异步编译器调用：**绝不能**用 execFileSync —— 那会同步阻塞整个 Host 事件循环。 */
+const runFile = promisify(execFile);
 
 /** profile key 只允许小写 ASCII + 数字 + 连字符（引擎按它生成命令别名）。 */
 const KEY_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
@@ -18,6 +25,7 @@ function text(value) {
 }
 
 function fail(code, message, details = {}) {
+  /** @type {Error & { code?: string, details?: object }} */
   const error = new Error(message);
   error.code = code;
   error.details = details;
@@ -44,14 +52,28 @@ function memberSlug(member) {
 export const COMPILER_DEFAULT_MAX_MEMBERS = 8;
 
 /**
- * @param generator - 小队编译器路径。调用方**优先传包内那份**（`<包>/data/team-profiles.py`）：
- *   它是随插件版本走的**代码**，而数据目录里那份只在首次启动时播种一次（非破坏性），
- *   升级时不会更新 —— 一直用数据目录那份，等于这个版本的编译器修复永远送不到老用户手里。
+ * @param generator - 小队编译器路径。调用方**只有传包内那份**才是安全且正确的接线：
+ *   `lib/index.js` 现在**只**传 `<包>/data/team-profiles.py`，**不回退**数据目录副本。
+ *   为什么：数据目录那份是 bootstrap 播种的**用户可写**文件，让「保存小队」去执行它
+ *   等于一条同权限代码执行面，且它与包内版本的漂移无法校验（C-3）。
+ *   本函数保留「未传就取同目录 `team-profiles.py`」的默认，只是为了直连数据层的调用方
+ *   （自检 / 面板预览脚本）不必显式传路径 —— **插件运行路径绝不走这个默认**。
  * @param maxMembers - 成员上限（来自 `Config.maxMembers`）。只有编译器声明支持 `--max-members`
  *   时才会真正生效；旧编译器把上限写死在源码里，此时会**记一条 warn** 并退回它的默认值，
  *   而不是让保存小队在「改大上限」后必然编译失败并回滚（D-14）。
+ * @param onReload - 小队保存**编译成功之后**的热重载回调（由 `lib/index.js` 注入：它持有团队引擎的
+ *   fiber，用新的 profiles 重挂引擎）。数据层不碰 `ctx`：这里只负责在正确时机敲门。
+ *   回调返回 `{ ok: true }` 表示重载成功；`{ ok: false, detail }` 表示重载失败（原因要能报给用户）。
+ *   **没有注入时不算成功**：那与"重载失败"是同一个后果（盘上是新配置、引擎还在用旧的），
+ *   所以会记成 `lastReload.ok === false` 并带出明确原因，而不是静默当成功（见 `scheduleReload()`）。
+ *   编译失败并回滚时本回调**绝不**被调用：那时盘上还是旧配置，重载只会重新加载同一份旧配置
+ *   （见 `save()`）。
+ * @param logger - 宿主 logger（`ctx.logger`，可选）。小队编译/重载的诊断**必须走这里**，
+ *   不能写 `console`：桌面与 Web 里 stderr 用户看不见，等于这条失败从来没被上报过
+ *   （与 `catalog.js` 的 N-3 同一条口径）。
+ *   **没有注入时也不写 console**：那正是「用户看不见」的老毛病，宁可静默也不能假装报了。
  */
-export function createSquadService({ teamsFile, catalog, python = "python3", generator: generatorPath, maxMembers }) {
+export function createSquadService({ teamsFile, catalog, python = "python3", generator: generatorPath, maxMembers, onReload, logger }) {
   const dataDir = dirname(teamsFile);
   const generator = typeof generatorPath === "string" && generatorPath !== ""
     ? generatorPath
@@ -64,7 +86,24 @@ export function createSquadService({ teamsFile, catalog, python = "python3", gen
   const generatorSupportsMemberLimit = existsSync(generator)
     ? readFileSync(generator, "utf8").includes("--max-members")
     : false;
+  /** 诊断一律走宿主 logger（见 `logger` 参数的说明）：console 在 GUI 里无人可见。 */
+  const logError = (message) => logger?.error?.(`[t-team] ${message}`);
   let lastBuild = { at: 0, ok: true, output: "" };
+  /** 正在跑的编译（见 `build()`）：并发调用合并成同一次，避免共享的 `lastBuild` 被交错覆盖。 */
+  let buildInFlight;
+  /**
+   * 热重载的**串行尾**：连续快速保存时，后一次重载必须等前一次结束再开始。
+   *
+   * 不只是节流：引擎重挂期间它自己的 fiber 处于 unload→load 过渡，并发重挂会让两次
+   * dispose/apply 交叠，最后一次重挂会在「已卸载」的中间态上跑，留下半死的引擎。
+   * 用一条 promise 链把重载串起来，天然满足「重载中不得并发重载」。
+   */
+  let reloadTail;
+  /**
+   * 最近一次**已完成**的重载结果（诊断用：设置页面板与系统提示段都读它）。
+   * 初值是 ok:true —— 「还没重载过」不等于失败。
+   */
+  let lastReload = { at: 0, ok: true, detail: "" };
 
   function readSpec() {
     try {
@@ -152,6 +191,8 @@ export function createSquadService({ teamsFile, catalog, python = "python3", gen
       engine: spec.engine ?? {},
       defaults: spec.defaults ?? {},
       lastBuild,
+      lastReload,
+      reloading: reloadTail !== undefined,
     };
   }
 
@@ -223,36 +264,101 @@ export function createSquadService({ teamsFile, catalog, python = "python3", gen
     return { ...spec, profiles };
   }
 
-  /** 跑生成器：编译 t-team.config.json + teams.resolved.json（失败即回滚 teams.json）。 */
+  /**
+   * 跑生成器：编译 t-team.config.json + teams.resolved.json（失败即回滚 teams.json）。
+   *
+   * **异步、且不得并发**（P-1）：这里过去用 `execFileSync`，保存一次小队就把整个 Host 事件
+   * 循环同步阻塞（最长 60s）—— 同一进程里所有会话的 SSE、工具调用与 Web 请求全部停摆。
+   * 改成 `await execFile(...)` 之后事件循环继续转，但会引入原来不存在的交错点：两次 `build()`
+   * 可能并行运行，共享的 `lastBuild` 会被先完成的那次覆盖。所以用一条 in-flight promise 把
+   * 并发调用**合并成同一次**（语义上也更正确：同时刻的 teams.json 只该被编译一次）。
+   *
+   * @returns {Promise<{at:number, ok:boolean, output:string}>}
+   */
   function build() {
-    if (!existsSync(generator)) {
-      lastBuild = { at: Date.now(), ok: false, output: `找不到生成器 ${generator}` };
+    if (buildInFlight !== undefined) return buildInFlight;
+    const run = (async () => {
+      if (!existsSync(generator)) {
+        lastBuild = { at: Date.now(), ok: false, output: `找不到生成器 ${generator}` };
+        return lastBuild;
+      }
+      try {
+        // 上限随 Config 走；旧编译器（无 --max-members）退回它写死的默认值并明确告警。
+        if (memberLimit !== COMPILER_DEFAULT_MAX_MEMBERS && !generatorSupportsMemberLimit) {
+          lastBuild = {
+            at: Date.now(),
+            ok: true,
+            output: `[warn] 小队编译器不支持 --max-members（${generator}），成员上限仍按它内置的 ${COMPILER_DEFAULT_MAX_MEMBERS} 执行：`
+              + `超过 ${COMPILER_DEFAULT_MAX_MEMBERS} 人的小队会编译失败，Config.maxMembers=${memberLimit} 不会生效。`
+              + `要真正用上它，请把 data/team-profiles.py 更新到带 --max-members 的版本。`,
+          };
+        }
+        const memberArgs = generatorSupportsMemberLimit ? ["--max-members", String(memberLimit)] : [];
+        // 参数与 execFileSync 时代逐项一致（数组传参、无 shell、60s 上限），只换执行方式。
+        const { stdout, stderr } = await runFile(python, [generator, "--teams", teamsFile, ...memberArgs], {
+          cwd: dataDir,
+          encoding: "utf8",
+          timeout: 60_000,
+          maxBuffer: 4 * 1024 * 1024,
+        });
+        const parts = [stdout, stderr].map((part) => text(part).trim()).filter((part) => part !== "");
+        lastBuild = { at: Date.now(), ok: true, output: parts.join("\n").split("\n").slice(-6).join("\n") };
+      } catch (error) {
+        const output = [error?.stdout, error?.stderr].map((part) => text(part).trim()).filter((part) => part !== "").join("\n");
+        lastBuild = { at: Date.now(), ok: false, output: output === "" ? String(error) : output };
+      }
       return lastBuild;
-    }
-    try {
-      // 上限随 Config 走；旧编译器（无 --max-members）退回它写死的默认值并明确告警。
-      if (memberLimit !== COMPILER_DEFAULT_MAX_MEMBERS && !generatorSupportsMemberLimit) {
-        lastBuild = {
+    })().finally(() => {
+      if (buildInFlight === run) buildInFlight = undefined;
+    });
+    buildInFlight = run;
+    return run;
+  }
+
+  /**
+   * 引擎热重载：保存成功后，让运行中的引擎用**新的** profiles 重挂，无需重启 DSH。
+   *
+   * 为什么必须在这里做：`/t` 列表每次从磁盘读（`lib/command.js` 的 `readTeams`），而引擎的
+   * profiles 是挂载期快照 —— 两者过去只在「重启」这一个点上重新对齐。保存是唯一让磁盘
+   * 配置变化的地方，所以在**编译成功之后**敲门重载是恢复一致性的正确时机。
+   *
+   * 三条不可动摇的语义：
+   *   1. 编译失败并回滚 → **不调用**（见 `save()`：回滚分支在调用点之前就抛了）；
+   *   2. 重载失败**不改抛**——盘上已经是新配置，抛错会让用户以为「保存没生效」而不停重试；
+   *      失败原因通过返回值进 `lastReload`、日志与系统提示段，用户/模型都看得到；
+   *   3. 重载串行化：并发保存不会产生并发重挂。
+   */
+  function scheduleReload() {
+    const run = (reloadTail ?? Promise.resolve()).then(async () => {
+      if (typeof onReload !== "function") {
+        // **绝不能静默当成功**：没有注入重载方意味着「保存生效了、引擎还用着旧 profiles」，
+        // 与"重载失败"是同一个可观察后果。记成失败（lastReload.ok=false + 原因），
+        // 系统提示段与 lastReload 都会带出去，用户/模型复述得到的是真实状态。
+        // 唯一的合法场景是单测直接构造数据层（此时没人会读 lastReload）。
+        lastReload = {
           at: Date.now(),
-          ok: true,
-          output: `[warn] 小队编译器不支持 --max-members（${generator}），成员上限仍按它内置的 ${COMPILER_DEFAULT_MAX_MEMBERS} 执行：`
-            + `超过 ${COMPILER_DEFAULT_MAX_MEMBERS} 人的小队会编译失败，Config.maxMembers=${memberLimit} 不会生效。`
-            + `要真正用上它，请把 data/team-profiles.py 更新到带 --max-members 的版本。`,
+          ok: false,
+          detail: "没有注入热重载回调（onReload）：这次保存已写入磁盘，但引擎仍在使用上一次的小队配置，需要重载插件或重启 DSH 才能用新小队建队。",
         };
+        logError(lastReload.detail);
+        return;
       }
-      const memberArgs = generatorSupportsMemberLimit ? ["--max-members", String(memberLimit)] : [];
-      const output = execFileSync(python, [generator, "--teams", teamsFile, ...memberArgs], {
-        cwd: dataDir,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "pipe"],
-        timeout: 60_000,
-      });
-      lastBuild = { at: Date.now(), ok: true, output: output.trim().split("\n").slice(-6).join("\n") };
-    } catch (error) {
-      const output = [error?.stdout, error?.stderr].map((part) => text(part).trim()).filter((part) => part !== "").join("\n");
-      lastBuild = { at: Date.now(), ok: false, output: output === "" ? String(error) : output };
-    }
-    return lastBuild;
+      const outcome = await onReload();
+      const ok = outcome?.ok !== false;
+      lastReload = { at: Date.now(), ok, detail: text(outcome?.detail) };
+      if (!ok) {
+        // 失败必须响：重载失败意味着"保存生效了、但运行中的引擎还用着旧 profiles"。
+        logError(`小队已保存，但团队引擎热重载失败：${lastReload.detail}`);
+      }
+    }).catch((error) => {
+      // 注入方自己抛错（契约违背）也要留住，不能让保存报告成"一切正常"。
+      lastReload = { at: Date.now(), ok: false, detail: String(error) };
+      logError(`小队已保存，但团队引擎热重载异常：${lastReload.detail}`);
+    }).finally(() => {
+      if (reloadTail === run) reloadTail = undefined;
+    });
+    reloadTail = run;
+    return run;
   }
 
   async function save(squads, expectedRevision) {
@@ -266,19 +372,32 @@ export function createSquadService({ teamsFile, catalog, python = "python3", gen
     }
     const previousText = readFileSync(teamsFile, "utf8");
     const nextSpec = serialize(readSpec(), squads);
-    writeFileSync(teamsFile, `${JSON.stringify(nextSpec, null, 2)}\n`);
-    const built = build();
+    // 原子写（P-2）：先写临时文件再 rename。进程若在写入中途被杀，原来会留下**截断的**
+    // teams.json，`readSpec()` 随即抛 `tTeam/squads-unreadable`，设置页「小队」标签整体不可用。
+    await writeFileAtomic(teamsFile, `${JSON.stringify(nextSpec, null, 2)}\n`);
+    const built = await build();
     if (!built.ok) {
-      writeFileSync(teamsFile, previousText); // 回滚，别把坏定义留在盘上
+      await writeFileAtomic(teamsFile, previousText); // 回滚，别把坏定义留在盘上（同样原子）
+      // 回滚之后**不重载**：盘上是旧配置，重载只会重新加载同一份旧配置，白跑一次还可能
+      // 让「保存失败」看起来像「保存成功」。下一次成功保存会重新对齐。
       throw fail("tTeam/squads-build-failed", `配置生成失败，已回滚 teams.json：\n${built.output}`, {
         actualRevision: revisionOf(),
       });
     }
-    return await list();
+    // 编译成功 = 新配置已经落在盘上（`build()` 写的正是引擎启动时读的那份），现在敲门重载。
+    const settled = scheduleReload();
+    const result = await list();
+    // 有重载还在跑时（可能是本次的，也可能是上一次的尾巴）就等它结束：这样本次保存返回的
+    // `lastReload` 才名副其实，调用方（自检探针 / 未来的面板）能直接读到「这次保存到底重载
+    // 成功没有」。等待期间系统提示段已经把真相写出来了，不会误导。
+    await settled;
+    return { ...result, lastReload, reloading: reloadTail !== undefined };
   }
 
   return {
     list, save, validate, revision: revisionOf, generator, dataDir,
+    // 本服务没有 `dispose()`：它只在 `save()` 调用期间持有状态（重载串行尾由 save() 自己 await
+    // 干净），两次调用之间是无状态的，所以宿主卸载时没有需要收尾的异步工作。
     // 让调用方（与自检）看得到「这次编译用的是哪个上限、编译器到底认不认这个参数」。
     memberLimit,
     generatorSupportsMemberLimit,

package/lib/teams/harness-compat.js

@@ -16,6 +16,32 @@ function boundary(runtime) {
 function unsupported(detail) {
     throw new Error(`t-team: unsupported Harness subagent contract (${detail}); use an explicitly tested Harness version and a coherent dependency installation`);
 }
+/**
+ * 这个兼容层**实测过**的 Harness 版本（A-1/E-1）。
+ *
+ * 为什么要写出来：`guardSubagentDelivery` 会覆写共享的 `ctx.subagents` 服务，用的两个
+ * `Symbol.for` 与调用签名都来自**未文档化的上游内部实现**。上游一旦改动，症状是"团队功能
+ * 突然不可用（引擎降级）"，没有这张表就只能靠猜。升级 Harness 后**必须**把这里改成
+ * "已实测通过"再发布，未知版本会走 `unsupported()` 明确报错（而不是半死）。
+ */
+export const TESTED_HARNESS_VERSIONS = ['0.1.5-rc.1', '0.1.5-rc.2'];
+/** 单个属性能否被安全覆写：可写数据属性、有 setter 的访问器，或对象可扩展时的新属性。 */
+function canAssign(object, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(object, key);
+    if (descriptor === undefined)
+        return Object.isExtensible(object);
+    if ('value' in descriptor)
+        return descriptor.writable === true;
+    return typeof descriptor.set === 'function';
+}
+/** 覆写前先确认**每一个**目标属性都可写，否则响亮失败（避免 strict mode 下抛裸 TypeError）。 */
+function assertAssignable(object, keys) {
+    const blocked = keys.filter((key) => !canAssign(object, key));
+    if (blocked.length > 0) {
+        const names = blocked.map((key) => (typeof key === 'symbol' ? key.toString() : key)).join(', ');
+        return unsupported(`subagent service properties are not writable (${names}); upstream may have frozen or accessor-ized the service`);
+    }
+}
 /** Read child-owned history, excluding any descriptor inherited from a parent. */
 export function sessionOwnEvents(session) {
     const current = session;
@@ -116,6 +142,16 @@ export function guardSubagentDelivery(ctx, isRetired) {
     if (typeof legacy !== 'function' && ((typeof queue !== 'function' && typeof deliver !== 'function') || typeof send !== 'function')) {
         return unsupported('cannot install complete retired-member guard');
     }
+    // A-1/E-1：**先探测可写性再动手**。过去直接赋值，若上游把服务冻结（`Object.freeze`）
+    // 或改成只有 getter 的访问器，strict mode 下这里会抛一个与"版本不支持"毫无关系的裸
+    // TypeError；现在会得到明确原因。同时这也是一次"契约变了"的早期信号。
+    const targets = [
+        ...(typeof legacy === 'function' ? ['followup'] : []),
+        ...(typeof queue === 'function' ? [hostPromptQueue] : []),
+        ...(typeof deliver === 'function' ? [hostPromptDeliver] : []),
+        ...(typeof send === 'function' ? ['sendMessage'] : []),
+    ];
+    assertAssignable(host, targets);
     ctx.effect(() => {
         const descriptors = new Map([
             ['followup', Object.getOwnPropertyDescriptor(host, 'followup')],

package/lib/teams/index.js

@@ -111,6 +111,12 @@ export function apply(ctx, config) {
         maxMembers: config.maxMembers ?? 8,
         profiles: config.profiles ?? {},
     };
+    // Hot reload: a squad saved in the settings tab re-applies this plugin with a new
+    // `profiles` object (the host updates the fiber's config instead of restarting the
+    // harness). Every read below must therefore go through `resolved.profiles` — the
+    // per-apply snapshot — and never through a module-level constant captured once at
+    // startup: that was the "edit a squad, restart DSH" behaviour this exists to remove.
+    const profiles = () => resolved.profiles;
     // Provider registration is a sibling plugin's effect (`subagent-spawn` /
     // `subagent-fork` rows), which can land after this mount under the Loader's
     // concurrent activation — so capability validation happens at the first
@@ -123,7 +129,9 @@ export function apply(ctx, config) {
         order: config.promptSectionOrder,
         // Keep the bounded profile directory available without extra tool calls.
         // installTeamCapabilities snapshots this once; no business state rewrites it.
-        captainPrompt: () => usageSectionText(TEAM_TOOL_NAMES.join(', '), formatProfilesForPrompt(config.profiles)),
+        // resolved.profiles is this apply's snapshot, so a hot reload rebuilds the
+        // captain prompt with the new squad directory instead of a stale closure.
+        captainPrompt: () => usageSectionText(TEAM_TOOL_NAMES.join(', '), formatProfilesForPrompt(profiles())),
     });
     // Deterministic activation surfaces: the closed-namespace `/t-team`
     // host command (surfaces in the Web GUI slash menu via the Harness
@@ -137,9 +145,9 @@ export function apply(ctx, config) {
     // never pends on it and simply never gains the slash command.
     if (config.slashCommand ?? true) {
         ctx.inject(['commands'], (commandCtx) => {
-            registerTTeamCommand(commandCtx, () => config.profiles ?? {});
+            registerTTeamCommand(commandCtx, profiles);
         });
-        installTTeamGestureBoundary(ctx, () => config.profiles ?? {});
+        installTTeamGestureBoundary(ctx, profiles);
     }
     // The activity panel data/artwork routes need the Web server and the
     // workspace registry, which headless profiles do not mount; under

package/lib/teams/members.js

@@ -70,7 +70,7 @@ export function selectFallbackRoute(current, fallback, failureCode, alreadySwitc
     return { retry: true, switched: true, selection: fallback };
 }
 /** Deliver a durable member report to the live captain at its next model step. */
-export function steerCaptainReport(captain, from, content) {
+export function steerCaptainReport(captain, from, content, logger) {
     try {
         captain.steer(createUserMessage({
             content: [{ type: 'text', text: `T Team message from member ${from}:\n\n${content}` }],
@@ -78,7 +78,10 @@ export function steerCaptainReport(captain, from, content) {
         }));
         return true;
     }
-    catch {
+    catch (error) {
+        // 投递失败必须留痕：调用方只拿到一个布尔值（true=实时投递 / false=回落持久信箱），
+        // 不留日志就只能靠猜「这次为什么走了信箱」。steer 的异常根因在这里唯一可见。
+        logger?.warn?.(`[t-team] 向队长实时投递消息失败，已回落到持久信箱：${error instanceof Error ? error.message : String(error)}`);
         return false;
     }
 }
@@ -138,7 +141,7 @@ export async function failMemberOpenAttempt(ctx, stateRoot, teamId, memberName,
     // Use the same lease/acknowledgment contract as send_message, outside the
     // team lock: steering can synchronously start another agent turn.
     const captain = ctx.agents.get(brandedSessionId(prepared.captainSessionId));
-    const delivered = captain !== undefined && steerCaptainReport(captain, memberName, prepared.message.content);
+    const delivered = captain !== undefined && steerCaptainReport(captain, memberName, prepared.message.content, ctx.logger);
     await withTeamLock(lockKey, () => delivered
         ? acknowledgeMailbox(stateRoot, teamId, CAPTAIN_KEY, [prepared.message.id])
         : releaseMailboxDelivery(stateRoot, teamId, CAPTAIN_KEY, [prepared.message.id]));
@@ -586,16 +589,22 @@ export function installRetiredMemberGuard(ctx, stateDir) {
  * rc.8 changed those rows to branded `SessionId` values plus residency-only
  * `activity`; neither is needed to answer whether the live Agent driver is
  * running, idle, or absent/ready.
- * @param ctx - the plugin context (injects `agents`).
+ * @param ctx - the plugin context (only needs `ctx.get`; `agents` itself is optional).
  * @param memberIds - child ids restored from the durable team record.
  * @returns child id → live activity.
  */
 export function memberActivity(ctx, memberIds) {
     const activity = new Map();
+    // `agents` 是**可选服务**：宿主侧静态 `inject` 只有 tools/subagents/systemPrompt，所以
+    // 属性访问 `ctx.agents` 在那种 ctx 上会抛 `cannot get property "agents" without inject`，
+    // 而调用方（团队面板的快照收集）用 try/catch 把它吞成「skipped unreadable team state」——
+    // 整支队伍从面板消失，只留一句没有原因可查的告警（2026-09-13 查明）。规则与
+    // lib/index.js 里 `ctx.get("agents")` 一致：可选服务必须惰查，缺了降级成 ready。
+    const agents = typeof ctx?.get === 'function' ? ctx.get('agents') : undefined;
     for (const id of memberIds) {
         if (id === '')
             continue;
-        const live = ctx.agents.get(brandedSessionId(id));
+        const live = agents?.get?.(brandedSessionId(id));
         activity.set(id, live === undefined ? 'ready' : live.status);
     }
     return activity;

package/lib/teams/snapshot.js

@@ -147,8 +147,11 @@ export async function collectTeamsActivity(ctx, roots) {
                     continue;
                 snapshots.push(await assembleTeamSnapshot(ctx, root.stateRoot, root.workspace, state));
             }
-            catch {
-                ctx.logger.warn(`t-team: skipped unreadable team state "${entry.name}" in workspace "${root.workspace}"`);
+            catch (error) {
+                // 必须带上根因：裸 `catch {` 只留一句「unreadable」，解析失败、权限、服务缺失、
+                // 并发读全都会变成同一句无法诊断的告警（2026-09-13 在真实宿主日志里就撞上一条
+                // 谁也没法解释的 "skipped unreadable team state"，根因正是被这里吞掉的）。
+                ctx.logger.warn(`t-team: skipped unreadable team state "${entry.name}" in workspace "${root.workspace}": ${String(error)}`);
             }
         }
     }
@@ -172,8 +175,8 @@ export async function collectArchivedTeamsActivity(ctx, roots) {
                     continue;
                 snapshots.push(await assembleTeamSnapshot(ctx, join(root.stateRoot, 'archive'), root.workspace, state, { includeRemoved: true, historic: true }));
             }
-            catch {
-                ctx.logger.warn(`t-team: skipped unreadable archived team "${teamId}" in workspace "${root.workspace}"`);
+            catch (error) {
+                ctx.logger.warn(`t-team: skipped unreadable archived team "${teamId}" in workspace "${root.workspace}": ${String(error)}`);
             }
         }
     }

package/lib/teams/tools.js

@@ -115,45 +115,62 @@ function trimmedOptional(value) {
     const trimmed = value?.trim();
     return trimmed === undefined || trimmed === '' ? undefined : trimmed;
 }
-/** Validate references and cycles before a staged graph can be saved or run. */
-function validateStagedGraph(team, requireRunnable) {
+/** Collect every staged-graph problem: empty subject, bad assignee, unknown/self dependency, cycles. */
+function collectStagedGraphProblems(team, requireRunnable) {
+    const problems = [];
     const members = team.members.filter((member) => member.status !== 'removed');
     if (requireRunnable && members.length === 0)
-        throw new Error('add at least one member before approving the plan');
+        problems.push('add at least one member before approving the plan');
     if (requireRunnable && team.tasks.length === 0)
-        throw new Error('add at least one task before approving the plan');
+        problems.push('add at least one task before approving the plan');
     const memberNames = new Set(members.map((member) => member.name));
     const taskIds = new Set(team.tasks.map((task) => task.id));
     for (const task of team.tasks) {
-        if (task.subject.trim() === '')
-            throw new Error(`task "${task.id}" must have a subject`);
-        if (task.assignee !== undefined && task.assignee !== CAPTAIN_KEY && !memberNames.has(task.assignee)) {
-            throw new Error(`task "${task.id}" assignee "${task.assignee}" is not an active member`);
+        if (String(task.subject ?? '').trim() === '')
+            problems.push(`task "${task.id}" must have a subject`);
+        if (task.assignee !== undefined && task.assignee !== null && task.assignee !== CAPTAIN_KEY && !memberNames.has(task.assignee)) {
+            problems.push(`task "${task.id}" assignee "${task.assignee}" is not an active member`);
         }
-        for (const dependency of task.dependencies) {
+        for (const dependency of task.dependencies ?? []) {
             if (dependency === task.id)
-                throw new Error(`task "${task.id}" cannot depend on itself`);
-            if (!taskIds.has(dependency))
-                throw new Error(`task "${task.id}" depends on unknown task "${dependency}"`);
+                problems.push(`task "${task.id}" cannot depend on itself`);
+            else if (!taskIds.has(dependency))
+                problems.push(`task "${task.id}" depends on unknown task "${dependency}"`);
         }
     }
     const visiting = new Set();
     const visited = new Set();
     const byId = new Map(team.tasks.map((task) => [task.id, task]));
-    const visit = (taskId) => {
-        if (visiting.has(taskId))
-            throw new Error(`task dependency graph contains a cycle at "${taskId}"`);
+    const visit = (taskId, trail) => {
+        if (visiting.has(taskId)) {
+            problems.push(`task dependency graph contains a cycle: ${[...trail, taskId].join(' → ')}`);
+            return;
+        }
         if (visited.has(taskId))
             return;
         visiting.add(taskId);
         for (const dependency of byId.get(taskId)?.dependencies ?? [])
-            visit(dependency);
+            visit(dependency, [...trail, taskId]);
         visiting.delete(taskId);
         visited.add(taskId);
     };
     for (const task of team.tasks)
-        visit(task.id);
+        visit(task.id, []);
+    return problems;
+}
+/**
+ * Validate references and cycles before a staged graph can be saved or run.
+ *
+ * 抛**第一条**问题（调用方的门禁语义：越早拒绝越好）。需要"一次报全部"的调用方
+ * （插件侧的 `t_team_plan_check` 只读预检）用导出的 `collectStagedGraphProblems`，
+ * 不要自己复刻规则 —— 两处规则一旦漂移，预检就会说 ok 而引擎拒绝。
+ */
+function validateStagedGraph(team, requireRunnable) {
+    const problems = collectStagedGraphProblems(team, requireRunnable);
+    if (problems.length > 0)
+        throw new Error(problems[0]);
 }
+export { collectStagedGraphProblems };
 function memberOpenTask(team, memberName, exceptTaskId) {
     return team.tasks.find(task => task.id !== exceptTaskId
         && task.assignee === memberName
@@ -1687,7 +1704,7 @@ export function registerTTeamTools(ctx, config) {
             if (prepared.kind === 'captain') {
                 let delivered = 'mailbox';
                 if (captain !== undefined && prepared.identity.kind === 'member') {
-                    delivered = steerCaptainReport(captain, prepared.from, args.content) ? 'live' : 'mailbox';
+                    delivered = steerCaptainReport(captain, prepared.from, args.content, ctx.logger) ? 'live' : 'mailbox';
                 }
                 if (delivered === 'live') {
                     await withTeamLock(teamLockKey(stateRoot, prepared.fresh.id), () => (acknowledgeMailbox(stateRoot, prepared.fresh.id, CAPTAIN_KEY, [prepared.message.id])));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-t-expert",
-  "version": "0.2.9",
+  "version": "0.2.12",
   "type": "module",
   "description": "T Expert — a 316-expert, 22-division roster with full Chinese translations, as a standalone DeepSeek Harness plugin, with a built-in multi-agent team engine (T Team).",
   "license": "MIT",
@@ -67,10 +67,11 @@
     }
   },
   "scripts": {
-    "build": "node ../build-client.mjs",
-    "verify": "node ../verify.mjs",
-    "sync-data": "node ../sync-data.mjs",
-    "prepublishOnly": "npm run build && npm run verify && node ../sync-data.mjs --check"
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "node tools/build-client.mjs",
+    "verify": "node tools/verify.mjs",
+    "sync-data": "node tools/sync-data.mjs",
+    "prepublishOnly": "npm run typecheck && npm run build && npm run verify && node tools/sync-data.mjs --check"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
@@ -147,7 +148,6 @@
     "@deepseek-ai/dsh-attachment": "^0.1.5-rc.1",
     "@deepseek-ai/dsh-client-connection": "0.1.5-rc.1",
     "@deepseek-ai/dsh-client-locale": "0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
     "@deepseek-ai/dsh-client-ui-input-trigger": "0.1.5-rc.1",
     "@deepseek-ai/dsh-client-ui-primitives": "0.1.5-rc.1",
     "@deepseek-ai/dsh-client-ui-settings": "0.1.5-rc.1",
@@ -164,9 +164,11 @@
     "@deepseek-ai/dsh-util-time": "^0.1.5-rc.1",
     "@deepseek-ai/dsh-util-values": "^0.1.5-rc.1",
     "@deepseek-ai/schemastery": "^3.18.2",
+    "@types/node": "^22.20.2",
     "esbuild": "^0.25.0",
     "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "react-dom": "^18.3.1",
+    "typescript": "^5.9.3"
   },
   "dependencies": {
     "zod": "^4.4.3"

package/skills/dsh-harness-project/SKILL.md

@@ -65,6 +65,33 @@ dsh --profile web --dump-config   # 看本机实际启动的树；打印出的
 
 **应用启动只有一条路**：`dsh` CLI + 具名 profile（`dsh web` 是 `--profile web` 的别名）。package bin、demo、public SDK argv 直接拼 Cordis 树都是禁止的，`scripts/verify-application-entrypoints.ts` 会拒绝。
 
+## 依赖语义：决定「等待」还是「挂起」
+
+`inject` 与 `ctx.get` 不是两种风格，而是**两种契约**（官方 `develop/framework/service` 有权威表述，本仓库同一套语义）：
+
+- **`inject = ['x']` = 必需依赖**。框架保证 `apply` 执行时声明的服务**已全部就绪**；缺一个，插件就**等着、不执行**。
+  → 这就是 **silent PENDING**：插件看起来"没加载"，而且**它自己不产生任何日志**。排查时先怀疑这里，别先怀疑业务代码。
+- **省略 `inject`、用 `ctx.get('x')` = 可选依赖**，但**必须在使用点调用**，不能在 `apply` 里探一次：
+  `apply` 是最早也最脆弱的时刻，提供方晚到的话那次探测已经返回 `undefined`，**没有任何机制会重跑它**。
+  （真实事故：把可选服务的 `ctx.get` 写在 apply 期做一次性探测 → 服务晚到时永久判负 → 设置段不注册、面板空白。）
+- 运行期必需服务**消失** → 依赖它的插件自动 dispose；服务**回来** → 自动重新加载。所以「注册即 effect」是生命周期要求，不是代码风格。
+- 需要"等某个服务就绪再做事"时用 `ctx.inject(['x'], cb)`：它等的是"服务就绪"这件事本身，服务迟到也能补上。
+
+## 官网文档：面向插件作者的同一份知识
+
+`https://deepseek-harness.github.io/deepseek-harness/` 是本仓库的**公开面**（`website/` 的 VitePress 投影），适合快速核对启动模型、依赖语义与钩子，再去读源码：
+
+| 页面 | 用途 |
+|---|---|
+| `guide/quickstart` | Web UI 起步：起服务、加工作区、配模型（新用户从这里开始） |
+| `develop/basic/` | 最小插件、`scratch-plugin/cordis.yml` 的 `- insert:` 行、**插件路径必须是绝对路径** |
+| `develop/basic/tool` · `config` · `publish` | 工具注册；受校验的 `Config`；`dsh.bundle` vs `dsh.profile` + `dsh plugin add` |
+| `develop/framework/` · `service` · `events` | 生命周期/effect、服务与依赖语义、事件系统 |
+| `develop/practice/` · `llm-adapter` · `dynamic-cordis` | 能力三角色分层、模型适配器、在运行中的智能体里改插件 |
+| `develop/cordis-tutorial/01…07` | Cordis 阶梯，终点是「进入 harness」 |
+
+**边界（重要）**：站点**不覆盖** `vitest` / `oxlint` / `run-gates.ts` / 覆盖率策略、`.agents/notes/` 约定、生成的子系统页 —— 所以**概念查站点、门禁与契约查检出**。冲突时以检出为准（站点由本仓库生成，冲突本身值得上报）。
+
 ## 核心包（spine）
 
 | 包 | 拥有 | ctx key |

package/skills/t-expert-manager/SKILL.md

@@ -21,7 +21,13 @@ description: T专家 运维台 —— 316 位专家 / 22 分区的名册增删
    正文里不写死位数，因为每加一位专家它就会过期。
 4. **数据更新不用重装、不用重启**（宿主按 mtime 指纹自动重载名册）；**改插件代码**才需要
    `tz.sh build` → `tz.sh install` → 重启 DSH Desktop。
-5. **小队改完必须 `tz.sh squads` + 重启 DSH Desktop** 才对建队生效。
+5. **小队改完分两条路，只有设置页那条会热重载**：
+   - **设置页「队伍」保存**（推荐）：`squads.save()` 编译成功后**就地热重载引擎配置 → 立即生效、不用重启**。
+   - **`tz.sh squads`（= 菜单 11）**：只是 CLI 直跑编译器（`python3 data/team-profiles.py`）把 `teams.json`
+     编译成引擎配置，**不经过插件、不会热重载**——运行中的引擎仍用旧 profiles，**必须重启 DSH**
+     （或再到设置页保存一次）才生效。所以别对用户说「跑完 tz.sh squads 就已经生效」。
+   两条路的失败语义一致：编译失败会**回滚**，盘上仍是旧配置（按旧小队建队）。
+   只有**改插件代码**才需要重启（见第 4 条）。
 6. **`data/zh/` 已冻结**：不要新增或"补译"中文。新专家没有中文名/简介会回退英文，这是预期行为。
 7. **破坏性动作先确认**：删除专家、卸载插件、发布 npm 之前，把影响讲给用户听，得到明确同意再执行。
 
@@ -78,7 +84,10 @@ bash "{{TZ}}" experts stats
    ```bash
    bash "{{TZ}}" squads
    ```
-3. 明确告诉用户：**重启 DSH Desktop 后生效**，之后用 `/t <小队> <目标>`。
+3. 明确告诉用户：**`tz.sh squads` 只是 CLI 直跑编译器**——它把 `teams.json` 编译成引擎配置，
+   **不会让运行中的插件重载**。所以：**要让新小队真正生效，需重启 DSH Desktop**（或再到设置页「队伍」保存一次，
+   那条路才会就地热重载、立即生效）。若 `/t` 里仍看不到新小队，先确认编译没报错（编译失败会回滚，盘上仍是旧配置）。
+4. 想免重启就直接走设置页：设置 → T专家 → 队伍 → 改完保存（`squads.save()` 编译成功后触发引擎热重载，立即生效）。
 
 ### F. 装机（只在改过插件代码时需要）