工作区运行徽标 yanli-nyan/maid-workspace-activity

maid-workspace-activity · 工作区运行徽标

在 深海女仆工坊 皮肤（@smalltailqwq/dsh-client-ui-skin-maid-atelier）下，让左侧栏 一眼看出哪些工作区有任务正在运行，不必逐个展开。

皮肤包本身零改动——这是一个独立的 DSH 客户端 UI 插件，皮肤升级（0.1.8 → …）不会覆盖它。

简体中文 · English

问题

宿主插件 @deepseek-ai/dsh-client-ui-workspace 渲染侧栏时：

- 工作区分组行（ProjectRowItem，data-row-key="workspace:<key>"）只渲染文件夹图标、箭头、标题和菜单按钮——没有任何运行状态位；
- 状态点（StateDot）只挂在会话行上：showStatus = primaryStatus.state !== "idle" 时才渲染；
- 更关键的是，deriveGroups 里折叠态是 sessions: expanded ? … : []，组行连子会话数据都不携带。

所以「哪些工作区有任务在跑」在工作区这一级结构上无处可看，必须逐个展开。

女仆皮肤把工作区行放大成了视觉焦点（54px 行高、缎带、浮雕文件夹），却继承了宿主的这个缺口，所以在该皮肤下问题格外刺眼。皮肤本身没有 bug，这是宿主设计使然。

做法

本插件做三件事，都不触碰皮肤与宿主的任何规则：

1. 工作区行徽标

把「工作区 → 运行中会话数」写回宿主工作区行的自有属性：

徽标完全由本插件自己的样式表用 ::after 绘制（呼吸感金蓝宝石点）。不插入 React 节点，
不覆盖宿主或皮肤的任何规则——皮肤在工作区行上没有用到 ::after，本插件只新增一个，
所以不冲突。data-maidrun-subtree="1" 时额外加一圈淡金外环，与「就是我本行在跑」区分开。

2. 折叠感知的子树聚合

宿主在「工作区树」分组模式下折叠父工作区时，会把子工作区行整段从 DOM 移除：

// 宿主 session 树 renderGroup（_asar_ws_client.js:3161）
const childRows = group.expanded ? children.map((child) => renderGroup(child, depth + 1)) : [];

被移除的行不再有落点，所以本插件把它们的运行数并入最近的仍在 DOM 中的祖先：父行替看不见的子树说话，不展开也能看出那棵子树里有任务在跑。展开后子行重新出现，各自就地显示，聚合自动撤销。多层折叠时穿透缺席的中间层，归到最近的在场祖先。

父子关系用与宿主 owningParentFolder / folderPath 完全相同的路径规则判定（Windows 反斜杠归一、大小写敏感），保证和宿主折叠行为一致。

3. 常驻胶囊 + 运行浮层（左下角）

在 shell.overlay 注册一个帧级常驻组件。这是唯一一个既全局常驻、又拿得到标准 hooks 的座位：

| hook | 用途 |
| useWorkspaces | 工作区 → sessionIds 归属、path（父子关系）、title |
| useSessionStatus | 每个会话的 running |

- 无运行：收缩成一枚 12px 小金环，不可点，不打扰。
- 有运行：展开成「N 个会话运行中」的胶囊，带脉冲金点。点击展开浮层，按侧栏顺序列出每个运行中的工作区及其运行会话数；点其中一项直接跳到该工作区正在跑的会话 （走宿主的 uiWorkspace.openSession）。点外部或按 Esc 关闭。

浮层读的是数据层而非 DOM，所以它不受折叠影响，是被折叠子树的可靠后备——即使行徽标因为宿主改版而失效，胶囊与浮层仍照常工作。

行元素重建由 MutationObserver 驱动重放（childList + body 上的皮肤标记属性）；本插件自己只写 data-maidrun，不在监听属性内，不会自触发。运行态一变还会经由 useEffect 依赖直接重写一次——会话开始/结束通常不改 DOM 结构，只重渲同样的行元素。

作用域

- JS：行定位只用宿主的 data-row-key^="workspace:"，所以皮肤尚未给行打上 data-maid-workspace-row 的窗口期同样生效。
- CSS：全部用 body[data-dsh-maid-atelier] 作用域限定。
- 离开女仆皮肤时组件直接返回 null：本插件所有样式都限定在皮肤作用域内，若继续渲染就会在别的皮肤下露出一段无样式的裸文本，所以这里显式判皮肤。
聚合逻辑照旧运行（hook 必须无条件调用），只是不画任何东西。

语义

按需求取两态：running === true 即运行中，其余为无。

