dsh-workspace-api-key 0.2.0 → 0.2.1

package/README.md

@@ -32,6 +32,7 @@ Host half (`lib/index.js`):
 - derives a stable ref per level — `DEEPSEEK_API_KEY_WS_<first 16 hex chars of sha1(normalized path), upper-cased>` for a workspace and `DEEPSEEK_API_KEY_SS_<first 16 hex chars of sha1(session id), upper-cased>` for a session (a session id contains `-` and cannot be a ref name) — writes the key through the credentials service, and serves that ref's value;
 - rewrites only refs a provider actually reads: the default ref, every adapter's configured `apiKeyEnv`, and its own generated refs. Every other ref passes through untouched;
 - builds the session list from the `sessionController` service (`list()`), so the panel shows the same titles and model projections the sidebar does, and degrades to per-workspace only when that service is absent;
+- reports its own version and a session probe (`available`, `count`, `withoutCwd`, `samples`, `error`, plus sample workspace paths) in `/wsk-api/state`, so the panel can say *why* no sessions are listed: a stale host half (only a page reload instead of an app restart), a missing `sessionController`, a throwing `list()`, or a `cwd` that matches no workspace path;
 - keeps its own bookkeeping (which level maps to which ref, invalid flags, the provider a key was recorded for) in `$DSH_HOME/storages/dsh-workspace-api-key.json`;
 - observes failures through the `agent/request-error` waterfall without ever returning `{kind: 'retry'}` — it only records the verdict and calls `next()`.
 
