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

package/src/config.mjs

@@ -0,0 +1,79 @@
+// 宿主与客户端共享的配置事实源(客户端不能 import,内联副本由测试对表)
+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 }),
+})
+
+// 阈值边界:低于下限视为非法配置回退默认,高于上限收敛(防止错误配置放大补丁行为)
+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 }) }),
+})
+
+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
+}
+
+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)
+  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),
+    },
+  }
+}

package/src/index.js

@@ -0,0 +1,126 @@
+// dsh-bug-perf Host 半区:把行配置归一化后经只读路由交给浏览器半区,
+// 并接收浏览器定期上报的性能采样(只落本地临时文件,用于定位“越用越卡”)。
+// 补丁本身全部在客户端执行;这里不做认证,缺 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'
+
+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 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('任务状态流上限'),
+}).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))
+}
+
+// 采样文件只保留最近一轮, 超过上限后轮转一次, 避免无限增长
+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) {
+  const server = ctx.get('webServer')
+  if (server === undefined || typeof server.register !== 'function') return
+  const routes = [
+    {
+      kind: 'exact',
+      path: CONFIG_PATH,
+      handler: (_req, res) => {
+        try {
+          sendJson(res, 200, { config: normalizeConfig(unwrapVolatile(config)) })
+        } catch {
+          sendJson(res, 500, { error: 'config-unavailable' })
+        }
+      },
+    },
+    {
+      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/test/client-jobs.test.mjs

@@ -0,0 +1,220 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+const source = readFileSync(new URL('../src/client.js', import.meta.url), 'utf8')
+
+function loadPlugin() {
+  let registered
+  const window = { __ModuleLoader__: { load: (entry) => { registered = entry } } }
+  new Function('window', source)(window)
+  return registered.factory(() => { throw new Error('no modules') })
+}
+
+function fakeJobs() {
+  const watched = []
+  const released = []
+  return {
+    watched,
+    released,
+    watchRows(sessionId) {
+      watched.push(sessionId)
+      return () => released.push(sessionId)
+    },
+  }
+}
+
+function fakeDoc() {
+  const listeners = new Map()
+  return {
+    addEventListener(type, listener) { listeners.set(type, listener) },
+    removeEventListener(type) { listeners.delete(type) },
+    clickOn(sessionId) {
+      const target = { closest: (selector) => (selector === '[data-row-key]' ? { getAttribute: () => `session:${sessionId}` } : null) }
+      listeners.get('click')?.({ target })
+    },
+    clickOnBlank() {
+      listeners.get('click')?.({ target: { closest: () => null } })
+    },
+  }
+}
+
+const fakeSessions = (summaries) => {
+  const snapshot = { byId: Object.fromEntries(summaries.map((item) => [item.sessionId, item])) }
+  return { list: { getSnapshot: () => snapshot } }
+}
+
+// s1..s9 是主会话, c1..c3 是 s1 的子 agent 会话
+const SESSIONS = fakeSessions([
+  { sessionId: 's1' },
+  { sessionId: 'c1', origin: 'subagent', parentSessionId: 's1' },
+  { sessionId: 'c2', origin: 'subagent', parentSessionId: 's1' },
+  { sessionId: 'c3', origin: 'subagent', parentSessionId: 's1' },
+  { sessionId: 's2' },
+  { sessionId: 's3' },
+  { sessionId: 's4' },
+  { sessionId: 's5' },
+  { sessionId: 's6' },
+])
+
+const install = ({ jobs = fakeJobs(), sessions = SESSIONS, doc = fakeDoc(), options = {} } = {}) => {
+  const plugin = loadPlugin()
+  const result = plugin.__test.installJobStreamLimit({
+    jobs,
+    sessionsOf: () => sessions,
+    doc,
+    options: { enabled: true, base: 3, max: 5, ...options },
+  })
+  return { plugin, jobs, doc, result }
+}
+
+// Given 主会话数量未到默认窗口, When 列表逐行订阅, Then 都建立流
+test('任务流_主会话_窗口内放行', () => {
+  const { jobs, result } = install()
+  for (const id of ['s1', 's2', 's3']) jobs.watchRows(id)
+  assert.deepEqual(jobs.watched, ['s1', 's2', 's3'])
+  assert.equal(result.state.main, 3)
+  assert.equal(result.state.rejected, 0)
+})
+
+// Given 默认窗口已满, When 第 4 个主会话订阅, Then 拒绝且不建流
+test('任务流_主会话_超出窗口拒绝', () => {
+  const { jobs, result } = install()
+  for (const id of ['s1', 's2', 's3', 's4']) jobs.watchRows(id)
+  assert.deepEqual(jobs.watched, ['s1', 's2', 's3'])
+  assert.equal(result.state.rejected, 1)
+})
+
+// Given 默认窗口还有空位, When 子 agent 会话自动订阅, Then 不占用窗口
+test('任务流_子会话_不占窗口', () => {
+  const { jobs, result } = install()
+  jobs.watchRows('c1')
+  jobs.watchRows('s1')
+  jobs.watchRows('s2')
+  jobs.watchRows('s3')
+  assert.deepEqual(jobs.watched, ['s1', 's2', 's3'])
+  assert.equal(result.state.subagent, 0)
+  assert.equal(result.state.rejected, 1)
+})
+
+// Given 点击子 agent 会话, When 窗口已满, Then 仍然为它建立流
+test('任务流_点击子会话_放行', () => {
+  const { jobs, doc, result } = install()
+  for (const id of ['s1', 's2', 's3']) jobs.watchRows(id)
+  doc.clickOn('c1')
+  assert.ok(jobs.watched.includes('c1'))
+  assert.equal(result.state.subagent, 1)
+  assert.equal(result.state.clicked, 1)
+})
+
+// Given 点击的主会话不在窗口内, When 点击, Then 同样放行
+test('任务流_点击主会话_放行', () => {
+  const { jobs, doc } = install()
+  for (const id of ['s1', 's2', 's3']) jobs.watchRows(id)
+  doc.clickOn('s6')
+  assert.ok(jobs.watched.includes('s6'))
+})
+
+// Given 总数已到上限, When 再点击一个会话, Then 淘汰最老的一条, 总数不变
+test('任务流_达到上限_淘汰最老', () => {
+  const { jobs, doc, result } = install()
+  for (const id of ['s1', 's2', 's3']) jobs.watchRows(id)
+  doc.clickOn('c1')
+  doc.clickOn('c2')
+  assert.equal(result.state.main + result.state.subagent, 5)
+  const watchedBefore = jobs.watched.length
+  doc.clickOn('c3')
+  assert.equal(jobs.watched.length, watchedBefore + 1)
+  assert.deepEqual(jobs.released, ['s1'])
+  assert.equal(result.state.evicted, 1)
+  assert.equal(result.state.main + result.state.subagent, 5)
+})
+
+// Given 点击的行已经在窗口内, When 点击, Then 不重复建流, 只标记
+test('任务流_点击已在窗口_不重复建流', () => {
+  const { jobs, doc, result } = install()
+  jobs.watchRows('s1')
+  const before = jobs.watched.length
+  doc.clickOn('s1')
+  assert.equal(jobs.watched.length, before)
+  assert.equal(result.state.clicked, 0)
+})
+
+// Given 点击了非会话行, When 触发点击, Then 忽略
+test('任务流_点击非会话行_忽略', () => {
+  const { jobs, doc } = install()
+  doc.clickOnBlank()
+  assert.deepEqual(jobs.watched, [])
+})
+
+// Given 行组件卸载, When 调用释放, Then 额度回收, 新的主会话可以进入窗口
+test('任务流_释放后_额度回收', () => {
+  const { jobs, result } = install()
+  const release = jobs.watchRows('s1')
+  jobs.watchRows('s2')
+  jobs.watchRows('s3')
+  jobs.watchRows('s4')
+  assert.equal(result.state.rejected, 1)
+  release()
+  jobs.watchRows('s4')
+  assert.deepEqual(jobs.watched, ['s1', 's2', 's3', 's4'])
+  assert.equal(result.state.main, 3)
+})
+
+// Given 同一行重复释放, When 调用两次, Then 只扣一次
+test('任务流_重复释放_只扣一次', () => {
+  const { jobs, result } = install()
+  const release = jobs.watchRows('s1')
+  release()
+  release()
+  assert.equal(result.state.main, 0)
+  assert.deepEqual(jobs.released, ['s1'])
+})
+
+// Given 包装已安装, When 再次安装, Then 幂等
+test('任务流_重复安装_幂等', () => {
+  const { jobs, plugin } = install()
+  const second = plugin.__test.installJobStreamLimit({ jobs, sessionsOf: () => SESSIONS, doc: fakeDoc(), options: { enabled: true, base: 3, max: 5 } })
+  assert.equal(second.installed, false)
+  assert.equal(second.reason, 'already installed')
+})
+
+// Given 宿主没有 jobs 服务, When 安装, Then 跳过并记录原因
+test('任务流_服务缺失_跳过', () => {
+  const plugin = loadPlugin()
+  const result = plugin.__test.installJobStreamLimit({ jobs: undefined, sessionsOf: () => SESSIONS, doc: fakeDoc(), options: { enabled: true, base: 3, max: 5 } })
+  assert.equal(result.installed, false)
+  assert.equal(result.reason, 'jobs unavailable')
+})
+
+// Given 会话摘要尚未就绪, When 订阅, Then 按主会话处理, 不误判为子会话
+test('任务流_摘要缺失_按主会话处理', () => {
+  const { jobs, result } = install({ sessions: null })
+  jobs.watchRows('s1')
+  jobs.watchRows('s2')
+  jobs.watchRows('c1')
+  jobs.watchRows('s4')
+  assert.deepEqual(jobs.watched, ['s1', 's2', 'c1'])
+  assert.equal(result.state.rejected, 1)
+})
+
+// Given 子会话已被点击放行, When 该会话从摘要里变为普通会话, Then 不重复建流
+test('任务流_重复订阅同一会话_只建一次', () => {
+  const { jobs, doc } = install()
+  doc.clickOn('c1')
+  jobs.watchRows('c1')
+  jobs.watchRows('c1')
+  assert.deepEqual(jobs.watched, ['c1'])
+})
+
+// Given 补丁卸载, When 调用 dispose, Then 所有流被释放且点击监听移除
+test('任务流_卸载_释放全部流', () => {
+  const { jobs, doc, result } = install()
+  jobs.watchRows('s1')
+  jobs.watchRows('s2')
+  doc.clickOn('c1')
+  result.dispose()
+  assert.deepEqual(jobs.released.sort(), ['c1', 's1', 's2'])
+  doc.clickOn('s5')
+  assert.equal(jobs.watched.length, 3)
+})

package/test/client-keepalive.test.mjs

@@ -0,0 +1,227 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+const source = readFileSync(new URL('../src/client.js', import.meta.url), 'utf8')
+
+function loadPlugin() {
+  let registered
+  const window = { __ModuleLoader__: { load: (entry) => { registered = entry } } }
+  new Function('window', source)(window)
+  return registered.factory(() => { throw new Error('no modules') })
+}
+
+function fakeClock() {
+  let now = 0
+  let nextId = 0
+  const intervals = new Map()
+  const fireDue = () => {
+    for (const [id, timer] of [...intervals]) {
+      if (timer.at <= now) {
+        timer.at = now + timer.every
+        timer.fn()
+      }
+    }
+  }
+  return {
+    now: () => now,
+    setInterval: (fn, ms) => { const id = ++nextId; intervals.set(id, { fn, every: ms, at: now + ms }); return id },
+    clearInterval: (id) => { intervals.delete(id) },
+    advance(ms) {
+      const target = now + ms
+      while (true) {
+        const due = [...intervals.values()].map((timer) => timer.at).filter((at) => at <= target)
+        if (due.length === 0) break
+        now = Math.min(...due)
+        fireDue()
+      }
+      now = target
+    },
+    intervalCount: () => intervals.size,
+  }
+}
+
+function fakeWebSocketClass() {
+  return class FakeSocket {
+    static CONNECTING = 0
+    static OPEN = 1
+    static CLOSING = 2
+    static CLOSED = 3
+    constructor(url) {
+      this.url = String(url)
+      this.readyState = 1
+      this.sent = []
+      this.listeners = new Map()
+    }
+    send(data) { this.sent.push(String(data)) }
+    addEventListener(type, fn) {
+      const list = this.listeners.get(type) ?? []
+      list.push(fn)
+      this.listeners.set(type, list)
+    }
+    removeEventListener(type, fn) {
+      const list = this.listeners.get(type) ?? []
+      this.listeners.set(type, list.filter((item) => item !== fn))
+    }
+    dispatch(type, event) {
+      for (const fn of this.listeners.get(type) ?? []) fn(event)
+    }
+  }
+}
+
+function install({ intervalMs = 1500, enabled = true } = {}) {
+  const plugin = loadPlugin()
+  const FakeSocket = fakeWebSocketClass()
+  const win = { WebSocket: FakeSocket, location: { href: 'https://dsh.example/' } }
+  const clock = fakeClock()
+  const disabled = []
+  const result = plugin.__test.installSocketKeepAlive({
+    win,
+    options: { enabled, intervalMs },
+    clock,
+    onDisabled: (reason) => disabled.push(reason),
+  })
+  return { plugin, win, clock, result, Native: FakeSocket, disabled }
+}
+
+const keepaliveFrames = (socket) => socket.sent.filter((raw) => raw.includes('dsh-bug-perf-keepalive'))
+
+// Given 页面创建 /api/remote.mux 连接, When 空闲到达保活间隔, Then 发出一条合法 item 帧
+test('保活_空闲_发出合法item帧', () => {
+  const { win, clock } = install()
+  const socket = new win.WebSocket('wss://dsh.example/api/remote.mux')
+  assert.equal(socket.sent.length, 0)
+  clock.advance(1500)
+  const frames = keepaliveFrames(socket)
+  assert.equal(frames.length, 1)
+  const frame = JSON.parse(frames[0])
+  assert.equal(frame.type, 'item')
+  assert.equal(typeof frame.streamId, 'string')
+  assert.ok(frame.streamId.length > 0)
+})
+
+// Given 保活已生效, When 继续空闲多个间隔, Then 每个间隔各一条,持续保活
+test('保活_持续_按间隔重复发送', () => {
+  const { win, clock } = install()
+  const socket = new win.WebSocket('wss://dsh.example/api/remote.mux')
+  clock.advance(1500)
+  clock.advance(1500)
+  clock.advance(1500)
+  const frames = keepaliveFrames(socket)
+  assert.equal(frames.length, 3)
+  assert.equal(new Set(frames.map((raw) => JSON.parse(raw).streamId)).size, 3)
+})
+
+// Given 连接上客户端自己刚发过上行帧, When 尚未到保活间隔, Then 不补保活帧
+test('保活_有上行活动_不补帧', () => {
+  const { win, clock } = install()
+  const socket = new win.WebSocket('wss://dsh.example/api/remote.mux')
+  socket.send('{"type":"open"}')
+  clock.advance(1000)
+  assert.equal(keepaliveFrames(socket).length, 0)
+  clock.advance(1000)
+  assert.equal(keepaliveFrames(socket).length, 1)
+})
+
+// Given 配置改了保活间隔, When 连接已存在, Then 既有连接按新间隔发送,不需要重建
+test('保活_间隔重配_既有连接生效', () => {
+  const { win, clock, result } = install()
+  const socket = new win.WebSocket('wss://dsh.example/api/remote.mux')
+  result.setIntervalMs(4000)
+  clock.advance(2500)
+  assert.equal(keepaliveFrames(socket).length, 0)
+  clock.advance(2000)
+  assert.equal(keepaliveFrames(socket).length, 1)
+})
+
+// Given 连接不在 OPEN 态, When 到达检查点, Then 不发送
+test('保活_非OPEN_不发送', () => {
+  const { win, clock } = install()
+  const socket = new win.WebSocket('wss://dsh.example/api/remote.mux')
+  socket.readyState = 3
+  clock.advance(1500)
+  assert.equal(socket.sent.length, 0)
+})
+
+// Given 非 remote.mux 连接, When 空闲到达间隔, Then 不发送(只补会话流)
+test('保活_其他连接_不发送', () => {
+  const { win, clock } = install()
+  const socket = new win.WebSocket('wss://dsh.example/api/bus/ws')
+  clock.advance(1500)
+  assert.equal(socket.sent.length, 0)
+})
+
+// Given 开关关闭, When 创建连接, Then 全局 WebSocket 不被包装且无任何帧
+test('保活_关闭_不包装', () => {
+  const { win, clock, Native } = install({ enabled: false })
+  assert.equal(win.WebSocket, Native)
+  clock.advance(5000)
+})
+
+// Given 连接关闭, When 连接已断, Then 保活定时器随连接清理,不再发送
+test('保活_连接关闭_清理定时器', () => {
+  const { win, clock, result } = install()
+  const socket = new win.WebSocket('wss://dsh.example/api/remote.mux')
+  socket.dispatch('close', { code: 1000 })
+  clock.advance(5000)
+  assert.equal(socket.sent.length, 0)
+  assert.equal(result.state.timers.size, 0)
+})
+
+// Given 普通断线与主动关闭, When 连续发生多次, Then 不计入熔断,补丁继续工作
+test('保活_普通断线_不熔断', () => {
+  const { win, clock, Native, disabled } = install()
+  for (const code of [1000, 1001, 1006, 1006]) {
+    const socket = new win.WebSocket('wss://dsh.example/api/remote.mux')
+    clock.advance(1500)
+    socket.dispatch('close', { code })
+  }
+  assert.equal(win.WebSocket === Native, false)
+  assert.deepEqual(disabled, [])
+})
+
+// Given 宿主以协议错误码关闭连接, When 连续命中熔断阈值, Then 补丁自行禁用并恢复原始构造器
+test('保活_协议关闭_熔断', () => {
+  const { win, clock, Native, disabled } = install()
+  for (let round = 0; round < 2; round++) {
+    const socket = new win.WebSocket('wss://dsh.example/api/remote.mux')
+    clock.advance(1500)
+    assert.equal(keepaliveFrames(socket).length, 1)
+    socket.dispatch('close', { code: 1008 })
+  }
+  assert.equal(win.WebSocket, Native)
+  assert.equal(disabled.length, 1)
+  clock.advance(9000)
+})
+
+// Given 连接从未发过保活帧, When 以协议错误码关闭, Then 不计入熔断(与应用自身协议错误区分)
+test('保活_未发保活帧_协议关闭不计数', () => {
+  const { win, clock, Native } = install()
+  for (let round = 0; round < 3; round++) {
+    const socket = new win.WebSocket('wss://dsh.example/api/remote.mux')
+    socket.dispatch('close', { code: 1008 })
+  }
+  assert.equal(win.WebSocket === Native, false)
+  clock.advance(5000)
+})
+
+// Given 连接健康存活超过恢复窗口, When 之后才发生协议关闭, Then 历史累计已清零
+test('保活_健康存活_清零累计', () => {
+  const { win, clock, Native } = install()
+  const first = new win.WebSocket('wss://dsh.example/api/remote.mux')
+  clock.advance(1500)
+  first.dispatch('close', { code: 1008 })
+  const second = new win.WebSocket('wss://dsh.example/api/remote.mux')
+  clock.advance(20000)
+  second.dispatch('close', { code: 1008 })
+  assert.equal(win.WebSocket === Native, false)
+})
+
+// Given 已被包装的连接, When 查看全局构造器, Then 仍是 WebSocket 语义且实例可判定
+test('保活_包装后_保持实例语义', () => {
+  const { win, Native } = install()
+  const socket = new win.WebSocket('wss://dsh.example/api/remote.mux')
+  assert.ok(socket instanceof Native)
+  assert.ok(socket instanceof win.WebSocket)
+  assert.equal(win.WebSocket.OPEN, 1)
+})