dsh-git-worktree

dsh-git-worktree

让 Agent 在独立 Git Worktree 中完成任务，你看过修改后再决定是否保存。

dsh-git-worktree 是 DeepSeek Harness 的 Git Worktree 插件。它会为每个编码任务创建独立的 Worktree（工作目录），Agent 不会直接改动你正在使用的项目。任务完成后，你可以先预览结果，再选择保存、退回修改或放弃。

这套 Git Worktree 工作方式最初来自基于 Pi Agent Runtime 的开源桌面 coding 工作台 Domi，本插件是针对 DeepSeek Harness 独立适配的版本，可以单独安装和使用。

English · 完整使用指南 · 架构说明

为什么使用它？

让 Agent 直接修改当前项目时，它的改动可能与你尚未提交的内容混在一起；同时运行多个任务时，也更容易互相影响。使用本插件后：

• 每个任务都在自己的 Git Worktree（独立工作目录）中修改和测试；
• 多个任务可以同时进行，不会共用同一个工作目录；
• Agent 完成后，你可以先把修改临时显示在当前项目中查看；
• 只有确认后才会保存本轮修改，遇到冲突时不会自动覆盖你的内容。

核心能力

• Git Worktree 隔离：每个任务都有独立的工作目录和 Agent 对话。
• 多个 Worktree 并行：可以同时开发多个任务；为了避免混入修改，同一项目每次只验收一个任务。
• 提交前预览：先在当前项目中查看真实效果，不会立即创建 Git 提交。
• 不满意可以退回：撤回本次预览，继续让 Agent 修改，不影响其他本地改动。
• 只保存本轮任务：确认后只提交这个任务的修改，不把无关内容一起带入。
• 长任务可分阶段：先保存当前阶段的进度，再继续开发；最终仍合并为一次交付。
• 出错时保护现场：检测到分支变化、内容冲突或中断时停止操作，保留现场供你处理。
• 集中查看任务：同一项目的当前及历史 Worktree 会按 Host 导航归属聚合到侧边栏，归属不明确时保守保留原位置。
• 验收详情集中查看：从验收条打开只读详情，查看文件列表、验证记录与版本信息，不必翻找聊天工具记录。
• 空仓库安全起步：无提交仓库可在明确确认后创建不包含用户文件的空首次提交，再建立隔离 Worktree。
• 携带项目 Skills：首次及下一轮 Worktree 创建时一次性携带 .dsh/skills、.agents/skills 和 .claude/skills，辅助文件与 Git 交付隔离。
• 原对话继续下一轮：任务交付后，无需新开对话即可继续下一项修改。

当前版本管理单个项目中的 Git Worktree，暂不提供跨项目的全局管理界面。

工作流

flowchart LR
    A[当前项目] -->|创建隔离任务| B[独立 Git Worktree]
    B --> C[Agent 修改并测试]
    C --> D[查看验收结果]
    D -->|预览修改| E[在当前项目中查看效果]
    E -->|确认并保存| F[创建本轮提交]
    F --> G[在原对话继续下一轮]

    D -.->|保存阶段进度| H[继续开发]
    E -.->|撤回本次预览| I[返回修改]
    D -.->|跳过预览| F

怎么选？

目标	操作
先在当前项目中查看效果	预览修改
预览结果没有问题	确认并保存
任务很长，先固定当前进度	保存阶段并继续
还要让 Agent 改代码	继续修改或撤回本次预览
不需要先查看效果	跳过预览并保存

详细的操作、恢复场景和命令见完整使用指南。

快速开始

环境要求

• Node.js ^22.19.0 || >=24.0.0
• 当前 Unreleased 源码基线为 DSH 0.2.1-rc.2（插件版本暂留 0.10.1，尚未发布）：新鲜隔离验证的类型、构建、sidebar/发布门禁及 43 个测试文件通过（607 passed / 1 skipped），包含 Provider 禁用/失败恢复修复；仅为源码兼容验证，不是浏览器、AI、桌面或 Windows 全流程验收。见验证报告。
• 已发布历史组合（不因本轮撤销）：插件按 Host 版本分线——0.10.0 面向 DSH 0.2.0-rc.2（peers 精确锁定；已通过隔离源码 Host 的安装、启动、Worktree 开关与预会话创建真实验证，AI 对话与交付全流程仍待验收）；DSH 0.1.x 请使用 0.9.x 插件线。详见兼容矩阵与限制。
• Harness Web Client
• Git Workspace

