Laplace-bit/dsh-smooth-stream

让 AI 的长篇生成如提词器般温润流淌。
为 DeepSeek Harness（dsh）打造的物理流式渲染与合成层补偿跟随引擎。

English · 项目主页 · 工作原理与基准 · npm

---

极致丝滑的阅读手感

无论是阅读数百行的长篇推演，还是紧盯高速吐字的代码生成，dsh-smooth-stream 带来的是一种沉浸、连贯且零视觉负担的阅读质感：

• 如水流般自然铺展：告别大段文本突然“砸”在屏幕上的视觉压迫，字句如打字机般富有呼吸感地逐字涌现；
• 视线无需追赶跳动：视口如同搭载了高精度阻尼滑轨，随文字增长平稳匀速推移，彻底终结换行时的突发踢移；
• 呼吸感与实时性的平衡：慢速输出时从容优雅，高并发爆发时平稳追赶，无论模型吐字多快，画面始终从容自若。

---

为什么需要它？

大模型输出是通过网络分块到达的。一个数据包可能在几毫秒内送达数百字符，下一个分块却需要数十毫秒。

如果直接将 DOM 渲染和视口滚动绑定在离散的到达事件上，通常会引发两个阅读体验问题：

1. 视觉跳跃与撕裂：段落、代码块和表格整段突发呈现，视线被迫频繁重新寻焦；
2. 滚动抖动与重排风暴：依靠 scrollTop = scrollHeight 进行瞬时硬跳；即使用 CSS scroll-behavior: smooth，高频写入也会不断重置缓动曲线，导致动画永远无法收敛，高速流下伴随剧烈的主线程重排。

dsh-smooth-stream 将内容呈现与视口运动拆分为两个独立的物理状态机，在每一帧动画回调（rAF）中连续积分，彻底消除跳跃感。

---

核心机理与架构

[ 模型 SSE 分块流 ]
         │
         ▼
 ┌─────────────────┐       背压阻尼 (0.55x ~ 1.0x)       ┌─────────────────┐
 │   揭示节奏引擎   │ ◄──────────────────────────────── │   弹簧跟随引擎   │
 │ (Reveal Engine) │                                   │ (Follow Engine) │
 └────────┬────────┘                                   └────────┬────────┘
          │ 字符积压与分数积分                                      │ 二阶阻尼弹簧积分 (k=130, c=24)
          ▼                                                     ▼
 [ 逐帧平滑展开 DOM ] ───────────────────────────────► [ 合成层 Transform 补偿 ]
  (按帧预算揭示字符)                                       (Transform 补偿视觉滞后)

1. 动态自适应的揭示引擎（Reveal Engine）

• 分数级字符积分：根据积压队列深度自适应调节速度（$v = 90 + \text{backlog}^{1.25} \times P$），低负载时从容自然，高积压时平稳追赶，绝不倾泻整段文本。
• 折行平滑：正文预测跟随使用速度、加速度受限的连续轨迹吸收折行；其他高度增长由弹簧跟随。8px 是约 60Hz 下变换衰减的常规预算，并非所有场景的单帧位移上限；补偿真实高度变化时可超过此值。
• 尾部平稳收束：回合结束标记到达后，残余缓冲区以恒定速率释放，正文、思考链与工具调用之间自然衔接。

2. 合成层补偿的跟随引擎（Follow Engine）

• 二阶阻尼物理系统：采用 $k=130, c=24, m=1$ 的亚步进物理弹簧，将内容高度的变化转化为平滑连续的速度与位移轨迹。
• 变换位移补偿：接管滚动时，真实滚动容器锚定在底部，安全范围内的视觉滞后由外层 DOM 的 transform: translate3d 吸收。引擎仍需读取高度和矩形，并调整临时边距、填充及滚动位置，因此不保证零重排；关闭接管后由内核负责贴底。
• 闭环背压控制（Closed-Loop Backpressure）：当跟随滞后接近预留空间时，反向向揭示引擎施加阻尼（最低降至 0.55 倍速），防止文本增长超出视口弹簧范围。
• 掉帧自愈与跨刷新率一致：主线程卡顿（Stall）时自动钳位物理时间（$\le 32\text{ms}$），避免画面恢复后的突进瞬移；在 60Hz 与 120Hz（ProMotion）屏幕下拥有近乎一致的物理收敛时间。

