Back to search
dsh-smooth-stream
SkillGitHub
DeepSeek Harness Web UI plugin for streaming rendering and scroll handling.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/laplace-bit--dsh-smooth-stream)HTML
<a href="/listings/laplace-bit--dsh-smooth-stream"><img src="/api/listings/laplace-bit--dsh-smooth-stream/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 165 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # dsh-smooth-stream
- > **让 AI 的长篇生成如提词器般温润流淌。**
- > 为 DeepSeek Harness(`dsh`)打造的物理流式渲染与合成层补偿跟随引擎。
- [English](README.en.md) · [项目主页](https://laplace-bit.github.io/dsh-smooth-stream/) · [工作原理与基准](https://laplace-bit.github.io/dsh-smooth-stream/how-it-works.html) · [npm](https://www.npmjs.com/package/dsh-smooth-stream)
- ---
- ## 极致丝滑的阅读手感
- 无论是阅读数百行的长篇推演,还是紧盯高速吐字的代码生成,`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` 输出为准。机制说明见[工作原理与基准](https://laplace-bit.github.io/dsh-smooth-stream/how-it-works.html)。
- ---
- ## 安装与使用
- 在 DeepSeek Harness 源码根目录运行:
- ```sh
- pnpm dsh plugin --profile web add dsh-smooth-stream
- ```
- 如果系统 `PATH` 中已有 `dsh`:
- ```sh
- dsh plugin --profile web add dsh-smooth-stream
- ```
- 启动界面:
- ```sh
- 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](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.