dsh-sidecard-ask 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 1.3.2
+
+**主题：核对并适配 DSH 桌面版（Electron，0.2.0-rc.2）。**
+
+核对结论（实测，详见 README §5.3）：
+
+- 桌面版是**独立运行形态**：Electron-as-Node 跑 `app.asar\dsh\...\dsh-desktop-host`，框架包全在 `app.asar` 内，
+  自带 node 24.18.1 + pnpm 11.7.0；`DSH_PROFILE=desktop`，与 web 版的 `profiles\web` **各自独立**；
+- 本插件在桌面 profile 中已登记（`link:D:/Users/34332/AI/dsh-sidecard-ask` + `dsh.profile.bundles`），
+  **无需改动即加载**：宿主半 `v1.3.1` 正常，客户端自检上报显示三个槽位落点正常、两个适配器均可用，
+  真机 `start→reasoning×106→delta×46→status→done`（1.89 s）通过；
+- 桌面版用的 dsh-better-sidebar 是 **0.24.1**：与 0.22.1 的消费端契约差异**纯增量**
+  （`target` 增加 `'side'`、新增可选 `preferNewPane`），本插件不传这两项 → 不受影响。
+
+**桌面特有修改：窗口拖拽区防御。** 桌面外壳把顶层元素标记为窗口拖拽区（`-webkit-app-region: drag`），
+落在其中的点击会变成拖动窗口；同生态的 dsh-better-sidebar 为此专门带了一条防御，而本插件的浮层此前没有。
+现在样式表为每个自有根节点声明 `-webkit-app-region:no-drag`（`.dsa-layer/.dsa-trigger/.dsa-pop/.dsa-stack/
+.dsa-card/.dsa-toast/.dsa-settings`），并有回归测试锁定该规则（含"该规则是真实规则而非只出现在注释里"的断言）。
+该属性在浏览器中无效，web 版不受影响。
+
+**确认无需改动的部分**：`styles.insert` / `host.call` 只属于**动态**客户端半（本插件是静态形态，官方等价做法
+就是手工插 `<style>`，宿主通信走自有 HTTP 路由）；名为 `shortcuts` 与 `conversation` 的客户端服务在运行实例中
+**都不存在**（inspection 报 `no catalogued Service`），因此快捷键与 composer 草稿保持既有实现与占位降级。
+
+自测 327 → **336 项**（verify 53 / contract 149 / smoke 134）。
+
+## 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
 
 **主题：把"客户端半的状态"变成宿主可读——补上导致前两次缺陷排查困难的观测盲点。**

package/README.md

@@ -221,6 +221,50 @@ better-sidebar 会把收到的每个 tab 描述符**镜像注册进同一个原
 
 两者共存、均 `active: true` —— 即"同 kind 冲突"已被消除，`auto` 默认走原生右侧栏，强制 `sideSurface: better-sidebar` 仍可用。
 