3. 按阶段配置折叠（Turn Fold Policy）

• 思考块可分别配置生成中、结束后的开合状态及展开高度。
• 整个回合结束后的开合默认跟随内核，也可选择保持展开或收起；适用条件见下方「用户偏好设置」。

---

效果对比

左：默认 Web UI。右：dsh-smooth-stream。

---

性能与基准

平滑度与稳定性基于本地自动化审计台架验证：

验证闸门	测试项目	指标要求
流式渲染审计	node scripts/run-render-audit.mjs	5 种典型生成场景下 10/10 Clean，零位移回退
视口溢出闸门	node scripts/verify-overflow.mjs	极限输出场景下零过滚、零反弹
尾行晃动抑制	pnpm test	单帧跳变 ≤30px，7 帧振幅峰值 ≤32px

• Host ESM 与浏览器 bundle 分别构建，当前体积以 pnpm build 输出为准。机制说明见工作原理与基准。

---

安装与使用

在 DeepSeek Harness 源码根目录运行：

pnpm dsh plugin --profile web add dsh-smooth-stream

如果系统 PATH 中已有 dsh：

dsh plugin --profile web add dsh-smooth-stream

启动界面：

pnpm dsh web

Host 日志中显示 [dsh-smooth-stream] plugin loaded! 即表示已成功加载。

卸载命令：pnpm dsh plugin --profile web remove dsh-smooth-stream。

---

内核兼容性

DSH 内核	本插件支持情况
0.2.x（@deepseek-ai/dsh-client-* ≥ 0.2.0-rc.0）	✅ peerDependencies 已声明。助手步骤的接管改为原地替换内置行（0.2.x 每个 keyed 条目各占一个座位），因此保留了内核的 children/locale/inject 座位；思考正文新增的 conversation.chat.reasoning.body 槽位已接入（见下）
0.1.7（@deepseek-ai/dsh-client-* ≥ 0.1.7-rc.1）	✅ 当前声明范围：peerDependencies 的下限即此版本。插件配置页迁到侧栏 Plugins（plugins.bundle.config）、助手步骤的双流程座位（groupPart）、图标与 primitive 改名、settings 投影 seam（describe() / update()）均已适配
≤ 0.1.6（含 0.1.5-rc 桌面内核）	⚠️ 代码里保留了旧 seam 的兼容分支（设置注册表、size 后缀图标名），但已不在 peerDependencies 声明范围内，本版未实测
0.1.0-rc.5 ～ 0.1.0-rc.7	✅ 旧版本（≤ 0.6.1）支持
0.1.1-rc.2	✅ 旧版本（≤ 0.6.1）支持
0.1.2-alpha.1 ～ 0.1.2-alpha.3	✅ 0.4.3 起

• ✅ = 兼容；⚠️ = 仍可用但已超出声明范围。0.1.7 线是本版的目标内核，已按“同一份构建、运行时探测”的方式适配；0.1.5-rc 的兼容分支保留在代码中，便于回退到旧内核时仍能加载。
• 0.2.x 给思考正文新增了 conversation.chat.reasoning.body 槽位（内核自带的思维链翻译、以及后续任何思考正文特性都注册在这里）。接管渲染思考正文时会先看该槽位：只有内核默认实现占位时仍由插件自己画（保留插件的平滑与自动滚动），一旦有别的特性替换了默认实现，展开状态就交回槽位，插件自身的显示层翻译同时让位，避免同一行出现两份互相矛盾的翻译。槽位不存在（旧内核、影子注册回退）时行为不变。
• 0.1.7 起内核把插件配置从 Settings 移到侧栏 Plugins 面板（plugins.bundle.config 槽位），并给助手步骤同时挂上 reasoning / response 两个流程座位（groupPart）、把图标导出从 size 后缀改名为权重后缀。本版对三者都做了运行时适配：槽位不存在时旧路径继续生效，groupPart 缺失时按“全部块归属本渲染”处理，图标按候选名逐个探测。
• 0.1.2 起内核移除了 settingsNamespace() 运行时助手（≤ 0.1.1 上它只是个校验恒等函数，0.1.2 仅保留同名类型）。本插件不静态导入该符号，而是在注册设置命名空间时本地内联常量并断言为 SettingsNamespace 类型。
• 跨插件协作使用 Cordis 服务；易变的 UI 导出通过模块表探测。宿主 CLI 的 tsx paths 映射可能把裸导入重定向到宿主源码，已改名或移除的符号会令启动失败，因此 primitive 使用 harnessIcons.ts / primitives-compat.tsx 探测。平台模块和允许内联的库仍可静态导入，具体边界由 tsdown.config.ts 校验；import type 不产生运行时导入。

