@mzzsfy/dsh-context-manager 0.2.0 → 0.3.0

package/src/core.mjs

@@ -17,6 +17,9 @@ export const HISTORY_INPUT_LIMIT = 200
 export const HISTORY_INPUT_MAX_CHARS = 20 * 1000
 export const HISTORY_SCOPES = ['prompts', 'session', 'workspace', 'global']
 export const HISTORY_PROMPTS_MAX = 100
+// 提取器输出格式版本:升级即令全部 extracts 指纹缓存失效重解压(自愈补齐新格式条目);
+// 已知边界——超 MAX_ARTIFACT 的巨产物会话对齐时直接跳过,其旧版条目不随升级补齐
+export const HISTORY_EXTRACT_VERSION = 2
 export const HISTORY_ALIGN_THROTTLE_MS = 30 * 1000
 export const HISTORY_STARTUP_DELAY_MS = 30 * 1000
 export const HISTORY_STARTUP_SCAN_LIMIT = 100
@@ -53,15 +56,24 @@ export function isSessionRunning({ agents, sessionId }) {
 }
 
 /**
- * 从会话事件流提取人类输入:仅 user/message 且来源为用户本人,
- * 文本块按行拼接;工具结果回填、插件注入与空白输入(纯图/空/纯空白)均不产出。
+ * 从会话事件流提取人类输入:user/message(来源为用户本人,文本块按行拼接)与
+ * command/run(斜杠命令,重组为 /name+args;args 是命令名后 verbatim rawInput,
+ * 含分隔空白,recordInput: false 的命令无 args 产出裸命令名)。
+ * 工具结果回填、插件注入与空白输入(纯图/空/纯空白)均不产出。
  * @param events - readSession 返回的原始事件数组
  * @returns 条目 { text, at },时间取事件时间
  */
 export function extractUserInputs(events) {
   const entries = []
   for (const event of events || []) {
-    if (!event || event.type !== 'user/message') continue
+    if (!event) continue
+    if (event.type === 'command/run') {
+      const data = event.data
+      if (!data || !data.source || data.source.kind !== 'user' || typeof data.name !== 'string' || data.name === '') continue
+      entries.push({ text: '/' + data.name + (typeof data.args === 'string' ? data.args : ''), at: event.time })
+      continue
+    }
+    if (event.type !== 'user/message') continue
     const message = event.data
     if (!message || !message.source || message.source.kind !== 'user') continue
     const text = (message.content || [])
@@ -144,57 +156,3 @@ export function forkRetryText(data) {
     .join('\n')
   return text.trim() === '' ? null : text
 }
-
-/**
- * 家族谱系投影:按 parentSessionId 把会话行组装成「根 → 后代」链,
- * parentSessionId 断链(引用的父不在集合内)的行视为独立根。
- * 编排派生会话(origin === 'subagent')不是用户的 fork 版本,整行剔除,
- * 其后代随之断链成独立根——家族只统计用户可跳转的对话分支。
- * @param items - sessions.list 行数组(至少含 sessionId/parentSessionId)
- * @returns Map<sessionId, { root, chain: string[] }>——chain 为根到自身的 id 序列
- */
-export function sessionFamilyMap(items) {
-  const byId = new Map()
-  for (const item of Array.isArray(items) ? items : []) {
-    if (item && item.origin === 'subagent') continue
-    const id = item && (item.sessionId ?? item.id)
-    if (typeof id === 'string' && id !== '') byId.set(id, item)
-  }
-  const chains = new Map()
-  for (const id of byId.keys()) {
-    const chain = []
-    let cursor = id
-    let root = cursor
-    while (cursor !== undefined) {
-      chain.unshift(cursor)
-      root = cursor
-      const parent = byId.get(cursor)
-      cursor = parent && typeof parent.parentSessionId === 'string' && byId.has(parent.parentSessionId)
-        ? parent.parentSessionId
-        : undefined
-      if (chain.includes(cursor)) break
-    }
-    chains.set(id, { root, chain, item: byId.get(id) })
-  }
-  return chains
-}
-
-/**
- * 家族环计数:某会话在所属家族中的序位与成员数(按 updatedAt 升序,与分叉先后一致)。
- * 单成员家族返回 null(不渲染计数器)。
- * @param chains - sessionFamilyMap 的结果
- * @param sessionId - 目标会话
- */
-export function familyRing(chains, sessionId) {
-  const entry = chains instanceof Map ? chains.get(sessionId) : undefined
-  if (!entry) return null
-  const members = [...chains.entries()]
-    .filter(([, value]) => value.root === entry.root)
-    .sort((left, right) => {
-      const at = (record) => (record && record.item && typeof record.item.updatedAt === 'number' ? record.item.updatedAt : 0)
-      return at(left[1]) - at(right[1])
-    })
-    .map(([id]) => id)
-  if (members.length < 2) return null
-  return { index: members.indexOf(sessionId) + 1, total: members.length, members }
-}

package/src/index.js

@@ -1,6 +1,6 @@
 // dsh-context-manager Host 半区:历史输入工作区缓存对齐 + 启停/数据路由
-// (inputs / prompts/toggle 与 history/steer-recall/fork/fork-auto-resend/copy-sid
-// 五条启停)。
+// (inputs / prompts/toggle 与 history/history-button/steer-recall/fork/fork-auto-resend/copy-sid
+// 六条启停)。
 // 浮层请求直接读缓存文件立即返回;对齐在后台解压范围内会话产物与缓存合并写回,
 // 运行中会话也参与(实时追加其新输入)。fork 分叉动作走 client 服务面,
 // host 侧只有其启停路由。
@@ -19,6 +19,7 @@ import {
   HISTORY_FOCUS_WAIT_MS,
   HISTORY_INPUT_LIMIT,
   HISTORY_INPUT_MAX_CHARS,
+  HISTORY_EXTRACT_VERSION,
   HISTORY_PROMPTS_MAX,
   HISTORY_SCOPES,
   HISTORY_SESSION_SCAN_LIMIT,
@@ -48,6 +49,8 @@ export const MESSAGES = {
 const SETTINGS_SCHEMA = schemastery.object({
   historyEnabled: schemastery.boolean().default(true)
     .description('历史输入浮层(Alt+↑),低频功能,关闭后输入框锚点与快捷键整体不渲染;变更刷新页面生效'),
+  historyButtonEnabled: schemastery.boolean().default(true)
+    .description('输入框工具排的历史输入按钮,点击开关浮层,与 Alt+↑ 等效;关闭仅隐藏按钮,快捷键与浮层不受影响;变更刷新页面生效'),
   steerRecallEnabled: schemastery.boolean().default(true)
     .description('插话撤回图标,低频功能,关闭后撤回图标整体不渲染;变更刷新页面生效'),
   forkEnabled: schemastery.boolean().default(true)
@@ -79,6 +82,7 @@ function readSettings(ctx) {
   const value = settings ? settings.get(NAMESPACE) : undefined
   return {
     historyEnabled: !value || value.historyEnabled !== false,
+    historyButtonEnabled: !value || value.historyButtonEnabled !== false,
     steerRecallEnabled: !value || value.steerRecallEnabled !== false,
     forkEnabled: !value || value.forkEnabled !== false,
     forkAutoResendEnabled: Boolean(value && value.forkAutoResendEnabled === true),
@@ -176,16 +180,18 @@ export function apply(ctx, config) {
   }
 
   // 单会话提取:产物 stat 指纹与缓存一致即复用(零解压);否则解压并更新缓存。
-  // 运行中会话走内存指纹(runtimeExtracts),其余走磁盘 extracts
+  // 运行中会话走内存指纹(runtimeExtracts),其余走磁盘 extracts。
+  // 指纹之外校验提取器版本:版本不符即重解压(升级后旧条目自动补齐新格式)
   async function extractSession(recordItem, fingerprint, extracts, isRunning) {
     const sessionId = recordItem.header.id
     const known = isRunning ? runtimeExtracts.get(sessionId) : extracts[sessionId]
-    if (fingerprint !== null && known && known.mtimeMs === fingerprint.mtimeMs && known.size === fingerprint.size) {
+    if (fingerprint !== null && known && known.v === HISTORY_EXTRACT_VERSION
+      && known.mtimeMs === fingerprint.mtimeMs && known.size === fingerprint.size) {
       return known.entries
     }
     const snapshot = await ctx.sessionQuery.readSession(sessionId)
     const entries = extractUserInputs(snapshot.events)
-    const record = { mtimeMs: fingerprint === null ? 0 : fingerprint.mtimeMs, size: fingerprint === null ? 0 : fingerprint.size, entries }
+    const record = { v: HISTORY_EXTRACT_VERSION, mtimeMs: fingerprint === null ? 0 : fingerprint.mtimeMs, size: fingerprint === null ? 0 : fingerprint.size, entries }
     if (isRunning) runtimeExtracts.set(sessionId, record)
     else if (fingerprint !== null) extracts[sessionId] = record
     return entries
@@ -339,9 +345,10 @@ export function apply(ctx, config) {
         }
       }
       // 实时追加:产物 stat 与已知指纹不一致 = 会话有新输入未入缓存——聚焦对齐
-      // 只解该会话并写回。路由有界等待本次对齐(首条 <3s 预算):正常会话单次
-      // 请求内直接拿到新数据;超时(巨产物等)返回既有数据 aligned=false,后续
-      // 轮询流式补齐。巨产物跳过聚焦(解压耗时与内存峰值失控),维持 aligned=true
+      // 只解该会话并写回。提取器版本不符同判 stale(升级后旧格式条目在首请求
+      // 内经聚焦对齐补齐,不等后台批量)。路由有界等待本次对齐(首条 <3s 预算):
+      // 正常会话单次请求内直接拿到新数据;超时(巨产物等)返回既有数据 aligned=false,
+      // 后续轮询流式补齐。巨产物跳过聚焦(解压耗时与内存峰值失控),维持 aligned=true
       const check = async (cached) => {
         const agents = ctx.get('agents')
         const running = isSessionRunning({ agents, sessionId })
@@ -349,7 +356,7 @@ export function apply(ctx, config) {
         const located = ctx.get('sessionPersistence') ? ctx.get('sessionPersistence').locate(header) : undefined
         const fingerprint = located ? await safeStat(located.path) : null
         return {
-          stale: fingerprint !== null && !(known && known.mtimeMs === fingerprint.mtimeMs && known.size === fingerprint.size),
+          stale: fingerprint !== null && !(known && known.v === HISTORY_EXTRACT_VERSION && known.mtimeMs === fingerprint.mtimeMs && known.size === fingerprint.size),
           oversize: fingerprint !== null && fingerprint.size > maxArtifactBytes,
         }
       }
@@ -466,6 +473,32 @@ export function apply(ctx, config) {
         }
       },
     },
+    {
+      // 输入框历史按钮启停:与历史浮层开关同构,读走 settings,写经 settings.update
+      path: '/api/context/history-button-enabled',
+      handler: async (req, res) => {
+        try {
+          if (req.method === 'GET') {
+            sendJson(res, 200, { enabled: readSettings(ctx).historyButtonEnabled })
+            return
+          }
+          if (!rejectMethod(req, res, 'POST')) return
+          let body
+          try {
+            body = JSON.parse(await readBody(req))
+          } catch {
+            throw new Error(MESSAGES.badJsonBody)
+          }
+          const settings = ctx.get('settings')
+          if (!settings) throw new Error('宿主设置服务不可用')
+          // update 异步落盘后才提交新值:await 保证持久化完成后再读回
+          await settings.update(NAMESPACE, { historyButtonEnabled: Boolean(body && body.enabled) })
+          sendJson(res, 200, { enabled: readSettings(ctx).historyButtonEnabled })
+        } catch (error) {
+          respondError(ctx, res, error)
+        }
+      },
+    },
     {
       // 插话撤回启停:与历史浮层开关同构,读走 settings,写经 settings.update
       path: '/api/context/steer-recall-enabled',

package/test/client-fork-enhance.test.mjs

@@ -33,7 +33,8 @@ test('源码契约:进行中轮的按钮说明标注进行中语义', () => {
 // F3 分叉后自动重发 的客户端契约:
 // - 开关经 fork-auto-resend-enabled 路由拉取,默认关
 // - 点击登记的草稿带 autoSubmit(跟随开关)
-// - 消费侧 autoSubmit 时经 prompt 通道提交,prompt 失败仅 toast
+// - 消费侧 autoSubmit 时经 prompt 通道提交,提交即无草稿(官方发送语义:发送后输入框
+//   不残留原文,残留会诱导用户再次发送造成重复消息);prompt 失败才回填文本供手动重发
 // - prompt 不可用(旧宿主)时 submitPrompt 为 null,自动降级仅回填
 
 test('源码契约:自动重发开关经新路由拉取且默认关', () => {
@@ -41,11 +42,16 @@ test('源码契约:自动重发开关经新路由拉取且默认关', () => {
   assert.ok(CLIENT_SRC.includes('setAutoResend(Boolean(payload && payload.enabled === true))'), '开关默认必须是关(严格 true 才开)')
 })
 
-test('源码契约:autoSubmit 草稿消费时回填后经 prompt 提交', () => {
+test('源码契约:autoSubmit 消费即提交不留草稿,失败才回填', () => {
   const consume = CLIENT_SRC.slice(CLIENT_SRC.indexOf('const draft = pendingForkDrafts.get(sessionId)'), CLIENT_SRC.indexOf('return h(ForkDock'))
-  assert.ok(consume.includes('inputActions.setDraft(text)'), '回填必须先行(prompt 前,失败也有兜底文本)')
-  assert.ok(consume.includes('submitRef.current({ sessionId, text })'), 'autoSubmit 时应经 prompt 通道提交')
-  assert.ok(consume.includes("toast('自动重发失败"), 'prompt 失败应 toast 且文本保留')
+  const autoIdx = consume.indexOf('if (autoSubmit && submitRef.current)')
+  assert.ok(autoIdx >= 0, 'autoSubmit 且通道可用时应走提交分支')
+  const draftIdx = consume.indexOf('inputActions.setDraft(text)')
+  assert.ok(draftIdx > autoIdx, '回填不得先于 prompt(提交成功路径输入框必须无残留)')
+  const autoBranch = consume.slice(autoIdx)
+  assert.ok(autoBranch.includes('submitRef.current({ sessionId, text })'), 'autoSubmit 时应经 prompt 通道提交')
+  assert.ok(autoBranch.includes("toast('自动重发失败"), 'prompt 失败应 toast 提示')
+  assert.ok(autoBranch.indexOf('setDraft(text)') > autoBranch.indexOf('catch'), '失败兜底回填必须落在 catch 分支内')
 })
 
 test('源码契约:prompt 通道参数形态(requestId 幂等 + queue + text 段)', () => {
@@ -58,3 +64,62 @@ test('源码契约:prompt 通道参数形态(requestId 幂等 + queue + text 段
 test('源码契约:旧宿主无 prompt 时通道降级为 null(仅回填)', () => {
   assert.ok(CLIENT_SRC.includes("(remoteSession && typeof remoteSession.prompt === 'function')"), 'prompt 通道应以能力探测守门(含面缺失)')
 })
+
+// F4 回填不得覆盖用户输入 的客户端契约(实测 bug:点分叉后 200ms 内用户输入被 setDraft 吞掉;
+// 且消费删除草稿后 effect 依赖变化再跑一次,取到 undefined 走进 setDraft("") 空写清空输入框):
+// - 消费即删草稿后,该会话必须标记为「已消费」,effect 重跑直接短路,绝不空写
+// - 回填走单次投递:非空输入框不覆盖(用户已输入优先),改为 toast 提示
+
+test('源码契约:草稿消费后不得再对同会话写草稿(杜绝空写清空)', () => {
+  const consume = CLIENT_SRC.slice(CLIENT_SRC.indexOf('const draft = pendingForkDrafts.get(sessionId)'), CLIENT_SRC.indexOf('return h(ForkDock'))
+  const guardIdx = CLIENT_SRC.indexOf('consumedForkDrafts.has(sessionId)')
+  const addIdx = CLIENT_SRC.indexOf('consumedForkDrafts.add(sessionId)')
+  assert.ok(guardIdx >= 0, '消费后应经 consumedForkDrafts 短路重跑')
+  assert.ok(addIdx >= 0, '删除草稿的同时应登记已消费')
+  assert.ok(guardIdx < addIdx, '短路判断必须先于登记(登记发生在有草稿分支内)')
+  assert.ok(guardIdx < CLIENT_SRC.indexOf('const draft = pendingForkDrafts.get(sessionId)'), '短路必须先于取草稿')
+  assert.ok(consume.includes('consumedForkDrafts.add(sessionId)'), '登记应落在消费分支内')
+})
+
+test('源码契约:回填前经 useInput 快照探测输入框,非空不覆盖', () => {
+  const consume = CLIENT_SRC.slice(CLIENT_SRC.indexOf('const draft = pendingForkDrafts.get(sessionId)'), CLIENT_SRC.indexOf('return h(ForkDock'))
+  assert.ok(consume.includes('draftOccupied'), '应经 useInput 快照判定输入框是否已被用户占用')
+  assert.ok(consume.includes('原输入未回填'), '被占用时应 toast 说明未回填')
+  assert.ok(consume.includes('原输入未自动发送'), '自动重发被占用时应 toast 说明未发送')
+  assert.ok(consume.indexOf('draftOccupied') < consume.indexOf('inputActions.setDraft(text)'), '占用探测必须先于回填')
+})
+
+// F5 新轮注入 的客户端契约(实测 bug:轮号映射拉取一次即冻结,新轮 turn 不在映射中,
+// 注入资格判空后直接跳过,按钮永不出现,必须刷新页面重拉才恢复):
+// - 扫描发现「有轮号但映射无此轮」时必须重拉映射,而不是静默跳过
+// - 重拉必须有在途门控,避免 MutationObserver 高频触发造成请求风暴
+// - 重拉结果与在途基线对比,相同则不再 setState(否则 setState→重渲染→扫描无限循环)
+
+test('源码契约:映射缺失的轮触发重拉而非静默跳过', () => {
+  const scan = CLIENT_SRC.slice(CLIENT_SRC.indexOf('function scan() {'), CLIENT_SRC.indexOf('if (typeof MutationObserver'))
+  assert.ok(scan.includes('entry === undefined'), '扫描应识别映射缺失的轮')
+  assert.ok(scan.includes('refreshRef.current()'), '映射缺失时应触发重拉')
+})
+
+test('源码契约:重拉有在途门控', () => {
+  const refresh = CLIENT_SRC.slice(CLIENT_SRC.indexOf('refreshRef.current = () =>'), CLIENT_SRC.indexOf('loadRef.current()\n      .then((map) => {\n        if (disposed) return'))
+  assert.ok(CLIENT_SRC.includes('refreshPendingRef'), '重拉必须有在途门控标志')
+  assert.ok(refresh.includes('if (refreshPendingRef.current) return'), '门控判断应位于重拉入口首位')
+  assert.ok(refresh.includes('refreshPendingRef.current = true'), '进入重拉即置在途')
+  assert.ok(refresh.includes('refreshPendingRef.current = false'), '重拉结束应清在途(含失败路径)')
+})
+
+test('源码契约:重拉结果与基线相同则不 setState(防扫描循环)', () => {
+  const refresh = CLIENT_SRC.slice(CLIENT_SRC.indexOf('refreshRef.current = () =>'), CLIENT_SRC.indexOf('loadRef.current()\n      .then((map) => {\n        if (disposed) return'))
+  assert.ok(refresh.includes('setTurnEnds'), '重拉应更新映射')
+  assert.ok(refresh.includes('if (turnEndsRef.current === map) return'), '同一映射引用应短路,避免 setState 触发扫描循环')
+})
+
+test('源码契约:重拉入口经 ref 跨组件传递(Bootstrap 装配,扫描处调用)', () => {
+  assert.ok(CLIENT_SRC.includes('const refreshRef = useRef(null)'), 'ForkDock 侧应有 refreshRef')
+  assert.ok(CLIENT_SRC.includes('refreshRef.current = () => {'), 'Bootstrap 应装配重拉入口')
+})
+
+test('源码契约:fork dock 订阅官方 input 快照取草稿', () => {
+  assert.ok(CLIENT_SRC.includes('useInput'), 'dock 应订阅宿主注入的 useInput 快照')
+})

package/test/client-help.test.mjs

@@ -8,9 +8,10 @@ const CLIENT_SRC = readFileSync(fileURLToPath(new URL('../src/client.js', import
 // 设置项悬停说明契约:说明常量必须存在且逐项挂到对应开关(开关行工厂调用位)。
 // 断言以工厂调用为锚:行文本与说明常量必须出现在同一 switchRow(...) 调用内,
 // 防常量互换挂载或挂错行仍通过
-test('源码契约:三项设置的悬停说明齐备且挂到对应控件', () => {
+test('源码契约:六项设置的悬停说明齐备且挂到对应控件', () => {
   const TITLES = {
     HISTORY_SWITCH_TITLE: '历史输入浮层开关',
+    HISTORY_BUTTON_SWITCH_TITLE: '输入框历史按钮开关',
     STEER_SWITCH_TITLE: '插话撤回开关',
     FORK_SWITCH_TITLE: '对话 fork 开关',
     FORK_AUTO_RESEND_SWITCH_TITLE: '分叉后自动重发开关',
@@ -20,6 +21,7 @@ test('源码契约:三项设置的悬停说明齐备且挂到对应控件', () =
   }
   const rowAnchors = [
     { constant: 'HISTORY_SWITCH_TITLE', text: "'历史输入浮层(Alt+↑)'", label: TITLES.HISTORY_SWITCH_TITLE },
+    { constant: 'HISTORY_BUTTON_SWITCH_TITLE', text: "'输入框历史按钮'", label: TITLES.HISTORY_BUTTON_SWITCH_TITLE },
     { constant: 'STEER_SWITCH_TITLE', text: "'插话撤回'", label: TITLES.STEER_SWITCH_TITLE },
     { constant: 'FORK_SWITCH_TITLE', text: "'对话 fork'", label: TITLES.FORK_SWITCH_TITLE },
     { constant: 'FORK_AUTO_RESEND_SWITCH_TITLE', text: "'分叉后自动重发'", label: TITLES.FORK_AUTO_RESEND_SWITCH_TITLE },
@@ -44,7 +46,6 @@ test('源码契约:悬停说明覆盖各设置的关键行为语义', () => {
   assert.ok(CLIENT_SRC.includes('回填子会话输入框'), 'fork 说明缺重试回填语义')
   assert.ok(CLIENT_SRC.includes('尾号递增'), 'fork 说明缺标题递增语义')
   assert.ok(CLIENT_SRC.includes('重生成语义'), '自动重发说明缺重生成语义')
-  assert.ok(CLIENT_SRC.includes('家族版本'), '计数器说明缺家族版本语义')
 })
 
 // 搜索功能源码契约:query 双写 + 组合输入守卫 + 命中计数 + 两级 Esc

package/test/client-history-button.test.mjs

@@ -0,0 +1,158 @@
+// 输入框历史按钮 BDD:寻行/注入纯函数切片(桩 DOM)+ 注入接线源码契约。
+// client.js 单文件自包含无法 import,切片经 new Function 实例化后对桩 DOM 断言。
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const CLIENT_SRC = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+
+// 切片:按钮标记常量起点到历史浮层组件声明终点,范围内仅常量与纯函数
+// (findToolsRow / ensureHistoryButton / histButtonSvg 全部经 doc 参数注入)
+const PURE_START = CLIENT_SRC.indexOf('const HISTORY_BTN_FLAG = ')
+const PURE_END = CLIENT_SRC.indexOf('function HistoryDock(')
+assert.ok(PURE_START >= 0 && PURE_END > PURE_START, 'client.js 历史按钮切片定位失败')
+const pure = new Function(
+  CLIENT_SRC.slice(PURE_START, PURE_END)
+  + '; return { findToolsRow: findToolsRow, ensureHistoryButton: ensureHistoryButton, HISTORY_BTN_FLAG: HISTORY_BTN_FLAG }',
+)()
+
+// ── DOM 桩:最小实现,行为断言所需。
+// 建模局限(显式注明):stubButton 以 onclick 属性模拟 addEventListener(未建
+// EventTarget 语义),插入位置仅覆盖行尾分支(stub 节点无 nextSibling)——
+// 「插到最后一个 _add 之后但行尾尚有其他节点」的 ref 非空分支由源码契约
+// (insertBefore 锚点)与 L3 人工回归兜底,桩不重复建模。 ──
+
+function stubButton(className) {
+  return {
+    className,
+    type: undefined,
+    title: undefined,
+    appended: null,
+    addEventListener(type, fn) { this['on' + type] = fn },
+    appendChild(node) { this.appended = node },
+    setAttribute(name, value) { this['attr_' + name] = value },
+    remove() {},
+  }
+}
+
+function stubRow(buttons) {
+  return {
+    children: [...buttons],
+    inserted: null,
+    insertBefore(node, ref) { this.inserted = { node, ref }; this.children.push(node) },
+    querySelector(selector) {
+      // 注入标记选择器与生产同源:按导出常量拼锚,常量改名时桩同步失真暴露
+      if (selector.includes(pure.HISTORY_BTN_FLAG)) return this.children.find((child) => child['attr_' + pure.HISTORY_BTN_FLAG] !== undefined) || null
+      if (selector.includes('_add')) return this.children.find((child) => child.className.endsWith('_add')) || null
+      return null
+    },
+    querySelectorAll(selector) {
+      if (selector.includes('_add')) return this.children.filter((child) => child.className.endsWith('_add'))
+      return []
+    },
+  }
+}
+
+// createElement 与 createElementNS 分开计数,svg 与按钮各自可断言;
+// createElementNS 真实返回 tag 形态的节点(svg 内嵌 path)
+function stubDoc(createdButtons, createdSvg) {
+  return {
+    createElement: (tag) => { const node = stubButton(''); node.tagName = tag; createdButtons.push(node); return node },
+    createElementNS: (_ns, tag) => {
+      const node = stubButton('')
+      node.tagName = tag
+      if (tag === 'svg') createdSvg.push(node)
+      return node
+    },
+  }
+}
+
+// ── 场景6:寻行纯函数 ──
+
+test('findToolsRow:行后缀 _tools 且直含 _add 按钮返回行,任一锚点漂移返回 null', () => {
+  const toolsRow = { className: 'uV2eYG_tools' }
+  const addInTools = { className: 'uV2eYG_add', parentElement: toolsRow }
+  const otherRow = { className: 'uV2eYG_toolbar' }
+  const addInOther = { className: 'uV2eYG_add', parentElement: otherRow }
+  const doc = (buttons) => ({ querySelectorAll: () => buttons })
+  assert.equal(pure.findToolsRow(doc([addInTools])), toolsRow, '双锚点一致应返回工具排行')
+  assert.equal(pure.findToolsRow(doc([addInOther])), null, '行类后缀漂移必须拒绝注入')
+  assert.equal(pure.findToolsRow(doc([])), null, '无 _add 按钮必须返回 null')
+})
+
+// ── 场景2:幂等注入 ──
+
+test('ensureHistoryButton:克隆官方 _add 类名,插到最后一个 _add 之后,重复调用幂等', () => {
+  const addA = stubButton('uV2eYG_add')
+  const addB = stubButton('uV2eYG_add')
+  const row = stubRow([addA, addB])
+  const createdButtons = []
+  const createdSvg = []
+  const doc = stubDoc(createdButtons, createdSvg)
+  const toggles = []
+  const first = pure.ensureHistoryButton(doc, row, () => toggles.push(1))
+  assert.notEqual(first, null, '工具排齐备时应注入成功')
+  assert.equal(createdButtons.length, 1, '应创建恰好一个按钮')
+  const button = createdButtons[0]
+  assert.equal(button.className, 'uV2eYG_add', '必须克隆官方按钮类名获得原生视觉')
+  assert.equal(button['attr_' + pure.HISTORY_BTN_FLAG], '', '必须携带注入标记防重复')
+  assert.equal(button.type, 'button')
+  assert.equal(typeof button.onclick, 'function', '点击必须接线 toggle')
+  assert.deepEqual(row.inserted, { node: button, ref: null }, '应插到最后一个 _add 之后')
+  assert.equal(createdSvg.length, 1, '应创建历史图标 svg')
+  assert.equal(button.appended && button.appended.tagName, 'svg', '图标必须挂到按钮上')
+  const again = pure.ensureHistoryButton(doc, row, () => toggles.push(2))
+  assert.equal(again, first, '已注入时重复调用必须幂等返回既有按钮')
+  assert.equal(createdButtons.length, 1, '幂等调用不得重复创建')
+  button.onclick()
+  assert.equal(toggles.length, 1, '点击应触发 toggle')
+})
+
+test('ensureHistoryButton:工具排缺官方 _add 按钮时返回 null(干净禁用)', () => {
+  const row = stubRow([stubButton('uV2eYG_primary')])
+  const createdButtons = []
+  const createdSvg = []
+  const result = pure.ensureHistoryButton(stubDoc(createdButtons, createdSvg), row, () => {})
+  assert.equal(result, null, '无克隆源不得注入')
+  assert.equal(createdButtons.length, 0)
+})
+
+// ── 场景3/4 接线契约:源码断言(观察器主体无法离线实例化)──
+
+test('源码契约:HistoryDock 注入 effect 具备扫描守卫/卸载清理/外点守卫/toggle 接线', () => {
+  assert.ok(CLIENT_SRC.includes("'button[class$=\"_add\"]'"), '扫描必须按官方 _add 按钮定位工具排')
+  const scopeStart = CLIENT_SRC.indexOf('const HISTORY_BTN_FLAG = ')
+  const scopeEnd = CLIENT_SRC.indexOf('function SteerRecallDock(')
+  const scope = CLIENT_SRC.slice(scopeStart, scopeEnd)
+  assert.ok(scope.includes("'[' + HISTORY_BTN_FLAG + ']'"), '移除与查询必须走注入标记选择器')
+  // 外点关闭守卫:点击注入按钮不得触发浮层外点关闭(mousedown 先关后开竞态)
+  assert.ok(scope.includes(".closest('[' + HISTORY_BTN_FLAG + ']')"), '外点关闭必须跳过注入按钮')
+  // toggle:开→关,关→openPopup;经 ref 接线供挂载一次的监听器读到最新状态
+  assert.ok(scope.includes('function toggleFromButton()'), '缺 toggle 接线函数')
+  assert.ok(scope.includes('= toggleFromButton') && scope.includes('openPopup()'), 'toggle 必须经 ref 接线并闭合 openPopup')
+})
+
+// ── 场景3(按钮开关)/场景5(设置卡行):开关读取与停用接线契约 ──
+
+test('源码契约:按钮开关挂载拉取,停用即移除已注入且不再注入,状态到达触发重扫', () => {
+  assert.ok(CLIENT_SRC.includes("const HISTORY_BUTTON_ENABLED_URL = '/api/context/history-button-enabled'"), '缺按钮开关路由常量')
+  const scopeStart = CLIENT_SRC.indexOf('function HistoryDock(')
+  const scopeEnd = CLIENT_SRC.indexOf('function SteerRecallDock(')
+  const scope = CLIENT_SRC.slice(scopeStart, scopeEnd)
+  // 挂载拉取 + ref 双写(停用路径在观察器外也要即时生效)
+  assert.ok(scope.includes('api(HISTORY_BUTTON_ENABLED_URL)'), '开关值必须挂载拉取')
+  assert.ok(scope.includes('buttonEnabledRef.current = buttonEnabled'), '开关值必须双写 ref')
+  // 扫描守卫必须同时受总开关与按钮开关约束,停用移除已注入
+  assert.ok(/if \(enabledRef\.current === false \|\| buttonEnabledRef\.current === false\) \{\s*\n\s*removeAll\(\)/.test(scope), '扫描守卫缺按钮开关分支')
+  // 开关值异步到达(不触发 DOM 变更)时需主动重扫
+  assert.ok(/\[historyEnabled, buttonEnabled\]/.test(scope), '开关状态到达必须触发重扫')
+})
+
+test('源码契约:设置卡第六开关行走 switchRow 工厂,挂按钮开关路由与说明常量', () => {
+  assert.ok(CLIENT_SRC.includes("switchRow(HISTORY_BUTTON_ENABLED_URL, '输入框历史按钮'"), '设置卡缺输入框历史按钮开关行')
+  assert.ok(CLIENT_SRC.includes('h(HistoryButtonSwitchRow)'), 'ContextPanel 未挂载第六开关行')
+  assert.ok(CLIENT_SRC.includes('const HISTORY_BUTTON_SWITCH_TITLE ='), '缺按钮开关说明常量')
+})

package/test/client-runtime.test.mjs

@@ -0,0 +1,134 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { runInThisContext } from 'node:vm'
+
+// client.js 运行时冒烟:契约测试只比对源码字符串,查不出跨组件作用域错误
+// (实测漏过一个 ReferenceError:重拉入口引用了他组件的 ref,浏览器控制台才报,
+// 143 条契约测试全绿)。这里真正加载 client.js、跑通 factory 模块求值、并把每个
+// 已注册的插槽组件渲染一遍,让作用域/初始化类错误在测试阶段暴露。
+
+const CLIENT_SRC = readFileSync(fileURLToPath(new URL('../src/client.js', import.meta.url)), 'utf8')
+
+// 组件函数体不渲染真实 DOM,只消费 hooks(useState/useEffect/useRef)与 createElement:
+// 自造最小桩,零依赖全平台可跑(真 react 反而是环境耦合:CI 无宿主 profile)
+const ReactStub = {
+  createElement: (type, props, ...children) => ({ type, props, children }),
+  useState: (init) => [typeof init === 'function' ? init() : init, () => {}],
+  useEffect: () => {},
+  useRef: (value) => ({ current: value }),
+}
+
+const HOST_HOOK = (name) => () => { throw new Error('缺少 react,无法执行 ' + name) }
+
+// __ModuleLoader__ 桩:捕获 factory 与注册的插槽条目
+function loadPlugin() {
+  assert.ok(ReactStub, '运行时冒烟需要宿主的 react;未找到时本测试无法建立保障')
+  const slots = []
+  let captured = null
+  // client.js 以 window/document/ MutationObserver 为宿主全局:桩全局后即在同上下文求值
+  const saved = {
+    window: globalThis.window,
+    document: globalThis.document,
+    MutationObserver: globalThis.MutationObserver,
+  }
+  // client.js 在 factory 求值期访问 window(工厂在宿主窗口内执行),故全局桩在
+  // factory 调用期间也必须就位,不能只在 runInThisContext 期间挂载
+  const stubWindow = {
+    __ModuleLoader__: {
+      load(definition) {
+        captured = definition
+      },
+    },
+    // 导航图标声明入口:吞噬,避免污染桩 window
+    __navicIcons: { register() {} },
+  }
+  globalThis.window = stubWindow
+  globalThis.document = {
+    createElement: () => ({
+      style: {},
+      setAttribute() {},
+      appendChild() {},
+      addEventListener() {},
+      querySelector: () => null,
+      querySelectorAll: () => [],
+    }),
+    querySelector: () => null,
+    querySelectorAll: () => [],
+    addEventListener() {},
+    documentElement: { appendChild() {} },
+    head: { appendChild() {} },
+  }
+  globalThis.MutationObserver = class {
+    observe() {}
+    disconnect() {}
+  }
+  try {
+    runInThisContext(CLIENT_SRC, { filename: 'client.js' })
+    assert.ok(captured, 'client.js 必须调用 window.__ModuleLoader__.load 注册插件')
+    const ctx = {
+      get: () => undefined,
+      slots: {
+        inject: (name, register) => { register() },
+        register: (definition, component) => { slots.push({ definition, component }); return () => {} },
+      },
+      remote: undefined,
+      on: () => () => {},
+      effect: () => {},
+    }
+    const plugin = captured.factory((specifier) => {
+      if (specifier === 'react') return ReactStub
+      throw new Error('模块表缺依赖:' + specifier)
+    })
+    assert.ok(typeof plugin === 'object' && plugin !== null, 'factory 应返回插件对象')
+    return { plugin, slots, ctx, id: captured.id }
+  } finally {
+    globalThis.window = saved.window
+    globalThis.document = saved.document
+    globalThis.MutationObserver = saved.MutationObserver
+  }
+}
+
+test('运行时:client.js 可加载并注册插件对象', () => {
+  const { plugin, id } = loadPlugin()
+  assert.equal(id, '@mzzsfy/dsh-context-manager')
+  assert.equal(typeof plugin.apply, 'function', '插件应有 apply')
+  assert.ok(Array.isArray(plugin.inject), '插件应声明 inject 依赖面')
+  assert.ok(plugin.inject.includes('slots'), '插槽面是全部 UI 能力的载体')
+})
+
+test('运行时:apply 可执行且插槽全部注册成功(作用域错误在此暴露)', () => {
+  const { plugin, slots, ctx } = loadPlugin()
+  // 无远程服务面:走「干净禁用」路径,插槽注册仍应完成,不得抛错
+  plugin.apply(ctx)
+  assert.ok(slots.length > 0, 'apply 应至少注册一个插槽条目')
+  for (const { component } of slots) {
+    assert.equal(typeof component, 'function', '插槽条目必须是可渲染组件')
+  }
+})
+
+test('运行时:每个插槽组件均可求值(跨组件作用域错误在此暴露)', () => {
+  const { plugin, slots, ctx } = loadPlugin()
+  plugin.apply(ctx)
+  assert.ok(slots.length > 0)
+  for (const { definition, component } of slots) {
+    // 组件函数体在渲染期执行:跨组件变量引用错位会在此抛 ReferenceError
+    // (实测漏过的正是 ReferenceError;hooks 与宿主注入的 hook 面在组件体外调用
+    // 属宿主渲染器职责,本冒烟不模拟渲染器,故只对 ReferenceError 断言)
+    try {
+      component({ session: undefined, inputActions: undefined, useInput: undefined })
+    } catch (error) {
+      if (error instanceof ReferenceError) throw error
+    }
+  }
+})
+
+// 宿主侧无远程服务面时各入口的注册是「干净禁用」路径:插槽注册不得因缺面而中断
+test('运行时:缺 remote.session 时仍完成全部插槽注册', () => {
+  const { plugin, slots, ctx } = loadPlugin()
+  assert.equal(ctx.remote, undefined)
+  plugin.apply(ctx)
+  const names = slots.map(({ definition }) => definition.name)
+  assert.ok(names.includes('conversation.input.dock'), '输入框 dock 是 fork/历史/撤回三入口的载体')
+})