@@ -41,7 +42,7 @@ The browser half (`lib/client.js`) registers into the `sidebar.panellist` slot (
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| GET | `/wsk-api/state` | default ref status, workspaces with their sessions, overrides, invalid flags |
+| GET | `/wsk-api/state` | default ref status, workspaces with their sessions, overrides, invalid flags, plugin version and session probe |
 | GET | `/wsk-api/resolve` | which level and ref the current session resolves to right now |
 | GET | `/wsk-api/check` | `?sessionId=…&path=…` — read-only verdict for one session: effective level, key, stale flag, provider mismatch, `needsAttention` |
 | POST | `/wsk-api/set` | `{scope: 'workspace' \| 'session', path \| sessionId, title, key, provider?}` binds a key; `{useDefault: true}` or an empty key clears it |
@@ -70,8 +71,8 @@ Then add `"dsh-workspace-api-key"` to `dsh.profile.bundles` in that profile's `p
 ## Tests
 
 ```sh
-node test/host.test.mjs     # 94 assertions
-node test/client.test.mjs   # 94 assertions
+node test/host.test.mjs     # 111 assertions
+node test/client.test.mjs   # 106 assertions
 ```
 
 Neither suite needs a running DSH process. The host suite drives `apply()` against a mock context (fake `credentials`, `workspaceRegistry`, `agents`, `sessionController`, `webServer`, stubbed `fetch`) and covers ref derivation, the session → workspace → default cascade, workspace matching, redirecting a second adapter's `apiKeyEnv`, clearing back to the default, 401/402/429/5xx classification, the loopback and origin checks, and state persistence. The client suite loads `lib/client.js` through a minimal `window.__ModuleLoader__` plus a small React runtime, renders the panel and the overlay, and asserts slot registration, the first render, session expand/collapse, per-session saving and testing, the ungrouped-directory card, the stale and mismatch prompts, the "go configure" hand-off, graceful degradation without a session list, and back-navigation when `ctx.get('layout')` only becomes available after the plugin was applied.
@@ -85,6 +86,7 @@ Neither suite needs a running DSH process. The host suite drives `apply()` again
 - Keys are stored through the credentials service in `$DSH_HOME/.credentials.yaml` under `refs:`, in plaintext, exactly like the default key. They are not written into session logs, the plugin's state file, or the plugin directory.
 - Matching is textual after normalization. If a session's `cwd` is a symlink or junction to a registered workspace path, it will not match and the level above is used.
 - Uninstalling the plugin leaves the generated `*_WS_*` / `*_SS_*` refs in the credentials file; remove them from the Models page.
+- If the panel lists workspaces but no expandable sessions, read the diagnostics line at the bottom of the panel. A red "the host half is still an older version" banner means the DSH process was never restarted: the host half is loaded once at startup, so closing the window or reloading the page is not enough — fully quit DSH Desktop and open it again. Otherwise the diagnostics line shows how many sessions the host sees and, when none of them match, sample session `cwd` values next to sample workspace paths.
 
 ## License
 

package/README.zh.md

@@ -32,6 +32,7 @@ DSH 只从一个全局凭据 ref（默认 `DEEPSEEK_API_KEY`）解析 DeepSeek k
 - 由每一层派生出稳定的 ref —— 工作区是 `DEEPSEEK_API_KEY_WS_<sha1(规范化路径) 前 16 位十六进制大写>`，会话是 `DEEPSEEK_API_KEY_SS_<sha1(会话 id) 前 16 位十六进制大写>`（会话 id 含 `-`，不能直接当 ref 名）——通过凭据服务写入 key，并返回这个 ref 的值；
 - 只改写 provider 真正会读的 ref：默认 ref、每个适配器配置的 `apiKeyEnv`，以及插件自己生成的 ref；其它 ref 原样透传；
 - 会话列表来自 `sessionController` 服务（`list()`），所以面板显示的标题与模型投影和侧栏一致；该服务缺失时自动降级为只能按工作区配置；
+- `/wsk-api/state` 会带上插件自身版本与会话探针（`available`、`count`、`withoutCwd`、`samples`、`error`，以及工作区路径样本），面板据此说明**为什么**没有列出会话：宿主半边是旧版本（只刷新了页面而没重启应用）、没有 `sessionController`、`list()` 抛错，还是会话的 `cwd` 与任何工作区路径都对不上；
 - 自己的账本（哪一层对应哪个 ref、失效标记、key 是给哪个服务商记的）落在 `$DSH_HOME/storages/dsh-workspace-api-key.json`；
 - 通过 `agent/request-error` waterfall 观察失败，但**从不**返回 `{kind: 'retry'}`——只记录判定结果并 `next()` 放行。
 
@@ -70,8 +71,8 @@ pnpm add "dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key"
 ## 测试
 
 ```sh
-node test/host.test.mjs     # 94 条断言
-node test/client.test.mjs   # 94 条断言
+node test/host.test.mjs     # 111 条断言
+node test/client.test.mjs   # 106 条断言
 ```
 
 两个套件都不需要启动 DSH。宿主套件用一个假 ctx（假的 `credentials`、`workspaceRegistry`、`agents`、`sessionController`、`webServer`，以及打桩的 `fetch`）驱动 `apply()`，覆盖 ref 派生、会话→工作区→默认的级联、工作区匹配、把第二个适配器的 `apiKeyEnv` 一起重定向、清回默认、401/402/429/5xx 的判定、回环与来源校验、状态落盘。浏览器套件通过一个极小的 `window.__ModuleLoader__` 与自制 React 运行时加载 `lib/client.js`，渲染出面板与覆盖层，断言槽注册、首屏渲染、会话折叠/展开、会话级保存与测试、未分组目录卡片、失效与不匹配提醒、「去配置」的交接、没有会话列表时的降级，以及 `ctx.get('layout')` 在插件 apply 之后才可用时返回键仍然有效。
@@ -85,6 +86,7 @@ node test/client.test.mjs   # 94 条断言
 - key 通过凭据服务存放在 `$DSH_HOME/.credentials.yaml` 的 `refs:` 里，明文，和默认 key 完全一样。它不会被写进会话日志、插件状态文件或插件目录。
 - 匹配是规范化之后的文本比较。如果某个会话的 `cwd` 是指向已注册工作区路径的符号链接或 junction，则匹配不上，会走上层层级。
 - 卸载插件不会删除已生成的 `*_WS_*` / `*_SS_*` ref，可在「设置 → 模型」里清掉。
+- 如果面板列出了工作区却没有可展开的会话，请看面板底部的诊断行。出现红色「宿主端插件还是旧版本」横幅，说明 DSH 进程没有重启过：宿主半边只在启动时加载，关窗口和刷新页面都不算——请完全退出 DSH Desktop 再打开。其余情况诊断行会写明宿主看到多少个会话；一个都对不上时，还会并排给出会话 `cwd` 样本与工作区路径样本，便于比对。
 
 ## 许可
 

package/lib/client.js

@@ -68,6 +68,7 @@ window.__ModuleLoader__.load({
   background: transparent; color: inherit; font: inherit; font-size: 12px; }
 .wsk-input:focus { outline: 2px solid color-mix(in srgb, #2563eb 45%, transparent); outline-offset: -1px; }
 .wsk-hint { color: var(--wsk-dim); font-size: 11px; line-height: 1.6; }
+.wsk-diag { color: var(--wsk-dim); font-size: 10px; line-height: 1.6; margin-top: 4px; word-break: break-all; }
 .wsk-msg { padding: 7px 10px; border-radius: 6px; font-size: 12px; line-height: 1.5; }
 .wsk-msg.ok { background: color-mix(in srgb, var(--wsk-ok) 12%, transparent); color: var(--wsk-ok); }
 .wsk-msg.bad { background: color-mix(in srgb, var(--wsk-bad) 12%, transparent); color: var(--wsk-bad); }
@@ -424,6 +425,42 @@ window.__ModuleLoader__.load({
       const defaultRef = state?.defaultRef
       const providers = state?.providers ?? []
 
+      // ── 诊断 ──────────────────────────────────────────────────────────────
+      // 面板里「看不到可展开的会话」有两个完全不同的原因，修法也不同：
+      //   1) 宿主半边还是旧版本（只刷新了页面 / 没重启应用）→ 响应里没有 storeVersion；
+      //   2) 宿主是新版本，但会话列表服务不可用或返回 0 行 → 看 sessionProbe。
+      // 这里把两者都显式画出来，用户截一张图就能定位。
+      const probe = state?.sessionProbe
+      const hostIsStale = state !== null && state.storeVersion === undefined
+      const sessionTotal = [...grouped, ...ungrouped].reduce(
+        (sum, ws) => sum + (Array.isArray(ws.sessions) ? ws.sessions.length : 0), 0)
+
+      const diagText = () => {
+        if (state === null) return undefined
+        const hostVersion = typeof state.pluginVersion === 'string'
+          ? state.pluginVersion
+          : '旧版（未重启应用）'
+        const sessions = probe === undefined
+          ? '未知'
+          : probe.available !== true
+            ? '不可用'
+            : `${probe.count} 个`
+        const listError = probe?.error !== undefined ? ` · list 报错：${probe.error}` : ''
+        const noCwd = probe?.withoutCwd > 0 ? ` · ${probe.withoutCwd} 个没有 cwd` : ''
+        return `插件 v${hostVersion} · 状态存储 v${state.storeVersion ?? '—'} · 会话列表：${sessions}${listError}${noCwd}`
+          + ` · 工作区 ${grouped.length} + 未分组 ${ungrouped.length} · 挂在目录下的会话 ${sessionTotal}`
+      }
+
+      const diagSamples = () => {
+        if (state === null || probe === undefined) return null
+        const cwds = Array.isArray(probe.samples) ? probe.samples : []
+        const paths = Array.isArray(state.workspacePathSample) ? state.workspacePathSample : []
+        if (cwds.length === 0 && paths.length === 0) return null
+        return h('div', { className: 'wsk-hint', style: { marginTop: 4 } },
+          cwds.length > 0 ? h('div', null, `会话 cwd 样本：${cwds.join(' | ')}`) : null,
+          paths.length > 0 ? h('div', null, `工作区路径样本：${paths.join(' | ')}`) : null)
+      }
+
       const providerOptions = (current, fallback) => {
         const list = [...providers]
         for (const candidate of [current, fallback]) {
@@ -704,9 +741,31 @@ window.__ModuleLoader__.load({
                 `读取失败：${error}`,
                 h('div', { className: 'wsk-hint' }, '请确认 DSH Web 服务正在运行、且本插件的宿主半边已加载。'))
             : null,
+          hostIsStale
+            ? h('div', { className: 'wsk-msg bad', style: { marginBottom: 12 } },
+                '宿主端插件还是旧版本：所以看不到会话列表，也没有按会话配置。',
+                h('div', { className: 'wsk-hint' },
+                  '请「完全退出」DSH Desktop 再重新打开（关闭窗口 / 刷新页面都不够：宿主代码只在启动时加载）。'),
+                h('div', { className: 'wsk-hint' }, diagText()))
+            : null,
           state !== null && state.sessionListAvailable === false
             ? h('div', { className: 'wsk-msg info', style: { marginBottom: 12 } },
-                '当前 DSH 版本没有提供会话列表服务，只能按工作区配置 key。')
+                '当前 DSH 版本没有提供会话列表服务，只能按工作区配置 key。',
+                h('div', { className: 'wsk-hint' }, diagText()))
+            : null,
+          !hostIsStale && probe?.available === true && probe.count === 0
+            ? h('div', { className: 'wsk-msg info', style: { marginBottom: 12 } },
+                '宿主报告 0 个会话，所以没有可展开的列表。',
+                h('div', { className: 'wsk-hint' },
+                  '只有「会话记录里带 cwd」的会话才能挂到工作区/未分组目录下。'),
+                h('div', { className: 'wsk-hint' }, diagText()),
+                diagSamples())
+            : null,
+          !hostIsStale && (probe?.count ?? 0) > 0 && sessionTotal === 0
+            ? h('div', { className: 'wsk-msg info', style: { marginBottom: 12 } },
+                '拿到会话了，但没有一个能对上工作区/目录（路径不匹配）。',
+                h('div', { className: 'wsk-hint' }, diagText()),
+                diagSamples())
             : null,
 
           h('div', { className: 'wsk-card' },
@@ -758,7 +817,8 @@ window.__ModuleLoader__.load({
 
           h('div', { className: 'wsk-hint' },
             '专属 key 存进 DSH 凭据库中的独立引用，因此换 key 不写进会话日志、也不影响历史回放。',
-            state?.statePath ? h('div', null, `状态文件：${state.statePath}`) : null)),
+            state?.statePath ? h('div', null, `状态文件：${state.statePath}`) : null,
+            diagText() !== undefined ? h('div', { className: 'wsk-diag' }, diagText()) : null)),
 
         renderPrompt())
     }

package/lib/index.js

@@ -57,6 +57,20 @@ function log(...args) {
   if (DEBUG) console.log('[workspace-api-key]', ...args)
 }
 
+/**
+ * 运行中的宿主半边版本（读自己的 package.json）。
+ * 界面把它显示出来是为了区分「宿主半边是旧版本（例如只刷新了页面而没重启应用）」
+ * 和「宿主是新版本、只是拿不到会话列表」——这两种情况的修法完全不同。
+ */
+const PLUGIN_VERSION = (() => {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+    return typeof pkg?.version === 'string' ? pkg.version : undefined
+  } catch {
+    return undefined
+  }
+})()
+
 // ─────────────────────────── 路径 / 工作区键 ───────────────────────────
 
 /** 统一的路径比较用规范形：绝对化 + 分隔符统一 + Windows 折大小写。 */
@@ -200,23 +214,48 @@ function sessionListAvailable(ctx) {
   }
 }
 
-/** 全部会话摘要（含冷会话）。服务缺失时返回空数组，界面退化成只列工作区。 */
-async function sessionSummaries(ctx) {  let controller
+/**
+ * 会话摘要 + 诊断信息。界面靠 available / count / error / 样本路径来解释
+ * 「为什么面板里看不到会话」：服务没挂载、list() 抛错、行里没有 cwd，还是
+ * 会话的 cwd 与工作区路径对不上。
+ */
+async function sessionProbe(ctx) {
+  let controller
   try {
     controller = ctx.get('sessionController')
-  } catch {
-    controller = undefined
+  } catch (err) {
+    return { available: false, rows: [], count: 0, error: String(err?.message ?? err) }
+  }
+  if (controller === undefined) return { available: false, rows: [], count: 0 }
+  if (typeof controller.list !== 'function') {
+    return { available: false, rows: [], count: 0, error: 'sessionController.list is not a function' }
   }
-  if (controller === undefined || typeof controller.list !== 'function') return []
   try {
     const rows = await controller.list()
-    return Array.isArray(rows) ? rows : []
+    const list = Array.isArray(rows) ? rows : []
+    const samples = []
+    let withoutCwd = 0
+    for (const row of list) {
+      const cwd = typeof row?.cwd === 'string' && row.cwd !== '' ? row.cwd : undefined
+      if (cwd === undefined) {
+        withoutCwd += 1
+        continue
+      }
+      if (samples.length < 5 && !samples.includes(cwd)) samples.push(cwd)
+    }
+    log('sessionController.list ok:', list.length, 'rows,', withoutCwd, 'without cwd')
+    return { available: true, rows: list, count: list.length, withoutCwd, samples }
   } catch (err) {
     log('sessionController.list failed:', String(err?.message ?? err))
-    return []
+    return { available: true, rows: [], count: 0, error: String(err?.message ?? err) }
   }
 }
 
+/** 只要会话摘要（含冷会话）。服务缺失 / 出错时为空数组，界面退化成只列工作区。 */
+async function sessionSummaries(ctx) {
+  return (await sessionProbe(ctx)).rows
+}
+
 /** 从摘要里取「当前会话在用的模型选择」，形状 {provider, model}。 */
 function modelSelectionOf(row) {
   const values = row?.projections?.values
@@ -895,7 +934,8 @@ async function snapshot(ctx, state) {
   const defaultRefName = 'DEEPSEEK_API_KEY'
   const defaultInfo = await describeKey(ctx, defaultRefName)
   const defaultHit = await resolveKey(ctx, defaultRefName)
-  const rows = await sessionSummaries(ctx)
+  const probe = await sessionProbe(ctx)
+  const rows = probe.rows
   const byCwd = new Map()
   for (const row of rows) {
     const norm = normPath(row?.cwd)
@@ -977,7 +1017,16 @@ async function snapshot(ctx, state) {
 
   return {
     ok: true,
+    pluginVersion: PLUGIN_VERSION,
     storeVersion: STATE_VERSION,
+    sessionProbe: {
+      available: probe.available,
+      count: probe.count,
+      withoutCwd: probe.withoutCwd ?? 0,
+      error: probe.error,
+      samples: probe.samples ?? [],
+    },
+    workspacePathSample: workspaces.slice(0, 5).map((ws) => ws.path),
     defaultRef: {
       ref: defaultRefName,
       configured: defaultInfo.configured === true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-workspace-api-key",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A DeepSeek Harness plugin that binds a separate DeepSeek API key to each workspace, or to a single session, so the spend of one key stays with the sessions you choose.",
   "type": "module",
   "license": "MIT",