@mzzsfy/dsh-context-manager 0.2.1 → 0.4.0

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)
@@ -58,6 +61,21 @@ const SETTINGS_SCHEMA = schemastery.object({
     .description('会话标题栏的复制 sessionId 按钮,平时隐藏,鼠标悬停标题栏时显示,点击复制当前会话 id;关闭后按钮整体不渲染;变更刷新页面生效'),
 })
 
+// 0.1.7 宿主以静态 Config 导出生成设置节表单(maintain 同构);legacy 宿主经
+// settings.register 注册命名空间。根级 volatile 包装:0.1.7 下整节为 live 表单,
+// 节写经 loader 原地热更;旧宿主 schemastery 无 volatile 方法,特性检测原样返回
+export const Config = volatileWrap(SETTINGS_SCHEMA)
+
+function volatileWrap(schema) {
+  return typeof schema.volatile === 'function' ? schema.volatile() : schema
+}
+
+// volatile ref 动态解包(get 协议):0.1.7 下 apply 入参 config 为整节单 ref;
+// legacy 宿主 config 为普通对象原样透传
+function unwrapVolatile(value) {
+  return typeof value?.get === 'function' ? value.get() : value
+}
+
 function sendJson(res, status, payload) {
   res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
   res.end(JSON.stringify(payload))
@@ -74,11 +92,14 @@ function respondError(ctx, res, error) {
   sendJson(res, 400, { error: message })
 }
 
-function readSettings(ctx) {
+function readSettings(ctx, config) {
   const settings = ctx.get('settings')
-  const value = settings ? settings.get(NAMESPACE) : undefined
+  // 双形读(maintain 同构):legacy settings 命名空间 get;0.1.7+ apply 入参
+  // config 整节解包。方法面守卫兼防:服务在但缺 get 时回落默认值,防路由 handler 抛错
+  const value = settings && typeof settings.get === 'function' ? settings.get(NAMESPACE) : unwrapVolatile(config)
   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),
@@ -86,6 +107,22 @@ function readSettings(ctx) {
   }
 }
 
+// 双形写(maintain 同构,判定延迟到使用点):legacy 方法面以 register 为准
+// (0.1.7 的 settings.update 名义在场但按命名空间找条目必败,不可作判据);
+// 0.1.7+ 走 configEditor.edit 落 profile 条目(fiber.entry,与命名空间解耦),
+// 仅 volatile 字段变化时 loader 原地热更不重启。await 保证持久化完成后再读回
+async function persistToggle(ctx, patch) {
+  const settings = ctx.get('settings')
+  if (typeof settings?.register === 'function' && typeof settings?.update === 'function') {
+    await settings.update(NAMESPACE, patch)
+    return
+  }
+  const editor = ctx.get('configEditor')
+  const entry = ctx.fiber?.entry
+  if (!editor || typeof editor.edit !== 'function' || !entry) throw new Error('宿主设置服务不可用')
+  await editor.edit(entry, (current) => ({ ...current, ...patch }))
+}
+
 function readBody(req) {
   const BODY_MAX_BYTES = 64 * 1024
   return new Promise((resolve, reject) => {
@@ -176,16 +213,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 +378,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 +389,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,
         }
       }
@@ -446,7 +486,7 @@ export function apply(ctx, config) {
       handler: async (req, res) => {
         try {
           if (req.method === 'GET') {
-            sendJson(res, 200, { enabled: readSettings(ctx).historyEnabled })
+            sendJson(res, 200, { enabled: readSettings(ctx, config).historyEnabled })
             return
           }
           if (!rejectMethod(req, res, 'POST')) return
@@ -456,11 +496,31 @@ export function apply(ctx, config) {
           } catch {
             throw new Error(MESSAGES.badJsonBody)
           }
-          const settings = ctx.get('settings')
-          if (!settings) throw new Error('宿主设置服务不可用')
-          // update 异步落盘后才提交新值:await 保证持久化完成后再读回
-          await settings.update(NAMESPACE, { historyEnabled: Boolean(body && body.enabled) })
-          sendJson(res, 200, { enabled: readSettings(ctx).historyEnabled })
+          await persistToggle(ctx, { historyEnabled: Boolean(body && body.enabled) })
+          sendJson(res, 200, { enabled: readSettings(ctx, config).historyEnabled })
+        } catch (error) {
+          respondError(ctx, res, error)
+        }
+      },
+    },
+    {
+      // 输入框历史按钮启停:与历史浮层开关同构,读走 settings,写经 settings.update
+      path: '/api/context/history-button-enabled',
+      handler: async (req, res) => {
+        try {
+          if (req.method === 'GET') {
+            sendJson(res, 200, { enabled: readSettings(ctx, config).historyButtonEnabled })
+            return
+          }
+          if (!rejectMethod(req, res, 'POST')) return
+          let body
+          try {
+            body = JSON.parse(await readBody(req))
+          } catch {
+            throw new Error(MESSAGES.badJsonBody)
+          }
+          await persistToggle(ctx, { historyButtonEnabled: Boolean(body && body.enabled) })
+          sendJson(res, 200, { enabled: readSettings(ctx, config).historyButtonEnabled })
         } catch (error) {
           respondError(ctx, res, error)
         }
@@ -472,7 +532,7 @@ export function apply(ctx, config) {
       handler: async (req, res) => {
         try {
           if (req.method === 'GET') {
-            sendJson(res, 200, { enabled: readSettings(ctx).steerRecallEnabled })
+            sendJson(res, 200, { enabled: readSettings(ctx, config).steerRecallEnabled })
             return
           }
           if (!rejectMethod(req, res, 'POST')) return
@@ -482,11 +542,8 @@ export function apply(ctx, config) {
           } catch {
             throw new Error(MESSAGES.badJsonBody)
           }
-          const settings = ctx.get('settings')
-          if (!settings) throw new Error('宿主设置服务不可用')
-          // update 异步落盘后才提交新值:await 保证持久化完成后再读回
-          await settings.update(NAMESPACE, { steerRecallEnabled: Boolean(body && body.enabled) })
-          sendJson(res, 200, { enabled: readSettings(ctx).steerRecallEnabled })
+          await persistToggle(ctx, { steerRecallEnabled: Boolean(body && body.enabled) })
+          sendJson(res, 200, { enabled: readSettings(ctx, config).steerRecallEnabled })
         } catch (error) {
           respondError(ctx, res, error)
         }
@@ -498,7 +555,7 @@ export function apply(ctx, config) {
       handler: async (req, res) => {
         try {
           if (req.method === 'GET') {
-            sendJson(res, 200, { enabled: readSettings(ctx).forkEnabled })
+            sendJson(res, 200, { enabled: readSettings(ctx, config).forkEnabled })
             return
           }
           if (!rejectMethod(req, res, 'POST')) return
@@ -508,11 +565,8 @@ export function apply(ctx, config) {
           } catch {
             throw new Error(MESSAGES.badJsonBody)
           }
-          const settings = ctx.get('settings')
-          if (!settings) throw new Error('宿主设置服务不可用')
-          // update 异步落盘后才提交新值:await 保证持久化完成后再读回
-          await settings.update(NAMESPACE, { forkEnabled: Boolean(body && body.enabled) })
-          sendJson(res, 200, { enabled: readSettings(ctx).forkEnabled })
+          await persistToggle(ctx, { forkEnabled: Boolean(body && body.enabled) })
+          sendJson(res, 200, { enabled: readSettings(ctx, config).forkEnabled })
         } catch (error) {
           respondError(ctx, res, error)
         }
@@ -524,7 +578,7 @@ export function apply(ctx, config) {
       handler: async (req, res) => {
         try {
           if (req.method === 'GET') {
-            sendJson(res, 200, { enabled: readSettings(ctx).forkAutoResendEnabled })
+            sendJson(res, 200, { enabled: readSettings(ctx, config).forkAutoResendEnabled })
             return
           }
           if (!rejectMethod(req, res, 'POST')) return
@@ -534,10 +588,8 @@ export function apply(ctx, config) {
           } catch {
             throw new Error(MESSAGES.badJsonBody)
           }
-          const settings = ctx.get('settings')
-          if (!settings) throw new Error('宿主设置服务不可用')
-          await settings.update(NAMESPACE, { forkAutoResendEnabled: Boolean(body && body.enabled) })
-          sendJson(res, 200, { enabled: readSettings(ctx).forkAutoResendEnabled })
+          await persistToggle(ctx, { forkAutoResendEnabled: Boolean(body && body.enabled) })
+          sendJson(res, 200, { enabled: readSettings(ctx, config).forkAutoResendEnabled })
         } catch (error) {
           respondError(ctx, res, error)
         }
@@ -549,7 +601,7 @@ export function apply(ctx, config) {
       handler: async (req, res) => {
         try {
           if (req.method === 'GET') {
-            sendJson(res, 200, { enabled: readSettings(ctx).copySidEnabled })
+            sendJson(res, 200, { enabled: readSettings(ctx, config).copySidEnabled })
             return
           }
           if (!rejectMethod(req, res, 'POST')) return
@@ -559,10 +611,8 @@ export function apply(ctx, config) {
           } catch {
             throw new Error(MESSAGES.badJsonBody)
           }
-          const settings = ctx.get('settings')
-          if (!settings) throw new Error('宿主设置服务不可用')
-          await settings.update(NAMESPACE, { copySidEnabled: Boolean(body && body.enabled) })
-          sendJson(res, 200, { enabled: readSettings(ctx).copySidEnabled })
+          await persistToggle(ctx, { copySidEnabled: Boolean(body && body.enabled) })
+          sendJson(res, 200, { enabled: readSettings(ctx, config).copySidEnabled })
         } catch (error) {
           respondError(ctx, res, error)
         }
@@ -576,6 +626,14 @@ export function apply(ctx, config) {
   }
 
   ctx.inject(['settings'], (settingsCtx) => {
+    // 方法面守卫:settings 服务缺 register 面(0.1.7 已移除)即走新形态分支;
+    // 0.1.7 关闭原生自动设置页,设置面由本包自带分区承担(maintain 同构)
+    if (typeof settingsCtx.settings.register !== 'function') {
+      if (typeof settingsCtx.settings?.configure === 'function') {
+        settingsCtx.effect(() => settingsCtx.settings.configure({ auto: false }, ctx.fiber))
+      }
+      return
+    }
     settingsCtx.settings.register(NAMESPACE, SETTINGS_SCHEMA, { base: config })
   })
 }

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 },

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-history-scope.test.mjs

@@ -0,0 +1,34 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const CLIENT_SRC = readFileSync(fileURLToPath(new URL('../src/client.js', import.meta.url)), 'utf8')
+
+// 范围标签契约:默认单胶囊只显当前范围,点击展开 pill 组,选择后收起;←/→ 键盘切换走同一落点
+test('源码契约:范围标签默认单胶囊,点击展开 pill 组选择', () => {
+  assert.ok(CLIENT_SRC.includes('const [scopeOpen, setScopeOpen] = useState(false)'), '展开态应默认收起')
+  assert.ok(CLIENT_SRC.includes('HISTORY_SCOPE_LABELS[scopeIndex]'), '默认应单胶囊显示当前范围')
+  assert.ok(CLIENT_SRC.includes('HISTORY_SCOPE_LABELS.map('), '展开后应循环渲染 pill 组')
+  assert.ok(CLIENT_SRC.includes('onClick: () => setScopeOpen(true)'), '单胶囊点击应展开')
+  assert.ok(CLIENT_SRC.includes('onClick: () => (idx === scopeIndex ? setScopeOpen(false) : selectScope(idx))'), 'pill 点击应直达对应范围,当前项点击收起')
+})
+
+test('源码契约:selectScope 为键盘与点击共用的唯一切换落点,切换即收起', () => {
+  assert.ok(CLIENT_SRC.includes('function selectScope('), '应有 selectScope 直达切换函数')
+  // 键盘相对切换委托 selectScope,消除重复切换链
+  assert.ok(/function switchScope\(\s*delta\s*\)\s*\{[\s\S]{0,200}selectScope\(next\)/.test(CLIENT_SRC),
+    'switchScope 应委托 selectScope')
+  // 同范围重复点击不重拉
+  const body = CLIENT_SRC.match(/function selectScope\([^)]*\)\s*\{[\s\S]*?\n  \}/)
+  assert.ok(body && body[0].includes('viewRef.current.scopeIndex'), 'selectScope 应以当前范围守卫幂等')
+  assert.ok(body && body[0].includes('setScopeOpen(false)'), '切换后应收起展开态')
+})
+
+test('源码契约:重开浮层展开态复位,设置悬停说明同步展开语义', () => {
+  // openPopup 内 setScopeOpen(false):浮层重开不残留展开态
+  assert.ok(/function openPopup\(\)\s*\{[\s\S]{0,300}setScopeOpen\(false\)/.test(CLIENT_SRC),
+    '浮层重开应复位展开态')
+  assert.ok(CLIENT_SRC.includes('点击顶栏范围标签展开选择'), '历史说明缺范围标签展开选择语义')
+  assert.ok(CLIENT_SRC.includes('←/→ 切换范围'), '历史说明应保留键盘切换语义')
+})