+### 5.3 与 DSH 桌面版（Electron）的适配核对（2026-09-30）
+
+桌面版与命令行/web 版**不是同一套运行形态**，核对结论如下。
+
+| 维度 | 事实（实测） |
+|---|---|
+| 桌面 App | `DeepSeek Harness.exe` **0.2.0-rc.2**（`resources\app-update.yml` 更新通道 `nightly`，源 `download.deepseek.com/dsh-desk/feeds/win-x64/`） |
+| 运行形态 | Electron-as-Node 跑 `app.asar\dsh\node_modules\@deepseek-ai\dsh-desktop-host\lib\index.js`；**框架包全部打包在 `app.asar` 内**（121 MB 归档，普通 shell/glob/grep 读不到，只能靠运行实例的 inspection 查） |
+| 自带运行时 | `resources\runtime\versions.json`：node **24.18.1** + pnpm **11.7.0**（装插件用的是它自带的 pnpm） |
+| profile | **`DSH_PROFILE=desktop` → `C:\Users\34332\.dsh\profiles\desktop`**，与 web 版的 `profiles\web` **互相独立**：两者各有自己的 `package.json`/`node_modules`/`dsh.profile.bundles`，插件必须分别安装 |
+| 本插件安装状态 | 桌面 profile 的 `package.json` 中为 `"dsh-sidecard-ask": "link:D:/Users/34332/AI/dsh-sidecard-ask"`，且已在 `dsh.profile.bundles` 内 → **无需改动即加载** |
+| 宿主半 | `GET http://127.0.0.1:19387/sidecard-ask/api/state` → `dsh-sidecard-ask v1.3.1`、`sideEngine=true`（provider `spawn,fork`）、`capabilities.parent` 正常、配置落点 `~/.dsh/sidecard-ask/config.json` |
+| 客户端半 | 由本插件自己的自检上报读出：`version=1.3.1`、`slots={overlay: shell.overlay, settings: settings.section, sessionProbe: conversation.input.right}`、`native.available=true`、`better.available=true` 且 `better.version=0.24.1` |
+| 端到端 | 真机 `start→reasoning×106→delta×46→status→done`，1.89 s，`done.text` 是真实答案（子代理 + 流式帧 + 只读工具白名单全部正常） |
+| 客户端服务目录 | 与 web 版**完全一致**（layout / locale / sessions / slots / theme / timer / uiWorkspace / workspaces），无桌面专属差异 |
+
+**桌面版用到的 dsh-better-sidebar 是 0.24.1**（比上轮核对的 0.22.1 新）：0.22.1 → 0.24.1 的
+`lib/types/client/service.d.ts` 差异是**纯增量**——`target?: 'right' | 'bottom'` 增加 `'side'`（右侧栏第二窗格），
+并新增可选 `preferNewPane?: boolean`；`SIDEBAR_FEATURES` 仍含 `tabMeta`，`dsh.client.inject` 未变。
+本插件不传这两个字段 → **不受影响**（默认落点行为未变）。
+
+**桌面版特有的适配修改（1.3.2）：窗口拖拽区。** 桌面外壳会把顶层元素标记为窗口拖拽区
+（`-webkit-app-region: drag`），落在拖拽区内的点击会**变成拖动窗口**而不是点中 UI。同生态的
+dsh-better-sidebar 为此专门带了一条防御（`html[data-platform] body>[data-dsh-better-sidebar]{-webkit-app-region:initial}`
++ `[data-dsh-panel-host]>*{-webkit-app-region:no-drag}`）。本插件的浮层此前**没有这条防御**，现已在样式表里为
+每个自有根节点声明 `-webkit-app-region:no-drag`
+（`.dsa-layer/.dsa-trigger/.dsa-pop/.dsa-stack/.dsa-card/.dsa-toast/.dsa-settings`），并加回归测试锁定该规则。
+该属性在浏览器里无效，不影响 web 版。
+
+**桌面形态下确认「不需要改」的两点**：
+
+- `styles.insert` / `host.call` 属于**动态运行时**的插件能力（inspection 的 `Builtin` 定义就是
+  "Plain-JavaScript symbols available to a **dynamic** Client half"）。本插件是**静态**客户端半
+  （`__ModuleLoader__.load` + `require('react')`），官方形态就是手工插入 `<style>`——同为静态形态的
+  `uiskin-theme` 在源码里注明 "the static twin of the dynamic runner's `styles.insert`"；宿主通信走自有的
+  `/sidecard-ask/api` 路由；
+- 名为 `shortcuts` 与 `conversation` 的客户端服务**都不在运行实例的服务目录里**（inspection 明确报
+  `no catalogued Service named ...`）。所以"并入宿主快捷键注册表"与"使用 composer 草稿服务"两条路都不存在：
+  本插件继续自带 keydown 监听（快捷键可配置）与 `PLACEHOLDER: composer-draft` 降级路径。
+
+**仍未验证的部分（如实记录）**：桌面窗口内的**视觉与点击行为**（本工作区无 GUI 自动化，无法点按验证）；
+`Alt+Q` 是否会撞上桌面 App 的菜单加速键（Electron 的菜单加速键由菜单先处理，页面的 keydown 可能收不到；
+若冲突，在设置页改成 `Ctrl+Alt+Q` 之类即可）；Electron 下 `navigator.clipboard` 的写入权限（已有"选中文本"降级兜底）。
+
 ---
 
 ## 六、未知 DSH API：占位接口与替换方式
@@ -396,7 +440,7 @@ node test/smoke-test.mjs      # 端到端：流式/截断/取消/持久化/失
 ```
 
 三个脚本都以 `process.exitCode` 反映结果，失败会列出具体条目；测试会把 `DSH_HOME` 指向临时目录，不会污染真实配置。
-当前规模：verify 53 项 + contract 135 项 + smoke 134 项 = **322 项全部通过**。
+当前规模：verify 53 项 + contract 149 项 + smoke 134 项 = **336 项全部通过**。
 
 ### 10.2 版本能力探测（§7 矩阵的来源）
 
@@ -447,6 +491,10 @@ $tmp = Join-Path $env:TEMP 'probe.json'
 `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

@@ -47,7 +47,7 @@ window.__ModuleLoader__.load({
      * 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'
+    const CLIENT_VERSION = '1.3.2'
 
     /**
      * Tab kind served by the DSH native right rail (also its implementation id).
@@ -948,6 +948,23 @@ 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.
      *
@@ -1015,6 +1032,17 @@ window.__ModuleLoader__.load({
 
     /** Theme-token-only stylesheet. Every class is prefixed `dsa-`. */
     const CSS_TEXT = `
+/* Desktop (Electron) window-drag guard.
+   The DSH desktop shell marks top-level elements as window-drag regions
+   (\`-webkit-app-region: drag\`), and a click landing inside such a region MOVES
+   THE WINDOW instead of reaching the UI — which would make the floating trigger,
+   the question popover and the cards unclickable in the desktop app. A
+   descendant of a drag region must opt out explicitly; dsh-better-sidebar ships
+   exactly this guard for its own host
+   (\`html[data-platform] body>[data-dsh-better-sidebar]{-webkit-app-region:initial}\`
+   plus \`[data-dsh-panel-host]>*{-webkit-app-region:no-drag}\`).
+   Every surface we draw declares it. The property is inert in a browser. */
+.dsa-layer,.dsa-trigger,.dsa-pop,.dsa-stack,.dsa-card,.dsa-toast,.dsa-settings{-webkit-app-region:no-drag}
 .dsa-layer{pointer-events:none;position:relative;z-index:60}
 .dsa-trigger{pointer-events:auto;position:fixed;display:flex;align-items:center;gap:4px;
   padding:4px 8px;border-radius:8px;border:1px solid var(--dsw-alias-border-l2, rgba(127,127,127,.35));
@@ -2164,14 +2192,23 @@ 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.
+         * 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)
@@ -2456,6 +2493,7 @@ window.__ModuleLoader__.load({
           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.3.0'
+export const PLUGIN_VERSION = '1.3.2'
 
 /** Route prefix of the plugin's own API. */
 export const ROUTE_PREFIX = '/sidecard-ask/api'

package/package.json

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