# DSH 工作目录快照分叉

[English](./README.md)

`dsh-workspace-snapshot-fork` 是一个增强 DeepSeek Harness 原生“分叉会话”功能的第三方插件。DSH 原生分叉会复制截至所选历史轮次的会话记录；本插件在此基础上，还会为新会话创建独立工作目录，并还原该分叉点对应的文件状态，而不修改原会话的工作目录。

> **Alpha 版本：**已在 Windows 上完成 DSH Web profile 测试，尚未验证 Linux 和 macOS。

## 工作方式

插件为每个完成的轮次创建不可变的 Git 快照。用户在 DSH 网页端点击历史轮次的分叉按钮时，插件复制会话日志前缀，并在新工作目录中还原该轮次的文件。

| 原工作目录 | 分叉行为 |
| --- | --- |
| 普通目录 | 从私有快照仓库还原到新目录。 |
| 已有提交的 Git 仓库根目录 | 在原仓库中创建新 worktree 和 `dsh/workspace-fork/<id>` 分支，再还原快照文件；原仓库的历史、远程、hooks 和配置保持可用。 |
| Git 仓库内的嵌套目录 | 使用私有快照方式。 |
| 没有初始提交的 Git 仓库 | 使用私有快照方式。 |

分叉点的未提交修改会在 Git 子 worktree 中显示为普通工作区修改。父目录不会被修改。

## 环境与兼容性

- DeepSeek Harness Web profile
- Node.js `^22.19.0` 或 `>=24.0.0`
- `PATH` 中可以执行 Git

| 平台 | 状态 |
| --- | --- |
| Windows | 已支持并测试 |
| Ubuntu/Linux | 尚未验证 |
| macOS | 尚未验证 |

此版本支持 DSH `0.1.1-rc.x` 系列。DeepSeek Harness 仍处于开发者预览阶段，不保证升级后继续兼容。

## 安装

把此版本安装到 `web` profile：

```powershell
dsh plugin --profile web add "github:Yu-Zhuang1/dsh-workspace-snapshot-fork#v0.1.0-alpha.1"
```

从 DSH 源码仓库运行时，在同一条命令前加 `pnpm`：

```powershell
pnpm dsh plugin --profile web add "github:Yu-Zhuang1/dsh-workspace-snapshot-fork#v0.1.0-alpha.1"
```

安装或升级包后重启 DSH。本插件只面向 Web profile；官方 headless profile 没有会话分叉 RPC 和工作区注册服务。

## 配置

插件自带的默认配置是：

```yaml
mode: workspace
storageRoot: <DSH_HOME>/workspace-snapshot-fork/snapshots
childRoot: <DSH_HOME>/workspace-snapshot-fork/workspaces
exclude: [.git, node_modules, .env, .env.*, .DS_Store]
```

`DSH_HOME` 默认是 `~/.dsh`。要覆盖 Web profile 配置，请编辑 `$DSH_HOME/profiles/web/cordis.patch.yml`，加入完整配置：

```yaml
- id: workspace-snapshot-fork
  config:
    mode: workspace
    storageRoot: !!js dshHomePath('workspace-snapshot-fork/snapshots')
    childRoot: !!js dshHomePath('workspace-snapshot-fork/workspaces')
    exclude: [.git, node_modules, .env, .env.*, .DS_Store]
```

DSH 会替换整个 `config`，而不是逐字段合并。因此覆盖配置时必须保留所有字段。

### 原生分叉模式

把完整配置中的 `mode` 改成 `native` 后，新分叉会完全委托给 DSH 原生逻辑，并停止记录新快照；归档清理仍会释放已有快照。DSH 运行时会监视 profile patch，合法配置保存后无需重启即可生效。

改回 `workspace` 后，只有此后完成的轮次会生成快照；`native` 期间的历史轮次不会被补录。

## 安全说明

插件使用独立的快照索引，不会把源仓库的 `.gitignore` 当成安全规则。被源 Git 忽略的文件，只要没有匹配本插件的 `exclude`，仍然会进入快照。

- 请把项目特有的凭据、密钥、隐私文件和大型生成目录加入 `exclude`。
- 从列表中移除 `.env` 或 `.env.*` 可能把凭据写入本地快照。
- 快照是本地 Git 对象，本插件不对其加密。
- `exclude` 是完整替换列表，不会叠加不可见的默认项。

在敏感工作目录中使用前，请阅读 [SECURITY.md](./SECURITY.md)。

## 归档与清理

归档会话时，插件删除该会话的 checkpoint 映射。只有不再被任何未归档会话映射引用时，对应 snapshot ref 才会删除。子会话会继承所选父会话前缀的 checkpoint，因此父会话归档后，子会话仍能从继承的历史轮次继续分叉。

成功创建的子工作目录、Git worktree 和 `dsh/workspace-fork/*` 分支不会自动删除。检查其中的未提交文件后，可以这样清理 Git 子工作区：

```powershell
git -C <原仓库> worktree remove <子工作目录>
git -C <原仓库> branch --delete dsh/workspace-fork/<id>
```

只有明确要丢弃未提交文件时才使用 `--force`。成功创建的普通子目录同样由用户自行管理。

## 卸载

```powershell
dsh plugin --profile web remove dsh-workspace-snapshot-fork
```

从 DSH 源码运行时，在命令前加 `pnpm`。卸载会停止后续快照和工作目录同步分叉，但不会删除已有快照或子工作目录。卸载后还应从 `$DSH_HOME/profiles/web/cordis.patch.yml` 删除插件覆盖项。

## 已知限制

- 只支持 Web profile，没有 headless 分叉适配器。
- DSH 分叉集成与版本相关，升级 DSH 后需要重新验证插件。
- 成功创建的子 worktree 和分支需要手动清理。
- 取消归档不会恢复归档时已清理的 checkpoint。
- 只有在 `mode: workspace` 生效期间完成的轮次才有 checkpoint。

## 开发

本包没有 npm 运行时依赖。测试只调用系统中的 Git，并在临时目录中创建测试文件。

```powershell
npm run check
npm test
npm pack --dry-run
```

## 许可证

[MIT](./LICENSE)