# dsh-trace-compare

> 为 DSH 智能体执行轨迹画时间轴迷宫：主干路径、失败探路、盲目重试一目了然；支持上传日志单/双会话对比与会话实时跟随，无需配置。

## Metadata

- Author: [@lamost423](https://github.com/lamost423)
- Repo: <https://github.com/lamost423/dsh-trace-compare.git>
- GitHub: [lamost423/dsh-trace-compare](https://github.com/lamost423/dsh-trace-compare)
- Stars: 41
- Language: HTML
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `agent-observability`, `agent-trajectory`, `ai-agents`, `deepseek-harness`, `dsh`, `dsh-plugin`, `llm-agents`, `observability`, `trace`, `tracing`, `visualization`
- Forks: 2
- Open Issues: 2
- Last push: 2026-08-20T12:52:10.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:lamost423/dsh-trace-compare
```

## Wiki

## 一句话定位
把 DSH 智能体真实的执行轨迹画成一张时间轴迷宫：它坚持推进的主干、失败或扑空的支路、折返点都落在同一根时间上，肉眼判断「为什么跑成这个结果」。

## 核心能力
- 上传 1 个 session log 画单次运行的迷宫时间轴（支持 .jsonl 与 .jsonl.zstd，浏览器端解压）
- 上传 2 个 session log 做同轴对比：按轮次自动对齐回答节点、可手动锚点、按轮次盘点支路差额
- 实时迷宫页签随当前会话执行生长，工具结果一旦落定，支路立刻显现
- 每步失败/扑空/盲目重试都有判定依据（错误标志 → 强失败特征 → 弱失败特征 → 按工具分类的四层规则 + 行为学重试簇）
- 节点长度 = 步骤真实耗时（并行工具调用按瀑布行分行），悬停预览、点击打开详情面板、滚轮缩放、拖拽平移
- 一键导出当前视图为 SVG 或 2x PNG（浅色底），输入框支持「只看失败/重试」+ 按工具过滤 + 全文搜索

## 技术实现
- **语言**: TypeScript + 内嵌 JS（迷宫页面跑在自包含 HTML 里）
- **关键依赖**: @deepseek-ai/cordis、@deepseek-ai/dsh-client-runtime、@deepseek-ai/dsh-client-ui-slots、fzstd
- **架构模式**: Cordis 客户端插件，通过 slots 注入 sidebar.footer.action（入口按钮）+ shell.overlay（上传对比浮层）+ conversation.view（实时迷宫页签）；可视化页面用 sandbox iframe（srcDoc）渲染，主机只通过 postMessage 同步主题与语言
- **入口文件**: src/client/index.ts（插件装配）、src/client/maze-upload.html（自包含可视化页面，构建时由 tsdown 注入 fzstd UMD）

## 适用场景
调试 DSH 智能体为什么跑出某个结果——回看整次运行的主干和支路；当同任务用不同模型/不同参数跑出差异时，把两份 log 叠在一起对比哪一步走偏了；边跑边盯实时页签，看到当前模型在哪一步犹豫、哪一步失败、是否在重复同一件事。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 0.1.0-rc.6+ | 已对 rc.6 全量验证、rc.8 实机验收，peer 范围覆盖 rc.6 到当前 rc 线 |
| Node | ^22.19.0 或 >=24.0.0 | engines 声明 |
| 平台 | 跨平台 | 纯前端插件，不依赖原生模块 |
| 原生模块 | 无 | zstd 在浏览器内用 JS 软解压（fzstd）或原生 DecompressionStream |

## 安装方式
```bash
dsh plugin --profile web add github:lamost423/dsh-trace-compare
```

## 配置项
本插件无需额外配置。

## 常见问题

**Q: 安装后要做任何配置吗？**

A: 不需要。安装并重启 dsh web 后，侧边栏底部自动出现「Trace 对比」入口，每个会话视图也会多一个「实时迷宫」页签，立即可用。

**Q: 上传的 session log 内容会发到服务器吗？**

A: 不会。整个解析、判定、可视化都跑在 iframe srcDoc 沙箱里，浏览器端完成；日志内容不会到达宿主或任何外部服务。

**Q: 支持哪些 session log 格式？**

A: 支持纯文本 .jsonl，以及 ~/.dsh/sessions/ 目录下的 .jsonl.zstd。zstd 在浏览器里直接解压（原生 DecompressionStream 优先，否则用内置 fzstd 软解压）。按内容识别格式，文件名任意（如 macOS 副本「session.jsonl 2」也能直接选）。

**Q: 实时迷宫页签能看历史更早的步骤吗？**

A: 不能。实时页签只画当前对话已加载的事件窗口，窗口外的陈旧步会被丢弃并标注「另有 N 步更早历史未加载」。要看完全量历史，可以下载 log 后用「Trace 对比」上传。

**Q: 导出的图是什么主题？**

A: 固定浅色底，与页面当前是明是暗无关——专门为分享场景设计。

**Q: 子代理任务会出现在迷宫里吗？**

A: 在具备后台加载子会话历史（SessionFace.open）能力的宿主上会。官方 0.1.0-rc.6 至 rc.8 暂缺此能力，插件自动静默隐藏，不会报错，其余功能不受影响。

**Q: 判定工具调用成功还是失败用的什么方法？**

A: 纯规则，不调用 LLM——四层判定：错误标志 → 强失败特征（开头与末尾窗口）→ 弱失败特征（仅开头 300 字符）→ 按工具分类。配上行为学盲目重试簇检测（参数相似 + 簇内含失败）。阈值都在 src/client/verdict.js 的 VERDICT_RULES。

**Q: 怎么卸载？**

A: 通过 dsh 的标准插件命令移除，然后重启 dsh web 即可。

## 上手难度
入门 — 安装即用，没有任何配置项；上传或切到实时页签就能看到结果。

## 已知问题与限制
- 子代理支路依赖宿主 `SessionFace.open` 能力，官方 rc.6–rc.8 暂缺，插件自动静默降级为不显示子代理（CHANGELOG.md:5-15 / src/client/subagent-lanes.ts:84-102）
- 实时页签只画对话已加载的事件窗口，窗口外陈旧步被丢弃并标注「⏮ 另有 N 步更早历史未加载」（README.md:43-46）
- 上传 2 个 session log 时，最多支持 2 个；多于 2 个会被页面拒绝（maze-upload.html:275）
- 导出的 SVG/PNG 固定浅色底，与页面当前主题无关（README.md:35）
- 双会话对比的「轮次对齐线」只连两边都有的轮次，单边独有的轮次在支路盘点里以「—」显示（README.md:32-34）

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-trace-compare](https://deepseek-plugin.org/plugins/lamost423/dsh-trace-compare)
Wiki generated by AI (model: `MiniMax-M3`)