dsh-evo-vis

Readme

# dsh-evo-vis · DeepSeek Harness 组件生态实时可视化

> 把 DeepSeek Harness（dsh）的每一次组件活动，变成一座会进化的深海生物圈。
> 实时、美观、有趣地看见你的 harness 正在做什么。

![Evo Vis 可视化面板](docs/screenshot-evo.png)

`dsh-evo-vis` 是一个面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
（Everything is a Plugin）的宿主侧插件。它监听 harness 的 Cordis 事件
（`session/event`、`tools/result`、`agent/*`），把会话、模型推理、工具调用、
记忆压缩、智能体、任务清单等组件活动归一化成轻量事件，通过 SSE 实时推送到
一个零依赖的全屏可视化面板（`/evo`）——组件化作深海生物圈里的一颗颗生命，
活动越多，能量越足，组件会进化（Lv.1 孢子 → Lv.6 超新星）。

## 特性

- 🌊 **美观**：深空鲸鱼蓝主题、玻璃拟态面板、Canvas 粒子引擎（星云、星点、
  荧光浮游、辉光节点、进化光环），无需任何前端依赖。
- ⚡ **实时**：SSE 事件流 + 快照回放；工具调用、token 流、回合/步骤、压缩、
  审批等事件即时点亮对应组件；顶部徽章实时显示当前 Provider / Model，
  生成中带有脉动"生成中"指示；60s 滑动窗口活动速率。
- 🧬 **有趣**：每个组件都是会进化的"物种"（能量积累 → 升级 → 冲击波 +
  名字进化）；演示模式在无活动时自动点亮生态（也可手动开关）。
- 🪶 **抗风暴**：streaming 时 `assistant/chunk` 按会话合并推送（默认 800ms
  一帧），token 统计仍实时累加，活动流不再被逐 token 刷屏。
- 🔌 **零侵入**：不修改 harness 核心；注册自己的 HTTP 路由 + `tapIndex`
  注入一个 Web UI 悬浮入口按钮，卸载即完全还原。
- 🪶 **零构建**：纯 ESM JavaScript，`dsh plugin add` 直接安装，无 `prepare`
  构建脚本、无 TypeScript 编译产物。

## 安装

在 deepseek-harness 的 Web profile 中安装本插件：

```sh
# 本地目录安装
dsh plugin --profile web add /path/to/dsh-evo-vis

# 或从 GitHub 安装（仓库发布后）
dsh plugin --profile web add github:simplosophy/dsh-evo-vis
```

然后启动 Web UI：

```sh
dsh web
```

打开 `http://127.0.0.1:3080/evo` 即可看到可视化面板；也可以直接在
DeepSeek Harness Web UI 右下角的 **Evo Vis** 悬浮按钮打开。首次打开且暂无
组件活动时，页面会自动进入演示模式，点亮生态供你观赏。

> 插件在无 `ctx.webServer` 的 profile（如 headless）里不会挂载面板，但会
> 继续安全地监听事件，不会影响启动。

## 工作原理

```
┌───────────────────────── DeepSeek Harness ─────────────────────────┐
│  session/event · tools/result · agent/*  …Cordis 事件流…            │
└───────────────┬────────────────────────────────────────────────────┘
                │ 监听并归一化（组件分类、能量、等级、指标）
┌───────────────▼────────────────────────────────────────────────────┐
│  dsh-evo-vis（宿主侧插件）                                           │
│  · /evo        可视化面板（单文件 HTML + Canvas）                    │
│  · /evo/data   快照（环形缓冲最近 N 条事件 + 统计）                   │
│  · /evo/stream SSE 实时事件流（hello/snapshot/event/level-up/stats） │
│  · tapIndex    在 Web UI 右下角注入悬浮入口                          │
└───────────────┬────────────────────────────────────────────────────┘
                │ SSE（EventSource）
┌───────────────▼────────────────────────────────────────────────────┐
│  浏览器：节点辉光/冲击波/彗星流/粒子 · 活动流 · KPI · 物种进化表      │
└────────────────────────────────────────────────────────────────────┘
```

## 组件与事件映射

| 组件 | 对应事件 |
|---|---|
| 核心循环 `core` | `turn/*`、`step/*`、`session/end-seed` |
| 模型推理 `llm` | `assistant/chunk`、`assistant/message`、`request/*` |
| 会话 `session` | `user/message`、`session/title` |
| 工具 `tools` | `tool/call`、`tool/result`、Cordis `tools/result` |
| 记忆压缩 `memory` | `compaction/start`、`compaction/end` |
| 智能体 `agent` | `agent/created`、`agent/status`、`agent/disposed`、`agent/session-start` |
| 任务清单 `todo` | `todo/write` |
| 规划 `plan` | `plan/mode` |
| 审批 `approval` | `approval/asked`、`approval/decided` |

事件会给组件贡献"能量"，能量越过阈值即进化（Lv.1 孢子 / Lv.2 萌芽 /
Lv.3 成长 / Lv.4 绽放 / Lv.5 星核 / Lv.6 超新星）。

模型 Provider / Model 取自 `request/header`、`request/context` 与
`agent/created`，显示在面板顶部的模型徽章和模型推理节点的详情提示里。

## 配置

在 profile 的 `cordis.patch.yml` 中覆盖：

```yaml
- update:
    - id: evo-vis
      config:
        path: /evo          # 面板路径
        maxEvents: 400      # 内存保留的最大事件数（快照回放）
        heartbeatMs: 15000  # SSE 心跳间隔
        statsIntervalMs: 2000 # 统计帧推送间隔
        chunkFlushMs: 800   # streaming 时 assistant/chunk 合并推送间隔
        waitForWebMs: 60000 # 等待 ctx.webServer 的最大时长
        uiTitle: 'Evo Vis'  # 页面标题与悬浮按钮文案
```

## 本地开发与测试

```sh
npm install
npm test                 # 冒烟测试：模拟 ctx + 真实路由/SSE 断言
npm run dev:preview      # 开发预览：http://127.0.0.1:3788/evo（模拟事件流）
```

仓库中的 `test/` 脚本均为独立开发工具，不随 npm 包发布。

## Roadmap（欢迎 PR）

- [ ] 作为 `dsh.client` 客户端插件嵌入 Web UI 侧边栏（面板常驻，而非独立页面）
- [ ] 组件调用链时序图（工具 A → 工具 B 的依赖轨迹）
- [ ] 会话/智能体粒度的筛选与回放
- [ ] 更多进化形态与皮肤（浅色主题、极简模式）

## License

[MIT](LICENSE)