前言¶
在 DeepSeek Harness（DSH）里跑智能体时，轨迹（trajectory）视图是排查「哪一步慢、哪次工具失败、模型在等什么」的常用入口。内置 trajectory 以列表或时间线方式呈现，多轮、长 idle、模型首 token 与解码分段等信息一屏里往往不够直观。社区插件 dsh-trace-waterfall 用独立的瀑布图界面替换该视图，交互参考 Kobra Trace Waterfall 的思路，实现与资源均不依赖 Kobra 代码。下面介绍它是什么、能做什么，以及如何安装与日常使用。
这是什么¶
dsh-trace-waterfall 由 omdsh-dev 维护，分类为客户端插件；在 SkillHub 目录中的简介为：A live, searchable trace waterfall for DeepSeek Harness.（实时、可搜索的 Harness trace 瀑布图。）
插件只做展示层：不增加工具、不改变 agent 行为、不上报遥测。安装后通过 bundle 中的 cordis.patch.yml 关闭 ui-trajectory，并注册 trace-waterfall；视图 ID 仍为 trajectory，因此原有视图偏好与工具检查链接可继续使用。
核心功能¶
单轮分段条¶
每一轮（turn）用一条分段 bar 表示模型调用、工具、等待、handoff、失败等活动，类型一目了然。
三车道概览与缩放¶
概览分为 input / model / tools 三条车道，支持拖拽框选时间范围进行缩放；双击可重置。超过 60 秒的 idle 在轴上会被压缩显示，记录中的实际时长不变。任意一轮可通过聚焦图标单独放大查看。
模型耗时拆分¶
模型 bar 将「首 token 时间（TTFT）」与「解码阶段」分开显示，便于区分排队/推理与生成。
摘要与详情¶
点击某行或 bar 会先弹出锚定在对应片段上的摘要；可再打开完整详情，查看完整 input、output、时序与 metadata。
实时跟随与稳定时间轴¶
进行中的 session 默认从底部打开；停留在底部时新行会自动保持在视野内。向上滚动、搜索、仅看错误、聚焦某轮或打开摘要时会暂停跟随，滚回底部可恢复。历史 session 从顶部打开。
全局视图会为最新调用预留空间，并按整 block 扩展；已完成的 bar 在扩展之间位置固定，session 结束后时间轴贴合录制结束时间。手动缩放与 turn 聚焦会保留所选范围。
搜索与错误过滤¶
Ctrl/Cmd+F 搜索，匹配名称、参数、prompt、输出并高亮。Errors only 只列出失败操作及其父级上下文；若失败已恢复，该轮显示 error 徽章而不是整轮标红。
按 Escape 可关闭摘要或详情，或清除过滤器。
与 DSH 状态栏一致的 token 统计¶
总 token = 未缓存 input + cache-read input + cache-write input + output，与 DSH 状态栏一致。缓存命中率 = cache-read input / 全部 input。
其他说明¶
- 独立子 agent session 不会合并进父 trace。
- 不展示 cost（录制 trace 无权威定价数据）。
安装与启用¶
环境要求：Node 24.9+，且 pnpm 11 在 PATH 中（dsh plugin 使用 pnpm；pnpm 10 会报 ERR_PNPM_ADDING_TO_ROOT）。README 注明在 DSH 0.2.1-rc.5 与 0.2.2-alpha 线（master 于 ce7073d）上测试；DSH 插件 API 仍属 pre-stable 阶段。
从 GitHub 安装（web profile）：
dsh plugin --profile web add github:omdsh-dev/dsh-trace-waterfall
安装后请重启 DSH Web 或刷新浏览器。更新到最新 commit 时，重复执行同一条 add 命令即可。
恢复 DSH 内置 trajectory：
dsh plugin --profile web remove dsh-trace-waterfall
不要同时启用两个 trajectory 提供方，它们共用同一视图。
当前 package 版本为 0.1.0，许可证 MIT；适配模块部分衍生自 DSH MIT 许可的 trajectory 实现，详见仓库 THIRD_PARTY_NOTICES.md。
典型用法¶
安装并 reload 后，在 Web 端打开 session，进入仍为 trajectory 的轨迹视图即可看到瀑布图。常用操作如下。
- 缩放时间范围：在概览上拖拽框选；双击重置；点击某轮的 target 图标聚焦该轮。
- 跟跑 live session：保持在列表底部以自动跟随新行；需要细看时向上滚动或搜索，看完再滚回底部。
- 查失败：开启 Errors only，结合分段条上的 error 徽章定位已恢复的失败。
- 查内容：
Ctrl/Cmd+F在 trace 文本中搜索并跳转高亮。
README 提供约 100 秒演示视频与多张 light/dark、多轮概览、handoff、popover 截图，路径见 GitHub 仓库。
本地开发者在已构建的 DSH checkout 上可用 patch 预览，无需正式安装：
pnpm dsh --patch <path-to-this-repository>/cordis.source.patch.yml --no-open
用确定性测试数据预览 UI：
node scripts/build-preview.mjs
python3 -m http.server 3468 --bind 127.0.0.1 --directory dist/preview
适用场景与注意¶
适合：经常在 DSH Web 里读 trace、对比模型/工具耗时、在多轮与 handoff 场景下做 live 跟跑与搜索的开发者。
注意：
- 插件随当前 DSH 进程在本地运行，安装前宜浏览仓库源码与许可证，确认符合你的环境与合规要求。
- SkillHub 插件目录（如 dsh-trace-waterfall 目录页）是社区站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态强调「一切皆插件」，本文介绍的是社区维护的客户端扩展。
- 仅 web profile 安装流程在 README 中明确写出；开发与 link 步骤需自备 DSH 源码 checkout。
结尾¶
dsh-trace-waterfall 把 DSH 的 trajectory 视图换成可缩放、可搜索、可 live 跟随的 trace 瀑布图，并在不改变 agent 行为的前提下保留原有视图 ID 与链接习惯。需要安装命令、演示与截图时，以仓库 README 为准。
- 目录页：https://www.skillhub.cn/plugins/omdsh-dev/dsh-trace-waterfall
- GitHub：https://github.com/omdsh-dev/dsh-trace-waterfall
