dsh-client-ui-session-rail

---

description: "DSH 客户端插件:侧边栏收起时在左侧显示活跃会话横条(阻塞→已完成未读→运行中,三色);dsh web 落在 56px 图标轨道里,Windows 桌面端落在内容区左边缘的浮层里" kind: "plugin"

dsh-client-ui-session-rail

侧边栏收起时,在左侧竖排显示"活跃会话"横条。两种落脚形态(按 <html> 平台标记自动选):

轨道形态(dsh web 浏览器)          浮层形态(Windows 标题栏桌面)
┌──────────┐                      ┌──────────────────────────────┐
│   🐟     │  ← 品牌/收起按钮      │ 应用 编辑        ─ □ ✕      │ ← 40px 标题栏
│   ＋     │                      │ ▬▬  4. 要注意的代价          │
│   ✦      │                      │ ▬▬                           │
│   🔍     │                      │ ▬▬  正文…                    │
│          │                      │ ▬▬                           │
│   ▬▬     │ ← 阻塞(琥珀)        │ ▬▬  ← 24px 窄浮层压左留白   │
│   ▬▬     │ ← 阻塞                │                              │
│   ▬▬     │ ← 已完成未读(绿)      │                              │
│   ▬▬     │ ← 运行中(蓝,呼吸)    │                              │
│          │                      │                              │
│   ⚙      │  ← 设置              │                              │
└──────────┘                      └──────────────────────────────┘

• 顺序:阻塞 → 已完成未读 → 运行中,同档按最近更新倒序。
• 初始形态:与右侧对话索引同构的 20×2px 圆角横条,静止缩到 60%,悬停/聚焦放大到 100%。
• 悬停:右侧弹出详情卡(会话标题 / 状态 · 多久以前 / 工作区)。
• 点击:跳到该会话(uiWorkspace.openSession),侧边栏保持收起。
• 空闲会话不进栏,所以栏里出现的每一条都是"有事在等"的会话。

状态与配色

优先级照抄侧边栏状态点:阻塞 > 自己运行 > 子代理运行 > 已完成未读 > 空闲。 只有子代理在跑的会话在侧边栏也是"进行中",所以这里同样进栏;悬停卡片会补一句 "N 个子智能体运行中"。子代理清单取自该会话的 subagentCatalog 投影,每个子代理的 running 先看状态快照、再看目录行(与 ui-workspace 的 runningChildCount 一致)。

实现要点

三个落点全部走座位契约,不读别的插件的 DOM / 样式 / 组件源码:

1. sidebar.footer.action(ui-sidebar 声明的 root 级 list 座位)——它的 owner props 带 wide, 这是框架给插件看"侧边栏是否收起"的唯一正规通道。本插件在那里注册一个不渲染 DOM 的探针, 把 wide 发布到模块内的折叠态源。Windows 桌面端收起时该座位仍然挂载(ui-sidebar 只是给 footArea 加了 display:none,React 组件不卸载)⇒ 探针照常发布 wide === false,不用另找信号。
2. shell.overlay(ui-layout 声明的 frame 级浮动层,在列容器之外、z-index 20)——横条栏渲染在这里: left:0 + 垂直居中。宽度走 CSS 变量 --sr-track:轨道形态 56px,浮层形态 (.sr-frame--overlay,判据是 <html data-windows-titlebar>)24px。 不用 position:fixed 挂在探针身上:祖先一旦有 transform/filter,fixed 就改成相对该祖先定位, 收起动画留下的 transform 会让横条错位。
3. 数据来自标准 props:useSessions(会话目录)、useSessionStatus(running / pendingInteraction / completionUnread)、useWorkspaces(归档集 + 工作区标题)。跳转回调与 t 走注册的 inject 面。

样式只吃主题令牌(--dsw-alias-* / --dsw-radius-lg / --dsw-elevation-panel / --dsw-font-*), 浅色深色自动跟随;prefers-reduced-motion 下关掉呼吸与过渡。可见文案走 locale 服务 (命名空间 sessionRail,zh/en 双词典)。

已知边界

