指令悬浮气泡 Ary66101/dsh-instruction-bubble

dsh-instruction-bubble

DSH Web GUI 客户端插件：在会话顶部（对话区视口上沿）悬浮一条长气泡，显示最近一条已经滚出视野顶部的用户指令；随滚动逐条切换为上一条指令。

行为

- 指令 = 普通用户消息（user）+ 中途插话（steering）；不含 /命令 与系统注入上下文。
- 最新指令仍在视野内 → 显示上一条指令；被推出视野顶部后 → 显示最新指令；继续上翻逐条切换。
- 没有任何指令被推出视野时显示视野内最靠上的指令（须存在对应 DOM 行）；空白会话不显示。
- 纯展示：pointer-events: none，不拦截任何鼠标操作。
- 与主题联动：使用 --dsw-alias- 主题令牌（暗/亮自适应，均带兜底值）、背景模糊、≤2 行截断、小字号。
- 气泡始终悬浮在对话区视口上沿并随对话区中轴居中；若安装了 dsh-better-sidebar，气泡会跟随右侧面板的开合平滑滑动。

兼容性

| 维度 | 要求 / 说明 |
| DSH 版本 | 需要 DSH ≥ 0.1.0-rc.6 的 web 客户端（shell.overlay 插槽要求注册带 options.id）；已在 0.1.1-rc.2 实测 |
| 浏览器 | Chromium 系（Chrome / Edge）；仅使用标准 API（ResizeObserver / requestAnimationFrame / getBoundingClientRect）+ React ≥18 的 useSyncExternalStore（react 由宿主模块表提供，本插件零 npm 依赖） |
| 平台 | 无平台依赖（浏览器端纯 JS）；仅安装说明中的“junction 备选方案”是 Windows 特例 |
| 核心 UI 属性 | 依赖 DSH web 的 3 个 DOM 属性：[data-conversation-scroll]、[data-chat-flow-kind]、[data-chat-flow-key]。它们当前版本内稳定，但属内部实现——若未来 DSH 改名，插件会静默不显示（不会报错或破坏 GUI） |
| 右侧面板 | [data-dsh-panel]（dsh-better-sidebar）用于“跟面板滑动”的增强动画；未安装 better-sidebar 时优雅降级：气泡仍正常工作（按对话区居中），只是没有随面板滑动 |
| 其他插件 | 无冲突设计：shell.overlay 为追加式插槽，气泡 pointer-events: none，z-index 60 |

安装

在 DSH web profile 目录（~/.dsh/profiles/web）执行：

方式 A：从 git 仓库安装（推荐）
pnpm add

方式 B：本地路径安装
pnpm add file:

然后关键一步：编辑 profile 的 package.json，把 "dsh-instruction-bubble" 追加进 dsh.profile.bundles 数组 —— boot 图只由 dsh.profile.bundles 栈组成，不添加则插件不会加载（不是扫描 node_modules）。

最后重启 dsh web（boot 图在启动时组成并缓存），浏览器硬刷新（Ctrl+Shift+R）。

备选：pnpm 11 供应链策略拦路时

如果 pnpm add 因 minimumReleaseAge 策略拦截 lockfile 校验（registry 条目发布不足 24h；项目级 .npmrc 设 minimumReleaseAge=0 实测无效），改用确定性手工安装：

Windows：在 profile 的 node_modules 建 junction 指向本插件目录 New-Item -ItemType Junction -Path "$HOME\.dsh\profiles\web\node_modules\dsh-instruction-bubble" -Target ""

package.json 的 dependencies 记录： "dsh-instruction-bubble": "link:" 再追加 dsh.profile.bundles 条目（同上），重启 dsh web + 硬刷新

macOS / Linux 下把 junction 换成 ln -s 即可。git 依赖通常不受该策略影响，优先走方式 A。

卸载

1. 从 dsh.profile.bundles 移除 dsh-instruction-bubble；
2. 移除依赖（profile 目录执行 pnpm remove dsh-instruction-bubble，或删除 junction 与 dependencies 条目）；
3. 重启 dsh web，硬刷新。

开发

npm test # node:test 单测（rule.js 纯逻辑；10/10）
node scripts/build.mjs # 生成 lib/client.js（__ModuleLoader__.load 注册；字节确定性）

产物 lib/client.js 提交入库；改动 src/client/ 后重新构建即可。

原理

- 挂载：shell.overlay 插槽（追加式浮层，list 型插槽注册必须带 options.id——DSH ≥ 0.1.0-rc.6 的 SlotCore 缺 id 会在加载期抛错）+ position: fixed 锚定 [data-conversation-scroll] 顶边。
- 数据：useSessions((s) => s.current) 取当前会话，经 ctx.sessions.binding(id).session（ConversationSnapshot）→ chat.order/chat.nodes 筛出 user/steering。
- 定位：[data-chat-flow-kind="user"|"steering"] 消息框 getBoundingClientRect().bottom ≤ 视口顶边 + 4px 视为已滚出。
- 居中：以“对话区可见右边界”计算中轴——右侧面板（[data-dsh-panel]）存在且可见时取其左缘逐帧跟随，否则取滚动区右缘；跟随期间内联关闭 CSS 过渡（逐帧本身就是动画），静止后恢复 0.2s 平滑过渡。
- 节奏：滚动/窗口缩放/visibilitychange/快照发布/面板滑动 → rAF 节流重算 + 500ms 轮询兜底；几何去重（frameRef）避免无谓重渲染。

文件结构

src/client/rule.js 纯逻辑（文本提取/指令列表/选择规则，可单测） src/client/index.js 浏览器入口（组件 + DOM 接线 + 样式注入） scripts/build.mjs 零依赖迷你打包器（ESM → __ModuleLoader__.load 工厂） test/rule.test.mjs node:test 单测 lib/client.js 构建产物（提交入库）

许可证

MIT