从旧 Harness 升级时请先处理 Host 数据迁移：0.1.2-rc.1 已移除可选 SQLite Session 后端，旧数据需使用旧版 Harness 导出；Code Mode 已更名为 PTC mode，但现有会话记录仍可读取。应用和本插件统一通过 dsh Profile 启动与安装。

从旧版 Harness 升级后，如果 Web 界面提示 Failed to load plugins，先确认插件线与 Host 版本匹配：DSH 0.2.0-rc.2 使用 0.10.0，DSH 0.1.x 参考 0.9.x 历史记录；当前 0.2.1-rc.2 适配仍为未发布源码；再按兼容矩阵排查并重启 Harness。历史版本 0.7.2 及更早依赖已停止发布的 dsh-client-runtime；0.7.3 在 rc.1 Web Client 中还可能形成 conversation / uiWorkspace 循环等待。

dsh plugin --profile web add dsh-git-worktree@0.10.0

安装

dsh plugin --profile web add dsh-git-worktree

也可以安装指定版本：

dsh plugin --profile web add github:wloops/dsh-git-worktree#v0.10.0

刚发布的新版本可能被 Harness 的供应链防护（minimumReleaseAge）暂时跳过而回退旧版，安装时报「与当前 DSH 不兼容」；此时请显式指定精确版本（如 dsh plugin --profile web add dsh-git-worktree@0.10.0），或待防护窗口过后重试。

安装后打开 Git Workspace，在新建 Session 时启用 Worktree；已有 Local Session 也可以让模型调用 worktree_create 创建隔离 Session。

第一次使用建议先完成一次“创建 → 预览修改 → 确认并保存 → cleanup”的完整流程。

如果 Git 源安装被 pnpm build approval 阻止，或需要查看完整命令和排错步骤，请阅读安装与使用指南。

界面预览

项目聚合与任务状态

准备验收

完整操作步骤见完整使用指南。

安全边界

每次把任务修改写回当前项目之前，插件都会重新确认任务版本、项目位置和文件状态仍与验收时一致。如果你切换了分支、修改发生冲突，或上一次操作意外中断，插件会停止写入并保留现场，而不是猜测后继续覆盖。

Worktree 隔离主要用于避免任务之间误改文件，不是用来运行不受信任代码的系统沙箱。

更详细的状态检查与恢复规则见：

• Worktree Console 架构
• Session Target 迁移说明

当前限制

• 只有归属关系明确的任务才会聚合到原项目；无法确认时仍保留原位置，避免任务被隐藏。
• 隔离任务可以重命名和归档，暂不支持从任务对话直接复制出新任务（Fork）。
• 子 Agent 与父任务使用同一个工作目录，不会再为每个子 Agent 创建新的 Worktree。
• 已保存的阶段记录暂不支持编辑、删除、调整顺序或回退到任意阶段。
• Domi 中更完整的跨项目管理、直接修复当前项目、依赖复用和协作交接能力不在本插件当前范围内。

本地开发

pnpm install
pnpm run typecheck
pnpm test
pnpm run build
pnpm run check:publish

端到端启动：

pnpm run dev:dsh

更多开发命令见完整使用指南，发布前检查见发布清单。

文档

• 完整使用指南
• Worktree Console 架构
• Session Target 迁移说明
• UI 开发说明
• 发布清单
• 变更记录

许可证

MIT

界面语言

插件跟随 DSH 的中英文选择，不提供独立语言开关。请在 DSH 中明确选择 English，以便界面、工具和 /worktree 消息都使用英文；自动浏览器语言尚未写入 DSH 偏好时，工具和命令会回退中文。详见 语言传递与文案贡献说明。