dsh-workspace-api-key 0.2.0 → 0.2.2

package/README.md

@@ -31,17 +31,18 @@ Host half (`lib/index.js`):
 - matches that directory against `workspaceRegistry.list()` after normalizing both sides (absolute, trailing separator removed, lower-cased on Windows);
 - 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;
+- builds the session list from the `sessionController` service (`list()`, unwrapping its `{items: […]}` envelope) and falls back to the live `sessions` service (`ctx.get('sessions').list()`), so the panel still has sessions when the controller is missing, throws, or returns an empty list — subagent sessions are filtered out of that fallback;
+- reports its own version and a session probe (`available`, `shape`, `source`, `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()`, an unexpected envelope shape, 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()`.
 
-The browser half (`lib/client.js`) registers into the `sidebar.panellist` slot (`order: 1`), the `main` slot (key `workspace-api-key`) and the `shell.overlay` slot (the entering-a-session warning), the same slots `dsh-skill-mcp-panel` and `dsh-429-guard` use. It is plain `React.createElement` with no build step and no bundled dependencies. The overlay asks `/wsk-api/check` about the session that currently owns the main view, asks at most once per session, and its buttons only ever navigate to the panel — the panel is where a key can actually be changed.
+The browser half (`lib/client.js`) registers into the `sidebar.panellist` slot (`order: 1`), the `main` slot (key `workspace-api-key`) and the `shell.overlay` slot (the entering-a-session warning), the same slots `dsh-skill-mcp-panel` and `dsh-429-guard` use. It is plain `React.createElement` with no build step and no bundled dependencies. It merges the host rows with the browser-side `sessions` store (`ctx.get('sessions').list.getSnapshot()`, which is what the sidebar itself renders), so session titles come from `displayTitle` and sessions stay visible even when the host cannot list them. The overlay asks `/wsk-api/check?sessionId=…&path=…` about the session that currently owns the main view, asks at most once per session, and its buttons only ever navigate to the panel — the panel is where a key can actually be changed.
 
 ### HTTP API (loopback only)
 
 | 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,21 +71,22 @@ 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     # 125 assertions
+node test/client.test.mjs   # 121 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.
+Neither suite needs a running DSH process. The host suite drives `apply()` against a mock context (fake `credentials`, `workspaceRegistry`, `agents`, `sessionController`, `sessions`, `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, state persistence, and the session probe including the `{items}` envelope and the live-session fallback. 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, sessions recovered from the browser-side store when the host has none (with `displayTitle` winning and subagent sessions hidden), 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.
 
 ## Requirements and limits
 
 - Verified against DSH Desktop 2.0.17 with `@deepseek-ai/dsh*` 0.2.0-rc.2 and `@deepseek-ai/cordis` 4.0.4. It has no runtime dependency and imports no `@deepseek-ai/*` package — only the host services (`credentials`, `workspaceRegistry`, `agents`, `sessionController`, `webServer`, `llm`, `settings`) and Node built-ins.
 - One key per level: a session has a single key whichever provider route reads it, and a key recorded for one provider is reported as a mismatch when the session runs on another. Model changes inside one provider are not treated as a mismatch, because a DeepSeek key is account-wide.
-- Sessions are matched to a workspace by their directory (`cwd`). Sessions that never stored a `cwd` are not listed by the host's own `list()`, so they appear in no row.
+- Sessions are matched to a workspace by their directory (`cwd`). The host's own `list()` skips stored sessions that never got a `cwd`, and the live-session fallback only knows sessions that are currently loaded, so the panel may show fewer sessions than the sidebar. Sessions visible only in the browser-side store carry no `cwd` of their own beyond the one the sidebar knows.
 - The connection test speaks the Anthropic Messages shape (`POST <baseURL>/messages` with `x-api-key` and `anthropic-version: 2023-06-01`), which is what the DeepSeek route uses. A provider that speaks a different protocol can still have keys bound per level, but the test may report a failure for a key that works.
 - 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 from which source: `sessionController`, its live-session fallback, or the browser store), plus sample session `cwd` values next to sample workspace paths when none of them match.
 
 ## License
 

package/README.zh.md

