dsh-maze
DeepSeek Harness 的执行迷宫——看 Agent 真实怎么干活:迷宫时间轴 · 数据轨道 · 确定性执行分析 · 多会话对比 | The execution maze for DSH agents: maze timeline, per-step data tracks, deterministic execution analysis, multi-session comparison. Formerly dsh-trace-compare.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/lamost423--dsh-maze)HTML
<a href="/listings/lamost423--dsh-maze"><img src="/api/listings/lamost423--dsh-maze/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**先看你的宿主是哪来的。** 宿主 `0.1.2` 把客户端包重新拆分了一次(`dsh-client-runtime` 拆成 `dsh-client-store` 等),同时换掉了会话快照的数据模型,所以两条线的插件不通用:
| 你的宿主 | 装哪个版本 | 命令 | |---|---|---| | `0.1.2` 及以后——npm 的 `@deepseek-ai/dsh`(现在的 `latest` 是 `0.2.0-rc.2`)、内核 `0.1.2` 以后的各家桌面版、或自建 master | dsh-maze `2.x`,`latest` 标签 | `dsh plugin --profile web add dsh-maze` | | 老宿主(`0.1.0-rc.6` ~ `0.1.1-rc.2`) | dsh-maze `1.1.2`,手动钉版本 | `dsh plugin --profile web add dsh-maze@1.1.2` |
**宿主 `0.1.7` 起需要 dsh-maze `2.3.0` 及以上**:`0.1.7` 改了图标名和子代理目录接口,更早的 `2.x` 装上去侧边栏入口不显示、实时迷宫页签空白。`0.1.6-alpha.2` 起的宿主上 `2.2.0` 虽然不崩,但切换会话时不再自动关闭上传面板,也建议升级。**桌面版(`0.2.0-rc.2`)请用 `2.4.0`**:本版把 `@deepseek-ai/dsh*` 的 peer 范围从 `<0.2.0` 放开到 `<0.3.0`,并把构建产物 `lib/` 纳入版本控制——否则从 GitHub 安装会装出一个没有 `lib/index.js` 的空壳,插件完全加载不了(2026-10-05 桌面版就是这个原因)。用 pnpm 11 的默认设置时,插件发新版后的 24 小时内,不带版本号的安装会解析回上一版,这时请钉精确版本,例如 `dsh plugin --profile desktop add dsh-maze@2.4.0`。
兼容性:`2.4.0` 对着 npm 的 `0.2.0-rc.2` 全家桶构建,类型检查另在 `0.1.2-rc.1`、`0.1.5-rc.3` 两套包上跑过,均为零错误,158 个测试全绿;实机验收在全新的 `0.1.5-rc.3`、`0.1.7-rc.2`、`0.2.0-rc.2` 宿主上做过(`2.3.0` 那轮:装上安装包、用模拟模型跑会话、界面数字与宿主自己的统计逐项对账,上传页也读通了这些宿主写出的第 3 版、第 4 版会话日志),`0.2.0-rc.2` 桌面版另装了本版做回归。`1.1.x` 已对官方 `0.1.0-rc.6`(构建 + 全量测试)与 `rc.8`(插槽/类型核对 + 实机验收)验证。
npm install --global @deepseek-ai/dsh dsh plugin --profile web add dsh-maze dsh web
重启 `dsh web` 后,侧边栏底部出现「执行迷宫」入口,每个会话视图多一个「实时迷宫」页签。
从源码安装:
git clone https://github.com/lamost423/dsh-maze.git cd dsh-maze corepack enable && pnpm install && pnpm build dsh plugin --profile web add . dsh web
也可以直接从 GitHub 装(仓库里带着构建产物,不用你本地构建;不钉版本时拿到的是默认分支最新提交):
dsh plugin --profile desktop add github:lamost423/dsh-maze
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 162 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # dsh-maze
- > 🔀 **`dsh-trace-compare` 已更名为 `dsh-maze`**(v1.0.0 起)。旧包保留可装但不再更新,[迁移只要两条命令](#从-dsh-trace-compare-迁移)。
- 中文 | [English](README.en.md)
- [](https://www.npmjs.com/package/dsh-maze)
- [](https://www.dsh.so/zh/artifact/dsh-maze)
- [](https://www.dsh.so/zh/artifact/dsh-maze)
- [](https://github.com/bruc3van/awesome-dsh-plugin)
- [](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
- [](https://dshbase.com/plugins/dsh-maze/)
- [](https://github.com/Dominic789654/awesome-deepseek-harness)
- [](https://github.com/0xsline/awesome-deepseek-harness)
- [](https://github.com/XingLingQAQ/dsh-plugin-registry)
- [](https://dshfind.com/zh/plugins/lamost423/dsh-maze?ref=badge)
- [](https://github.com/unStone/dsh-xray)
- [](https://whyihaveyou.github.io/dsh-suite/)
- [](https://github.com/AdamPlatin123/dsh-plugin-radar)
- <sub>还被收录于:[fendouai/awesome-deepseek-harness](https://github.com/fendouai/awesome-deepseek-harness)(独立介绍页)· [Zhiyuan-Fan/Awesome-DeepSeek-Harness-Plugins](https://github.com/Zhiyuan-Fan/Awesome-DeepSeek-Harness-Plugins) · [ZeroPointRepo/awesome-dsh-plugins](https://github.com/ZeroPointRepo/awesome-dsh-plugins) · [cccakeee/awesome-dsh-plugins](https://github.com/cccakeee/awesome-dsh-plugins) · [diegosouzapw/awesome-omni-dsh-plugins](https://github.com/diegosouzapw/awesome-omni-dsh-plugins) · [anbeime/skill](https://github.com/anbeime/skill) · [dsh-app 内置插件市场](https://github.com/JochenYang/dsh-app)</sub>
- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的**执行迷宫**:把 Agent 真实的干活过程完整画出来、并分析给你看。
- 
- - **迷宫**——主干路径、失败支路、折返点落在同一根时间轴上;空闲自动折叠、密集段自动聚合成「×N」徽标(点击放大、标签逐级补齐)、进度条自带失败热力,8 小时的会话照样字字可辨:
- 
- - **数据轨道**——每一步的工具调用密度、Token 脉冲(缓存背景 + 未缓存输入/推理/输出增量柱)、上下文压力曲线(70%/90% 阈值线、压缩事件「⌄−N%」标注,悬停看压缩前后真值):
- 
- - **执行分析**——失败恢复链(原样重试 / 换参数 / 换工具 / 未恢复)、工具结果矩阵、耗时分位散点。**每个结论一键点回原始命令与返回内容**:
- 
- - **多会话对比**——同一任务在不同模型上的 2~5 次跑同轴对比:轮次对齐、手动锚点、支路盘点。
- 
- - **回放**——最高 300× 重放整场执行,看它是怎么一步步走到结果的:
- 
- **铁律**:所有数字都是对判定数据的确定性聚合,不调 LLM;每个判定带依据、每个结论可回溯到证据;数据缺失时如实标注(不画没有数据的轨道、不猜未知模型的窗口),绝不编。
- 两个入口:会话内的「**实时迷宫**」页签(随当前会话实时生长),侧边栏的「**执行迷宫**」(上传 session log 单看或对比)。
- ## 迷宫画的是什么
- - 实线:主干路径——工具调用成功推进的步骤和回答节点。
- - **时长胶囊条**:每个步骤画成从开始到结束的圆角条,判定色填充——3 分钟的 bash 和 0.2 秒的 read 一眼可辨;条够宽时耗时直接写在条内。
- - **并行工具分行**(v0.3.2 起):一步内 ≥2 次工具调用时,每次调用画成胶囊条下方的细小条(瀑布惯例),按各自真实起止摆位、按各自判定上色——一眼看出并行发的几个调用里哪个拖了时间、哪个失败;悬停单条看该次调用的命令/返回/判定依据,泳道高度随最大并行数自适应。支路节点保持「+N」标签(其空间为固定泳道格,详情面板已列全)。
- - 虚线弧:探索支路——工具失败(红 ✗)、检索扑空(灰 ·)或盲目重试(灰 ↻)的步骤,以及折返回分支点的回程线。
- - **子代理支路**(v0.4.0 起,实时页签):模型派生的 dsh 子代理会话画成主干上分出的聚合支路节点——挂靠在派生它的那一步、与父会话共享时间轴,节点子条是子代理全部已判定的工具调用,运行中的子代理实时生长并标注「仍在运行」;悬停/详情面板显示「子代理支路」身份与派生汇回关系,点击跳回主对话中的派生位置。只认真正的任务子代理(`origin: 'subagent'`),手动分支和 side-chat 侧聊不入图。宿主 `0.1.6-alpha.2` 起子会话须先被持有才能读取,插件在这些宿主上自己持有子会话(来源名 `maze`,不切换当前会话):成员来自父会话的子代理目录,迷宫打开之前就结束的子代理也画完整支路;运行中的一直持有、已结束的读一次就释放并缓存;同时最多展开 8 个,超出的在泳道上注明。更早的宿主(`0.1.5` / `0.1.2`)只画宿主已打开过的子会话。支路名字取派出时的任务简述;运行中的支路每秒向右生长。
- - 悬停任意节点或弧线快速预览;**点击**在右侧打开固定详情面板——完整命令与返回内容(各带复制按钮,返回内容保留前 5000 字)、耗时、判定、思考摘要,Esc 或 × 关闭。
- - **缩放导航**:滚轮以光标为中心横向缩放,拖拽平移,双击空白处或「⤢ 整图」按钮复位;轴刻度随缩放窗口自动加密(最细到 1 秒)。
- - **跳转对话**(仅实时页签):详情面板里点「在对话中定位此步骤」,宿主切回对话页并滚动高亮对应的工具行。行太老、超出对话已加载窗口时退化为只切页签。
- - **搜索与过滤**:工具行提供「只看失败/重试」开关、按工具类型过滤、命令与返回内容全文搜索(含 5000 字面板全文);不命中的节点与支路淡化到 15% 透明度,实时显示命中步数。实时模式下过滤状态在重建后自动还原。
- - **轮次对齐线**(同任务对比件,v0.3.0 起,现扩到 2~5 泳道):仅当各文件被识别为同一任务的多次跑(首条用户消息一致)时启用。每一轮的回答节点自动连成跨泳道对比链,标注各泳道**本轮各自的耗时**(该轮起点 → 回答完成;轮与轮之间等用户输入的空闲不计入,v0.5.1 起);双泳道额外标注耗时差与该轮支路数差(如「第 3 轮耗时:1st 4m ↔ 2nd 6m(Δ2m)· 支路 4↔0」)。只连该轮出现在 ≥2 条泳道的轮次——旧版从特定任务总结的「模型列表结果」正则里程碑已退役。
- - **手动锚点**(同任务对比件):「🔗 加锚点」后在任意两条泳道各点一个节点,钉一条带时差标注的对比线;点线删除,Esc 取消选点。适合钉住语义等价但轮次错位的时刻。
- - **支路盘点**(同任务对比件):「📋 支路盘点」打开按轮次的盘点表——每轮各泳道的支路步数、墙钟耗时、类别构成(✗ 失败 / ↻ 无效重试 / · 扑空),双泳道附差额列(如「第 2 会话多耗 48.4s」);点一行缩放到该轮并只保留该轮支路,其余淡化。某泳道没有这轮显示「—」,缺席本身就是信号。任务不同的文件仅同轴并排,这三样不出现(图例明示原因)。
- - **泳道数据轨道**(v0.7 起,📊 可开关):泳道带底部三条与迷宫同一时间轴联动的轨道——**工具调用密度**(每次调用一根刻线,按读取/检索/命令/编辑/其他着色)、**Token 脉冲**(每步堆叠柱:缓存输入/未缓存输入/推理/可见输出,读自 usage 真值)、**上下文压力**(折线+面积,纵轴随数据自适应;模型窗口已知时显示占用百分比与 70%/90% 阈值线,上下文压缩呈现为锯齿下落,窗口未知或表值过时自动退回绝对 token 数——绝不显示超过 100% 的占用)。日志没报 usage 的轨道不画、不占高度。
- - **执行分析区**(v0.7 起,迷宫下方主界面直出):摘要三卡(工具失败与恢复 / 时间消耗 / 上下文压力)+ **耗时分布散点图**(每工具一行,P50/P95 参考线,失败点标红,悬停看单次调用)+ 按工具的结果矩阵(成功/失败/扑空/盲重试/成功率 + P50/P95/最长耗时)+ **失败恢复链**——每个失败调用之后发生了什么:原样重试 / 换参数 / 换工具 / 未恢复,恢复耗时如实标注;点一条缩放到该失败并打开详情。口径:链只统计失败(✗),扑空(· 检索无结果)与盲重试(↻)计入矩阵各自列、不单独进链,盲重试也不作为恢复证据。全部数字是确定性聚合,不调 LLM。
- - **结果与证据**(诊断层第 1 项,分析区首块):六格——任务完成 / 测试 / 构建 / Lint / 产物 / 人工确认——加一个综合徽标(已完成 / 部分成功 / 未验证),全部来自日志证据、不信 Agent 自述。测试/构建/Lint 按命令正则在**命令位置**识别(初版覆盖 JS/TS、Python、Rust、Go、Swift;npm/pnpm/yarn 的 `check` 脚本按测试计;`cat vitest.config.ts`、`grep pytest` 不算),一条命令命中多类分别记;通过 = 该调用没有错误标志且返回**末行**没有非零退出码;每个类别以最后一次运行的结果为准,此前别的命令最后一次失败的条数小字注明(「同一条命令」按命中的那段算,`cd` 前缀、重定向、`&& echo PASS` 装饰不同不算两条);后台任务按之后 `job_output` 末行的退出码计,取不到就不计并标注;点格定位到最后一次运行所在的那一步并打开该步详情。产物 = 写入/编辑/补丁类调用成功触及的文件去重(格内展开路径);任务完成 = 最后一轮 `turn/end` 不是 error/aborted/interrupted/blocked 且最后一步是回答;人工确认只看最终回答之后有没有真人消息,不解读内容。一条验证命令都没有时显示中性的「未验证」;code 模式会话(`run_code`)里脚本内部派发的真实命令暂不识别,块里如实标注。规则在 `verdict.js` 的 `ANALYSIS_RULES.VALIDATION`。
- - **行为信号**(诊断层第 2 项,失败恢复链旁的块):每条带严重度(高/中/低/信息)、一句话依据(含具体数字)和涉及调用数——失败后原样重试、同轮重复调用(含重复读取子标签)、循环、工具失败、慢调用(≥120 秒)、工具集中度(赫芬达尔指数)、上下文骤升/骤降(骤降落在压缩事件附近标「压缩」)、上下文峰值、压缩发生、待办陈旧、换策略恢复。阈值按本机 202 份会话校准(「中」落在最差的 15%~20% 会话,「高」落在最差的 3%~5%),常量在 `verdict.js` 的 `ANALYSIS_RULES.SIGNALS`;各信号独立计数。点一条淡化其他节点并定位到该段第一个调用(再点或按 Esc 取消,与其他过滤叠加);没有信号时明说「本场没有触发任何信号」。code 模式本版只统计外层 run_code 调用,方法说明注明。上下文占用(峰值信号、上下文压力轨道、摘要卡与头部指标条)按每次请求当时的模型换算窗口:上传日志读 `request/context`,实时页签按逐请求模型查表;轨道纵轴是占用百分比,标题标注中途切过的窗口和因窗口值不可信而略过的样本。
- - **Agent 关系图谱**(v0.7 起,分析区内的块):主 Agent 与子代理的星形总览,节点大小 = 各 Agent 消耗的 token、连线粗细 = 工具调用数、运行中的虚线标示;点子代理节点跳到时间轴位置。只在有子代理数据时出现。
- - **导出**:一键导出当前视图(含缩放窗口与过滤淡化状态)为 SVG 或 2x PNG,样式已内联、拿去即用;**无论页面当前是浅色还是暗色,导出固定浅色底**(分享场景)。
- - **界面双语**(v0.5.0 起):整页 UI(上传区、图例、泳道统计、对齐线、支路盘点、悬停卡、详情面板、错误提示)中英双语,嵌入宿主时实时跟随 dsh 的语言设置切换,独立打开按浏览器语言兜底;判定依据是结构化键值、按当前语言渲染,切语言不用重新上传。
- - **主题跟随**(v0.3.1 起):页面随宿主 dsh 的明暗主题自动切换(宿主组件监听 `body[data-ds-dark-theme]` 并 postMessage 进 iframe);独立打开时按系统偏好。
- - **设置页开关**(v2.1.0 起):「设置 → Maze」可隐藏侧边栏入口——只用「实时迷宫」页签的人可以把常驻按钮收掉,开关即时生效、无需刷新,按浏览器保存;隐藏后实时页签与已打开的迷宫页不受影响。
- - **紧凑页头**(v0.3.1 起):出数据后说明文字隐藏、上传区收成细条、泳道统计卡隐藏(同信息已画在泳道带内)、图例压成一行——迷宫拿走绝大部分视口。
- - 播放功能最高 300× 回放整次运行。
- 时间轴的诚实规则:
- - **空闲折叠**:超过 60 秒没有任何步骤/工具活动的区间(比如两轮对话之间你在思考)压缩成一条带 `⏸` 标注的细缝,标明省略了多久;活动段内的刻度仍显示真实墙钟时间。
- - 步骤标识带轮次(`S15·47`),多轮会话的支路不会挂错节点。
- - 步骤时长、工具耗时、总耗时都保持墙钟真值,只有轴被压缩。
- - **实时页签只画对话已加载的事件窗口**(v0.2.3 起诚实标注):窗口边缘残留的更早轮次步骤会被丢弃并标注「⏮ 另有 N 步更早历史未加载」,不再钳到 0 秒堆在左边缘、虚高统计;要看全会话用「Session log 下载 → 上传对比」。
- - **token 是真值**(v0.2.2 起):推理/输出 token 读自 session log 里 `assistant/message` 的 `usage`(此前的「reasoning N tok」数的是流式段数,不是 token)。日志没有 usage 时标签诚实回退为「推理 N 段(日志未报 token 用量)」——中转站日志常缺推理 token 字段,与原厂日志并排时单位不同,标签自带原因(v0.5.1 起)。
- 判定的诚实规则(v0.2.1 起):
- - **不按输出长度判定**。单工具判定三层:错误标志(isError)→ 失败特征 → 按工具分类(写入类无错误即成功;检索类空结果才算扑空;bash 及未知工具有输出即成功)。
- - **失败特征只扫开头与末尾窗口**(v0.2.3 起):真实报错要么从开头开始说、要么是追加在末尾的 stderr 段;而 git log / 读文件 / 转储日志时**引用**的报错字样悬在长文本中部——判定刻意不看那里,避免把「病历」当「发病」(实测案例:提交信息里写 "upstream returns HTTP 400" 被误判为该命令失败)。两条渲染链路统一在未截断的全文上判定。
- - **盲目重试**是行为学判定:时间序上连续的「同工具 + 参数相似」调用簇、且簇内至少一次失败,才标为无效重试——借鉴 AgentLens 对 SWE-agent 轨迹「浪费」的确定性检测。
- - 每个判定都带**依据文本**,悬停 tooltip 和详情面板可见(如「同一操作连续重试 4 次(其中 1 次失败),判为盲目重试」)。
- - 全部阈值与分类在 `src/client/verdict.js` 的 `VERDICT_RULES` 常量里,可按项目语料调整;页面与实时两条渲染链路共用这一份实现(构建期注入)。
- ## 支持的 session log 格式
- 按文件内容识别格式,文件名任意(macOS 复制出的「session.jsonl 2」也能直接选):
- - 纯文本 `.jsonl`(session 格式 v0 事件流)
- - `~/.dsh/sessions/` 下原样的 `.jsonl.zstd`——浏览器端直接解压(原生 `DecompressionStream('zstd')` 可用时优先,否则用内置的 [fzstd](https://github.com/101arrowz/fzstd))
- ## 安装
- **先看你的宿主是哪来的。** 宿主 `0.1.2` 把客户端包重新拆分了一次(`dsh-client-runtime` 拆成 `dsh-client-store` 等),同时换掉了会话快照的数据模型,所以两条线的插件不通用:
- | 你的宿主 | 装哪个版本 | 命令 |
- |---|---|---|
- | `0.1.2` 及以后——npm 的 `@deepseek-ai/dsh`(现在的 `latest` 是 `0.2.0-rc.2`)、内核 `0.1.2` 以后的各家桌面版、或自建 master | dsh-maze `2.x`,`latest` 标签 | `dsh plugin --profile web add dsh-maze` |
- | 老宿主(`0.1.0-rc.6` ~ `0.1.1-rc.2`) | dsh-maze `1.1.2`,手动钉版本 | `dsh plugin --profile web add dsh-maze@1.1.2` |
- **宿主 `0.1.7` 起需要 dsh-maze `2.3.0` 及以上**:`0.1.7` 改了图标名和子代理目录接口,更早的 `2.x` 装上去侧边栏入口不显示、实时迷宫页签空白。`0.1.6-alpha.2` 起的宿主上 `2.2.0` 虽然不崩,但切换会话时不再自动关闭上传面板,也建议升级。**桌面版(`0.2.0-rc.2`)请用 `2.4.0`**:本版把 `@deepseek-ai/dsh*` 的 peer 范围从 `<0.2.0` 放开到 `<0.3.0`,并把构建产物 `lib/` 纳入版本控制——否则从 GitHub 安装会装出一个没有 `lib/index.js` 的空壳,插件完全加载不了(2026-10-05 桌面版就是这个原因)。用 pnpm 11 的默认设置时,插件发新版后的 24 小时内,不带版本号的安装会解析回上一版,这时请钉精确版本,例如 `dsh plugin --profile desktop add dsh-maze@2.4.0`。
- 兼容性:`2.4.0` 对着 npm 的 `0.2.0-rc.2` 全家桶构建,类型检查另在 `0.1.2-rc.1`、`0.1.5-rc.3` 两套包上跑过,均为零错误,158 个测试全绿;实机验收在全新的 `0.1.5-rc.3`、`0.1.7-rc.2`、`0.2.0-rc.2` 宿主上做过(`2.3.0` 那轮:装上安装包、用模拟模型跑会话、界面数字与宿主自己的统计逐项对账,上传页也读通了这些宿主写出的第 3 版、第 4 版会话日志),`0.2.0-rc.2` 桌面版另装了本版做回归。`1.1.x` 已对官方 `0.1.0-rc.6`(构建 + 全量测试)与 `rc.8`(插槽/类型核对 + 实机验收)验证。
- ```sh
- npm install --global @deepseek-ai/dsh
- dsh plugin --profile web add dsh-maze
- dsh web
- ```
- 重启 `dsh web` 后,侧边栏底部出现「执行迷宫」入口,每个会话视图多一个「实时迷宫」页签。
- 从源码安装:
- ```sh
- git clone https://github.com/lamost423/dsh-maze.git
- cd dsh-maze
- corepack enable && pnpm install && pnpm build
- dsh plugin --profile web add .
- dsh web
- ```
- 也可以直接从 GitHub 装(仓库里带着构建产物,不用你本地构建;不钉版本时拿到的是默认分支最新提交):
- ```sh
- dsh plugin --profile desktop add github:lamost423/dsh-maze
- ```
- ## 从 dsh-trace-compare 迁移
- ```sh
- dsh plugin --profile web remove dsh-trace-compare
- dsh plugin --profile web add dsh-maze
- ```
- 旧包停在 v0.7.0(功能与 dsh-maze 1.0.0 相同),此后只有 dsh-maze 继续更新。GitHub 旧地址自动重定向到本仓库。
- ## 版本历史
- 全部演进见 [CHANGELOG.md](CHANGELOG.md)。
- ## 开发
- ```sh
- pnpm install
- pnpm check # 类型检查 + vitest + 构建
- ```
- 上传/可视化页面是一份自包含的 HTML(`src/client/maze-upload.html`),运行在沙箱化的 `<iframe srcDoc>` 里;解析与渲染全部在浏览器端完成,上传的日志内容不会到达宿主。
- ## 许可
- MIT。见 [NOTICE](NOTICE)——本项目包含源自 DeepSeek Harness 的衍生代码。
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.