@goodandready/dsh-time-machine

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

📦 @goodandready/dsh-time-machine

<div align="center">

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

<p align="center">

<a href="https://www.npmjs.com/package/@goodandready/dsh-time-machine"><img src="https://img.shields.io/npm/v/@goodandready/dsh-time-machine.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>

<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>

<a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>

<a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>

</p>

<!-- 作者所有开源项目目录按钮 -->

<p align="center">

<a href="https://goodandready.app/"><img src="https://img.shields.io/badge/作者全部项目-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="作者全部项目"></a>

</p>

<p align="center">

<a href="README.md"><b>🇬🇧 English</b></a> •

<a href="README.ru.md"><b>🇷🇺 Русский</b></a> •

<a href="README.zh.md"><b>🇨🇳 中文说明</b></a>

</p>

<table align="center">

<tr>

<td align="center">

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

<br><br>

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

</td>

</tr>

</table>

</div>

---

⚡ 插件概览

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.16 — API 安全强化与侧边栏标签防重注册

• Security (Gitea #38): 将 isTrustedSettingsRequest 升级为严格的 fail-closed 判定模式（校验本地回环 IP 127.0.0.1/::1、sec-fetch-site 严格限制为 same-origin 或 none、校验 origin 与 host 匹配及 Bearer/Cookie 令牌）。对所有变动型接口（/create、/delete、/prune、/rollback、/rollback-file）强制要求 POST 请求（非法方法返回 405 Method Not Allowed），对只读接口（/snapshots、/diff）强制要求 GET。
• Fixed (GitHub #2): 修复在 DSH >= 0.1.6-alpha.1 环境下，原生右侧边栏 sidebarRightTabs 与 betterSidebar 同时存在时抛出 tab kind "time-machine" is already registered 崩溃异常的问题；采用共享防重守卫优先注册原生侧边栏，并安全抑制重复注册错误。

v0.1.15 — 单文件选择性回滚、暂存区隔离与富文本 Diff 弹窗

• Added in v0.1.15: 支持单文件选择性回滚（time_machine_file_rollback 工具与 /rollback-file 接口），无需重置整个工作区即可精准恢复单个目标文件。
• Added in v0.1.15: 通过 stagedTreeHash 实现用户暂存区隔离，创建与回滚快照时不干扰 .git/index 中已暂存的内容。
• Added in v0.1.15: Diff 弹窗增加交互式文件列表，支持单文件变更统计与补丁分屏预览。
• Added in v0.1.15: 在高危工具执行前自动触发前置快照（auto:pre-tool:<tool>）。
• Changed in v0.1.15: 严格遵循 DSH 本地化标准（纯净 en/zh 客户端包，俄语本地化转入 goodandready/dsh-russian-lang 集中管理）。

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: 保持对旧版 `better

…(truncated)