dsh-workspace-plus 0.1.1 → 0.4.0

package/README.md

@@ -1,13 +1,15 @@
 # dsh-workspace-plus
+[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/sen70s/dsh-workspace-plus)
 
-DeepSeek Harness Web GUI 的插件。一个功能，两个入口：
+DeepSeek Harness Web GUI 的插件。一个功能，三个入口：
 
 | 入口 | 说明 |
 | --- | --- |
 | **工作区行上的目录按钮**（弹窗） | 一个工作区登记 N 个目录，每个目录带标签；标签在对话里可直接指代 |
-| **设置 → `workspace+`** | 一个开关：是否对**默认工作区**启用本功能（**默认关闭**） |
+| **对话输入框里的 `@`** | 打 `@` 就能看到本工作区的标签，选中即插入一个指向该目录绝对路径的引用 |
+| **设置 → `workspace+`** | **每个工作区一个开关**：是否在该工作区启用本功能（默认工作区默认关闭） |
 
-功能 2 解决的问题：一个工作区（DSH 里 = 一个目录）装不下真实项目。前后端分在两个仓库、文档在第三个目录时，
+它解决的问题：一个工作区（DSH 里 = 一个目录）装不下真实项目。前后端分在两个仓库、文档在第三个目录时，
 每次都要在对话里手写绝对路径，而且目录名相似时 agent 容易改错文件。本插件让工作区带上
 「标签 → 绝对路径」映射，并**在每个请求里把这张表注入 agent 上下文**，于是：
 
@@ -15,6 +17,12 @@ DeepSeek Harness Web GUI 的插件。一个功能，两个入口：
 >
 > agent 直接去 `D:\proj\backend`，不会因为旁边有个 `D:\proj\backend-legacy` 而改错。
 
