dsh-sidecard-ask 1.2.1 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.3.1
+
+**主题：让"两半代际不一致"成为一个被处理的状态，而不是噪声。**
+
+这个插件的宿主半只在**重启 DSH** 时更新，客户端半在**页面加载**时更新，所以"新客户端 + 旧宿主"是结构性常态
+（当前本机就是这个状态：页面已跑到 1.3.x，宿主仍是重启前的 1.2.0）。
+
+- 客户端在自检上报被宿主以 `not-found`（该路由还不存在，旧宿主）、`bad-response`（SPA 兜底返回 HTML）
+  或 `unreachable` 拒绝时，**记住"此宿主不支持自检"并停止重试**，只打一条 info 说明"重启 DSH 后生效"；
+  其它错误（例如配置类真实错误）仍按 warning 记录，不会错误地关闭通道。
+- 新增纯函数 `isDiagnosticsUnsupported(error)` 并纳入契约测试（5 条断言覆盖各错误码）。
+
+自测 322 → **327 项**（verify 53 / contract 140 / smoke 134）。
+
+## 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 的适配性，并修掉由此暴露的一个真实缺陷。**

package/README.md

@@ -212,6 +212,15 @@ better-sidebar 会把收到的每个 tab 描述符**镜像注册进同一个原
 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：占位接口与替换方式
@@ -237,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: <名字>` 注释 + 可运行的降级路径，替换时只需改该函数的实现，调用方（卡片、设置页）无需改动。
 
@@ -382,7 +396,7 @@ node test/smoke-test.mjs      # 端到端：流式/截断/取消/持久化/失
 ```
 
 三个脚本都以 `process.exitCode` 反映结果，失败会列出具体条目；测试会把 `DSH_HOME` 指向临时目录，不会污染真实配置。
-当前规模：verify 53 项 + contract 118 项 + smoke 118 项 = **289 项全部通过**。
+当前规模：verify 53 项 + contract 140 项 + smoke 134 项 = **327 项全部通过**。
 
 ### 10.2 版本能力探测（§7 矩阵的来源）
 
@@ -409,8 +423,34 @@ $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 冲突正是靠这类信息才定位到的。
+
+> **两半代际不一致是常态**：宿主半只在重启 DSH 时更新，客户端半在页面加载时更新。
+> 所以"新客户端 + 旧宿主"很常见——此时 `/diagnose` 还不存在，客户端会**识别这一点、只提示一次并停止重试**
+> （`not-found` / SPA 兜底 HTML / 不可达三类失败），不会每次加载都刷警告。
+
 **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()` 都是**在真实宿主上跑通的**，

package/client.js

@@ -42,6 +42,13 @@ window.__ModuleLoader__.load({
       settings: 'sidecard-ask-settings',
       sessionProbe: 'sidecard-ask-session-probe',
     }
+    /**
+     * 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.1'
+
     /**
      * Tab kind served by the DSH native right rail (also its implementation id).
      */
@@ -941,6 +948,58 @@ window.__ModuleLoader__.load({
      */
     let capturedComposerActions = null
 
+    /**
+     * Whether `POST /diagnose` is worth calling on this host generation.
+     *
+     * The two halves update independently — the Host half only on a DSH
+     * restart, the Client half on a page load — so a page can easily run a
+     * NEWER Client against an older Host that has no `/diagnose` route. The
+     * first refusal turns the channel off for this page instead of retrying
+     * (and warning) on every report.
+     *
+     * @param {unknown} error - the thrown wire error.
+     * @returns {boolean} true when the failure means "this host lacks the route".
+     */
+    function isDiagnosticsUnsupported(error) {
+      const code = error?.code
+      return code === 'not-found' || code === 'bad-response' || code === 'unreachable'
+    }
+
+    /**
+     * 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
@@ -1743,6 +1802,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
@@ -1757,6 +1817,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)
               }
@@ -2118,10 +2179,35 @@ 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, and a
+         * host too old to have the route is remembered so the channel is not
+         * retried for the rest of the page's life.
+         */
+        let reportTimer = null
+        let diagnosticsSupported = true
+        const scheduleReport = (delay = 600) => {
+          if (!diagnosticsSupported) return
+          if (reportTimer !== null) clearTimeout(reportTimer)
+          reportTimer = setTimeout(() => {
+            reportTimer = null
+            void postJson('diagnose', buildClientReport(store.state)).catch((error) => {
+              if (isDiagnosticsUnsupported(error)) {
+                diagnosticsSupported = false
+                console.info(`[${PLUGIN_ID}] 宿主半尚不支持自检上报（宿主半比客户端旧，重启 DSH 后生效）`)
+                return
+              }
+              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(
@@ -2340,12 +2426,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,
@@ -2373,7 +2463,7 @@ window.__ModuleLoader__.load({
        * `window` and exercises these without a browser.
        */
       api: Object.freeze({
-        version: '1.2.1',
+        version: CLIENT_VERSION,
         /** Read-only state accessor for diagnostics and the test harness. */
         snapshot: () => store.state,
         pure: Object.freeze({
@@ -2391,6 +2481,8 @@ window.__ModuleLoader__.load({
           selectionSignature,
           composeMainPrompt,
           askInMainConversation,
+          buildClientReport,
+          isDiagnosticsUnsupported,
           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.1'
+export const PLUGIN_VERSION = '1.3.1'
 
 /** 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.1",
+  "version": "1.3.1",
   "description": "DSH 划词追问（侧边卡片作答）：在聊天区与任务区选中文本就地追问，答案由独立子代理在侧边卡片里流式呈现，也可选择落回主对话。",
   "type": "module",
   "main": "index.js",