dsh-sidecard-ask 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 1.3.0
+
+**主题：把"客户端半的状态"变成宿主可读——补上导致前两次缺陷排查困难的观测盲点。**
+
+- 新增 **`POST /sidecard-ask/api/diagnose`**：客户端半在启动、槽位落点变化、承载面回退时把一份受限摘要
+  （客户端版本、当前承载面、区域锚点是否可用、三个槽位的真实落点、两个适配器的可用性与失败原因、
+  侧边卡片插件的版本与能力列表）上报给宿主；`GET /state` 的 **`value.client`** 即可读到。
+  宿主对上报做**白名单 + 截断**（未知键丢弃、字符串 ≤200 字符、能力列表 ≤40 项、槽位 ≤8 项）。
+- 客户端版本改为单一常量 `CLIENT_VERSION`：自检上报与 `api.version` 同源，报告不会声称一个页面其实没在跑的版本。
+- 此前两次客户端静默失效（原生 tab 类型因 kind 冲突从未注册；客户端产物是上一代）都只能靠人工翻阅
+  槽位清单才发现，这条通道把它们变成一条命令就能查到的事实。
+
+**同时复核 1.2.1 的修复在运行实例上生效**：`sidebar.right.pane.tab` 的占用者现在**同时**包含
+`sidecard-ask:card`（本插件原生右侧栏）与 `dsh-better-sidebar:sidecard-ask:card:workbench`（better-sidebar 镜像），
+两者均 active——kind 冲突已消除。
+
+自测 295 → **322 项**（verify 53 / contract 135 / smoke 134），新增用例覆盖上报的接收、白名单裁剪、
+截断、非法体拒绝，以及客户端上报体的构造。
+
+## 1.2.1
+
+**主题：核对 DSH 0.2.0-rc.1 的适配性，并修掉由此暴露的一个真实缺陷。**
+
+核对（本机运行中的就是 0.2.0-rc.1，`@deepseek-ai/dsh` 的 `next` 通道）：
+
+- 包内容层面：`node tools/compat-probe.mjs 0.1.7-rc.2 0.2.0-rc.1` → 16 项能力**逐项一致**，没有任何依赖被移除或改名；
+- 运行实例上：宿主半 `v1.2.0` 正常（`sideEngine`、provider `spawn,fork`、`capabilities.parent` 均可用）；
+  客户端半在 `shell.overlay` / `conversation.input.right` 都已注册；`standardProps` 仍含 `sessionId` 与 `inputActions`；
+  真机端到端作答 `start→delta×31→status→done`（1.36 s）通过。新增的 `sessions.fork`/`uiWorkspace.forkSession`
+  可选参数 `onCreated` 是纯增量，不影响既有调用。
+
+**修掉的缺陷**：`sidebar.right.pane.tab` 的运行清单里只有 `dsh-better-sidebar:sidecard-ask:card`，
+没有本插件原生右侧栏的 `sidecard-ask:card`——两个适配器用了同一个 tab kind，而 better-sidebar 会把每个 tab 描述符
+镜像注册进**同一个**原生注册表（band `extension`），该注册表对同 band 同 kind 的二次注册抛错，后注册的一方静默失败。
+
+- better-sidebar 承载面改用独立类型 `sidecard-ask:card:workbench`（`CARD_KIND_BETTER`），两端不再重叠；
+- `contract-test` 新增"surface kinds must not collide"一节：**在测试里模拟该注册表的重复 kind 抛错规则**
+  与 better-sidebar 的镜像注册行为，若两者再共用 kind，测试立即失败；
+- 设置页自检行改为同时报告**两个适配器**（原先原生适配器的错误在界面上不可见，只能靠翻槽位清单发现）。
+
+自测 289 → **295 项**（verify 53 / contract 124 / smoke 118）。
+
 ## 1.2.0
 
 **主题：核对并加固与 dsh-better-sidebar 0.22.1 的适配。**

package/README.md