+名字相似的目录摆在一处，本就是容易出事的地方。让机器记住哪个是哪个，比每次都由人在对话里
+把路径抄一遍要可靠些 —— 抄写这桩事，人向来是做不过机器的；而记错门牌这桩事，机器又向来是做不过人的。
+插件能做的，只是把它擅长的那一半接过来。
+
+> 想先看看它长什么样、怎么用：[**使用**](#使用) 一节里配了截图。
+
 > 本仓库只包含插件本身；没有改动 DSH 安装目录里的任何文件。state 文件由插件自己写在 `~/.dsh/workspaceplus/`。
 
 ## 目录结构
@@ -27,7 +35,10 @@ dsh-workspace-plus/
 │   ├── index.js        # 宿主半：store + 设置 + 上下文注入 + workspace_dirs 工具 + HTTP 路由
 │   └── client.js       # 浏览器半：设置页 + 目录弹窗 + 工作区行按钮（无需构建）
 ├── icon.svg            # 插件管理页显示的图标
-├── tools/verify.mjs    # 离线自检（258 项断言，不需要 DSH 在跑）
+├── LICENSE             # MIT
+├── docs/               # README 里那几张截图
+├── tools/verify.mjs    # 离线自检（387 项断言，不需要 DSH 在跑）
+├── tools/preview/      # 截图是怎么来的：真实 React + 真实壳层样式 + 无头 Edge（见其 README）
 └── README.md
 ```
 
@@ -36,15 +47,18 @@ dsh-workspace-plus/
 
 ## 设置：设置 → `workspace+`
 
-一个开关：**对默认工作区启用**。
+**每个工作区一个开关**：这个工作区里启用还是停用 workspace+。一个开关同时管三处 ——
+工作区行上的目录按钮、注入该工作区对话的标签表、以及 `workspace_dirs` 工具。
+关掉**不会删除**已登记的标签，只是让这个工作区暂时不参与。
 
-「默认工作区」是 DSH 首次启动时自动创建的那个（`workspaceRegistry` 里 `defaultWorkspaceId`
-指向它，即使它的注册被删掉这个身份也会保留）。它属于产品而不属于本插件，所以：
+默认值不是一刀切：
 
-- **默认关闭**：不在它的工作区行显示目录按钮，不把标签表注入它的会话上下文，`workspace_dirs`
-  工具对它直接返回一个指向上面的开关的错误。
-- 其它工作区不受影响，始终启用。
-- 打开开关后立即生效（无需重启、无需刷新）：行按钮出现、上下文开始注入。关掉不会删除已登记的标签。
+- 除默认工作区外，**每个工作区默认开启**。
+- 「默认工作区」是 DSH 首次启动时自动创建的那个（`workspaceRegistry` 里 `defaultWorkspaceId`
+  指向它，即使它的注册被删掉这个身份也会保留）。它属于产品而不属于本插件，所以**默认关闭**：
+  不显示目录按钮、不注入上下文、`workspace_dirs` 对它直接返回一个指向上面的开关的错误。
+  在设置页打开它自己那一行的开关即可，无需重启、无需刷新。
+- 拨动开关写的是**这个工作区的显式值**，所以它一定覆盖默认值；设置页不会因为「默认值恰好相同」而装作没生效。
 
 宿主怎么认出默认工作区：它只调用**公开的** `workspaceRegistry.initializeDefault()`，
 并传一个「拒绝创建」的目录解析器 —— 已有默认工作区时该调用直接返回它（无副作用），
@@ -54,6 +68,26 @@ dsh-workspace-plus/
 > 首次探测可能早于注册表服务初始化完成而失败。失败时状态保持「未决」并在下一次请求/工具调用时重试，
 > 而不是把「没有默认工作区」永久缓存下来 —— 否则默认工作区会被静默启用。
 
+### 设置是怎么存的
+
+```json
+{
+  "settings": {
+    "defaultWorkspaceEnabled": false,
+    "workspaceEnabled": { "d:\\projects\\api": false }
+  }
+}
+```
+
+- `workspaceEnabled` 是**按工作区**那一层：键是工作区目录（和 `workspaces` 一样大小写折叠），
+  值 `true` / `false` 是显式覆盖。
+- 键由宿主下发（`/workspaceplus/api` 快照里每个工作区的 `key`），浏览器半**不会**自己从路径猜 ——
+  Windows 下大小写折叠规则一旦不一致，猜出来的键会「存得进去但永远匹配不上」，是个静默失效。
+  旧宿主没有这个字段时，设置页把开关置灰并提示重启 dsh。
+- `defaultWorkspaceEnabled` 是「默认工作区那一行的默认值」。字段保留是为了兼容旧状态文件，
+  正常使用中不需要手改；在设置页拨默认工作区那一行写入的是 `workspaceEnabled` 里的显式覆盖。
+- 旧状态文件（没有 `settings`，或没有 `workspaceEnabled`）照常工作：缺失的那层归一化成「没有覆盖」。
+
 ## 功能是怎么工作的
 
 ### 数据
@@ -63,6 +97,7 @@ dsh-workspace-plus/
 ```json
 {
   "version": 1,
+  "settings": { "defaultWorkspaceEnabled": false, "workspaceEnabled": {} },
   "workspaces": {
     "d:\\proj": {
       "path": "D:\\proj",
@@ -112,6 +147,8 @@ dsh-workspace-plus/
 
 ### 界面：一个弹窗，两个触发器
 
+（第三个入口 —— 对话输入框里的 `@` —— 见下面单独一节。）
+
 弹窗本身注册在 **`shell.overlay`** —— 和壳层自己的「重命名工作区 / 删除工作区」对话框同一个层
 （那两个是 `workspace.session-rename`、`workspace.session-archive`），所以观感和层级天然一致。
 
@@ -122,7 +159,7 @@ dsh-workspace-plus/
 > 「Workspace row menus are visual-only except Rename/Delete」，
 > 代码里 `ProjectRowItem` 也只收到 `actions: { rename, delete }`。
 
-所以「往那个菜单里加一项」无法用官方 API 做到。替代方案是把按钮**追加到该行的操作区**
+所以「往那个菜单里加一项」无法用官方 API 做到。替代方案是把按钮**插进该行的操作区**
 （`rowActions`），定位不依赖易变的哈希类名，而用壳层自己发出的稳定锚点：
 
 - `data-slot="sidebar.workspaces"` —— 渲染器给每个 slot 出口都加的锚（`SlotOutlet`）
@@ -130,9 +167,14 @@ dsh-workspace-plus/
   `buildGroup(workspace.workspaceId, workspace.workspaceId, …)` 保证这个 key **就是** workspace id，
   与宿主 `workspaceRegistry` 的 `Workspace.id`（客户端 `workspaceView().workspaceId`）一致
 
-按钮**追加在操作区的最后**（React 的 child 协调不需要在它前面插入），并用 `MutationObserver`
-做增删对账 —— React 重渲染时并不知道这个节点的存在。点击时 `preventDefault + stopPropagation`，
-所以不会触发行本身的展开/折叠。
+**位置：夹在中间。** 壳层渲染的操作区是 `[「更多」菜单, 「新会话」按钮]`，本插件的按钮插在
+**最后一个子节点之前**，于是那一行读作「更多 · 工作区目录设置 · 新会话」，新会话保持最后一个。
+（`insertBefore(node, null)` 等价于 append，所以操作区只有一个子节点时会退化成「排在菜单之后」，
+而不是硬造一对不存在的顺序。）
+
+React 重渲染时并不知道这个节点的存在，可能把自己的子节点重新插到它两边，所以**位置是每次对账都重新
+确认的**，不是创建时设一次。对账由 `MutationObserver` 驱动，覆盖增、删、移位三种情况，
+重复对账是幂等的。点击时 `preventDefault + stopPropagation`，所以不会触发行本身的展开/折叠。
 
 外观上刻意对齐壳层自己的行内按钮（`Rows.module.css` 的 `.iconButton`）：16×16、无边框、无底色、
 `color: label-tertiary`，**hover 只变颜色不加背景**；图标直接复用官方的文件夹图形
@@ -145,19 +187,50 @@ dsh-workspace-plus/
 侧边栏不会多出任何图标（有一个 1.2s 的 settle 窗口避免闪烁）。
 
 弹窗**锁定触发它的那个工作区**：从哪个工作区行点的，就只编辑那个工作区，弹窗里没有选择器，
-只显示工作区名和根目录。位于工作区根目录之外的目录会被标出来（见下面的沙箱一节）。
+只显示工作区名和根目录。卡片宽度是 `min(760px, 100%)`（壳层默认的 380px 装不下一行
+「标签 + 绝对路径 + 说明 + 行尾图标」）。位于工作区根目录之外的目录，行尾是一个**黄色盾牌图标**，
+说明放在 hover / 键盘聚焦才出现的 tooltip 里（见下面的沙箱一节）。
 如果 HTTP 通道不可用，弹窗会明确说明原因（区分 401 / 404 / 传输不可达），而不是假装映射是空的 ——
 此时仍然可以在对话里用 `workspace_dirs` 管理。
 
-**添加目录时可以用系统的目录选择器**：路径输入框旁边的「浏览…」调用壳层自己的
-`ctx.uiWorkspace.pickDirectory()`（就是「选择工作区」用的那一个），所以桌面版是原生对话框、
-浏览器版是壳层的浏览面板。选中后自动填路径，**标签为空时**还会按目录名猜一个合法标签
-（`D:\proj\my api` → `my-api`；纯中文目录名不猜，避免塞一个宿主会拒绝的标签）。取消选择不会改动任何字段。
-`ui-workspace` 没有挂载时（合成里没有这一行）整个按钮自动置灰，插件其余部分照常工作。
+**路径没有手动输入框**：添加表单的第一行就是一个字段样式的按钮（文件夹图标 + 「选择目录…」），
+**点击它直接打开系统的目录选择器**，也就是壳层自己的 `ctx.uiWorkspace.pickDirectory()`
+（就是「选择工作区」用的那一个），所以桌面版是原生对话框、浏览器版是壳层的浏览面板。
+选中后路径显示在这个字段里，**标签为空时**还会按目录名猜一个合法标签
+（`D:\proj\my api` → `my-api`；纯中文目录名不猜，避免塞一个宿主会拒绝的标签）；
+标签和说明在同一行，路径在它们的上一行。取消选择不会改动任何字段。
+路径为空时「添加」保持禁用；`ui-workspace` 没有挂载时（合成里没有这一行）这个字段自动置灰，
+并用 `title` 说明改用 `workspace_dirs`，插件其余部分照常工作。
 
 > 唯一的例外是兜底入口：它是全局的、没有工作区上下文，所以那条路径下弹窗会退回显示选择器。
 > 正常使用中不会看到它。
 
+## 对话输入框里的 `@`
+
+在会话里打 `@` 会多出一组「工作区目录」候选 —— 就是已登记的标签，可以按标签、说明或路径过滤。
+选中后插入一个引用 chip：**chip 显示标签，提交给模型的是那个目录的绝对路径**。
+
+这样一来，即使注入的标签表因为上下文压缩而不在了，模型拿到的仍然是路径本身，指代不会失焦：
+
+> `@backend 加个健康检查` → 模型收到 `D:\proj\backend 加个健康检查`
+
+候选来自**所有已启用的工作区**，按工作区标题分节；**当前会话所在工作区排在最前**（能读到它的 cwd 时）。
+会话查找只是排序优化，不是前置条件 —— 早先按「只会话工作区」出候选的写法有个致命缺点：只要 cwd 读不到，
+整组就静默变空，而空菜单和坏 bundle 从外面看一模一样，无法证伪。
+
+实现要点（都在 [lib/client.js](lib/client.js) 里，用壳层的 input trigger 管线）：
+
+| 事项 | 做法 |
+| --- | --- |
+| 注册 | `ctx.inject(['inputTriggers'], …)` → `registerSource({ trigger: '@', name: 'workspace-plus', … })`；`(trigger, name)` 必须唯一，`@reference` 是官方占用的 |
+| 候选 | 所有 `enabled !== false` 且登记了目录的工作区；被设置页关掉的工作区自然被排除 |
+| 排序 | 从管道给的 `{ sessionId }` 反查 cwd（`sessions.list` 投影，与 `ui-reference`/`ui-session` 同一处），命中的工作区提到最前；读不到就按原序 |
+| **必须是 async** | 管线是 `source.candidates(...).then(...)` 直接调用 —— 同步返回数组会在它自己的循环里抛错 |
+| 分组标题 | `showGroupTitle: false` + 每行自带 `section`（工作区标题），否则标题会是管道字典里查不到的 key |
+| chip | `appearance: 'folder'` → 文件夹图标、且不会被标成可点开；点击时因为本 source 没有 `openReference` 而是安全的空操作 |
+| 序列化 | 本 source 自带 `codec.serialize(ref) => ref`；**chip 的 serializer 是按 source 名路由的，没有 codec 的 source 会让整次提交被拒** |
+| 自检 | 设置 → `workspace+` 里有一行「输入框 `@` 候选」，直接告诉你候选源是否已注册、共有多少标签 |
+
 ## ⚠ 沙箱：一个会话只有一个可写根
 
 DSH 的沙箱策略把每个会话的可写范围限定在 `SessionHeader.cwd`（也就是工作区目录）；
@@ -211,7 +284,7 @@ for (const root of writableRoots(policy)) if (await isPathUnder(fresh.targetKey,
 2. 保持 `workspace-write`，接受每次越界写入弹一次批准（agent 会按工具提示发起升级）。
 
 插件本身不做任何绕过沙箱的事，只是把限制如实告诉 agent（上下文里会标注哪些目录在根目录之外）
-和界面（行尾标注「工作区根目录之外」）。
+和界面（行尾一个黄色盾牌图标，悬浮或键盘聚焦时用 tooltip 说明原因）。
 
 ## 安装
 
@@ -230,14 +303,15 @@ dsh plugin --profile desktop add <本地 checkout 目录>
 
 `lib/` 是仓库里已提交的产物、包内没有 `prepare` 构建脚本，所以上面三种方式都不需要
 pnpm 的 `allowBuilds` 构建授权，装到的就是可直接加载的代码。想锁定版本可以用
-`github:Sen70s/dsh-workspace-plus#v0.1.1`。要求 DSH `>=0.1.7-rc.2`（桌面版当前就是
+`github:Sen70s/dsh-workspace-plus#v0.4.0`。要求 DSH `>=0.1.7-rc.2`（桌面版当前就是
 `@deepseek-ai/dsh-desktop 0.1.7-rc.2`；npm 上是 `next` 通道）。
 
 > 0.1.0 曾以包名 `dsh-workspaceplus` 发布；自 0.1.1 起更名为 `dsh-workspace-plus`，旧包已废弃，
 > 请勿再安装。
 
 装完后**重启 `dsh`** 并刷新页面。悬停任一工作区那一行，操作区会多出一个目录图标，点它打开弹窗；
-设置面板里会多出一个 `workspace+` 分区（默认工作区默认关闭，见下一节）。
+设置面板里会多出一个 `workspace+` 分区（默认工作区那一行默认关着，其它工作区默认开着，见下一节）；
+对话输入框里打 `@` 会多出一组「工作区目录」候选。
 
 卸载：
 
@@ -247,17 +321,62 @@ dsh plugin --profile desktop remove dsh-workspace-plus
 
 ## 使用
 
-界面上：悬停工作区行 → 点目录图标 → 填「标签 / 绝对路径 / 说明」→ 添加。弹窗已经锁定在这个工作区上，
-不需要（也不能）再选一次。默认工作区要先在 设置 → `workspace+` 里打开开关，它的行上才会出现那个图标；
-此时也可以直接在设置页里管理，或让 agent 用 `workspace_dirs`。
+我向来不惮于把话说明白，只是插件的用法，说一遍也就够了，不必绕弯子。
+
+### 一、先把目录登记上
+
+把鼠标停在左侧边栏的任意一个工作区上，那一行的右边会浮出三个小东西。头一个是「更多」，末尾一个是「新会话」，中间那个文件夹，是本插件的。
+
+![工作区行上的目录按钮](https://raw.githubusercontent.com/Sen70s/dsh-workspace-plus/main/docs/row-button.png)
+
+它排在中间，不是末尾 —— 末尾那个位置是壳层的，我不去占。人有各人的座位，插件也一样。
 
-对话里（工作区 = `D:\proj`）：
+点它，「工作区目录设置」就开出来了：
 
-- 「把 `D:\proj\backend` 加为 backend 标签，说明写后端 API」→ agent 调 `workspace_dirs add`
+![工作区目录设置弹窗](https://raw.githubusercontent.com/Sen70s/dsh-workspace-plus/main/docs/dialog-default.png)
+
+表格里是已经登记过的目录，一行一个：标签、绝对路径、说明，如此而已。若某个目录在工作区根目录之外，行尾会立一个小小的黄盾牌 —— 这个下面再讲。
+
+**路径是不用手打的。** 表单最上头那个带文件夹图标的格子，它本身就是个按钮。点它，系统的目录选择器就开了：
+
+![选好目录之后，路径与标签都填上了](https://raw.githubusercontent.com/Sen70s/dsh-workspace-plus/main/docs/dialog-picked.png)
+
+选中之后，路径落进格子里；标签若还空着，便从目录名里猜一个（`D:\proj\my api` → `my-api`；纯中文的目录名不猜，因为宿主不收，猜了也是白猜）。再补一句说明，点「添加」，完事。标签和说明占同一行，路径在它们上面那一行 —— 三样东西原本挤作一处，那是我的不是。
+
+### 二、那个黄盾牌
+
+目录若在工作区根目录之外，它就立在那里，不写字。非得你把鼠标放上去，或者用键盘 Tab 把它聚焦了，它才开口：
+
+![盾牌图标的浮层提示](https://raw.githubusercontent.com/Sen70s/dsh-workspace-plus/main/docs/dialog-tooltip.png)
+
+说的是：DSH 的沙箱只认工作区根目录这一个可写根；会话权限不是 `danger-full-access` 的时候，根目录之外只能读，要写就得逐次批准。这不是插件不肯通融，是它本来就只有这一条路。
+
+所以要图省事，**把工作区建在几个工程的共同父目录上**，让所有标签都落在里头。这是最省事的办法，也是唯一的办法。
+
+### 三、开关，一个工作区一个
+
+设置 → `workspace+`：
+
+![设置页里按工作区的开关](https://raw.githubusercontent.com/Sen70s/dsh-workspace-plus/main/docs/settings.png)
+
+一个工作区一行，一行一个开关。这个开关管三件事：那一行的目录按钮出不出现、标签表注不注入这个工作区的对话、`workspace_dirs` 认不认这个工作区。
+
+默认值并不整齐：**除默认工作区外，都默认是开的**；而默认工作区 —— 也就是 DSH 第一次启动时自己建起来的那一个 —— 默认关着。它属于产品，不属于这个插件，我不便替你做主。要用，把它那一行的开关拨开就是。
+
+关掉**不会删掉标签**。哪天想起来了再拨回来，目录还在那里。
+
+### 四、在对话里
+
+前提是工作区 `D:\proj` 底下挂了 `backend` 和 `docs` 两个标签。于是：
+
+- 打一个 `@`，菜单里多出一组「工作区目录」。选 `backend`，输入框里就落下一个 `backend` 的 chip —— 而**送给模型的是那个绝对路径**。这一点要紧：哪怕注入的标签表被上下文压缩挤掉了，模型手里那个路径也还是硬的。
+- 「把 `D:\proj\backend` 记成 backend，说明写后端 API」→ agent 调 `workspace_dirs add`
 - 「现在有哪些标签？」→ `workspace_dirs list`
-- 「把 backend 改指向 `D:\proj\backend-v2`」→ `workspace_dirs update`
-- 「删掉 docs 标签」→ `workspace_dirs remove`
-- 之后：「backend 加个健康检查接口」→ agent 直接用 `D:\proj\backend` 的绝对路径
+- 「backend 改指向 `D:\proj\backend-v2`」→ `workspace_dirs update`
+- 「删掉 docs」→ `workspace_dirs remove`
+- 诸事办完，才可以说那句：「backend 加个健康检查接口」。agent 去的是 `D:\proj\backend`，不会因为隔壁站着一个 `backend-legacy` 就摸错了门。
+
+标签表是每次请求都注入的，所以上面这些，多数时候你不说，它也晓得。
 
 ## 自检
 
@@ -267,29 +386,56 @@ dsh plugin --profile desktop remove dsh-workspace-plus
 node tools/verify.mjs
 ```
 
-它会（当前 `283/283 checks passed`，另有 1 项按环境跳过）：
+它会（当前 `387/387 checks passed`，另有 1 项按环境跳过）：
 
 - 校验 manifest、patch 层、`dsh.client.inject` 的取值；
 - 用临时 `DSH_HOME` 运行宿主半：标签/路径校验、增删改、去重、大小写折叠、损坏文件容错、原子写；
-- 用假的 Cordis ctx 验证三处注册，并**真实执行** `workspace_dirs` 的 list/add/remove；
+- 用假的 Cordis ctx 验证各处注册，并**真实执行** `workspace_dirs` 的 list/add/remove；
 - 用假的 `node:http` req/res 真实调用 HTTP 路由的 GET/POST/405/401 分支；
 - 在 `node:vm` 里加载浏览器半，用**最小 DOM 替身**（只实现本插件用到的那几个选择器）真实驱动
   工作区行按钮：挂载前不误报、按行注入、未分组行跳过、重复对账幂等、行移除后回收、
   点击只开弹窗而不冒泡到行、dispose 清理干净；
 - 校验弹窗的外部 store（打开/切换/关闭/退订）与各槽位注册，
   校验行按钮 CSS 与壳层 `.iconButton` 的度量一致（16×16、无底色、hover 只变色），
-  校验**默认工作区闸门**（宿主快照标 disabled 后行按钮消失、开关打开后回来、探测失败会重试），
+  校验样式表在**模块热重载**后仍是一个、且是当前版本的 tag（不会新旧并存），
+  校验**按钮的位置**（落在「更多」和「新会话」之间、新会话保持最后一个、被 React 挤走后会自动归位、
+  只有一个子节点时退化为排在菜单之后、dispose 后壳层自己的按钮原样不动），
+  校验**工作区闸门**（宿主快照标 disabled 后行按钮消失、开关打开后回来、探测失败会重试），
+  校验**按工作区设置**（覆盖能关掉一个平时开着的工作区、也能打开默认工作区、覆盖优先于默认值、
+  `null` 恢复默认、非法值整批拒绝且一个字节都不写、旧状态文件缺这一层照常工作、
+  设置页一个工作区一个开关、按键由宿主下发而不是从路径猜、旧宿主没有 key 时置灰并提示），
+- 校验**弹窗的形状**（卡片被拉宽到 760px、description 与脚注都不再渲染、
+  「工作区根目录之外」不再是行内文字而是带 tooltip 的盾牌图标、路径是控件而不是输入框且位于标签行之上、
+  路径为空时「添加」禁用），
   校验**目录选择器**（标签猜测始终满足宿主语法、取消不改变任何字段、失败被捕获并给出原因、
-  没有挂载 ui-workspace 时按钮自动置灰且不会调用），
-  并用最小 React + Button/Switch/Modal 桩**真实渲染**设置页（含拨动开关 → POST 一次 settings op →
-  共享快照更新）与弹窗/面板的各状态文案。
+  没有挂载 ui-workspace 时字段自动置灰且不会调用），
+- 校验 **`@` source**（触发器的唯一性、`candidates` 返回 thenable、按标签/说明/路径过滤、
+  默认工作区关闭时不出候选、pick 产出的 chip 与它序列化出的绝对路径一致、坏 payload 不插入），
+  并用最小 React + Button/Switch/Modal/Tooltip 桩**真实渲染**设置页（每个工作区一个开关 →
+  POST 一次按键的 settings op → 共享快照更新）与弹窗/面板的各状态文案。
 
 ## 故障排查
 
+### 输入框打 `@` 有「文件与文件夹」，但没有「工作区目录」
+
+**先看 设置 → `workspace+` 里的「输入框 `@` 候选」那一行**，它把三种情况分开了：
+
+| 那一行显示 | 含义与处理 |
+| --- | --- |
+| `候选源未注册` | 当前页面跑的还是旧 bundle。**重启 `dsh` 并强制刷新页面**（Ctrl+Shift+R） |
+| `候选源已注册，但还没有可用的标签` | 代码是新的，只是没有可登记目录 —— 去工作区行里加标签；或者这个工作区是默认工作区而开关关着 |
+| `候选源已注册，共 N 个标签` | 代码和数据都就位。若菜单里仍看不到，多半是这一组的行被 `@reference` 的文件/会话组挤到可视区之外，滚动菜单看看 |
+
+**为什么必须重启而不能只刷新**：客户端 bundle 的 URL 带一个由 `mtime/ctime/size` 派生的 `rev`，
+而 rev 只在宿主重新组合模块图时才更新（`dsh-client-modules` 的 `rebuilt()`）。文件内容是在**首次 GET**
+时读取并缓存的，所以 rev 不变，刷新只会拿回缓存里的旧 bundle。宿主侧的重载驱动是 `dsh-hmr`，
+你 profile 里它的 `root` 是空的 —— 也就是不监听这个插件目录。
+
 ### 工作区行上没有出现目录按钮
 
 1. 先确认宿主半已加载（见下一条的判据）。
-2. **这个工作区是默认工作区，且 设置 → `workspace+` 的开关还关着** —— 这是默认行为。
+2. **这个工作区在 设置 → `workspace+` 里被关着**：默认工作区默认就是关的，其它工作区如果显示关了，
+   说明有人（或某个旧开关）把它关掉了 —— 打开它自己那一行即可，无需重启或刷新。
 3. 悬停工作区行才会显示操作区，这是壳层的行为。
 4. 兜底入口会在 1.2s 后出现在侧边栏（`workdirs`）；如果它出现了，说明行锚点没匹配上 ——
    多半是 DSH 升级改了行 DOM。此时功能仍然可用（走 `workspace_dirs` 工具或兜底入口），