GooDAnDReaDY/dsh-time-machine

---

⚡ 插件概览

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