影子快照回滚GooDAnDReaDY/dsh-time-machine

📦 @goodandready/dsh-time-machine

面向 DeepSeek Harness 的影子 Git 自动快照、工作区时间旅行与即时回滚引擎

🇬🇧 English •
🇷🇺 Русский •
🇨🇳 中文说明

⭐ 如果您喜欢这个插件，请在 GitHub 上为它点亮 Star — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。

🐛 如果您发现 Bug 或希望增加功能，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。

⚡ 插件概览

dsh-time-machine 为 DeepSeek Harness 智能体提供全自动工作区安全护栏与即时状态回滚引擎。

智能体在执行多文件批量重构、依赖安装或高危终端命令时，一旦发生代码损坏或逻辑回归，手动 Git 回退不仅繁琐，还容易丢失未跟踪的新建文件。

本插件在后台利用影子 Git 快照技术（Shadow Git Snapshots）自动捕获工作区状态，不污染用户 Git 提交树与分支，支持一键即时回退、可视化文件 Diff 对比以及命令失败时的主动自愈挽救。

graph LR
subgraph AgentAction [智能体执行操作]
Agent[🤖 智能体: 批量修改文件 / 执行终端命令] --> Trigger{执行前置拦截}
end

subgraph TimeMachine [dsh-time-machine 引擎核心]
Trigger --> ShadowGit[影子 Git 快照引擎]
ShadowGit --> Snapshots[(时序检查点历史队列)]
Snapshots --> DiffEngine[可视化工作区 Diff 计算器]
end

subgraph SafetyNet [安全防护与界面集成]
DiffEngine --> Sidebar[🕒 侧边栏 Time Machine 时间轴]
Snapshots --> Rollback[⏪ 一键毫秒级即时回滚]
Rollback --> CleanState[恢复纯净安全状态]
Trigger -.->|命令报错| AutoHeal[🩹 自动弹出回滚修复建议]
end

style AgentAction fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
style TimeMachine fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
style SafetyNet fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4

4. 选择性单文件回滚与暂存区保护 (v0.1.15 新增)
- 单文件恢复：通过 time_machine_file_rollback 工具或差异弹窗 UI 精确恢复单个文件，保留智能体已完成的其他正确成果。
- 暂存区安全守护：用户未提交的 git add 暂存状态（stagedTreeHash）被安全跟踪与保护。
- 高危工具前置快照：在执行高风险命令（bash、execute_command、apply_patch 等）前自动创建检查点。
- 结构化文件差异导航：左侧文件树提供增删行数统计，并支持一键恢复指定文件。

🛠️ 智能体工具列表 (7 个工具)

| 工具名称 | 参数 | 说明 |
|---|---|---|
| time_machine_checkpoint_create | label?: string, sessionId?: string | 在高危修改前创建影子 Git 检查点快照 |
| time_machine_checkpoint_list | sessionId?: string | 按时间倒序列出最近的工作区检查点 |
| time_machine_checkpoint_rollback | id: string, confirm: boolean | 安全还原工作区文件至指定检查点（不移动分支 HEAD） |
| time_machine_diff | from: string, to?: string | 对比当前工作区文件与目标检查点的文件差异 |
| time_machine_checkpoint_delete | id: string, confirm: boolean | 删除指定检查点并同步清理 Git 引用 |
| time_machine_checkpoint_prune | sessionId?: string, keep?: number | 清理会话过期检查点，保留指定数量的最新快照 |

📦 安装指南

dsh plugin --profile web add @goodandready/dsh-time-machine

⚙️ 配置说明 (settings.yaml)

dsh-time-machine:
autoSnapshotEnabled: true    # 文件修改前自动创建快照
maxSnapshots: 20             # 内存保留的最大滚动检查点数量
autoHealPrompt: true         # 终端命令执行失败时提示回滚

📋 版本更新记录 (Release Notes)

v0.1.14 — 界面风格对齐 dsh-clinebot、CSRF 防护与稳定性提升
* Added in v0.1.14: 界面全面对齐 dsh-clinebot 设计令牌规范，通过 --dsw-alias- 变量原生支持深浅色主题，提供主要操作按钮与危险操作按钮，在设置卡片与检查点列表引入状态徽章，升级磨砂半透明 Diff 弹窗。
Security in v0.1.14: 对所有变更型 HTTP 路由（create、delete、rollback、prune）实施 CSRF 防护（isTrustedSettingsRequest）。
* Fixed in v0.1.14: 在插件启动生命周期中自动执行孤儿 Git 索引清理（cleanupOrphanedIndices）；在 legacy 事件总线回退中补充错误快照生成支持（autoHealPrompt）。

