---

description: "DSH Web 客户端插件:侧边栏收起时,在左侧 56px 轨道的空白区竖排显示活跃会话横条(阻塞→已完成未读→运行中),悬停出详情卡,点击跳转" kind: "plugin"

dsh-client-ui-session-rail

侧边栏收起(56px 图标轨道)时,在左侧空白区竖排显示"活跃会话"横条。

┌──────────┐
│   🐟     │  ← 品牌/收起按钮
│   ＋     │
│   ✦      │
│   🔍     │
│          │
│   ▬▬     │ ← 阻塞(琥珀)      ┐
│   ▬▬     │ ← 阻塞              │ 本插件渲染的横条栏
│   ▬▬     │ ← 已完成未读(绿)    │ (垂直居中,最多 420px,超出内部滚动)
│   ▬▬     │ ← 运行中(蓝,呼吸)  ┘
│          │
│   ⚙      │  ← 设置
└──────────┘

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

状态与配色

档位	判定(与 ui-workspace 的行状态同口径)	颜色
阻塞	pendingInteraction.kind ∈ approval / plan-review / question	--dsw-alias-state-warn-primary(与侧边栏"等待审批"点同色)
已完成未读	completionUnread === true(且自己没在跑、子代理也没在跑)	--dsw-alias-state-success-primary(与"已完成"点同色)
运行中	自己 running === true,或名下还有 running 的直接子代理	--dsw-alias-state-business-primary(蓝色强调色)+ 1s 呼吸

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

实现要点

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

1. sidebar.footer.action(ui-sidebar 声明的 root 级 list 座位)——它的 owner props 带 wide, 这是框架给插件看"侧边栏是否收起"的唯一正规通道。本插件在那里注册一个不渲染 DOM 的探针, 把 wide 发布到模块内的折叠态源。
2. shell.overlay(ui-layout 声明的 frame 级浮动层,在列容器之外、z-index 20)——横条栏渲染在这里: left:0 + 垂直居中,正好落在轨道中段的空白区。不用 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 双词典)。

已知边界

• 只在真正还剩 56px 轨道时出图:ui-layout 对 macOS 桌面与 Windows 标题栏桌面把收起宽度设为 0 (整列压平,没有空白区可放),本插件在这两种平台不出图。
• 子代理只算直接子代理:清单来自该会话自己的 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-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(与右侧索引同构)。
• 单测 24/24(node tests/derive.test.mjs)。

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

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

开发

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

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

踩过的坑

• 详情卡只挂 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)),否则"一开始就是收起态"会漏掉第一次发布。