wloops/dsh-git-worktree

安装

### 1. 创建隔离 Session

在 blank/new Local Session 中打开 **Worktree** 开关并确认。确认之前不会创建 Worktree；确认后，未发送的文字和图片草稿会迁移到新的隔离 Session。

已有 Local Session 也可以由模型调用 `worktree_create` 创建目标 Session。源 Session 始终保持 Local，不会被偷偷切换到另一个 cwd。

### 2. Agent 在 Worktree 中工作

Agent 只在隔离 cwd 中读取、修改和验证项目。该 cwd 对应真实 Git Worktree，同时注册为 Harness Workspace，因此 Harness 的 Workspace 和 Session 边界仍然有效。

### 3. 准备验收

实现和验证完成后，Agent 调用 `worktree_ready_for_review`，提交：

- 变更摘要；
- changed files；
- 验证状态与测试命令；
- 建议 Commit Message。

该操作只保存验收报告，不写入 Local，也不创建 Commit。

### 4. 用户决定如何交付

用户可以选择：

- **同步到 Local 验收**：创建一个未提交、可撤回的 Preview；
- **验收通过并提交**：只提交本次任务增量；
- **撤回并继续修改**：移除 Preview，返回原 Worktree；
- **跳过验收直接提交**：显式确认后走受保护的直接交付路径；
- **放弃任务**：在满足安全条件后清理任务环境。

### 5. 在原对话开始下一轮

成功提交并 cleanup 后，本轮 Worktree cwd 会被删除，但 Session 和对话仍然保留。用户提出新的代码或文件修改时，插件可以基于最新 Local HEAD，安全重建该 Session 的 immutable cwd，并进入下一轮 iteration。

Retained、cleanup-pending 或 recovery 状态不会被静默清理，必须先完成对应的人工处理。

## 界面预览

以下截图按一次完整任务的实际顺序展示主要交付流程。

### 创建 Worktree Session

在新的 Local Session 中启用 Worktree 后，Harness 会先说明会话切换边界；只有用户确认后才会创建并切换到隔离 Session。

![确认创建并切换到 Worktree Session](docs/screenshots/01-create-worktree.png)

### 准备验收

Agent 完成实现和验证后生成 Ready for Review，用户可以查看变更摘要与验证结果，再决定是否同步到 Local。

![Worktree 修改已准备验收](docs/screenshots/02-ready-for-review.png)

### 在 Local Preview 中验收

同步后，本次任务增量会以可撤回的 Local Preview 等待验收；用户可以提交、撤回后继续修改，或放弃任务。

![任务修改正在 Local Preview 中等待验收](docs/screenshots/03-local-preview.png)

### 确认提交与环境保留

默认路径会确认 Commit Message 并在提交后清理 Worktree；需要继续排查时，也可以按所选时长暂时保留冻结的运行环境。

| 提交并清理 | 提交并保留运行环境 |
| --- | --- |
| ![确认提交任务增量并清理 Worktree](docs/screenshots/04-commit-confirmation.png) | ![确认提交任务增量并保留运行环境](docs/screenshots/06-retain-environment.png) |

### 在同一 Session 开始下一轮

交付与 cleanup 成功后，原对话会保留，并可以基于最新 Local HEAD 开始下一轮修改。

![本轮已交付并可以开始下一轮修改](docs/screenshots/05-next-iteration.png)

## 术语说明

文档保留部分英文术语，以便与 Harness 界面、工具名和错误码对应；首次阅读时可以按下表理解：

| 术语 | 中文注解 | 在本项目中的含义 |
| --- | --- | --- |
| Session Target | 会话执行目标 | 当前 Session 被固定到的实际工作位置与执行边界，可以是 Local 或 Isolated Worktree |
| Isolated Worktree / checkout | 隔离 Worktree / checkout | Agent 独立施工的 Git 工作副本，不直接修改用户的 Local checkout |
| Review / Ready for Review | 验收稿 / 等待验收 | Agent 完成当前阶段后提交的摘要、文件、验证结果和建议 Commit Message |
| Local Preview | Local 预览 | 将任务增量临时同步到 Local 查看，但暂不创建 Commit |
| Rollback / Finalize | 撤回预览 / 确认提交 | 分别表示安全移除本次 Preview，或将验收通过的任务增量提交到 Local |
| acceptance slot | 验收槽位 | 同一 Local 项目唯一的 Preview 写入名额，用于避免多个任务同时写入 Local |
| cleanup / retention | 清理 / 保留运行环境 | 交付后立即删除 Worktree，或按用户选择暂时保留冻结环境 |
| iteration | 任务轮次 | 同一 Session 中一次完整的创建、修改、验收与交付周期 |
| fail closed / recovery | 保守拒绝 / 恢复处理 | 无法证明安全时停止写入并保留证据，而不是自动猜测或覆盖 |

## 设计基础与 Harness 适配

本项目的 Worktree 生命周期与 Git 交付引擎基于一套经过实际使用验证的桌面端实现重新适配。重点不是复制原有界面，而是保留已经验证过的安全不变量：

- managed checkout registry 与 revision CAS；
- canonical path、Git common-dir 和 git-dir 身份校验；
- staged、unstaged、untracked、binary 和 deletion 状态的完整 fingerprint；
- receipt-first Local Preview、Rollback 与 Finalize；
- 只提交任务增量，同时保留 Local 其他修改；
- internal refs、journal recovery、retention、quarantine 和保守 cleanup；
- 无法证明安全时 fail closed，而不是猜测后继续写入。

DeepSeek Harness 与原桌面端宿主模型不同，因此本插件对产品和权限边界做了重新适配：

- Harness 的 Workspace 与 Session cwd 是权威身份，插件 registry 只作为辅助状态；
- Host 能力通过 strict Typert Remote 暴露，浏览器 UI 使用 Harness 的公开 Client Slots；
- Local source Session 与 Isolated target Session 始终分离；
- cleanup 后不修改 Harness 已持久化的 Session cwd，而是在下一轮严格校验后重建同一路径；
- 模型只负责创建、恢复编辑和准备验收，最终写入 Local、提交与清理由用户入口控制。

详细的身份、状态与恢复边界见 [Session Target 迁移说明](docs/PORTING.md)。

## 环境要求

- Node.js 20 或更高版本；
- DeepSeek Harness `0.1.0-rc.6` 包线；
- Harness Web Client，用于完整的 Worktree 创建和验收界面；
- 当前 Workspace 是 Git 仓库。

## 安装

推荐直接安装 npm 包：

把 wloops/dsh-git-worktree 加入你的 DSH 配置（web profile）即可启用。