v0.1.13 — 移除 settings.section 回退与安全访问 settingsScope
* Changed in v0.1.13: 移除 settings.section 顶级侧边栏设置注册回退，设置严格归属于 settings.plugin.item 折叠卡片，避免挤占全局平面设置列表。
* Fixed in v0.1.13: 使用安全 ctx.get('settingsScope') 访问设置作用域服务，避免 Cordis proxy 属性读取返回 undefined。

v0.1.12 — 修复原生侧边栏引导页中时钟图标过大的问题
* Fixed in v0.1.12: 将图标函数重构为标准 React 组件 TimeMachineIcon，兼容 { size, className } 属性对象与数字传参，增加内联样式限制（width, height, flex: none），彻底解决右侧边栏 Guide 卡片中图标溢出的缺陷。

v0.1.11 — 双侧边栏支持：原生 DSH 右侧边栏与 BetterSidebar
* Added in v0.1.11: 原生支持 DSH 0.1.5-alpha.1 引入的右侧边栏（sidebarRightTabs 注册与 sidebar.right.pane.tab 插槽），包含专属引导页卡片与图标。
* Preserved in v0.1.11: 保持对旧版 betterSidebar 的完全向后兼容；两种表面同时启用时互不干扰，杜绝重复挂载或 ID 冲突。
* Added in v0.1.11: 在两种侧边栏均缺失的环境下，安全降级至插件设置卡片。

v0.1.10 — 稳定性、动态工作目录、统一 Diff 与架构优化
* Added in v0.1.10: 动态工作区感知（cwd）：时光机工具与 REST 接口自动关联当前会话目录或支持显式工作区路径。
* Added in v0.1.10: 统一补丁支持（format: "patch" | "stat"），带输出截断保护（最大 256KB）。
* Added in v0.1.10: Git 变动操作异步排队队列，彻底解决高并发下的 index.lock 竞争冲突。
* Added in v0.1.10: 采用 git for-each-ref 批量查询引用，消除 $O(N)$ 次 git log 进程生成，极大加速快照加载。
* Added in v0.1.10: 空提交去重：若工作树无变化，自动跳过重复快照创建。
* Added in v0.1.10: 启动时自动清理遗留的 tm_index_ 临时暂存索引文件。
Changed in v0.1.10: 精简设置卡片界面，引导在侧边栏时光机标签页查看时间线。
* Changed in v0.1.10: 完善错误告警日志（console.warn），替换静默吞并异常。

v0.1.9 — 事件总线统一与依赖清理
* Changed in v0.1.9: 统一事件总线监听逻辑，杜绝自动快照重复触发。优先使用原生 DSH session/event 总线，仅在缺失 ctx.on 时启用 legacy ctx.events 回退。
* Changed in v0.1.9: 从 peerDependencies 中移除未使用的 @deepseek-ai/dsh-credentials。
* Added in v0.1.9: 新增项目设计规范文档 docs/design/DESIGN.md。

v0.1.7 — 分支历史安全、暂存区隔离与 DSH 原生事件总线
* Changed in v0.1.7: 安全工作区回滚。改用 read-tree + checkout-index + clean -fd，彻底杜绝回滚时误将分支 HEAD 覆盖为孤立提交的严重缺陷。
* Changed in v0.1.7: 保护用户 Git 暂存区。快照操作通过独立的 GIT_INDEX_FILE 执行，不会覆盖 .git/index 中已暂存的文件。
* Changed in v0.1.7: 原生对接 DSH session/event 事件总线，全面激活 turn/start、approval/asked、turn/end 和错误自愈事件监听。
* Changed in v0.1.7: 修复快照淘汰时的 Git 引用泄露问题，自动执行 git update-ref -d。
* Changed in v0.1.7: 修复 Diff 计算，直接对比当前工作区中的未提交修改。
* Changed in v0.1.7: 严格遵循 DSH 插件规范：仅在 ready 状态下允许编辑配置。
* Added in v0.1.7: WebServer API 增加 1MB 请求体大小上限，抵御 DoS 攻击。
* Added in v0.1.7: 前端界面完整支持中文本地化 (zh)。

📄 开源协议

MIT © GooDAnDReaDY