@mzzsfy/dsh-context-manager 0.1.0

package/test/client-steer.test.mjs

@@ -0,0 +1,265 @@
+// 插话撤回(steer recall)接线与纯函数测试:加载真实 src/client.js,
+// 捕获 slots.register 断言 dock 条目结构,切片实例化纯函数锁定撤回动作与失败文案。
+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')
+
+// 加载 client.js 并执行 apply(mock 最小服务面),返回插槽注册捕获。
+// slots.inject 收到注册回调即同步执行;binding 桩仅对会话 s1 生效
+function loadClient({ binding, remoteSession } = {}) {
+  const modules = []
+  const registered = []
+  const injectedNames = []
+  const windowStub = { __ModuleLoader__: { load: (module) => modules.push(module) }, addEventListener: () => {} }
+  const reactStub = {
+    useState: (value) => [value, () => {}],
+    useEffect: () => {},
+    useRef: (value) => ({ current: value }),
+    createElement: () => null,
+  }
+  const requireStub = (name) => {
+    if (name === '@mzzsfy/dsh-toast/client') return { show: () => 0 }
+    return reactStub
+  }
+  const factory = new Function('window', 'require', 'document', CLIENT_SRC + '\n;return null')
+  factory(
+    windowStub,
+    requireStub,
+    { createElement: () => ({ style: {}, remove() {} }), head: { appendChild: () => {} }, body: { appendChild: () => {} } },
+  )
+  assert.equal(modules.length, 1, 'client.js 模块未被捕获')
+  const mod = modules[0].factory(requireStub)
+
+  const sessions = {
+    binding: (sessionId) => (sessionId === 's1' ? binding : undefined),
+    fork: () => Promise.resolve('child-1'),
+    open: () => {},
+  }
+  const remote = { session: remoteSession }
+  const ctx = {
+    get: (name) => (name === 'sessions' ? sessions : {}),
+    effect: () => {},
+    slots: {
+      inject: (name, register) => { injectedNames.push(name); register() },
+      register: (options, component) => registered.push({ options, component }),
+    },
+    get remote() { return remote },
+  }
+  mod.apply(ctx)
+  return { registered, injectedNames }
+}
+
+// 插话撤回 dock 条目捕获:与官方 queue dock(order 20)、goal dock(order 10)同槽位
+function findSteerEntry(options) {
+  const { registered, injectedNames } = loadClient(options)
+  assert.ok(injectedNames.includes('conversation.input.dock'), 'apply 未注入 conversation.input.dock 插槽')
+  const entries = registered.filter((item) => item.options.name === 'conversation.input.dock')
+  const entry = entries.find((item) => item.options.id === 'context-manager-steer')
+  assert.ok(entry, '未注册 id=context-manager-steer 的插话撤回 dock 条目')
+  return { entry, entries }
+}
+
+test('Given client.js 装载, When apply, Then 注册插话撤回与历史浮层 dock 条目', () => {
+  const { entry, entries } = findSteerEntry()
+  assert.equal(typeof entry.component, 'function', 'dock 条目缺组件')
+  assert.equal(entry.options.order, 25, '插话撤回条目 order 应紧邻官方队列面板(20)之后')
+  assert.ok(entries.some((item) => item.options.id === 'context-manager-history'), '历史浮层条目被挤掉')
+})
+
+test('Given 会话绑定存在, When dock inject, Then updateQueue 路由到 binding.session.updateQueue', async () => {
+  const calls = []
+  const binding = {
+    session: {
+      updateQueue: async (itemId, action) => {
+        calls.push({ itemId, action })
+        return { ok: true }
+      },
+    },
+  }
+  const { entry } = findSteerEntry({ binding })
+  const props = entry.options.inject('s1')
+  assert.equal(typeof props.updateQueue, 'function', 'inject 未返回 updateQueue')
+  const result = await props.updateQueue('m1', { kind: 'remove' })
+  assert.deepEqual(calls, [{ itemId: 'm1', action: { kind: 'remove' } }], 'updateQueue 未按 remove 动作透传')
+  assert.deepEqual(result, { ok: true })
+})
+
+test('Given 会话绑定缺失, When dock inject, Then 返回空 props(干净禁用)', () => {
+  const { entry } = findSteerEntry()
+  assert.deepEqual(entry.options.inject('s1'), {}, '绑定缺失应返回空 props')
+  assert.deepEqual(entry.options.inject('missing'), {}, '未知会话应返回空 props')
+})
+
+test('Given 会话面无 updateQueue(旧宿主), When dock inject, Then 返回空 props(干净禁用)', () => {
+  const { entry } = findSteerEntry({ binding: { session: {} } })
+  assert.deepEqual(entry.options.inject('s1'), {}, '会话面无 updateQueue 应返回空 props')
+})
+
+// 纯函数切片:steerRowsOf / withdrawFailureText / withdrawSteer(无外部依赖,动作经注入)
+const PURE_START = CLIENT_SRC.indexOf('function steerRowsOf(')
+const PURE_END = CLIENT_SRC.indexOf('function SteerRecallDock(')
+assert.ok(PURE_START >= 0 && PURE_END > PURE_START, 'client.js 插话撤回纯函数切片定位失败')
+const pure = new Function(
+  CLIENT_SRC.slice(PURE_START, PURE_END)
+  + '; return { steerRowsOf: steerRowsOf, withdrawFailureText: withdrawFailureText, withdrawSteer: withdrawSteer }',
+)()
+
+const STEERING_ROW = { id: 'm1', placement: 'steering', preview: '帮我看下', text: '帮我看下' }
+
+test('steerRowsOf:仅保留 placement=steering,防非数组与非行形态', () => {
+  const queue = [
+    { id: 'q1', placement: 'queued' },
+    STEERING_ROW,
+    { id: 'c1', placement: 'context' },
+    STEERING_ROW,
+    null,
+  ]
+  assert.deepEqual(pure.steerRowsOf(queue), [STEERING_ROW, STEERING_ROW])
+  assert.deepEqual(pure.steerRowsOf([]), [])
+  assert.deepEqual(pure.steerRowsOf(undefined), [])
+})
+
+test('withdrawSteer 主路径:remove 成功后回填草稿并提示,返回 true', async () => {
+  const calls = []
+  const actions = {
+    updateQueue: async (itemId, action) => { calls.push({ itemId, action }); return { ok: true } },
+    setDraft: (text) => calls.push({ setDraft: text }),
+    notify: (text, opts) => calls.push({ notify: text, opts }),
+  }
+  const done = await pure.withdrawSteer(STEERING_ROW, actions)
+  assert.equal(done, true)
+  assert.deepEqual(calls, [
+    { itemId: 'm1', action: { kind: 'remove' } },
+    { setDraft: '帮我看下' },
+    { notify: '已撤回到输入框', opts: undefined },
+  ])
+})
+
+test('withdrawSteer 已被应用:queue-item-not-found 不回填草稿,专用文案报错', async () => {
+  const calls = []
+  const actions = {
+    updateQueue: async () => ({ ok: false, error: { code: 'session/queue-item-not-found', message: 'queued item is no longer pending' } }),
+    setDraft: (text) => calls.push({ setDraft: text }),
+    notify: (text, opts) => calls.push({ notify: text, opts }),
+  }
+  const done = await pure.withdrawSteer(STEERING_ROW, actions)
+  assert.equal(done, false)
+  assert.deepEqual(calls, [{ notify: '插话已被应用,无法撤回', opts: { kind: 'error' } }])
+})
+
+test('withdrawSteer 其他失败:透传错误消息且不回填草稿', async () => {
+  const calls = []
+  const actions = {
+    updateQueue: async () => ({ ok: false, error: { code: 'session/steer-unavailable', message: 'busy' } }),
+    setDraft: (text) => calls.push({ setDraft: text }),
+    notify: (text, opts) => calls.push({ notify: text, opts }),
+  }
+  const done = await pure.withdrawSteer(STEERING_ROW, actions)
+  assert.equal(done, false)
+  assert.deepEqual(calls, [{ notify: '撤回失败: busy', opts: { kind: 'error' } }])
+})
+
+test('withdrawSteer 传输层拒绝:按错误处理且不回填草稿', async () => {
+  const calls = []
+  const actions = {
+    updateQueue: async () => { throw new Error('network down') },
+    setDraft: (text) => calls.push({ setDraft: text }),
+    notify: (text, opts) => calls.push({ notify: text, opts }),
+  }
+  const done = await pure.withdrawSteer(STEERING_ROW, actions)
+  assert.equal(done, false)
+  assert.deepEqual(calls, [{ notify: '撤回失败: network down', opts: { kind: 'error' } }])
+})
+
+test('withdrawSteer 摘除成功但回填抛错:兜底展示原文,不报成功', async () => {
+  const calls = []
+  const actions = {
+    updateQueue: async () => ({ ok: true }),
+    setDraft: () => { throw new Error('shell released') },
+    notify: (text, opts) => calls.push({ notify: text, opts }),
+  }
+  const done = await pure.withdrawSteer(STEERING_ROW, actions)
+  assert.equal(done, false)
+  assert.deepEqual(calls, [{ notify: '草稿回填失败,原文: 帮我看下', opts: { kind: 'error' } }])
+})
+
+// ── 组件级门控:干净禁用规约的落地断言(整源加载 + 记录型 createElement 直接调组件) ──
+
+// createElement 桩记录调用树:h(type, props, ...children) -> {type, props, children}
+function loadComponent() {
+  const modules = []
+  const registered = []
+  const windowStub = { __ModuleLoader__: { load: (module) => modules.push(module) }, addEventListener: () => {} }
+  const element = (type, props, ...children) => ({ type, props, children })
+  const reactStub = {
+    useState: (value) => [value, () => {}],
+    useEffect: () => {},
+    useRef: (value) => ({ current: value }),
+    createElement: element,
+  }
+  const requireStub = (name) => {
+    if (name === '@mzzsfy/dsh-toast/client') return { show: () => 0 }
+    return reactStub
+  }
+  const factory = new Function('window', 'require', 'document', CLIENT_SRC + '\n;return null')
+  factory(
+    windowStub,
+    requireStub,
+    { createElement: () => ({ style: {}, remove() {} }), head: { appendChild: () => {} }, body: { appendChild: () => {} } },
+  )
+  const mod = modules[0].factory(requireStub)
+  const sessions = { binding: () => undefined, fork: () => Promise.resolve('c'), open: () => {} }
+  const ctx = {
+    get: (name) => (name === 'sessions' ? sessions : {}),
+    effect: () => {},
+    slots: {
+      inject: (name, register) => register(),
+      register: (options, component) => registered.push({ options, component }),
+    },
+    get remote() { return { session: { page: () => Promise.resolve({ records: [] }) } } },
+  }
+  mod.apply(ctx)
+  const entry = registered.find((item) => item.options.id === 'context-manager-steer')
+  assert.ok(entry, '组件级测试未捕获插话撤回条目')
+  return entry.component
+}
+
+const DOCK_COMPONENT = loadComponent()
+const NO_ACTIONS = { setDraft: () => {} }
+const OK_UPDATE = async () => ({ ok: true })
+
+// useSession 桩:两次 selector 读取共用同一快照(与官方 SessionSnapshotSelector 单快照同构)
+function dockWith(snapshot) {
+  const useSession = (selector) => selector(snapshot)
+  return (props) => DOCK_COMPONENT({ session: {}, useSession, inputActions: NO_ACTIONS, updateQueue: OK_UPDATE, ...props })
+}
+
+test('SteerRecallDock 干净禁用:依赖任一缺失即返回 null', () => {
+  const dock = dockWith({ queue: [STEERING_ROW], subagent: null })
+  assert.equal(dock({ session: undefined }), null, 'session 缺失应不渲染')
+  assert.equal(dock({ inputActions: undefined }), null, 'inputActions 缺失应不渲染')
+  assert.equal(dock({ updateQueue: undefined }), null, 'updateQueue 缺失应不渲染')
+})
+
+test('SteerRecallDock 干净禁用:subagent 非 continuable 即返回 null,启用时零占位宿主', () => {
+  const locked = dockWith({ queue: [STEERING_ROW], subagent: { address: { mode: 'prompt' } } })
+  assert.equal(locked({}), null, 'queueMutable 为假应不渲染')
+  const host = dockWith({ queue: [], subagent: null })({})
+  assert.equal(host.type, 'div')
+  assert.equal(host.props.className, 'cx-steer-host', '启用时应渲染 display:none 宿主承载注入逻辑')
+})
+
+// 注入契约(源码级守卫):选择器/标记/清理必须存在,官方 DOM 结构漂移时静默降级
+test('SteerRecallDock 注入契约:语义标记选择器、按钮标记与卸载清理齐备', () => {
+  assert.ok(CLIENT_SRC.includes('[data-pending-steering]'), '应定位官方气泡语义标记')
+  assert.ok(CLIENT_SRC.includes('[class$="_actions"]'), '应按 CSS module 类名后缀定位官方图标排')
+  assert.ok(CLIENT_SRC.includes('data-cx-steer-recall'), '应有自家按钮标记防重复注入')
+  assert.ok(CLIENT_SRC.includes('new MutationObserver'), '应经 MutationObserver 跟随气泡出现')
+  assert.ok(CLIENT_SRC.includes('official.className'), '应克隆官方按钮类名保证样式原生')
+  assert.ok(CLIENT_SRC.includes('observer.disconnect()'), '卸载应断开观察')
+})