@@ -31,11 +31,12 @@ DSH 只从一个全局凭据 ref（默认 `DEEPSEEK_API_KEY`）解析 DeepSeek k
 - 把该目录与 `workspaceRegistry.list()` 做规范化后比对（绝对化、去掉尾部分隔符、Windows 折大小写）；
 - 由每一层派生出稳定的 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()`），所以面板显示的标题与模型投影和侧栏一致；该服务缺失时自动降级为只能按工作区配置；
+- 会话列表来自 `sessionController` 服务（`list()`，会拆开它 `{items: […]}` 的信封），控件缺失 / 抛错 / 列表为空时再退到宿主 live 会话服务（`ctx.get('sessions').list()`），所以那种情况下面板仍能列出会话（该兜底会过滤掉子代理会话）；
+- `/wsk-api/state` 会带上插件自身版本与会话探针（`available`、`shape`、`source`、`count`、`withoutCwd`、`samples`、`error`，以及工作区路径样本），面板据此说明**为什么**没有列出会话：宿主半边是旧版本（只刷新了页面而没重启应用）、没有 `sessionController`、`list()` 抛错、信封形状不认识，还是会话的 `cwd` 与任何工作区路径都对不上；
 - 自己的账本（哪一层对应哪个 ref、失效标记、key 是给哪个服务商记的）落在 `$DSH_HOME/storages/dsh-workspace-api-key.json`；
 - 通过 `agent/request-error` waterfall 观察失败，但**从不**返回 `{kind: 'retry'}`——只记录判定结果并 `next()` 放行。
 
-浏览器半边（`lib/client.js`）注册到 `sidebar.panellist` 槽（`order: 1`）、`main` 槽（key 为 `workspace-api-key`）与 `shell.overlay` 槽（点进会话时的提醒），和 `dsh-skill-mcp-panel`、`dsh-429-guard` 用的是同一套槽。全部是朴素的 `React.createElement`，没有构建步骤，也不打包任何依赖。覆盖层向 `/wsk-api/check` 查询当前占据主视图的会话，每个会话最多问一次，它的按钮只负责把你带到面板——改 key 只能由面板里的操作完成。
+浏览器半边（`lib/client.js`）注册到 `sidebar.panellist` 槽（`order: 1`）、`main` 槽（key 为 `workspace-api-key`）与 `shell.overlay` 槽（点进会话时的提醒），和 `dsh-skill-mcp-panel`、`dsh-429-guard` 用的是同一套槽。全部是朴素的 `React.createElement`，没有构建步骤，也不打包任何依赖。它会把宿主行与浏览器端 `sessions` 存储（`ctx.get('sessions').list.getSnapshot()`，也就是侧栏自己渲染的数据）合并起来，因此标题取自 `displayTitle`，宿主列不出会话时面板也照样有会话可列。覆盖层向 `/wsk-api/check?sessionId=…&path=…` 查询当前占据主视图的会话，每个会话最多问一次，它的按钮只负责把你带到面板——改 key 只能由面板里的操作完成。
 
 ### HTTP 接口（仅限回环）
 
@@ -70,21 +71,22 @@ 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     # 125 条断言
+node test/client.test.mjs   # 121 条断言
 ```
 
-两个套件都不需要启动 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 之后才可用时返回键仍然有效。
+两个套件都不需要启动 DSH。宿主套件用一个假 ctx（假的 `credentials`、`workspaceRegistry`、`agents`、`sessionController`、`sessions`、`webServer`，以及打桩的 `fetch`）驱动 `apply()`，覆盖 ref 派生、会话→工作区→默认的级联、工作区匹配、把第二个适配器的 `apiKeyEnv` 一起重定向、清回默认、401/402/429/5xx 的判定、回环与来源校验、状态落盘，以及会话探针（含 `{items}` 信封与 live 兜底）。浏览器套件通过一个极小的 `window.__ModuleLoader__` 与自制 React 运行时加载 `lib/client.js`，渲染出面板与覆盖层，断言槽注册、首屏渲染、会话折叠/展开、会话级保存与测试、宿主列不出会话时从浏览器端存储恢复会话（标题取 `displayTitle`、隐藏子代理会话）、未分组目录卡片、失效与不匹配提醒、「去配置」的交接、没有会话列表时的降级，以及 `ctx.get('layout')` 在插件 apply 之后才可用时返回键仍然有效。
 
 ## 要求与限制
 
 - 已在 DSH Desktop 2.0.17（`@deepseek-ai/dsh*` 0.2.0-rc.2、`@deepseek-ai/cordis` 4.0.4）上验证。插件没有运行时依赖，也不 import 任何 `@deepseek-ai/*` 包，只用宿主服务（`credentials`、`workspaceRegistry`、`agents`、`sessionController`、`webServer`、`llm`、`settings`）与 Node 内置模块。
 - 每一层只有一把 key：一个会话无论被哪个 provider 路由读取，用的都是同一把 key；key 记下的服务商与会话当前服务商不一致时会被报为「不匹配」，但同一服务商内换模型不算不匹配，因为 DeepSeek key 是账号级的。