@@ -183,6 +183,44 @@ plugin_manager(action="install_bundle", target="D:\\Users\\34332\\AI\\dsh-sideca
 
 > 注意：`version` 是加载到浏览器里的那份模块报告的版本。页面刷新后即可用它确认"跑的是不是 0.22.1"。
 
+### 5.2 与 DSH 0.2.0-rc.1 的适配核对（2026-09-29）
+
+本机实际运行的就是 **0.2.0-rc.1**（`@deepseek-ai/dsh` 的 `next` 通道；`latest` 仍是 0.1.7-rc.2）。核对分两层：
+
+**① 包内容层面**（`node tools/compat-probe.mjs 0.1.7-rc.2 0.2.0-rc.1`）：
+16 项能力**逐项与 0.1.7-rc.2 完全一致**——`shell.overlay`、`conversation.input.right`、`settings.section`、
+`data-slot` 锚点、原生右侧栏、`sessions.using/retain`、归档门、`agent/assistant-stream`、子代理、`tools.schemas`、
+`webServer` 路由……全部 ✅。
+
+**② 在运行中的实例上实测**：
+
+| 检查 | 结果 |
+|---|---|
+| 宿主半是否加载 | ✅ `/sidecard-ask/api/state` 返回 `dsh-sidecard-ask v1.2.0`，`sideEngine=true`（provider `spawn,fork`）、`capabilities.parent` 正常 |
+| 客户端半是否注册 | ✅ `shell.overlay` 有 `sidecard-ask`（order 45、active）、`conversation.input.right` 有 `sidecard-ask-session-probe`、`settings.section` 有设置页 |
+| 依赖的槽位与标准 prop | ✅ `conversation.input.right` 仍是 list/session，`standardProps` 仍含 **`sessionId`** 与 **`inputActions`** |
+| 依赖的客户端服务 | ✅ `sessions`（`retain`/`using`/`scope`）、`slots`、`locale`、`layout`、`theme` 全在；`sessions.fork`/`uiWorkspace.forkSession` 只是**新增**了可选 `onCreated`，不影响既有调用 |
+| 端到端作答 | ✅ 真机 `start→delta×31→status→done`（1.36 s，`streamSource=frames`），只读工具白名单照常生效 |
+
+**③ 由此发现并修掉的真实缺陷（1.2.1）**：运行中的 `sidebar.right.pane.tab` 清单里只有
+`dsh-better-sidebar:sidecard-ask:card`，**没有我的原生 `sidecard-ask:card`**。原因是两个适配器用了**同一个 tab kind**：
+better-sidebar 会把收到的每个 tab 描述符**镜像注册进同一个原生注册表**（`sidebarRightTabs.register`，band `extension`），
+而该注册表对*同 band 同 kind 的二次注册直接抛错*（源码注释：*"Everything else colliding on a kind throws"*）——
+后注册的那一方就此失败，而且**在界面上不可见**。修法：
+
+1. better-sidebar 承载面改用独立类型 **`sidecard-ask:card:workbench`**，两端 kind 不再重叠；
+2. `contract-test` **模拟该注册表的"重复 kind 抛错"规则**，此类冲突今后会直接让测试失败；
+3. 设置页自检行改为**同时报告两个适配器**的状态（此前原生适配器的错误压根看不到）。
+
+**④ 修复后的运行实例复核（2026-09-29，1.3.0）**：`sidebar.right.pane.tab` 的占用者现在**同时**包含
+
+| key | 来源 |
+|---|---|
+| `sidecard-ask:card` | 本插件的**原生右侧栏**承载面（1.2.1 之前完全缺失） |
+| `dsh-better-sidebar:sidecard-ask:card:workbench` | 经 dsh-better-sidebar 镜像注册的承载面（独立 kind） |
+
+两者共存、均 `active: true` —— 即"同 kind 冲突"已被消除，`auto` 默认走原生右侧栏，强制 `sideSurface: better-sidebar` 仍可用。
+
 ---
 
 ## 六、未知 DSH API：占位接口与替换方式
@@ -208,8 +246,13 @@ ctx.inject(['sidebarRightTabs', 'sidebarRight'], (injected) => { ... })
 - **占位 1（草稿降级）**：`ctx.get('conversation').input.for(scope)` → `{ state.getSnapshot().draft, setDraft(text) }`。
   这是**未出现在服务目录里**的接口（属 harness 内部形态），所以只作为第二顺位降级；搜索 `PLACEHOLDER: composer-draft`。
 - **占位 2（最后兜底）**：前两者都不可用时，插件抛出可读错误并提示用户复制文本，搜索 `PLACEHOLDER: clipboard-fallback`。
-- **线协议**：客户端与宿主半之间是插件**自有的** `/sidecard-ask/api`（`GET /state`、`POST /ask|cancel|config|reset`），
+- **线协议**：客户端与宿主半之间是插件**自有的** `/sidecard-ask/api`（`GET /state`、`POST /ask|cancel|config|reset|diagnose`），
   不依赖任何 harness 内部 RPC；若未来 harness 提供正式的同进程 RPC，替换点就是 `client.js` §3 的 `postJson/streamAsk`。
+- **`POST /diagnose`（客户端自检上报）**：宿主**看不到浏览器里的客户端半**，所以客户端在启动、槽位落点变化、
+  承载面回退时把自己的一份受限摘要（版本、承载面、区域锚点、槽位落点、两个适配器的可用性与原因、侧边卡片插件版本与能力）
+  POST 给宿主；随后 `GET /state` 的 `value.client` 就能读到它。宿主侧对上报做**白名单 + 长度截断**（未知键丢弃、
+  字符串截断到 200 字符、能力列表最多 40 项），所以页面即使被注入垃圾也不会污染状态面。
+  这条通道是在两次"客户端静默失效只能靠人工翻槽位清单才发现"之后补上的。
 
 > 约定：所有占位点都写成 `PLACEHOLDER: <名字>` 注释 + 可运行的降级路径，替换时只需改该函数的实现，调用方（卡片、设置页）无需改动。
 
@@ -353,7 +396,7 @@ node test/smoke-test.mjs      # 端到端：流式/截断/取消/持久化/失
 ```
 
 三个脚本都以 `process.exitCode` 反映结果，失败会列出具体条目；测试会把 `DSH_HOME` 指向临时目录，不会污染真实配置。
-当前规模：verify 53 项 + contract 105 项 + smoke 118 项 = **276 项全部通过**。
+当前规模：verify 53 项 + contract 135 项 + smoke 134 项 = **322 项全部通过**。
 
 ### 10.2 版本能力探测（§7 矩阵的来源）
 
@@ -380,8 +423,30 @@ $tmp = Join-Path $env:TEMP 'probe.json'
 [System.IO.File]::WriteAllText($tmp, $body, (New-Object System.Text.UTF8Encoding($false)))
 (Invoke-WebRequest http://127.0.0.1:8080/sidecard-ask/api/ask -Method POST `
    -ContentType 'application/json; charset=utf-8' -InFile $tmp -TimeoutSec 240 -UseBasicParsing).Content
