@mzzsfy/dsh-bug-perf 0.0.0-stage → 0.2.0

package/src/config.mjs

@@ -0,0 +1,100 @@
+// 宿主与客户端共享的配置事实源(客户端不能 import,内联副本由测试对表)
+export const DIAG_MAX_SAMPLES = 720
+const DIAG_DEFAULT_REPORT_EVERY = 12
+
+export const DEFAULT_CONFIG = Object.freeze({
+  restartCoalesce: Object.freeze({ enabled: true, windowMs: 100 }),
+  terminalWatchdog: Object.freeze({ enabled: true, checkMs: 2000, stallMs: 8000, cooldownMs: 60000 }),
+  socketKeepAlive: Object.freeze({ enabled: true, intervalMs: 1500 }),
+  stuckSession: Object.freeze({ enabled: true, checkMs: 2000, stallMs: 8000, reconnect: true, maxReconnectAttempts: 5, reconnectIntervalMs: 15000 }),
+  jobStreamLimit: Object.freeze({ enabled: true, base: 32, max: 48 }),
+  listSlim: Object.freeze({ enabled: true }),
+  diag: Object.freeze({ enabled: false, reportEvery: DIAG_DEFAULT_REPORT_EVERY }),
+})
+
+// 阈值边界:非有限数或低于下限回退默认,高于上限收敛;diag.reportEvery 两侧都收敛
+export const LIMITS = Object.freeze({
+  restartCoalesce: Object.freeze({ windowMs: Object.freeze({ min: 0, max: 2000 }) }),
+  terminalWatchdog: Object.freeze({
+    checkMs: Object.freeze({ min: 250, max: 60000 }),
+    stallMs: Object.freeze({ min: 1000, max: 600000 }),
+    cooldownMs: Object.freeze({ min: 1000, max: 3600000 }),
+  }),
+  socketKeepAlive: Object.freeze({ intervalMs: Object.freeze({ min: 500, max: 60000 }) }),
+  stuckSession: Object.freeze({
+    checkMs: Object.freeze({ min: 250, max: 60000 }),
+    stallMs: Object.freeze({ min: 1000, max: 600000 }),
+    maxReconnectAttempts: Object.freeze({ min: 1, max: 20 }),
+    reconnectIntervalMs: Object.freeze({ min: 500, max: 600000 }),
+  }),
+  jobStreamLimit: Object.freeze({ base: Object.freeze({ min: 4, max: 256 }), max: Object.freeze({ min: 4, max: 512 }) }),
+  diag: Object.freeze({ reportEvery: Object.freeze({ min: 1, max: DIAG_MAX_SAMPLES }) }),
+})
+
+const isSection = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+const sectionOf = (value) => (isSection(value) ? value : {})
+
+const booleanOr = (value, fallback) => (typeof value === 'boolean' ? value : fallback)
+
+// 非有限数或低于下限 = 非法, 回退默认;超过上限 = 收敛
+const numberWithin = (value, bounds, fallback) => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback
+  if (value < bounds.min) return fallback
+  return value > bounds.max ? bounds.max : value
+}
+
+// 非有限数回退默认;有限数两侧都收敛到边界
+const numberClamped = (value, bounds, fallback) => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback
+  return Math.min(bounds.max, Math.max(bounds.min, value))
+}
+
+export function normalizeConfig(raw) {
+  const input = sectionOf(raw)
+  const restart = sectionOf(input.restartCoalesce)
+  const watchdog = sectionOf(input.terminalWatchdog)
+  const keepAlive = sectionOf(input.socketKeepAlive)
+  const stuck = sectionOf(input.stuckSession)
+  const jobLimit = sectionOf(input.jobStreamLimit)
+  const listSlim = sectionOf(input.listSlim)
+  const diag = sectionOf(input.diag)
+  return {
+    restartCoalesce: {
+      enabled: booleanOr(restart.enabled, DEFAULT_CONFIG.restartCoalesce.enabled),
+      windowMs: numberWithin(restart.windowMs, LIMITS.restartCoalesce.windowMs, DEFAULT_CONFIG.restartCoalesce.windowMs),
+    },
+    terminalWatchdog: {
+      enabled: booleanOr(watchdog.enabled, DEFAULT_CONFIG.terminalWatchdog.enabled),
+      checkMs: numberWithin(watchdog.checkMs, LIMITS.terminalWatchdog.checkMs, DEFAULT_CONFIG.terminalWatchdog.checkMs),
+      stallMs: numberWithin(watchdog.stallMs, LIMITS.terminalWatchdog.stallMs, DEFAULT_CONFIG.terminalWatchdog.stallMs),
+      cooldownMs: numberWithin(watchdog.cooldownMs, LIMITS.terminalWatchdog.cooldownMs, DEFAULT_CONFIG.terminalWatchdog.cooldownMs),
+    },
+    socketKeepAlive: {
+      enabled: booleanOr(keepAlive.enabled, DEFAULT_CONFIG.socketKeepAlive.enabled),
+      intervalMs: numberWithin(keepAlive.intervalMs, LIMITS.socketKeepAlive.intervalMs, DEFAULT_CONFIG.socketKeepAlive.intervalMs),
+    },
+    stuckSession: {
+      enabled: booleanOr(stuck.enabled, DEFAULT_CONFIG.stuckSession.enabled),
+      checkMs: numberWithin(stuck.checkMs, LIMITS.stuckSession.checkMs, DEFAULT_CONFIG.stuckSession.checkMs),
+      stallMs: numberWithin(stuck.stallMs, LIMITS.stuckSession.stallMs, DEFAULT_CONFIG.stuckSession.stallMs),
+      reconnect: booleanOr(stuck.reconnect, DEFAULT_CONFIG.stuckSession.reconnect),
+      maxReconnectAttempts: numberWithin(stuck.maxReconnectAttempts, LIMITS.stuckSession.maxReconnectAttempts, DEFAULT_CONFIG.stuckSession.maxReconnectAttempts),
+      reconnectIntervalMs: numberWithin(stuck.reconnectIntervalMs, LIMITS.stuckSession.reconnectIntervalMs, DEFAULT_CONFIG.stuckSession.reconnectIntervalMs),
+    },
+    jobStreamLimit: {
+      enabled: booleanOr(jobLimit.enabled, DEFAULT_CONFIG.jobStreamLimit.enabled),
+      base: Math.min(
+        numberWithin(jobLimit.base, LIMITS.jobStreamLimit.base, DEFAULT_CONFIG.jobStreamLimit.base),
+        numberWithin(jobLimit.max, LIMITS.jobStreamLimit.max, DEFAULT_CONFIG.jobStreamLimit.max),
+      ),
+      max: numberWithin(jobLimit.max, LIMITS.jobStreamLimit.max, DEFAULT_CONFIG.jobStreamLimit.max),
+    },
+    listSlim: {
+      enabled: booleanOr(listSlim.enabled, DEFAULT_CONFIG.listSlim.enabled),
+    },
+    diag: {
+      enabled: booleanOr(diag.enabled, DEFAULT_CONFIG.diag.enabled),
+      reportEvery: numberClamped(diag.reportEvery, LIMITS.diag.reportEvery, DEFAULT_CONFIG.diag.reportEvery),
+    },
+  }
+}

