前言¶
DeepSeek Harness（DSH）用于调试和评估 Agent 行为，但面对长链路执行，开发者很难直观看到 Agent 在时间轴上的真实流动、失败节点以及 Token 消耗情况。dsh-maze 将 Agent 的执行过程绘制成一张“迷宫图”，把主干路径、失败支路和折返点落在同一根时间轴上，并提供数据轨道和分析面板。
这是什么¶
dsh-maze 是 DeepSeek Harness 的执行迷宫插件，由用户 lamost423 维护。
该插件原名 dsh-trace-compare，在 v1.0.0 版本起更名为 dsh-maze。旧包保留可安装但不再更新，如需迁移只需执行两条命令（具体命令见迁移说明）。
它主要解决 Agent 调试中的可视化问题：通过时间轴、数据轨道和确定性分析，让开发者看清 Agent 是如何一步步走到结果的，而不是依赖 LLM 的自我陈述。
核心功能¶
迷宫时间轴
将执行过程的主干路径、失败支路和折返点绘制在同一时间轴上。系统会自动折叠超过 60 秒的空闲区间（显示为 ⏸ 标注），并将密集的操作段聚合成“×N”的徽标（点击可放大查看标签详情）。进度条带有失败热力色，即使是一场 8 小时的长会话，也能保持字字可辨。
数据轨道
在时间轴下方提供与迷宫联动的数据轨道：
* 工具调用密度：按工具类型着色，显示每次调用的刻线。
* Token 脉冲：堆叠柱状图展示缓存输入、未缓存输入、推理和可见输出的 Token 数量。
* 上下文压力：折线+面积图，显示模型窗口占用百分比及 70%/90% 阈值线。上下文压缩事件会标注为“⌄−N%”，悬停可查看压缩前后的真值。
确定性执行分析
所有统计数据均为对判定数据的确定性聚合，不调用 LLM。
* 失败恢复链：记录每个失败调用后的处理方式（原样重试 / 换参数 / 换工具 / 未恢复）及耗时。
* 执行分析区：提供耗时分布散点图、工具结果矩阵（含成功率、P50/P95/最长耗时），以及任务完成度判定（任务完成 / 测试 / 构建 / Lint / 产物 / 人工确认）。
多会话对比
支持同一任务在不同模型上的 2~5 次跑同轴对比。功能包括轮次对齐线（自动连接各轮的回答节点）、手动锚点（钉住语义等价的时刻）以及支路盘点（按轮次列出各泳道的支路步数和耗时差）。
回放与导出
支持最高 300× 的速度回放整场执行过程。支持一键导出当前视图（含缩放窗口与过滤状态）为 SVG 或 2x PNG，导出固定为浅色底，适合分享。
其他特性
* 界面双语：支持中英文切换。
* 主题跟随：自动跟随宿主 DSH 的明暗主题。
* Agent 关系图谱：可视化主 Agent 与子代理的星形总览。
典型用法¶
实时迷宫
在 DSH 的对话页签中，迷宫会随当前会话实时生长。侧边栏的「执行迷宫」入口也可以直接打开实时迷宫页签。
单看或对比
点击侧边栏的「执行迷宫」，上传 session log 文件即可查看或对比历史会话。
定位与回溯
在迷宫图上点击任意节点或弧线，右侧会打开详情面板，显示完整命令、返回内容（前 5000 字）、耗时和判定依据。详情面板提供「在对话中定位此步骤」功能，可直接跳回对话页并高亮对应行。
导出视图
迷宫图支持导出为 SVG 或 2x PNG 图片。
注意事项¶
- 数据真实性：插件对判定数据的聚合是确定性的，不调用 LLM。数据缺失时如实标注（不画没有数据的轨道、不猜未知模型的窗口），绝不编造。
- 旧版本提示：
dsh-trace-compare旧包保留可装但不再更新。 - 依赖宿主能力：实时页签中的子代理支路功能依赖宿主对子会话历史的后台加载能力。
结尾¶
dsh-maze 通过可视化的方式，将 Agent 的执行迷宫、数据轨道和确定性分析整合在同一个界面中。对于需要深入理解 Agent 行为逻辑、排查长链路问题或对比不同模型性能的开发者来说，这是一个实用的调试工具。
