dsh-router-core 0.4.2 → 0.4.4

package/src/index.ts

@@ -44,9 +44,9 @@ import { SupplierConfigStore } from './supplier-config.ts'
 import { CredentialStore } from './credential-store.ts'
 import { dataDirOf, profileDirOf } from './data-dir.ts'
 import { loopbackBaseURL } from './host-base-url.ts'
-import { detectHostVersion, isHost017Plus, supportsLastHitDock } from './host-version.ts'
+import { detectHostVersion, isHostSupported } from './host-version.ts'
 import { ExtStore } from './ext/store.ts'
-import type { ExtInfo, ExtStoreService, RouterExt, RouterExtService } from './ext/contract.ts'
+import type { ExtControl, ExtInfo, ExtStoreService, RouterExt, RouterExtService } from './ext/contract.ts'
 
 /**
  * Plugin identity for cordis.yml rows — 必须与 package.json 的 name 一致。
@@ -58,28 +58,25 @@ export const name = 'dsh-router-core'
 export const inject = ['webServer', 'llm']
 
 /**
- * `Config` 导出：让 Router 卡片进 0.1.7 的设置镜像。
+ * `Config` 导出：让 Router 卡片进设置-模型的镜像（0.2.0 的收录链是「插件导出的
+ * Config + 配置树行 id」）。
  *
- * **这处刻意保留能力检测，不用宿主版本号** —— 与另两处兼容点（installSection /
- * adapter 消息形态）不同。原因（已实测）：这是**模块顶层导出**，loader 一 import
- * 就求值；而 schemastery 是本插件的**普通依赖**（`^3.18.4`，见 package.json），
- * 解析到的是**插件自己 node_modules 里那一份**，跟宿主实际加载的版本无关
- * （实测：插件解析到 3.18.4，而 profile 里是 3.18.3、全局是 3.18.2）。既然这里
- * 拿不到宿主版本，就只剩「这份 Schema 实例到底有没有 `.volatile`」这个真问题 ——
- * 能力检测恰好就是**对**的判据。
+ * **这处保留能力检测，不看宿主版本号** —— 因为它是**模块顶层导出**，loader 一 import
+ * 就求值，那时还没有 `ctx.baseUrl`；而 schemastery 是本插件的**普通依赖**，解析到的
+ * 是插件自己 node_modules 里那一份，跟宿主实际加载的版本无关。既然这里拿不到宿主
+ * 版本，就只剩「这份 Schema 实例到底有没有 `.volatile`」这个真问题 —— 能力检测
+ * 恰好就是**对**的判据。
  *
- * 定位说明（非兼容分叉）：`.volatile()` 是 schemastery 3.18.4 才有的原型方法；
- * 老版本上直写 `Schema.object({}).volatile()` 会 `.volatile` 为 undefined →
- * 抛 TypeError → **整个插件加载失败**（不只是卡片，是 dsh-router 完全挂掉）。
- *   - 有 volatile：走 volatile，空 object 不被 volatileForm 过滤 → 卡片进镜像；
- *   - 无 volatile：回落普通空 schema，不抛；此时宿主必是 0.1.5，本就靠
- *     installSection 出卡片（见下方按版本分流的注册），这个 Config 无副作用。
+ * 为什么要 `.volatile()`：空 object 会被 volatileForm 过滤掉，顶层标 volatile 才能让
+ * 卡片进镜像。`.volatile()` 是 schemastery 3.18.4 才有的原型方法，直写
+ * `Schema.object({}).volatile()` 在没有它的版本上会抛 TypeError → **整个插件加载
+ * 失败**。所以：无 volatile 就回落普通空 schema（不抛，代价是卡片不出现，并有日志）。
  */
 const emptySchema = Schema.object({})
 const hasVolatile = typeof (emptySchema as { volatile?: unknown }).volatile === 'function'
 
 /**
- * 0.1.7 的设置镜像只认「插件导出的 Config + 配置树行 id」这条收录链，且空 object
+ * 设置镜像只认「插件导出的 Config + 配置树行 id」这条收录链，且空 object
  * 会被 volatileForm 过滤掉 —— 顶层 `.volatile()` 才能让 Router 卡片出现在设置-模型。
  * Router 的真配置在自己的 state.json（路由系统面板），这里故意不暴露任何字段。
  */
@@ -132,29 +129,6 @@ interface Llm {
   registerAdapter: (providers: readonly string[], adapter: unknown) => () => void
 }
 
