dsh-checkpoint-diff

English version: README.en.md

把 dsh-checkpoint-rewind 的检查点（快照）当作时间节点，提供任意两个节点之间的文件差异可视化：会话头部 "Diff" 按钮打开浮层面板（时间线 → 文件清单 A/M/D → 逐行 diff），另有 /diff 命令与 JSON HTTP API 供 headless 使用。

只读设计，唯一显式例外是回滚：可从任意时间节点把工作区文件恢复回来（整节点或单文件），经面板、/rollback 命令或 API 触发。回滚只覆盖写、绝不删除（节点之后新建的文件保留并报告）、绝不碰 .git/.dsh、绝不写快照存储/git/会话。"绝不删除"的唯一例外是回滚的单次撤销（/rollback --undo、面板按钮）：只删除恢复操作自己刚创建的文件，其余一律不动（进程内记忆，重启即失效）。

[!IMPORTANT] 先装上游，再装本插件。 本插件是只读消费端——检查点（快照）由上游 dsh-checkpoint-rewind（快照生产者）产生，本插件自身不产生快照。只装 dsh-checkpoint-diff 而漏掉上游，检查点时间线是空的：Diff 按钮、/diff、回滚都没有数据（只有 Trace (session log) 范围可用）。安装见安装。

理念：它解决什么问题，为什么是它

场景。 AI 代理在替你写代码、改文件。它的"思考"是黑盒，但它的行动会落到你的工作区：它改了什么？什么时候改的？改坏了怎么办？——这些问题不能没有答案。

立场。 这类工具通常有两条路：一是替你省事——自动总结、自动判断、替你过滤信息；二是让你安心——把真相原样交给你，保证你随时能查清、能追究、能退回去。本插件明确选择第二条路：不做"替你看"的总结与过滤，而是把看清楚和退回去的能力完整交到你手里。

• 你不必看，但你必须能看。 日常开发可以完全无视它；但任何时候想查，每次变更动作都对应一个高粒度的快照时间节点，任意两个节点之间改了什么、怎么改的，逐文件、逐行可见；
• 出问题能追究到底。 哪一步、哪个工具、动了哪些文件，都能精确还原；确认误伤后，还能从任意时间节点把工作区恢复回来（只覆盖写、绝不删除、可撤销）；
• 安全感不来自"不出错"，而来自"查得到、退得回"。

一句话：你可以不看，但它不能不可查。 人可以不看不追究，但绝不能没有看和追究的手段——这就是本插件存在的理由。

演示

GUI 面板

全部为真实截图（运行在真实 harness 会话上）。面板全貌——scope 切换、from/to 时间节点下拉（意图标签 + (HEAD) 前缀）、目录树文件清单（A/M/D）、逐行 diff（红删绿增 + ↑/↓ 变更块跳转）、Restore workspace 恢复卡片：

Trace (session log) 范围——会话日志重放 + 三泳道拖选时间线（Input / Model / Tools span、turn 边界；拖选区间自动映射为 from/to 边界节点）：

本会话 范围——当前会话的检查点时间线,选择要回滚的版本，点击“Preview Restore”预览效果：

本项目 范围——跨会话合并 + fork 血缘分支下拉：

UI 每次大改后必须重新截图并更新本文（采集规则见 docs/screenshots/README.md）。

命令行形态（真实输出格式）

/diff 列出本会话时间线——rewind 在每次变更工具执行前自动留下快照时间节点（格式与真实输出一致，数据为示意）：

diff: 3 checkpoint(s) for this session
  #a1b2c3d4  20m ago  turn 2 step 1  copy  3 file(s)  18 KiB  edit lib/engine.mjs
  #b2c3d4e5  10m ago  turn 3 step 1  copy  2 file(s)  12 KiB  edit README.md
  #c3d4e5f6   5m ago  turn 3 step 2  copy  4 file(s)  25 KiB  bash pnpm test
usage: /diff <from> <to>  (id prefix or "latest" for either side)

/diff <from> <to> 任意两节点：变更文件摘要 + 逐行 diff（GUI 面板中同屏显示红删绿增）：

diff: #b2c3d4e5 (14:02 · edit README.md) → #c3d4e5f6 (14:07 · bash pnpm test)
  4 file(s) changed: +1 added, 2 modified, 1 deleted
  M  lib/engine.mjs
    - function lcs(a, b) {
    + function lcs(a, b, opts) {
  M  README.md
    - 只读设计，唯一例外是回滚
    + 只读设计，唯一显式例外是回滚
  A  test/engine.test.mjs
  D  lib/legacy.mjs

速览（At a glance）

• 是什么：DeepSeek Harness 插件——把 dsh-checkpoint-rewind 的快照变成可浏览时间线，任意两个时间节点之间逐文件、逐行 diff（GUI 面板 / /diff / HTTP API），并提供预览式回滚（只覆盖写、绝不删除、可撤销）。
• 先决条件：必须先安装上游插件 dsh-checkpoint-rewind（快照生产者）——本插件只读消费它产生的检查点/快照，不产生快照；未装上游时检查点时间线为空，只有 Trace (session log) 范围可用。详见安装。
• 解决什么：AI 代理自主修改工作区之后——它改了什么、何时改的、出问题时如何追究与恢复。
• 面向谁：使用 DeepSeek Harness 并安装了 dsh-checkpoint-rewind 的开发者。
• 兼容：DSH 0.1.0-rc.5 / rc.6 · rewind 0.4.0（域 v1）/ 0.5.0（域 v2）双兼容 · Node ^22.19 || >=24 · Apache-2.0。
• 入口：会话头部 Diff 按钮 · /diff · /rollback · /checkpoint-diff/api。

特性

…