-- 会话按目录（`cwd`）归入工作区。从未存过 `cwd` 的会话不会被宿主自己的 `list()` 列出，因此不会出现在任何行里。
+- 会话按目录（`cwd`）归入工作区。宿主自己的 `list()` 会跳过从未存过 `cwd` 的历史会话，而 live 兜底只认识当前装载中的会话，所以面板列出的会话可能比侧栏少；只在浏览器端存储里可见的会话，除了侧栏知道的那个 `cwd` 之外没有别的路径信息。
 - 「测试连接」说的是 Anthropic Messages 协议（`POST <baseURL>/messages` 带 `x-api-key` 与 `anthropic-version: 2023-06-01`），也就是 DeepSeek 路由用的协议；换了别的协议的 provider 一样可以按层绑 key，只是测试可能把有效的 key 报成失败。
 - key 通过凭据服务存放在 `$DSH_HOME/.credentials.yaml` 的 `refs:` 里，明文，和默认 key 完全一样。它不会被写进会话日志、插件状态文件或插件目录。
 - 匹配是规范化之后的文本比较。如果某个会话的 `cwd` 是指向已注册工作区路径的符号链接或 junction，则匹配不上，会走上层层级。
 - 卸载插件不会删除已生成的 `*_WS_*` / `*_SS_*` ref，可在「设置 → 模型」里清掉。
+- 如果面板列出了工作区却没有可展开的会话，请看面板底部的诊断行。出现红色「宿主端插件还是旧版本」横幅，说明 DSH 进程没有重启过：宿主半边只在启动时加载，关窗口和刷新页面都不算——请完全退出 DSH Desktop 再打开。其余情况诊断行会写明宿主看到多少个会话、会话列表来自哪个来源（`sessionController`、live 兜底，还是浏览器端存储）；一个都对不上时，还会并排给出会话 `cwd` 样本与工作区路径样本，便于比对。
 
 ## 许可
 

package/lib/client.js

