智能体过程可视化lisongjianustc/dsh-viz

dsh-viz

把「过程可视」做成 DeepSeek Harness 的插件体系 —— 所有视图都是事件流的投影，谁想要什么视图，就装一个视图插件。

视图不产生状态，只消费事件 → 视图崩了不影响 agent 干活。
用户 / 插件可以定义自己的「投影」 → 扩展性天然保留。
事件流可重放 → 过程可视可以做到「回放级」。

截图

在 web GUI 的会话头部，每个视图是一个 tab：

① 执行时间轴（Timeline）——turns / 工具 / 文件 / 网络 / 子代理 / 压缩点铺在一条可缩放时间轴上，带回放滑块：

时间轴

② 上下文仪表盘（Context Radar）——窗口占用、构成堆叠、逐请求 token 曲线、压缩记录（回答「它怎么忘了前面说的？」）：

上下文仪表盘

③ 子代理编排泳道图（Swimlanes）——goal 卡 + 主会话时间线（派发点高亮）+ 子代理血缘泳道：

子代理编排泳道图

④ 组件依赖图（Component Map）——boot 图 inject 边 + 实时 fiber 状态，看「智能体由什么拼起来」：

组件依赖图

⑤ 环境变更日志（Environment Diff）——组件安装→效应→卸载→还原的 diff 日志：

环境变更日志

包

| 包 | 作用 | 数据源 |
|---|---|---|
| @dsh-viz/core | 投影框架 + 事件分类学 + 快照适配器（宿主半面还提供组件效应日志镜像） | — |
| @dsh-viz/ui-timeline | 视图① 执行时间轴：turns / 工具 / 文件 / 网络 / 子代理 / 压缩点铺在一条可缩放时间轴上（DevTools Performance 面板），带回放滑块 | ConversationSnapshot |
| @dsh-viz/ui-context-radar | 视图② 上下文仪表盘：窗口占用、构成堆叠、逐请求 token 曲线、压缩记录（回答「它怎么忘了前面说的？」） | token-meter 投影 + 快照 |
| @dsh-viz/ui-swimlanes | 视图③ 子代理编排泳道图：goal 头 + 父会话泳道 + 子代理泳道（血缘/运行态/派发点对齐），GoalBar 的升级版 | goal/subagent 投影 + 快照 + 会话列表 |
| @dsh-viz/ui-component-map | 视图④ 组件依赖图：boot 图 inject 边 + 实时 fiber 状态（「我的智能体是由什么拼起来的」） | window.__DSH_BOOT__ + pluginInventory Remote |
| @dsh-viz/ui-env-diff | 视图⑤ 环境变更日志：组件安装→效应→卸载→还原的 diff 日志（调试插件、理解系统行为） | core 宿主半面 /api/plugins/viz/effects |

快速开始（安装到 web profile）

git clone https://github.com/lisongjianustc/dsh-viz   # 或直接使用本地仓库
cd dsh-viz
node scripts/link-deps.mjs     # 链接本机的 dsh 类型合同（构建期类型解析，跳过也可装预构建产物）
node scripts/build.mjs         # esbuild → 各包 lib/{index,client,invariant}.js（仓库已带预构建产物，可跳过）

dsh plugin --profile web remove @dsh-viz/core @dsh-viz/ui-timeline   # 若已装过旧版
dsh plugin --profile web add file:$PWD/packages/core \
file:$PWD/packages/ui-timeline \
file:$PWD/packages/ui-context-radar \
file:$PWD/packages/ui-swimlanes \
file:$PWD/packages/ui-component-map \
file:$PWD/packages/ui-env-diff

dsh --dump-config --profile web | tail   # 组装树末尾应有 6 个 viz-* 条目
重启 dsh web 宿主（插件集合变化需要重启），刷新页面即可看到新视图 tab

开发

npx tsc --noEmit              # 类型门
node scripts/build.mjs        # 构建全部包（--watch 可用）
node scripts/build.mjs --watch
node scripts/smoke.mjs        # bundle 物化冒烟（模拟模块表执行 factory）

注意：不要跑 pnpm install（pnpm 会给链接进来的 cordis bin 做 chmod，指向 store 路径会被沙箱拒绝）；
依赖链接只走 scripts/link-deps.mjs。改了 package.json / cordis.patch.yml 后重装要先 dsh plugin remove 再 add
（pnpm 不刷新 file: 安装副本）。

文档

- docs/DESIGN.md —— 总纲与架构：视图 = 事件流的投影
- docs/ADD-A-VIEW.md —— 新增一个视图插件的 10 步施工标准（所有坑都是实测踩过的）
- docs/client-contract-research.md —— 浏览器客户端插件合同调研（ClientContext / 槽位全表 / 视图注册 / locale / 分发）
- docs/contracts/api-surface.md —— wire API 合同调研（双 API、MuxFrame、投影、pluginInventory、goals/subagents）

铁律

1. 视图不产生状态，只消费事件；fold 崩溃被框架吞掉，视图崩了 agent 照常干活。
2. 投影可组合可替换：新视图 = 新投影 spec + 一个 conversation.view 注册。
3. 事件流可重放：同一份 fold 跑实时流，也跑任意历史前缀（回放免费）。
4. 客户端模块图是平的：跨插件运行时 require 只有 @dsh-viz/core 一条边（immediately 预取）。