dsh-smooth-stream

43Star4Fork1Issue0Watching

为 DeepSeek Harness Web 界面接管助手回复与工具结果的自适应流式渲染与平滑跟随滚动，并接入"丝滑流式"用户设置卡。

分类🖥️ 界面增强🔌 集成与服务
Laplace-bitLaplace-bit
·Laplace-bit/dsh-smooth-stream.git·laplace-bit.github.io/dsh-smooth-stream
语言
JavaScript
License
MIT
分支
main
ai-chatchat-uicordisdeepseekdeepseek-harnessdeveloper-toolsdshdsh-plugin

安装

$ dsh plugin --profile web add github:Laplace-bit/dsh-smooth-stream

在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程

一句话定位

dsh-smooth-stream 是 DeepSeek Harness（dsh）Web 界面的第三方插件，用"打字机"式的自适应揭示接管助手回复、Markdown、代码块、表格和工具结果的渲染，并在内容增长时让页面平滑跟随滚动，避免长回复一次性铺满或频繁跳行。

核心能力

  • 把助手回复（文本块、Markdown、代码块、表格）按打字机节奏逐字揭示，标题/列表等结构在流式过程中持续可用
  • 用同一套 follow 边界包裹 Agent 拥有的聊天行（Tool、Context、Command、重试等），让多行场景保持一条连续滚动轨迹
  • 实时观察模型到达速率（EMA）来调整揭示速度：慢输出从容展示，快输出及时跟上，闲置期以限定速度收尾排空
  • 在 Web 界面"设置 → 插件 → 插件配置"提供"丝滑流式"卡片，开关插件接管、切换"自动展开思考"两项偏好即时生效
  • 内置 FPS 守护（30 fps 阈值）与 prefers-reduced-motion 适配，屏外低帧或开启减少动画时直接显示完整文本，不与可见帧抢资源
  • 支持 Host 的 npm 安装包固定更新流程：检测到 profile 用 npm 注册表安装时，UI 卡片显示"更新"按钮，调用同一 pnpm update

技术实现

  • 语言: TypeScript（ESM，type: module，构建工具 tsdown）
  • 关键依赖: @deepseek-ai/cordis（Host 插件运行时）、@deepseek-ai/schemastery（配置 Schema）、@deepseek-ai/dsh-settings（用户级设置注册）、react ^18.2.0（浏览器渲染层）
  • 架构模式: 双端 Cordis 插件。src/plugin.ts 是 Host 端：apply(ctx, config) 打印 [dsh-smooth-stream] plugin loaded! 横幅、调用 webServer.tapIndex 把 Schema 校验后的配置作为 window.__DSH_SMOOTH_STREAM_CONFIG__ 内联脚本注入到 index.html，再注册 smooth-stream 命名空间的用户设置和仅 loopback RPC（读/写/触发 npm 更新）。src/client/index.ts 是浏览器端：从内联配置读取后，通过 slots 影子化 assistant-step 并就地包裹其它 Agent 行；用户级偏好通过插件自己的 loopback RPC 同步，绕开第三方 namespace 默认 allowlist。
  • 入口文件: src/index.ts（Host 端导出 apply/name/Config），src/client/index.ts（客户端 apply，exports 通过 ./client 子路径暴露）

适用场景

喜欢长篇 Markdown、代码块、表格或工具调用结果逐步出现在 DSH 上的用户，例如想看着思考过程一边落字一边展开的代码审查场景；或者希望阅读节奏不被一次性刷屏打断的方案对比 / 长文写作 / 报告生成。普通短回复也能直接受益——它把 Harness 内置的"块状铺设"换成单一连续揭示曲线。

前置依赖与兼容性

依赖最低版本说明
DeepSeek Harness（cordis、settings、connection、conversation、UI 套件等）0.1.0-rc.6+来自 peerDependencies 和 devDependencies 锁定值，cordis ^4.0.1
Node.js^22.19.0 或 >=24.0.0来自 engines.node
React^18.2.0来自 peerDependencies，用于浏览器端渲染
宿主 profileWeb profile（dsh.client.platform: web）本插件只为 Web 宿主面注册到 cordis.patch.yml，CLI/Desktop 不会被注入
平台macOS / Windows / Linux（任意带现代浏览器的桌面 OS）engines 无 os 限制；客户端是浏览器，无原生模块依赖
原生模块无纯前端渲染 + Cordis RPC，无 node-pty / node:sqlite 等

安装方式

dsh plugin --profile web add github:Laplace-bit/dsh-smooth-stream

配置项

本插件包含两类配置：profile 级组合配置（写在 cordis.patch.yml 里、改完需重启 Harness）和用户级偏好（在 Web 设置卡里改、即时生效）。

Profile 级组合配置（字段由 Host 端 Schema 校验）：

配置类型说明默认值
modetypewriter / teleprompter兼容性字段，两种 mode 当前都走同一套自适应揭示引擎typewriter
presetrealtime / balanced / silky揭示节奏预设：realtime 更贴模型到达；balanced 默认；silky 缓冲最大、跟进最慢balanced
revealCharsPerSec5–200 的数字旧版字段，仍被加载但运行时不再使用，自适应引擎只跟到达速率80
scrollSpeedPxPerSec1–200 的数字旧版字段，仍被加载但运行时不再使用，跟随走 smooth-damp 而非巡航速度48
maxScrollSpeedPxPerSec1–2000 的数字旧版字段，仍被加载但运行时不再使用1000