package/src/index.js

@@ -0,0 +1,240 @@
+// dsh-bug-perf Host 半区:把行配置归一化后经配置路由交给浏览器半区,接收设置页保存,
+// 并接收浏览器定期上报的性能采样(只落本地临时文件,用于定位“越用越卡”)。
+// 会话列表瘦身在宿主执行(包装 sessionController.list),其余补丁在客户端执行;
+// 这里不做认证,缺 webServer 或路由注册失败都不影响宿主。
+import { appendFileSync, existsSync, renameSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import z from '@deepseek-ai/schemastery'
+import { DEFAULT_CONFIG, normalizeConfig } from './config.mjs'
+import { installListSlim } from './list-slim.mjs'
+
+export const name = 'dsh-bug-perf'
+// web profile 必有 webServer; 声明依赖让 apply 在服务就绪后执行,缺服务宿主即不激活本行
+export const inject = ['webServer']
+
+const CONFIG_PATH = '/api/dsh-bug-perf/config'
+const DIAG_PATH = '/api/dsh-bug-perf/diag'
+const NAMESPACE = 'bug-perf'
+const BODY_MAX_BYTES = 64 * 1024
+const DIAG_FILE = join(tmpdir(), 'dsh-bug-perf-diag.jsonl')
+const DIAG_MAX_BYTES = 2 * 1024 * 1024
+
+const SETTINGS_SCHEMA = z.object({
+  restartCoalesce: z.object({
+    enabled: z.boolean().default(DEFAULT_CONFIG.restartCoalesce.enabled).description('合并 session/follow 重建:同一 Remote stream 在窗口内的多次重启只保留一次尾随执行'),
+    windowMs: z.number().default(DEFAULT_CONFIG.restartCoalesce.windowMs).description('合并窗口(毫秒);0 表示关闭合并,每次重启都立即执行'),
+  }).description('会话流重建合并'),
+  terminalWatchdog: z.object({
+    enabled: z.boolean().default(DEFAULT_CONFIG.terminalWatchdog.enabled).description('终端输出看门狗:视图停滞且仍持有 attach 流时自动重连'),
+    checkMs: z.number().default(DEFAULT_CONFIG.terminalWatchdog.checkMs).description('检查周期(毫秒)'),
+    stallMs: z.number().default(DEFAULT_CONFIG.terminalWatchdog.stallMs).description('判定停滞的输出静默时长(毫秒)'),
+    cooldownMs: z.number().default(DEFAULT_CONFIG.terminalWatchdog.cooldownMs).description('单个视图两次自愈的最小间隔(毫秒)'),
+  }).description('终端输出看门狗'),
+  socketKeepAlive: z.object({
+    enabled: z.boolean().default(DEFAULT_CONFIG.socketKeepAlive.enabled).description('会话流保活:空闲时向会话流连接发送无害帧,避免宿主短心跳把公网连接误判为失联'),
+    intervalMs: z.number().default(DEFAULT_CONFIG.socketKeepAlive.intervalMs).description('保活帧间隔(毫秒)'),
+  }).description('会话流保活'),
+  stuckSession: z.object({
+    enabled: z.boolean().default(DEFAULT_CONFIG.stuckSession.enabled).description('会话停滞自愈:加载卡住时主动请求宿主重建连接,多次无效才给出提示'),
+    checkMs: z.number().default(DEFAULT_CONFIG.stuckSession.checkMs).description('检查周期(毫秒)'),
+    stallMs: z.number().default(DEFAULT_CONFIG.stuckSession.stallMs).description('判定加载停滞的持续时长(毫秒)'),
+    reconnect: z.boolean().default(DEFAULT_CONFIG.stuckSession.reconnect).description('停滞时调用宿主 connection.reconnect() 主动重建连接'),
+    maxReconnectAttempts: z.number().default(DEFAULT_CONFIG.stuckSession.maxReconnectAttempts).description('连续重建连接的最大次数,用尽后才显示提示'),
+    reconnectIntervalMs: z.number().default(DEFAULT_CONFIG.stuckSession.reconnectIntervalMs).description('两次重建连接之间的最小间隔(毫秒)'),
+  }).description('会话加载停滞兜底'),
+  jobStreamLimit: z.object({
+    enabled: z.boolean().default(DEFAULT_CONFIG.jobStreamLimit.enabled).description('任务状态流上限:每个会话行各订阅一条常驻 job/list 流,会话多时会把主线程压满,这里按默认窗口加点击放行'),
+    base: z.number().default(DEFAULT_CONFIG.jobStreamLimit.base).description('默认窗口:只给主会话放行的条数,子 agent 会话不占这个窗口'),
+    max: z.number().default(DEFAULT_CONFIG.jobStreamLimit.max).description('硬上限;点击某个会话可越过默认窗口加入,总数到上限后淘汰最先加入的一条'),
+  }).description('任务状态流上限'),
+  listSlim: z.object({
+    enabled: z.boolean().default(DEFAULT_CONFIG.listSlim.enabled).description('会话列表瘦身:按白名单裁剪 session/list 的投影并缓存,降低列表响应体积与重建耗时;响应形状不符时透传,新增列表字段需同步白名单'),
+  }).description('会话列表瘦身'),
+  diag: z.object({
+    enabled: z.boolean().default(DEFAULT_CONFIG.diag.enabled).description('性能采样上报:开启后按采样次数把页面性能摘要写入宿主临时文件,供事后排查;关闭时内存采样仍运行'),
+    reportEvery: z.number().default(DEFAULT_CONFIG.diag.reportEvery).description('每多少次采样上报一次;采样周期固定,修改后刷新页面生效'),
+  }).description('性能采样上报'),
+}).description('宿主缺陷兜底与性能补丁,每个功能独立开关')
+
+// 旧宿主 schemastery 无 volatile 方法,特性检测原样返回
+export const Config = typeof SETTINGS_SCHEMA.volatile === 'function' ? SETTINGS_SCHEMA.volatile() : SETTINGS_SCHEMA
+
+// 0.1.7 宿主以整节 volatile ref 传入,旧宿主为普通对象
+const unwrapVolatile = (value) => (typeof value?.get === 'function' ? value.get() : value)
+
+const sendJson = (res, status, body) => {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  })
+  res.end(JSON.stringify(body))
+}
+
+// 设置页保存:legacy 命名空间以 register 在场为准(0.1.7 的 update 名义存在但按命名空间找条目必败);
+// 0.1.7+ 走 configEditor 落 profile 条目,与命名空间解耦
+const persistConfig = async (ctx, next) => {
+  const settings = ctx.get('settings')
+  if (settings !== undefined && typeof settings.register === 'function' && typeof settings.update === 'function') {
+    await settings.update(NAMESPACE, next)
+    return
+  }
+  const editor = ctx.get('configEditor')
+  const entry = ctx.fiber?.entry
+  if (editor !== undefined && typeof editor.edit === 'function' && entry !== undefined && entry !== null) {
+    await editor.edit(entry, (current) => ({ ...(current ?? {}), ...next }))
+    return
+  }
+  throw new Error('宿主配置服务不可用')
+}
+
+// 读回优先级:旧宿主 settings 命名空间已写入的节;否则用行配置(live ref 解箱)
+const readConfig = (ctx, config) => {
+  const settings = ctx.get('settings')
+  const stored = settings !== undefined && typeof settings.get === 'function' ? settings.get(NAMESPACE) : undefined
+  const known = stored !== null && typeof stored === 'object'
+    && ['restartCoalesce', 'terminalWatchdog', 'socketKeepAlive', 'stuckSession', 'jobStreamLimit', 'listSlim', 'diag']
+      .some((key) => stored[key] !== null && typeof stored[key] === 'object')
+  return normalizeConfig(known ? stored : unwrapVolatile(config))
+}
+
+const readBody = (req) => new Promise((resolve, reject) => {
+  let size = 0
+  const chunks = []
+  req.on('data', (chunk) => {
+    size += chunk.length
+    if (size > BODY_MAX_BYTES) {
+      reject(new Error('body too large'))
+      req.destroy()
+      return
+    }
+    chunks.push(chunk)
+  })
+  req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+  req.on('error', reject)
+})
+
+const configHandler = async (ctx, config, req, res) => {
+  if (req.method !== 'POST') {
+    if (req.method !== 'GET') {
+      sendJson(res, 405, { error: 'method-not-allowed' })
+      return
+    }
+    try {
+      sendJson(res, 200, { config: readConfig(ctx, config) })
+    } catch {
+      sendJson(res, 500, { error: 'config-unavailable' })
+    }
+    return
+  }
+  let body
+  try {
+    body = JSON.parse(await readBody(req))
+  } catch {
+    sendJson(res, 400, { error: 'bad-payload' })
+    return
+  }
+  const patch = body?.config
+  if (patch === null || typeof patch !== 'object' || Array.isArray(patch)) {
+    sendJson(res, 400, { error: 'bad-config' })
+    return
+  }
+  let next
+  try {
+    next = normalizeConfig({ ...readConfig(ctx, config), ...patch })
+  } catch {
+    sendJson(res, 500, { error: 'config-unavailable' })
+    return
+  }
+  try {
+    await persistConfig(ctx, next)
+  } catch {
+    sendJson(res, 503, { error: 'config-unavailable' })
+    return
+  }
+  sendJson(res, 200, { config: next })
+}
+
+// 采样文件只保留最近一轮, 超过上限后轮转一次, 避免无限增长
+const recordDiag = (payload) => {
+  try {
+    if (existsSync(DIAG_FILE) && statSync(DIAG_FILE).size > DIAG_MAX_BYTES) renameSync(DIAG_FILE, `${DIAG_FILE}.1`)
+    appendFileSync(DIAG_FILE, `${JSON.stringify(payload)}\n`, 'utf8')
+  } catch {
+    // 磁盘不可写时丢弃采样, 不影响页面与宿主
+  }
+}
+
+const diagHandler = (req, res) => {
+  let value
+  try {
+    value = new URL(req.url ?? '/', 'http://localhost').searchParams.get('d')
+  } catch {
+    sendJson(res, 400, { error: 'bad-request' })
+    return
+  }
+  if (value === null) {
+    sendJson(res, 400, { error: 'missing-payload' })
+    return
+  }
+  let payload
+  try {
+    payload = JSON.parse(value)
+  } catch {
+    sendJson(res, 400, { error: 'bad-payload' })
+    return
+  }
+  recordDiag(payload)
+  sendJson(res, 200, { ok: true })
+}
+
+export function apply(ctx, config) {
+  // 列表瘦身:不依赖 webServer/路由,开关从行配置实时读取;装载失败只关闭该能力
+  installListSlim(ctx, { isEnabled: () => normalizeConfig(unwrapVolatile(config)).listSlim.enabled })
+  const server = ctx.get('webServer')
+  if (server === undefined || typeof server.register !== 'function') return
+
+  // 设置页持久化双形:legacy settings 命名空间 / 0.1.7 行配置编辑器
+  const installSettings = (scope) => {
+    const settings = scope.settings ?? scope.get?.('settings')
+    if (settings === undefined) return
+    if (typeof settings.register === 'function') {
+      try {
+        settings.register(NAMESPACE, SETTINGS_SCHEMA, { base: unwrapVolatile(config) })
+      } catch (error) {
+        console.warn('[dsh-bug-perf] settings unavailable:', error instanceof Error ? error.message : String(error))
+      }
+      return
+    }
+    if (typeof settings.configure === 'function') {
+      try {
+        scope.effect(() => settings.configure({ auto: false }, ctx.fiber))
+      } catch (error) {
+        console.warn('[dsh-bug-perf] settings configure failed:', error instanceof Error ? error.message : String(error))
+      }
+    }
+  }
+  if (typeof ctx.inject === 'function') ctx.inject(['settings'], installSettings)
+
+  const routes = [
+    {
+      kind: 'exact',
+      path: CONFIG_PATH,
+      handler: (req, res) => configHandler(ctx, config, req, res),
+    },
+    {
+      kind: 'exact',
+      path: DIAG_PATH,
+      handler: diagHandler,
+    },
+  ]
+  try {
+    ctx.effect(() => {
+      const disposers = routes.map((route) => server.register(route))
+      return () => { for (const dispose of disposers) if (typeof dispose === 'function') dispose() }
+    }, 'bug-perf routes')
+  } catch (error) {
+    // 路由表冻结/换代竞态:补丁配置退回客户端默认值,不影响宿主
+    console.warn('[dsh-bug-perf] routes unavailable:', error instanceof Error ? error.message : String(error))
+  }
+}