• macOS 桌面不出图:ui-layout 在 darwin 收起时把 sidebarCol 整个从 DOM 移除(不是压成 0), 既没有轨道也没有内容列左留白可压,本插件在那里返回 null。
• Windows 桌面端走浮层形态:ui-layout 对 Windows 标题栏桌面把收起宽度设为 0 (collapsedWidth = darwin || hasAttribute('data-windows-titlebar') ? 0 : 56),整列压平。 本插件改成贴内容区左边缘的 24px 窄浮层 —— 实测 1280×720 最大化窗口下内容列左留白约 85px, 24px 只压住留白、不碰正文;窗口更窄时留白随之收窄,理论上到 24px 内边距才会开始压字。
• 子代理只算直接子代理:清单来自该会话自己的 subagentCatalog 投影(侧边栏同源); 子代理会话自身仍不进栏(侧边栏也不列)。
• 归档过滤依赖工作区快照:useWorkspaces 缺席时退化为不过滤归档会话(并留一条控制台告警)。
• 横条栏是浮层,不吃鼠标事件的部分(横条之间的空隙)会穿透到下层界面。

安装与启用

本包是 profile 组合包(bundle):装进 profile 后,插件页「已安装」里的总开关写 dsh.profile.bundles,行级开关向 profile 的 cordis.patch.yml 写 disabled 覆盖。

# 安装(或重装以刷新链接)
# 用 plugin_manager 工具:action=install_bundle, target=<本包绝对路径>

客户端插件的加载边界:页面必须在插件装好之后打开(或刷新)。本机实测:宿主侧 dsh-client-hmr 的 /plugins/events 实时图同步在这个页面上没生效 —— 停用另一个客户端插件 (@michengai/dsh-btw)后宿主条目确实消失,而页面里的注册仍在。所以装完新插件要刷新一次页面 (F5);刷新后 sidebar.footer.action 座位里应出现 session-rail-probe、shell.overlay 里应出现 session-rail(可用 cordis_inspect_query 查 Slots 核对)。

验收状态

2026-09-30 桌面端浮层形态(本轮新增)

• 背景:本机 DSH 于 2026-09-30 从 dsh web 切到官方桌面端 0.2.0-rc.2,横条栏在桌面端完全不出图。 根因两条:ui-layout 对 Windows 标题栏桌面把 collapsedWidth 设成 0 (darwin || hasAttribute('data-windows-titlebar') ? 0 : 56),整列压平;而本插件原来的 railExists() 正是靠同一个 data-windows-titlebar 标记判"不出图"。
• 改法:railExists() 只保留 darwin 的否决;新增 overlayMode()(判据仍是 data-windows-titlebar), 浮层形态下把轨道从 56px 收窄到 24px、贴内容区左边缘(见「实现要点」与「已知边界」)。
• 实测(2026-09-30 18:0x,1920×1080 最大化窗口,cordis_inspect_query + Cua Driver 后台投递, 全程未抢前台):
  • Slots.listSubTree(root="shell.overlay") 的 occupants 里有 {id: "session-rail", order: 10, active: true}; root="sidebar.footer.action" 里有 session-rail-probe ⇒ 两半都注册上了。
  • 点标题栏左侧的收起按钮后,抓屏在窗口左边缘竖排出现两根横条:绿色(已完成未读)在上、 蓝色(运行中)在下,位于 x≈30–50、垂直居中 —— 与设计一致。
  • 同屏量到内容列左内边距 ≈196px(收起态),24px 的浮层完全落在留白里,不压正文。
  • 单测 40/40(node tests/derive.test.mjs)。
• 本轮未实测:浮层形态下的悬停详情卡与点击跳转。原因是本机前台被别的窗口占着, Cua Driver 对 Chrome_WidgetWin_1 的后台 hover/drag 不可用,而抢前台会打断用户正在做的事 (本机当时有游戏在跑)。这两条代码路径本轮未改动,浏览器形态下此前已由用户实测通过。

2026-09-26 浏览器形态(原始验收)

已实测:

• 宿主行 include:session-rail 生效;刷新后两个座位条目都注册上了。
• 侧边栏收起时横条栏出现:UIA 树里 Group "活跃会话" + 三条 Button "<标题> · <状态>", 顺序 = 阻塞在前、运行中在后,无障碍名走的是词典中文(证明 locale 座位与词典注册都生效)。
• 抓屏量像素(1280×720 逻辑坐标):阻塞条 rgb(245,158,11) = --dsw-static-amber-500; 运行中条 rgb(79,106,153) = 深色主题的蓝色强调色 #7aaaff 按呼吸动画的半透明叠加; 两条运行条处在不同呼吸相位(动画在跑);条宽 18px = 20 CSS × 静止 0.6(与右侧索引同构)。
• 单测 37/37(node tests/derive.test.mjs)。