+
+# 3) 客户端半的真实状态（浏览器跑的那份代码/槽位落点/两个适配器）
+#    页面加载后 GET /state，看 value.client —— 这是唯一能从页面外读到客户端状态的通道
+((Invoke-WebRequest http://127.0.0.1:8080/sidecard-ask/api/state -UseBasicParsing).Content | ConvertFrom-Json).value.client
+```
+
+**客户端状态样例**（1.3.0 起）：
+
+```json
+{
+  "at": 1790555771338,
+  "version": "1.3.0",
+  "surface": "native-rightbar",
+  "zoneAnchors": true,
+  "sessionKnown": true,
+  "slots": { "overlay": "shell.overlay", "settings": "settings.section", "sessionProbe": "conversation.input.right" },
+  "native": { "available": true },
+  "better": { "available": true, "version": "0.22.1", "features": ["badge", "…", "tabMeta"] }
+}
 ```
 
+`native.reason` / `better.reason` 会写明**为什么**某个承载面不可用（例如 `no-tab-meta` 或注册表的报错原文）——
+1.2.1 修掉的那个 tab kind 冲突正是靠这类信息才定位到的。
+
 **2026-09-28 在 DSH 0.1.7-rc.2 上的实测结果**（`provider=spawn`、`sideTools=readonly`）：
 `start x1 → reasoning x181 → delta x90 → status x1 → done x1`，耗时 2.6 s，`done.text` 为真实模型答案。
 这条记录同时说明：子代理启动、只读工具白名单（与真实工具表求交后）、流式帧桥接、SSE 线协议、运行结束后的 `dispose()` 都是**在真实宿主上跑通的**，
@@ -471,5 +536,5 @@ npm deprecate "<旧包名>@*" "Renamed to <新包名> - <原因>"       # 旧名
    本仓库当前文件比运行中的宿主模块新（1.0.1 的「归档父会话不再一刀切 / 持久化 chunk 流式源 / 能力门控 / 路由降级」），
    **重启后**这些改动才生效；`/state` 的 `version` 与 `capabilities.parent` 字段可以直接确认是否已加载新版。
 6. **除 0.1.7-rc.2 外，其余版本只做了产物层验证**：见 §7.3——插件在 0.1.2-rc.1 … 0.1.6-alpha.2 上安装启动过**没有**得到验证，
-   验证到的是"这些版本缺哪些 API + 插件对每个缺失都有分支"，分支本身由 276 项自测覆盖。
+   验证到的是"这些版本缺哪些 API + 插件对每个缺失都有分支"，分支本身由 289 项自测覆盖。
 

package/client.js

@@ -42,9 +42,34 @@ window.__ModuleLoader__.load({
       settings: 'sidecard-ask-settings',
       sessionProbe: 'sidecard-ask-session-probe',
     }
-    /** Side-card tab type registered in a side-card host. */
+    /**
+     * Version of this Client half. Single source of truth: the self-report to
+     * the Host and the module's `api.version` both read it, so a report can
+     * never claim a generation the browser is not actually running.
+     */
+    const CLIENT_VERSION = '1.3.0'
+
+    /**
+     * Tab kind served by the DSH native right rail (also its implementation id).
+     */
     const CARD_KIND = 'sidecard-ask:card'
 
+    /**
+     * Tab type served by the dsh-better-sidebar plugin.
+     *
+     * It MUST differ from {@link CARD_KIND}: better-sidebar mirrors every tab
+     * descriptor it is given into the SAME native registry
+     * (`sidebarRightTabs.register`, id `dsh-better-sidebar:<id>`, band
+     * `extension`), and that registry THROWS when a kind already has a
+     * registration in the same band ("Everything else colliding on a kind
+     * throws"). Sharing one kind made the two adapters collide: whichever
+     * registered second failed — observed live on 0.2.0-rc.1, where the pane
+     * listed `dsh-better-sidebar:sidecard-ask:card` and no native
+     * `sidecard-ask:card` at all. `test/contract-test.mjs` now emulates that
+     * registry rule so the collision cannot come back.
+     */
+    const CARD_KIND_BETTER = 'sidecard-ask:card:workbench'
+
     /**
      * Client-side mirror of the Host `DEFAULT_CONFIG`. The client needs values
      * before `/state` answers (first paint) and when the Host is unreachable;
@@ -170,6 +195,7 @@ window.__ModuleLoader__.load({
         diagSidecard: '侧边卡片插件（dsh-better-sidebar）',
         diagFeatures: '项能力',
         diagNoTabMeta: '版本过旧：没有 tabMeta 能力，已跳过它改用其它承载面',
+        diagNativeKind: 'kind',
         toolGuardUnavailable: '该 provider 不支持工具白名单，本次作答继承了当前会话的工具',
         toolGuardInherited: '按配置继承当前会话的工具',
         diagUnreachable: '宿主接口不可达：{msg}',
@@ -272,6 +298,7 @@ window.__ModuleLoader__.load({
         diagSidecard: 'Side-card plugin (dsh-better-sidebar)',
         diagFeatures: 'capabilities',
         diagNoTabMeta: 'too old: no tabMeta capability, skipped in favour of another surface',
+        diagNativeKind: 'kind',
         toolGuardUnavailable: 'This provider supports no tool allow-list, so the answer inherited the session tools',
         toolGuardInherited: 'Inherits the session tools, as configured',
         diagUnreachable: 'Host API unreachable: {msg}',
@@ -889,20 +916,20 @@ window.__ModuleLoader__.load({
         },
         open(card) {
           if (!this.available() || typeof this.service.openTab !== 'function') return false
-          const tabId = `${CARD_KIND}:${card.id}`
+          const tabId = `${CARD_KIND_BETTER}:${card.id}`
           // `meta` is the transport for the card id (feature `tabMeta`), and
           // `dedupeKey` on our descriptor is what collapses repeat opens onto
           // the same tab; both are part of the stable consumer contract
           // (`lib/types/client/service.d.ts`, unchanged across 0.22.0 → 0.22.1).
           this.service.openTab(
-            { type: CARD_KIND, id: tabId, title: card.question.slice(0, 32), meta: { cardId: card.id } },
+            { type: CARD_KIND_BETTER, id: tabId, title: card.question.slice(0, 32), meta: { cardId: card.id } },
             store.state.sessionId === null ? undefined : { sessionId: store.state.sessionId },
           )
           return true
         },
         close(card) {
           if (!this.available() || typeof this.service.closeTab !== 'function') return false
-          this.service.closeTab(`${CARD_KIND}:${card.id}`)
+          this.service.closeTab(`${CARD_KIND_BETTER}:${card.id}`)
           return true
         },
       },
@@ -921,6 +948,41 @@ window.__ModuleLoader__.load({
      */
     let capturedComposerActions = null
 
+    /**
+     * What this Client half wants the Host to know about its own state.
+     *
+     * The Host cannot inspect a browser-side plugin, so this report is what
+     * makes a silent CLIENT-side failure visible from outside the page
+     * (`GET /sidecard-ask/api/state` → `value.client`). It was added after two
+     * such failures were only diagnosable by hand-inspecting the live slot
+     * inventory: a native tab type that never registered, and a client build
+     * that was still the previous generation.
+     *
+     * @param {object} state - `store.state`.
+     * @returns {object} the report body (allow-listed again on the Host).
+     */
+    function buildClientReport(state) {
+      return {
+        // Read from the module's own version constant so the report can never
+        // claim a generation the browser is not actually running.
+        version: CLIENT_VERSION,
+        surface: state.surface,
+        zoneAnchors: state.zoneAnchors,
+        sessionKnown: typeof state.sessionId === 'string' && state.sessionId !== '',
+        slots: { ...state.slots },
+        native: {
+          available: surfaces.native.available(),
+          ...(surfaces.native.error === null ? {} : { reason: String(surfaces.native.error) }),
+        },
+        better: {
+          available: surfaces.better.available(),
+          ...(surfaces.better.version === null ? {} : { version: surfaces.better.version }),
+          ...(surfaces.better.reason === null ? {} : { reason: String(surfaces.better.reason) }),
+          features: surfaces.better.features,
+        },
+      }
+    }
+
     /**
      * The card id an external host is CURRENTLY rendering. `CardHost` sets it
      * on mount and clears it on unmount, which is what turns "the adapter
@@ -1554,7 +1616,7 @@ window.__ModuleLoader__.load({
                 h('div', { key: 'slots' }, `${t('diagSlots')}: ${Object.entries(state.slots).map(([k, v]) => `${k}=${v}`).join(' · ')}`),
                 // The side-card plugin's own report: which version is loaded and
                 // whether it advertises the capability this adapter needs.
-                h('div', { key: 'sidecard' }, `${t('diagSidecard')}: ${describeSidecardAdapter()}`),
+                h('div', { key: 'sidecard' }, `${t('diagSidecard')}: ${describeSurfaces()}`),
                 h('div', { key: 'path' }, `${t('settingsTitle')} → ${diag.provenance?.persistedPath ?? ''}`),
               ])
           : null)
@@ -1582,10 +1644,22 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * One line describing how the optional side-card plugin resolved, for the
-     * settings page's capability check. Reported from the plugin's OWN
-     * `version`/`features` fields, so the answer is what is running, not what
-     * package.json claims.
+     * One line describing how each optional side-card surface resolved, for the
+     * settings page's capability check. Both adapters are reported, because a
+     * failing NATIVE registration was previously invisible here (it only showed
+     * up as a missing entry in the pane's own slot inventory).
+     * @returns {string} human-readable state.
+     */
+    function describeSurfaces() {
+      const native = surfaces.native.available()
+        ? `${t('yes')} · ${t('diagNativeKind')}=${CARD_KIND}`
+        : `${t('no')}${surfaces.native.error === null ? '' : `（${surfaces.native.error}）`}`
+      return `${t('surfaceNative')}: ${native} ／ ${t('surfaceBetter')}: ${describeSidecardAdapter()}`
+    }
+
+    /**
+     * The optional side-card plugin's own report: which version is loaded and
+     * whether it advertises the capability this adapter needs.
      * @returns {string} human-readable state.
      */
     function describeSidecardAdapter() {
@@ -1711,6 +1785,7 @@ window.__ModuleLoader__.load({
               if (!opened) {
                 store.set({ surface: 'flow' })
                 patchCard(card.id, { surface: 'flow' })
+                scheduleReport(0)
               } else {
                 // Render proof: an adapter that accepts the open but never
                 // mounts our body would leave an empty tab. Unless the card is
@@ -1725,6 +1800,7 @@ window.__ModuleLoader__.load({
                   store.set({ surface: 'flow', surfaceNote: t('surfaceUnproven') })
                   patchCard(card.id, { surface: 'flow' })
                   toast(t('surfaceUnproven'))
+                  scheduleReport(0)
                 }, 600)
                 pendingProofs.add(proof)
               }
@@ -2086,10 +2162,26 @@ window.__ModuleLoader__.load({
           }
         }
 
+        /**
+         * Debounced self-report to the Host. Diagnostics are best-effort: a
+         * failure is logged and never surfaces as a user-visible error.
+         */
+        let reportTimer = null
+        const scheduleReport = (delay = 600) => {
+          if (reportTimer !== null) clearTimeout(reportTimer)
+          reportTimer = setTimeout(() => {
+            reportTimer = null
+            void postJson('diagnose', buildClientReport(store.state)).catch((error) => {
+              console.warn(`[${PLUGIN_ID}] 自检上报失败（不影响功能）：`, error?.message ?? error)
+            })
+          }, delay)
+        }
+
         /** Record which rung a registration actually landed on. */
         const noteSlot = (name, key) => {
           const slots = { ...(store.state.slots ?? {}), [name]: key }
           store.set({ slots })
+          scheduleReport()
         }
 
         disposers.push(firstLiveSlot(
@@ -2245,7 +2337,11 @@ window.__ModuleLoader__.load({
                 return
               }
               const off = service.registerTab({
-                id: CARD_KIND,
+                // A DIFFERENT type from the native rail's: better-sidebar mirrors
+                // this descriptor into `sidebarRightTabs` as an `extension`-band
+                // registration, and a second registration of the same kind in
+                // that band throws (see CARD_KIND_BETTER).
+                id: CARD_KIND_BETTER,
                 title: () => t('answerTitle'),
                 description: () => t('settingsDesc'),
                 order: 120,
@@ -2304,12 +2400,16 @@ window.__ModuleLoader__.load({
 
         // ── boot ─────────────────────────────────────────────────────────
         void refreshState().catch(() => { /* the settings page shows the failure */ })
+        // One report after the slot ladders have had time to settle, so the
+        // Host ends up holding the CLIENT's real registration state.
+        scheduleReport(2500)
         disposers.push(() => {
           for (const controller of controllers.values()) controller.abort()
           controllers.clear()
           for (const proof of pendingProofs) clearTimeout(proof)
           pendingProofs.clear()
           if (toastTimer !== null) clearTimeout(toastTimer)
+          if (reportTimer !== null) clearTimeout(reportTimer)
           store.set({
             trigger: null,
             popover: null,
@@ -2337,13 +2437,14 @@ window.__ModuleLoader__.load({
        * `window` and exercises these without a browser.
        */
       api: Object.freeze({
-        version: '1.2.0',
+        version: CLIENT_VERSION,
         /** Read-only state accessor for diagnostics and the test harness. */
         snapshot: () => store.state,
         pure: Object.freeze({
           CLIENT_DEFAULTS,
           IDS,
           CARD_KIND,
+          CARD_KIND_BETTER,
           parseSseBlock,
           truncateSelection,
           parseShortcut,
@@ -2354,6 +2455,7 @@ window.__ModuleLoader__.load({
           selectionSignature,
           composeMainPrompt,
           askInMainConversation,
+          buildClientReport,
           renderRichText,
           pickSurface,
           dict: DICT,

package/index.js

@@ -42,7 +42,7 @@ export const name = 'dsh-sidecard-ask'
 export const inject = ['webServer']
 
 /** Version of this plugin (kept in step with package.json by test/verify.mjs). */
-export const PLUGIN_VERSION = '1.2.0'
+export const PLUGIN_VERSION = '1.3.0'
 
 /** Route prefix of the plugin's own API. */
 export const ROUTE_PREFIX = '/sidecard-ask/api'
@@ -1047,6 +1047,58 @@ export function apply(ctx, patchConfig) {
   const engine = createSideEngine(ctx, configOf)
   ctx.effect(() => () => { engine.dispose() }, 'sidecard-ask: side engine')
 
+  /**
+   * The Client half's own status report, or null before the first one.
+   *
+   * This exists because the Client runs in a browser this plugin cannot
+   * inspect: without it, a broken CLIENT-side registration (for example two
+   * adapters colliding on one tab kind, or a slot that never went live) is
+   * invisible from the Host — it only shows up as a missing entry deep in a
+   * slot inventory. The Client posts a bounded, allow-listed summary after its
+   * registration ladders settle; `/state` hands it back.
+   */
+  let clientReport = null
+
+  /** Allow-listed, size-bounded view of one Client report. */
+  function sanitizeClientReport(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
+    const short = (value, limit = 200) => (typeof value === 'string' ? value.slice(0, limit) : undefined)
+    const flag = value => (typeof value === 'boolean' ? value : undefined)
+    const out = {
+      at: Date.now(),
+      version: short(raw.version, 40),
+      surface: short(raw.surface, 40),
+      zoneAnchors: flag(raw.zoneAnchors),
+      sessionKnown: flag(raw.sessionKnown),
+      slots: {},
+      native: {},
+      better: {},
+    }
+    if (raw.slots !== null && typeof raw.slots === 'object' && !Array.isArray(raw.slots)) {
+      for (const [slot, key] of Object.entries(raw.slots).slice(0, 8)) {
+        const name = short(slot, 40)
+        const value = short(key, 80)
+        if (name !== undefined && value !== undefined) out.slots[name] = value
+      }
+    }
+    for (const [target, source] of [['native', raw.native], ['better', raw.better]]) {
+      if (source === null || typeof source !== 'object' || Array.isArray(source)) continue
+      const available = flag(source.available)
+      if (available !== undefined) out[target].available = available
+      const version = short(source.version, 40)
+      if (version !== undefined) out[target].version = version
+      const reason = short(source.reason ?? source.error, 200)
+      if (reason !== undefined && reason !== '') out[target].reason = reason
+      if (Array.isArray(source.features)) {
+        out[target].features = source.features
+          .filter(feature => typeof feature === 'string')
+          .slice(0, 40)
+          .map(feature => feature.slice(0, 40))
+      }
+    }
+    return out
+  }
+
   /** Whether the request may reach the plugin routes. */
   const trustedHostsOf = () => {
     const runtime = ctx.get('webRuntime')
@@ -1074,9 +1126,35 @@ export function apply(ctx, patchConfig) {
         // Informational: which process-local stream the host bridges.
         streamSource: 'agent/assistant-stream',
       },
+      // The Client half's last self-report (null until it posts one).
+      client: clientReport,
     })
   }
 
+  /**
+   * `/diagnose` — the Client half reports its own registration state.
+   *
+   * A browser-side plugin cannot be inspected from the Host, so this is the
+   * only channel that turns "the card silently fell back" or "the native tab
+   * never registered" into something readable from outside the page.
+   */
+  const handleDiagnose = async (req, res) => {
+    let body
+    try {
+      body = await readJsonBody(req)
+    } catch (error) {
+      writeError(res, 400, toWireError(error, 'bad-request').code, toWireError(error).message)
+      return
+    }
+    const report = sanitizeClientReport(body)
+    if (report === null) {
+      writeError(res, 400, 'bad-request', '诊断上报必须是对象')
+      return
+    }
+    clientReport = report
+    writeOk(res, { accepted: true, at: report.at })
+  }
+
   /** `/ask` — one SSE stream per side answer. */
   const handleAsk = async (req, res) => {
     let body
@@ -1164,7 +1242,7 @@ export function apply(ctx, patchConfig) {
    * The HTTP methods the plugin serves; kept in one place because the route
    * registration has two shapes (see below).
    */
-  const API_METHODS = ['state', 'ask', 'cancel', 'config', 'reset']
+  const API_METHODS = ['state', 'ask', 'cancel', 'config', 'reset', 'diagnose']
 
   /** One request → one response; the dispatcher owns path parsing and the fence. */
   const routeHandler = async (req, res) => {
@@ -1197,6 +1275,7 @@ export function apply(ctx, patchConfig) {
       else if (method === 'cancel') await handleCancel(req, res)
       else if (method === 'config') await handleConfig(req, res)
       else if (method === 'reset') handleReset(req, res)
+      else if (method === 'diagnose') await handleDiagnose(req, res)
       else writeError(res, 404, 'not-found', `未知接口 "${method}"`)
     } catch (error) {
       const wire = toWireError(error)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-sidecard-ask",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "DSH 划词追问（侧边卡片作答）：在聊天区与任务区选中文本就地追问，答案由独立子代理在侧边卡片里流式呈现，也可选择落回主对话。",
   "type": "module",
   "main": "index.js",