-/**
- * 设置服务（`ctx.settings`，dsh-settings）的最小切面。0.1.5 用 `installSection`
- * 注册命名空间；0.1.7 已移除该方法、改由插件导出的 Config 驱动 —— 故声明为可选，
- * 调用处做能力检测（不是版本分支）。dsh-settings 是宿主注入的 peer service，不深绑类型。
- */
-interface SettingsServiceFace {
-  installSection?: (
-    owner: CordisContext,
-    ns: string,
-    schema: unknown,
-    entry: unknown,
-    hooks: { setSource: (current: () => unknown) => void; onChange: () => void },
-  ) => void
-}
-
-/**
- * cordis Context 的最小切面。`installSection(owner)` 只会对 owner 调
- * `ctx.effect(...)` 并在卸载时读 `fiber.state`，所以这里只声明 `effect`。
- */
-interface CordisContext {
-  effect: (fn: () => () => void, label?: string) => unknown
-}
-
 function writeJson(res: ServerResponse, status: number, body: unknown): void {
   const payload = JSON.stringify(body)
   res.writeHead(status, {
@@ -205,12 +179,18 @@ export function apply(rawContext: unknown): void {
   const dataDir = dataDirOf(ctx.baseUrl)
   const stateFile = join(dataDir, 'state.json')
   log(`data dir: ${dataDir}`)
-  // 宿主版本探测：三处 0.1.5/0.1.7 兼容分叉共用这一个判据（徽章 / 设置命名空间 /
-  // adapter 的 tool-result 消息形态）。探测失败按老版本处理，不影响其它功能。
+  // 宿主版本：只用于**报版本**与**守地板**（不再是兼容分叉的判据，见 host-version.ts）。
+  // 低于 0.2.0 的宿主上本插件会静默走错路径，所以这里必须出声，把「插件坏了」和
+  // 「宿主太老」区分开 —— 否则用户只能对着症状猜。
   const hostVersion = detectHostVersion(ctx.baseUrl)
-  const host017Plus = isHost017Plus(ctx.baseUrl)
-  const lastHitDock = supportsLastHitDock(ctx.baseUrl)
-  log(`host version: ${hostVersion ?? '未知'} (>=0.1.7: ${host017Plus ? 'yes' : 'no'}, last-hit dock: ${lastHitDock ? 'on' : 'off'})`)
+  const hostSupported = isHostSupported(ctx.baseUrl)
+  log(`host version: ${hostVersion ?? '未知'} (>=0.2.0: ${hostSupported ? 'yes' : 'no'})`)
+  if (!hostSupported) {
+    ctx.logger.warn(
+      `[dsh-router] 宿主版本 ${hostVersion ?? '未知'} 低于本插件支持的 0.2.0 —— 插件仍会加载，` +
+      '但设置卡片、「最近命中」徽章与工具结果转发会走错路径。请把宿主升到 0.2.0 及以上。',
+    )
+  }
   const store = new SupplierConfigStore(stateFile)
   const credentials = new CredentialStore(join(dataDir, 'auths'))
   const router = new Router(stateFile, store, log)
@@ -403,10 +383,11 @@ export function apply(rawContext: unknown): void {
     const { suppliers } = router.status()
     writeJson(res, 200, {
       ok: true,
-      // 宿主版本 + 徽章支持位：客户端据此决定是否挂「最近命中」控件
-      // （composer.dock 在 0.1.5 渲染位置不对，只有 >= 0.1.7 才挂）。
+      // 宿主版本（客户端/排障用）。`lastHitDock` 是给 0.1.5→0.1.7 那个位置差异留的
+      // 能力位，0.2.0 起恒为 true —— 保留字段形状是为了不打断已有读取方，客户端
+      // 已不再依赖它做分支（见 client/index.tsx）。
       hostVersion: hostVersion ?? '',
-      lastHitDock: lastHitDock,
+      lastHitDock: true,
       suppliers: suppliers.map((s) => {
         const loaded = loadedSuppliers.find((l) => l.supplier.id === s.id)
         return {
@@ -590,21 +571,198 @@ export function apply(rawContext: unknown): void {
     writeJson(res, 200, { ok: true, requireApiKey: keys.requireApiKey })
   })
 
+
+/**
+ * 把 `router.ext` 表映射成面板要的 `ExtInfo[]`。**GET 与 PATCH 共用**。
+ *
+ * ⚠️ 2026-09-30：op 成功时我复制了一份这段映射来就地回表 —— 两份必然漂移
+ *   （改一处只生效一半，本仓反复栽的坑）⇒ 抽成函数，一处定义两处调用。
+ */
+function extInfos(table: Record<string, unknown>, isEnabled: (id: string) => boolean): ExtInfo[] {
+  // ⚠️ **必须用参数 `isEnabled`，不能抓 `extStore`**（2026-09-30 实测的卡死）：
+  //   本函数是**模块顶层**，而 `extStore` 是 `apply()` 里的局部变量
+  //   ⇒ 顶层函数引用它会 `extStore is not defined`。而这个异常发生在
+  //   启动/请求路径上被吞掉，表现是**接口一直转圈、不报错** —— 最坏的一种。
+  //   （我抽出这个函数时加了参数、却忘了把函数体里的引用换掉。）
+
+return Object.values(table as RouterExtService)
+  .map((raw): ExtInfo | undefined => {
+    const e = raw as RouterExt
+    if (!e || typeof e.id !== 'string' || e.id === '') return undefined
+    const st = typeof e.getState === 'function' ? e.getState() : { ready: false }
+    return {
+      id: e.id,
+      name: e.name ?? e.id,
+      ...(e.description !== undefined ? { description: e.description } : {}),
+      ...(e.icon !== undefined ? { icon: e.icon } : {}),
+      enabled: isEnabled(e.id),
+      ready: st?.ready === true,
+      // 随核心分发的扩展带这个标记（插件页自绘节据此不重复列它：它已经有原生行）
+      ...(raw.source === 'builtin' ? { source: 'builtin' as const } : {}),
+      // 子开关：扩展自报，核心只搬运（形状归扩展，见 ExtControl 的注释）。
+      // ⚠️ **必须过滤掉形状不对的条目**：落盘的 controls 不可信，一条
+      // `undefined` 的 title 会让面板渲染出空行且**不报错**（假绿）。
+      ...(Array.isArray(e.controls) && e.controls.length > 0
+        ? {
+            controls: e.controls
+              .filter((c): c is ExtControl =>
+                !!c && typeof c.id === 'string' && c.id !== '' && typeof c.title === 'string')
+              .map((c) => ({ id: c.id, title: c.title, on: c.on === true, ...(c.detail !== undefined ? { detail: c.detail } : {}), ...(typeof c.body === 'string' ? { body: c.body } : {}), ...(c.editable === true ? { editable: true } : {}), custom: c.custom === true, overridden: c.overridden === true })),
+          }
+        : {}),
+      ...(st?.detail !== undefined ? { detail: st.detail } : {}),
+    }
+  })
+  .filter((e): e is ExtInfo => e !== undefined)
+}
   // ---- 扩展 (Ext)：扩展器列表 + 开关 ----
   route(`${ROUTER_API_BASE}/ext`, async (req, res) => {
     if (req.method === 'PATCH') {
-      let body: { id?: unknown; enabled?: unknown }
+      // ⚠️ `on` 与 `enabled` **都声明为 unknown**：请求体不可信，真正判类型的地方
+      //   在下面（`typeof … !== 'boolean'` ⇒ 400）。这里只是让它在类型上可访问。
+      let body: { id?: unknown; enabled?: unknown; controlId?: unknown; on?: unknown; title?: unknown; body?: unknown; op?: unknown; ids?: unknown }
       try {
-        body = JSON.parse(await readBody(req, 64 << 10)) as { id?: unknown; enabled?: unknown }
+        body = JSON.parse(await readBody(req, 64 << 10)) as typeof body
       } catch {
         writeJson(res, 400, { ok: false, error: 'invalid JSON body' })
         return
       }
+      // `addedId` 只给 add 用：面板要靠它定位刚建的那条。声明放在 PATCH 顶层，
+      // 因为**成功路径会落到末尾统一响应**（op 块内声明的话末尾够不着）。
+      let addedId: string | null = null
       const ext = typeof body.id === 'string' ? exts[body.id] as RouterExtService[string] : undefined
       if (!ext) {
         writeJson(res, 404, { ok: false, error: 'extension not found' })
         return
       }
+      // ---- 子开关的四个列表级动作（`op`）----
+      //
+      // 与单条动作（开关/文本）**分开**：它们改的是**列表本身**（顺序、增、删），
+      // 不是一个字段。合在一起会让面板每次都得问"这次改的是哪一层"。
+      if (body.op !== undefined) {
+        const op = body.op
+        // ⚠️⚠️ **成功不早退**（2026-09-30 实测修的真 bug）：原来四个分支各自
+        //   `writeJson(res, 200, {ok:true}); return` —— **不回 `enhancers`**。
+        //   客户端 `act()` 靠回发的整张表刷新 ⇒ 增删改/排序之后**界面不更新**
+        //   （用户看着像没生效，刷新一下又"变了"）。
+        //   ⇒ 失败早退（400），**成功一律落到末尾**的统一响应，那里会带上新列表。
+        //   这是旧的两个分支（开关 / 文本）本来就有的行为，我加新分支时漏了。
+        //
+        if (op === 'reorder') {
+          if (!Array.isArray(body.ids)) {
+            writeJson(res, 400, { ok: false, error: 'ids must be an array' })
+            return
+          }
+          if (typeof ext.setControlOrder !== 'function' || !ext.setControlOrder(body.ids as string[])) {
+            writeJson(res, 400, { ok: false, error: '排序保存失败' })
+            return
+          }
+        } else if (op === 'remove' || op === 'reset') {
+          if (typeof body.controlId !== 'string' || body.controlId === '') {
+            writeJson(res, 400, { ok: false, error: 'controlId must be a non-empty string' })
+            return
+          }
+          const fn = op === 'remove' ? ext.removeCustomControl : ext.resetControlText
+          if (typeof fn !== 'function' || !fn.call(ext, body.controlId)) {
+            // ⚠️ **失败要说得清是哪个**：`remove` 拒的是内置条目、`reset` 拒的是
+            //   自建条目或没改过的 —— 一句 "op failed" 会让人以为是 bug。
+            writeJson(res, 400, {
+              ok: false,
+              error: op === 'remove'
+                ? '只能删除自定义准则（内置条目请用开关关掉）'
+                : '只能还原内置准则，且它得先被改过',
+            })
+            return
+          }
+        } else if (op === 'add') {
+          if (typeof ext.addCustomControl !== 'function') {
+            writeJson(res, 400, { ok: false, error: 'extension does not support custom controls' })
+            return
+          }
+          addedId = ext.addCustomControl(
+            typeof body.title === 'string' ? body.title : '',
+            typeof body.body === 'string' ? body.body : '',
+          )
+          if (addedId === null) {
+            writeJson(res, 400, { ok: false, error: '标题与内容都不能为空' })
+            return
+          }
+        } else {
+          writeJson(res, 400, { ok: false, error: `unknown op: ${String(op)}` })
+          return
+        }
+        // ✅ 成功：回整张表（与 GET 走**同一个**构造函数，不复制一份）。
+        // ⚠️ 必须带 `enhancers`：客户端 `act()` 靠它刷新；少了它，界面停在旧状态
+        //   （2026-09-30 实测：增删改/排序后看起来"没生效"，刷新一下又变了）。
+        writeJson(res, 200, addedId === null
+          ? { ok: true, enhancers: extInfos(exts, (id) => extStore.isEnabled(id)) }
+          : { ok: true, id: addedId, enhancers: extInfos(exts, (id) => extStore.isEnabled(id)) })
+        return
+        return
+      }
+
+      // ---- 子开关文本（`{ controlId, title?, body? }`）----
+      //
+      // 与下面的开关**分开判**：一个是字符串、一个是布尔，面板问的也是两个问题。
+      // 判据是**有没有带 title/body**，而不是「controlId 在不在」——后者两个
+      // 分支都会满足，分不开。
+      if (body.title !== undefined || body.body !== undefined) {
+        if (typeof body.controlId !== 'string' || body.controlId === '') {
+          writeJson(res, 400, { ok: false, error: 'controlId must be a non-empty string' })
+          return
+        }
+        if (typeof body.title !== 'undefined' && typeof body.title !== 'string') {
+          writeJson(res, 400, { ok: false, error: 'title must be a string' })
+          return
+        }
+        if (typeof body.body !== 'undefined' && typeof body.body !== 'string') {
+          writeJson(res, 400, { ok: false, error: 'body must be a string' })
+          return
+        }
+        if (typeof ext.setControlText !== 'function') {
+          writeJson(res, 400, { ok: false, error: 'extension controls are not editable' })
+          return
+        }
+        const patch: { title?: string; body?: string } = {}
+        if (typeof body.title === 'string') patch.title = body.title
+        if (typeof body.body === 'string') patch.body = body.body
+        if (!ext.setControlText(body.controlId, patch)) {
+          writeJson(res, 400, { ok: false, error: 'unknown controlId' })
+          return
+        }
+        // ✅ 成功：回整张表（下面统一出口那句够不着这里 —— 它在别的 `if` 里，
+        //    靠 `return` 出去会**不写响应** ⇒ 请求挂死、开关卡在 loading）。
+        writeJson(res, 200, { ok: true, enhancers: extInfos(exts, (id) => extStore.isEnabled(id)) })
+        return
+      }
+
+      // ---- 子开关（`{ controlId, on }`）----
+      //
+      // 与总开关**分开判**：总开关管「这个扩展在不在」，子开关管「它自己的行为细节」。
+      // 混在一个 PATCH 里会让面板多问一句「这次到底改的是哪个」—— 那是两个独立动作。
+      if (body.controlId !== undefined) {
+        if (typeof body.controlId !== 'string' || body.controlId === '') {
+          writeJson(res, 400, { ok: false, error: 'controlId must be a non-empty string' })
+          return
+        }
+        if (typeof body.on !== 'boolean') {
+          writeJson(res, 400, { ok: false, error: 'on must be a boolean' })
+          return
+        }
+        if (typeof ext.setControl !== 'function') {
+          writeJson(res, 400, { ok: false, error: 'extension has no controls' })
+          return
+        }
+        // 扩展自写（落盘形状归它，核心不代劳 —— 见 ExtControl.setControl 注释）。
+        // 写失败**如实回错**且不改盘：面板据此把开关弹回去，而不是假装成功。
+        if (!ext.setControl(body.controlId, body.on)) {
+          writeJson(res, 400, { ok: false, error: 'unknown controlId' })
+          return
+        }
+        writeJson(res, 200, { ok: true, enhancers: extInfos(exts, (id) => extStore.isEnabled(id)) })
+        return
+      }
+
       if (typeof body.enabled !== 'boolean') {
         writeJson(res, 400, { ok: false, error: 'enabled must be a boolean' })
         return
@@ -622,24 +780,11 @@ export function apply(rawContext: unknown): void {
       // 开关归核心持久化。
       extStore.setEnabled(ext.id, body.enabled)
     }
-    const list: ExtInfo[] = Object.values(exts as RouterExtService)
-      .map((raw): ExtInfo | undefined => {
-        const e = raw as RouterExt
-        if (!e || typeof e.id !== 'string' || e.id === '') return undefined
-        const st = typeof e.getState === 'function' ? e.getState() : { ready: false }
-        return {
-          id: e.id,
-          name: e.name ?? e.id,
-          ...(e.description !== undefined ? { description: e.description } : {}),
-          ...(e.icon !== undefined ? { icon: e.icon } : {}),
-          enabled: extStore.isEnabled(e.id),
-          ready: st?.ready === true,
-          // 随核心分发的扩展带这个标记（插件页自绘节据此不重复列它：它已经有原生行）
-          ...(raw.source === 'builtin' ? { source: 'builtin' as const } : {}),
-          ...(st?.detail !== undefined ? { detail: st.detail } : {}),
-        }
-      })
-      .filter((e): e is ExtInfo => e !== undefined)
+    const list: ExtInfo[] = extInfos(exts, (id) => extStore.isEnabled(id))
+    // ⚠️⚠️ **这行是 GET 的唯一出口**（2026-09-30 实测的「一直加载中」）：
+    //   上一轮我以为「成功路径统一落到末尾响应」就把它删了，结果**没有任何地方
+    //   写响应** ⇒ 请求永不结束 ⇒ 面板一直转圈。
+    //   症状极其恶劣：不报错、不 500、就挂在那儿。
     writeJson(res, 200, { ok: true, enhancers: list })
   })
 
@@ -720,32 +865,9 @@ export function apply(rawContext: unknown): void {
       // Router 的配置（组合/密钥/签到）存在 core 自己的 state.json，走插件自己的
       // 「路由系统」面板；设置-模型 这边必须让 settingsNs 在设置镜像里能解析出来
       // （见 dsh-client-ui-settings-models 的 configurable 过滤），否则卡片不出现。
-      // 按宿主版本分流（不再靠 installSection 能力检测）：
-      //   0.1.7+：镜像行来自顶部导出的 volatile Config（ns = 行 id），无需注册；
-      //   0.1.5 ：镜像行来自 settings.installSection。
-      // 空 schema = 卡片是入口/占位（该布局下不可提交），真正的配置在路由系统面板。
-      const routerSettingsSchema = Schema.object({})
-      if (isHost017Plus(ctx.baseUrl)) {
-        log(`settings section driven by exported Config (${settingsNs})`)
-      } else {
-        ctx.inject(['settings'], (sctx: unknown) => {
-          const settings = (sctx as { settings?: SettingsServiceFace }).settings
-          if (settings === undefined) {
-            log('settings service absent — skip Router settings-section registration')
-            return
-          }
-          if (settings.installSection === undefined) {
-            // 版本说该走 installSection 但它不在（异常宿主）：只记日志，不抛。
-            log(`settings.installSection absent despite 0.1.5 host (${settingsNs})`)
-            return
-          }
-          settings.installSection(rawContext as CordisContext, settingsNs, routerSettingsSchema, {}, {
-            setSource: () => {},
-            onChange: () => {},
-          })
-          log(`Router settings section registered (${settingsNs})`)
-        })
-      }
+      // 0.2.0 的镜像行来自**顶部导出的 Config**（空 object + `.volatile()`，ns = 行 id），
+      // 这里无需任何注册动作 —— 0.1.5 那条 `settings.installSection` 路径已随兼容分叉删除。
+      log(`settings section driven by exported Config (${settingsNs})`)
       // adapter：模型目录自动带出组合；对话转发到本插件 /v1（组合路由在 /v1 内完成）。
       // 带上组合的上下文窗口：没有它 dsh 的自动压缩算不出阈值、会静默关闭。
       // 图片序列化需要读附件字节：把 ctx.attachments 传给 adapter（dsh-attachment

package/src/llm/adapter.test.ts

@@ -473,17 +473,17 @@ test('wire：reasoningEffort 为 none/off 时删字段，且无请求时不硬
 test('wire：空工具结果发空串，不伪造 (no output) 字面量', async () => {
   // 模型会以为工具真打印了那句话 —— 对「bash 无输出」是误导。
   const body = await captureBody({
-    messages: [{ role: 'user', content: [{ type: 'tool-result', toolCallId: 'c1', content: [] }] }],
+    messages: [{ role: 'tool', toolCallId: 'c1', content: [] }],
   })
   const tool = (body.messages as Array<{ role: string; content: string }>).find((m) => m.role === 'tool')
   assert.equal(tool?.content, '', '空结果就该是空串')
 })
 
-// 0.1.7+ 消息模型：tool 结果是**独立 role:"tool" 消息**、toolCallId 挂消息级，
-// ContentBlockMap 已无 'tool-result' 块。必须原样发 role:"tool"，否则工具结果被
+// 0.2.0 消息模型：tool 结果是**独立 role:"tool" 消息**、toolCallId 挂消息级，
+// ContentBlockMap 里**没有** 'tool-result' 块。必须原样发 role:"tool"，否则工具结果被
 // 序列化成 role:"user"、夹在 assistant(tool_calls) 与 tool 之间，上游判定失配 → 400
-// code=11148。下面几条锁死新分支；老的 'tool-result' 块路径（≤0.1.6）仍有各自的用例。
-test('wire：0.1.7+ 独立 role:"tool" 消息序列化为 role:"tool"，正确带 tool_call_id', async () => {
+// code=11148。
+test('wire：独立 role:"tool" 消息序列化为 role:"tool"，正确带 tool_call_id', async () => {
   const body = await captureBody({
     messages: [
       { role: 'assistant', content: [{ type: 'text', text: '' }, { type: 'tool-call', id: 'c1', name: 'bash', arguments: '{}' }] },
@@ -492,13 +492,13 @@ test('wire：0.1.7+ 独立 role:"tool" 消息序列化为 role:"tool"，正确
   })
   const messages = body.messages as Array<{ role: string; tool_call_id?: string; content: unknown }>
   const tool = messages.find((m) => m.role === 'tool')
-  assert.ok(tool, '0.1.7 tool 消息必须原样发 role:"tool"')
+  assert.ok(tool, 'tool 消息必须原样发 role:"tool"')
   assert.equal(tool.tool_call_id, 'c1', 'tool_call_id 取自消息级 toolCallId')
   assert.equal(tool.content, 'out', '纯文本重组为字符串')
   assert.equal(messages.filter((m) => m.role === 'user').length, 0, '不容许被误序列化成 user 消息')
 })
 
-test('wire：0.1.7+ 独立 role:"tool" 消息不带图时不在其后插 user(图)', async () => {
+test('wire：独立 role:"tool" 消息不带图时不在其后插 user(图)', async () => {
   // 图片才攒批补 user(图)；纯文本 tool 后面绝不能冒出 user，配对接续必须完整。
   const body = await captureBody({
     messages: [
@@ -516,7 +516,7 @@ test('wire：0.1.7+ 独立 role:"tool" 消息不带图时不在其后插 user(
   }
 })
 
-test('wire：0.1.7+ 空 tool 结果发空串（不伪造字面量）', async () => {
+test('wire：空 tool 结果发空串（不伪造字面量）', async () => {
   const body = await captureBody({
     messages: [{ role: 'tool', toolCallId: 'c2', content: [] }],
   })
@@ -524,34 +524,11 @@ test('wire：0.1.7+ 空 tool 结果发空串（不伪造字面量）', async ()
   assert.equal(tool?.content, '', '空结果该是空串')
 })
 
-/**
- * tool 结果的两种形态**都必须序列化成 role:'tool'**，且分派只看消息形状、与宿主版本无关。
- *
- * 背景（实测）：同一宿主内两种形态都合法 —— 0.1.7 loop-built 走新形态
- * （独立 role:'tool' 消息），而老会话历史经 session-format 迁移/重放时仍是旧形态
- * （user 消息里的 'tool-result' 块）。所以 adapter 不能按版本号判形态对错，
- * 只能按形状分派；这条锁死两种形状在**同一份 adapter**下产物一致。
- */
-test('wire：tool-result 新/旧两种形态都序列化为 role:"tool"（按形状分派，与版本无关）', async () => {
-  const newShapeMsgs = [
-    { role: 'assistant', content: [{ type: 'text', text: '' }, { type: 'tool-call', id: 'c1', name: 'bash', arguments: '{}' }] },
-    { role: 'tool', toolCallId: 'c1', content: [{ type: 'text', text: 'out' }] },
-  ]
-  const oldShapeMsgs = [
-    { role: 'assistant', content: [{ type: 'text', text: '' }, { type: 'tool-call', id: 'c1', name: 'bash', arguments: '{}' }] },
-    { role: 'user', content: [{ type: 'tool-result', toolCallId: 'c1', content: [{ type: 'text', text: 'out' }] }] },
-  ]
-  // 新形态：原样发 role:'tool'
-  const n = await captureBody({ messages: newShapeMsgs })
-  const nt = (n.messages as Array<{ role: string; tool_call_id?: string }>).find((m) => m.role === 'tool')
-  assert.ok(nt, '新形态应发 role:"tool"')
-  assert.equal(nt.tool_call_id, 'c1')
-  // 旧形态：由 'tool-result' 块转出 role:'tool'（同样带 tool_call_id）
-  const o = await captureBody({ messages: oldShapeMsgs })
-  const ot = (o.messages as Array<{ role: string; tool_call_id?: string }>).find((m) => m.role === 'tool')
-  assert.ok(ot, '旧形态也应转出 role:"tool"')
-  assert.equal(ot.tool_call_id, 'c1')
-})
+// 这里曾有一条「tool-result 新/旧两种形态都序列化成 role:tool」的用例，随 0.1.x
+// 兼容一起删除：0.2.0 的 ContentBlockMap 里已无 'tool-result' 块，且 v3→v4 会话迁移
+// 主动拒绝该包装（老会话要么被迁移展开、要么拒绝打开），这条形态到不了 adapter。
+// 剩下的新形态已由上面「独立 role:"tool" 消息…」那条锁死。删它的理由与事实出处见
+// src/llm/adapter.ts 的对应注释与 src/host-version.ts。
 
 /**
  * 为什么要有这一条：只不发 `block-end` **并不能**拦住残缺调用。
@@ -878,8 +855,8 @@ test('wire：一步两个 read_image（每条一个 user 消息，同现场）
           { type: 'tool-call', id: 'c2', name: 'read_image', arguments: '{}' },
         ],
       },
-      { role: 'user', content: [{ type: 'tool-result', toolCallId: 'c1', content: [{ type: 'text', text: 'tree_assembly.png' }, { type: 'image', attachment: ref }] }] },
-      { role: 'user', content: [{ type: 'tool-result', toolCallId: 'c2', content: [{ type: 'text', text: 'tree_part.png' }, { type: 'image', attachment: ref }] }] },
+      { role: 'tool', toolCallId: 'c1', content: [{ type: 'text', text: 'tree_assembly.png' }, { type: 'image', attachment: ref }] },
+      { role: 'tool', toolCallId: 'c2', content: [{ type: 'text', text: 'tree_part.png' }, { type: 'image', attachment: ref }] },
     ],
   }, fakeAttachments())
   const messages = body.messages as Array<{ role: string; tool_call_id?: string; tool_calls?: Array<{ id: string }>; content: unknown }>
@@ -905,7 +882,7 @@ test('wire：一步两个 read_image（每条一个 user 消息，同现场）
 })
 
 /**
- * 为什么要有这一组：`read_image` 的结果是**带图的 tool-result**。适配器曾把
+ * 为什么要有这一组：`read_image` 的结果是**带图的 tool 消息**。适配器曾把
  * 图片和文本一起提成一条 `user` 消息、排在 `tool` 消息**之前**，于是 wire 里
  * 出现 `assistant(tool_calls) → user(image) → tool`。上游判定 tool_call 与
  * tool_result 失配，回 400 网关码 11148「tool calls and tool results do not
@@ -946,17 +923,17 @@ function assertToolPairingIntact(messages: Array<{ role: string; tool_call_id?:
   }
 }
 
-test('wire：纯文本 tool-result 不因图片逻辑改变顺序（tool 紧跟 assistant）', async () => {
+test('wire：纯文本 tool 消息不因图片逻辑改变顺序（tool 紧跟 assistant）', async () => {
   const body = await captureBodyWith({
     messages: [
       { role: 'user', content: [{ type: 'text', text: '跑一下' }] },
       { role: 'assistant', content: [{ type: 'tool-call', id: 'c1', name: 'bash', arguments: '{}' }] },
-      { role: 'user', content: [{ type: 'tool-result', toolCallId: 'c1', content: [{ type: 'text', text: 'out' }] }] },
+      { role: 'tool', toolCallId: 'c1', content: [{ type: 'text', text: 'out' }] },
     ],
   }, fakeAttachments())
   const messages = body.messages as Array<{ role: string; tool_call_id?: string; tool_calls?: Array<{ id: string }> }>
   assertToolPairingIntact(messages)
-  assert.deepEqual(messages.map((m) => m.role), ['user', 'assistant', 'tool'], '纯文本 tool 结果仍紧跟 assistant')
+  assert.deepEqual(messages.map((m) => m.role), ['user', 'assistant', 'tool'], '纯文本 tool 消息仍紧跟 assistant')
 })
 
 /* ---------------- 流空闲超时：上游停摆不能永久挂住（issue #6） ---------------- */

package/src/llm/adapter.ts

@@ -123,11 +123,10 @@ export interface RouterAdapterSource {
  * base64）。图片字节经 `resolveAttachments` 读取；读不到时回退为稳定的占位文本，
  * **绝不静默丢图**（丢图 = 模型看到一条没有图的消息却毫无提示）。
  *
- * 工具结果双模型兼容：0.1.5/0.1.6 里 tool result 是 user 消息里的 'tool-result' 块
- * （旧路径）；0.1.7+ 改成了独立 role:'tool' 消息、toolCallId 挂消息级（新分支）。
- * 两者在 wire 上统一序列化为 role:'tool'，产物一致。见主循环里的 role==='tool' 分支。
+ * 工具结果只有一种形态：独立 `role:'tool'` 消息、toolCallId 挂消息级，wire 上原样
+ * 发 `role:'tool'`。见主循环里的 `role === 'tool'` 分支。
  */
-/** tool-result 里图片挂到 user 消息时用的说明文字（与官方适配器一致）。 */
+/** tool 消息里的图片挂到 user 消息时用的说明文字（与官方适配器一致）。 */
 const TOOL_RESULT_IMAGE_TEXT = 'Tool result images'
 
 /**
@@ -144,7 +143,7 @@ const STREAM_IDLE_TIMEOUT_MS = 300_000
 async function wireMessages(options: GenerateOptions, system: string | undefined, attachments: RouterAttachmentStore | undefined, log?: (msg: string) => void): Promise<Array<Record<string, unknown>>> {
   const out: Array<Record<string, unknown>> = []
   /**
-   * 攒着「tool-result 里带出来的图片」，等这一串 tool 消息**发完**再合并成一条
+   * 攒着「tool 消息里带出来的图片」，等这一串 tool 消息**发完**再合并成一条
    * user 消息补在后面。
    *
    * 为什么必须跨消息攒、而不是各消息各发一条：harness 把**每个 tool 结果放
@@ -188,14 +187,13 @@ async function wireMessages(options: GenerateOptions, system: string | undefined
       })
       continue
     }
-    // tool 结果的消息形态：**同一宿主内两种形态都合法**，按消息实际形状分派。
-    //   新形态：独立 role:'tool' 消息、toolCallId 挂消息级（0.1.7 loop-built）；
-    //   旧形态：user 消息里的 'tool-result' 块（0.1.5/0.1.6，以及 0.1.7 下经
-    //           session-format 迁移/重放的老会话历史——实测 0.1.7 仍会出现）。
-    // 所以**不能**用宿主版本号判断形态对错（0.1.7-alpha.2 也是 0.1.7，同样会出现
-    // 旧形态）——形状才是事实，按形状分派这一份 adapter 就同时吃两版。
-    const isToolRoleMessage = (message.role as string) === 'tool'
-    if (isToolRoleMessage) {
+    // tool 结果：0.2.0 起**只有一种形态** —— 独立 role:'tool' 消息、toolCallId 挂消息级。
+    // 旧的「user 消息内嵌 'tool-result' 块」（0.1.5/0.1.6 时代，0.1.7 起退役）**不再
+    // 支持**：0.2.0 的 v3→v4 会话迁移主动拒绝 tool-result 包装
+    // （`must not contain a released tool-result wrapper`），老会话要么被迁移展开成
+    // tool 消息、要么直接拒绝打开 —— 这条形态到不了 adapter（见 host-version.ts 的
+    // 版本地板）。
+    if ((message.role as string) === 'tool') {
       // tool 消息必须紧跟 assistant(tool_calls)：中间插进任何 user 消息，上游都会判定
       // tool_call 与 tool_result 失配 → codebuddy 直接 400 网关码 11148（bad_request
       // 按核心设计不罚账号，面板上看不到异常，易误判成额度/风控）。
@@ -214,35 +212,11 @@ async function wireMessages(options: GenerateOptions, system: string | undefined
       pendingToolImages.push(...imageParts)
       continue
     }
-    // user / tool-result
-    const toolResults = message.content.filter((b) => b.type === 'tool-result')
-    // 这条消息自己的（非 tool-result 的）user 部分：文本 + 图片。
-    const ownParts = await contentParts(
-      message.content.filter((b) => b.type !== 'tool-result'),
-      attachments,
-      options.signal,
-      log,
-    )
-    // 有实质 user 内容（或压根没有 tool 结果）就先发这条 user 消息；
-    // 只有 tool 结果的「纯工具」消息不发空 user，图片留到 pending 里合并。
-    if (ownParts.length > 0 || toolResults.length === 0) {
-      flushToolImages()
-      out.push({ role: 'user', content: compactUserContent(ownParts) })
-    }
-    for (const result of toolResults) {
-      // **tool 消息必须紧跟 assistant(tool_calls)**：中间插进任何 user 消息，
-      // 上游都会判定 tool_call 与 tool_result 失配 —— codebuddy 直接 400 网关码
-      // 11148「tool calls and tool results do not match」。
-      // 图片不能放进 tool 消息（实测模型会把两张不同的图认成同一张），
-      // 也不能插在两条 tool 之间（同样 400），所以先攒起来、发完整串再补一条 user。
-      const parts = await contentParts(result.content, attachments, options.signal, log)
-      const imageParts = parts.filter((p) => p.type !== 'text')
-      const text = parts.filter((p) => p.type === 'text').map((p) => (p as { text?: string }).text ?? '').join('')
-      // 空结果就发空串，不要替换成 '(no output)' 之类的字面量 —— 模型会
-      // 以为工具真的打印了那句话（9router 也是补 content: ""）。
-      out.push({ role: 'tool', tool_call_id: result.toolCallId, content: text })
-      pendingToolImages.push(...imageParts)
-    }
+    // user：文本 + 图片。**即使内容为空也照发** —— 这条 user 消息在历史里存在过，
+    // 悄悄省掉等于让模型看到一段断掉的话轮。
+    const userParts = await contentParts(message.content, attachments, options.signal, log)
+    flushToolImages()
+    out.push({ role: 'user', content: compactUserContent(userParts) })
   }
   flushToolImages()
   return out
@@ -262,7 +236,7 @@ function compactUserContent(parts: Array<Record<string, unknown>>): string | Arr
 }
 
 /**
- * 一块 DSH user/tool-result 内容序列化成 OpenAI content parts（text + image_url）。
+ * 一条 DSH 消息的内容块序列化成 OpenAI content parts（text + image_url）。
  * 纯文本时返回空数组（上层走紧凑字符串路径）。图片转 base64 data URI；
  * attachments 缺失或读取失败时回退稳定占位文本（绝不静默丢图）。
  */
@@ -284,10 +258,9 @@ async function contentParts(
       parts.push(...(await imageParts(ref, attachments, signal, log)))
       continue
     }
-    if (block.type === 'tool-result') {
-      parts.push(...(await contentParts((block as unknown as { content: ReadonlyArray<{ type: string }> }).content, attachments, signal, log)))
-    }
-    // 其它块（reasoning/tool-call）不属于 user content，忽略
+    // 其它块（reasoning/tool-call/tool-addition/tool-removal/file）不属于发给上游的
+    // user/tool 内容，忽略。0.1.x 的 'tool-result' 块曾在这里递归展开，随 0.2.0
+    // 单面编写一并删除（该块在 0.2.0 的 ContentBlockMap 里已不存在，见主循环注释）。
   }
   return parts
 }