dsh-sidecard-ask 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.2.0
+
+**主题：核对并加固与 dsh-better-sidebar 0.22.1 的适配。**
+
+核对方式（可复现）：把 0.22.0 与 0.22.1 的发布产物都拉下来解包，逐文件 SHA256 比对。结论：
+
+- 消费端契约 `lib/types/client/service.d.ts` **除 `SIDEBAR_SERVICE_VERSION` 常量外逐字节相同**；
+  `SIDEBAR_FEATURES`、`dsh.client.inject`、peer 依赖均未变；
+- 0.22.1 唯一的大体量改动是它**自己** `src/client/native/index.ts` 的健壮性修复（`disposeSafely` +
+  槽位注册失败时回滚已注册的 tab 类型），不涉及本插件调用的任何字段；
+- 本插件用到的 `registerTab / openTab(seed, scope) / closeTab / features / version` 全部仍在。
+
+即 **0.22.1 下无需改动即兼容**。据此做了三处加固：
+
+1. **按能力而非版本判断**：适配器仅在 `features` 含 `tabMeta` 时可用（该能力自 better-sidebar 0.12 起提供，
+   更早的版本会打开一个读不到 `meta.cardId` 的空 tab）；不满足时 `auto` 跳到原生右侧栏/内置浮层，
+   并在自检里给出 `no-tab-meta`。
+2. **原生承载面注册回滚**：先注册 tab 类型再注册槽位，槽位注册抛错时释放已占用的类型 id
+   （正是 0.22.1 在自己原生胶水里修的同类问题，否则该 kind 会永久占用、渲染宿主"无实现"的空面）。
+3. **运行时可见**：设置页「运行自检」新增一行，显示侧边卡片插件**自己报告的 `version` 与能力项数**，
+   以及本插件对它的判定（可用 / 版本过旧 / 未检测到）。
+
+自测 276 → **289 项**（verify 53 / contract 118 / smoke 118），新增用例覆盖：0.22.1 形状的服务被接受、
+`openTab(seed, scope)` 的字段与作用域、缺 `tabMeta` 时被拒绝并落到浮层、缺 `registerTab` 时被拒绝、
+槽位注册失败时类型被释放且适配器转为不可用。
+
 ## 1.1.0
 
 **改名：`dsh-selection-followup` → `dsh-sidecard-ask`**（显示名「划词追问」→「侧边卡片追问」）。

package/README.md

