---
## ⚡ 插件概览
**`dsh-time-machine`** 为 **DeepSeek Harness** 智能体提供全自动工作区安全护栏与即时状态回滚引擎。
智能体在执行多文件批量重构、依赖安装或高危终端命令时，一旦发生代码损坏或逻辑回归，手动 Git 回退不仅繁琐，还容易丢失未跟踪的新建文件。
本插件在后台利用**影子 Git 快照技术（Shadow Git Snapshots）**自动捕获工作区状态，不污染用户 Git 提交树与分支，支持**一键即时回退、可视化文件 Diff 对比以及命令失败时的主动自愈挽救**。
```mermaid
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` | 清理会话过期检查点，保留指定数量的最新快照 |
---
## 📦 安装指南
```bash
dsh plugin --profile web add @goodandready/dsh-time-machine
```
---
## ⚙️ 配置说明 (`settings.yaml`)
```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:
