轮次回溯 zhaolianghz/dsh-turnscope

dsh-turnscope

理解每一次 agent 轮次。安全回退。重试而不丢失好的工作成果。

dsh-turnscope 是一个 DeepSeek Harness 插件，面向使用 agent 修改代码的开发者。0.1.0 版本提供了一个原生、只读的轮次时间线，包含逐文件 diff 和确定性警告，以及预览优先的安全回退（轮次面板中的 Preview / Apply 按钮）。分叉重试仍计划在 V0.3 中实现。0.1.1 / 0.1.2 / 0.1.3 / 0.1.4 / 0.1.5 补丁改进了渲染器行为（见下方更新日志）。

状态：V0.1.5 已发布（@zhaolianghz/dsh-turnscope@0.1.5），适用于 DSH 0.1.6-alpha.1（该插件捆绑的客户端代码使用了 0.1.1-rc.2 中提供的运行时类型，这些类型与 0.1.6-alpha.1 通过 useChat hook 暴露的实际 ChatSnapshot 结构向前兼容）。V0.2（预览优先的安全回退）在同一构建中发布；API_VERSION 为 4（自 0.1.1 起）。0.1.1 / 0.1.2 / 0.1.3 / 0.1.4 / 0.1.5 补丁改进了渲染器行为，但未提升 API_VERSION。分叉重试仍计划在 V0.3 中实现。

更新日志

0.1.5 — 2026-09-17

聊天数据源修复。V0.1 → V0.1.4 的渲染器通过 useSession((s) => s.nodes.filter(...)) 等方式读取聊天节点 / 轮次计时 / 轮次结束，但 DSH 0.1.6-alpha.1 的 SessionSnapshot 不再携带这些字段——聊天构建器的输出位于一个单独的 useChat hook 之后，该 hook 返回 ChatSnapshot（带有 legacy.{nodes, turnTimings, turnEnds}）。渲染器现在从 useChat() 读取（只有 openState 继续来自 useSession）。仅渲染器修复；无 API_VERSION 提升，无宿主变更，无数据库迁移。599 个测试（599 → 599，fixtures 围绕 ChatSnapshot 重建），类型检查通过。

0.1.4 — 2026-09-15

崩溃修复。每当 useSession 选择器收到一个 nodes 字段尚未填充的快照时，0.1.3 的渲染器就会使 DSH 的 conversation.view 槽崩溃——这是该 DSH 构建中正常的首次渲染情况，此时 getSnapshot() 在第一次真实发射之前可能返回 undefined 或一个存根。选择器现在将缺失的 nodes / turnTimings / turnEnds 视为“无数据”并返回空列表；openState 读取器也做同样处理。V0.1.3 的 bootstrap 上下文过滤器保持不变。仅渲染器修复；无 API_VERSION 提升。599 个测试（598 → 599，+1），类型检查通过，客户端 bundle 78.42 kB。

0.1.3 — 2026-09-15 DSH 将一次会话的启动突发——即 harness 在首个用户提示之前注入的指令、目录和召回内容——记录为 context 对话节点。渲染器现在会从轮次活动列表中丢弃这些提示前的上下文事件，因此新会话的第 1 轮和第 2 轮卡片不再显示 Context/Context/Context 行。会话中途的上下文注入（seq ≥ 首个用户/助手 seq）不受影响；尚未收到任何用户消息的会话会保留这些条目，因为没有信号可以区分引导内容与“用户正在撰写其首个提示”。仅渲染器修复；无 API_VERSION 提升。598 项测试（595 → 598，+3），类型检查通过，客户端包 78.21 kB（+0.32）。

0.1.2 — 2026-09-15

详情页的变更列表现在将继承的基线脏路径分组到一个带标签的 本轮开始时已脏 (N) 分隔符下，因此打开详情页查看 agent 本轮做了什么的读者不再需要滚过继承的工作树状态。每行的 本轮开始时已脏 徽章保持不变。仅渲染器修复；无 API_VERSION 提升，无数据库迁移，无工作树写入。595 项测试（593 → 595，+2），类型检查通过。

0.1.1 — 2026-09-15

基线脏状态清晰化。每轮的“已更改文件”计数此前将 agent 的编辑与会话开始时工作树已经变脏的路径相加，因此任何打开时会话工作树不干净的会话都会在每一轮报告同样具有误导性的 76 个文件标题。修复将传输结构拆分为 agentChangeCount + baselineChangeCount（增量式，API_VERSION 4），轮次卡片显示 agent 计数，并在基线数量非零时显示一个弱化的 +N 本轮开始时已脏 标签，详情页头部也如此处理。每个文件的 本轮开始时已脏 徽章保持不变。593 项测试，类型检查通过，客户端包 77.09 kB。

0.1.0 — 2026-09-11

首个发布版本。在一个包中同时发布 V0.1（轮次时间线 + 差异 + 警告）和 V0.2（预览优先的安全回退）——回退功能需要 V0.1 已分配的同一 recovery_before / recovery_after 检查点阶段，而发布真实回退的唯一安全时机，是当工作树状态漂移防护已针对真实 Git 仓库完成端到端验证时。

亮点：

- 原生 conversation.view 集成；轮次时间线具有运行中 / 已完成 / 失败 / 输出限制状态
- 每轮持续时间、工具计数、错误计数、活动列表、命令结果、文件摘要、文件差异
- 针对常见失败模式的确定性安全警告
- 预览 / 应用安全回退：预览会起草一个零工作树写入的计划；应用会通过原子重命名 + 每文件日志提交该计划，并且任何应用中途崩溃都会在下次启动时将文件回滚到应用前的字节
- 漂移防护：如果实时工作树自预览起草以来已发生变化，应用会拒绝（比较真实的 git.blobAt(HEAD) 字节与实时文件，而不仅仅是哈希）
- recovery_before 和 recovery_after 检查点阶段在应用前后捕获；未来的“回退之回退”可以与其中任一进行比对
- 仅本地存储（受管理的根目录，模式 0o600），无遥测，无 git reset --hard，无分支重写
- 英文 + 简体中文文案

为什么

编码代理可以在单轮中触及许多文件并运行许多命令。当某一轮出错时，用户需要明确的答案：

- 代理更改了什么？
- 哪条命令或哪个工具失败了？
- 会话从哪里开始偏离？
- 我能否撤销那一轮而不丢失后续或不相关的工作？
- 我能否在隔离的工作区中从该点重试？

Turnscope 正是围绕这些问题设计的。

现已可用

- 原生 conversation.view 集成
- 实时、最新优先的轮次时间线
- 运行中、已完成、失败和输出限制状态
- 每轮持续时间、工具数量、错误数量和活动列表
- 命令、测试结果和已更改文件摘要
- 每轮文件差异
- 针对常见失败模式的确定性警告
- V0.2 — 预览优先的安全回退：预览按钮起草一份计划，零工作树写入；单独的应用按钮通过原子重命名 + 日志提交该计划，任何应用中途崩溃都会在下次启动时将文件回滚到应用前的字节状态。
- 简体中文和英文文案
- 仅浏览器、只读行为，无遥测

计划中的 MVP

- 在隔离的 Git 工作树和关联的 DSH 会话中进行分叉重试
- 默认仅本地存储，无遥测
- V0.3 — 分叉与重试（在 §10 探索之后；无自动应用，无自动模型运行，无 LLM 作为裁判）。

安全边界

Turnscope 绝不会运行 git reset --hard、重写用户的分支，或静默覆盖自检查点以来已偏离的工作区。当无法证明安全回退时，插件必须拒绝该操作，并提供检查或隔离分叉作为替代方案。

要求

- Node.js 22.19 或更新版本
- pnpm 11.7
- 本地 DSH 0.1.6-alpha.1 安装（插件捆绑的客户端代码使用 0.1.1-rc.2 中附带的运行时类型，这些类型与 0.1.6-alpha.1 通过 useChat 钩子暴露的 ChatSnapshot 形状向前兼容）

开发

corepack enable
pnpm install
pnpm build
pnpm test
pnpm typecheck

构建会生成宿主入口、DSH 的 window.__ModuleLoader__ 所期望的浏览器交接包，以及 lib/ 下的 TypeScript 声明。

在本地 DSH 中加载

首先构建 Turnscope。从本地 DSH 0.1.6-alpha.1 源代码检出中，将其添加为 web 配置文件的开发依赖：

cd /path/to/deepseek-harness
pnpm dsh plugin --profile web add /path/to/dsh-turnscope

启动 DSH Web。pnpm dsh plugin add 已经将插件插入到 web 配置文件的捆绑层中；请不要同时将捆绑的 examples/cordis.patch.yml 传递给 --patch，否则加载器会看到重复的 turnscope id 并拒绝启动。该补丁覆盖层是仅在将 turnscope 链接到没有 bundle 层的 profile 时才需要（罕见；为完整性而记录）：

pnpm dsh --profile web

已在 0.1.6-alpha.1 上验证：首页在启动清单中带有 turnscope 提供服务（/plugins/@zhaolianghz/dsh-turnscope/client.js），并且客户端 bundle 导出了 previewRewind、listTurns、 RecoverySection 以及其他 DTO。

打开一个会话并选择 Turns / 轮次 对话标签页。由于此包尚未发布，因此有意不提供 npm 安装命令。

项目文档

- 产品需求
- 架构
- 实施计划

范围

首个版本面向 DSH Web 中由 Git 支持的编程项目。非 Git 工作区可获得时间线和检查功能，但不提供回退或分叉保证。

中文简介

dsh-turnscope 是一个面向 DSH 编程用户的开发者工具插件。V0.1 在 DSH 0.1.1-rc.2 上提供只读轮次时间线和文件差异；V0.2 增加 preview-first 安全回退（轮次 面板中的 Preview / Apply 按钮）；分叉重试仍在后续计划中。0.1.1 补丁修复了会话启动时工作区已脏导致的"变更文件"误报（详见下方 Changelog）。

首版坚持本地优先、默认无遥测，并且绝不通过重置分支或覆盖 Git 历史来实现回退。

License

MIT