前言¶

用 DeepSeek Harness（DSH）跑长任务时，原生轨迹会记录消息、工具调用和事件，但一轮任务往往包含成百上千个步骤。想回答几个基本问题并不容易：Agent 实际采用了什么策略？哪些步骤在推进任务，哪些是重复试探？失败来自模型判断、工具使用还是环境条件？一段「已经完成」的回答有没有足够证据？

逐条翻轨迹效率很低。下面介绍的 dsh-trace-insight 做的就是这件事：把密集的轨迹事件整理成持续更新的分析时间线，并让每条结论都能回到对应的原始事件。

这是什么¶

dsh-trace-insight（DSH Trace Insight｜DSH 轨迹解读器）是 Liu-Bot24 维护的 DSH 只读执行复盘插件，许可证为 MIT。DSH 的理念是「一切皆插件」，Trace Insight 就以插件形式接入 DSH web 界面的右侧栏，左侧保留对话或轨迹，右侧显示解读结果，宽度可调。

它直接读取 DSH 的结构化 Session Event Log，先用本机规则分析建立事实底座，再按需使用独立配置的模型解释决策、风险和改进方向。

边界需要先说清楚：插件只读取数据，不修改被检查的 Session、工作区、Skill 或全局记忆，也不干预、不暂停、不阻断开发 Agent 的执行。

核心功能¶

分析侧的能力：

• 持续复盘：按 Turn 和 Seq 整理规则分析与模型分析，长任务不必等到整轮结束就能看到阶段进展。
• 规则分析：在本机识别工具失败、重复失败、无进展循环、路径猜测、工具误用、完成信号和证据缺口，不调用模型。
• 模型解读：使用独立配置的 DSH 模型分析策略、根因、风险、下一步和可复用经验，不影响开发 Agent 的主模型。
• 受控重分析：为指定区间临时切换模型重新分析，不改变以后自动分析使用的默认模型。

消费分析结果的能力：

• 证据定位：从结论回到对应的 Seq、Turn、Step、Tool、摘录和原始前后文。
• 任务概览：按开发阶段、工具使用和问题线索汇总整个任务，只整理已有分析，不产生新的模型调用。
• 结果对比：比较同一段轨迹的两次成功模型分析，分别展示结论、配置、资源用量和原始证据，可观察不同模型或配置给出的差异。
• 历史与导出：分析记录保存在本机，可分别导出分析历史、原始 Session 历史或完整分析包。

右侧栏包含复盘、概览、对比、设置四个页面。

安装与启用¶

先确认环境：需要 Node.js 22.19.0 或更高版本（package.json 中 engines 要求 node >=22.19.0）。插件通过 dshCompatibility 声明兼容 DSH 0.1.0-rc.7、0.1.0-rc.8、0.1.1-rc.1、0.1.1-rc.2，surface 为 web。

安装前必须关闭正在运行的 DSH，然后下载或克隆仓库，在仓库根目录运行安装程序。

macOS 或 Linux：

bash ./install.sh

Windows 下双击 安装到DSH.cmd，或在 PowerShell 中运行：

powershell -ExecutionPolicy Bypass -File .\install.ps1

安装程序会为发现的每个受支持 DSH 安装接入右侧栏，插件包保存在 <DSH_HOME>/trace-insight/packages；安装完成后，DSH 不依赖源码目录或下载目录继续存在。

启动 DSH：

dsh web

如果没有全局 dsh 命令，使用：

npx --yes --package=@deepseek-ai/dsh dsh web

打开任意会话后，点击「解读」即可打开右侧栏。

一个需要留意的版本说明：README 提示当前版本请使用 packages/standard 下的「标准无补丁侧栏 1.5.0」，仓库根目录的安装、卸载脚本属于旧补丁版；标准版的具体安装方式见仓库 packages/standard/README.md，两版的具体关系资料中未展开，安装前建议先确认要用哪一版。

卸载同样先关闭 DSH，在仓库根目录运行对应的卸载脚本（uninstall.sh / uninstall.ps1 / 双击 卸载插件.cmd）。卸载会移除 Trace Insight、右侧栏和安装程序管理的插件包，已保存的分析历史保留在数据目录中。

