前言¶
在 DeepSeek Harness（DSH）里跑多步任务时，模型回复和工具调用往往串成一条长链。出问题时，仅靠终端滚动或零散日志很难回答「第几步开始偏了」「两次重试差在哪里」。手工复制上下文做对比也费时，且缺少每步耗时。
下面介绍社区插件 dsh-step-trace：把每个会话的步骤追加写入本地 replay 文件，并提供 CLI 与设置页里的面板，按步查看输入输出、分叉重跑，以及对比两条会话的分歧点。
这是什么¶
dsh-step-trace 由维护者 hj01857655 发布，npm 包名同为 dsh-step-trace。包描述为：记录智能体走过的每一步，并支持正向、反向逐步查看，定位出错环节。
独立仓库 hj01857655/dsh-step-trace 已在社区目录标注为已归档，源码曾并入 monorepo hj01857655/dsh-plugins；2026-10-20 起该 monorepo 工作区仅保留其余两个包，dsh-step-trace 等七个包已从仓库移除，但 npm 上仍可安装，安装方式不变（见 monorepo README 说明）。
SkillHub 目录页将本插件归类为可安装联网工具，当前展示版本为 v0.5.1；npm 最新版为 0.6.1（2026-10-16 发布）。许可证：MIT。
核心功能¶
以下能力均来自 npm 包 README，安装启用后由插件在 DSH 宿主侧接入。
记录与存储¶
- 每次模型回复与工具调用记为一条 trace step。
- 数据写入工作区下的
.replay/.jsonl：按会话分文件、仅追加（append-only）。
逐步查看与分支¶
- 可按步骤向前或向后浏览，查看该步完整输入与输出；每步带时间戳与耗时。
- 可从任意一步分叉（branch）出新会话，用于「若当时选了另一条路径会怎样」的试探。
- 分歧检测（divergence）：对同一任务的两条会话，找出第一个不一致的步骤，便于理解重试结果为何不同。
统计与界面¶
- 会话级统计：总步数、总时长、平均步延迟、最慢一步。
- Panel：Settings 内「Step trace」页；宿主注册
GET /api/step-trace.panel，每次请求从 replay 文件重建数据。无 Web 界面的 headless 宿主可跳过该路由。 - 面板包含：按时间排序的会话列表（步数、总时长）、逐步查看器、步骤耗时时间线、双会话分歧对比视图。
安装与启用¶
官方推荐从 npm 安装（需 DSH 的 web profile）：
dsh plugin --profile web add dsh-step-trace
README 亦给出从 GitHub 源安装的方式（独立仓库已归档，若命令失败可改用 npm）：
dsh plugin --profile web add github:hj01857655/dsh-step-trace
安装前建议在 npm 或历史提交中阅读源码与 MIT 许可证。插件以当前 dsh 进程权限运行，会读写工作区 .replay/ 下的会话数据。
典型用法¶
CLI¶
插件提供可在 DSH 外单独使用的命令行入口，常用子命令如下：
dsh-step-trace list # 列出已记录的会话
dsh-step-trace trace <id> # 显示某会话的全部步骤
dsh-step-trace step <id> <n> # 查看第 N 步详情
dsh-step-trace diverge <a> <b> # 找出两个会话首次分歧的步骤
将 <id> 换为 list 输出中的会话标识；<n> 为从 1 起的步序号。
设置面板¶
在 DSH Settings 中打开 Step trace 页：浏览会话、逐步查看 I/O、看时间线，或在分歧视图中并排对比两个会话。适合不习惯纯 CLI、但需要看清某步完整 payload 的场景。
适用场景与注意¶
适合谁
- 调试多步 Agent：定位第一次错误工具调用或异常模型输出。
- 对比两次运行（例如改 prompt 或换模型后重试），用
diverge或面板找分叉点。 - 需要会话级耗时分布，而不是只看总 wall time。
注意
- Replay 文件落在项目目录
.replay/，含模型与工具输入输出，请注意敏感信息与版本管理（勿误提交密钥）。 - 面板依赖 web profile 与宿主路由；纯 headless 环境以 CLI 与
.jsonl为主。 - 社区目录 SkillHub 与 GitHub 仓库并非 DeepSeek / 幻方官方应用商店；DSH 生态主张「一切皆插件」，安装第三方包前请自行审计代码。
结尾¶
dsh-step-trace 把「每步发生了什么、花多久、两条路何时分开」落到可查询的 replay 与 CLI/面板上，适合作为 DSH 多步任务的事后排查工具。
- 目录页：https://www.skillhub.cn/plugins/hj01857655/dsh-step-trace
- 原 GitHub 标识：
https://github.com/hj01857655/dsh-step-trace（已归档；当前 npm 主页指向 monorepo 历史路径） - npm：https://www.npmjs.com/package/dsh-step-trace
- 维护者 monorepo：https://github.com/hj01857655/dsh-plugins