用户级偏好（写入 dsh 用户设置文档，通过插件自己的 loopback RPC 编辑，无需重启）：

偏好类型说明默认值
enabled布尔总开关：开启时由本插件接管回复和工具行的渲染与跟随；关闭后会撤销接管、完整回退到 Harness 内置渲染true
thinkAutoExpand布尔思考（Think）块是否在流式期间自动展开，思考结束后再收起；关闭后保持折叠但仍可手动展开。enabled = false 时本项不再生效true

常见问题

Q: 这个插件是做什么的？

A: 它在 DSH 的 Web 界面把助手回复按打字机节奏逐字揭示，Markdown 结构在流式时也保持可用；同时接管跟随滚动，让多行 / 多工具场景也走同一条视觉曲线，不让页面反复跳。

Q: 这是官方插件吗？

A: 不是。代码仓库和 README 都明确：本项目是独立维护的 MIT 授权插件，与 DeepSeek 公司没有官方从属关系。

Q: 支持 prefers-reduced-motion 和低帧率吗？

A: 支持。系统开启减少动态效果时（window.matchMedia('(prefers-reduced-motion: reduce)')）直接展示完整文本、不接管跟随；流式时若帧率持续低于 30 fps 且回复位于屏外，揭示会被 FPS 守护暂停，等恢复后再补上。

Q: 如何切换流式节奏？

A: 在安装 profile 的 cordis.patch.yml 里把 config.preset 改为 realtime（贴近模型到达）、balanced（默认）或 silky（缓冲最大、跟进最柔），保存后重启 Harness 即可看到差异。

Q: 安装后还需要额外做什么吗？

A: 通常不需要。npm 包随包带预构建的 lib/，所以不用 pnpm ≥10 的构建脚本授权；安装命令完成后 dsh web 启动，Host 日志出现 [dsh-smooth-stream] plugin loaded! ... 表示加载成功。

Q: 如何卸载？

A: 在 dsh 源码目录运行 dsh plugin --profile web remove dsh-smooth-stream 即可，UI 会回到 Harness 内置渲染，组合包配置也会被一并撤掉。

Q: 可以从 npm 安装吗？

A: 可以。dsh plugin --profile web add dsh-smooth-stream 安装的就是 Laplace-bit/dsh-smooth-stream@0.3.4 这个 npm 包的预构建产物。

Q: 怎么更新到这个插件的新版本？

A: 如果安装时走的是 npm 包（不是 link: / file: 本地开发），网页"丝滑流式"卡片会显示"更新"按钮，点一下它会在当前 profile 目录下跑一次固定的 pnpm update dsh-smooth-stream，完成后会提示重启 Harness；也可以从命令行跑 dsh plugin --profile web update dsh-smooth-stream。

Q: 这个插件只能装在 Web profile 吗？

A: 是。package.json 的 dsh.client.platform 声明为 web，Hook 面板里只注册了 @deepseek-ai/dsh-client-runtime、@deepseek-ai/dsh-client-ui-conversation、@deepseek-ai/dsh-client-locale、@deepseek-ai/dsh-client-connection、@deepseek-ai/dsh-client-ui-settings、@deepseek-ai/dsh-client-ui-settings-plugins 这一组 Web 相关的客户端包，因此不会自动注入 CLI / Desktop 等其它宿主面。

Q: 报错或没看到效果怎么办？

A: 优先检查 Host 日志是否出现 [dsh-smooth-stream] plugin loaded! 字样；如果没出现，多半是 profile 没勾上插件或浏览器已被改造。如果是 boot 配置不合法（错误码见 dsh-smooth-stream: malformed __DSH_SMOOTH_STREAM_CONFIG__），可以把 cordis.patch.yml 的 config 段清空让它重新走默认。

上手难度

入门 —— 安装即用，默认配置即可工作；只有想切换节奏或停用插件时才需要改 cordis.patch.yml 或设置卡，不需要修改 React / 源码。

已知问题与限制

  • revealCharsPerSec、scrollSpeedPxPerSec、maxScrollSpeedPxPerSec 三个 legacy 数字字段仍能被 Schema 接受，但运行时已不再使用，自适应引擎只看 preset（见 src/config.ts:20-30）；用户改这些字段不会改变手感，只有 preset 才有效果
  • 思考块处于流式尾部时，root 节点刻意不开启 pre-paint 的横向位移，避免在快节奏推理下把空白 runway 露在固定 turn-status 上方；如果你依赖"提前打位置"的体验，需要关掉流式或停用插件（src/client/TypewriterAssistantNodeView.tsx:513-522）
  • 一次点击"更新"按钮只能在 profile 用 npm: / 通用注册表范围声明时生效；link: / file: 本地开发安装和 catalog: / patch: / portal: / workspace: 等非注册表说明符会被识别为不可更新，更新按钮保持禁用以保护源码目录（见 src/profile-installation.ts:56-77、:100-102）
  • 这个插件只为 Web profile 设计，不为 CLI / 其他宿主面注册；试图装到非 web profile 不会生效但也不会报错，需要自己把 profile 改回 web（package.json:65-78）
返回插件目录