package/test/client-switch-guard.test.mjs

@@ -0,0 +1,33 @@
+// cx-switch 开关样式守卫 BDD:状态选择器回退为裸 input 会静默隐藏 label 内其他 input,
+// 属无报错的 UI 损坏,故对源文本做静态断言锁死结构
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const source = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+
+test('switch 隐藏规则以 input[type="checkbox"] 精确匹配', () => {
+  assert.match(source, /\.cx-switch input\[type="checkbox"\] \{ position:absolute/)
+})
+
+test('switch 状态选择器禁止裸 input 锚定(防误伤 label 内其他 input)', () => {
+  const bare = source.match(/\.cx-switch input:(?!\[type)[a-z-]+/g)
+  assert.equal(bare, null, `裸 input 状态选择器: ${bare}`)
+})
+
+test('checkbox 仅允许出现在 switchRow 工厂内,禁止裸 checkbox 直出', () => {
+  const occurrences = [...source.matchAll(/type: 'checkbox'/g)].map((match) => match.index)
+  assert.equal(occurrences.length, 1, `checkbox 字面量出现 ${occurrences.length} 次`)
+  const factoryStart = source.indexOf('function switchRow(')
+  assert.ok(factoryStart >= 0, '缺 switchRow 工厂')
+  const factoryEnd = source.indexOf('cx-switch__label', factoryStart)
+  assert.ok(occurrences[0] > factoryStart && occurrences[0] < factoryEnd, 'checkbox 字面量不在 switchRow 工厂内')
+})
+
+test('switchRow 产出顺序为 input 在前 track 在后', () => {
+  const factory = source.slice(source.indexOf('function switchRow('))
+  assert.ok(factory.indexOf("h('input'") < factory.indexOf('cx-switch__track'), '工厂内 input 必须先于 track')
+})

package/test/core-family.test.mjs

@@ -0,0 +1,122 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  forkFailureText,
+  forkRetryText,
+  sessionFamilyMap,
+  familyRing,
+} from '../src/core.mjs'
+
+// ── fork 锚点解析 ──
+
+test('Given 插件注入消息, When forkRetryText, Then 返回 null', () => {
+  assert.equal(forkRetryText({ source: { kind: 'plugin' }, content: [{ type: 'text', text: 'hi' }] }), null)
+})
+
+test('Given 纯图或空白 user 消息, When forkRetryText, Then 返回 null', () => {
+  assert.equal(forkRetryText({ source: { kind: 'user' }, content: [{ type: 'image', attachment: {} }] }), null)
+  assert.equal(forkRetryText({ source: { kind: 'user' }, content: [{ type: 'text', text: '   ' }] }), null)
+})
+
+test('Given undefined 或畸形 data, When forkRetryText, Then 返回 null', () => {
+  assert.equal(forkRetryText(undefined), null)
+  assert.equal(forkRetryText({}), null)
+  assert.equal(forkRetryText({ source: { kind: 'user' } }), null)
+})
+
+test('Given 多文本块 user 消息, When forkRetryText, Then 按行拼接且跳过图块', () => {
+  const text = forkRetryText({
+    source: { kind: 'user' },
+    content: [
+      { type: 'text', text: '第一行' },
+      { type: 'image', attachment: {} },
+      { type: 'text', text: '第二行' },
+    ],
+  })
+  assert.equal(text, '第一行\n第二行')
+})
+
+test('Given user 消息先于 turn/start(无门), When forkRetryText, Then 照常提取', () => {
+  assert.equal(forkRetryText({ source: { kind: 'user' }, content: [{ type: 'text', text: '首问' }] }), '首问')
+})
+
+// ── 家族谱系投影 ──
+
+test('Given 空/畸形输入, When sessionFamilyMap, Then 返回空 Map', () => {
+  assert.equal(sessionFamilyMap(undefined).size, 0)
+  assert.equal(sessionFamilyMap([]).size, 0)
+  assert.equal(sessionFamilyMap([null, {}, { sessionId: '' }]).size, 0)
+})
+
+test('Given 直链家族 根→A→B, When sessionFamilyMap, Then 各成员链正确且同根', () => {
+  const items = [
+    { sessionId: 'root', updatedAt: 3 },
+    { sessionId: 'a', parentSessionId: 'root', updatedAt: 1 },
+    { sessionId: 'b', parentSessionId: 'a', updatedAt: 2 },
+  ]
+  const chains = sessionFamilyMap(items)
+  assert.deepEqual(chains.get('b').chain, ['root', 'a', 'b'])
+  assert.equal(chains.get('b').root, 'root')
+  assert.equal(chains.get('a').root, 'root')
+  assert.equal(chains.get('root').root, 'root')
+})
+
+test('Given parentSessionId 指向不存在的会话(孤儿), When sessionFamilyMap, Then 视为独立根', () => {
+  const chains = sessionFamilyMap([{ sessionId: 'x', parentSessionId: 'ghost' }])
+  assert.equal(chains.get('x').root, 'x')
+  assert.deepEqual(chains.get('x').chain, ['x'])
+})
+
+test('Given 循环引用, When sessionFamilyMap, Then 不死循环', () => {
+  const chains = sessionFamilyMap([
+    { sessionId: 'p', parentSessionId: 'q' },
+    { sessionId: 'q', parentSessionId: 'p' },
+  ])
+  assert.ok(chains.get('p').chain.length <= 2)
+})
+
+test('Given 编排派生会话(origin=subagent)挂在根下, When sessionFamilyMap, Then subagent 行剔除且不计数', () => {
+  const chains = sessionFamilyMap([
+    { sessionId: 'root', updatedAt: 30 },
+    { sessionId: 'task', parentSessionId: 'root', origin: 'subagent', updatedAt: 20 },
+    { sessionId: 'fork', parentSessionId: 'root', updatedAt: 10 },
+  ])
+  assert.equal(chains.has('task'), false)
+  const ring = familyRing(chains, 'root')
+  assert.deepEqual(ring, { index: 2, total: 2, members: ['fork', 'root'] })
+})
+
+test('Given 整链均为 subagent, When familyRing, Then 单成员返回 null', () => {
+  const chains = sessionFamilyMap([{ sessionId: 'task', origin: 'subagent' }])
+  assert.equal(familyRing(chains, 'task'), null)
+})
+
+// ── 家族环计数 ──
+
+test('Given 家族 3 成员, When familyRing(中间 updatedAt), Then index=2 total=3 members 按 updatedAt 升序', () => {
+  const chains = sessionFamilyMap([
+    { sessionId: 'root', updatedAt: 30 },
+    { sessionId: 'a', parentSessionId: 'root', updatedAt: 10 },
+    { sessionId: 'b', parentSessionId: 'root', updatedAt: 20 },
+  ])
+  const ring = familyRing(chains, 'b')
+  assert.deepEqual(ring, { index: 2, total: 3, members: ['a', 'b', 'root'] })
+})
+
+test('Given 单成员家族, When familyRing, Then 返回 null', () => {
+  const chains = sessionFamilyMap([{ sessionId: 'only' }])
+  assert.equal(familyRing(chains, 'only'), null)
+})
+
+test('Given 目标不在投影内, When familyRing, Then 返回 null', () => {
+  assert.equal(familyRing(new Map(), 'nope'), null)
+  assert.equal(familyRing(undefined, 'nope'), null)
+})
+
+test('Given fork 错误码, When forkFailureText, Then 已知码映射中文未知码透出', () => {
+  assert.equal(forkFailureText('session/fork-unavailable'), '该轮尚未完成,不可分叉')
+  assert.equal(forkFailureText('session/workspace-attach-failed'), '分叉成功,但挂载到工作区失败')
+  assert.equal(forkFailureText('gateway/internal'), '分叉失败: gateway/internal')
+  assert.equal(forkFailureText(undefined), '分叉失败: 未知错误')
+})

package/test/core.test.mjs

@@ -0,0 +1,223 @@
+// core 纯函数测试:历史输入提取(G1-G3)/聚合(G4-G5)/搜索过滤/fork 错误文案/巨产物跳过线
+
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+const {
+  extractUserInputs,
+  aggregateInputs,
+  filterHistoryInputs,
+  forkFailureText,
+  forkRetryText,
+  maxArtifactBytesForHost,
+  HISTORY_ALIGN_LEGACY_MAX_ARTIFACT_BYTES,
+  HISTORY_ALIGN_MODERN_MAX_ARTIFACT_BYTES,
+  HISTORY_SCOPES,
+  HISTORY_INPUT_LIMIT,
+  HISTORY_INPUT_MAX_CHARS,
+  HISTORY_PROMPTS_MAX,
+} = await import('../src/core.mjs')
+
+function userEvent(overrides, text, at) {
+  return {
+    type: 'user/message',
+    seq: 1,
+    time: at,
+    ...overrides,
+    data: {
+      id: 'm1',
+      role: 'user',
+      source: { kind: 'user' },
+      content: text === undefined ? [] : [{ type: 'text', text }],
+      ...overrides?.data,
+    },
+  }
+}
+
+// ── 历史输入:事件提取(G1-G3)──
+
+test('历史输入提取:user/message 且 kind=user 产出文本与时间', () => {
+  const events = [userEvent(null, '修复归档面板', 500)]
+  assert.deepEqual(extractUserInputs(events), [{ text: '修复归档面板', at: 500 }])
+})
+
+test('历史输入提取:tool 结果与 plugin 注入不产出', () => {
+  const tool = userEvent({ data: { source: { kind: 'tool', callId: 'c1' }, content: [{ type: 'tool-result', toolCallId: 'c1', content: [] }] } }, undefined, 100)
+  const plugin = userEvent({ data: { source: { kind: 'plugin', plugin: 'x', form: 'instructions' }, content: [{ type: 'text', text: '注入' }] } }, undefined, 200)
+  assert.deepEqual(extractUserInputs([tool, plugin]), [])
+})
+
+test('历史输入提取:纯图与空文本跳过', () => {
+  const image = userEvent({ data: { content: [{ type: 'image', attachment: { id: 'a1' } }] } }, undefined, 100)
+  const blank = userEvent(null, '', 200)
+  const whitespace = userEvent(null, ' \n ', 300)
+  assert.deepEqual(extractUserInputs([image, blank, whitespace]), [])
+})
+
+test('历史输入提取:多 text block 按行拼接为单条', () => {
+  const events = [userEvent({ data: { content: [{ type: 'text', text: '第一段' }, { type: 'text', text: '第二段' }] } }, undefined, 300)]
+  assert.deepEqual(extractUserInputs(events), [{ text: '第一段\n第二段', at: 300 }])
+})
+
+// ── 历史输入:聚合(G4-G5)──
+
+test('历史输入聚合:同文本去重保留最新时间,按时间倒序', () => {
+  const merged = aggregateInputs([
+    { text: 'a', at: 1 },
+    { text: 'b', at: 5 },
+    { text: 'a', at: 9 },
+  ], { limit: 10, maxChars: 100 })
+  assert.deepEqual(merged, [{ text: 'a', at: 9 }, { text: 'b', at: 5 }])
+})
+
+test('历史输入聚合:limit 裁剪与单条截断', () => {
+  const merged = aggregateInputs([
+    { text: 'abcdef', at: 1 },
+    { text: 'xy', at: 2 },
+  ], { limit: 1, maxChars: 3 })
+  assert.deepEqual(merged, [{ text: 'xy', at: 2 }])
+})
+
+// ── 历史输入:每会话首条保护(挤出不做永久丢弃)──
+
+test('历史输入聚合:超 limit 挤出时每个会话最早条目仍保留', () => {
+  const merged = aggregateInputs([
+    { text: '开场提示词', at: 1, sid: 's-old' },
+    { text: '继续', at: 2, sid: 's-old' },
+    { text: '新会话开场', at: 3, sid: 's-new' },
+    { text: '收尾', at: 4, sid: 's-new' },
+  ], { limit: 2, maxChars: 100 })
+  assert.deepEqual(merged, [
+    { text: '收尾', at: 4, sid: 's-new' },
+    { text: '新会话开场', at: 3, sid: 's-new' },
+    { text: '开场提示词', at: 1, sid: 's-old' },
+  ])
+})
+
+test('历史输入聚合:首条已在 limit 内不多余追加,结果仍为时间倒序', () => {
+  const merged = aggregateInputs([
+    { text: 'a', at: 1, sid: 's1' },
+    { text: 'b', at: 2, sid: 's2' },
+  ], { limit: 10, maxChars: 100 })
+  assert.deepEqual(merged, [{ text: 'b', at: 2, sid: 's2' }, { text: 'a', at: 1, sid: 's1' }])
+})
+
+test('历史输入聚合:首条保护在去重后集合上计算,与 limit 内文本重复不产生双条目', () => {
+  // s-old 的首条文本与 s-new 的某条相同:去重保留最新,归属 s-new,不再重复追加
+  const merged = aggregateInputs([
+    { text: '继续', at: 1, sid: 's-old' },
+    { text: '继续', at: 9, sid: 's-new' },
+    { text: '其他', at: 5, sid: 's-new' },
+  ], { limit: 1, maxChars: 100 })
+  assert.deepEqual(merged, [{ text: '继续', at: 9, sid: 's-new' }, { text: '其他', at: 5, sid: 's-new' }])
+})
+
+test('历史输入聚合:无 sid 条目不触发首条保护', () => {
+  const merged = aggregateInputs([
+    { text: 'old', at: 1 },
+    { text: 'new', at: 2 },
+  ], { limit: 1, maxChars: 100 })
+  assert.deepEqual(merged, [{ text: 'new', at: 2 }])
+})
+
+test('历史输入聚合:首条保护同样受 maxChars 截断', () => {
+  const merged = aggregateInputs([
+    { text: 'abcdef', at: 1, sid: 's1' },
+    { text: 'xy', at: 2, sid: 's2' },
+  ], { limit: 1, maxChars: 3 })
+  assert.deepEqual(merged, [{ text: 'xy', at: 2, sid: 's2' }, { text: 'abc', at: 1, sid: 's1' }])
+})
+
+// ── 搜索过滤(与 client.js 镜像,行为逐条对齐)──
+
+test('历史搜索:空查询原样返回全量,非数组入参按空处理', () => {
+  const entries = [{ text: 'abc' }, { text: 'def' }]
+  assert.deepEqual(filterHistoryInputs(entries, ''), entries)
+  assert.deepEqual(filterHistoryInputs(entries, '   '), entries)
+  assert.deepEqual(filterHistoryInputs(undefined, 'a'), [])
+  assert.deepEqual(filterHistoryInputs(null, 'a'), [])
+})
+
+test('历史搜索:大小写不敏感子串匹配,保留原序', () => {
+  const entries = [{ text: 'Fix ARCHIVE bug' }, { text: '归档面板' }, { text: 'unrelated' }]
+  assert.deepEqual(filterHistoryInputs(entries, 'archive'), [entries[0]])
+  assert.deepEqual(filterHistoryInputs(entries, '归档'), [entries[1]])
+  assert.deepEqual(filterHistoryInputs(entries, 'un'), [entries[2]])
+})
+
+test('历史搜索:查询词去首尾空白后匹配,无命中返回空数组', () => {
+  const entries = [{ text: 'abc' }]
+  assert.deepEqual(filterHistoryInputs(entries, ' abc '), entries)
+  assert.deepEqual(filterHistoryInputs(entries, 'zzz'), [])
+})
+
+test('历史搜索:条目缺 text 按空串参与匹配,仅命中空查询', () => {
+  const entries = [{ at: 1 }, { text: 'abc' }]
+  assert.deepEqual(filterHistoryInputs(entries, ''), entries)
+  assert.deepEqual(filterHistoryInputs(entries, 'abc'), [entries[1]])
+  assert.deepEqual(filterHistoryInputs(entries, 'a'), [entries[1]])
+})
+
+// ── fork 错误文案 ──
+
+test('fork 错误文案:未完成轮/挂载失败/未知码分通道', () => {
+  assert.equal(forkFailureText('session/fork-unavailable'), '该轮尚未完成,不可分叉')
+  assert.equal(forkFailureText('session/workspace-attach-failed'), '分叉成功,但挂载到工作区失败')
+  assert.equal(forkFailureText('gateway/internal'), '分叉失败: gateway/internal')
+  assert.equal(forkFailureText(undefined), '分叉失败: 未知错误')
+})
+
+// ── fork 重试文本提取 ──
+
+test('Given 用户本人多文本块消息, When forkRetryText, Then 文本块按行拼接', () => {
+  const data = {
+    source: { kind: 'user' },
+    content: [{ type: 'text', text: '第一行' }, { type: 'image', attachment: {} }, { type: 'text', text: '第二行' }],
+  }
+  assert.equal(forkRetryText(data), '第一行\n第二行')
+})
+
+test('Given 插件注入/空白/纯图片消息, When forkRetryText, Then 返回 null 不提供重试', () => {
+  assert.equal(forkRetryText({ source: { kind: 'plugin', plugin: 'x' }, content: [{ type: 'text', text: '注入' }] }), null)
+  assert.equal(forkRetryText({ source: { kind: 'user' }, content: [] }), null)
+  assert.equal(forkRetryText({ source: { kind: 'user' }, content: [{ type: 'text', text: '   ' }] }), null)
+  assert.equal(forkRetryText({ source: { kind: 'user' }, content: [{ type: 'image', attachment: {} }] }), null)
+})
+
+test('Given 非对象或畸形 data, When forkRetryText, Then 返回 null 不抛错', () => {
+  assert.equal(forkRetryText(undefined), null)
+  assert.equal(forkRetryText({}), null)
+  assert.equal(forkRetryText({ source: { kind: 'user' } }), null)
+})
+
+// ── 巨产物跳过线:宿主版本黑名单 ──
+
+test('巨产物跳过线:0.1.1 与 0.1.2 系列(含 prerelease)按旧线', () => {
+  for (const version of ['0.1.1', '0.1.1-rc.2', '0.1.2', '0.1.2-rc.1', '0.1.2-alpha.2']) {
+    assert.equal(maxArtifactBytesForHost(version), HISTORY_ALIGN_LEGACY_MAX_ARTIFACT_BYTES, version)
+  }
+})
+
+test('巨产物跳过线:0.1.3 起与未知未来版本按新线', () => {
+  for (const version of ['0.1.3', '0.1.5', '0.1.5-rc.1', '0.2.0', '1.0.0']) {
+    assert.equal(maxArtifactBytesForHost(version), HISTORY_ALIGN_MODERN_MAX_ARTIFACT_BYTES, version)
+  }
+})
+
+test('巨产物跳过线:版本缺失或非法保守回退旧线', () => {
+  for (const version of [null, undefined, '', 'garbage', '0.1']) {
+    assert.equal(maxArtifactBytesForHost(version), HISTORY_ALIGN_LEGACY_MAX_ARTIFACT_BYTES, String(version))
+  }
+})
+
+// ── 常量自检 ──
+
+test('历史范围常量:四范围固定序,默认落点为当前会话', () => {
+  assert.deepEqual(HISTORY_SCOPES, ['prompts', 'session', 'workspace', 'global'])
+})
+
+test('历史容量常量:输入 200 条/单条 2 万字符/收藏 100 条', () => {
+  assert.equal(HISTORY_INPUT_LIMIT, 200)
+  assert.equal(HISTORY_INPUT_MAX_CHARS, 20 * 1000)
+  assert.equal(HISTORY_PROMPTS_MAX, 100)
+})