宿主还存在「等待你回答/审批」的 pendingInteraction 状态（黄色警告点）。本插件不标记它，只回答「有没有任务在跑」。若日后想区分，加一态即可，聚合层已预留位置。

安装

方式一：DSH 插件页（推荐）

在 DSH 桌面端 → 左侧栏「插件」页 → 安装 里填以下任一绝对路径：

<本仓库克隆目录>\maid-workspace-activity # 目录路径，按 link: 装 <本仓库克隆目录>\build\maid-workspace-activity-1.1.0.tgz # 打包产物（build/ 不入库） <下载的 maid-workspace-activity-1.1.0.tgz> # 或从 Release 下载后填其绝对路径目录路径按 link: 装（该目录不能删也不能挪）；.tgz 结尾按 tarball 装。
装完完全退出并重新打开 DSH 桌面端。

desktop 配置档归桌面端应用独占管理，独立安装的 dsh 命令行会被拒绝（error: profile "desktop" is managed exclusively by the Electron application），所以请用 GUI 的插件页。

方式二：用 dsh 会话里的插件管理器安装

用 plugin_manager 的 install_bundle，target 传上面的绝对目录，等价。
（「会话内」指 dsh 命令行的会话，不是本仓库。）

卸载

在插件页移除该 bundle（或 remove_bundle）。注入的 与全部 data-maidrun 属性随插件卸载自动清除，皮肤始终零改动。

文件

| 文件 | 说明 |
| package.json | dsh.bundle.patch + dsh.client（platform:"web", immediately:true） |
| index.js | 宿主半边，空实现 |
| client.js | 浏览器半边：行徽标属性维护 + 折叠子树聚合 + 胶囊与浮层 + 样式表 |
| cordis.patch.yml | 把 dsh.client 入口挂进 Web 插件名册 |
| locale/zh.json、locale/en.json | Plugin Manager 读取的 meta.title / meta.description |
| icon.svg | 插件图标（本插件原创，MIT） |
| README.md | 本文件（中文，默认） |
| README.en.md | 英文版说明 |

详细说明

本文件是「能装、能用」的简要版。徽标的三种状态语义、折叠子树聚合的判据、浮层的交互细节、以及已知边界，都在：

- docs/详细说明.md（仓库内）
- 在线读：https://github.com/yanli-nyan/maid-workspace-activity/blob/main/docs/详细说明.md

微调落点（不改插件）

徽标与胶囊的位置都做成了 CSS 变量，写在自己皮肤样式或任何自建样式里即可覆盖，无需改本插件：

body[data-dsh-maid-atelier] {
/ 工作区行徽标距行右边缘的距离，值越大越靠左。默认 11px / --maid-workspace-run-badge-inset: 11px; / 胶囊在左下角的落点。默认 14px / 14px / --maid-workspace-run-capsule-inset: 14px; --maid-workspace-run-capsule-bottom: 14px; }

浮层的底部会自动跟随 --maid-workspace-run-capsule-bottom（+34px），所以只调胶囊变量不会让两者分家。

已知边界

- 依赖宿主工作区行的 data-row-key="workspace:<id>" 属性。宿主若改这个属性名，徽标会静默消失（胶囊与浮层仍正常工作，不会报错——它们读数据层，不读 DOM）。
- 折叠聚合只在行真的不在 DOM 中时生效。若宿主未来改成「折叠仍渲染但隐藏」，汇聚会失效，届时改判据即可（聚合层与渲染层是分开的）。
- 跳转走宿主的 uiWorkspace.openSession。它是硬依赖，已列入 inject
（['slots', 'locale', 'uiWorkspace']），并保留 ctx.get 与「点宿主会话行」两级兜底。
踩过的坑：最初只用 ctx.get('uiWorkspace') 这种未声明依赖的可选获取，取不到时浮层行会静默变成 disabled，而浏览器对 disabled button 不派发 click，表现就是「能看、能点、毫无反应」。教训：Cordis 里要用服务就写进 inject，不要靠 ctx.get 撞运气。
- 胶囊与浮层用 position: fixed 放在左下角。若侧栏底部有遮挡元素，可能需要微调 bottom / inset-inline-start。
- 未在真实浏览器里做过逐像素视觉验证；其余边界见 docs/详细说明.md。

版本

| 版本 | 变更 |
| 1.1.0 | 加入中文显示名（工作区运行徽标）、中文说明与 icon.svg 图标；另附英文版 README.en.md |
| 1.0.0 | 首版：工作区行运行徽标 + 折叠子树聚合 + 左下角胶囊与浮层 |