典型用法¶

第一次使用的完整流程：

1、打开任意 DSH 会话，点击「解读」，进入「复盘」。规则分析直接读取现有轨迹，不需要配置模型。

2、如需模型解读，进入「设置 → 模型与自动策略」，选择 DSH 已注册的 provider 和模型并保存。

3、保存后可以等待自动分析触发，也可以在复盘中选择一段轨迹手动分析。

4、点击分析结论中的证据入口，查看对应的原始事件和前后文。

经过上面的步骤，每条模型结论和规则发现都可以打开独立证据抽屉，每条引用标出 Seq、Turn 和摘要，需要时再读取原始前后文。

有几件事不会触发模型调用：打开或刷新 Trace Insight、筛选时间线、查看证据、进入概览、对比已有分析。只有自动分析或用户主动发起模型分析时才产生模型请求。

模型配置分三层：全局默认模型、当前 Session 专用模型、仅本次分析临时使用的模型。只有前两项会保存；临时换模型不会修改以后自动分析使用的默认配置。自动分析只在 Session 已被实时执行纳入观察、已配置默认模型并满足触发条件时运行；模型失败、取消或返回无效结果时，分析进度不会越过该区间。

如果看不到「解读」入口，先完全关闭 DSH 再重新运行安装程序；仍未出现时，可以检查插件是否进入 web profile：

dsh --profile web --dump-config | grep "trace-insight"

Windows PowerShell 换用 Select-String：

dsh --profile web --dump-config | Select-String "trace-insight"

仅通过 npx 使用 DSH 时，把命令中的 dsh 替换为 npx --yes --package=@deepseek-ai/dsh dsh。

数据目录与导出¶

默认数据目录如下，设置了 DSH_HOME 时为 <DSH_HOME>/trace-insight：

目录中主要包含 settings.json 和 sessions/<session-id-hash>.json。

导出分三类：分析历史（规则分析、模型分析、运行状态和分析进度）、原始 Session 历史（DSH 原始事件、surface 与会话谱系）、完整分析包（前两者都有）。导出原始历史或完整分析包时需要再次确认；分析历史可能包含证据摘录和模型原文，共享前先检查内容。

隐私与费用边界¶

• 规则分析完全在本机运行，不调用模型。
• 模型输入使用经过裁剪和常见凭证脱敏的轨迹证据，不会发送完整原始日志；使用外部模型时，相应证据会发送给你选择的模型供应商。
• 原始 Session 数据默认不会包含在普通分析导出中。
• Trace Insight Host RPC 仅允许 loopback 页面访问，需在运行 DSH 的同一台机器上通过 127.0.0.1 或 localhost 使用；通过局域网地址打开 DSH 时读不到数据。

适用场景与注意¶

适合的人群和场景：经常用 DSH 跑长任务、需要复盘 Agent 行为的开发者；想在保留原始轨迹的同时获得结构化分析的人；需要在同一段轨迹上对比不同模型或配置解读结果的场景。

使用前注意几点：

1、插件以当前 DSH 进程的权限运行，安装前应自行检查仓库源码与许可证（当前为 MIT）。
2、安装和卸载前必须关闭正在运行的 DSH。
3、显示「等待默认模型」时，规则分析仍会继续运行；配置默认模型后模型分析才会开始。模型分析失败时，失败记录保留，进度不跳过失败区间，可检查 provider 凭证、模型路由和限流状态后从失败区间重试。

结语¶

dsh-trace-insight 把轨迹复盘拆成两层：本机规则分析做事实底座，独立配置的模型做解释层，所有结论都能回溯到原始事件，且全程只读、不干扰开发 Agent。如果你在用 DSH 跑长任务并苦于逐条翻轨迹，可以试试它。

• 社区插件目录：https://www.skillhub.cn/plugins/Liu-Bot24/dsh-trace-insight
• GitHub 仓库：https://github.com/Liu-Bot24/dsh-trace-insight