@yfwu2020/dsh-selection-explain 0.7.0 → 0.8.3

package/scripts/test-format.mjs

@@ -0,0 +1,93 @@
+/**
+ * 会话格式契约：**写出去的那几个 shape 必须是当前内核认的**。
+ *
+ * 为什么单独一个文件：升格（`↗ 升格`）是往会话日志里**写**事件，写完由内核按
+ * 会话格式做准入校验 —— 校验发生在**真实内核跑起来的那一刻**，不在构建期，
+ * 所以离线测试全绿也照样能在用户机器上炸。v0.7.0 就是这么坏的：
+ *
+ *   `source: { kind: 'plugin', plugin: name }` 是会话格式 v3 的写法；
+ *   v4 起该包装已退役，准入直接抛
+ *     format v4 message requires a producer-owned source kind
+ *   表现：升格请求返回 `ok: true`（只写进了内存里的会话面）→ 随后那轮 opener
+ *   「本轮运行失败」→ 整个 artifact 一个字都没落盘，新会话只剩表头。
+ *
+ * 这里钉住两件**离线可判**的事实（都是当初真正踩坏的）：
+ *   ① 上下文消息的 source.kind 是生产者自有的（`plugin:<插件名>`：非空、非裸 'plugin'），
+ *      且真的被用在 `form: 'snapshot'` 的上下文消息上（不是写了个没人用的常量）；
+ *   ② 构建产物里不再出现退役的 plugin 包装，以及升格那套 turn/step 骨架还在
+ *      （骨架丢了消息就没有坐标，客户端不会把它显示成历史对话）。
+ *
+ * 跑法：node scripts/test-format.mjs（已挂进 npm test）
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { PLUGIN_SOURCE_KIND, name } from '../lib/index.js'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const BUNDLE = readFileSync(resolve(HERE, '..', 'lib', 'index.js'), 'utf8')
+
+let pass = 0
+let fail = 0
+const assert = (label, ok, detail) => {
+  if (ok) {
+    pass += 1
+    console.log(`PASS  ${label}${detail ? ` — ${detail}` : ''}`)
+  } else {
+    fail += 1
+    console.log(`FAIL  ${label}${detail ? ` — ${detail}` : ''}`)
+  }
+}
+
+// ───────────────────────── ① 来源归属（v4 准入的那条线） ─────────────────────────
+assert(
+  '来源归属：上下文消息的 kind 与「插件名」一致（plugin:<插件名>）',
+  PLUGIN_SOURCE_KIND === `plugin:${name}`,
+  JSON.stringify({ PLUGIN_SOURCE_KIND, name }),
+)
+assert(
+  '来源归属：kind 是生产者自有的（非空、非裸 plugin）',
+  typeof PLUGIN_SOURCE_KIND === 'string' && PLUGIN_SOURCE_KIND.length > 'plugin:'.length && PLUGIN_SOURCE_KIND !== 'plugin',
+  JSON.stringify(PLUGIN_SOURCE_KIND),
+)
+assert(
+  '来源归属：第三方插件带 `plugin:` 命名空间（与内核 v3→v4 迁移的写法一致）',
+  PLUGIN_SOURCE_KIND.startsWith('plugin:'),
+  JSON.stringify(PLUGIN_SOURCE_KIND),
+)
+
+// ───────────────────────── ② 真的用上了（不是写了没人用的常量） ─────────────────────────
+const used = BUNDLE.indexOf('kind: PLUGIN_SOURCE_KIND')
+assert('使用点：源码里真的以 PLUGIN_SOURCE_KIND 作为 kind 写出消息', used >= 0, used >= 0 ? `偏移 ${used}` : '构建产物里找不到')
+{
+  // 同一个 source 字面量里：kind 之后要跟着 snapshot 呈现（客户端据此折叠成「上下文」行）
+  const window = used >= 0 ? BUNDLE.slice(used, used + 240) : ''
+  assert('使用点：同一条 source 带 `form: \'snapshot\'`（客户端才折叠成上下文行）', /form:\s*'snapshot'/.test(window), window ? JSON.stringify(window.slice(0, 80)) : '')
+  assert('使用点：同一条 source 带 sections（snapshot 的命名分节，模型读的就是这些字）', /sections:\s*\[/.test(window), '')
+}
+
+// ───────────────────────── ③ 退役写法不再出现 ─────────────────────────
+{
+  // v3 的 plugin 包装：kind:'plugin' 后面紧跟一个 plugin 字段。
+  // 注意这是**文本级**断言（连注释里都别写出那个形状）—— 宁可误报，也别漏报：
+  // 这正是本次回归的形态，写进注释里也会把将来的人带沟里。
+  const retired = /kind:\s*(["'])plugin\1\s*,\s*plugin\s*:/.exec(BUNDLE)
+  assert(
+    '退役写法：构建产物里没有 kind: plugin + plugin 字段的包装（v4 会当场拒掉）',
+    retired === null,
+    retired ? `offset ${retired.index}：${JSON.stringify(retired[0])}` : '',
+  )
+}
+
+// ───────────────────────── ④ 升格那套 turn/step 骨架还在 ─────────────────────────
+{
+  // 客户端按 turn/step 事件给消息定位；少一个，历史消息就没有坐标、不显示成对话
+  const skeleton = ['turn/start', 'step/start', 'user/message', 'assistant/message', 'step/end', 'turn/end']
+  const missing = skeleton.filter((type) => !BUNDLE.includes(`'${type}'`))
+  assert('升格骨架：turn/step 六个事件都还写着', missing.length === 0, missing.length ? `缺：${missing.join(', ')}` : '')
+  assert('升格骨架：turn/end 带 reason（否则那轮不算收尾）', /reason:\s*\{\s*kind:\s*'completed'/.test(BUNDLE), '')
+  assert('升格骨架：历史轮号从 1000 起（避开真实第一轮的号段）', /turnNo\s*=\s*1000/.test(BUNDLE), '')
+}
+
+console.log(`\n=== 会话格式契约测试结束：${pass} 通过 / ${fail} 失败 ===`)
+process.exit(fail === 0 ? 0 : 1)

package/scripts/test-model-follow.mjs

@@ -0,0 +1,193 @@
+/** Model following regressions: execute the client functions against real HTTP responses. */
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { createServer } from 'node:http'
+import { resolve } from 'node:path'
+import { test } from 'node:test'
+
+const source = readFileSync(resolve(process.argv[2] || 'src/client/index.js'), 'utf8')
+
+// Extract executable functions, never assert on their spelling or implementation.
+function functionSource(name) {
+  const start = source.indexOf('function ' + name + '(')
+  assert.ok(start >= 0, 'Missing client function: ' + name)
+  let depth = 0
+  for (let i = source.indexOf('{', start); i < source.length; i += 1) {
+    const ch = source[i]
+    if (ch === '{') depth += 1
+    else if (ch === '}' && --depth === 0) return source.slice(start, i + 1)
+    else if (ch === "'" || ch === '"' || ch === '`') {
+      for (i += 1; i < source.length; i += 1) {
+        if (source[i] === '\\') i += 1
+        else if (source[i] === ch) break
+      }
+    } else if (ch === '/' && source[i + 1] === '/') {
+      while (i < source.length && source[i] !== '\n') i += 1
+    } else if (ch === '/' && source[i + 1] === '*') {
+      i = source.indexOf('*/', i) + 1
+    }
+  }
+  throw new Error('Unclosed function: ' + name)
+}
+
+function currentSession(services) {
+  return new Function('ctx', functionSource('currentSessionId') + '; return currentSessionId()')({
+    get: (name) => services[name],
+  })
+}
+
+test('reads the current session from the modern DSH session binding, not catalog.current', () => {
+  assert.equal(currentSession({
+    uiSession: { adapter: { current: { getSnapshot: () => ({ key: 'session-a', props: { sessionId: 'session-a' } }) } } },
+    sessions: { list: { getSnapshot: () => ({ ids: ['session-a'], byId: {}, phase: 'ready', projectionsBySession: {} }) } },
+  }), 'session-a')
+})
+
+test('an absent modern binding cannot revive a stale legacy current session', () => {
+  assert.equal(currentSession({
+    uiSession: { adapter: { current: { getSnapshot: () => ({ key: undefined, props: { sessionId: undefined } }) } } },
+    sessions: { list: { getSnapshot: () => ({ current: 'stale-session' }) } },
+  }), '')
+})
+
+test('supports older DSH runtimes without the session binding service', () => {
+  assert.equal(currentSession({ sessions: { list: { getSnapshot: () => ({ current: 'legacy-session' }) } } }), 'legacy-session')
+})
+
+const server = createServer((req, res) => {
+  const id = new URL(req.url, 'http://localhost').searchParams.get('sessionId')
+  const send = () => {
+    res.setHeader('content-type', 'application/json')
+    res.end(JSON.stringify({ ok: true, current: { provider: 'provider', model: id }, models: [{ provider: 'provider', model: id }] }))
+  }
+  // A finishes after B, reproducing a switch while A's catalog is loading.
+  setTimeout(send, id === 'session-a' ? 40 : 0)
+})
+await new Promise((done) => server.listen(0, '127.0.0.1', done))
+const origin = 'http://127.0.0.1:' + server.address().port
+
+function catalogClient(currentId) {
+  return new Function('MODELS', 'fetch', 'currentSessionId', 'panelOrCurrentSessionId', `
+    var modelCatalog = { at: 0, items: [], current: null, stages: null, loading: false, pending: null, error: '', leakyOff: [], sessionId: null }
+    var modelCatalogRequestSeq = 0
+    ${functionSource('loadModelCatalog')}
+    return { load: loadModelCatalog, snapshot: () => modelCatalog }
+  `)(origin + '/models', fetch, () => currentId, () => currentId)
+}
+
+try {
+  await test('catalog requests use the panel session even after navigation to another session', async () => {
+    const client = catalogClient('session-b')
+    const result = await client.load(true, 'session-a')
+    assert.equal(result.current.model, 'session-a')
+    assert.equal(result.sessionId, 'session-a')
+  })
+
+  await test('concurrent catalogs for different sessions cannot share or overwrite each other', async () => {
+    const client = catalogClient('session-a')
+    const a = client.load(true, 'session-a')
+    const b = client.load(true, 'session-b')
+    const [resultA, resultB] = await Promise.all([a, b])
+    assert.equal(resultA.current.model, 'session-a')
+    assert.equal(resultB.current.model, 'session-b')
+    assert.equal(client.snapshot().current.model, 'session-b')
+    const cachedB = await client.load(false, 'session-b')
+    assert.equal(cachedB.current.model, 'session-b')
+  })
+} finally {
+  server.closeAllConnections()
+  await new Promise((done) => server.close(done))
+}
+
+await test('legacy follow-up model cannot override the model used by first and second rounds', async () => {
+  const ts = await import('typescript')
+  const host = readFileSync(resolve('src/index.ts'), 'utf8')
+  const start = host.indexOf('  const resolveRoute = (')
+  const end = host.indexOf('  /** 分钟级限流。 */', start)
+  const js = ts.default.transpileModule(host.slice(start, end), { compilerOptions: { target: ts.default.ScriptTarget.ES2022 } }).outputText
+  const config = { provider: 'shared', model: 'chosen', chatProvider: 'legacy', chatModel: 'wrong' }
+  const route = new Function('config', 'modelCache', 'ctx', 'captured', js + '; return resolveRoute')(config, { items: [] }, { get: () => null }, null)
+  assert.deepEqual(route(undefined, null, false), { provider: 'shared', model: 'chosen' })
+  assert.deepEqual(route(undefined, null, true), { provider: 'shared', model: 'chosen' })
+  config.provider = ''; config.model = ''
+  assert.deepEqual(route(undefined, { provider: 'session', model: 'current' }, true), { provider: 'session', model: 'current' })
+})
+
+await test('first and second rounds use the same selected model without borrowing follow-up effort', () => {
+  const payload = new Function('state', 'document', 'location', 'panelOrCurrentSessionId', 'selectionKind', functionSource('buildPayload') + '; return buildPayload')(
+    { modelChoice: { provider: 'shared', model: 'chosen' }, effort: 'max' }, { title: 'test' }, { href: 'http://local' }, () => 'session', () => 'text')
+  for (const stage of ['translation', 'detail']) {
+    const body = payload('text', 'context', 'label', false, stage)
+    assert.equal(body.provider, 'shared')
+    assert.equal(body.model, 'chosen')
+    assert.equal(body.effort, undefined)
+  }
+})
+
+function settingsClient(send) {
+  return new Function('fetch', `
+    var SETTINGS = '/settings', settingsSpec = {}, settingsSaving = false, settingsResetting = false,
+        settingsSaveRequest = null, settingsSaveSeq = 0, settingsSaveTimer = 0,
+        settingsLive = {provider: 'p', model: 'old'}, settingsSaved = {provider: 'p', model: 'old'},
+        settingsByKey = {}, state = {}, bridgeOn = true, EFFORT_KEY = 'effort', scheduled = 0, MAX_SELECTION = 4000;
+    var settingsNoteText = {textContent: ''}, settingsNote = {setAttribute: function(){}};
+    function renderSettingsNote(note) { settingsNoteText.textContent = note === 'error' ? '保存失败，改动未生效' : note }
+    function settingsDirtyCount() { return Object.keys(settingsLive).filter(k => settingsLive[k] !== settingsSaved[k]).length }
+    function scheduleSettingsSave() { scheduled++ }
+    function paintModelPick(){} function repaintModelMenu(){} function setControlValue(){}
+    function updateSettingDependencies(){} function syncComposerModel(){ state.modelChoice = settingsLive.model ? {provider: settingsLive.provider, model: settingsLive.model} : null }
+    function refreshModelRow(){} function paintModelPill(){} function writeStore(){} function applyPillPrefs(){} function scheduleBridgeScan(){}
+    ${functionSource('applySelectionLimit')}
+    ${functionSource('applyServerValues')}
+    ${functionSource('flushSettingsSave')}
+    ${functionSource('resetSettings')}
+    return { edit(model) { settingsLive.model = model }, save: flushSettingsSave, reset: resetSettings,
+      snapshot() { return {live: {...settingsLive}, saved: {...settingsSaved}, scheduled, resetting: settingsResetting, choice: state.modelChoice} } }
+  `)(send)
+}
+
+await test('a slow save preserves a newer model choice and schedules its save', async () => {
+  let finish
+  const client = settingsClient(() => new Promise(resolve => { finish = resolve }))
+  client.edit('first')
+  const pending = client.save()
+  client.edit('second')
+  finish({json: async () => ({ok: true, values: {provider: 'p', model: 'first'}})})
+  await pending
+  assert.equal(client.snapshot().live.model, 'second')
+  assert.equal(client.snapshot().saved.model, 'first')
+  assert.equal(client.snapshot().choice.model, 'second')
+  assert.equal(client.snapshot().scheduled, 1)
+})
+
+await test('reset waits for an active save before clearing the shared model', async () => {
+  let finish; const requests = []
+  const client = settingsClient((url, init) => {
+    const body = JSON.parse(init.body); requests.push(body)
+    if (!body.reset) return new Promise(resolve => { finish = resolve })
+    return Promise.resolve({json: async () => ({ok: true, values: {provider: '', model: '', chatReasoningEffort: 'high'}})})
+  })
+  client.edit('changed'); const pending = client.save(); client.reset()
+  await Promise.resolve()
+  assert.equal(requests.length, 1)
+  finish({json: async () => ({ok: true, values: {provider: 'p', model: 'changed'}})})
+  await pending
+  for (let i = 0; i < 20 && client.snapshot().resetting; i++) await new Promise(resolve => setTimeout(resolve, 0))
+  assert.equal(requests.length, 2)
+  assert.equal(requests[1].reset, true)
+  assert.equal(client.snapshot().live.model, '')
+  assert.equal(client.snapshot().choice, null)
+})
+
+await test('reset also clears a value normalized by the in-flight save', async () => {
+  let finish
+  const client = settingsClient((url, init) => JSON.parse(init.body).reset
+    ? Promise.resolve({json: async () => ({ok: true, values: {provider: '', model: ''}})})
+    : new Promise(resolve => { finish = resolve }))
+  client.edit(' padded '); const pending = client.save(); client.reset()
+  finish({json: async () => ({ok: true, values: {provider: 'p', model: 'padded'}})})
+  await pending
+  for (let i = 0; i < 20 && client.snapshot().resetting; i++) await new Promise(resolve => setTimeout(resolve, 0))
+  assert.equal(client.snapshot().live.model, '')
+  assert.equal(client.snapshot().scheduled, 0)
+})

