fix(subagent): 子代理页实时预览改为批量接口，避免 O(N²) history 请求风暴 (#298)

* fix(subagent): 子代理页实时预览改为批量接口，避免 O(N²) history 请求风暴 ## 背景 DSH Web UI 中，当主代理同时运行多个子代理时，`dsh-better-sidebar` 的「任务管理/子代理」页面会出现明显卡顿。经调查，卡顿根因不在页面渲染，而在实时预览的请求模式。 ## 根因旧实现中，每个 running 子代理卡片都独立轮询 `subagents.history`： - N 个 running 子代理 → 每 3 秒产生 N 次 `subagents.history` 请求； - 每次 `subagents.history` 都会在 host 侧触发一次完整的 `listChildren` 全量子代理目录枚举； - 子代理数量越多，服务端重复扫描越严重，近似 O(N²) 放大； - 请求超过 3 秒时，客户端还会 abort 旧请求并重发，进一步形成请求风暴。 ## 改动内容 1. **新增 host 批量接口 `POST /sidebar/api/subagents.live`** - 请求 `{ rootSessionId }`； - 通过 `ctx.subagents.listDescendants(rootSessionId)` 一次枚举整棵子代理树； - 仅对 running 且非 Side Chat 的子代理，从 session events 尾部提取最新 `text/tool` 活动； - 返回 `{ live: Record<childId, { text?, tool? }> }`； - 缺 `subagents`/`agents` 服务或枚举失败时返回 503；单个子代理日志异常只跳过该子代理。 2. **客户端改为单轮询 + 单飞行请求** - 删除每个 running 子代理独立的 `subagents.history` 定时器； - 在 `SubagentView` 中合并为一个 `useSubagentLive` 轮询 hook； - 使用递归 `setTimeout` 和单在途请求，慢请求不再被 abort/重发； - 页面隐藏或 root 变化时停止轮询并中止在途请求。 3. **解析器优化** - `lastActivity` 改为接收原始 `SidebarSessionEvent[]`； - 从事件尾部向前扫描，找到最新 text 和 tool 后提前停止，避免复制/遍历完整历史。 4. **UI 保持不变** - 实时预览的展示逻辑、文案、截断规则均未改变。 ## 测试 - 新增 `tests/subagent-live-route.spec.ts`：覆盖批量接口成功聚合、只返回 running、跳过 Side Chat、缺服务 503、枚举失败 503、`ctx.get` 回退、bad-request。 - 新增 `tests/subagent-live-polling.spec.tsx`：覆盖每轮只发 1 次 `subagents.live`、不再调用 `subagents.history`、单在途不并发。 - 更新 `tests/subagent-activity.spec.ts` 与 `tests/subagent-jobs-view.spec.tsx`。 - `pnpm typecheck` ✅ - `pnpm build` ✅ - 相关测试 29 个全部通过 ✅ > 本机完整 `pnpm test` 仍有与本改动无关的环境性失败（node-pty 超时、Windows CRLF 断言、pty-deps 路径断言），不影响本 PR 逻辑。 * fix(subagent): live 预览以 catalog activity 为准，删除 agents 第二事实源 (#298) - host 路由 running 门改回 entry.activity === 'running'（与客户端卡片渲染门一致），恢复 PR 承诺的 UI 不变：turn 间 idle 的 continuable 子代理仍显示最后活动 - 删除 ctx.agents 依赖与 SidebarAgent.status 新增（agents 缺失时不再静默 200 空 map； 503 契约收窄为只涉及 subagents，与文档/测试一致） - service 解析统一为 ctx.get('subagents')（兄弟路由惯例；插件未 inject subagents，直接属性访问有抛错风险） - buildSubagentLiveApi 签名改收完整 Context，删除 SidebarSubagentLiveContext 窄接口 - api.ts 复用 LastActivity，删除重复类型 SubagentLiveEntry - 测试：route spec 删除 agents 相关用例；polling spec 新增页面隐藏停止轮询、 root 变化清空 live 并重启轮询两个用例 * fix(subagent): live 预览恢复最近 12 条消息窗口，排除陈旧活动 (#298) CR 反馈：新批量接口把完整 session event log 喂给 lastActivity， - 长时间只输出文本、早期调用过工具的 running 子代理会持续显示陈旧 tool - 无 tool 的长会话每次轮询反向扫描整个事件数组，重新引入与历史长度相关的 CPU 成本修复（与旧 subagents.history({ maxMessages: 12 }) 窗口语义一致）： - lastActivity 增加可选 maxMessages 参数：反向扫描按表面消息（user/message + assistant/message）计数，窗口满后更老事件一律跳过 - 路由传 LIVE_WINDOW_MESSAGES = 12（导出常量） - 回归测试：窗口外旧 tool 不返回；窗口内 tool 保留；非消息事件不消耗配额 --------- Co-authored-by: Menghuan1918 <menghuan2003@outlook.com>
2026-08-21 18:15:49 +08:00
parent a9d3451415
commit 6cea4bdd6f
12 changed files with 815 additions and 143 deletions
@@ -41,7 +41,7 @@ import {
  isSideThreadSummary,
  rootAncestor,
 } from './subagent-detect.ts'
-import { lastActivity } from './subagent-activity.ts'
+import { type LastActivity } from '../subagent-activity.ts'
 import { SIDE_LABEL_PREFIX } from '../sidechat-core.ts'
 import {
  collectTreeJobs,
@@ -150,56 +150,14 @@ function CatalogLoadingRows(props: {
 }

 /**
- * The live lines of one RUNNING subagent card: the last text output and the
- * last tool call of the child's history tail, refreshed every few seconds
- * while the page is visible. Idle cards render nothing (a quiet topology); a
- * running child with neither output yet reads "thinking…".
+ * The live lines of one RUNNING subagent card: a pure presentation of the
+ * batch `subagents.live` activity. The polling lives in one place (the
+ * SubagentView hook), not per card. A running child with neither output yet
+ * reads "thinking…".
 */
-function SubagentLiveLines(props: {
-  ctx: Context
-  parentSessionId: string
-  childSessionId: string
-  mode: SidebarSubagentAddress['mode']
-  running: boolean
-  /** The page is visible (active tab + open panel): skip polling otherwise. */
-  active: boolean
-}) {
-  const { ctx, parentSessionId, childSessionId, mode, running, active } = props
-  const [live, setLive] = useState<ReturnType<typeof lastActivity>>({})
-  const controllerRef = useRef<AbortController | undefined>(undefined)
-  const address = useMemo(
-    () => ({ parentSessionId, childSessionId, mode }),
-    [parentSessionId, childSessionId, mode],
-  )
-
-  const load = useCallback(async (): Promise<void> => {
-    controllerRef.current?.abort()
-    const controller = new AbortController()
-    controllerRef.current = controller
-    try {
-      const response = await ctx.connection.api.subagents.history(
-        { ...address, maxMessages: 12 },
-        controller.signal,
-      )
-      if (!response.result.ok) return
-      setLive(lastActivity(response.result.value.events))
-    } catch {
-      // Aborted by a newer pull or a wire failure: keep the last known lines.
-    }
-  }, [ctx, address])
-
-  useEffect(() => {
-    if (!active) return
-    void load()
-    if (!running) return
-    const timer = window.setInterval(() => { void load() }, POLL_MS)
-    return () => { window.clearInterval(timer) }
-  }, [load, running, active])
-
-  useEffect(() => () => { controllerRef.current?.abort() }, [])
-
-  if (!running) return null
-  if (live.text === undefined && live.tool === undefined) {
+function SubagentLiveLines(props: { live: LastActivity | undefined }) {
+  const { live } = props
+  if (live?.text === undefined && live?.tool === undefined) {
    return <span className={css.subagentLive}>{t('subagentThinking')}</span>
  }
  return (
@@ -219,6 +177,59 @@ function SubagentLiveLines(props: {
  )
 }

+/**
+ * One shared live-preview poller for the whole Subagent tree. Unlike the old
+ * per-card `subagents.history` timers, this sends at most ONE `subagents.live`
+ * request at a time: a recursive timeout starts only after the previous
+ * request settles, so a slow host never sees abort/restart storms.
+ */
+function useSubagentLive(
+  rootId: string | undefined,
+  active: boolean,
+): Readonly<Record<string, LastActivity>> {
+  const [live, setLive] = useState<Record<string, LastActivity>>({})
+  const controllerRef = useRef<AbortController | undefined>(undefined)
+
+  // A new tree must never inherit another root's live previews.
+  useEffect(() => { setLive({}) }, [rootId])
+
+  useEffect(() => {
+    if (rootId === undefined || !active) return
+    const targetRootId = rootId
+    let disposed = false
+    let timer: number | undefined
+
+    const schedule = (): void => {
+      if (disposed) return
+      timer = window.setTimeout(() => { void load() }, POLL_MS)
+    }
+    async function load(): Promise<void> {
+      if (disposed) return
+      const controller = new AbortController()
+      controllerRef.current = controller
+      try {
+        const result = await api.subagentsLive(targetRootId, controller.signal)
+        if (!disposed) setLive(result.live)
+      } catch {
+        // Keep the last known live map; the next scheduled poll retries.
+      } finally {
+        if (controllerRef.current === controller) controllerRef.current = undefined
+        if (!disposed) schedule()
+      }
+    }
+
+    void load()
+    return () => {
+      disposed = true
+      if (timer !== undefined) window.clearTimeout(timer)
+      controllerRef.current?.abort()
+      controllerRef.current = undefined
+    }
+  }, [rootId, active])
+
+  return live
+}
+
 interface RowsProps {
  parentSessionId: string
  catalog: SidebarSubagentCatalog | undefined
@@ -227,16 +238,15 @@ interface RowsProps {
  level: number
  /** The currently-open session id (highlighted in the topology). */
  currentSessionId: string
-  /** The page is visible (active tab + open panel): live polling pauses otherwise. */
-  active: boolean
-  ctx: Context
+  /** The batch live-preview map (child id → latest activity). */
+  live: Readonly<Record<string, LastActivity>>
  openChild: (address: SidebarSubagentAddress) => void
  refresh: (parentSessionId: string) => void
 }

 /** Render one topology level; branches are always expanded (lazy catalogs). */
 function CatalogRows({
-  parentSessionId, catalog, catalogs, byId, level, currentSessionId, active, ctx,
+  parentSessionId, catalog, catalogs, byId, level, currentSessionId, live,
  openChild, refresh,
 }: RowsProps) {
  const emptyLoading = catalog?.state === 'loading' && catalog.entries.length === 0
@@ -327,14 +337,9 @@ function CatalogRows({
              <span className={css.subagentContent}>
                <span className={css.subagentLabel}>{label}</span>
                <span className={css.subagentSecondary}>{secondary}</span>
-                <SubagentLiveLines
-                  ctx={ctx}
-                  parentSessionId={parentSessionId}
-                  childSessionId={entry.id}
-                  mode={entry.mode}
-                  running={entry.activity === 'running'}
-                  active={active}
-                />
+                {entry.activity === 'running' && (
+                  <SubagentLiveLines live={live[entry.id]} />
+                )}
              </span>
            </div>
            {!knownLeaf && (
@@ -355,8 +360,7 @@ function CatalogRows({
                      byId={byId}
                      level={level + 1}
                      currentSessionId={currentSessionId}
-                      active={active}
-                      ctx={ctx}
+                      live={live}
                      openChild={openChild}
                      refresh={refresh}
                    />
@@ -658,6 +662,7 @@ export function SubagentView(props: {
  const rootId = useMemo(() => rootAncestor(byId, sessionId), [byId, sessionId])
  const rootCatalog = rootId === undefined ? undefined : catalogs[rootId]
  const rootSummary = rootId === undefined ? undefined : byId[rootId]
+  const live = useSubagentLive(rootId, active)

  /** Catalog owners currently consuming live membership updates. */
  const observedRef = useRef(new Set<string>())
@@ -852,8 +857,7 @@ export function SubagentView(props: {
                  byId={byId}
                  level={1}
                  currentSessionId={sessionId}
-                  active={active}
-                  ctx={ctx}
+                  live={live}
                  openChild={openChild}
                  refresh={refresh}
                />
@@ -7,6 +7,7 @@
 * request). Failures surface as {@link SidebarApiError} with the wire code.
 */
 import { encodeHtmlUrl } from '../html-route.ts'
+import type { LastActivity } from '../subagent-activity.ts'
 import type { SidechatThreadInfo } from '../sidechat-core.ts'
 import type { BrowserProbeResult } from './browser.ts'

@@ -80,6 +81,9 @@ export interface JobOutputResult {
  read: boolean
 }

+/** The `subagents.live` response: running child id → latest activity. */
+export type SubagentLiveResult = { live: Record<string, LastActivity> }
+
 /** Terminal dependency status (mirror of the host's depsStatus; issue #140). */
 export type TerminalDepsStatus =
  | { ok: true }
@@ -245,6 +249,13 @@ export const api = {
      id,
      ...(reason !== undefined ? { reason } : {}),
    })),
+  /**
+   * One batch live-preview fetch for the whole Subagent tree. The payload is
+   * the already-resolved topology ROOT (not a session scope); the host
+   * enumerates descendants once and folds running children's activity.
+   */
+  subagentsLive: (rootSessionId: string, signal?: AbortSignal) =>
+    call<SubagentLiveResult>('subagents.live', { rootSessionId }, signal),
  /** Create a Side Chat thread: a child session seeded with the parent's
   *  full log up to now. Empty question = immediate create (Codex-style):
   *  the thread opens empty, the first prompt carries the boundary. */
@@ -1,67 +0,0 @@
-/**
- * Pure derivation of the compact LIVE line shown on a running subagent card:
- * the last text output and the last tool call of the child's history tail
- * (`subagent.history` events, oldest → newest). Renders nothing itself — the
- * SubagentLiveLine component turns this into the card's status lines.
- * Kept framework-free so the parser is unit-testable in the node environment.
- */
-import type { SidebarHistoryEntry } from '../context-types.ts'
-
-/**
- * Extract the concatenated plain text of a content-block list (the durable
- * `ContentBlock[]` shape, structurally: blocks with `type: 'text'` carry
- * `text`; anything else — tool_use, image, … — contributes nothing).
- * @param content - the raw `content` field of a message event.
- * @returns the joined text, or undefined when the message carries no text.
- */
-export function contentText(content: unknown): string | undefined {
-  if (!Array.isArray(content)) return undefined
-  const parts: string[] = []
-  for (const block of content) {
-    if (block === null || typeof block !== 'object') continue
-    const candidate = block as { type?: unknown; text?: unknown }
-    if (candidate.type === 'text' && typeof candidate.text === 'string') {
-      parts.push(candidate.text)
-    }
-  }
-  return parts.length > 0 ? parts.join('\n') : undefined
-}
-
-/** The live status of one subagent card (both fields optional). */
-export interface LastActivity {
-  /** The latest assembled assistant text output in the tail. */
-  text?: string
-  /** The latest tool call in the tail. */
-  tool?: { name: string; args: string }
-}
-
-/**
- * Fold a history tail into the last text output + last tool call (each is
- * the LAST occurrence in event order). Lifecycle events and raw
- * `assistant/chunk` rows are ignored — the card shows what the subagent is
- * doing right now, not its plumbing.
- * @param entries - the tail page from `subagent.history` (oldest → newest).
- * @returns the last text and/or tool call; an empty object when the tail has neither.
- */
-export function lastActivity(entries: SidebarHistoryEntry[]): LastActivity {
-  let text: string | undefined
-  let tool: { name: string; args: string } | undefined
-  for (const entry of entries) {
-    const { type, data } = entry.event
-    if (type === 'assistant/message') {
-      const message = data.message as { content?: unknown } | undefined
-      const extracted = contentText(message?.content)
-      if (extracted !== undefined) text = extracted
-    } else if (type === 'tool/call') {
-      tool = {
-        name: typeof data.name === 'string' ? data.name : 'tool',
-        args: typeof data.arguments === 'string' ? data.arguments : '',
-      }
-    }
-  }
-  if (text === undefined && tool === undefined) return {}
-  return {
-    ...(text === undefined ? {} : { text }),
-    ...(tool === undefined ? {} : { tool }),
-  }
-}