工作区聚焦 wuenna/dsh-workspace-focus

dsh-workspace-focus

一个 DSH Web 插件，在侧边栏的工作区浏览器标题栏中添加一个眼睛切换按钮，位于内置的搜索、视图选项和添加工作区按钮旁边。当该切换按钮处于激活状态时，侧边栏仅显示包含当前会话的工作区——其他所有工作区都被隐藏。

┌ 工作区 ─────────────── ⌕ ≡ ＋ 👁 ┐ ← 插件的按钮，位于该行最后 │ ▾ .dsh │ │ 53 分钟 │ ← 仅显示当前会话的工作区 └───────────────────────────────────────┘

行为

| 关闭（默认） | 列出所有工作区，与内置浏览器渲染的完全一致。图标为带斜杠的眼睛。 |
| 开启 | 仅列出包含当前会话的工作区——其他分区完全不显示，而不是被收集到某个分组中。图标为睁开的眼睛，并带有品牌色着色。该选择在重新加载后仍然保留（localStorage["dsh.workspace.focus.v1"]）。 |
| 嵌套工作区 | DSH 0.1.6 可以将工作区排列为树形结构。被聚焦的工作区与其包含它的祖先一起保留，其他所有分支都被隐藏。 |
| 无当前会话 | 按钮被禁用，其工具提示会说明这一点。该切换按钮永远不会被开启到隐藏一切的状态。 |
| 右侧面板已打开 | 当面板接管选择时，主视图不再保留会话。聚焦模式会继续记住最后一次有应答的工作区，因此列表不会因为用户看不到的原因而闪烁消失。 |
| 列表模式“单一列表” | 侧边栏的视图选项可以取消分组。此时没有工作区分区，聚焦模式不隐藏任何内容；一旦恢复分组视图，它就会再次生效。 |

工作原理

侧边栏在带有 role="tree" 的列表中为每个工作区渲染一个分区——这正是内置的 groupByWorkspace 所产生的结果；自 DSH 0.1.6 起，它也可以按路径将它们嵌套在 role="group" 包装器内。聚焦模式仅应用于该渲染后的标记，而不应用于其他任何地方：包含当前工作区的分区保留其位置，其他每个分区获得一个标记属性，插件样式表中的一条规则将该标记转换为 display: none。

// 插件用于过滤的整个样式表
[data-dsh-workspace-focus-tree] [data-dsh-workspace-focus-hide] { display: none }

标记分区而不是缩小存储范围才是关键所在，值得详细说明为什么存储是错误的切入点。内置功能从会话派生其分区，并与工作区列表交叉引用：