package/scripts/test-route-cache.mjs

@@ -0,0 +1,138 @@
+/**
+ * /route 的会话级短缓存。
+ *
+ * 为什么单测它：跟随状态下**小窗一开着**客户端就每 2 秒问一次 /route，
+ * 而 host 侧解析"本会话在用哪个模型"要 readSession —— 那会把整份日志重放成 Session、
+ * 再逐条深拷贝一遍（本机实测 1.5MB 会话一次 80~125ms）。不缓存等于每 2 秒重放一次日志。
+ *
+ * 验的是三条：
+ *   ① 事件没涨（live 会话的 seq 不变）→ 不重读，直接回缓存；
+ *   ② seq 涨了但离上次重读太近 → 先扛住（防"主会话在连续对话时每拍重放"）；
+ *   ③ 用户动作路径（/models、/ping、analyze）不吃缓存 —— 必须是此刻那一份。
+ *
+ * 用法：node scripts/test-route-cache.mjs
+ */
+import assert from 'node:assert/strict'
+import { createServer } from 'node:http'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { apply } from '../lib/index.js'
+
+const home = await mkdtemp(join(tmpdir(), 'dsh-route-cache-'))
+const previousHome = process.env.DSH_HOME
+process.env.DSH_HOME = home
+
+/** 会话自己记的模型选择（每次"主会话换模型"都改它 + 让 seq 涨一格）。 */
+let selection = { provider: 'p1', model: 'm-fast' }
+/** live 会话的事件数（Session.seq = 日志长度，append 一次涨一格）。 */
+let liveSeq = 12
+/** readSession 被真正调用了几次 —— 缓存命中就该一次都不涨。 */
+let reads = 0
+
+const services = {
+  llm: { listProviders: () => [{ id: 'p1', models: [{ id: 'm-fast' }] }] },
+  agentDefaultModel: { currentSelection: () => ({ provider: 'p9', model: 'm-global' }) },
+  sessions: { get: () => ({ header: { cwd: '/fixture' }, seq: liveSeq }) },
+  sessionQuery: {
+    readSurface: async () => ({ events: [] }),
+    readSession: async () => {
+      reads += 1
+      return {
+        events: [
+          { type: 'user/message', data: {} },
+          { type: 'model/selection', data: { provider: 'p1', model: 'm-old' } },
+          { type: 'assistant/message', data: {} },
+          { type: 'model/selection', data: selection },
+        ],
+      }
+    },
+  },
+}
+
+const routes = new Map()
+const ctx = {
+  llm: services.llm,
+  get: (name) => services[name],
+  on: () => () => {},
+  effect: (fn) => fn(),
+  logger: { info() {}, warn() {} },
+  webServer: { register: (route) => { routes.set(route.path, route.handler); return () => routes.delete(route.path) } },
+}
+apply(ctx, {})
+
+const server = createServer((req, res) => {
+  const handler = routes.get(new URL(req.url, 'http://localhost').pathname)
+  if (!handler) { res.writeHead(404); res.end(); return }
+  Promise.resolve(handler(req, res)).catch((error) => {
+    console.error(error)
+    if (!res.headersSent) res.writeHead(500)
+    res.end()
+  })
+})
+await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve))
+const origin = 'http://127.0.0.1:' + server.address().port
+
+let passed = 0
+let failed = 0
+function check(label, ok, detail) {
+  if (ok) { passed += 1; console.log(`PASS  ${label}${detail ? ' — ' + detail : ''}`) }
+  else { failed += 1; console.log(`FAIL  ${label}${detail ? ' — ' + detail : ''}`) }
+}
+const route = async () => (await fetch(`${origin}/selection-explain/api/route?sessionId=session-1`)).json()
+const models = async () => (await fetch(`${origin}/selection-explain/api/models?sessionId=session-1`)).json()
+
+try {
+  // ① 第一次：真读一次
+  const first = await route()
+  check('第一次 /route 真读会话，拿到本会话的模型',
+    first.ok === true && first.model === 'm-fast' && reads === 1,
+    `model=${first.model} reads=${reads}`)
+
+  // ① 事件没涨（seq 不变）→ 命中缓存，一次都不重读
+  const second = await route()
+  const third = await route()
+  check('事件没涨时不重读会话日志（seq 没变 → 结论不可能变）',
+    second.model === 'm-fast' && third.model === 'm-fast' && reads === 1,
+    `reads=${reads}`)
+
+  // ② seq 涨了，但离上次重读太近 → 先扛住（挡住"主会话连续对话时每 2 秒重放一次"）
+  selection = { provider: 'p1', model: 'm-strong' }
+  liveSeq += 1
+  const throttled = await route()
+  check('seq 刚涨、距上次重读不足下限时不重读（防重放风暴）',
+    throttled.model === 'm-fast' && reads === 1,
+    `model=${throttled.model} reads=${reads}`)
+
+  // ② 过了下限 → 重读，跟上新模型
+  await new Promise((resolve) => setTimeout(resolve, 3200))
+  const caught = await route()
+  check('过了最短间隔后重读并跟上新模型',
+    caught.model === 'm-strong' && reads === 2,
+    `model=${caught.model} reads=${reads}`)
+
+  // ③ 用户动作路径不吃缓存：/models 每次都直读（刚换完模型划词不能按旧模型解析）
+  selection = { provider: 'p2', model: 'm-other' }
+  liveSeq += 1
+  const beforeModels = reads
+  await models()
+  await models()
+  check('/models（用户动作路径）每次都直读，不走缓存',
+    reads === beforeModels + 2,
+    `reads=${beforeModels} → ${reads}`)
+
+  // ③ 直读顺手把结论种进缓存（seq 对得上）→ 紧接着的轮询不必再读一遍
+  const seeded = await route()
+  check('直读种进缓存后，轮询不再重复读（seq 对得上就是同一个结论）',
+    seeded.model === 'm-other' && reads === beforeModels + 2,
+    `model=${seeded.model} reads=${reads}`)
+} finally {
+  server.closeAllConnections()
+  await new Promise((resolve) => server.close(resolve))
+  if (previousHome === undefined) delete process.env.DSH_HOME
+  else process.env.DSH_HOME = previousHome
+  await rm(home, { recursive: true, force: true })
+}
+
+console.log(`=== /route 缓存测试结束：${passed} 通过 / ${failed} 失败 ===`)
+if (failed > 0) process.exitCode = 1

package/scripts/test-settings-behavior.mjs

@@ -0,0 +1,188 @@
+/** Exercise setting effects through the real plugin HTTP handlers in disposable storage. */
+import assert from 'node:assert/strict'
+import {createServer} from 'node:http'
+import {mkdtemp, mkdir, readFile, rm, writeFile} from 'node:fs/promises'
+import {tmpdir} from 'node:os'
+import {join} from 'node:path'
+import {apply} from '../lib/index.js'
+
+const home=await mkdtemp(join(tmpdir(),'dsh-settings-behavior-'))
+const oldHome=process.env.DSH_HOME
+process.env.DSH_HOME=home
+await mkdir(join(home,'selection-explain'))
+await writeFile(join(home,'selection-explain/settings.json'),JSON.stringify({values:{maxTokens:1234,temperature:0.4,resultCacheTtlMs:600000,historyMaxEntries:0}}))
+const longSelection='长'.repeat(4500)+'末尾标记'
+await writeFile(join(home,'selection-explain/history.json'),JSON.stringify({entries:[{key:'existing-long',text:longSelection}]}))
+const routes=new Map(), calls=[], executions=[]
+let mode='answer', toolPath='inside.txt', checks=0, serial=0
+const events=[]
+for(let i=1;i<=10;i++){
+  events.push({type:'user/message',data:{role:'user',source:{kind:'user'},content:[{type:'text',text:`Q${String(i).padStart(2,'0')} `+'甲'.repeat(300)}]}})
+  events.push({type:'assistant/message',data:{message:{content:[{type:'text',text:`A${String(i).padStart(2,'0')} `+'乙'.repeat(300)}]}}})
+}
+const llm={listProviders:()=>[{id:'fixture',name:'Fixture'}],listModels:async()=>[{id:'a',name:'A'},{id:'b',name:'B'}],
+  async *stream(options){
+    calls.push(options)
+    if(mode==='timeout'){
+      await new Promise((resolve,reject)=>{
+        if(options.signal.aborted)reject(new DOMException('aborted','AbortError'))
+        else options.signal.addEventListener('abort',()=>reject(new DOMException('aborted','AbortError')),{once:true})
+      })
+    }
+    const tool=mode==='unexpected-tools'?(options.tools?.[0]??{name:'read'}):mode==='unlisted-tool'?{name:'grep'}:options.tools?.[0]
+    // 工具结果消息的 shape 跟运行时版本有关，两种都要认（见下面 textOfBlocks 的注释）
+    const hasResult=options.messages.some(m=>m.role==='tool'||(m.content||[]).some(b=>b.type==='tool-result'))
+    if(tool && (mode==='unexpected-tools' || mode==='unlisted-tool' || mode==='repeat-tools' || mode==='one-tool' && !hasResult)){
+      yield {type:'block-start',index:0,blockType:'tool-call'}
+      yield {type:'tool-call-delta',index:0,id:'call-'+calls.length,name:tool.name,argumentsDelta:JSON.stringify({file_path:toolPath})}
+      yield {type:'block-end',index:0,block:{type:'tool-call',id:'call-'+calls.length,name:tool.name,arguments:JSON.stringify({file_path:toolPath})}}
+      yield {type:'finish',reason:{kind:'tool-calls'}}
+    }else{
+      yield {type:'text-delta',index:0,text:'这是验证设置行为的回答，内容完整。'}
+      yield {type:'finish',reason:{kind:'stop'}}
+    }
+  },
+}
+const registry={schemas:()=>['read','grep','web_search','platform_search'].map(name=>({name,description:name,parameters:{type:'object',properties:{}}})),
+  async execute(input){executions.push(input);return {content:[{type:'text',text:'工具结果'.repeat(400)}],isError:false}}}
+const services={llm,tools:registry,agentDefaultModel:{currentSelection:()=>({provider:'fixture',model:'a'})},sessions:{get:()=>({header:{cwd:'/fixture/project'}})},
+  sessionQuery:{readSurface:async()=>({events}),readSession:async()=>({events:[]})}}
+const ctx={llm,get:name=>services[name],on(){return ()=>{}},effect:fn=>fn(),logger:{info(){},warn(){}},
+  webServer:{register(route){routes.set(route.path,route.handler);return ()=>routes.delete(route.path)}}}
+apply(ctx,{})
+const server=createServer((req,res)=>{
+  const handler=routes.get(new URL(req.url,'http://localhost').pathname)
+  if(!handler){res.writeHead(404);res.end();return}
+  Promise.resolve(handler(req,res)).catch(error=>{console.error(error);if(!res.headersSent)res.writeHead(500);res.end()})
+})
+await new Promise(resolve=>server.listen(0,'127.0.0.1',resolve))
+const origin='http://127.0.0.1:'+server.address().port
+async function json(path,body){const r=await fetch(origin+'/selection-explain/api/'+path,body?{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify(body)}:{});return r.json()}
+async function set(values){const result=await json('settings',{values});assert.equal(result.ok,true);assert.deepEqual(result.rejected,[]);return result}
+async function analyze(body={}){
+  const start=calls.length
+  const r=await fetch(origin+'/selection-explain/api/analyze',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({text:'probe-'+(++serial),refresh:true,sessionId:'fixture-session',...body})})
+  const text=await r.text()
+  const chunks=text.split('\n').filter(s=>s.startsWith('data: ')).map(s=>JSON.parse(s.slice(6)))
+  return {status:r.status,text,chunks,calls:calls.slice(start)}
+}
+function check(label,fn){try{fn();checks++;console.log('PASS '+label)}catch(error){console.error('FAIL '+label);throw error}}
+/**
+ * 取一段消息里的**全部文本**（含嵌在工具结果里的）。
+ *
+ * 工具结果消息的 shape 随运行时版本不同，两种都得认：
+ *   · `dsh-llm@0.1.7-rc.x`（本机运行时）：`role:'tool'`，`content` 就是 `[{type:'text',…}]`；
+ *   · `dsh-llm@0.1.5-rc.3`（`devDependencies` 里那份、也是 peer 范围的下界，**CI 装的就是它**）：
+ *     `role:'user'`，`content` 是 `[{type:'tool-result', content:[{type:'text',…}]}]` —— 嵌一层。
+ * 只认顶层 `type:'text'` 的话，在 CI 上"工具结果里有没有『已截断』"会**假失败**
+ * （v0.8.3 发布时实测踩到：截断标记明明在，只是藏在 tool-result 块里）。
+ */
+function textOfBlocks(blocks){return (blocks||[]).flatMap(b=>b.type==='text'?[String(b.text)]:(b.type==='tool-result'?textOfBlocks(b.content):[]))}
+function prompt(call){return (call?.messages||[]).filter(m=>m.role!=='system').flatMap(m=>textOfBlocks(m.content)).join('\n')}
+function background(call){const text=prompt(call);return text.includes('【会话背景】')?text.split('【会话背景】')[1].split('上面是会话背景')[0]:''}
+try{
+  await json('history',{key:'startup',text:'启动时历史设置'})
+  const initialHistory=await json('history')
+  check('首次直接保存历史也读取已持久化的设置',()=>assert.deepEqual(initialHistory.entries.map(e=>e.key),['existing-long']))
+  const loadedLong=await json('history?key=existing-long')
+  check('加载已有长划词历史不会按旧默认截断',()=>assert(loadedLong.entry.text===longSelection,`实际保存 ${loadedLong.entry.text.length} 字，期望 ${longSelection.length} 字`))
+  await json('settings')
+  await set({historyMaxEntries:20})
+  await set({provider:'fixture',model:'b',translationReasoningEffort:'max',reasoningEffort:'low',chatReasoningEffort:'off',tools:false})
+  for(const [label,body,effort] of [['首轮',{stage:'translation'},'max'],['次轮',{stage:'detail'},'low'],['追问',{question:'继续解释'},'off']]){
+    const r=await analyze(body)
+    check(label+'实际采用同一模型与对应思考强度',()=>{assert.equal(r.calls[0].model,'b');assert.equal(r.calls[0].reasoningEffort,effort)})
+  }
+  check('隐藏的输出上限、温度仍进入模型调用',()=>{assert.equal(calls[0].maxTokens,1234);assert.equal(calls[0].temperature,0.4)})
+  await set({maxSelectionChars:20})
+  const over=await analyze({text:'长'.repeat(21)})
+  check('选中文字上限拒绝过长请求',()=>assert.equal(over.status,413))
+  await set({maxSelectionChars:6000})
+  const longer=await analyze({text:'长'.repeat(4500)})
+  check('调高选中文字上限后 host 接受超过旧默认的文字',()=>assert.equal(longer.status,200))
+  await json('history',{key:'saved-long',text:longSelection})
+  const savedLong=await json('history?key=saved-long')
+  check('保存长划词历史保留选中文字及末尾',()=>assert(savedLong.entry.text===longSelection,`实际保存 ${savedLong.entry.text.length} 字，期望 ${longSelection.length} 字`))
+  await set({maxContextChars:200,sessionContext:false})
+  const local=await analyze({context:'局'.repeat(400)})
+  check('局部上下文按上限截断',()=>{assert(prompt(local.calls[0]).includes('局'.repeat(200)));assert(!prompt(local.calls[0]).includes('局'.repeat(201)))})
+  check('关闭会话背景后不注入会话消息',()=>assert.equal(background(local.calls[0]),''))
+  await set({sessionContext:true,sessionContextFastMessages:2,sessionContextMaxMessages:4,sessionContextMaxChars:0})
+  const fast=await analyze({text:'Q09',stage:'translation'})
+  const detail=await analyze({text:'Q09',stage:'detail'})
+  const chat=await analyze({text:'Q09',question:'继续'})
+  const count=r=>(background(r.calls[0]).match(/(?:▶\s*)?(?:用户|助手)：/g)||[]).length
+  check('首轮按设置取两条背景消息',()=>assert.equal(count(fast),2))
+  check('次轮与追问按设置取四条背景消息',()=>{assert.equal(count(detail),4);assert.equal(count(chat),4)})
+  await set({sessionContextMaxChars:1000})
+  const cap=await analyze({text:'Q09',stage:'detail'})
+  check('会话上下文字符上限改变实际注入量',()=>assert(background(cap.calls[0]).length<background(detail.calls[0]).length))
+  await set({quoteContextRounds:0,quoteContextMaxCharsPerTurn:200,quoteContextMaxChars:6000})
+  const quote0=await json('quote-context',{text:'Q05',sessionId:'fixture-session'})
+  await set({quoteContextRounds:2,quoteContextMaxCharsPerTurn:2000})
+  const quote2=await json('quote-context',{text:'Q05',sessionId:'fixture-session'})
+  check('引用上下文轮数控制实际取出的轮数',()=>{assert.equal(quote0.rounds,1);assert.equal(quote2.rounds,5)})
+  check('引用单条消息上限控制长消息裁剪',()=>{assert(quote0.context.length<600);assert(quote2.context.includes('甲'.repeat(300)))})
+  await set({quoteContextMaxChars:600})
+  const quoteCap=await json('quote-context',{text:'Q05',sessionId:'fixture-session'})
+  check('引用总字符上限减少上下文并保留引用',()=>{assert(quoteCap.context.length<quote2.context.length);assert(quoteCap.context.includes('【Q05】'))})
+  await set({tools:true,maxToolRounds:1,toolNames:'read',fallbackToolNames:'web_search',toolReadRoot:'/fixture/project',toolResultMaxChars:200})
+  mode='one-tool'; toolPath='/fixture/project/inside.txt'
+  const tool=await analyze()
+  check('工具允许列表控制提供给模型的工具',()=>assert.deepEqual(tool.calls[0].tools.map(t=>t.name),['read','web_search']))
+  check('工具返回字符上限作用于回灌模型的结果',()=>{const next=prompt(tool.calls[1]);assert(next.includes('已截断'));assert(!next.includes('工具结果'.repeat(60)))})
+  const beforeDenied=executions.length;toolPath='/fixture/outside.txt'
+  const denied=await analyze()
+  check('指定文件目录拒绝目录外调用',()=>{assert.equal(executions.length,beforeDenied);assert(denied.text.includes('越界已拒绝'))})
+  await set({toolReadRoot:''});toolPath='/fixture/outside.txt'
+  const beforeDefault=executions.length;await analyze()
+  check('文件目录留空时按会话工作目录限制',()=>assert.equal(executions.length,beforeDefault))
+  await set({toolReadRoot:'*'});await analyze()
+  check('文件目录星号允许跨目录调用',()=>assert.equal(executions.length,beforeDefault+1))
+  await set({toolNames:'unavailable',fallbackToolNames:'web_search'})
+  const fallback=await analyze()
+  check('首选工具不可用时加入备用搜索工具',()=>assert.deepEqual(fallback.calls[0].tools.map(t=>t.name),['web_search']))
+  await set({tools:false})
+  const noTools=await analyze()
+  check('关闭工具调用后模型拿不到工具',()=>assert.equal(noTools.calls[0].tools,undefined))
+  await set({tools:true,maxToolRounds:0})
+  const zero=await analyze()
+  check('调用轮数为零时不提供工具',()=>assert.equal(zero.calls[0].tools,undefined))
+  await set({maxToolRounds:1});mode='repeat-tools'
+  const beforeRounds=executions.length;await analyze()
+  check('调用轮数为一时只执行一轮工具',()=>assert.equal(executions.length-beforeRounds,1))
+  mode='unexpected-tools'
+  const beforeUnexpected=executions.length;await analyze()
+  check('收尾轮即使返回工具调用也不突破轮数上限',()=>assert.equal(executions.length-beforeUnexpected,1))
+  await set({maxToolRounds:0})
+  const beforeZeroUnexpected=executions.length;await analyze()
+  check('轮数为零时即使返回工具调用也不执行',()=>assert.equal(executions.length,beforeZeroUnexpected))
+  await set({maxToolRounds:1,tools:false})
+  const beforeDisabledUnexpected=executions.length;await analyze()
+  check('关闭工具后即使返回工具调用也不执行',()=>assert.equal(executions.length,beforeDisabledUnexpected))
+  await set({tools:true,toolNames:'read',fallbackToolNames:''});mode='unlisted-tool'
+  const beforeUnlisted=executions.length;await analyze()
+  check('模型返回未允许的工具也不执行',()=>assert.equal(executions.length,beforeUnlisted))
+  mode='answer';await set({tools:false})
+  const cacheText='cache-probe';const first=await analyze({text:cacheText,refresh:false});const second=await analyze({text:cacheText,refresh:false})
+  check('隐藏缓存设置后仍复用相同请求的结果',()=>{assert(first.calls.length>0);assert.equal(second.calls.length,0);assert(second.chunks.some(c=>c.cached===true))})
+  await set({historyMaxEntries:1})
+  await json('history',{key:'one',text:'一',turns:[]});await json('history',{key:'two',text:'二',turns:[]})
+  const history=await json('history')
+  check('历史保留段数实际淘汰旧对话',()=>assert.deepEqual(history.entries.map(e=>e.key),['two']))
+  await set({historyMaxEntries:0});await json('history',{key:'three',text:'三'})
+  const unchangedHistory=await json('history')
+  check('历史上限为零停止新保存并保留已有记录',()=>assert.deepEqual(unchangedHistory.entries.map(e=>e.key),['two']))
+  await set({timeoutMs:5000});mode='timeout'
+  const started=Date.now(), timed=await analyze()
+  check('生成时限实际取消模型流',()=>{assert(timed.chunks.some(c=>c.type==='error'&&c.message.includes('超时')));assert(Date.now()-started>=4900);assert(Date.now()-started<9000)})
+  mode='answer';await set({maxRequestsPerMinute:1})
+  const rate=await analyze()
+  check('每分钟请求上限实际拒绝超限请求',()=>assert.equal(rate.status,429))
+  console.log(`全部 ${checks} 项实际行为验证通过`)
+}finally{
+  server.closeAllConnections();await new Promise(resolve=>server.close(resolve))
+  await new Promise(resolve=>setTimeout(resolve,900))
+  if(oldHome===undefined)delete process.env.DSH_HOME;else process.env.DSH_HOME=oldHome
+  await rm(home,{recursive:true,force:true})
+}