dsh-pref-kit

Readme

# dsh-pref-kit

DSH 性能插件：在数据流源头合并模型流式输出的相邻文本增量，减少会话事件量，
缓解长会话与多 agent 并发下的卡顿与资源占用。不改任何接口与协议。

当前版本 **v0.4.0**，要求 DSH **>= 0.1.2-alpha.5**（Cordis >= 4.0.2，Node >= 20）。

## 功能

- **流式合并（默认开启）**：把同一文本块内的相邻 text/reasoning 增量合并后再写入
  会话日志与推送，事件量下降 11–56%（短回复 −45.6%、长回复 −53.5%、6 并发 −55.6%，
  复杂长会话 −11%），内存 / 磁盘 / 带宽同步下降；`windowMs = 0` 即完全透传，
  与未装插件逐事件等价。
- **设置卡片**：Settings → Plugins 提供配置卡片（与内置卡片同款样式），修改保存后
  即时生效、跨重启保留。
- **实验开关（默认全关）**：
  - 替换轨迹视图：用轻量轨迹页接管官方轨迹入口（需先禁用官方 `ui-trajectory` 行），
    消除轨迹页在流式期间的每帧全量重算（基准模型实测 ×239–×184.9k 工作降幅）；
  - 聊天区渲染提示：让浏览器跳过视口外消息的绘制（画面不变）；
  - 运行时行管理：按白名单禁用/启用官方插件行（如遥测、token 统计），即时生效并持久化。

## 安装

```bash
cd dsh-pref-kit
npm run build                                       # 构建
dsh plugin --profile web add "file:$(pwd)"          # 装入目标 profile（自动挂载插件行）
# 重启 DSH 生效（启动日志出现 [dsh-pref-kit] llm/stream coalescer active）
```

更新：`npm run build` 后先 `dsh plugin --profile web remove dsh-pref-kit` 再 `add`。
卸载：`dsh plugin --profile web remove dsh-pref-kit`。

## 配置

| 配置项 | 默认 | 说明 |
|---|---|---|
| `windowMs` | 30 ms | 合并窗口（0–200ms）；0 = 关闭合并（逐 token 透传）。窗口越大事件削减越多，首个字延迟 ≈ 窗口 |

实验项（Settings → Plugins → dsh-pref-kit 卡片 → 实验组）：

| 配置项 | 默认 | 说明 |
|---|---|---|
| `experimental.replaceTrajectoryView` | false | 替换轨迹视图；需同时把 `ui-trajectory` 加入下方行管理的禁用列表（或手工禁用该行） |
| `experimental.chatContainment` | false | 聊天区渲染提示（画面不变，浏览器少画视口外内容） |
| `experimental.rowManager.enabled` / `disabledRows` | false / [] | 运行时禁用官方行（白名单：`ui-trajectory`、`session-telemetry-otel`、`token-meter`、`session-stats`、`session-projection-cache`）；Host 即时生效并持久化，客户端需刷新页面。alpha.5：`session-query-sqlite` 已是 base 中唯一的 `ctx.sessionQuery` provider（schema 默认 `openAt: startup`，base/web 组合将其覆盖为 `never`，不打开 SQLite），不可安全停用；旧的 `session-persistence-sqlite` 后端已移除 |

## 基准测试

离线可复现（固定种子 + 虚拟时钟，不连接 DSH；含逐块协议等价断言与复杂长会话生成器，
任何人可逐位复现）：

| 场景 | 事件数（基线 → 合并 30ms） | 首块延迟 |
|---|---|---|
| 短回复 | 810 → 441（−45.6%） | 16 → 40ms |
| 长回复 | 9674 → 4501（−53.5%） | 20 → 28ms |
| 复杂长会话（生成器） | 12210 → 10869（−11.0%） | 30 → 60ms |
| 6 并发 agent | 35592 → 15788（−55.6%） | 18 → 50ms |

运行：`npm run benchmark`。详细分析与实验性策略消融见[性能分析报告](docs/perf-bottlenecks.md)。

## 许可证

[MIT](LICENSE)