@yangdcm/dsh-expert-team 1.3.10 → 1.3.11

package/CHANGELOG.md

@@ -3,6 +3,73 @@
 本包遵循[语义化版本](https://semver.org/lang/zh-CN/)。dsh 宿主版本线的对应关系写在
 `package.json` 的 `engines.dsh` 与 `dsh.compatibility` 里，插件市场按它判断"这个插件跟你的宿主兼不兼容"。
 
+## 1.3.11
+
+**`/state` 的 `subs` / `roles` 两段收口 —— 这次不靠预测，靠 1.3.10 留下的分步计时开关实测定位。**
+父会话在真机上带 `DSH_EXPERT_TEAM_STATE_PROFILE=1` 复测，拿到确切归属（同一台机器、同一 session、
+连续两次请求）：
+
+```
+totalMs 2222 / 2047
+profile.runs+select   21 / 15  ms   ✓ 便宜
+profile.subs        1327 / 1388 ms  ✗ 主犯
+profile.wfLabels       0 / 0   ms   ✓
+profile.roles        869 / 638 ms  ✗ 次犯
+profile.tail           3 / 3   ms   ✓
+rolesBudget: {per:4, left:0, deferred: 16 → 40}   ← deferred 在**涨**
+```
+
+### ① `subs` 段：按 session id 备忘（并纠正两处"看起来像缓存、其实没用"的设置）
+
+- **根因**：1.3.10 的"只在真缺人时才查"**没真正省下钱** —— 已结束/历史子会话本来就不在活注册表里，
+  `missingIds` 每请求都非空 ⇒ 每请求都退化成对 **475 个 artifact 逐个读 header** 的枚举；
+  而当时设的 **2 s TTL 恰好等于真实请求间隔**（轮询 + 退避），**必然过期** ⇒ 等于没有缓存。
+- **改法**：新增 `SUB_HEADER_MEMO`（按 session id 永久记住 `createdAt/parentId/depth`）——
+  这条分支上的 id 恰恰是"活注册表里查不到"的那些，其 header 不可变，记住它们不会让用户看到旧状态；
+  枚举本身的主失效键改为 **`(sessions 根目录, mtimeMs, size)`**（`sessionsRootStamp()`，实测 0.56 ms），
+  TTL 只作兜底并放宽到 **60 s**。
+- **口径不变**：**活代理一律实时读，绝不进任何缓存**（有断言守着：活代理不写入备忘）。
+- **折算前后**（单位成本取自上面的真机 profile：一次枚举 ≈ 1500–2400 ms，本机取 1800 ms）：
+  **旧：每请求 ≈ 1800 ms；新：第 1 次 1800 ms，第 2 次起 0.02–0.09 ms** ⇒ 热态 `subs` ≈ **0 ms**。
+
+### ② `roles` 段：限次摊平改成**跨请求推进的队列**
+
+- **根因**：1.3.10 每请求都把候选集**从零重算**，预算永远喂给队首同几条，而新派的子代理不断出现在队尾
+  ⇒ **进度不前进、`deferred` 只增不减**（实测 16 → 40）。"限次摊平"退化成"永远摊不完"。
+- **改法**：模块级 `ROLE_PENDING` 队列 —— 每请求按"当前 subs 里仍未缓存"的顺序**重建队列**
+  （已缓存的自动掉队、既有顺序保留、新人追加队尾），再从队首消费 ≤ 4 条；角色结果**永久缓存**
+  （对已结束会话不可变）。`resetRoleReadBudget()` 只复位**本请求额度**，**不丢队列进度**。
+- **两种零仍然分得开**：`deferred` = **还没解析**（队列长度，单调不增）；`unresolved` = **解析不出来**
+  （读过但日志里没有角色）—— 新增这个数，正是为了不让两者混成一个。
+- **实测（21 个子会话，每次 4 条预算）**：`deferred` **17 → 13 → 9 → 5 → 1 → 0**；
+  6 个 tick 后**零次日志读**。折算：**旧 860 ms/请求且永不收敛 → 收敛后 ≈ 0 ms**。
+
+### ③ 推荐插件自检的**假警报**（用户贴的启动日志直接坐实）
+
+- **现象**：日志说 `@vectorize-io/hindsight-coding-agents` 与 `dsh-cost-meter`"已安装但当前不可用 ⇒
+  `dsh plugin … add`"，**紧跟着 `dsh-cost-meter` 自己就加载成功了** ⇒ 判定是错的、建议是误导的。
+- **根因（两条）**：① 我们的 `apply()` 跑在其它插件之前，那一刻 `ctx.get('costMeter')`/工具表里当然还没有它们；
+  ② 对 `installed-not-ready` 也拼了安装命令，等于叫用户装一个**已经装好**的东西。
+- **宿主没有 app 级 ready 事件**（已核源码）：`dsh-app-boot` 的 `boot()` 顺序是
+  `mountRootInclude → await ctx.get('loader').await() → assertEntriesActivated → return`，
+  期间不 emit 任何"就绪"事件；而 `loader.await()` 我们**不能用** —— 那棵树包含我们自己的挂载任务，
+  在 init 里 await 它会**自等死锁**。
+- **改法**：`scheduleOptionalPluginCheck()` —— **有界延迟重探**（250/1000/3000 ms，最后一次才下结论）
+  ＋ **`ctx.inject([服务])` 事件驱动**（服务一出现立刻重探；服务始终不出现则回调不触发，零副作用）；
+  外加 **`/team help` 懒重探**（刚装上/刚修好配置不必为了这行提示再重启）。
+- **文案分档**：`missing` ⇒ 给安装命令；`installed-not-ready` ⇒ 只说"已安装但当前未就绪（可能未配置或被关闭）"，
+  **不再给安装命令**；`unknown` ⇒ 不出现（四态与"两种零可区分"的语义不变）。
+
+### 验证与口径
+
+- `npm run test:all` **EXIT=0**（**80** 个测试文件；`state-perf-guard` 扩到 37 条断言：备忘只枚举一次、
+  活代理不入备忘、目录戳失效、队列跨请求推进、deferred 单调不增、额度复位不丢进度、
+  `installed-not-ready` 不含安装命令、服务晚挂不再误报、就绪后重探与懒重探的接线）。
+- **诚实边界**：上面"折算前后"的数字是**用父会话真机实测的单位成本 × 新代码的调用次数**折算的
+  （本机宿主仍跑 1.3.10，我无法把新代码装进运行中的进程）。**端到端 `totalMs` 请装完 1.3.11 后带
+  `DSH_EXPERT_TEAM_STATE_PROFILE=1` 复测**：预期 `subs`/`roles` 两段都接近 0，
+  `totalMs` 由 `runs+select`（~20 ms）+ `tail`（~3 ms）主导。
+
 ## 1.3.10
 
 **四项一次收口：推荐插件自检 · 画布轮询也走 single-flight · 底盘缓存 · 角色解析限次。**

package/lib/command.js

@@ -985,16 +985,27 @@ function detectOptionalPlugins(ctx) {
   const needsAttention = items.filter((i) => i.status === 'missing' || i.status === 'installed-not-ready');
   let hint = '';
   if (needsAttention.length) {
+    // 分档文案（2026-09-15 真实踩到）：对 `installed-not-ready` **不能**再给安装命令 ——
+    // 那等于叫用户装一个已经装好的东西（用户机器上 dsh-cost-meter 明明紧接着自己加载成功了，
+    // 我们却提示他去 `dsh plugin add dsh-cost-meter` ⇒ 假警报 + 误导）。
+    //   · missing（确认没装）⇒ 给安装命令；
+    //   · installed-not-ready（装了但此刻拿不到）⇒ 只说事实与可能原因，**不给命令**；
+    //   · unknown ⇒ 不进 needsAttention，不出现。
     const parts = needsAttention.map((i) => {
-      const why = i.status === 'missing' ? '未安装' : '已安装但当前不可用（未配置或被关闭）';
-      return `${i.pkg}（${i.what}）：${why} ⇒ ${i.install}`;
+      const head = `${i.pkg}（${i.what}）`;
+      return i.status === 'missing'
+        ? `${head}：未安装 ⇒ ${i.install}`
+        : `${head}：已安装但当前未就绪（可能未配置或被关闭；若刚装上，稍后或重启后再看）`;
     });
     hint = `[expert-team] 推荐插件未就绪（不影响使用，只是少了对应体验）：${parts.join('；')}`;
   }
   return { items, needsAttention, hint };
 }
 let OPTIONAL_HINT_DONE = false;
-/** 加载时提示一次（**装了/都齐则完全不吭声**；进程内最多一行）。 */
+/**
+ * 提示一次（**装了/都齐则完全不吭声**；进程内最多一行）。
+ * 语义保持：只在"真的有需要关注的东西"时打印，且只打印一次。
+ */
 function hintOptionalPluginsOnce(ctx) {
   if (OPTIONAL_HINT_DONE) return '';
   try {
@@ -1005,7 +1016,53 @@ function hintOptionalPluginsOnce(ctx) {
     return r.hint;
   } catch { return ''; }
 }
-function _resetOptionalHintOnce() { OPTIONAL_HINT_DONE = false; }
+/** 懒重探（`/team help` 等"真正用到"的时刻调用）：结果更新，但同一次进程里仍最多打印一行。 */
+function recheckOptionalPlugins(ctx) {
+  try { return detectOptionalPlugins(ctx); } catch { return { items: [], needsAttention: [], hint: '' }; }
+}
+// ── 探测时机（2026-09-15 第二轮修复）─────────────────────────────────────────────
+// **问题（用户贴的启动日志直接坐实）**：我们的 `apply()` 跑在其它插件之前，
+// 那一刻 `ctx.get('costMeter')` / 工具表里当然还没有它们 ⇒ 已装且可用的插件被误判成
+// `installed-not-ready`，日志里紧跟着 `dsh-cost-meter` 自己就加载成功了 ⇒ **假警报**。
+//
+// **宿主没有 app 级 ready 事件**（已核源码）：`dsh-app-boot` 的 `boot()` 顺序是
+// `await mountRootInclude(...)` → `await ctx.get('loader')?.await()` → `assertEntriesActivated` → return，
+// 期间**不 emit** 任何"就绪"事件（只 emit `loader/config-update`）。
+// 而 `loader.await()` 我们也**不能**用：那棵树包含我们自己的挂载任务 ⇒ 在 init 里 await 它会自等死锁。
+// ⇒ 采用两条**不会有死锁**的机制：
+//   ① 有界延迟重探（下面的 delays）：每次重探都拿最新事实，直到"无待关注项"或重试用尽；
+//   ② `ctx.inject([服务])` 事件驱动（服务/工具一旦出现立刻重探）—— 这是 cordis 的正确姿势，
+//      服务始终不出现时回调**只是不触发**，不会报错、也不阻塞。
+// 结果：**已装且可用的插件不再被误报**；刚装上的插件也不必为了这行提示再重启一次（懒重探兜底）。
+const OPTIONAL_PROBE_DELAYS_MS = [250, 1000, 3000];
+let OPTIONAL_PROBE_TIMERS = [];
+function scheduleOptionalPluginCheck(ctx, delays) {
+  const plan = Array.isArray(delays) ? delays : OPTIONAL_PROBE_DELAYS_MS;
+  const timers = [];
+  const run = (isLast) => {
+    if (OPTIONAL_HINT_DONE) return;
+    let r;
+    try { r = detectOptionalPlugins(ctx); } catch { return; }
+    if (!r.needsAttention.length) { OPTIONAL_HINT_DONE = true; return; } // 都就绪 ⇒ 一声不吭（且不再打扰）
+    if (isLast) { OPTIONAL_HINT_DONE = true; console.log(r.hint); }
+  };
+  plan.forEach((ms, i) => {
+    const t = setTimeout(() => run(i === plan.length - 1), ms);
+    if (t && typeof t.unref === 'function') t.unref();
+    timers.push(t);
+  });
+  OPTIONAL_PROBE_TIMERS = timers;
+  // 事件驱动兜底：服务一出现就重探（不出现则永不触发，零副作用）。
+  for (const svc of ['costMeter', 'tools']) {
+    try { if (ctx && typeof ctx.inject === 'function') ctx.inject([svc], () => run(true)); } catch { /* best-effort */ }
+  }
+  return timers;
+}
+function _resetOptionalHintOnce() {
+  OPTIONAL_HINT_DONE = false;
+  for (const t of OPTIONAL_PROBE_TIMERS) { try { clearTimeout(t); } catch { /* ignore */ } }
+  OPTIONAL_PROBE_TIMERS = [];
+}
 
 function warnInstallFailureOnce(kind) {
   if (INSTALL_FAILURE_WARNED.has(kind)) return;
@@ -2889,39 +2946,66 @@ function subHeaderIndex(ctx, subs, wfLabels) {
 }
 
 /**
- * 并发合并 + 短 TTL 的 `sessionQuery.listSessions()`。
+ * 并发合并 + **目录戳失效** + 长 TTL 的 `sessionQuery.listSessions()`。
  *
  * 为什么需要它（2026-09-15 性能诊断）：宿主的 listSessions 在持久化层是
- * **枚举全部 artifact、逐个读 header**（本机 475 个、实测 ~1.5–2.4 s），而 /state 每 3 秒轮询；
- * 客户端在飞重叠时更会 6 个请求同时跑 ⇒ 同一份枚举被重算 6 遍。
+ * **枚举全部 artifact、逐个读 header**（本机 475 个、实测 ~1.5–2.4 s），而 /state 每 3 秒轮询。
+ *
+ * **2026-09-15 第二轮（profile 实测 subs 段 1.3–1.4 s 之后的纠正）**：
+ *   ① **2 s TTL 等于没有**：真实请求间隔就在 2 s 上下（轮询 + 退避），必然过期 ⇒ 每请求重算。
+ *      现在 TTL 只作**兜底**（60 s），主失效键改成 `(sessions 根目录, mtimeMs, size)`
+ *      —— 新增/删除会话必然改动目录 mtime/size ⇒ **立刻失效**，不必靠 TTL 猜新鲜度。
+ *   ② **真正省时的是下面的 `SUB_HEADER_MEMO`**：按 session id 记住**不可变**的 header 字段，
+ *      第二个请求起**根本不再枚举**。这才是把 subs 段打到近 0 的手段，而不是调 TTL 骗自己。
  *
  * **缓存纪律（本仓对"看到的就是真的"很敏感，所以写死在这里）**：
- *   · 只服务"**已结束/已释放**的子代理"这一支（`listSubagentStatusBySession` 的兜底分支）——
- *     它们的 header 不再变化，短 TTL 不会让用户看到旧状态；
- *   · **活代理**的状态一律走 listChildren/agents **实时读**，绝不经过这个缓存；
- *   · 失效条件：2 s TTL（兜底）＋ 并发合并（同刻只跑一次）。TTL 之后必然重算，
- *     所以"新生效的会话"最多晚 2 秒可见 —— 这是**有界的**，且不会让在飞代理看起来停滞。
+ *   · 只服务"活注册表里**查不到**的子代理"这一支 ⇒ 都是**已结束/历史**会话，其 header 不再变化；
+ *   · **活代理**的状态一律走 listChildren/agents **实时读**，绝不经过这里的任何缓存；
+ *   · 目录戳取不到时退化为 60 s TTL 兜底（有界：新生效会话最多晚 60 s 可见，且只在 stat 失败时）。
  */
-const LIST_SESSIONS_TTL_MS = 2000;
-let LIST_SESSIONS_CACHE = { at: 0, sessions: null, inflight: null };
-async function cachedListSessions(q) {
+const LIST_SESSIONS_TTL_MS = 60000;
+let LIST_SESSIONS_CACHE = { at: 0, stamp: null, sessions: null, inflight: null };
+/** 会话目录的廉价失效戳（mtime + size）。取不到 ⇒ null ⇒ 只用 TTL 兜底。 */
+async function sessionsRootStamp() {
+  try {
+    const st = await stat(join(dshHome(), 'sessions'));
+    return `${Math.round(Number(st.mtimeMs) || 0)}:${Number(st.size) || 0}`;
+  } catch { return null; }
+}
+async function cachedListSessions(q, stamp) {
   const now = Date.now();
-  if (LIST_SESSIONS_CACHE.sessions && (now - LIST_SESSIONS_CACHE.at) < LIST_SESSIONS_TTL_MS) {
+  const stampOk = (stamp === undefined || stamp === null) ? true : (LIST_SESSIONS_CACHE.stamp === stamp);
+  if (LIST_SESSIONS_CACHE.sessions && (now - LIST_SESSIONS_CACHE.at) < LIST_SESSIONS_TTL_MS && stampOk) {
     return LIST_SESSIONS_CACHE.sessions;
   }
   if (LIST_SESSIONS_CACHE.inflight) return LIST_SESSIONS_CACHE.inflight; // 同刻只有一个枚举在跑
+  SUB_HEADER_STATS.enumCalls += 1;
   const p = Promise.resolve()
     .then(() => q.listSessions())
     .then((sessions) => {
-      LIST_SESSIONS_CACHE = { at: Date.now(), sessions: Array.isArray(sessions) ? sessions : [], inflight: null };
+      LIST_SESSIONS_CACHE = { at: Date.now(), stamp: (stamp === undefined ? null : stamp), sessions: Array.isArray(sessions) ? sessions : [], inflight: null };
       return LIST_SESSIONS_CACHE.sessions;
     })
-    .catch((e) => { LIST_SESSIONS_CACHE = { at: 0, sessions: null, inflight: null }; throw e; });
+    .catch((e) => { LIST_SESSIONS_CACHE = { at: 0, stamp: null, sessions: null, inflight: null }; throw e; });
   LIST_SESSIONS_CACHE.inflight = p;
   return p;
 }
 /** 仅供测试：清空枚举缓存并复位（生产代码不需要调用它）。 */
-function _resetListSessionsCache() { LIST_SESSIONS_CACHE = { at: 0, sessions: null, inflight: null }; }
+function _resetListSessionsCache() { LIST_SESSIONS_CACHE = { at: 0, stamp: null, sessions: null, inflight: null }; }
+
+// ── 已结束子会话的 header 备忘（按 session id，**永久**）─────────────────────────
+// createdAt / parentId / depth 对**已结束**会话是不可变的；而用到备忘的这条分支，其 id 恰恰是
+// "活注册表里查不到"的那些 ⇒ 记住它们**不会**让用户看到旧状态（活代理走实时路径，永不写入这里）。
+// 旧实现每请求都要枚举 475 个 artifact 才能回答"这些人是何时建的、谁派工的"——
+// 有了备忘，第二个请求起直接查表。
+const SUB_HEADER_MEMO = new Map();
+const SUB_HEADER_STATS = { memoHits: 0, memoWrites: 0, enumCalls: 0 };
+function _resetSubHeaderMemo() {
+  SUB_HEADER_MEMO.clear();
+  SUB_HEADER_STATS.memoHits = 0;
+  SUB_HEADER_STATS.memoWrites = 0;
+  SUB_HEADER_STATS.enumCalls = 0;
+}
 
 async function listSubagentStatusBySession(ctx, sid, knownIds) {
   const root = sid ? await rootSessionId(ctx, sid) : '';
@@ -2955,36 +3039,52 @@ async function listSubagentStatusBySession(ctx, sid, knownIds) {
   // Fallback: completed subagents may be disposed from the live registry —
   // the durable session projection (sessionQuery) still lists them.
   //
-  // ⚠️ 2026-09-15 性能修复：**只有真的缺人才花这笔钱**。
-  // 旧实现只要 `knownIds` 非空就无条件 `listSessions()`，而它在宿主侧是"枚举全部 artifact、
-  // 逐个读 header"（本机 475 个、~1.5–2.4 s）；代理都还在活注册表里时这笔钱白花。
-  // 现在先算"活注册表里查不到的人"，一个都不缺就整段跳过 ⇒ 常见情形直接省下这笔开销。
-  // 并发合并与 TTL 见 cachedListSessions() 的注释（缓存纪律写在那里）。
+  // ⚠️ 2026-09-15 两轮性能修复：
+  //   第一轮：只有**真的缺人**才花这笔钱（旧实现无条件 listSessions()）；
+  //   第二轮：缺的那些**先查 `SUB_HEADER_MEMO`**（已结束会话的 header 不可变 ⇒ 永久备忘），
+  //           只有仍然未知的才去枚举 ⇒ 第二个请求起通常**零枚举**。
   const missingIds = (knownIds || []).filter((id) => !rows.some((r) => r.id === id));
   if (missingIds.length) {
-    try {
-      const q = (ctx && typeof ctx.get === 'function') ? ctx.get('sessionQuery') : null;
-      if (q && typeof q.listSessions === 'function') {
-        const sessions = await cachedListSessions(q);
-        const byId = new Map(rows.map((r) => [r.id, r]));
-        for (const rec of sessions || []) {
-          const h = rec?.header || rec;
-          const aid = h?.id;
-          if (!aid || byId.has(aid) || !knownIds.includes(aid)) continue;
-          // ⚠️ header 里的 createdAt / parentSession / delegationDepth **必须带出来**。
-          // 旧实现只取 id，把它们丢掉，导致面板上每个成员都是 createdAt=0 ⇒ 流转图
-          // 判为「无创建时间记录，无法分批」，尽管会话日志第一行明明写着
-          // {"type":"session","createdAt":…,"parentSession":…,"delegationDepth":1}。
-          byId.set(aid, {
-            id: aid, mode: 'continuable', label: '', activity: 'inactive', model: '',
-            createdAt: Number(h?.createdAt) || 0,
-            parentId: String(h?.parentSession || ''),
-            depth: Number(h?.delegationDepth) || 0,
-          });
+    const memoById = new Map(rows.map((r) => [r.id, r]));
+    const stillUnknown = [];
+    for (const id of missingIds) {
+      const memo = SUB_HEADER_MEMO.get(id);
+      if (!memo) { stillUnknown.push(id); continue; }
+      SUB_HEADER_STATS.memoHits += 1;
+      memoById.set(id, {
+        id, mode: 'continuable', label: '', activity: 'inactive', model: '',
+        createdAt: memo.createdAt, parentId: memo.parentId, depth: memo.depth,
+      });
+    }
+    rows = [...memoById.values()];
+    if (stillUnknown.length) {
+      try {
+        const q = (ctx && typeof ctx.get === 'function') ? ctx.get('sessionQuery') : null;
+        if (q && typeof q.listSessions === 'function') {
+          const sessions = await cachedListSessions(q, await sessionsRootStamp());
+          const byId = new Map(rows.map((r) => [r.id, r]));
+          for (const rec of sessions || []) {
+            const h = rec?.header || rec;
+            const aid = h?.id;
+            if (!aid || byId.has(aid) || !knownIds.includes(aid)) continue;
+            // ⚠️ header 里的 createdAt / parentSession / delegationDepth **必须带出来**。
+            // 旧实现只取 id，把它们丢掉，导致面板上每个成员都是 createdAt=0 ⇒ 流转图
+            // 判为「无创建时间记录，无法分批」，尽管会话日志第一行明明写着
+            // {"type":"session","createdAt":…,"parentSession":…,"delegationDepth":1}。
+            const entry = {
+              createdAt: Number(h?.createdAt) || 0,
+              parentId: String(h?.parentSession || ''),
+              depth: Number(h?.delegationDepth) || 0,
+            };
+            // 只有"活注册表里查不到"的 id 会走到这里（活代理走实时路径）⇒ header 不可变 ⇒ 备忘安全。
+            SUB_HEADER_MEMO.set(aid, entry);
+            SUB_HEADER_STATS.memoWrites += 1;
+            byId.set(aid, { id: aid, mode: 'continuable', label: '', activity: 'inactive', model: '', ...entry });
+          }
+          rows = [...byId.values()];
         }
-        rows = [...byId.values()];
-      }
-    } catch { /* best-effort */ }
+      } catch { /* best-effort */ }
+    }
   }
   return Array.isArray(rows) ? rows : [];
 }
@@ -3056,16 +3156,52 @@ const SUB_ROLE_LOG_CACHE = new Map();
 // 投影/限量/流式参数 —— `projectionMode` 只存在于内部 `corpus.read`，公开方法不暴露；
 // `filterEvents`/`readEvent` 也都是"先把整条日志 load 进内存再筛"。要"只读首帧"只能绕过
 // 公开接口去碰持久化层的内部方法（`readFirstZstdLine` 之类），那是**非契约、脆的**。
-// ⇒ 采用**有界**做法：每次 /state 最多读 N 条子会话日志（角色结果**永久缓存**，几个 tick
-// 内自然收敛），其余留到下一个 tick。**这不是"优化成流式"，而是"把一次 20 秒的尖峰摊平"**，
-// 并把"本轮被推迟"的条数如实交给调用方（rolesDeferred）⇒「还没解析」与「解析不出来」
-// 两件事分得清（本仓纪律：两种零必须可区分），**不臆造角色**。
+// ⇒ 采用**有界**做法：每次 /state 最多读 N 条子会话日志（角色结果**永久缓存**），其余留到下一个 tick。
+// **这不是"优化成流式"，而是"把一次 20 秒的尖峰摊平"**，并把"本轮被推迟"的条数如实交给
+// 调用方（rolesDeferred）⇒「还没解析」与「解析不出来」两件事分得清
+// （本仓纪律：两种零必须可区分），**不臆造角色**。
+//
+// ⚠️ 2026-09-15 第二轮（profile 实测 roles 段 0.6–0.9 s、且 `deferred` 从 16 涨到 40 之后）：
+// 旧实现每请求都把候选集**从零重算**，预算永远花在队首那几条上，而新派的人不断出现在队尾
+// ⇒ **进度不前进、deferred 只增不减**（"限次摊平"退化成"永远摊不完"）。
+// 现在改成**跨请求保留进度**：每次按"当前 subs 里仍未缓存"的顺序**重建队列**（已缓存的自动掉队、
+// 既有顺序保留），再从队首消费 ≤N 条 ⇒ 进度单调推进，`deferred` 单调不增（除非真的又新派了人）。
 const ROLE_READ_BUDGET_PER_REQUEST = 4;
 let ROLE_READS_LEFT = ROLE_READ_BUDGET_PER_REQUEST;
-let ROLE_READS_DEFERRED = 0;
-/** /state 每次进来复位预算（同一请求内多次调用共享这一份）。 */
-function resetRoleReadBudget() { ROLE_READS_LEFT = ROLE_READ_BUDGET_PER_REQUEST; ROLE_READS_DEFERRED = 0; }
-function roleReadBudgetSnapshot() { return { per: ROLE_READ_BUDGET_PER_REQUEST, left: ROLE_READS_LEFT, deferred: ROLE_READS_DEFERRED }; }
+/** 待解析队列（跨请求保留进度）：元素是子会话 id。 */
+let ROLE_PENDING = [];
+/** /state 每次进来复位**本请求的读取额度**（队列进度**不**复位）。 */
+function resetRoleReadBudget() { ROLE_READS_LEFT = ROLE_READ_BUDGET_PER_REQUEST; }
+/**
+ * 按当前 subs 重建待解析队列：保留既有顺序里"仍在场且仍未缓存"的，再把新出现的未缓存 id 追加到队尾。
+ * 幂等、无副作用；已缓存（含"解析不出来"缓存为 ''）的条目自动掉队。
+ */
+function syncRolePending(subs) {
+  const present = new Set();
+  for (const s of subs || []) { const id = String((s && s.id) || ''); if (id) present.add(id); }
+  const seen = new Set();
+  const next = [];
+  for (const id of ROLE_PENDING) {
+    if (SUB_ROLE_LOG_CACHE.has(id) || !present.has(id) || seen.has(id)) continue;
+    seen.add(id); next.push(id);
+  }
+  for (const s of subs || []) {
+    const id = String((s && s.id) || '');
+    if (!id || seen.has(id) || SUB_ROLE_LOG_CACHE.has(id)) continue;
+    seen.add(id); next.push(id);
+  }
+  ROLE_PENDING = next;
+  return ROLE_PENDING;
+}
+/** 仅供测试：清空待解析队列（生产代码不需要调用它）。 */
+function _resetRolePending() { ROLE_PENDING = []; }
+function roleReadBudgetSnapshot() {
+  // deferred = **还没解析**（队列里等着读的）；unresolved = **解析不出来**（读过但日志里没有角色）。
+  // 两者必须是两个数：本仓纪律"两种零要分得清"。
+  let unresolved = 0;
+  for (const v of SUB_ROLE_LOG_CACHE.values()) if (!v) unresolved += 1;
+  return { per: ROLE_READ_BUDGET_PER_REQUEST, left: ROLE_READS_LEFT, deferred: ROLE_PENDING.length, unresolved };
+}
 /**
  * Infer a child's role from its own session log. **Only the first `user/message`
  * counts** — it is the delegation prompt the lead passed, e.g.
@@ -3078,9 +3214,9 @@ function roleReadBudgetSnapshot() { return { per: ROLE_READ_BUDGET_PER_REQUEST,
 async function roleFromChildLog(ctx, id) {
   if (!id) return '';
   if (SUB_ROLE_LOG_CACHE.has(id)) return SUB_ROLE_LOG_CACHE.get(id);
-  // 预算用尽 ⇒ 本轮不读，**且不写缓存**（下一 tick 再试）。这是"本轮被推迟"，
-  // 不是"解析不出来" —— 调用方通过 rolesDeferred 如实区分两者（两种零可区分）。
-  if (ROLE_READS_LEFT <= 0) { ROLE_READS_DEFERRED += 1; return ''; }
+  // 预算用尽 ⇒ 本轮不读，**且不写缓存**（下一个 tick 再试）。这是"本轮被推迟"，
+  // 不是"解析不出来" —— 调用方通过 rolesDeferred（队列长度）如实区分两者（两种零可区分）。
+  if (ROLE_READS_LEFT <= 0) { return ''; }
   ROLE_READS_LEFT -= 1;
   let role = '';
   try {
@@ -3232,16 +3368,33 @@ async function workflowRuns(ctx, sid, subs) {
  * （2026-09-11 真实踩到：30 个子代理里只有 5 个有角色，正是 wfLabels 解析不出的那 5 个。）
  */
 async function resolveSubRoles(ctx, subs, wfLabels) {
+  const byId = new Map();
+  for (const s of subs || []) { const id = String((s && s.id) || ''); if (id) byId.set(id, s); }
+  // ① 便宜来源（自带 label / 父会话事件流 label）与已缓存结果 —— **不花预算、不读日志**
   for (const s of subs || []) {
     try {
-      // ① 自带 label（显式角色/括号 id/关键词）与 ③ 父会话事件流的 workflow 派工 label
       const known = roleOfSub(s, wfLabels);
       if (known) { if (!s.role) s.role = known; continue; }
-      // ② 最后兜底：子会话首条 prompt
-      const r = await roleFromChildLog(ctx, String(s.id || ''));
-      if (r) s.role = r;
+      const id = String((s && s.id) || '');
+      if (!id) continue;
+      if (SUB_ROLE_LOG_CACHE.has(id)) {
+        const cached = SUB_ROLE_LOG_CACHE.get(id);
+        if (cached && !s.role) s.role = cached;
+      }
     } catch (e) { /* best-effort */ }
   }
+  // ② 跨请求推进：重建待解析队列（保留进度、已缓存的掉队、新人追加到队尾），再消费本请求额度。
+  //    这样 `deferred`（队列长度）只减不增，除非真的又新派了人 —— 旧实现每请求从零重算，
+  //    预算永远喂给队首同几条，新派的人永远轮不到（实测 deferred 16 → 40）。
+  syncRolePending(subs);
+  while (ROLE_READS_LEFT > 0 && ROLE_PENDING.length) {
+    const id = ROLE_PENDING.shift();
+    if (SUB_ROLE_LOG_CACHE.has(id)) continue;
+    const r = await roleFromChildLog(ctx, id);
+    if (!SUB_ROLE_LOG_CACHE.has(id)) { ROLE_PENDING.unshift(id); break; } // 预算耗尽（未写缓存）⇒ 放回队首，下一轮继续
+    const s = byId.get(id);
+    if (s && r && !s.role) s.role = r;
+  }
   return subs;
 }
 // sub rows → Map<role, sub> (first match wins; unknown labels map to '' and
@@ -4767,7 +4920,10 @@ async function executeTeamCommand(ctx, invocation) {
   const memRun = (mem && mem.workspace === cwd) ? mem.runId : '';
   const runArg = (s) => s || memRun;
   switch (c.kind) {
-    case 'help': return { kind: 'success', text: USAGE };
+    // 懒重探兜底（2026-09-15）：加载当刻的探测可能"太早"（那时别人的服务还没挂上）。
+    // `/team help` 是"用户真的来看能做什么"的时刻 ⇒ 顺手重探一次并更新结论，
+    // 这样刚装上/刚修好配置的插件**不必为了这一行提示再重启**。
+    case 'help': recheckOptionalPlugins(ctx); return { kind: 'success', text: USAGE };
     case 'status': return renderStatus(cwd);
     case 'members': return renderMembers(cwd);
     case 'models': return renderModels(cwd, runArg(c.run));
@@ -4812,7 +4968,7 @@ function warnLeadToolFaceOnce(status, detail) {
   LEAD_TOOLFACE_WARNED.add(status);
   console.warn(`[expert-team] lead 工具面**未**收窄（${status}）：${detail}`);
 }
-export const _live = { pushActivity, phaseAccountingViolations, loggedPhases, authorityViolations, WRITE_TRACER, createWriteTracer, formatConflict, summarizeTool, parseLogLine, roleOfSub, mapRoleToSub, membersFromState, buildRoleSubMap, resolveSubRoles, childSessionTiming, subHeaderIndex, sessionExists, SUB_HEADER_CACHE, workflowEventIndex, workflowChildLabels, workflowChildMeta, workflowRuns, WF_EVENT_CACHE, rememberSessionRun, sessionRunFor, runOwnerSession, SESSION_RUNS, parseTeamCommand, deriveMemberEntries, schemaViolations, runHealth, RUN_STALL_MS, scaffoldFingerprint, SCAFFOLD_REQUIRED, strandedTasks, settleStranded, IN_FLIGHT_STATUSES, normalizeCoverage, SCHEMA_WARN_SEEN, pushActivityEvent, DEFAULT_LIMITS, LIMITS, resolveLimits, capacityViolations, DEFAULT_ROUND_LIMITS, ROUND_LIMITS, ROUND_LIMIT_ENV, resolveRoundLimits, ROUND_LIMIT_OF_KIND, roundOf, isQualityTask, normTitle, roundLimitViolations, reworkLoopWriteGuard, mutateTasks, readStandingRules, appendStandingRule, rulesRun, scopeOverlapWarnings, applyTaskStatus, waitRun, eventFamily, verdictFromToken, normalizeRoleName, truncateCodepoints, filterRunScopedSubs, runCreatedAtMs, runLogTail, liveFiles, LIVE_FILES_CACHE, DEFAULT_ROLES, resolveTierGate, TIER_GATE_ENV, snapshotRun, settingsPath, loadSettingsSync, currentSettings, limitsBaseFromSettings, roundLimitsBaseFromSettings, effectiveTierGate: () => TIER_GATE, ensureSkillInstalled, ensurePresetInstalled, uninstallInstalled, buildSkillRegistration, parseSkillMarkdown, PLUGIN_VERSION, INSTALL_STAMP, runtimeSkillRegistered: () => RUNTIME_SKILL_REGISTERED, agentScopedToolNames, warnLeadToolFaceOnce, resolveLeadToolFace, LEAD_TOOLFACE_ENV, effectiveLeadToolFace: () => LEAD_TOOLFACE, resolveLoopGuard, LOOP_GUARD_ENV, effectiveLoopGuard: () => LOOP_GUARD_ENABLED, resolveRosterDefaults, rosterSettings, createRun, watchScript, canvasPollMs, installHostSettings, hostValues, hostScope, hostSettingsNote, updateHostSettings, pickFileOnly, pickHostExpressible, buildHostSchema, hostBase, hostSchemaPaths, reapplySettingsDerived, currentSettings, mergeSettings, detectOptionalPlugins, OPTIONAL_PLUGINS, hintOptionalPluginsOnce, _resetOptionalHintOnce, loaderEntryNames, hindsightToolReady, costMeterReady, listSubagentStatusBySession, cachedListSessions, _resetListSessionsCache, LIST_SESSIONS_TTL_MS, resetRoleReadBudget, roleReadBudgetSnapshot, ROLE_READ_BUDGET_PER_REQUEST, ROLE_READ_LOG_CACHE: SUB_ROLE_LOG_CACHE };
+export const _live = { pushActivity, phaseAccountingViolations, loggedPhases, authorityViolations, WRITE_TRACER, createWriteTracer, formatConflict, summarizeTool, parseLogLine, roleOfSub, mapRoleToSub, membersFromState, buildRoleSubMap, resolveSubRoles, childSessionTiming, subHeaderIndex, sessionExists, SUB_HEADER_CACHE, workflowEventIndex, workflowChildLabels, workflowChildMeta, workflowRuns, WF_EVENT_CACHE, rememberSessionRun, sessionRunFor, runOwnerSession, SESSION_RUNS, parseTeamCommand, deriveMemberEntries, schemaViolations, runHealth, RUN_STALL_MS, scaffoldFingerprint, SCAFFOLD_REQUIRED, strandedTasks, settleStranded, IN_FLIGHT_STATUSES, normalizeCoverage, SCHEMA_WARN_SEEN, pushActivityEvent, DEFAULT_LIMITS, LIMITS, resolveLimits, capacityViolations, DEFAULT_ROUND_LIMITS, ROUND_LIMITS, ROUND_LIMIT_ENV, resolveRoundLimits, ROUND_LIMIT_OF_KIND, roundOf, isQualityTask, normTitle, roundLimitViolations, reworkLoopWriteGuard, mutateTasks, readStandingRules, appendStandingRule, rulesRun, scopeOverlapWarnings, applyTaskStatus, waitRun, eventFamily, verdictFromToken, normalizeRoleName, truncateCodepoints, filterRunScopedSubs, runCreatedAtMs, runLogTail, liveFiles, LIVE_FILES_CACHE, DEFAULT_ROLES, resolveTierGate, TIER_GATE_ENV, snapshotRun, settingsPath, loadSettingsSync, currentSettings, limitsBaseFromSettings, roundLimitsBaseFromSettings, effectiveTierGate: () => TIER_GATE, ensureSkillInstalled, ensurePresetInstalled, uninstallInstalled, buildSkillRegistration, parseSkillMarkdown, PLUGIN_VERSION, INSTALL_STAMP, runtimeSkillRegistered: () => RUNTIME_SKILL_REGISTERED, agentScopedToolNames, warnLeadToolFaceOnce, resolveLeadToolFace, LEAD_TOOLFACE_ENV, effectiveLeadToolFace: () => LEAD_TOOLFACE, resolveLoopGuard, LOOP_GUARD_ENV, effectiveLoopGuard: () => LOOP_GUARD_ENABLED, resolveRosterDefaults, rosterSettings, createRun, watchScript, canvasPollMs, installHostSettings, hostValues, hostScope, hostSettingsNote, updateHostSettings, pickFileOnly, pickHostExpressible, buildHostSchema, hostBase, hostSchemaPaths, reapplySettingsDerived, currentSettings, mergeSettings, detectOptionalPlugins, OPTIONAL_PLUGINS, hintOptionalPluginsOnce, _resetOptionalHintOnce, scheduleOptionalPluginCheck, recheckOptionalPlugins, OPTIONAL_PROBE_DELAYS_MS, loaderEntryNames, hindsightToolReady, costMeterReady, listSubagentStatusBySession, cachedListSessions, _resetListSessionsCache, LIST_SESSIONS_TTL_MS, SUB_HEADER_MEMO, SUB_HEADER_STATS, _resetSubHeaderMemo, sessionsRootStamp, resetRoleReadBudget, roleReadBudgetSnapshot, syncRolePending, _resetRolePending, ROLE_READ_BUDGET_PER_REQUEST, ROLE_READ_LOG_CACHE: SUB_ROLE_LOG_CACHE };
 
 export function apply(ctx, config) {
   // 留一份 config：设置在运行时改变（官方面板 / 浮层）时要**用同一份 config** 重算上限与档位门，
@@ -4858,8 +5014,10 @@ export function apply(ctx, config) {
   // skill 已有运行时注册时这里立即返回（零成本）；只有宿主没有 skill 注册表时才真复制。
   installInBackground('skill', () => ensureSkillInstalled());
   // 推荐插件自检：纯读、缺了只打一行、装了完全不打扰（见 detectOptionalPlugins 的注释）。
-  // 放在加载路径上但**不 await**（探测本身是同步的，这里只是不阻塞后续注册）。
-  hintOptionalPluginsOnce(ctx);
+  // ⚠️ **不能在加载当刻就下结论**：我们的 apply() 跑在其它插件之前，那一刻 costMeter/工具表
+  // 里还没有它们 ⇒ 已装且可用的插件会被误判成"已安装但当前未就绪"（2026-09-15 真实假警报）。
+  // 现在改为**就绪后重探**（有界延迟 + `ctx.inject` 事件驱动，见 scheduleOptionalPluginCheck）。
+  scheduleOptionalPluginCheck(ctx);
   void loadSessionRuns(); // session→run memory for overlay auto-select
   ctx.commands.register({
     name: 'team',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yangdcm/dsh-expert-team",
-  "version": "1.3.10",
+  "version": "1.3.11",
   "description": "dsh「专家团」bundle：一句自然语言自动组建/持久化一支 12 角色多智能体团队，共享工作区协议 + 阶段门控编排 + 结构化交接 + 质量门禁/自动调度，实现者直接改代码并产出持久工件；带 live 团队浮层（质量门禁/覆盖率/工件预览）。 · Role-based multi-agent expert team for DeepSeek Harness: one sentence in, a staged and gated team delivery out.",
   "type": "module",
   "license": "MIT",