前言¶

在 DeepSeek Harness（DSH）里做代码相关会话时，常见需求是：在不动当前工作目录的前提下开一条隔离分支，并在界面里看清「这个会话实际落在哪、相对 Git 有哪些改动」。有的工作流会把 worktree 管理做成独立页面或常驻目录栏，占用侧栏空间。维护者 zxbingoo 的 dsh-minimalist-worktree 走另一条路：参考 Paseo 的交互思路做轻量 worktree 选择，把目录信息放进会话列表悬浮卡片，在会话内提供只读文件树与 unified Diff，不新增独立工作树管理页。插件归类为客户端，在 SkillHub 插件目录 可查；源码与说明见 GitHub（MIT 许可证）。SkillHub 页显示星标为 0，不代表功能完整性，仅以公开资料为准。

这是什么¶

dsh-minimalist-worktree 是 DSH 的客户端插件：在新会话里可选「本地」或「新建 worktree」及起始分支；列表悬停可查看分支名与完整目录；会话内可浏览工作区文件（含部分格式预览）并查看 Git 变更与只读 Diff。它不替代 DSH 自带的归档与停止机制，在归档时按约定清理本插件创建的外部 worktree，并支持 worktree 丢失时的受控恢复与可选的 Codex 风格环境初始化。

宿主要求（package.json）：engines.dsh 为 >=0.2.1-rc.5 <0.3.0-0；README 写明当前开发/回归侧重 DSH 0.2.2-rc.1，更换已安装插件后需重启 DSH 才能确保加载新构建的 client.js。

核心功能¶

新会话：本地 / 新建 worktree¶

两个紧凑选择器仅在：会话尚未发送消息且工作区为 Git 仓库时显示。非 Git 工作区默认「本地」并隐藏选择器；检测完成前不闪现。权限或 Git 读取错误不会被误判为「非 Git」或「没有变更」。

典型步骤（摘自 README）：

1. 在新会话选择 Git 工作目录。
2. 默认「本地」：沿用当前目录，不切换源仓库分支。
3. 选「新建 worktree」并选起始分支，等待选择保存完成后再发消息。
4. 宿主在首个模型步骤之前创建独立分支与检出目录，并把本会话切过去。

新分支名采用 dsh/<形容词>-<名词>（内置英文词表随机组合，例如 dsh/ripe-bird）。目录位于 ~/.dsh/worktrees/<项目名>-<规范仓库路径 SHA256 前 8 位>/...，不再嵌套在源项目 .agents 下。已有 worktree 不搬迁、不删除；创建失败会中止模型步骤，可能留下检出目录或分支，需自行检查后处理。

工作目录改变后需重新选择；已开始或派生的会话不能补选，以免改变正在执行的任务。

会话列表：悬浮卡片中的目录与分支¶

会话条目沿用 DSH 原生悬浮卡片：悬停显示当前分支与当前目录（跟被悬停的会话，而非当前打开会话）。无常驻图标、无点击复制；浮层打开时才查询，关闭后释放订阅。非 Git、读取失败或无法实时查询的历史会话会明确提示，不编造分支。

右侧：文件树与 Git 变更（只读）¶

自 0.5.0 起，原「工作区文件」类面板升级为左侧文件/变更导航、右侧当前文件或行内 Diff（自动换行、收起目录、复用 DSH 全屏与主题变量）。文件树以 Session 的 workingDirectory 为根，按层展开（每目录 500 条）；点文件可只读预览 UTF-8 文本（512 KiB / 10000 行上限）。0.5.5 起支持 Markdown 等有界渲染、JSON 格式化、CSV/TSV 表格及常见图像预览；Office/PDF 等暂不嵌入。无暂存、提交、撤销、推送等写操作。

