dsh-smooth-stream 0.3.3 → 0.4.0

package/README.en.md

@@ -2,29 +2,24 @@
 
 English | [中文](README.md)
 
-[![featured on dsh-suite](https://img.shields.io/badge/featured%20on-dsh--suite-4d6bfe)](https://whyihaveyou.github.io/dsh-suite/)
-
-**dsh-smooth-stream** is a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) community plugin for **silky streaming** in the Web UI: arrival-tracking typewriter reveal, glide-in wraps, no flicker. It is not part of the official DeepSeek distribution.
+**dsh-smooth-stream** brings fluid streaming rendering and silky scrolling to the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) Web UI. Text, Markdown, code blocks, tables, and tool results appear as the reply arrives; as the content grows, the page follows along in one continuous visual rhythm.
 
 Project homepage: <https://laplace-bit.github.io/dsh-smooth-stream/>
 
+[Install guide](https://laplace-bit.github.io/dsh-smooth-stream/install.html) · [How it works and reproducible benchmark](https://laplace-bit.github.io/dsh-smooth-stream/how-it-works.html)
+
 ## Preview
 
 Left: default Web UI. Right: dsh-smooth-stream.
 
 ![Left: without the plugin. Right: with dsh-smooth-stream.](docs/compare.gif)
 
-## Current behavior
+## Core experience
 
-- **The whole Agent turn uses one extensible pipeline.** Assistant text, Think, Context, Retry, Command, Bash, Glob, Read, tool calls, and newly registered renderers all enter progressive reveal and bottom-follow through the same boundary, without a tool-name allowlist.
-- **Reveal speed adapts to queue pressure.** Small updates keep a soft cadence while large or fast bursts catch up promptly. Once the producer completes, remaining source is committed immediately instead of continuing to type long after the Agent has stopped.
-- **Markdown remains mounted throughout streaming.** Code blocks, tables, emphasis, and other formatting do not begin as plain text and later swap trees. Historical messages also do not replay their reveal animation when remounted.
-- **Scroll room opens only when a wrap is actually likely.** The predictor combines buffered source with the current line's remaining width before opening its runway. Long replies still absorb line wraps smoothly, while a short same-line answer after Think does not pre-scroll and rebound.
-- **Conversation chrome stays fixed.** `Deep diving...`, the composer, and the to-bottom button never ride the message transform. Fast output and low-frame-rate catch-up cannot paint through the status row or disappear behind the composer.
-- **One continuous spring owns motion.** The engine carries velocity and displacement between frames instead of repeatedly starting native smooth-scroll calls. Line wraps, code, tables, and growing tool rows converge along the same trajectory; completion lands on the natural floor and retires temporary state without a flash or overshoot rebound.
-- **Reader input wins immediately.** A small upward wheel, touch, or keyboard gesture releases automatic follow. Ownership returns only after the reader actually reaches the bottom again.
-- **Think respects the user's preference.** With auto-expand enabled it keeps the Harness disclosure interaction and collapses when thinking ends. With it disabled, collapsed reasoning can keep updating without fake height motion, and a manual toggle is not wrestled back by stream state.
-- **Performance guards preserve the final position.** `prefers-reduced-motion` shows complete content without taking follow. Off-screen DOM commits pause under low FPS, then catch up under control and still finish exactly at the bottom.
+- **Fluid rendering.** Text appears as it arrives while Markdown structure stays active, keeping headings, lists, code blocks, and tables readable throughout the stream.
+- **Silky scrolling.** As the content grows, the page follows along one continuous scroll path and keeps the reader close to the generated output.
+- **Consistent transitions.** Line wraps, code blocks, tables, and tool results use the same motion treatment, so text, reasoning, and tools flow together.
+- **Adaptive cadence.** Reveal speed responds to arrival rate and pending content, staying measured for slow output and catching up with fast output.
 
 ## Install
 
@@ -66,12 +61,20 @@ Legacy `mode`, `revealCharsPerSec`, `scrollSpeedPxPerSec`, and `maxScrollSpeedPx
 
 ## User settings
 
-In the Web UI, open **Settings → Plugins → Plugin configuration** to find a **Smooth stream** card with an **"Auto-expand thinking"** toggle:
+In the Web UI, open **Settings → Plugins → Plugin configuration** to find a **Smooth stream** card with:
+
+- **Enable smooth streaming** (on by default): lets this plugin own reply and tool-row rendering and follow. Turn it off to return rendering completely to the built-in Harness UI.
+- **Auto-expand thinking**: controls whether reasoning opens while it streams. This preference has no effect while the master toggle is off.
+- **Collapse finished work** (on by default): once a turn finishes processing, its thinking, tool calls, context injection, and intermediate output fold behind one “已处理 X秒 / Processed” summary row so only the final answer shows. Click the summary any time to expand or re-collapse the full process.
+- **Show render diagnostics** (off by default): opens a chat-side panel with live rendering, frame-rate, and scroll-follow measurements, plus controls for reveal and spring behavior.
 
-- **On** (default): reasoning blocks auto-expand while streaming and collapse when thinking ends — the plugin's default behavior.
-- **Off**: reasoning blocks stay collapsed; you can still open one by hand, and the stream state will not wrestle it back.
+With “Auto-expand thinking” on, reasoning blocks open while streaming and collapse when thinking ends. With it off, reasoning stays collapsed; you can still open a block by hand, and the stream state will not wrestle it back.
 
-This is a durable, user-level preference that applies live without a restart, and is written to the DeepSeek Harness user-settings document rather than the plugin's composed configuration.
+“Collapse finished work” never interferes while a reply streams — output expands live, and folding happens only after the turn settles with all work complete. The switch works independently of “Enable smooth streaming”: folding applies whether this plugin or the built-in renderer owns the conversation. Plain replies without thinking or tools get no summary row. Content embedded by other plugins through fully custom tool views (such as `dsh-pianist`'s piano card) is never folded — only calls rendered as native tool cards participate. This feature supersedes the standalone `dsh-auto-collapse` plugin; do not run both at once, or they will fight over the same DOM nodes and overlap text.
+
+These are durable, user-level preferences that apply live without a restart, and are written to the DeepSeek Harness user-settings document rather than the plugin's composed configuration.
+
+Diagnostics controls apply as you move them: reveal multiplier, queue pressure, maximum reveal rate, spring stiffness/damping/mass, predictive runway, runway response time, and minimum backpressure scale. The panel reports FPS, frame time, character backlog, effective reveal rate, progress, visual lag, scroll velocity, and available follow room. You can **Save** a combination, **Discard** unsaved edits, **Restore defaults**, or copy the current tuning and measurements. Turning diagnostics off immediately returns the renderer to its production defaults.
 
 ## About & updates
 
@@ -89,7 +92,7 @@ dsh plugin --profile web update dsh-smooth-stream
 ## FAQ
 
 **Is this an official DeepSeek plugin?**
-No. It is a community plugin for the DeepSeek Harness (`dsh`) Web UI, MIT-licensed, and not part of the official DeepSeek distribution.
+No. It is independently maintained, MIT-licensed software for the DeepSeek Harness (`dsh`) Web UI and is not affiliated with DeepSeek.
 
 **How do I install a DeepSeek Harness plugin?**
 Use the built-in plugin command: `dsh plugin --profile web add dsh-smooth-stream` from a dsh source checkout (see [Install](#install)).
@@ -100,6 +103,8 @@ Yes — `dsh-smooth-stream` is published to [npm](https://www.npmjs.com/package/
 **Does it respect `prefers-reduced-motion`?**
 Yes. With reduced motion enabled the finished text is shown at once and the plugin does not take over follow. If the frame rate drops below 30 fps while the reply is off-screen, reveal pauses and catches up later.
 
+[![featured on dsh-suite](https://img.shields.io/badge/featured%20on-dsh--suite-4d6bfe)](https://whyihaveyou.github.io/dsh-suite/)
+
 ## License
 
 [MIT](LICENSE)

package/README.md

@@ -2,29 +2,24 @@
 
 [English](README.en.md) | 中文
 
-[![featured on dsh-suite](https://img.shields.io/badge/featured%20on-dsh--suite-4d6bfe)](https://whyihaveyou.github.io/dsh-suite/)
-
-**dsh-smooth-stream** 是 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）的社区插件，给 Web 对话做**丝滑流式渲染**：字跟着模型走、换行滑入、不闪。不是官方发行的一部分。
+**dsh-smooth-stream** 为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）Web UI 带来流畅的流式渲染和丝滑滚动。文字、Markdown、代码块、表格以及工具结果会随着输出自然呈现；内容逐步增长时，页面平稳跟随，整轮回复保持连贯的视觉节奏。
 
 项目主页：<https://laplace-bit.github.io/dsh-smooth-stream/>
 
+[安装指南](https://laplace-bit.github.io/dsh-smooth-stream/install.html) · [工作原理与可复现基准](https://laplace-bit.github.io/dsh-smooth-stream/how-it-works.html)
+
 ## 效果
 
 左：默认 Web UI。右：dsh-smooth-stream。
 
 ![左：未使用插件。右：使用 dsh-smooth-stream。](docs/compare.gif)
 
-## 当前实现
+## 核心体验
 
-- **整轮 Agent 输出统一接管。** 助手正文、Think、Context、Retry、Command、Bash、Glob、Read、工具调用以及后续注册的新渲染器，都通过同一个可扩展入口进入渐进揭示和底部跟随，不依赖工具名称白名单。
-- **吐字速度会跟随积压自动变速。** 小批内容保持柔和节拍，大批或高速到达时及时追赶；完成信号到达后立即提交剩余正文，不让 Agent 已结束而文字还长时间继续输出。
-- **流式过程始终使用 Markdown 渲染。** 代码块、表格、强调等不会先显示成纯文本再整体换树，历史消息也不会在重新挂载时重播动画。
-- **换行前才准备滚动空间。** 引擎结合待揭示内容和当前行剩余宽度判断是否可能增高，只在真实换行风险出现时打开预测 runway。长回复仍能平滑吸收换行，Think 后的短同一行正文不会多滚再回弹。
-- **状态区域保持稳定。** `Deep diving...`、输入框和「滚动到底部」按钮不参与消息 transform；高速输出或低帧率下，正文也不会越过状态区域或藏到输入框后面。
-- **滚动使用持续弹簧而不是反复启动原生平滑滚动。** 每帧保留速度和位移状态，换行、代码块、表格及工具卡片增高都沿同一轨迹收敛；结束时落在自然底部并安静撤销临时状态，不闪烁、不越位回弹。
-- **用户输入拥有最高优先级。** 向上滚轮、触控拖动或键盘滚动会在轻微手势时立即解除自动跟随；只有用户真正回到底部后才重新接管。
-- **Think 尊重用户设置。** 自动展开开启时沿用 Harness 的 disclosure 交互并在思考结束后收起；关闭时折叠内容持续更新但不引发虚假高度和上下闪动，手动展开也不会被流状态抢回。
-- **性能保护不会破坏最终状态。** `prefers-reduced-motion` 直接显示完整内容且不接管跟随；低帧率且回复在屏外时暂停 DOM 提交，恢复后受控追赶，最终仍准确停在底部。
+- **流畅渲染。** 文字边到边呈现，Markdown 结构持续更新，标题、列表、代码块和表格在流式过程中保持自然的阅读状态。
+- **丝滑滚动。** 内容逐步变高时，页面沿连续的滚动轨迹平稳跟随，视线始终贴着正在生成的内容。
+- **统一过渡。** 换行、代码块、表格和工具结果使用一致的过渡方式，正文、思考过程与工具输出衔接自然。
+- **自适应节奏。** 渲染速度会根据输出速度和待显示内容调整，让慢速输出从容呈现，快速输出及时跟上。
 
 ## 安装
 
@@ -66,12 +61,20 @@ Host 日志里应出现 `[dsh-smooth-stream] plugin loaded!`。
 
 ## 用户设置
 
-在 Web 界面打开 **设置 → 插件 → 插件配置**，会看到一张 **丝滑流式（Smooth stream）** 卡片，可切换**「自动展开思考」**：
+在 Web 界面打开 **设置 → 插件 → 插件配置**，会看到一张 **丝滑流式（Smooth stream）** 卡片，其中包含：
+
+- **启用丝滑流式渲染**（默认开启）：开启时由本插件接管回复和工具行的渲染与跟随；关闭后会撤销接管，完整使用 Harness 内置渲染。
+- **自动展开思考**：控制思考块在流式期间是否自动展开。主开关关闭时此选项不会生效。
+- **完成后自动折叠**（默认开启）：回合处理完成后，把思考过程、工具调用、上下文注入和中间输出折叠为一行“已处理 X秒”摘要，只展示最终回复；点击摘要可随时展开或收起完整工作过程。
+- **显示渲染调试面板**（默认关闭）：在聊天页右侧显示实时渲染、帧率和滚动跟随数据，并开放流式揭示与滚动弹簧参数。
 
-- **开**（默认）：思考块在流式时自动展开，思考结束收起——与插件默认行为一致。
-- **关**：思考块保持折叠；仍可手动点开，且不会被流式状态抢回控制。
+“自动展开思考”开启时，思考块会在流式时自动展开、思考结束后收起；关闭后思考块保持折叠，仍可手动点开，且不会被流式状态抢回控制。
 
-该设置是用户级的持久化偏好，改完即生效，无需重启；会写进 DeepSeek Harness 的用户设置文档，而不是插件的组合配置。
+“完成后自动折叠”在流式期间不干预——回复实时展开输出；只有回合结束（出现结束标记且全部工作完成）才折叠。该开关独立于“启用丝滑流式渲染”：无论由本插件还是内置渲染器负责对话，折叠都照常工作。纯文本回复（无思考、无工具）不会生成摘要行。其他插件通过自定义工具视图嵌入的内容（如 `dsh-pianist` 的钢琴卡片）不会被折叠——只有渲染为原生工具卡样式的调用才参与折叠。此功能取代外挂的 `dsh-auto-collapse` 插件，二者不要同时安装，否则会互相抢夺同一批 DOM 节点造成文字重叠。
+
+这些设置是用户级的持久化偏好，改完即生效，无需重启；会写进 DeepSeek Harness 的用户设置文档，而不是插件的组合配置。
+
+调试面板中的参数在拖动时实时生效，包括揭示倍率、队列压力、最大揭示速度、弹簧刚度/阻尼/质量、预测 runway、runway 响应时间和最低背压倍率。面板同时显示 FPS、帧耗时、积压字符、实际揭示速度、渲染进度、视觉滞后、滚动速度和可用跟随空间；可随时**保存**当前组合、**放弃**未保存修改、**恢复默认**，或复制当前参数与指标。关闭调试开关后，渲染引擎立即恢复正式默认参数。
 
 ## 关于与更新
 
@@ -89,7 +92,7 @@ dsh plugin --profile web update dsh-smooth-stream
 ## 常见问题
 
 **这是 DeepSeek 官方插件吗？**
-不是。它是 DeepSeek Harness（`dsh`）Web UI 的社区插件，MIT 协议开源，不属于 DeepSeek 官方发行。
+不是。它是面向 DeepSeek Harness（`dsh`）Web UI 的独立维护项目，采用 MIT 许可证，和 DeepSeek 没有从属关系。
 
 **dsh 插件怎么安装？**
 用内置插件命令：在 dsh 源码目录运行 `dsh plugin --profile web add dsh-smooth-stream`（见[安装](#安装)）。
@@ -100,6 +103,8 @@ dsh plugin --profile web update dsh-smooth-stream
 **支持 `prefers-reduced-motion` 吗？**
 支持。系统开启减少动态效果时直接显示完整文本、不接管跟随；帧率低于 30 fps 且回复在屏外时，揭示自动暂停、恢复后再补上。
 
+[![featured on dsh-suite](https://img.shields.io/badge/featured%20on-dsh--suite-4d6bfe)](https://whyihaveyou.github.io/dsh-suite/)
+
 ## 许可证
 
 [MIT](LICENSE)