dsh-speedometer 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# DSH 速度计（dsh-speedometer）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+为 DeepSeek Harness 提供**实时生成速度**与**对话全程速度回溯**的插件。
+
+- 右下角悬浮胶囊：当前/上次生成速度 + 迷你曲线，可拖到任意位置，不打断写作。
+- 展开面板：实时 tok/s、平均速度、首字延迟（TTFT）、峰值、输出 token 数。
+- 折线图回溯整个会话：**全程**把每次生成的平均速度连成趋势线，默认显示最近 100 次，横向拖动查看更早；**最近**按真实时间连续绘制最近 1 分钟内有活动的片段。
+- “全程”横轴按 `#N` 标注绝对生成序号；鼠标悬停查看每次生成的均值。“最近”横轴为 `-60s … 现在`，悬停显示相对时间。
+- 会话下拉框自动列出最近会话；生成中的会话带「生成中」标记。
+- 面板底部五格显示最近 5 轮完整对话：每格是该轮所有生成的输出 token 总数，数字不再带单位。
+- 关闭面板后仍持续记录，重启 DSH 后历史自动从会话日志恢复。
+- 外观跟随当前 DSH 皮肤：读取主题的 CSS 变量，自动适配明暗、主色、圆角、边框与阴影；截图使用 Orca Link 皮肤。
+
+**全程**（最近 100 次平均速度，可拖动回看更早）：
+
+![全程速度趋势](docs/preview.png)
+
+**最近**（最近 1 分钟活动，按时间连续绘制）：
+
+![最近一分钟速度](docs/recent.png)
+
+## 兼容性
+
+插件在 `llm/stream` 的与提供商无关的统一流式层测速，不依赖 DeepSeek 专有字段，因此对以下接入方式同时生效：
+
+| 接入方式 | 是否支持 |
+| --- | --- |
+| DeepSeek 官方 API | ✅ |
+| 自定义 OpenAI 兼容 API | ✅ |
+| 本地模型（Ollama / LM Studio / vLLM 等） | ✅ |
+| 其他 DSH 已接入的 provider | ✅ |
+
+速度按**流式 chunk 到达时间**统计。文本、推理内容和工具调用参数都会计入输出 token；因此推理模型在“思考”阶段同样会显示实时速度。
+
+## 安装
+
+### 图形界面（推荐）
+
+1. 打开 DSH → 左侧「插件」→「添加插件」→「安装已有插件」。
+2. 选择 npm 包名，输入 `dsh-speedometer`，确认安装。
+3. 重启 DSH 桌面应用，右下角出现速度胶囊。
+
+### 命令行
+
+```bash
+dsh plugin --profile desktop add dsh-speedometer
+```
+
+安装后**重启 DSH 桌面应用**。插件通过 `webserver/index-inject` 注入页面脚本，通过 `/dsh-speed/*` 同源路由提供状态与 SSE；`dsh.profile.bundles` 会自动包含 `dsh-speedometer`。
+
+> 开发者：也可以直接把源码目录以 `link:` 方式装进 profile（`dsh plugin --profile desktop add 'link:<目录绝对路径>'`），改完 `lib/widget.js` 刷新页面即生效，改 `lib/index.js` 需重启应用。
+
+## 使用
+
+1. 重启后右下角（鲸鱼挂件上方）出现速度胶囊。
+2. 生成时胶囊实时跳动；空闲时显示上次生成的平均速度。
+3. 点击胶囊展开面板：
+   - **全程**：每次生成取一个平均速度点，连成一条趋势线；默认只展示最近 100 次，在图上左右拖动可查看更早/更新。
+   - **最近**：以“现在”为右端、按真实时间绘制最近 1 分钟内有活动的生成片段，断档超过 4 秒会断开；没有活动时曲线停在最后一次活动的位置，不再向右延伸。
+4. 胶囊和面板都可拖动；位置、展开状态和图表模式会保存在浏览器 localStorage。
+
+## 指标口径
+
+| 指标 | 含义 |
+| --- | --- |
+| 实时 tok/s | 最近 1.6 秒滑动窗口内的输出 token 速率 |
+| 均值 | 从第一个 token 到最后一个 token 的平均速率（不含首字等待） |
+| 首字 | 从发起请求到第一个输出 token 的时间（TTFT） |
+| 峰值 | 本次生成中滑动窗口速率的最高值 |
+| 输出 | 本次生成统计到的输出 token 数 |
+
+> 这里的 token 是 DSH 流式 chunk 的计数口径，用于比较速度，不等同于计费 token。
+
+## 数据与隐私
+
+- 历史仅保存在本机：`~/.dsh/dsh-speedometer/history.json`。
+- 同时从 DSH 会话日志恢复历史，因此已有的旧对话也能看到速度回溯。
+- 不向任何外部服务发送数据；前端只访问同源的 `/dsh-speed/state` 与 `/dsh-speed/events`。
+
+## 开发与测试
+
+```bash
+# 语法检查
+node --check lib/index.js
+node --check lib/widget.js
+
+# 后端单元/集成测试（mock root、路由、SSE、流式测速、日志恢复、信任边界）
+node test-speedometer.mjs
+
+# 独立预览面板（mock 数据）
+node test-widget-server.mjs   # http://127.0.0.1:52801/
+```
+
+主要文件：
+
+- `lib/index.js`：测速、会话归属、历史恢复/持久化、HTTP 路由、SSE、页面注入。
+- `lib/widget.js`：悬浮胶囊与面板 UI（closed shadow root，避免污染 DSH 样式）。
+- `cordis.patch.yml`：把插件插入 profile 配置树。
+
+## 排障
+
+- 页面没有胶囊：确认已重启应用，且 `dsh.profile.bundles` 含 `dsh-speedometer`；访问 `http://127.0.0.1:<端口>/dsh-speed/health` 应返回 JSON。
+- 有胶囊但无数据：确认当前会话确实在生成；断线时前端会自动降级轮询，恢复后自动继续更新。
+- 历史为空：首次启动会异步从会话日志恢复，稍等片刻或切换一次会话。

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh-speedometer —— DSH 实时速度计
+#
+# 安装（npm 发布后）：GUI「插件 → 添加插件 → 安装已有插件 → dsh-speedometer」
+# 或 CLI：dsh plugin --profile desktop add dsh-speedometer
+#
+# 本文件把插件插入 Web profile 的配置树；实际的 UI 注入与测速逻辑在 lib/index.js。
+
+- insert:
+    - id: dsh-speedometer
+      name: dsh-speedometer