未能由我实测(工具面限制,不是已知缺陷):点击跳转。本机浏览器窗口是 Chrome_WidgetWin_1,Cua Driver 拒绝后台投递键鼠;move_cursor 移动真实指针后页面收不到 hover(条宽仍是静止态的 18px),而抢前台会打断用户正在做的事,故没有继续。

用户实测补充(2026-09-26):悬停详情卡能出,但移开鼠标后不消失 —— 已修 (横条补 onPointerLeave/onPointerCancel,原先只挂了 onBlur,鼠标划过而没点过时收不掉); 新增的渲染层用例会断言这两个处理函数存在,防止回归。

用户实测补充(2026-09-27):点绿色"已完成未读"横条跳转后,横条消失而详情卡留存, 划过别的横条才恢复 —— 已修,根因见「踩过的坑」的"卡片比横条活得久"一条。 回归用例走 tests/derive.test.mjs 的 mountRail(带 hook 槽位、能重复渲染的 harness)。

开发

lib/client.js          浏览器半侧(唯一有行为的文件):纯函数 + 组件 + apply
lib/index.js           宿主半侧:空 apply(只为让加载器发现本包)
cordis.patch.yml       profile 层 patch(一行 insert)
tests/derive.test.mjs  纯函数单测 + apply 冒烟 + 渲染层用例(node tests/derive.test.mjs,40 例)

测试里有两个 React 桩:reactStub 无状态,只够断言"处理函数挂上了没"; 需要跨渲染的用例(详情卡在横条消失后要收掉)用 mountRail —— 带 hook 槽位、 能重复渲染并在提交后冲刷 effect 的最小 harness(等价于真实 React 的 fiber 复用)。

改代码后:工作区这份是 link: 进 profile 的(实测 profile 里是 Junction), 改文件即时生效;但页面仍需刷新才会重新执行 bundle。

踩过的坑

• 卡片比横条活得久:点绿色"已完成未读"横条跳转 ⇒ uiWorkspace.openSession 把该会话 变成主视图 ⇒ ui-session 的 reconcileStatus 当帧清掉 completionUnread ⇒ 横条从行里消失。 指针正压在那根横条上,而横条卸载时浏览器只对已脱离文档的节点发 pointerleave, React 的 onPointerLeave 收不到(焦点路径同理:被移除的按钮不再发 blur)⇒ preview 留在旧行上,详情卡挂着一根不存在的横条,直到划过别的横条才被换掉。 修法是让卡片只对"还在栏里的横条"负责:行里查不到 preview.row.id 就收卡片 (行还在、只是换档时不收,免得鼠标还停在横条上卡片却闪没)。
• 详情卡只挂 onBlur 收不掉:卡片自己是 pointer-events:none,收不到任何鼠标事件; 鼠标划过横条(没点过、没聚焦)时不会触发 blur,卡片就一直挂着。横条必须自己处理 onPointerLeave(顺带 onPointerCancel,指针被系统抢走时也要收)。
• --dsw-alias-brand-primary 不是蓝色强调色:这套设计里它是"品牌墨色" (--dsw-static-neutral-bluish-1000,浅色主题近黑),深色主题下画出来是浅灰横条。 实测抓屏量到 rgb(178,178,179) 才发现。蓝色强调色是 --dsw-alias-state-business-primary (= --dsw-static-deepseek-500 #4176e6)。单测里加了一条断言禁止再用 brand-primary 当强调色。
• inject 必须声明全:动态客户端包的 apply 会等到 inject 里的服务全部就位才跑。 最初只写 ["slots"],apply 在 slots 一就绪就执行,那时 uiWorkspace / locale 还没被各自的 插件 provide,ctx.get("uiWorkspace") 返回 undefined ⇒ 整插件静默不注册(座位表里查不到条目, 页面无任何表现)。现在是 ["slots", "uiWorkspace", "locale"]。
• locale: NS 与词典注册的顺序:ui-locale 的 apply 里 provide("locale") 之后同步 installLocale(),所以等到 locale 服务再执行就一定能拿到框架合成的 t 座位;服务缺席时组件 退回中文兜底,不硬崩。
• 探针与横条栏的时序:探针的 effect 先于浮层的订阅 effect 跑,横条栏在订阅时补读一次当前值 (setValue(collapsedValue)),否则"一开始就是收起态"会漏掉第一次发布。