for (const workspace of workspaces) { /* members from workspace.sessionIds / }
const stray = list.ids.filter((id) => !accounted.has(id)); // → the "未分组" bucket

因此，缩小工作区列表并不会缩小侧边栏。每个其工作区从列表中消失的会话都会变成“游离”会话，并被扫入内置的 Ungrouped 桶，因此隐藏四个工作区会产生第五个分组，其中包含它们所有的会话。这里没有触及框架存储的任何内容，因此那个桶永远不会被填充，而用户要求隐藏的内容只是不被显示。

哪个会话是当前会话

插件读取这一点的方式与内置功能相同，而这在 DSH 0.1.6 中发生了变化。会话列表不再携带 current 字段——它是 { ids, byId, phase, … }——而主视图正在显示的会话现在是主视图仍然保留的那个：即 retainedBy.mainView 非零的那一行。旧字段仍然作为回退被支持，因此插件可以在该变更前后的构建上运行。

哪些部分保留

当前会话自己的行——即 aria-selected 的 role="treeitem"——是权威依据，这是有意为之：它不说明内置功能如何安排其各个部分。该行与树之间的每个部分都是必须保留的工作区，当工作区嵌套时，这会得到聚焦的工作区及其祖先，并且如果宿主重新排序其工作区，它仍能继续工作。

当该行不在屏幕上时（聚焦的工作区被折叠，因此它完全不渲染任何会话行），则改用较旧的位置映射：按照宿主的顺序，每个工作区对应一个部分，并与侧边栏渲染的标签进行核对。当各个部分嵌套时，该映射没有意义，因此只有在每个部分都是树的直接子级时才会尝试它。

值得了解的后果：

- 框架的工作区和会话存储是只读的——插件订阅它们以跟随选择，并且从不写入它们。
- 每个不确定的情况都会失败为显示更多：没有当前会话、无法识别的列表形状，或某个部分的渲染标签与其应代表的工作区不匹配，都会让列表保持原样。门控属性位于树上，因此去掉那一个属性就会显示所有内容。
- 布局切换不会闪烁。 将侧边栏折叠到其栏轨会使内置功能渲染出完全没有子级的列表区域，因此树——以及其上的每个标记——都会被卸载；展开时会以裸状态挂载各个部分。文档上的 MutationObserver 会重新标记它们，并且由于它的回调在帧绘制之前运行，过渡过程永远不会先显示完整列表。其下还有一个一秒间隔作为兜底。

查找内置标记的各个部分

这里没有任何内容固定 CSS 模块类名：那些类名是内容哈希的，并且会随所发布 bundle 的每次重新构建而变化。两个锚点都是结构性的。

- 树是 [role="tree"]——那个*其分支有一个持有按钮的兄弟节点的树。从树向上爬升会经过父级，直到树的那个分支有一个持有按钮的兄弟节点的层级，也就是部分标题；不计算任何层级，因此额外的包装器不会破坏它。一个树 React portal 直接到 body —— 子代理谱系菜单 —— 没有这样的兄弟节点，并且会被同一次遍历拒绝。
- 操作行是包含按钮且没有文本输入的头部子节点，这正是它与旁边的搜索槽位区分开来的依据。一个内置按钮就足以证明该行的存在，因此即使内置只渲染其中一个按钮，插件也能继续工作。

该按钮复制兄弟节点自身的类列表，因此它继承图标按钮的悬停、形状和尺寸。

第三个按钮需要空间

内置的操作行被限制为恰好其两个按钮的宽度（两个 28px 按钮加 4px 间隙时为 max-width: 60px），并裁剪放不下的内容，因此如果不提高该上限，第三个按钮将不可见。插件在 CSS 中完成此操作，作用域限定在标记的头部，并用 :has() 匹配：

[data-dsh-workspace-focus-header]:has(button[aria-expanded="false"]) > [data-dsh-workspace-focus-row] { max-width: 96px }

将其写成样式表规则而不是 JavaScript 样式写入，正是保持内置权威性的原因：当搜索框展开时，aria-expanded 翻转为 true，该规则停止匹配，内置自身对该行的折叠再次生效——无需观察状态，无需重新应用，也不存在该行在搜索字段上方保持宽度的窗口期。该行的自然宽度由其内容决定，因此只有一个按钮的内置不受提高后的上限影响。

眼睛字形是内联绘制的：随附的图标集中不包含眼睛或可见性图标。

布局

| 文件 | 作用 |
| lib/index.js | 宿主半部分——有意留空。它的存在是为了让 Loader 扫描该行，而正是它组成了浏览器 bundle。 |
| lib/client.js | 浏览器半部分——整个功能。 |
| cordis.patch.yml | 该包自身的 bundle 补丁：宿主行。 |
| test/client.test.mjs | 自包含检查：一个带有小型选择器匹配器的 DOM 替身，复现内置浏览器的真实嵌套（包括工具提示包装器和头部的搜索输入），以及服务替身。从包根目录运行 node test/client.test.mjs。 |

安装

该插件位于 ~/.dsh/plugins/dsh-workspace-focus，链接到 Web 配置文件中，与 dsh-deepseek-cost 完全一样：

New-Item -ItemType Junction
-Path "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-workspace-focus"
-Target "$env:USERPROFILE\.dsh\plugins\dsh-workspace-focus"

有三件事使它加载，且三者都需要：

| 位置 | 内容 |
| ~/.dsh/profiles/web/package.json | dsh.profile.bundles 列出 dsh-workspace-focus，并且 dependencies 将其链接为 link:../../plugins/dsh-workspace-focus。 |
| cordis.patch.yml（该包自身的） | dsh.bundle.patch 挂载宿主行 workspace-focus。 |
| lib/index.js | 有意留空的宿主半部分。Loader 只会为包可解析的行组成浏览器 bundle。 |

注册不得在配置文件的 ~/.dsh/profiles/web/cordis.patch.yml：bundle 层先运行，而 insert 是追加，因此同一行 id 会被挂载两次。一旦这些就位，内置插件管理器就拥有该行，并可以在自己的页面中启用或禁用它（plugins.json，rowId workspace-focus）。

适配框架更新

一次升级可能会移动此插件所读取的内置界面。一个消失的开关几乎总是以下情况之一，按此顺序——在修改代码之前先检查它们。

1. 重新加载页面。 一次框架升级会同时替换许多客户端 bundle，此插件的依赖也在其中。仍持有升级前模块图的页面可能完全缺少插件行；重新加载会重新组合模块图。确认插件确实在其中：

curl.exe -s -N --max-time 6 -o "$env:TEMP\events.txt" http://127.0.0.1:3080/plugins/events
Select-String -LiteralPath "$env:TEMP\events.txt" -Pattern 'dsh-workspace-focus'

（curl 在该流上按设计以 28 退出；负载仍会被写入。）
2. 服务。 apply 注入 workspaces、sessions 和 locale。在 0.1.7 中，工作区浏览器还提供了一个新的 uiWorkspace 服务——那是新增（目录选择、归档），而不是对 workspaces 的重命名。
3. 快照形状。 sessions.list 现已变更两次：0.1.6 弃用了 current，改用 retainedBy.mainView，而 0.1.7 用 projectionsBySession 替换了 subagentsByParent/jobsBySession。这里只有保留字段重要，而它在两次变更中都保留了下来。
4. DOM 锚点。 对照 node_modules/@deepseek-ai/dsh-client-ui-workspace/lib/client.js，重新验证查找内置标记的各个部分下列出的锚点。
5. 运行测试。 node test/client.test.mjs。它们覆盖的是逻辑，而不是内置界面的标记，因此一次通过但开关缺失的运行指向锚点 4 （或锚点 1）。