@@ -20,6 +20,19 @@ window.__ModuleLoader__.load({
     //   refresh —— 面板挂载后在这里登记自己的刷新函数
     const bridge = { focus: null, refresh: null }
 
+    // apply 阶段拿到的 ctx。会话列表服务（browser 侧 "sessions"）由
+    // dsh-api-session-controller 的客户端半边在 effect 里 provide，可能晚于
+    // 本插件注册，所以只在渲染/点击时惰性取，不在 apply 阶段捕获结果。
+    const host = { ctx: null }
+    function sessionsService(fallback) {
+      if (fallback !== undefined && fallback !== null) return fallback
+      try {
+        return host.ctx?.get?.('sessions')
+      } catch {
+        return undefined
+      }
+    }
+
     // ─────────────────────────────── 样式 ───────────────────────────────
 
     const CSS = `
@@ -68,6 +81,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); }
@@ -178,6 +192,153 @@ window.__ModuleLoader__.load({
       return title ?? (session.blank === true ? '（空会话）' : String(session.sessionId).slice(0, 12))
     }
 
+    // ─────────────────── 会话树：宿主行 + 浏览器端列表 ───────────────────
+    // 宿主 /state 里的会话行只有「带 cwd 的会话」才能被挂到目录下，而且不含标题
+    // （标题是浏览器端的 projection）。这里用浏览器端 sessions 服务补齐：
+    //   · 标题（displayTitle）
+    //   · 宿主漏掉的会话（例如 cwd 规范化差异导致的挂载失败）
+    // 合并后仍然保持宿主的 key 信息（level / configured / invalid / mismatch）。
+
+    function normKey(p) {
+      if (typeof p !== 'string' || p === '') return undefined
+      const trimmed = p.replace(/[\\/]+$/, '')
+      const base = trimmed === '' ? p : trimmed
+      return base.replace(/\//g, '\\').toLowerCase()
+    }
+
+    function dirName(p) {
+      if (typeof p !== 'string' || p === '') return ''
+      const parts = p.replace(/[\\/]+$/, '').split(/[\\/]/)
+      return parts[parts.length - 1] ?? p
+    }
+
+    /** 浏览器端 sessions 服务快照 → 顶层会话条目（子代理会话不算）。 */
+    function clientSessionEntries(sessions) {
+      const snap = sessions?.list?.getSnapshot?.()
+      if (snap === null || snap === undefined) return []
+      const ids = Array.isArray(snap.ids) ? snap.ids : Object.keys(snap.byId ?? {})
+      const entries = []
+      for (const id of ids) {
+        const item = snap.byId?.[id]
+        if (item === null || item === undefined) continue
+        // 子代理会话不作为可配置项列出（它们跟随父会话）。
+        if (item.parentId !== undefined || item.origin === 'subagent') continue
+        entries.push({
+          sessionId: typeof item.id === 'string' && item.id !== '' ? item.id : id,
+          cwd: typeof item.cwd === 'string' && item.cwd !== '' ? item.cwd : undefined,
+          title: typeof item.displayTitle === 'string' && item.displayTitle !== ''
+            ? item.displayTitle
+            : typeof item.title === 'string' && item.title !== '' ? item.title : undefined,
+          updatedAt: typeof item.updatedAt === 'number' ? item.updatedAt : 0,
+          running: item.running === true,
+        })
+      }
+      return entries
+    }
+
+    /**
+     * 用浏览器端的会话列表重建「工作区/目录 → 会话」的树。
+     * 宿主行（含 key 层级）按 sessionId 合并进来；宿主没给出的会话用
+     * /state 里的覆盖记录补出层级，保证按钮不会因为宿主列表为空而消失。
+     */
+    function mergeSessions(state, sessions) {
+      const entries = clientSessionEntries(sessions)
+      if (state === null || state === undefined || entries.length === 0) return state
+
+      const hostRows = new Map()
+      for (const group of [...(state.workspaces ?? []), ...(state.ungrouped ?? [])]) {
+        for (const row of (Array.isArray(group?.sessions) ? group.sessions : [])) {
+          if (row?.sessionId !== undefined) hostRows.set(row.sessionId, row)
+        }
+      }
+      const overrideBySession = new Map()
+      for (const item of (Array.isArray(state.sessionOverrides) ? state.sessionOverrides : [])) {
+        if (item?.sessionId !== undefined) overrideBySession.set(item.sessionId, item)
+      }
+      const workspaceByPath = new Map()
+      for (const ws of (state.workspaces ?? [])) {
+        const key = normKey(ws?.path)
+        if (key !== undefined) workspaceByPath.set(key, ws)
+      }
+
+      const buckets = new Map()
+      const extras = new Map()
+      for (const entry of entries) {
+        const host = hostRows.get(entry.sessionId)
+        const cwd = typeof host?.cwd === 'string' && host.cwd !== '' ? host.cwd : entry.cwd
+        const pathKey = normKey(cwd)
+        const ws = pathKey !== undefined ? workspaceByPath.get(pathKey) : undefined
+        let row = host
+        if (row === undefined) {
+          const own = overrideBySession.get(entry.sessionId)
+          const level = own !== undefined ? 'session' : ws?.configured === true ? 'workspace' : 'default'
+          row = {
+            sessionId: entry.sessionId,
+            title: entry.title,
+            cwd,
+            updatedAt: entry.updatedAt,
+            running: entry.running,
+            blank: false,
+            parentSessionId: undefined,
+            provider: own?.provider ?? ws?.overrideProvider,
+            model: own?.model ?? ws?.overrideModel,
+            ref: own?.ref,
+            configured: own !== undefined,
+            keyMasked: own?.keyMasked,
+            overrideProvider: own?.provider,
+            overrideModel: own?.model,
+            level,
+            effectiveRef: level === 'session' ? own?.ref : level === 'workspace' ? ws?.ref : undefined,
+            effectiveKeyMasked: level === 'session'
+              ? own?.keyMasked
+              : level === 'workspace' ? ws?.keyMasked : state.defaultRef?.keyMasked,
+            effectiveProvider: own?.provider ?? ws?.overrideProvider,
+            effectiveModel: own?.model ?? ws?.overrideModel,
+            effectiveTitle: undefined,
+            invalid: (level === 'session' ? own?.invalid : level === 'workspace' ? ws?.invalid : null) ?? null,
+            mismatch: null,
+          }
+        } else {
+          const patch = {}
+          if ((row.title === undefined || row.title === '') && entry.title !== undefined) patch.title = entry.title
+          if ((row.cwd === undefined || row.cwd === '') && cwd !== undefined) patch.cwd = cwd
+          if (Object.keys(patch).length > 0) row = { ...row, ...patch }
+        }
+        const bucketKey = pathKey ?? ''
+        const target = ws !== undefined ? buckets : extras
+        const list = target.get(ws !== undefined ? ws.path : bucketKey) ?? []
+        list.push(row)
+        target.set(ws !== undefined ? ws.path : bucketKey, list)
+      }
+
+      const sorted = (rows) => rows.slice().sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0))
+      const workspaces = (state.workspaces ?? []).map((ws) => (
+        { ...ws, sessions: sorted(buckets.get(ws.path) ?? []) }
+      ))
+      const ungrouped = []
+      for (const [key, rows] of extras) {
+        const known = (state.ungrouped ?? []).find((group) => normKey(group?.path) === key)
+        const path = known?.path ?? rows[0]?.cwd ?? undefined
+        ungrouped.push({
+          ...(known ?? {
+            id: undefined,
+            path,
+            title: path !== undefined && path !== '' ? dirName(path) : '（没有目录）',
+            kind: 'directory',
+            configured: false,
+            exists: true,
+          }),
+          sessions: sorted(rows),
+        })
+      }
+      for (const group of (state.ungrouped ?? [])) {
+        if (!ungrouped.some((item) => item.path === group.path)) {
+          ungrouped.push({ ...group, sessions: sorted(buckets.get(group.path) ?? []) })
+        }
+      }
+      return { ...state, workspaces, ungrouped, sessionSource: 'client' }
+    }
+
     function modelText(session) {
       if (typeof session.provider !== 'string' || session.provider === '') return '模型未知'
       return `${session.provider} / ${session.model ?? '默认模型'}`
@@ -321,6 +482,16 @@ window.__ModuleLoader__.load({
 
       useEffect(() => { refresh() }, [refresh])
 
+      // 浏览器端的会话列表（含标题、cwd）会随时变化：变了就重渲染。
+      const sessionStore = sessionsService(props?.sessions)
+      const [sessionTick, setSessionTick] = useState(0)
+      useEffect(() => {
+        const store = sessionStore?.list
+        if (store === undefined || store === null || typeof store.subscribe !== 'function') return undefined
+        const off = store.subscribe(() => setSessionTick((tick) => tick + 1))
+        return () => { if (typeof off === 'function') off() }
+      }, [sessionStore])
+
       // 让覆盖层能立刻刷新面板（点「去配置」时面板可能已经挂载着）。
       useEffect(() => {
         bridge.refresh = refresh
@@ -417,12 +588,55 @@ window.__ModuleLoader__.load({
         }
       }
 
-      const workspaces = state?.workspaces ?? []
+      // 把浏览器端的会话列表并进宿主状态：宿主列表为空时（例如 list() 信封形状
+      // 不匹配）界面仍然能列出会话，并且会话标题来自浏览器端 projection。
+      const view = mergeSessions(state, sessionStore)
+      const workspaces = view?.workspaces ?? []
       const grouped = workspaces.filter((ws) => ws.kind === 'workspace')
       const orphans = workspaces.filter((ws) => ws.kind !== 'workspace')
-      const ungrouped = state?.ungrouped ?? []
-      const defaultRef = state?.defaultRef
-      const providers = state?.providers ?? []
+      const ungrouped = view?.ungrouped ?? []
+      const defaultRef = view?.defaultRef
+      const providers = view?.providers ?? []
+
+      // ── 诊断 ──────────────────────────────────────────────────────────────
+      // 面板里「看不到可展开的会话」有两个完全不同的原因，修法也不同：
+      //   1) 宿主半边还是旧版本（只刷新了页面 / 没重启应用）→ 响应里没有 storeVersion；
+      //   2) 宿主是新版本，但会话列表服务不可用或返回 0 行 → 看 sessionProbe。
+      // 这里把两者都显式画出来，用户截一张图就能定位。
+      const probe = state?.sessionProbe
+      const hostIsStale = state !== null && state.storeVersion === undefined
+      const clientCount = clientSessionEntries(sessionStore).length
+      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} 个${probe.shape !== undefined ? `（${probe.shape}）` : ''}`
+              + (probe.source === 'sessions' ? '（live 兜底）' : '')
+        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}`
+          + ` · 浏览器会话列表：${clientCount} 个`
+          + ` · 工作区 ${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]
@@ -482,7 +696,9 @@ window.__ModuleLoader__.load({
               type: 'button', className: 'wsk-btn',
               onClick: () => setEditing(null),
             }, '取消')),
