# @goodandready/dsh-time-machine 中文文档

规范地址：https://npmcn.com/package/%40goodandready/dsh-time-machine/

版本：0\.1\.32
npm 元数据更新时间：2026-11-13T21:13:08.243Z
中文译文更新时间：2026-11-16T19:12:23.530Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40goodandready/dsh-time-machine
原文对照：https://npmcn.com/package/%40goodandready/dsh-time-machine/?lang=original
项目主页：https://github.com/GooDAnDReaDY/dsh-time-machine#readme
源码仓库：https://github.com/GooDAnDReaDY/dsh-time-machine

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：164 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-tools ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1，@deepseek-ai/schemastery ^3\.18\.4，@deepseek-ai/dsh-settings ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1，@deepseek-ai/dsh-host-webserver ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1
- 首次发布：2026-08-31T11:53:38.473Z
- 最新版本发布：2026-11-13T21:13:08.043Z
- 近 30 天下载量：6071（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

用于智能检查站、工作空间安全警卫和即时回滚的DSH插件

## 安装

```sh
npm install @goodandready/dsh-time-machine
```

也可以使用：`pnpm add @goodandready/dsh-time-machine`、`yarn add @goodandready/dsh-time-machine`、`bun add @goodandready/dsh-time-machine`

## README

# 📦 @goodandready/dsh-time-machine

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

[![npm version](https://img.shields.io/npm/v/@goodandready/dsh-time-machine.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b)](https://www.npmjs.com/package/@goodandready/dsh-time-machine) [![license](https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b)](https://npmcn.com/package/%40goodandready/dsh-time-machine/LICENSE) [![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065)](https://github.com/topics/dsh-plugin) [![Node version](https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03)](https://nodejs.org/)

[![作者全部项目](https://img.shields.io/badge/%E4%BD%9C%E8%80%85%E5%85%A8%E9%83%A8%E9%A1%B9%E7%9B%AE-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e)](https://goodandready.app/)

[**🇬🇧 English**](https://npmcn.com/package/%40goodandready/dsh-time-machine/README.md) • [**🇷🇺 Русский**](https://npmcn.com/package/%40goodandready/dsh-time-machine/README.ru.md) • [**🇨🇳 中文说明**](https://npmcn.com/package/%40goodandready/dsh-time-machine/README.zh.md)

<table><tbody><tr><td align="center">⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。<br><br>🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。</td></tr></tbody></table>

* * *

## ⚡ 插件概览

**`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:<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](https://github.com/GooDAnDReaDY)

## 常见问题

### @goodandready/dsh-time-machine 是什么？

用于智能检查站、工作空间安全警卫和即时回滚的DSH插件

### 如何安装 @goodandready/dsh-time-machine？

在项目目录运行 npm install @goodandready/dsh-time-machine，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）、@deepseek-ai/dsh-tools（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1）、@deepseek-ai/schemastery（^3\.18\.4）、@deepseek-ai/dsh-settings（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1）、@deepseek-ai/dsh-host-webserver（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @goodandready/dsh-time-machine 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/goodandready\_\_dsh-time-machine 是否存在。

### @goodandready/dsh-time-machine 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @goodandready/dsh-time-machine 可以商用吗？

@goodandready/dsh-time-machine 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @goodandready/dsh-time-machine 的下载量有多少？

根据 npm 官方下载统计，@goodandready/dsh-time-machine 在 2026/10/17 – 2026/11/15 这 30 天内被下载 6,071 次，日均约 202 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @goodandready/dsh-time-machine 还在维护吗？

最新版本 0\.1\.32 发布于 2026/11/14（2 天前）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/08/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

