在 DSH Web 环境中开发智能体时，调试复杂的工具调用链路和推理过程往往需要精确的执行快照。dsh-trace-repeat 插件通过原子、版本化的方式，记录任意会话的执行 trace，将每次推理完成或工具执行封装为不可变版本，并支持基于 git worktree 的历史版本恢复。
功能特性¶
原子化版本记录¶
插件订阅宿主的 session/event，按序记录三种类型的版本：
1. 推理版本：对应 assistant/message，记录收齐后的最终消息。
2. 工具版本：对应 tool/call 和 tool/result，包含工具名、参数、执行结果及错误状态。
3. 用户版本：对应普通用户输入。
每个版本都是一个不可变的 JSON 文件，使用原子写操作（tmp 文件 + rename）落盘，索引文件同样原子更新，避免数据损坏。
完整可复现元数据¶
每个版本均附带完整的上下文信息，用于复现当时的执行环境：
* 推理元数据：provider、model、reasoningEffort、maxTokens、usage、完整 content。
* 工具元数据：工具名、callId、参数、结果、isError。
* 会话头信息：workspace、cwd、preset、agentOptions。
Git 版本管理与恢复¶
默认开启 git 版本化：trace 根目录被初始化为专用 git 仓库，每个版本对应一次 commit。插件支持将历史版本物化为 git worktree，路径位于 .dsh-trace-worktrees/<session>-v<seq>。
通过 /trace resume 命令，可以从任意历史版本恢复执行。系统会自动重建平衡上下文（截断到最近一个无悬挂 tool 调用的推理完成版本），并在对应的 worktree 中新开会话继续执行，新会话的 trace 独立产生。
安装与启用¶
插件通过 manifest 自动激活，无需额外配置。安装后需重启宿主进程。
# 从 GitHub 安装
dsh plugin --profile web add github:p2coder/dsh-trace-repeat
安装完成后，在浏览器中刷新 DSH Web 页面即可生效。
使用方式¶
安装并重启后，无需手动开启，任意会话的执行即自动记录。通过以下命令进行操作：
# 列出当前所有会话
/trace
# 查看指定会话的版本时间线及详情
/trace show <session> [vN]
# 从指定版本恢复执行
/trace resume <session> <vN>
注意事项¶
- 只记录最终消息：插件仅记录收齐后的最终消息，不记录流式输出的增量内容。
- 恢复版本限制：恢复执行只能在“推理完成”版本（即无悬挂 tool 调用）进行。若尝试在回合中间版本恢复，系统会报错并提示更早的平衡版本。
- 独立新会话：回放或恢复操作不会修改原会话的 trace，而是产生一个新的独立 trace。
- 工作区快照：git 物化操作仅覆盖 trace 文件，不包含该时刻工作区内的文件快照。
- 暂停/恢复标记：暂停/恢复标记版本仅在“暂停/恢复后的下一个会话事件”时写入。若仅执行暂停和恢复且中间无其他事件，则不会产生标记版本。
总结¶
dsh-trace-repeat 提供了从微观工具调用到宏观会话状态的完整记录链路。通过不可变版本和 git worktree，开发者可以方便地追溯任意时刻的执行上下文并进行状态回溯。