-          h('div', { className: 'wsk-hint' }, `凭据引用：${target.ref ?? '—'}`))
+          h('div', { className: 'wsk-hint' }, target.ref === undefined || target.ref === null
+            ? '凭据引用：保存时由宿主按这个会话/目录的 ID 生成，保存后这里会显示出来'
+            : `凭据引用：${target.ref}`))
       }
 
       const renderSession = (ws, session) => {
@@ -704,9 +920,31 @@ window.__ModuleLoader__.load({
                 `读取失败：${error}`,
                 h('div', { className: 'wsk-hint' }, '请确认 DSH Web 服务正在运行、且本插件的宿主半边已加载。'))
             : null,
-          state !== null && state.sessionListAvailable === false
+          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 && clientCount === 0
+            ? h('div', { className: 'wsk-msg info', style: { marginBottom: 12 } },
+                '当前 DSH 版本没有提供会话列表服务，只能按工作区配置 key。',
+                h('div', { className: 'wsk-hint' }, diagText()))
+            : null,
+          !hostIsStale && probe?.available === true && probe.count === 0 && clientCount === 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 && sessionTotal === 0 && clientCount === 0 && (probe?.count ?? 0) > 0
             ? h('div', { className: 'wsk-msg info', style: { marginBottom: 12 } },
-                '当前 DSH 版本没有提供会话列表服务，只能按工作区配置 key。')
+                '拿到会话了，但没有一个能对上工作区/目录（路径不匹配）。',
+                h('div', { className: 'wsk-hint' }, diagText()),
+                diagSamples())
             : null,
 
           h('div', { className: 'wsk-card' },
@@ -758,7 +996,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())
     }
