@yangdcm/dsh-expert-team 1.3.9 → 1.3.10

package/CHANGELOG.md

@@ -3,6 +3,59 @@
 本包遵循[语义化版本](https://semver.org/lang/zh-CN/)。dsh 宿主版本线的对应关系写在
 `package.json` 的 `engines.dsh` 与 `dsh.compatibility` 里，插件市场按它判断"这个插件跟你的宿主兼不兼容"。
 
+## 1.3.10
+
+**四项一次收口：推荐插件自检 · 画布轮询也走 single-flight · 底盘缓存 · 角色解析限次。**
+这一版全部由**真机实测**驱动，改动都带可复现的判据（下面每条都写明"改前 → 目标"）。
+
+### ① 启动时自检推荐插件（缺了说一句，装了不吭声）
+
+- 事实前提（只读调查）：本插件**零硬依赖** —— `package.json` 连 `dependencies` 字段都没有，
+  全库没有一条外部 import；点名到的外部插件只有 `@vectorize-io/hindsight-coding-agents`（工具名
+  `hindsight_*`）与 `dsh-cost-meter`，**缺了都不会报错**，只是少了对应体验。
+- `detectOptionalPlugins(ctx)`（**纯读、无副作用**）三条探测路径：
+  ① `ctx.get('loader').entries()` 的 `options.name` = **装没装**；
+  ② `ctx.get('costMeter')`（服务名是**驼峰**）= 费用插件是否可用；
+  ③ `ctx.get('tools').get('hindsight_ingest_document')` = **此刻能不能用** —— Hindsight 在
+  "装了但未配置/被 opt-out"时**根本不注册工具**，所以这一条天然把「没装」与「装了没配」分开。
+- 状态四态：`ready` / `missing` / `installed-not-ready` / `unknown`（loader 探测不可用 + 服务也
+  拿不到时**不假装知道**，且不进提示）。
+- 加载时**最多一行**（进程内去重），都齐则**完全不打扰**；`/team help` 里加一行说明。
+
+### ② 客户端的**所有** /state 轮询统一走一个 hub（上一版只护住了面板）
+
+- 实测问题：面板一套 `load()`（1.3.5 已加守卫），而 `HeaderButton` 徽章与画布另走 `liveStore` 的
+  `setInterval(liveTick, 2500)` —— **画布一开就有 2–3 个轮询并发压同一个重端点**：10 秒 **7 发**、
+  **6 次重叠**，单发被拖到 **5,891 / 8,347 ms**（并发叠加服务端约 2 s 的同步 CPU）。
+- 现在只有 `stateHub` 一个时钟、一份在飞表：**同 URL 同刻只跑一次**（后来者复用在飞 promise）、
+  全局单一时钟、统一退避 `clamp(max(基础间隔, 最慢一次×2), 基础间隔, 30000)`，
+  团队有人跑时基础间隔按 40% 加速（面板原有意图，现在对徽章/画布同样生效）。
+- 结构性护栏：`client.js` 里**不再存在**任何裸的 `fetch('/plugins/dsh-expert-team/state…')`
+  （唯一调用点在 `stateHubFetch` 内），也**只剩一个** `setInterval(stateHubTick, …)`。
+
+### ③ 底盘：`listSessions` 只在真缺人时查 + 并发合并 + 短 TTL
+
+- 实测残留：`/state` 热态仍是 **2,887 / 2,603 ms**（诊断点名的"固定底盘 1500–2400 ms"）。
+- 两处都遵循"**先证明需要，再花这笔钱**"：① 旧实现只要 `knownIds` 非空就无条件
+  `listSessions()`（宿主侧 = 枚举全部 artifact、逐个读 header，本机 475 个、~1.5–2.4 s），
+  现在先算"活注册表里查不到的人"，一个不缺就整段跳过；② 真的要查时**并发合并 + 2 s TTL**。
+- **缓存纪律（写死在注释里）**：只服务"已结束/已释放子代理"这一支（其 header 不再变化）；
+  **活代理一律走 listChildren/agents 实时读，绝不经过缓存**；失败不毒化缓存。
+- 另加**分步计时**（`DSH_EXPERT_TEAM_STATE_PROFILE=1` 才收集，默认响应体不变）：
+  `profile: {runs+select, subs, wfLabels, roles, tail, rolesBudget}` —— 让"哪一步还贵"下一次**可测**
+  而不是靠猜。
+
+### ④ 角色解析：**限次摊平**（不是流式，且不假装流式）
+
+- 诊断建议"真流式：读到首条 `user/message` 即停"。**做不到**：宿主公开 API
+  （`readSession/listEvents/filterEvents/readEvent`）**没有**投影/限量/流式参数
+  （`projectionMode` 只在内部 corpus.read），要"只读首帧"只能碰持久化层的非契约内部方法。
+- 改为**有界**：每次 `/state` 最多读 **4** 条子会话日志（角色结果**永久缓存** ⇒ 几个 tick 内收敛），
+  其余留到下一 tick，并把"本轮被推迟"的条数作为 `rolesDeferred` **如实**交给调用方 ——
+  「还没解析」与「解析不出来」两件事**分得清**（两种零可区分），**不臆造角色**。
+
+> 本版**未**改文档/图片（`README*.md`、`docs/images/*` 是前几版刚定稿的）；未改 `files` 字段。
+
 ## 1.3.9
 
 **新增第二张真实画布截图：`事` 视图（任务依赖图）**（纯文档/资产：`lib/`、`client.js` 零改动）。

package/client.js

@@ -1342,7 +1342,6 @@ window.__ModuleLoader__.load({
       var draftMeta = useRef({ loadedAt: '', dirty: false })
       var planMsgS = useState(''); var planMsg = planMsgS[0], setPlanMsg = planMsgS[1]
       var err = useState(''); var errV = err[0], setErr = err[1]
-      var pollRef = useRef(0)
 
       function stateUrl() {
         var url = '/plugins/dsh-expert-team/state', q = []
@@ -1350,23 +1349,12 @@ window.__ModuleLoader__.load({
         if (selRunV && selRunV.workspace && selRunV.runId) { q.push('workspace=' + encodeURIComponent(selRunV.workspace)); q.push('run=' + encodeURIComponent(selRunV.runId)) }
         return url + (q.length ? ('?' + q.join('&')) : '')
       }
-      // ── single-flight + 自适应退避（2026-09-15 性能修复）──────────────────────────
-      // 实测：8 秒内曾发 5 个 /state、其中 4 个重叠，而单发可达 7–283 秒 ⇒ 队列只增不减，
-      // 服务端被压垮（连轻量端点 /settings 都涨到 20.7 s / 42.5 s，整个 dsh web 一起卡）。
-      // 两条纪律：① **未回绝不发下一个**（晚一点看到状态，好过把 web 拖死）；
-      //          ② 间隔随上次耗时**退避**（见 reschedule），重活端点不该 1.2 秒一发。
-      var inFlightRef = useRef(false)
-      var lastMsRef = useRef(0)
-      function load() {
-        if (inFlightRef.current) return
-        inFlightRef.current = true
-        var t0 = (window.performance && performance.now) ? performance.now() : Date.now()
-        var done = function () {
-          inFlightRef.current = false
-          var now = (window.performance && performance.now) ? performance.now() : Date.now()
-          lastMsRef.current = Math.max(0, now - t0)
-        }
-        fetch(stateUrl()).then(function (r) { return r.ok ? r.json() : null }).then(function (d) {
+      // ── 数据到达后的副作用（**本组件不再自带轮询器**；由 stateHub 统一驱动）─────────
+      // 2026-09-15 性能修复 #2：面板原先自己 hold 一个 setInterval + in-flight 守卫，而徽章与
+      // 画布另走 liveStore 的 setInterval ⇒ 画布一开就有 2–3 个轮询并发压同一个重端点
+      // （实测 10 秒 7 发、6 次重叠、单发被拖到 5.9/8.3 s）。现在全部经 stateHub：
+      // 同 URL 同刻只跑一次、全局单一时钟、统一退避（见 stateHub 的注释）。
+      function onState(d) {
           if (d && d.ok) {
             setData(d); setErr(''); reschedule(d)
             // N2: keep the composer takeover in sync with pendingDecision
@@ -1400,30 +1388,16 @@ window.__ModuleLoader__.load({
             } catch (e) {}
           } else if (d && !d.ok && d.runsAvailable === 0) { setData(null); if (d.runs) setRunsMeta(d.runs); setErr(t('还没有专家团 run。先运行 /team <task> 开一个。', 'No team run yet — run /team <task> first.')) }
           else if (d && !d.ok) { if (d.runs) setRunsMeta(d.runs); setErr(d.error || ''); }
-        }).catch(function () {}).then(done, done)
-      }
-      // Adaptive refresh: while any member is running, poll fast (workers are
-      // touching files right now); otherwise the configured cadence.
-      // 2026-09-15：再叠一层**退避** —— 间隔 = clamp(max(基础间隔, 上次耗时×2), 基础间隔, 30000)。
-      // 单发越慢 ⇒ 下次越晚；display.pollMs 仍是基础节奏（设置里那一项依然说了算）。
-      function reschedule(d) {
-        var m = (d && d.members) || {}
-        var busy = Object.keys(m).some(function (k) { var v = m[k]; return v && typeof v === 'object' && (v.activity === 'running' || v.shortStatus === 'running') })
-        clearInterval(pollRef.current)
-        // 1.3.4：间隔来自设置 display.pollMs（忙碌时按同一意图加速到 40%，下限 300ms）
-        var base = busy ? Math.max(300, Math.round(dispCfg.pollMs * 0.4)) : dispCfg.pollMs
-        var backoff = Math.max(base, Math.min(30000, Math.round((lastMsRef.current || 0) * 2)))
-        pollRef.current = setInterval(load, backoff)
       }
       useEffect(function () {
         if (!isOpen && !viewMode) return undefined // panel closed & not canvas → no polling
-        load(); pollRef.current = setInterval(load, dispCfg.pollMs)
+        var off = stateHubSubscribe(stateUrl(), dispCfg.pollMs, onState)
         // catch up instantly when the user returns to the tab / window
-        var onVis = function () { if (document.visibilityState === 'visible') load() }
-        var onFocus = function () { load() }
+        var onVis = function () { if (document.visibilityState === 'visible') stateHubFetch(stateUrl(), onState) }
+        var onFocus = function () { stateHubFetch(stateUrl(), onState) }
         document.addEventListener('visibilitychange', onVis)
         window.addEventListener('focus', onFocus)
-        return function () { clearInterval(pollRef.current); document.removeEventListener('visibilitychange', onVis); window.removeEventListener('focus', onFocus) }
+        return function () { off(); document.removeEventListener('visibilitychange', onVis); window.removeEventListener('focus', onFocus) }
       }, [sessionId, selRunV, isOpen, viewMode, dispCfg.pollMs])
 
       // Make the docked panel reserve space (shift the shell frame) instead of
@@ -2365,17 +2339,93 @@ window.__ModuleLoader__.load({
     function Boundary(props) { var e = useState(null); if (e[0]) return h('div', { className: 'exp-preview' }, t('专家团面板渲染出错：', 'Team panel render error: ') + esc(String(e[0] && e[0].message || e[0]))); return h('div', {}, props.children) }
     function wrap(Component) { return function (props) { return h(Boundary, null, h(Component, props || {})) } }
 
+    // ── 统一的 /state 加载器（2026-09-15 性能修复 #2）────────────────────────────
+    // 为什么必须统一：同一个重端点在客户端曾有三套轮询 —— 面板组件自己的 load()、
+    // HeaderButton 徽章与画布共用的 liveStore.liveTick()（还有画布标签自己那一份）。
+    // 画布一开就有 2–3 个 setInterval 并发压同一个 /state（实测 10 秒 7 发、6 次重叠，
+    // 单发被拖到 5.9/8.3 s；服务端每请求还有 ~2 s 同步 CPU ⇒ 把整个 web 一起拖慢）。
+    // 现在**所有** /state 拉取都经这里：
+    //   ① 同一 URL 同刻只跑一次（in-flight 合并，后来者复用在飞 promise 的结果）；
+    //   ② 全局**一个**时钟（不再每个组件一个 setInterval）；
+    //   ③ 间隔 = clamp(max(基础间隔, 上次耗时×2), 基础间隔, 30000)；
+    //      团队有人在跑时基础间隔按 40% 加速（面板原有意图，现在对徽章/画布同样生效）。
+    // 纪律不变：**未回绝不发下一个**（晚一点看到状态，好过把 web 拖死）。
+    var stateHub = { inflight: {}, lastMs: {}, subs: [], timer: 0, busy: false }
+    function stateHubNow() { return (window.performance && performance.now) ? performance.now() : Date.now() }
+    function stateHubUrls() { var out = []; stateHub.subs.forEach(function (x) { if (out.indexOf(x.url) < 0) out.push(x.url) }) ; return out }
+    function stateHubBase() {
+      var base = 0
+      stateHub.subs.forEach(function (x) { if (!base || x.base < base) base = x.base })
+      if (!base) base = 3000
+      return stateHub.busy ? Math.max(300, Math.round(base * 0.4)) : base
+    }
+    function stateHubSchedule() {
+      clearInterval(stateHub.timer)
+      stateHub.timer = 0
+      if (!stateHub.subs.length) return
+      var slowest = 0
+      stateHubUrls().forEach(function (u) { if ((stateHub.lastMs[u] || 0) > slowest) slowest = stateHub.lastMs[u] })
+      var base = stateHubBase()
+      var next = Math.max(base, Math.min(30000, Math.round(slowest * 2)))
+      stateHub.timer = setInterval(stateHubTick, next)
+    }
+    function stateHubDeliver(url) {
+      return function (d) {
+        var list = stateHub.subs.slice()
+        for (var i = 0; i < list.length; i++) { if (list[i].url === url) { try { list[i].onData(d) } catch (e) {} } }
+      }
+    }
+    function stateHubFetch(url, onData) {
+      if (typeof fetch === 'undefined') return
+      var p = stateHub.inflight[url]
+      if (p) { p.then(function (d) { try { onData(d) } catch (e) {} }); return }  // 同刻同 URL：复用在飞结果
+      var t0 = stateHubNow()
+      p = fetch(url).then(function (r) { return r.ok ? r.json() : null }).then(function (d) {
+        delete stateHub.inflight[url]
+        stateHub.lastMs[url] = Math.max(0, stateHubNow() - t0)
+        return d
+      }, function () { delete stateHub.inflight[url]; return null })
+      stateHub.inflight[url] = p
+      p.then(function (d) { try { onData(d) } catch (e) {} })
+    }
+    function stateHubTick() {
+      if (!stateHub.subs.length) { clearInterval(stateHub.timer); stateHub.timer = 0; return }
+      stateHubUrls().forEach(function (u) { stateHubFetch(u, stateHubDeliver(u)) })
+      stateHubSchedule()
+    }
+    function stateHubSubscribe(url, base, onData) {
+      var sub = { url: url, base: base || 3000, onData: onData }
+      stateHub.subs.push(sub)
+      stateHubFetch(url, onData)      // 立即拉一次（面板/徽章打开即有数据）
+      stateHubSchedule()
+      return function () {
+        var i = stateHub.subs.indexOf(sub)
+        if (i >= 0) stateHub.subs.splice(i, 1)
+        if (!stateHub.subs.length) { clearInterval(stateHub.timer); stateHub.timer = 0 }
+        else stateHubSchedule()
+      }
+    }
+
     // ── 共享 state 轮询（HeaderButton / LiveCapsule 复用，单例；无订阅者即停）──
-    var liveStore = { data: null, sid: '', timer: 0, subs: new Set() }
+    var liveStore = { data: null, sid: '', off: null, subs: new Set() }
+    var LIVE_BASE_MS = 2500   // 徽章/画布的基础节奏（与面板的 dispCfg.pollMs 取更小者由 hub 统一决定）
+    function liveUrl(sid) { return '/plugins/dsh-expert-team/state?sessionId=' + encodeURIComponent(sid) }
+    // 手动催一次（子代理刚出现时立刻刷新一次徽章，不必等下一个 tick）
     function liveTick() {
       var sid = liveStore.sid
       if (!sid || typeof fetch === 'undefined') return
-      fetch('/plugins/dsh-expert-team/state?sessionId=' + encodeURIComponent(sid)).then(function (r) { return r.ok ? r.json() : null }).then(function (d) {
-        if (!d) return
-        liveStore.data = d
-        try { harvestActivity(d) } catch (e) {}
-        liveStore.subs.forEach(function (f) { try { f(d) } catch (e) {} })
-      }).catch(function () {})
+      stateHubFetch(liveUrl(sid), liveDeliver)
+    }
+    function liveDeliver(d) {
+      if (!d) return
+      liveStore.data = d
+      try { harvestActivity(d) } catch (e) {}
+      try { stateHub.busy = teamBusy(d) } catch (e) {}
+      liveStore.subs.forEach(function (f) { try { f(d) } catch (e) {} })
+    }
+    function teamBusy(d) {
+      var m = (d && d.members) || {}
+      return Object.keys(m).some(function (k) { var v = m[k]; return v && typeof v === 'object' && (v.activity === 'running' || v.shortStatus === 'running') })
     }
     function useLiveState(sid) {
       var st = useState(liveStore.data); var data = st[0], setData = st[1]
@@ -2384,10 +2434,11 @@ window.__ModuleLoader__.load({
         liveStore.sid = sid
         var fn = function (d) { setData(d) }
         liveStore.subs.add(fn)
-        if (!liveStore.timer) { liveTick(); liveStore.timer = setInterval(liveTick, 2500) }
+        // 经 hub 订阅：与面板/画布共用同一个时钟与在飞守卫（这里**不再**自己 setInterval）
+        var off = stateHubSubscribe(liveUrl(sid), LIVE_BASE_MS, liveDeliver)
         return function () {
           liveStore.subs.delete(fn)
-          if (!liveStore.subs.size && liveStore.timer) { clearInterval(liveStore.timer); liveStore.timer = 0 }
+          off()
         }
       }, [sid])
       return data

package/lib/command-parse.js

@@ -60,6 +60,7 @@ export const USAGE = [
   '  /team wait [<run>]                 查看在飞任务进展（不阻塞；无进展超 5 分钟会提示）',
   '  /team clear [<run>]                清理一个或全部 run',
   '  /team uninstall                    回收本插件铺到 $DSH_HOME 的副本（skill 现默认走运行时注册，本就不落地）',
+  '  ⓘ 推荐插件（可选，缺了不报错）：Hindsight = 跨项目记忆；dsh-cost-meter = 费用视图',
 ].join('\n');
 
 // ── command parsing ────────────────────────────────────────────────────────

package/lib/command.js

@@ -906,6 +906,107 @@ async function uninstallInstalled() {
  * 会把"响亮"变成噪声，而噪声的代价是所有告警一起被降权。
  */
 const INSTALL_FAILURE_WARNED = new Set();
+// ── 推荐插件自检（2026-09-15 · 用户要求）───────────────────────────────────────
+// 事实（只读调查结论，别再重证）：本插件**零硬依赖** —— package.json 连 `dependencies`
+// 字段都没有，全库没有一条外部 import；下面这些插件**缺了都不会报错**，只是会让某些体验打折。
+// 所以这里只做一件事：**装了就一声不吭，缺了说一句怎么办**（不吓人、不重复、不影响加载）。
+//
+// 三条探测路径（都有宿主源码依据）：
+//   ① loader 条目（`ctx.get('loader').entries()` → `options.name`）= **装没装**（最通用）；
+//   ② 服务探测（`ctx.get('costMeter')`）= 费用插件是否可用（服务名是**驼峰** costMeter）；
+//   ③ 工具探测（`ctx.get('tools').get('hindsight_ingest_document')`）= **此刻能不能用**：
+//      Hindsight 在"装了但未配置/被 opt-out"时**根本不注册工具**（其 registerTools 开头
+//      模板不可用即 return）⇒ 这一条天然把「没装」与「装了没配」分开 —— 两种零可区分。
+// 全部 best-effort：任何异常都当"不知道"，**绝不**因此影响插件加载。
+const OPTIONAL_PLUGINS = [
+  {
+    id: 'hindsight',
+    pkg: '@vectorize-io/hindsight-coding-agents',
+    match: (name) => name === '@vectorize-io/hindsight-coding-agents' || name.indexOf('@vectorize-io/hindsight-coding-agents/') === 0,
+    what: '跨项目/跨会话长期记忆（clarify 前召回、deliver 时落库）',
+    install: 'dsh plugin --profile web add @vectorize-io/hindsight-coding-agents',
+  },
+  {
+    id: 'cost-meter',
+    pkg: 'dsh-cost-meter',
+    match: (name) => name === 'dsh-cost-meter' || name.indexOf('dsh-cost-meter/') === 0,
+    what: '会话费用 / token 账（浮层「在用模型」那一行指向它）',
+    install: 'dsh plugin --profile web add dsh-cost-meter',
+  },
+];
+/** 装了哪些插件（loader 条目名）。返回 null = 探测不可用（**不是**"没装"）。 */
+function loaderEntryNames(ctx) {
+  try {
+    const loader = ctx && typeof ctx.get === 'function' ? ctx.get('loader') : null;
+    if (!loader || typeof loader.entries !== 'function') return null;
+    const out = [];
+    for (const entry of loader.entries() || []) {
+      const n = entry && entry.options && entry.options.name;
+      if (n) out.push(String(n));
+    }
+    return out;
+  } catch { return null; }
+}
+/** 工具面探测：Hindsight 的工具在"未配置/被关"时压根不注册 ⇒ 天然区分没装与装了没配。 */
+function hindsightToolReady(ctx) {
+  try {
+    const tools = ctx && typeof ctx.get === 'function' ? ctx.get('tools') : null;
+    if (!tools || typeof tools.get !== 'function') return null;
+    return !!tools.get('hindsight_ingest_document');
+  } catch { return null; }
+}
+function costMeterReady(ctx) {
+  try { return !!(ctx && typeof ctx.get === 'function' && ctx.get('costMeter')); } catch { return null; }
+}
+/**
+ * 自检推荐插件。**纯读、无副作用**。
+ * @returns {{items:Array, needsAttention:Array, hint:string}}
+ *   status: 'ready'（装了且可用）/ 'installed-not-ready'（装了但当下不可用）/ 'missing'（没装）
+ *           / 'unknown'（探测不可用 ⇒ 不下结论）
+ */
+function detectOptionalPlugins(ctx) {
+  const names = loaderEntryNames(ctx);
+  const items = OPTIONAL_PLUGINS.map((spec) => {
+    const installed = names ? names.some(spec.match) : null; // null = 探测不可用
+    const usable = spec.id === 'hindsight' ? hindsightToolReady(ctx) : (spec.id === 'cost-meter' ? costMeterReady(ctx) : null);
+    let status;
+    // 只有**确定**的结论才给确定的状态：
+    //   · 工具/服务可用 ⇒ ready（最强的肯定证据）；
+    //   · loader 明确列出"没有" ⇒ missing（确定没装）；
+    //   · loader 列出有、但工具/服务不可用 ⇒ installed-not-ready（装了没配 —— 第二种零）；
+    //   · 其余（loader 探测不可用 **且** 服务也拿不到）⇒ **unknown**：这时"没装"与"装了没配"
+    //     分不开，就**不假装知道**。unknown 不进提示、不阻断任何功能。
+    if (usable === true) status = 'ready';
+    else if (installed === false) status = 'missing';
+    else if (installed === true && usable === false) status = 'installed-not-ready';
+    else status = 'unknown';
+    return { id: spec.id, pkg: spec.pkg, what: spec.what, install: spec.install, installed, usable, status };
+  });
+  const needsAttention = items.filter((i) => i.status === 'missing' || i.status === 'installed-not-ready');
+  let hint = '';
+  if (needsAttention.length) {
+    const parts = needsAttention.map((i) => {
+      const why = i.status === 'missing' ? '未安装' : '已安装但当前不可用（未配置或被关闭）';
+      return `${i.pkg}（${i.what}）：${why} ⇒ ${i.install}`;
+    });
+    hint = `[expert-team] 推荐插件未就绪（不影响使用，只是少了对应体验）：${parts.join('；')}`;
+  }
+  return { items, needsAttention, hint };
+}
+let OPTIONAL_HINT_DONE = false;
+/** 加载时提示一次（**装了/都齐则完全不吭声**；进程内最多一行）。 */
+function hintOptionalPluginsOnce(ctx) {
+  if (OPTIONAL_HINT_DONE) return '';
+  try {
+    const r = detectOptionalPlugins(ctx);
+    if (!r.hint) return '';
+    OPTIONAL_HINT_DONE = true;
+    console.log(r.hint);
+    return r.hint;
+  } catch { return ''; }
+}
+function _resetOptionalHintOnce() { OPTIONAL_HINT_DONE = false; }
+
 function warnInstallFailureOnce(kind) {
   if (INSTALL_FAILURE_WARNED.has(kind)) return;
   INSTALL_FAILURE_WARNED.add(kind);
@@ -2787,6 +2888,41 @@ function subHeaderIndex(ctx, subs, wfLabels) {
   return out;
 }
 
+/**
+ * 并发合并 + 短 TTL 的 `sessionQuery.listSessions()`。
+ *
+ * 为什么需要它（2026-09-15 性能诊断）：宿主的 listSessions 在持久化层是
+ * **枚举全部 artifact、逐个读 header**（本机 475 个、实测 ~1.5–2.4 s），而 /state 每 3 秒轮询；
+ * 客户端在飞重叠时更会 6 个请求同时跑 ⇒ 同一份枚举被重算 6 遍。
+ *
+ * **缓存纪律（本仓对"看到的就是真的"很敏感，所以写死在这里）**：
+ *   · 只服务"**已结束/已释放**的子代理"这一支（`listSubagentStatusBySession` 的兜底分支）——
+ *     它们的 header 不再变化，短 TTL 不会让用户看到旧状态；
+ *   · **活代理**的状态一律走 listChildren/agents **实时读**，绝不经过这个缓存；
+ *   · 失效条件：2 s TTL（兜底）＋ 并发合并（同刻只跑一次）。TTL 之后必然重算，
+ *     所以"新生效的会话"最多晚 2 秒可见 —— 这是**有界的**，且不会让在飞代理看起来停滞。
+ */
+const LIST_SESSIONS_TTL_MS = 2000;
+let LIST_SESSIONS_CACHE = { at: 0, sessions: null, inflight: null };
+async function cachedListSessions(q) {
+  const now = Date.now();
+  if (LIST_SESSIONS_CACHE.sessions && (now - LIST_SESSIONS_CACHE.at) < LIST_SESSIONS_TTL_MS) {
+    return LIST_SESSIONS_CACHE.sessions;
+  }
+  if (LIST_SESSIONS_CACHE.inflight) return LIST_SESSIONS_CACHE.inflight; // 同刻只有一个枚举在跑
+  const p = Promise.resolve()
+    .then(() => q.listSessions())
+    .then((sessions) => {
+      LIST_SESSIONS_CACHE = { at: Date.now(), 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; });
+  LIST_SESSIONS_CACHE.inflight = p;
+  return p;
+}
+/** 仅供测试：清空枚举缓存并复位（生产代码不需要调用它）。 */
+function _resetListSessionsCache() { LIST_SESSIONS_CACHE = { at: 0, sessions: null, inflight: null }; }
+
 async function listSubagentStatusBySession(ctx, sid, knownIds) {
   const root = sid ? await rootSessionId(ctx, sid) : '';
   let rows = [];
@@ -2818,11 +2954,18 @@ async function listSubagentStatusBySession(ctx, sid, knownIds) {
   }
   // Fallback: completed subagents may be disposed from the live registry —
   // the durable session projection (sessionQuery) still lists them.
-  if (knownIds && knownIds.length) {
+  //
+  // ⚠️ 2026-09-15 性能修复：**只有真的缺人才花这笔钱**。
+  // 旧实现只要 `knownIds` 非空就无条件 `listSessions()`，而它在宿主侧是"枚举全部 artifact、
+  // 逐个读 header"（本机 475 个、~1.5–2.4 s）；代理都还在活注册表里时这笔钱白花。
+  // 现在先算"活注册表里查不到的人"，一个都不缺就整段跳过 ⇒ 常见情形直接省下这笔开销。
+  // 并发合并与 TTL 见 cachedListSessions() 的注释（缓存纪律写在那里）。
+  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 q.listSessions();
+        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;
@@ -2907,6 +3050,22 @@ function roleOfSub(sub, wfLabels) {
 // A child's role never changes, and reading its log is the expensive path —
 // cache once per child session id ('' entries are cached too, to avoid re-reads).
 const SUB_ROLE_LOG_CACHE = new Map();
+// ── 每请求的"子会话日志读取"预算（2026-09-15）──────────────────────────────────
+// 诊断建议改成"真流式：读到首条 user/message 即停"。**做不到，且不假装做到**：
+// 宿主公开 API（`sessionQuery.readSession/listEvents/filterEvents/readEvent`）**没有**
+// 投影/限量/流式参数 —— `projectionMode` 只存在于内部 `corpus.read`，公开方法不暴露；
+// `filterEvents`/`readEvent` 也都是"先把整条日志 load 进内存再筛"。要"只读首帧"只能绕过
+// 公开接口去碰持久化层的内部方法（`readFirstZstdLine` 之类），那是**非契约、脆的**。
+// ⇒ 采用**有界**做法：每次 /state 最多读 N 条子会话日志（角色结果**永久缓存**，几个 tick
+// 内自然收敛），其余留到下一个 tick。**这不是"优化成流式"，而是"把一次 20 秒的尖峰摊平"**，
+// 并把"本轮被推迟"的条数如实交给调用方（rolesDeferred）⇒「还没解析」与「解析不出来」
+// 两件事分得清（本仓纪律：两种零必须可区分），**不臆造角色**。
+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 }; }
 /**
  * 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.
@@ -2919,6 +3078,10 @@ const SUB_ROLE_LOG_CACHE = new Map();
 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 ''; }
+  ROLE_READS_LEFT -= 1;
   let role = '';
   try {
     const q = ctx && typeof ctx.get === 'function' ? ctx.get('sessionQuery') : null;
@@ -4649,7 +4812,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 };
+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 function apply(ctx, config) {
   // 留一份 config：设置在运行时改变（官方面板 / 浮层）时要**用同一份 config** 重算上限与档位门，
@@ -4694,6 +4857,9 @@ export function apply(ctx, config) {
   installInBackground('preset', () => ensurePresetInstalled());
   // skill 已有运行时注册时这里立即返回（零成本）；只有宿主没有 skill 注册表时才真复制。
   installInBackground('skill', () => ensureSkillInstalled());
+  // 推荐插件自检：纯读、缺了只打一行、装了完全不打扰（见 detectOptionalPlugins 的注释）。
+  // 放在加载路径上但**不 await**（探测本身是同步的，这里只是不阻塞后续注册）。
+  hintOptionalPluginsOnce(ctx);
   void loadSessionRuns(); // session→run memory for overlay auto-select
   ctx.commands.register({
     name: 'team',
@@ -4916,6 +5082,13 @@ export function apply(ctx, config) {
               const json = (code, body) => { res.writeHead(code, { 'content-type': 'application/json; charset=utf-8' }); res.end(JSON.stringify(body)); };
               try {
                 if (req.method !== 'GET') { res.writeHead(405); res.end(); return; }
+                // 每请求复位"子会话日志读取"预算（见 roleFromChildLog 的注释）。
+                resetRoleReadBudget();
+                // 分步计时：只有显式打开才收集，平时零成本（不打印、不进响应）。
+                // 用途：装上新版后**由人**核对"哪一步还贵"，而不是靠猜——验收需要可复现数字。
+                const STATE_PROFILE_ON = String((typeof process !== 'undefined' && process.env && process.env.DSH_EXPERT_TEAM_STATE_PROFILE) || '') === '1';
+                const prof = STATE_PROFILE_ON ? { at: Date.now(), steps: {} } : null;
+                const mark = (name) => { if (prof) { const n = Date.now(); prof.steps[name] = n - prof.at; prof.at = n; } };
                 const url = new URL(req.url ?? '/plugins/dsh-expert-team/state', 'http://127.0.0.1');
                 const sid = (url.searchParams.get('sessionId') ?? '').trim();
                 // cwd is OPTIONAL: if absent (e.g. overlay has no session id), fall
@@ -4956,6 +5129,7 @@ export function apply(ctx, config) {
                     if (nr) sel = await snapshotRun(nr.workspace, nr.runId);
                   }
                 }
+                mark('runs+select');
                 if (!runs.length) { json(200, { ok: false, runs, workspaces, runsAvailable: 0, error: '还没有专家团 run。先运行 /team <task> 开一个。' }); return; }
                 if (!sel) {
                   // current workspace has no team run (but other workspaces do)
@@ -4997,8 +5171,11 @@ export function apply(ctx, config) {
                 //   ① wfLabels — the workflow delegation labels in THIS session's own
                 //      log (covers interrupted fan-outs, which have no chat card); then
                 //   ② the child's own role prompt (roleFromChildLog).
+                mark('subs');
                 const wfLabels = await workflowChildLabels(ctx, peopleSid);
+                mark('wfLabels');
                 await resolveSubRoles(ctx, subs, wfLabels);
+                mark('roles');
                 // R12 + R13 + R17（F-1 · P0 跨 run 成员串号）：**显示与写盘都只吃过滤后的 `subById`**。
                 // R13 裁决：只严写盘的话，数据污染修好了但用户看到的串号现象一点没变 —— 面板照样把
                 // 别的 run 的 8 个活人显示成本 run 成员，而 membersUnresolved 当前 client.js 并不渲染，
@@ -5164,7 +5341,16 @@ export function apply(ctx, config) {
                 // 以及上面的「派工即登记」写本 run 的 `STATE.json`。它们同样值得搬到显式路径，
                 // 但那属于「第二个写者」的设计问题（见 `docs/专家团-开发计划.md` 的第 17 项）。
                 persistSessionRuns();
-                json(200, { ok: true, runs, workspaces, cwd, agents: sel.agents, ...sel });
+                mark('tail');
+                // profile 只在 DSH_EXPERT_TEAM_STATE_PROFILE=1 时出现（默认不含该字段，
+                // 线上响应体不变）；rolesDeferred = 本轮因预算被推迟的子会话日志读取条数，
+                // 让调用方能把"还没解析"与"解析不出来"分开（两种零可区分）。
+                const budget = roleReadBudgetSnapshot();
+                json(200, Object.assign(
+                  { ok: true, runs, workspaces, cwd, agents: sel.agents, rolesDeferred: budget.deferred },
+                  sel,
+                  prof ? { profile: Object.assign({}, prof.steps, { rolesBudget: budget }) } : null,
+                ));
               } catch (e) {
                 json(500, { ok: false, error: String(e && e.message ? e.message : e) });
               }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yangdcm/dsh-expert-team",
-  "version": "1.3.9",
+  "version": "1.3.10",
   "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",