@@ -152,14 +152,37 @@ plugin_manager(action="install_bundle", target="D:\\Users\\34332\\AI\\dsh-sideca
 
 | 顺序 | 承载面 | 依赖 | 失败时 |
 |---|---|---|---|
-| 1 | DSH 原生右侧栏 | `ctx.sidebarRightTabs`（注册 tab 类型）+ `ctx.sidebarRight`（`openTab`），并占用槽位 `sidebar.right.pane.tab` / `…tab.title` | 记 `surfaces.native.error`，落到下一层 |
-| 2 | **dsh-better-sidebar**（侧边卡片插件） | 客户端服务 `ctx.betterSidebar`：`registerTab` + `openTab(seed, scope)`；卡片 id 走 `tab.meta.cardId`（依赖其 `features` 含 `tabMeta`） | 同上 |
+| 1 | DSH 原生右侧栏 | `ctx.sidebarRightTabs`（注册 tab 类型）+ `ctx.sidebarRight`（`openTab`），并占用槽位 `sidebar.right.pane.tab` / `…tab.title` | 记 `surfaces.native.error`，落到下一层；**类型注册会回滚**（见下） |
+| 2 | **dsh-better-sidebar**（侧边卡片插件） | 客户端服务 `ctx.betterSidebar`：`registerTab` + `openTab(seed, scope)`；卡片 id 走 `tab.meta.cardId`，因此**要求其 `features` 含 `tabMeta`** | 同上（缺 `tabMeta` 时记 `no-tab-meta` 并跳过，而不是开一个空 tab） |
 | 3 | **内置浮层卡片**（默认兜底） | 只需要 `shell.overlay` 槽位 | ——（这是保底面，永远可用） |
 
 - 装了 `dsh-better-sidebar`：卡片以它的 tab 形式出现在它的面板里，关闭卡片会同时 `closeTab`，不残留空 tab。
 - 没装：自动使用内置浮层卡片（右下角卡片栈），功能完全一致——**这条路径是本插件的默认与保底路径**。
 - 强制指定了一个不可用的承载面：回退到内置浮层，并在卡片上标注「已回退」。
 
+### 5.1 与 dsh-better-sidebar 0.22.1 的适配核对（2026-09-28）
+
+做法：把 0.22.0 与 0.22.1 的发布产物都拉下来、解包、逐文件比对（`npm pack` + SHA256）。
+
+| 检查项 | 结果 |
+|---|---|
+| 消费端契约 `lib/types/client/service.d.ts` | **除 `SIDEBAR_SERVICE_VERSION` 常量外逐字节相同** → `BetterSidebarService` 的方法/参数/返回类型没变 |
+| `SIDEBAR_FEATURES`（能力清单） | **未变**（`tabMeta` 等仍在；契约承诺"Features are never removed"） |
+| `dsh.client.inject` / peer 依赖 | 未变（仍是 locale / ui-slots / ui-conversation / ui-sidebar-right / client-modules） |
+| `src/client/native/index.ts`（0.22.1 唯一大体量改动） | 是它**自己原生胶水的健壮性修复**：`disposeSafely` + 槽位注册失败时回滚已注册的 tab 类型；不涉及我们调用的任何字段 |
+| 本插件实际用到的面 | `registerTab({id,title,description,order,dedupeKey,component})`、`openTab({type,id,title,meta},{sessionId})`、`closeTab(id)`、`features`、`version` —— 全部仍在 |
+
+**因此 0.22.1 下适配为「无需改动即兼容」**；本轮据此做了三处加固：
+
+1. **能力门控而非版本判断**：适配器只在 `features` 含 `tabMeta` 时可用（0.12 起才有，旧版会开出空 tab）；
+   不满足时 `auto` 直接跳到原生右侧栏/内置浮层，设置页自检里写明原因（`no-tab-meta`）。
+2. **原生承载面类型注册回滚**：先注册 tab 类型、再注册槽位；槽位注册抛错（reload/teardown 期的失活 context）时
+   **释放已占用的类型 id**——这正是 0.22.1 在自己原生胶水里修的同一类问题（否则该 kind 会永久占用并显示宿主"没有实现"的空面）。
+3. **运行时可见**：设置页「运行自检」新增一行，直接显示**侧边卡片插件自己的 `version` 与能力项数**，
+   以及本插件对它的判定（可用 / 版本过旧 / 未检测到），不再依赖 package.json 的声明。
+
+> 注意：`version` 是加载到浏览器里的那份模块报告的版本。页面刷新后即可用它确认"跑的是不是 0.22.1"。
+
 ---
 
 ## 六、未知 DSH API：占位接口与替换方式
@@ -410,14 +433,27 @@ Host: ctx.subagents.start('spawn')
 ## 十三、发布流程
 
 ```powershell
-npm whoami                 # 先确认登录态（改过 2FA/密码会让旧 token 失效）
+npm whoami                     # 先确认登录态；本机用的是 granular Publish token
 node test/verify.mjs; node test/contract-test.mjs; node test/smoke-test.mjs
-npm publish --access public
+npm publish --access public    # 1.0.1 那次被 npm 暂存（staged）后才转正；再遇到可用 --otp=<验证码>
+git push origin main           # 仓库：https://github.com/HERO476/dsh-sidecard-ask
+```
+
+改名/迁移时的额外两步（1.1.0 实际做过）：
+
+```powershell
+plugin_manager(action="remove_bundle", target="<旧包名>")      # 卸旧 bundle（同时移除 profile 里的 link）
+plugin_manager(action="install_bundle", target="D:\...\<新目录>")
+npm deprecate "<旧包名>@*" "Renamed to <新包名> - <原因>"       # 旧名指路，避免别人再装到废弃名
 ```
 
 版本号同时出现在三处，必须一致：`package.json` 的 `version`、`index.js` 的 `PLUGIN_VERSION`、`client.js` 的 `api.version`
 （`test/verify.mjs` 会断言前两处；第三处在契约测试中同样被断言）。
 
+**发布前必查"地址类信息"**（1.0.0 的教训）：包名不能只查 npm —— 还要查 GitHub 仓库名是否已被占用，以及
+[`awesome-dsh-plugin` 收录索引](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/tree/main/data/plugins)
+里是否已有同名插件（本插件第一次改名就是因为漏查了后者）。
+
 ---
 
 ## 十四、已知限制（含未在本机验证的部分）

package/client.js

@@ -167,6 +167,9 @@ window.__ModuleLoader__.load({
         diagZones: '区域锚点（data-slot）',
         diagZonesMissing: '缺失，区域过滤已停用',
         diagSlots: '槽位落点',
+        diagSidecard: '侧边卡片插件（dsh-better-sidebar）',
+        diagFeatures: '项能力',
+        diagNoTabMeta: '版本过旧：没有 tabMeta 能力，已跳过它改用其它承载面',
         toolGuardUnavailable: '该 provider 不支持工具白名单，本次作答继承了当前会话的工具',
         toolGuardInherited: '按配置继承当前会话的工具',
         diagUnreachable: '宿主接口不可达：{msg}',
@@ -266,6 +269,9 @@ window.__ModuleLoader__.load({
         diagZones: 'Zone anchors (data-slot)',
         diagZonesMissing: 'missing — region filtering disabled',
         diagSlots: 'Slot landing',
+        diagSidecard: 'Side-card plugin (dsh-better-sidebar)',
+        diagFeatures: 'capabilities',
+        diagNoTabMeta: 'too old: no tabMeta capability, skipped in favour of another surface',
         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}',
@@ -859,12 +865,35 @@ window.__ModuleLoader__.load({
         error: null,
         dispose: null,
         features: [],
+        /**
+         * Why this adapter is (not) usable, in the settings page's own words.
+         * `null` means "usable"; a string explains the refusal.
+         */
+        reason: 'not-detected',
+        /**
+         * Reported by the plugin itself (`BetterSidebarService.version`), so the
+         * settings page can say which side-card plugin version is really in use.
+         */
+        version: null,
+        /**
+         * Usable only when the service advertises the `tabMeta` capability: the
+         * card id travels in `tab.meta`, and `SIDEBAR_FEATURES` has listed
+         * `tabMeta` since v0.12.0 with newer versions only ever ADDING features
+         * ("Features are never removed"). A pre-0.12 instance would open an
+         * empty tab, so it is skipped and the ladder continues to the native
+         * right rail or the built-in flow card instead.
+         */
         available() {
-          return this.service !== null && this.error === null
+          if (this.service === null || this.error !== null) return false
+          return Array.isArray(this.features) && this.features.includes('tabMeta')
         },
         open(card) {
           if (!this.available() || typeof this.service.openTab !== 'function') return false
           const tabId = `${CARD_KIND}:${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 } },
             store.state.sessionId === null ? undefined : { sessionId: store.state.sessionId },
@@ -1523,6 +1552,9 @@ window.__ModuleLoader__.load({
                 h('div', { key: 'session' }, `${t('diagSession')}: ${state.sessionId ?? t('none')}`),
                 h('div', { key: 'zones' }, `${t('diagZones')}: ${state.zoneAnchors === false ? t('diagZonesMissing') : t('yes')}`),
                 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: 'path' }, `${t('settingsTitle')} → ${diag.provenance?.persistedPath ?? ''}`),
               ])
           : null)
@@ -1549,6 +1581,27 @@ window.__ModuleLoader__.load({
       return capturedComposerActions === null ? null : { actions: capturedComposerActions }
     }
 
+    /**
+     * 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.
+     * @returns {string} human-readable state.
+     */
+    function describeSidecardAdapter() {
+      const better = surfaces.better
+      if (better.error !== null) return `${t('no')}（${better.error}）`
+      if (better.version === null && better.service === null) return t('none')
+      const version = better.version ?? '?'
+      if (better.available()) {
+        return `v${version} · ${better.features.length} ${t('diagFeatures')} · ${t('yes')}`
+      }
+      if (better.reason === 'no-tab-meta') {
+        return `v${version} · ${t('diagNoTabMeta')}`
+      }
+      return `v${version} · ${better.reason ?? t('no')}`
+    }
+
     // ─────────────────────────────────────────────────────────────────────
     // §10 plugin face
     // ─────────────────────────────────────────────────────────────────────
@@ -2099,6 +2152,18 @@ window.__ModuleLoader__.load({
               if (registry === null || registry === undefined) return
               surfaces.native.registry = registry
               surfaces.native.controller = controller ?? null
+              // Register the tab TYPE first, then its body/title slots — and
+              // roll the type back if a slot refuses to register.
+              //
+              // The host takes the id the moment `register` returns and refuses
+              // a second registration of the same id; a slot registration that
+              // throws (an already-inactive context during a reload/disposal)
+              // would then leave the kind taken for the rest of the page's life,
+              // rendering the host's "nothing can view this" face forever. This
+              // mirrors what dsh-better-sidebar 0.22.1 fixed in its own native
+              // glue (`disposeSafely` + partial-set release in
+              // `src/client/native/index.ts`).
+              let releaseType = null
               if (typeof registry.register === 'function') {
                 const off = registry.register({
                   id: CARD_KIND,
@@ -2111,20 +2176,40 @@ window.__ModuleLoader__.load({
                     description: () => t('settingsDesc'),
                   }],
                 })
-                surfaces.native.dispose = typeof off === 'function' ? off : null
+                releaseType = typeof off === 'function' ? off : null
+                surfaces.native.dispose = releaseType
+              }
+              const slotDisposers = []
+              try {
+                slotDisposers.push(ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register({
+                  name: 'sidebar.right.pane.tab',
+                  key: CARD_KIND,
+                  inject: sessionId => ({ sessionId }),
+                }, (props) => h(CardHost, { props, actions }))))
+                slotDisposers.push(ctx.slots.inject('sidebar.right.pane.tab.title', () => ctx.slots.register({
+                  name: 'sidebar.right.pane.tab.title',
+                  key: CARD_KIND,
+                }, () => h('span', null, t('answerTitle')))))
+              } catch (error) {
+                for (const dispose of slotDisposers) {
+                  try {
+                    dispose()
+                  } catch { /* releasing must not mask the failure */ }
+                }
+                if (releaseType !== null) {
+                  try {
+                    releaseType()
+                  } catch { /* releasing must not mask the failure */ }
+                  surfaces.native.dispose = null
+                }
+                surfaces.native.registry = null
+                surfaces.native.controller = null
+                throw error
               }
-              const offBody = ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register({
-                name: 'sidebar.right.pane.tab',
-                key: CARD_KIND,
-                inject: sessionId => ({ sessionId }),
-              }, (props) => h(CardHost, { props, actions })))
-              const offTitle = ctx.slots.inject('sidebar.right.pane.tab.title', () => ctx.slots.register({
-                name: 'sidebar.right.pane.tab.title',
-                key: CARD_KIND,
-              }, () => h('span', null, t('answerTitle'))))
               disposers.push(() => {
-                try { offBody() } catch { /* already disposed */ }
-                try { offTitle() } catch { /* already disposed */ }
+                for (const dispose of slotDisposers) {
+                  try { dispose() } catch { /* already disposed */ }
+                }
                 try { surfaces.native.dispose?.() } catch { /* already disposed */ }
               })
             } catch (error) {
@@ -2137,9 +2222,15 @@ window.__ModuleLoader__.load({
         }
 
         // The dsh-better-sidebar plugin, when installed: its client service
-        // registers a tab type and opens one per card. `features.tabMeta`
-        // gates the meta-carried card id, so an older version of that plugin
-        // degrades to the built-in flow card instead of showing an empty tab.
+        // registers a tab type and opens one per card.
+        //
+        // Verified against the published consumer contract: between 0.22.0 and
+        // 0.22.1 `lib/types/client/service.d.ts` is byte-identical apart from the
+        // version constant, and 0.22.1's `src/client/native/index.ts` changes are
+        // robustness fixes in ITS own native glue — no field we use changed. The
+        // `features` array is the forward-compatible half of that contract
+        // ("Features are never removed"), so the adapter gates on `tabMeta`
+        // instead of on a version number.
         try {
           ctx.inject(['betterSidebar'], (injected) => {
             try {
@@ -2147,7 +2238,12 @@ window.__ModuleLoader__.load({
               if (service === null || service === undefined) return
               const features = Array.isArray(service.features) ? service.features : []
               surfaces.better.features = features
-              if (typeof service.registerTab !== 'function') return
+              surfaces.better.version = typeof service.version === 'string' ? service.version : null
+              surfaces.better.reason = features.includes('tabMeta') ? null : 'no-tab-meta'
+              if (typeof service.registerTab !== 'function') {
+                surfaces.better.reason = 'no-register-tab'
+                return
+              }
               const off = service.registerTab({
                 id: CARD_KIND,
                 title: () => t('answerTitle'),
@@ -2241,7 +2337,7 @@ window.__ModuleLoader__.load({
        * `window` and exercises these without a browser.
        */
       api: Object.freeze({
-        version: '1.1.0',
+        version: '1.2.0',
         /** Read-only state accessor for diagnostics and the test harness. */
         snapshot: () => store.state,
         pure: Object.freeze({

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.1.0'
+export const PLUGIN_VERSION = '1.2.0'
 
 /** 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.1.0",
+  "version": "1.2.0",
   "description": "DSH 划词追问（侧边卡片作答）：在聊天区与任务区选中文本就地追问，答案由独立子代理在侧边卡片里流式呈现，也可选择落回主对话。",
   "type": "module",
   "main": "index.js",