Git 变更以仓库根为比较基准，支持未提交 / 未暂存 / 已暂存等范围，并可处理根仓与已登记子模块分组（子模块未初始化不自动拉取）。共享源目录会包含其他工具的改动，不局限于当前 AI。单次 Git 相关操作有 10 秒预算；列表与 patch 大小有明确上限，超限不伪装完整结果。

变更视图可在桌面分栏、窄屏上下布局；会话 cwd 在子目录时仍可看仓库级 Diff，但超出 cwd 的文件不提供「打开文件」，防止目录越界。

工作树丢失、归档清理与初始化¶

工作树丢失与回源（0.4.2）：在模型 pre-step 前后核验已创建 worktree 的目录与分支；异常时在输入框上方显示恢复选项（非常驻）。可选「重建隔离工作树」或「使用源目录」，均需用户确认；失败 fail-closed，不提供模型可调用的 mutating recovery 工具。

Paseo 风格归档清理（0.4.1）：仅处理更新后的新归档，核验归属后对外部 worktree 执行 git worktree remove --force；不创建新快照，未提交与未跟踪文件会被删除，归档前需自行提交要保留的内容。清理失败不影响归档本身。

Codex 本地环境初始化：在新检出目录读取 .codex/environments/environment.toml，仅支持已核实的 version = 1 且 [setup].script 非空时，在首个模型步骤前执行一次（最长 10 分钟，受会话沙箱约束）。不执行 [[actions]]；Windows 上会暂停并提示不支持。首条用户消息后可展示创建工作树 / 运行初始化的轻量进度与日志（脱敏展示，不保证识别所有自定义密钥）。

安装与启用¶

安装通过 DSH Plugin Manager 完成目录 bundle 安装，README 不要求改用户配置文件。将 target 换成本地 clone 或解压后的绝对路径：

{ "action": "install_bundle", "target": "/absolute/path/to/dsh-minimalist-worktree" }

本地开发（README）：Node 24+，执行：

pnpm install --ignore-scripts
node build.mjs
node --test test/*.test.mjs

修改 src/client.js、src/changes-client.js 或语言资源后需重新 node build.mjs。client.js 为生成产物。

插件以当前 DSH 进程权限运行，会通过会话挂载的文件系统、子进程与沙箱创建外部 worktree 并执行只读 Git 查询；安装或使用前请自行查看源码与 MIT 许可证，确认与团队安全策略一致。

典型用法小结¶

1. 打开 Git 仓库下的新会话，确认选择器出现。
2. 需要隔离时选「新建 worktree」+ 起始分支，保存后发送首条消息，等待 worktree 创建（及可选 setup）进度结束。
3. 在会话内打开文件/变更面板，按范围查看 Diff；列表悬停核对分支与目录。
4. 任务结束按 DSH 流程归档；知晓归档可能删除未提交的 worktree 内文件。
5. 若目录丢失，按界面恢复流程二次确认，成功后需重新发送原消息（不自动重发）。

适用场景与注意¶

适合：希望在 DSH 里用 Git worktree 做会话级隔离、又不需要单独 worktree 管理页的开发者；需要在同一会话内只读浏览变更、配合模型讨论 patch 的场景。

注意：

• 仅查看 Git 与文件，不提供 Git 写入与工作区写回策略以外的越权操作。
• 未配置 .codex/environments/environment.toml 的 [setup].script 时不会自动跑 pnpm run setup 等命令。
• DSH 升级到不兼容版本时插件可能拒绝加载（见 README「DSH 升级兼容策略」）；应升级已验证的插件版本或回退宿主，勿强行删除持久状态绕过检查。
• SkillHub 为社区目录，与 DeepSeek / 幻方无官方从属关系；插件非 DSH 内置应用商店条目。

结尾¶

dsh-minimalist-worktree 把 worktree 选择、目录可见性与只读变更审查收进会话流，避免额外管理页和常驻目录栏，并与 DSH 归档、沙箱及主题体系对齐。查阅说明与版本信息可访问 SkillHub 目录页 与 GitHub 仓库。