配置与手感预设

插件默认采用 preset: balanced。如需切换手感，可在对应 profile 的 cordis.patch.yml 中修改：

preset	动态特性
realtime	紧跟模型分块到达节奏，缓冲更小
balanced	默认推荐，兼顾阅读流畅度与响应延迟
silky	增大缓冲区，追赶更平缓柔和

---

用户偏好设置

在 Web 界面打开侧栏 插件 → 已安装 → dsh-smooth-stream，在包详情页的配置卡片中个性化调节（0.1.7 之前的内核仍在 设置 → 插件 → 插件配置）：

• 启用丝滑流式渲染（默认开启）：接管回复和工具行的渲染与跟随；关闭后即时恢复 Harness 内置渲染。
• 折叠行为：按阶段管理思考块的开合与展开高度。
  • 思考生成中（默认展开）：思考内容到达时是否自动打开；收起后可随时手动打开。
  • 思考结束后（默认收起）：停止输出后继续展开便于回看，或折叠回一行摘要。
  • 展开高度（默认限高）：限高时正文留在自身的 300px 滚动框内；全高时按完整高度铺开，滚动交给会话。
  • 回合结束后（默认跟随内核）：回合完成时是否把整个过程收起成一行摘要。选「保持展开」或「收起」时，插件在回合已关闭且可折叠时，对当前挂载的回答行应用一次所选状态；该行保持挂载期间，之后的手动开合不会被改回去，回答行重新挂载时会再次应用。
• 对数淡入（默认开启）：回答正文和展开的思考内容中，尾部范围随输出速度从 24 扩展到最多 160 个字素，从 0% 不透明度在 240ms 内按反向对数曲线变实（前段更通透，后段变实）。网络停顿时也会恢复清晰；关闭此项保留逐字输出与滚动。遵循动效偏好，跳过代码、公式和思考摘要，不支持文字范围着色的浏览器自动使用原有输出效果。
• 显示渲染调试面板（默认关闭）：在界面右侧开启实时 HUD，观测 FPS、字符积压、弹性曲线并微调物理参数。

升级提示：旧的 thinkAutoExpand 只保留用于接受历史配置，其值不再影响渲染。此前关闭自动展开的用户，升级后需要将「思考生成中」重新选为「收起」。新配置未设置时仍默认展开。回合策略在当前回答行上应用一次后，再改策略不会重置该行的开合；后续回合或重新进入会话时采用新策略。内核强制展开的回合仍由内核决定。

本地淡入预览：执行 pnpm build:repro，在仓库根目录启动 python3 -m http.server 8765 --bind 127.0.0.1，打开 http://127.0.0.1:8765/repro/index.html?demo=fade。预览包含暂停、停止、深浅主题、高速分片和代码/公式保护样例，复用真实输出引擎，富文本为测试样例。

执行 node scripts/verify-logarithmic-fade.mjs 可验证并录制预览（需要 Chrome 和 pnpm exec playwright-core install ffmpeg；其他 Chrome 路径可用 CHROME_BIN 指定），报告与视频保存在未跟踪的 repro/artifacts/logarithmic-fade/。

---

许可证

MIT