VinciBeans/dsh-smooth-plugin

dsh-smooth-scroll

让 DSH 会话滚底从瞬时跳变变成恒速平滑跟随

装上后，流式内容增长时消息列平滑跟随到底部，回到最新仍保持瞬时。

安装

需要已安装 DSH，并至少成功启动过一次 Web GUI。从 npm 安装（按 dist-tag 选择）：

1. npm latest（0.1.2-rc.1，与 next 同步）— 兼容 dsh v0.1.2-alpha.1 ~ 0.1.3-alpha.2：
dsh plugin --profile web add dsh-smooth-scroll
等价写法：dsh plugin --profile web add dsh-smooth-scroll@next

2. npm alpha（0.1.2-alpha.5）— 与 latest 同一契约代、兼容范围相同，保守通道：
dsh plugin --profile web add dsh-smooth-scroll@alpha

旧代 0.1.1-rc.2 不再挂在任何 dist-tag 上，仅可按确切版本安装（不兼容，见「兼容性」）。

源码安装（GitHub Release v0.1.3-alpha.2 即当前源码版）：dsh plugin --profile web add .。

快速开始

dsh plugin --profile web add dsh-smooth-scroll
dsh --profile web --dump-config          # 看到 dsh-smooth-scroll 层即安装成功
重启 dsh web，打开会话，流式内容平滑滚到底部

滚动行为

直接在原生 scrollTop 上做有节奏的平滑滚动，配合合成 getter：平滑期间 scrollTop 读到目标值，DSH 自身状态机看不到中间位置，不误判脱钩、不重复钉底。

- 速度剖面: 起步 0 到 0.9px/ms 用 240ms 缓升，巡航恒速 0.9px/ms，收尾 220ms 软着陆。
- 用户滚动接管: 真实位置连续偏离动画写入 ≥2 帧才停动画，DSH 正常脱钩，回到最新按钮照常；单帧偏差（浏览器滚动锚定等一次性非用户位移）自动重基后继续钉底跟随——发送消息等操作引发的非用户位移不会导致误判脱钩或停在信息处；内容收窄导致的夹紧则在 2 帧内停止于新底部（同样不掉队）。与之对称，孤立的一次性小幅定位（如滚动条点一格）也会被当作非用户位移吸收、随后被跟随回底部；只有持续 ≥2 帧的偏离才视为用户接管。另：主机内（输入栏除外）的指针按下立即停动画并让 getter 回落真实值——turn 导轨跳转（landOnRow 的 el.scrollTop += flowTop - 24 复合读改写）由此读到真实位置，落点不被合成目标偏移（真实宿主 e2e 实测：流式中点击「跳转到第 N 轮」后漂移 0px）。
- 同目标兜底: DSH 每滚动事件重跑 toBottom 而目标不变时忽略，动画不被逐帧重启。
- 减少动效: prefers-reduced-motion 时完全回退官方瞬时行为。
- 无 transform: 不应用任何 transform，输入栏 overlay/sticky 永不受扰。

参数

| 常量 | 默认 | 含义 |
| --- | --- | --- |
| VEL | 0.9 | 巡航速度（px/ms） |
| RAMP_MS | 240 | 起步缓加速时长 |
| QUIET_MS | 240 | 判定停止增长的静默窗口 |
| TAIL_PX | 120 | 进入软尾的剩余距离阈值 |
| TAIL_MS | 220 | 软尾缓动时长 |
| DIVERGE_STOP_FRAMES | 2 | 真实位置连续偏离动画写入的帧数阈值（≥2 帧判定读者接管） |

改参数：编辑 src/client.js 顶部常量区，pnpm run build 后重启 dsh web。

兼容性
- dsh v0.1.2-alpha.1 ~ rc.1（支持）: 插件的唯一 DOM 锚点 [data-conversation-scroll]（会话滚动容器，ConversationRoot 的 scrollBody）与宿主跟随状态机（observedTopRef / movedByReader / ResizeObserver follow、el.scrollTop 读写面）在 dsh-v0.1.2-alpha.1 ~ dsh-v0.1.2-alpha.5 五个 tag 上一致；dsh-v0.1.2-rc.1 相对 alpha.5 的整仓差异仅全仓包 package.json 版本号变更（非 package.json 文件零变化、非版本行零变化），[data-conversation-scroll] / [data-composer-seat] 锚点、el.scrollTop = el.scrollHeight 钉底写与跟随状态机均在 rc.1 tag 上复核，与 alpha.5 逐字一致；turn 导轨跳转 landOnRow 仍为 el.scrollTop += flowTop - 24 复合读改写，pointerdown 接管先停动画、复合写读到真实位置。alpha.4 把宿主滚动几何采样改为每 500ms 一次并以 scrollend 提前采样（ChatView 的 SCROLL_SAMPLE_INTERVAL_MS）；真实宿主行为 e2e（见验证）确认该节奏下追击无停顿（流式最大离底 0px、追击停顿 0ms）、滚轮接管后漂移 0px 且宿主正常脱钩。
- dsh v0.1.3-alpha.2（支持）: 契约面与 rc.1 逐字一致——packages/client/modules 的模块系统（client/system.ts / client/manifest.ts 零差异）、dsh.client 扫描与 ./client 导出要求、dsh plugin add 的 bundle 层重建（apps/cli/src/plugin.ts 零差异）、cordis.patch.yml 的 insert 行、ctx.effect 客户端 API 全部不变；DOM 锚点 [data-conversation-scroll]（ConversationRoot.tsx）与跟随状态机（observedTopRef / movedByReader / toBottom 的 el.scrollTop = el.scrollHeight / landOnRow 复合读改写）逐行保留。唯一相关变更在 ChatView.tsx:604-616：onScroll 在「已贴底且非读者位移」时改为同步 sample()（取代 500ms 定时器 + scrollend 兜底）。该变更对插件中性——真 Chromium 实测宿主钉底在 rc.1（经 scrollend）与 alpha.2（经 scroll）下都是每帧一次，插件「同目标重钉不重启追击」的兜底照常生效；node test/alpha2-realhost-e2e.mjs 在真实 dsh web 0.1.3-alpha.2 上复核：流式追击最终离底 0px / 最大离底 75px / 追击停顿 0ms，滚轮接管后漂移 0px 且宿主出现「回到底部」，导轨跳转漂移 0px，reduced-motion 下 220ms 内钉底，浏览器零 console 错误。
- 0.1.1-rc.2 及更早（不支持）: 该代使用 @deepseek-ai/dsh-client-runtime，滚动宿主结构不同，不兼容。
- 验证：pnpm test（契约冒烟，bundle 自包含）+ node test/scroll-follow.test.mjs（15 个 e2e 场景，含「追击中点击导轨」回归点；需 Playwright 与 Chromium）+ node test/alpha2-realhost-e2e.mjs （真实 dsh web 0.1.3-alpha.2 + 真 Chromium：流式追击、滚轮接管、导轨跳转、reduced-motion、控制台错误；token 取自 dsh web 启动输出）+ node test/alpha4-realhost-e2e.mjs （同上，针对 0.1.2-alpha.4）。

License

MIT