前言¶
在 DeepSeek Harness（DSH）里跑智能体时，会话轨迹往往跨多轮、多工具调用，还有等待与 handoff。内置的 trajectory 视图能看过程，但在长会话里要快速定位某次模型调用、某段 idle，或只看失败步骤，仍然偏费眼。社区插件 dsh-trace-waterfall 用一条可缩放、可搜索的 trace 瀑布图替换 Web 端的 trajectory 展示，交互参考 Kobra Trace Waterfall 的思路，实现独立，不包含 Kobra 代码或资源。
这是什么¶
dsh-trace-waterfall 是 DSH 的客户端（Web）插件，维护者为 GreatV，仓库 github.com/GreatV/dsh-trace-waterfall。一句话定位：在 DSH Web 里提供 live、可搜索的 trace waterfall，替代默认 trajectory 视图，不改变 agent 行为、不增加工具、不上报遥测。
插件通过 bundle 里的 cordis.patch.yml 关闭 ui-trajectory 并挂载 trace-waterfall；视图 ID 仍为 trajectory，原有视图偏好与工具检查链接可继续工作。
核心功能¶
以下能力均来自仓库 README 说明。
单行 Turn 与三车道总览¶
每一行 Turn 用分段条展示 model、tool、waiting、handoff、failed 等活动。上方三车道总览（input / model / tools）支持拖拽框选缩放；超过 60 秒的 idle 在轴上压缩显示（记录时长不变）；任意 Turn 可聚焦查看。
模型耗时拆分¶
Model 条会把 首 token 时间 与 解码阶段 分开显示，便于区分「等模型」与「流式输出」各占多少。
摘要与详情¶
点击某行或某段条，先出现锚定位置的摘要；再打开完整详情，可查看完整 input、output、timing 与 metadata。
实时跟随与稳定时间轴¶
进行中的会话默认从底部打开；停留在底部时新行会保持在视野内。向上滚动、搜索、仅看错误、聚焦 Turn 或打开摘要会暂停跟随，滚回底部可恢复。历史会话从顶部打开。
全局视图会为最新调用预留空间并按块扩展；已完成的条在扩展之间位置固定；会话结束后轴对齐到记录结束时间。手动缩放与 Turn 聚焦会保留所选范围。
搜索与错误过滤¶
- 搜索：
Ctrl/Cmd+F，在名称、参数、prompt、输出中高亮匹配。 - Errors only：只列失败操作及父级上下文；已恢复的失败会在 Turn 上加 error 徽章，而不是整行标红。
- Escape：关闭摘要或详情，或清除过滤。
其他说明¶
- Total tokens 与 DSH 状态栏一致：uncached input + cache-read + cache-write + output；cache hit rate = cache-read / 全部 input。
- 独立子 agent 会话不会合并进父 trace。
- 不展示 cost（trace 中无权威定价数据）。
安装与启用¶
环境要求（README 原文）：
- Node 24.9+
- pnpm 11 在
PATH上（dsh plugin使用 pnpm；pnpm 10 会报ERR_PNPM_ADDING_TO_ROOT） - 面向 DSH 0.2.1-rc.3；DSH 插件 API 仍属 pre-stable
从 GitHub 安装（命令须与 README 一致）：
dsh plugin --profile web add github:greatv/dsh-trace-waterfall
安装后重启 DSH Web 或刷新浏览器。更新到最新 commit 时，再执行同一条 add 命令即可。
恢复 DSH 内置 trajectory：
dsh plugin --profile web remove dsh-trace-waterfall
不要同时启用两个 trajectory 提供方，它们共用同一视图。
插件以当前 DSH 进程权限运行；安装前建议在 GitHub 阅读源码与 THIRD_PARTY_NOTICES.md（适配模块源自 DSH MIT trajectory 实现）。许可证：MIT（package.json 版本 0.1.0）。
典型用法¶
安装并进入 Web 会话后，在 trajectory 视图（已被 waterfall 替换）中操作：
- 缩放：在总览上拖拽选择时间范围；双击重置。Turn 上的 target 图标可聚焦该 Turn。
- 跟 live 会话：保持在列表底部以跟随新行；需要细查时向上滚动或搜索，结束后再滚回底部。
- 查失败：打开 Errors only，结合 Turn 上的 error 徽章区分「整轮失败」与「已恢复的单步失败」。
- 查内容：
Ctrl/Cmd+F搜工具名、参数或输出片段；点条打开摘要后再进详情看完整 IO。
仓库 README 提供约 100 秒的演示视频与 light/dark 主题截图，可在 GitHub 页面查看。
本地开发或预览（可选，需已 checkout DSH 与本仓库）：
npm ci
npm run link:dsh -- <path-to-deepseek-harness>
npm run build
npm test
在仓库根目录用工作副本安装 Web profile：
dsh plugin --profile web add .
不安装插件、仅在 DSH checkout 里试 patch：
pnpm dsh --patch <path-to-this-repository>/cordis.source.patch.yml --no-open
用确定性测试数据预览静态页：
node scripts/build-preview.mjs
python3 -m http.server 3468 --bind 127.0.0.1 --directory dist/preview
适用场景与注意¶
适合：经常在 DSH Web 上调试多轮 agent、需要按时间轴看 model/tool/wait/handoff、或要在长 trace 里搜索与筛错误的开发者。
注意：
- 仅 Web 客户端（
--profile web）；与内置 trajectory 互斥。 - DSH 生态是「一切皆插件」；社区目录 skillhub.cn 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系。
- 插件只做展示层；权限与数据范围仍取决于你本地 DSH 与会话内容。
结尾¶
dsh-trace-waterfall 把 DSH Web 的 trajectory 换成可缩放、可搜索、可跟 live 的 trace 瀑布图，适合把智能体运行过程当时间线来读。更多信息见社区目录页与 GitHub 仓库：
