前言¶
在 DeepSeek Harness（DSH）里跑智能体任务，对话窗口通常只呈现「最终选中的那条路」：哪次工具调用成功了、模型接着说了什么。失败重试、检索扑空、绕远折返，往往散落在多轮输出里，要靠肉眼翻日志才能拼出全貌。
如果你要对比两次运行（比如同一任务用 flash 与 pro）、或者想看清长会话里时间花在哪，纯文本 session log 并不直观。下面介绍的 dsh-trace-compare 是社区维护的 DSH 客户端插件，把执行轨迹可视化成「迷宫」：主干、支路、折返点落在同一根时间轴上，支持离线对比与实时跟随。
这是什么¶
dsh-trace-compare（GitHub：lamost423/dsh-trace-compare）由维护者 lamost423 开发，归类为 客户端 插件。npm 包名 dsh-trace-compare，当前仓库版本 0.6.2。
插件做一件事：从 session log 或当前会话事件流中解析工具调用与回答节点，用统一的视觉语言画出智能体的探索过程——成功推进的主干、失败/扑空/无效重试的支路，以及折返回分支点的回程线。
两个入口共用同一套图例与判定逻辑：
- Trace 对比（侧边栏）：上传 1 个 log 看单次运行的迷宫，或上传 2 个做同轴对比。
- 实时迷宫（会话内页签）：迷宫随当前会话执行实时生长，工具结果落定后支路立刻显现。
核心功能¶
迷宫图例¶
图上各元素含义如下（均来自插件 README 说明）：
- 实线主干：工具调用成功推进的步骤与回答节点。
- 时长胶囊条：每步从开始到结束画成圆角条，按判定上色；条够宽时耗时写在条内。一步内 ≥2 次并行工具调用时（v0.3.2 起），每次调用在胶囊条下方画细小条，按各自起止摆位。
- 虚线弧（支路）：工具失败（红 ✗）、检索扑空（灰 ·）、盲目重试（灰 ↻），以及折返回分支点的回程线。
- 子代理支路（v0.4.0 起，实时页签）：模型派生的 dsh 子代理会话（
origin: 'subagent'）画成主干分出的聚合节点，与父会话共享时间轴；运行中的子代理实时生长。手动分支与 side-chat 不入图。
悬停节点或弧线可快速预览；点击在右侧打开详情面板，含完整命令与返回（各带复制按钮，返回保留前 5000 字）、耗时、判定与思考摘要。
Trace 对比（双会话）¶
上传两个 session log 后，插件按轮次自动对齐两边的回答节点，并支持：
- 轮次对齐线（v0.3.0 起）：每轮回答节点互连，标注两边本轮耗时、耗时差与支路数差；v0.5.1 起耗时口径为「该轮起点 → 回答完成」，轮间用户空闲不计入。
- 手动锚点：在两条泳道各点一个节点，钉带时差标注的对比线，适合轮次错位但语义等价的时刻。
- 支路盘点：按轮次列出两边支路步数、墙钟耗时、类别构成与差额结论；点一行可缩放到该轮。
实时迷宫¶
会话页签内同一张图随执行生长。详情面板可点「在对话中定位此步骤」，宿主切回对话页并高亮对应工具行（行过旧、超出已加载窗口时退化为只切页签）。
实时页签只画对话已加载的事件窗口（v0.2.3 起标注）；窗口外更早步骤会丢弃并提示「另有 N 步更早历史未加载」。要看全会话，用「Session log 下载 → 上传对比」。
交互与导出¶
- 缩放导航：滚轮以光标为中心横向缩放，拖拽平移，双击空白或「整图」复位；轴刻度随缩放加密（最细到 1 秒）。
- 搜索与过滤：「只看失败/重试」开关、按工具类型过滤、命令与返回全文搜索；不命中节点淡化至 15% 透明度。
- 播放：最高 300× 回放整次运行。
- 导出：当前视图导出为 SVG 或 2x PNG；导出固定浅色底。
- 界面双语（v0.5.0 起）：嵌入宿主时跟随 dsh 语言设置；独立打开按浏览器语言兜底。
- 主题跟随（v0.3.1 起）：随宿主明暗主题切换。
时间轴与判定规则¶
时间轴上的诚实约定：
- 超过 60 秒无活动的区间压缩为带
⏸的细缝，标明省略时长；活动段内刻度仍为墙钟真值。 - 步骤标识带轮次（如
S15·47）；token 读自 session log 里assistant/message的usage（v0.2.2 起）；日志无 usage 时标签回退为「推理 N 段（日志未报 token 用量）」。
支路判定（v0.2.1 引入，页面与实时共用 src/client/verdict.js 的 VERDICT_RULES）：
- 错误标志（
isError）→ 失败； - 强/弱失败特征，只扫输出开头与末尾窗口，避免长文本中部「引用」的报错字样误判；
- 按工具分类：写入类无错误即成功；检索类空结果才算扑空；bash 及未知工具空输出才算扑空；
- 行为学检测：连续「同工具 + 参数相似」且簇内至少一次失败的调用，非失败成员判为无效重试。
一步进主干还是支路，由该步最坏工具判定决定。
支持的 log 格式¶
按文件内容识别，文件名任意：
- 纯文本
.jsonl（session 格式 v0 事件流） ~/.dsh/sessions/下原样.jsonl.zstd（浏览器端解压，优先原生DecompressionStream('zstd')，否则内置 fzstd）
安装与启用¶
插件已在官方 0.1.0-rc.6（构建 + 全量测试）与 rc.8（插槽/类型核对 + 实机验收）验证；peer 范围覆盖 rc.6 到当前 rc 线。
下面是从 README 给出的安装步骤。插件以当前 dsh 进程权限运行，安装前建议查看 GitHub 仓库 源码与许可证。
npm install --global @deepseek-ai/dsh@0.1.0-rc.8
dsh plugin --profile web add dsh-trace-compare
dsh web
若要钉住特定发布版本，可使用 Release 附带的 tgz（README 示例为 v0.5.2）：
dsh plugin --profile web add https://github.com/lamost423/dsh-trace-compare/releases/download/v0.5.2/dsh-trace-compare-0.5.2.tgz
从源码安装：
git clone https://github.com/lamost423/dsh-trace-compare.git
cd dsh-trace-compare
corepack enable
pnpm install
pnpm build
dsh plugin --profile web add .
dsh web
重启 dsh web 后，侧边栏底部出现「Trace 对比」入口，每个会话视图多一个「实时迷宫」页签。
社区目录页：SkillHub · lamost423/dsh-trace-compare。DSH 生态奉行「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
典型用法¶
对比两次运行¶
- 在 DSH 中分别跑完同一任务（或导出两次 session log）。
- 打开侧边栏「Trace 对比」，上传两个
.jsonl或.jsonl.zstd文件。 - 查看同轴双泳道：轮次对齐线对比每轮耗时与支路差额；需要时用「加锚点」钉住语义等价时刻。
- 点「支路盘点」按轮次查看失败/重试/扑空构成，点某行缩放到该轮细节。
实时观察当前会话¶
- 安装插件并启动
dsh web。 - 进入任意会话，切换到「实时迷宫」页签。
- 随工具调用观察迷宫生长；点节点看详情，必要时「在对话中定位此步骤」跳回原文。
- 用过滤与搜索定位失败步骤；会话结束后可导出 SVG/PNG 分享。
分析长会话¶
README 提到插件可处理大规模日志（示例：14 小时、8.6MB），按宽度铺满并支持纵向滚动，时间轴钉顶；⌘/Ctrl+滚轮可缩放到任意片段。若实时页签提示有未加载更早历史，下载完整 session log 再走 Trace 对比上传。
适用场景与注意¶
适合谁：
- 需要对比同一任务不同模型或不同 prompt 的智能体开发者；
- 调试工具调用失败、无效重试、检索扑空等行为；
- 分析含子代理派生的复杂会话（实时页签，依赖宿主「后台加载子会话历史」能力）；
- 需要把轨迹导出为图分享给同事的场景。
使用注意：
- 实时迷宫只反映对话已加载窗口内的事件，不等于完整 session；全长分析请用 log 上传。
- 支路判定基于确定性规则，阈值可在
VERDICT_RULES按项目语料调整，但不调用 LLM 二次判断。 - 子代理支路在官方 rc 线暂缺「后台加载子会话历史」时会自动静默隐藏。
- Node 引擎要求：
^22.19.0 || >=24.0.0（见 package.json）。
结尾¶
dsh-trace-compare 把智能体「实际走过哪条路」从日志里抽出来，画成可缩放、可对比、可导出的迷宫图。离线双会话对比与实时页签共用一套判定与时间轴规则，适合在 DSH 开发流程里做轨迹复盘与运行差异分析。