@@ -776,25 +1015,31 @@ window.__ModuleLoader__.load({
           if (sessions === undefined || sessions === null) return undefined
 
           let disposed = false
-          const currentSessionId = () => {
+          const currentSession = () => {
             try {
               const snapshot = sessions.list?.getSnapshot?.()
               const byId = snapshot?.byId ?? {}
               for (const [id, item] of Object.entries(byId)) {
-                if (Number(item?.retainedBy?.mainView) > 0) return id
+                if (Number(item?.retainedBy?.mainView) > 0) return { id, cwd: item?.cwd }
               }
             } catch {
               /* 快照不可用时静默跳过 */
             }
             return undefined
           }
+          const currentSessionId = () => currentSession()?.id
 
           const evaluate = async () => {
-            const sessionId = currentSessionId()
+            const current = currentSession()
+            const sessionId = current?.id
             if (sessionId === undefined || asked.current.has(sessionId)) return
             asked.current.add(sessionId)
             try {
-              const res = await api(`/check?sessionId=${encodeURIComponent(sessionId)}`)
+              // 一并带上 cwd：宿主拿到路径后，即使会话列表为空也能定位到工作区。
+              const cwd = typeof current?.cwd === 'string' && current.cwd !== '' ? current.cwd : undefined
+              const query = `/check?sessionId=${encodeURIComponent(sessionId)}`
+                + (cwd === undefined ? '' : `&path=${encodeURIComponent(cwd)}`)
+              const res = await api(query)
               if (disposed) return
               if (res.needsAttention === true) setPrompt(res)
             } catch {
@@ -889,6 +1134,7 @@ window.__ModuleLoader__.load({
       ensureStyles()
       const slots = ctx.get('slots')
       if (slots === undefined || slots === null) return
+      host.ctx = ctx
 
       // 惰性取 layout：点击时才读，避免服务尚未就绪时把 undefined 缓存下来。
       const back = () => {
@@ -915,7 +1161,7 @@ window.__ModuleLoader__.load({
         slots.register({
           name: 'main',
           key: PANEL_ID,
-          inject: () => ({ back }),
+          inject: () => ({ back, sessions: ctx.get('sessions') }),
         }, WorkspaceKeyPage)), 'workspace-api-key: main page')
 
       ctx.effect(() => slots.inject('shell.overlay', () =>

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 折大小写。 */
@@ -188,9 +202,9 @@ function effectiveOverride(ctx, state, { sessionId, cwd }) {
   return { level: 'default', ref: undefined, entry: undefined }
 }
 
-// ───────────────── 会话列表（宿主 sessionController） ─────────────────
+// ───────────────── 会话列表（宿主 sessionController + live 兜底） ─────────────────
 
-/** 宿主是否挂载了会话列表 API（决定界面能否列出会话）。 */
+/** 宿主是否挂载了会话列表 API（仅诊断用；界面看 sessionProbe.available）。 */
 function sessionListAvailable(ctx) {
   try {
     const controller = ctx.get('sessionController')
@@ -200,21 +214,93 @@ function sessionListAvailable(ctx) {
   }
 }
 
-/** 全部会话摘要（含冷会话）。服务缺失时返回空数组，界面退化成只列工作区。 */
-async function sessionSummaries(ctx) {  let controller
+/**
+ * 会话摘要 + 诊断信息。界面靠 available / count / error / 样本路径来解释
+ * 「为什么面板里看不到会话」：服务没挂载、list() 抛错、行里没有 cwd，还是
+ * 会话的 cwd 与工作区路径对不上。
+ */
+async function sessionProbe(ctx) {
+  let controller
+  let controllerError
   try {
     controller = ctx.get('sessionController')
-  } catch {
-    controller = undefined
-  }
-  if (controller === undefined || typeof controller.list !== 'function') return []
-  try {
-    const rows = await controller.list()
-    return Array.isArray(rows) ? rows : []
   } catch (err) {
-    log('sessionController.list failed:', String(err?.message ?? err))
-    return []
+    controllerError = String(err?.message ?? err)
+  }
+  if (controller !== undefined && typeof controller.list !== 'function') {
+    controllerError = 'sessionController.list is not a function'
+  }
+  let list = []
+  let shape
+  let probeError = controllerError
+  if (controller !== undefined && typeof controller.list === 'function') {
+    try {
+      // 宿主 SessionController.list(request, signal) 返回的是 { items: [...] } 信封，
+      // 不是数组（远端 remote.session.list 也是同一形状）。早期版本只认数组，
+      // 于是「信封」被当成空列表 —— 界面因此看不到任何会话。
+      // 这里同时容忍裸数组与小写 value.items（不同 DSH 版本的形状差异）。
+      const raw = await controller.list()
+      shape = Array.isArray(raw)
+        ? 'array'
+        : raw === null || raw === undefined
+          ? String(raw)
+          : typeof raw === 'object'
+            ? 'object'
+            : typeof raw
+      list = Array.isArray(raw)
+        ? raw
+        : Array.isArray(raw?.items)
+          ? raw.items
+          : Array.isArray(raw?.value?.items)
+            ? raw.value.items
+            : []
+      if (list.length === 0 && shape === 'object') {
+        probeError = `sessionController.list() 返回了 object（keys: ${Object.keys(raw).slice(0, 8).join(',') || '—'}），既不是数组也没有 items`
+      }
+    } catch (err) {
+      log('sessionController.list failed:', String(err?.message ?? err))
+      probeError = String(err?.message ?? err)
+      shape = 'throw'
+    }
+  }
+  // sessionController 给不出任何会话时（服务缺失、list 抛错、列表为空……），
+  // 用宿主 live 会话服务兜底，让界面至少能列出「当前装载中的会话」。
+  let rows = list
+  let source = rows.length > 0 ? 'sessionController' : undefined
+  if (rows.length === 0) {
+    const live = liveSessionRows(ctx)
+    if (live.length > 0) {
+      rows = live
+      source = 'sessions'
+      log('sessionController gave no rows, falling back to sessions service:', live.length, 'rows')
+    }
+  }
+  const samples = []
+  let withoutCwd = 0
+  for (const row of rows) {
+    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('sessionProbe:', rows.length, 'rows from', source ?? 'none', ',', withoutCwd, 'without cwd, shape', shape)
+  return {
+    available: source !== undefined,
+    rows,
+    count: rows.length,
+    withoutCwd,
+    samples,
+    shape,
+    source,
+    error: probeError,
+  }
+}
+
+/** 只要会话摘要（含冷会话）。服务缺失 / 出错时为空数组，界面退化成只列工作区。 */
+async function sessionSummaries(ctx) {
+  return (await sessionProbe(ctx)).rows
 }
 
 /** 从摘要里取「当前会话在用的模型选择」，形状 {provider, model}。 */
@@ -242,6 +328,69 @@ function titleOf(row) {
   return undefined
 }
 
+// ───────────────── 兜底：宿主 live 会话服务（ctx.get('sessions')） ─────────────────
+// sessionController.list() 依赖 sessionQuery / 持久化绑定，某些情况下会返回空列表；
+// 而 dsh-session 的 sessions 服务始终有「当前装载中的会话」。用它兜底能让
+// /check（进入会话时的提醒）与 /state 在那种情况下仍然工作。
+
+/** 单个 live 会话的 cwd 与当前模型选择。 */
+function liveSessionInfo(ctx, sessionId) {
+  if (sessionId === undefined) return undefined
+  try {
+    const session = ctx.get('sessions')?.get?.(sessionId)
+    if (session === undefined || session === null) return undefined
+    const cwd = typeof session.header?.cwd === 'string' && session.header.cwd !== ''
+      ? session.header.cwd
+      : undefined
+    let config
+    try {
+      config = session.requestHeader?.()?.config
+    } catch {
+      config = undefined
+    }
+    const provider = typeof config?.provider === 'string' && config.provider !== '' ? config.provider : undefined
+    const model = typeof config?.model === 'string' && config.model !== '' ? config.model : undefined
+    const selection = provider === undefined && model === undefined ? undefined : { provider, model }
+    if (cwd === undefined && selection === undefined) return undefined
+    return { cwd, selection }
+  } catch {
+    return undefined
+  }
+}
+
+/** 用 live 会话服务凑出与 sessionController 行兼容的摘要（仅在没有其它来源时使用）。 */
+function liveSessionRows(ctx) {
+  let sessions = []
+  try {
+    const service = ctx.get('sessions')
+    if (service === undefined || typeof service.list !== 'function') return []
+    sessions = service.list() ?? []
+  } catch {
+    return []
+  }
+  const rows = []
+  for (const session of sessions) {
+    const sessionId = session?.id ?? session?.header?.id
+    if (typeof sessionId !== 'string' || sessionId === '') continue
+    // 子代理会话不作为可配置项列出（与 sessionController 的 remote 列表不同，
+    // live 会话服务包含子代理会话）。
+    const origin = session?.header?.origin
+    if (origin === 'subagent' || session?.header?.parentSession !== undefined) continue
+    const info = liveSessionInfo(ctx, sessionId)
+    const values = {}
+    if (info?.selection !== undefined) values.modelSelection = { ...info.selection }
+    rows.push({
+      sessionId,
+      cwd: info?.cwd,
+      updatedAt: 0,
+      running: session?.getSnapshot?.()?.running === true,
+      blank: false,
+      projections: Object.keys(values).length === 0 ? undefined : { values },
+    })
+  }
+  return rows
+}
+
 /** 所有 provider 路由名（用于「这把 key 是给哪个 provider 的」选择项）。 */
 function providerList(ctx) {
   const names = new Set(['deepseek-official'])
@@ -895,7 +1044,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 +1127,18 @@ 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 ?? [],
+      shape: probe.shape,
+      source: probe.source,
+    },
+    workspacePathSample: workspaces.slice(0, 5).map((ws) => ws.path),
     defaultRef: {
       ref: defaultRefName,
       configured: defaultInfo.configured === true,
@@ -990,7 +1151,8 @@ async function snapshot(ctx, state) {
     interceptableRefs: [...interceptableRefs(ctx, state)],
     workspaceCount: workspaceIndex(ctx).size,
     credentialsAvailable: credentials !== undefined,
-    sessionListAvailable: sessionListAvailable(ctx),
+    sessionListAvailable: probe.available,
+    sessionControllerAvailable: sessionListAvailable(ctx),
     statePath: stateFilePath(),
     workspaces,
     ungrouped,
@@ -1051,6 +1213,13 @@ async function checkSession(ctx, state, params) {
       title = titleOf(row)
     }
   }
+  // 会话没出现在宿主列表里时（sessionController 空列表、冷会话未装载等），
+  // 用 live 会话服务补 cwd 与模型选择 —— 否则进入会话时的提醒会静默失效。
+  if (sid !== undefined && (cwd === undefined || selection === undefined)) {
+    const live = liveSessionInfo(ctx, sid)
+    if (cwd === undefined && live?.cwd !== undefined) cwd = live.cwd
+    if (selection === undefined && live?.selection !== undefined) selection = live.selection
+  }
   if (cwd === undefined) cwd = activeCwd(ctx)
   const eff = effectiveOverride(ctx, state, { sessionId: sid, cwd })
   const hit = eff.ref !== undefined ? await resolveKey(ctx, eff.ref) : await resolveKey(ctx, 'DEEPSEEK_API_KEY')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-workspace-api-key",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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",
@@ -15,6 +15,7 @@
   "homepage": "https://github.com/COH2357/dsh-workspace-api-key#readme",
   "keywords": [
     "dsh",
+    "dsh-plugin",
     "deepseek-harness",
     "plugin",
     "api-key",