package/src/list-slim.mjs

@@ -0,0 +1,207 @@
+// 会话列表瘦身:session/list 为每个会话下发完整投影快照,列表行只消费其中少数几项。
+// 本模块在 remote 方法返回前按白名单裁剪并缓存结果。任何失败路径都降级为原行为:
+// 未装载、形状不符、原方法抛错一律透传,不影响本插件的其它补丁。
+// sessionController 经 ctx.inject 可选依赖取得,宿主缺该服务时静默等待。
+// 缓存只服务 owner/本地调用:非 owner Remote 主体直接透传原方法,避免跨主体命中共享缓存。
+
+// 列表行消费的投影;其余键不下发。被裁掉的投影仍由会话详情接口完整返回。
+export const KEEP_PROJECTIONS = ['title', 'sessionListMetadata', 'inbox', 'modelSelection', 'tokenUsage']
+
+// 缓存有效期:会话增删立即失效,TTL 只兜底标题与运行时状态的漂移。
+export const TTL_MS = 15 * 1000
+
+// 启动后预热延迟:让宿主先完成装载,再让出一次列表重建。
+export const WARMUP_DELAY_MS = 10 * 1000
+
+// 预热等待上限:宿主列表长期不返回时不无限占用共享构建。
+export const WARMUP_TIMEOUT_MS = 2 * 60 * 1000
+
+const LOG_PREFIX = '[dsh-bug-perf] 列表瘦身'
+const INSTALL_MARKER = Symbol.for('@mzzsfy/dsh-bug-perf/list-slim')
+const WRAPPED_MARKER = Symbol.for('@mzzsfy/dsh-bug-perf/list-slim/wrapped')
+
+/**
+ * 当前 receiver 是否来自非 owner Remote 主体。
+ * 与宿主 remoteAccess.allows 的判定同源:owner 或非 Remote 调用没有 principal。
+ * @param receiver - 列表方法调用时的 this。
+ * @returns 非 owner 主体返回 true。
+ */
+function isNonOwner(receiver) {
+  const principal = receiver?.ctx?.invocation?.peer?.principal
+  return principal !== undefined && principal.kind !== 'owner'
+}
+
+/**
+ * 让一个调用者按自己的 signal 等待共享构建,取消只影响本次等待。
+ * @param promise - 共享的列表构建。
+ * @param signal - 调用者的取消信号。
+ * @returns 本调用者的等待结果。
+ */
+function raceWithSignal(promise, signal) {
+  if (signal === undefined) return promise
+  if (signal.aborted) return Promise.reject(signal.reason ?? new Error('aborted'))
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(signal.reason ?? new Error('aborted'))
+    signal.addEventListener('abort', onAbort, { once: true })
+    promise.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort)
+        resolve(value)
+      },
+      (error) => {
+        signal.removeEventListener('abort', onAbort)
+        reject(error)
+      },
+    )
+  })
+}
+
+/**
+ * 裁剪一条列表项的投影,只保留白名单里的键。
+ * @param item - 宿主返回的列表项。
+ * @param keep - 保留的投影键。
+ * @returns 投影已裁剪的列表项;形状不符时原样返回。
+ */
+export function slimItem(item, keep = KEEP_PROJECTIONS) {
+  const values = item?.projections?.values
+  if (values === null || typeof values !== 'object' || Array.isArray(values)) return item
+  const picked = {}
+  for (const key of keep) if (key in values) picked[key] = values[key]
+  return { ...item, projections: { ...item.projections, values: picked } }
+}
+
+/**
+ * 给 sessionController.list 装上裁剪与缓存。
+ * @param ctx - 宿主上下文。
+ * @param options - 开关、白名单、缓存有效期与预热延迟。
+ * @returns 是否提交了装载回调;sessionController 缺席时回调不执行,宿主行为不变。
+ */
+export function installListSlim(ctx, options = {}) {
+  const {
+    isEnabled,
+    keep = KEEP_PROJECTIONS,
+    ttlMs = TTL_MS,
+    warmupDelayMs = WARMUP_DELAY_MS,
+  } = options
+  const warn = (message) => ctx.logger?.warn?.(LOG_PREFIX + ' ' + message)
+  try {
+    ctx.inject(['sessionController'], (scope) => {
+      try {
+        const controller = scope.sessionController
+        const original = controller?.list
+        if (typeof original !== 'function') {
+          warn('sessionController.list 不可用,跳过')
+          return
+        }
+        if (controller[INSTALL_MARKER] !== undefined && controller.list?.[WRAPPED_MARKER] === true) return
+        let cache
+        let cachedAt = 0
+        let inflight
+        let generation = 0
+        let active = true
+
+        const fresh = () => cache !== undefined && Date.now() - cachedAt < ttlMs
+        const invalidate = () => {
+          generation += 1
+          cachedAt = 0
+        }
+        scope.on('api-session/added', invalidate)
+        scope.on('api-session/removed', invalidate)
+
+        // 每个调用者独立等待共享构建;所有等待者都取消时中止构建,避免挂起被后续调用复用
+        const awaitBuild = (entry, signal) => {
+          const waiter = {}
+          entry.waiters.add(waiter)
+          const result = raceWithSignal(entry.promise, signal)
+          const settle = () => {
+            entry.waiters.delete(waiter)
+            if (entry.waiters.size === 0 && inflight === entry) {
+              entry.controller.abort()
+              inflight = undefined
+            }
+          }
+          result.then(settle, settle)
+          return result
+        }
+
+        // 缓存跨调用共享,按 TTL 与会话增删事件失效;非 owner 不读写缓存。
+        // 普通函数保留调用方 receiver:宿主在 list 内按 invocation 做逐项鉴权。
+        const wrapped = function list(request, signal) {
+          const receiver = this
+          // 卸载、关闭、已取消或非 owner:不裁剪、不缓存,原样交给宿主
+          if (!active || signal?.aborted || (isEnabled !== undefined && !isEnabled()) || isNonOwner(receiver)) {
+            return original.call(receiver, request, signal)
+          }
+          if (fresh()) return cache
+          // 共享构建不绑定任何调用者的 signal;调用者取消只结束自己的等待
+          if (inflight !== undefined && inflight.generation === generation) return awaitBuild(inflight, signal)
+          const current = generation
+          const buildController = new AbortController()
+          const entry = { promise: undefined, generation: current, controller: buildController, waiters: new Set() }
+          const created = Promise.resolve(original.call(receiver, request, buildController.signal))
+            .then((value) => {
+              if (!Array.isArray(value?.items)) return value
+              const slimmed = { items: value.items.map((item) => slimItem(item, keep)) }
+              // 在途期间发生增删失效时只返回本次结果,不把旧快照写回缓存
+              if (generation === current && inflight === entry) {
+                cache = slimmed
+                cachedAt = Date.now()
+              }
+              return slimmed
+            })
+            .finally(() => {
+              if (inflight === entry) inflight = undefined
+            })
+          entry.promise = created
+          inflight = entry
+          return awaitBuild(entry, signal)
+        }
+        Object.defineProperty(controller, INSTALL_MARKER, { value: wrapped, configurable: true })
+        Object.defineProperty(wrapped, WRAPPED_MARKER, { value: true })
+        try {
+          controller.list = wrapped
+        } catch (error) {
+          if (controller[INSTALL_MARKER] === wrapped) delete controller[INSTALL_MARKER]
+          throw error
+        }
+        let timer
+        if (warmupDelayMs >= 0) {
+          timer = setTimeout(() => {
+            if (isEnabled !== undefined && !isEnabled()) return
+            if (fresh() || inflight !== undefined) return
+            const timeout = AbortSignal.timeout?.(WARMUP_TIMEOUT_MS)
+            void wrapped.call(controller, {}, timeout).catch(() => {})
+          }, warmupDelayMs)
+          timer.unref?.()
+        }
+
+        // 卸载恢复原方法:按包装标记与归属判断,不摘掉后装或其它实例的包装;
+        // 已被后装引用时由 active 失活,链上继续透传;在途构建一并中止
+        const dispose = () => {
+          active = false
+          if (timer !== undefined) clearTimeout(timer)
+          if (inflight !== undefined) {
+            inflight.controller.abort()
+            inflight = undefined
+          }
+          if (controller[INSTALL_MARKER] === wrapped && controller.list?.[WRAPPED_MARKER] === true) controller.list = original
+          if (controller[INSTALL_MARKER] === wrapped) delete controller[INSTALL_MARKER]
+        }
+        try {
+          scope.effect(() => dispose)
+        } catch (error) {
+          // effect 注册失败时回滚包装与标记,避免留下无法卸载的包装
+          dispose()
+          throw error
+        }
+        ctx.logger?.info?.(`${LOG_PREFIX} 已装载 (keep=${keep.join(',')} ttl=${ttlMs}ms)`)
+      } catch (error) {
+        warn('装载失败,保持原行为: ' + String(error?.message ?? error))
+      }
+    })
+    return true
+  } catch (error) {
+    warn('未启用: ' + String(error?.message ?? error))
+    return false
+  }
+}