dsh-checkpoint-diff

dsh plugin --profile web add dsh-checkpoint-diff

dsh-checkpoint-diff

English version: [README.en.md](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](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。

特性

• 时间线 — 每个检查点都是一个可选时间节点（#短id、时间、turn/step、provider、触发工具；/rewind 守护检查点带标记）。
• 跨会话 / 同项目时间线 — 切到 本项目 合并共享同一工作区键的全部会话检查点，按 /rewind fork 血缘组织：分支下拉（根 + 旁支，会话标题）、会话标签、fork / 根缺失标记；可选 dsh-session-query 服务缺席时退化为扁平合并。
• 意图标签（紧凑） — 节点按会话日志命名：(turn, step) 的 tool/call 事件解析出 edit README.md、bash pnpm test 之类的标签（GUI、/diff 输出、JSON API 一致）；文件目标相对化到工作区（超长退化为文件名）、命令简写为"命令名 + 首参"、str_replace_editor 显示为 edit、只读工具带 Ⓡ 标注；日志缺失回退原始触发工具。trace 时间线的 tooltip 还会附上该工具前一条 assistant 消息的说明文本（引号标注，批量工具共享）。
• 文件摘要 — 两节点间的变更文件清单，带 A（新增）/ M（修改）/ D（删除）徽标。
• 目录树视图 — 变更清单以可折叠目录树呈现，目录行带 A/M/D 计数；点文件看逐行 diff。
• 逐行 diff — 自包含 LCS 引擎（copy 快照无需 git），ctx/del/add 行带对齐行号。
• 双快照 provider — git（未引用 stash/commit-tree 对象，经 git diff-tree/git show 只读访问）与 copy（快照目录 + manifest），按记录分发；混合 provider 配对拒绝（响亮报错）。
• 回滚 — 从任意时间节点恢复工作区（整节点或单文件）：先预览再应用；只覆盖写——节点之后新建的文件保留并报告，绝不删除；路径校验（禁穿越、禁绝对路径、不碰 .git/.dsh）；git provider 只用只读原语，并要求会话 cwd 即仓库根。
• 恢复预览 diff — 预览恢复时点计划中的任意文件，diff 区显示当前工作区 → 目标快照逐行差异（"current → #target"），应用前看清将要改什么。
• 单次撤销 — 应用恢复后一次 ↩ Undo this restore（面板按钮、/rollback --undo、POST /api/rollback-undo）即可回退：被覆盖文件回到恢复前内容、恢复新建的文件被移除（"绝不删除"的唯一例外）；仅进程内、无 redo；恢复后被改动的文件跳过不动。
• diff 视图细节 — ↑/↓ 按变更块跳转（连续新增行合成一块，相邻红区+绿区合成一块，纯删除也是一块；跳转对齐块中心行；最后一个块 ↓ 先提示、再点才回绕，↑ 对称）；打开文件自动定位到第一个变更块；diff 区下方 "Last view" 跳回上次查看的节点对（localStorage 持久）。
• 位置标签 — 最新节点带大写 (HEAD) 前缀（如 (HEAD) #bbbbbbbb 20:26 · edit b.txt）。HEAD 恒指当前快照（全局最新节点）：选择版本、切换分支过滤都不会移动它，刷新时间线后自动移到新快照。
• 独立恢复卡片 — 回滚区是工具栏下方独立的可折叠 "Restore workspace" 卡片，与节点对比区视觉分离；恢复预览（"Restore preview: current workspace → …"）与 from/to 对比互相独立：选择其它版本不清空预览，改恢复目标则按新目标重载。
• 优雅降级 — 被 git gc 回收（或重克隆丢失）的 git 检查点标 ⚠ degraded，默认选择自动跳过；时间线显示 "N checkpoint(s) degraded" 提示条；diff/回滚报错精确点名死节点。绝不删除任何记录；剪枝记录、缺失记录/文件保持现有明确报错。
• 轨迹重放（可脱离 rewind 独立工作） — 面板 scope 切到 Trace (session log) 或 /diff --trace：把会话日志（session.jsonl.zstd）里的每个工具调用当作时间节点（trace:<seq>），选中任意两节点即"选中区间"——由 write/edit/str_replace_editor 参数重放内容，逐文件逐行 diff（复用同一 LCS 引擎与面板）。无需任何快照生产者：rewind 缺席、快照被配额逐出或被 gc 回收、甚至装插件之前的历史会话，都能回答"这次对话改了哪些文件

…(truncated)