dsh-minimalist-worktree

为 DeepSeek Harness 提供参考 Paseo 的轻量工作树交互，支持中文、英文及 DSH 主题：

• 新会话的 本地 / 新建 worktree、起始分支两个紧凑选择器。
• 会话列表的悬浮卡片：鼠标移到会话条目上，显示该会话的分支名与完整目录，无常驻图标、无点击复制。
• 会话内的变更视图：文件列表、分支及只读 unified Diff，不在输入框外常驻目录栏。

不增加工作树管理页面。两个选择器仅在会话尚未发送消息且工作区属于 Git 仓库时显示。非 Git 工作区默认本地并隐藏选择器；检测完成前也不闪现。目录信息放入 DSH 原生会话行悬浮卡片，不替换列表或标题。权限或 Git 读取错误不会被误判为“非 Git”或“没有变更”。

右侧文件与变更（0.5.0）

原「工作区文件」入口的面板内容升级为左侧文件/变更导航、右侧当前文件/行内 Diff（自动换行、收起目录、复用 DSH 全屏）。复用已有 guide/快捷键/插件级 Tab，只替换 files 类型的正文，不创建内部文件 Tab，不影响终端、浏览器等其他类型。全部使用 DSH 主题变量。

文件树以 Session 实际 workingDirectory 为根，按层展开（每目录500条）；点文件原位替换只读 UTF8预览（512KiB/10000行）。文件名筛选仅作用于已展开目录。0.5.5 增加文件类型标识；Markdown 渲染标题、列表、代码块、表格、引用等（有界基础语法，不承诺完整 CommonMark），JSON格式化、CSV/TSV表格（200行50列），PNG/JPEG/GIF/WebP/BMP图像预览（签名检查，最大5MiB）；代码和SVG/HTML仍为安全源码，Office/PDF等暂不嵌入。Markdown不执行原始HTML、不加载远程图片；链接仅HTTP(S)。主题沿用DSH变量。

Git 变更以仓库根为比较基准，支持全部未提交/未暂存/已暂存、根仓及已登记子模块分组，子模块未初始化不自动拉取。Git 变更不局限于当前AI；共享源目录会包含其他工具的改动。仅从Git索引登记的gitlink发现子仓，最多32仓；每次操作10秒预算，失败/超限不伪装干净。会话cwd在仓库子目录时仓库级Diff仍可查看，超出cwd的文件不提供“打开文件”，防止目录越界。

目录展开仅补读新目录，已加载目录不清空；后台刷新保留现有树节点与选中文件，内容按文件记录滚动位置，无整树加载占位闪动。切会话/cwd/连接时重置并取消过期读取；打开、聚焦、回合结束、手动刷新时重新查询，不逐token轮询Git。暂未接入文件系统实时watch，外部编辑后可聚焦或点刷新。单文件patch按选中加载。无暂存、提交、撤销、推送操作。

使用

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

新工作树分支使用 dsh/<形容词>-<名词>：从内置英文词表随机组合，例如 dsh/ripe-bird、dsh/calm-otter。新建目录为执行环境用户主目录下的 ~/.dsh/worktrees/<项目名>-<规范仓库路径SHA256前8位>/ripe-bird，dsh/ 只作为分支前缀，不再嵌套在源项目的 .agents 目录内。名称不添加 UUID 或数字后缀；哈希只用于区分不同路径的同名仓库。已有工作树不搬迁、不删除。保存选择时生成并固定名称；更改起始分支会沿用，切回本地再选新建会重新抽取。旧版本已经保存或创建的名称保持不变。

选名会只读检查完整的本地分支引用，已存在的同名分支或其子分支会跳过，最多抽取 64 次；本次插件运行内也会避免并发会话选中同一名称。若已有名为 dsh 的分支，将提示命名空间冲突，不会自动重命名或删除。目录占用及保存选择后发生的并发冲突仍由底层创建服务安全拒绝，不会覆盖或在分配后换名重试。

起始提交在保存选择时固定；不会自动 fetch。未提交改动保留在源目录，不复制到新 worktree。检出自身不会安装依赖或初始化子模块；下述显式配置的 setup 脚本可以执行这些操作。

创建遵守会话原有的文件和沙箱策略，使用 DSH 挂载的文件系统、子进程和沙箱创建外部工作树，不修改源仓库的 HEAD，不自动扩大写入权限。创建失败会中止模型步骤，不会自动重试、删除文件或退回本地运行。失败或中断可能留下检出目录/分支，请检查后自行处理；重新开始新会话再选择。

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

工作树丢失与回源保护（0.4.2）

仅修复本插件，不修改 DSH 本身的 workingDirectory.ensure 自动恢复规则。每次模型 pre-step 前后核验 created 工作树的实际目录/分支；目录缺失或当前 cwd 意外离开隔离目录时阻止执行。在输入框上方显示恢复选择（仅异常出现，不常驻目录栏），读取阶段不创建、不切目录、不运行 setup。

• 重建隔离工作树：仅原目录不存在时可用。原分支仍在时固定该分支当前本地提交；原分支删除时显示原先记录的提交，必须再次确认，绝不自动替换成当前源分支。只在外部受控池的原路径重建，不覆盖现有目录；完成后按已配置 setup 初始化。
• 使用源目录：先展示完整源目录、当前本地分支，再二次确认。决定持久绑定当前会话/原选择/源仓库分支和提交。源状态或目录变化会失效；不选择、取消、刷新不授权。
• 恢复失败/中断持久 fail-closed，不自动重复分配或切回源目录。无快照删除的未提交内容不会凭重建找回。旧 .agents 目录不支持自动重建，可显式选择源目录。
• 成功后提醒重新发送原消息，不自动重发，防止重复任务。选择属于用户授权，不提供模型可调用的 mutating recovery 工具；RPC 的 Host 校验会话、目录状态 token 及空闲状态，页面不会仅靠按钮禁用保证安全。

Paseo 风格归档清理（0.4.1）

仅处理更新后发生的新归档，不扫描历史归档。只清理本插件创建并核验归属的外部工作树，保留分支与会话历史。确认已归档、初始化及任务不再运行、其他会话不占用、注册未锁定且分支/路径/common-dir 一致后，执行 git worktree remove --force -- <精确目标>。不创建新快照，未提交、未跟踪、ignored 文件（包括 .env 和 node_modules）会被删除，不能由保留分支恢复。 请在归档前提交需要保留的成果。

遇到运行中、共享占用、锁定、陌生目录或执行权限不足时保留并记录原因；清理失败不影响归档。沿用 DSH 的归档停止机制，不绕过沙箱；不同于 Paseo 的底层兜底，不执行 rm -rf 或广泛 prune，不自动执行仓库 teardown 命令。停止尚未完成时会保留，不冒险删除。只对齐“无快照移除托管目录、释放分支”的核心语义，不声称完全复刻其生命周期。

既有 ~/.dsh/worktree-snapshots/ 完整或未完成备份均保留，不批量删除。旧完整快照仍可通过「变更」视图或 dsh_worktree_restore 恢复；新归档无快照则没有恢复入口。旧 .agents 工作树不自动清理。dsh_worktree inspect 的 cleanup 返回清理结果与原因。

新工作树的 Codex 本地环境初始化

在新检出目录中读取 .codex/environments/environment.toml，支持已核实的 Codex v1 默认 setup：

version = 1
name = "my-project"
[setup]
script = "pnpm run setup"

• 新建检出完成后、首个模型步骤前执行一次；工作目录为新工作树根目录。缺少配置或脚本为空则记录 skipped。不会从源工作区复制未跟踪配置，不从 AGENTS.md 推断命令，不因为存在 package.json 的 setup 就自动运行。不执行 [[actions]]。
• 使用执行环境默认 shell 的 -lc 参数执行，受原会话沙箱约束；最长 10 分钟，输出各保留 128 KiB，失败携带末尾诊断。安装、fetch、子模块更新等副作用由脚本明确决定，可能联网。没有初始化回滚或静默本地兜底。
• 在执行前持久保存 created 工作树和 running 初始化状态；成功/跳过/失败状态通过 dsh_worktree inspect 可读。失败或进程中断后不自动重复创建或重复执行；先检查保留目录和日志。已有 created 工作树不会补跑初始化。
• 与 Codex 的对齐边界： 官方 Local environments 确认自动新 worktree setup、平台覆盖及 actions 分离。公开资料未给出完整平台覆盖 TOML、shell、配置来源优先级、重试合同。本版仅兼容 [setup].script，未知 setup 字段明确拒绝，不声称完整逐项等同；Windows setup 暂停执行并提示不支持，避免选错脚本。以上 cwd、shell、限制和失败关闭是本插件明确合同。
• Codex 的 .worktreeinclude 文件复制、配置编辑器及平台专属脚本暂未实现，不会复制密钥、.env 或启动开发服务。未配置该文件的项目不会自动运行 pnpm run setup。

初始化过程展示（0.3.1）

• 在首条用户消息后展示一条轻量状态：创建工作树 / 运行环境初始化，显示实际累计秒数；初次进行中自动展开日志，允许手动收起。
• 成功或未配置跳过时原位收起，可展开回看；失败自动展开原因并说明保留目录、未启动任务。准备完成仅代表可以继续执行，不伪称模型已经输出。
• 使用当前 DSH 的主题变量，无固定 Codex 配色、不新增菜单、不替换原用户消息或任务过程。按首条真实用户输入序号定位；该输入尚未加载到历史窗口时不错误挂到其他消息下。
• 进度使用独立 dsh_minimalist_worktree_progress 存储域，记录阶段、时间、32 KiB 尾部日志与截断标记。旧会话无记录不补造完成卡片；重启后的遗留 running 状态显示中断失败，不重复执行。
• 仅在初始化子进程存活时每 200ms 读取已收集输出，停止时最后刷新并回收子进程；页面通过有界等待变化的只读 RPC 订阅，完成后停止，切会话/断线/卸载即取消。没有重复 Git 轮询。
• 日志作为纯文本展示，去除终端控制字符并尽力遮盖常见凭证格式。此脱敏不保证识别任意自定义秘密，setup 脚本不应打印密钥。日志刷新不滚动整个页面、不抢焦点。
• 停止任务仍使用 DSH 原有停止按钮；不新增重试初始化按钮，不改变 0.3.0 的执行、授权和失败语义。

当前目录与只读 Diff

会话列表条目的原生悬浮卡片增加“当前分支”和“当前目录”两行，跟随被悬停的会话，而不是当前打开的会话。沿用宿主的悬停延迟、定位和关闭行为，不增加图标、按钮或复制操作。浮层打开时才查询，关闭后释放订阅并取消未完成请求。目录使用实际 cwd；非 Git、读取失败或未打开的历史会话无法实时查询时明确提示，不编造分支。选择 worktree 后、实际创建前仍显示源目录。

打开会话的「变更」视图。桌面布局为文件列表与 Diff 分栏，窄屏上下排列。可选择：

范围	比较方式
全部未提交（默认）	HEAD → 工作目录 的净变化，加未跟踪文件；不是 staged 与 unstaged 数字简单相加
未暂存	index → 工作目录，加未跟踪文件
已暂存	HEAD → index

尚无首次提交的仓库以空树为基准。比较覆盖当前仓库根目录，即使会话 cwd 是子目录；独立 worktree 使用它自己的 HEAD、index 和工作目录。包含手工及其他工具产生的修改，不局限于 AI 修改。首版不提供相对起始分支的累计差异。

打开面板后才读取所选文件的 patch；原 changes 摘要不读取未跟踪文件内容；右侧文件面板的 browser 摘要会对未跟踪文本做有界行数统计（单文件512KiB、单仓累计4MiB），二进制、超限或不可读文件仍标记未统计，不编造完整数字。重命名显示新旧路径；二进制、冲突、子模块指针、符号链接及超限文件显示原因，不强行展开内容。

会话、工作目录、连接发生变化，回合结束、页面重新获得焦点，以及手动刷新时重新查询。重复请求合并，失效请求取消或丢弃；不持续轮询，也不逐 token 触发 Git。查询失败有错误提示，不将失败渲染为干净工作区。

边界与安全

• 仅查看，不暂存、提交、撤销、切换分支、fetch、写入 Git 对象或改动源文件。
• 通过会话挂载的文件系统、子进程与沙箱执行；Git 使用字面量参数，不调用 shell。禁用外部 diff、textconv、fsmonitor、hooks 和已配置的内容过滤驱动。无法安全解析过滤驱动配置时拒绝查询。
• 单次操作最多 10 秒；Git 元数据最多 2 MiB，列表最多 500 个文件；单文件 patch 最多 512 KiB / 10,000 行。超限不返回截断后伪装完整的 patch。文件列表和统计的限制会明确显示。
• patch 路径必须是当前比较范围内的精确已变更路径；不接受目录或前缀读取。未跟踪文件只做有界读取，不遍历嵌套仓库，不跟随可见的符号链接或符号链接祖先。
• 挂载文件系统没有基于文件描述符的 no-follow 读取接口。实现会在读取前后复核路径和版本，但不承诺抵御恶意宿主在系统调用间精准替换符号链接的竞态。仓库或配置在多次查询之间变化时，结果也不是原子快照，可手动刷新确认。

安装与构建

当前定版 0.5.17，已适配 DSH 0.2.2-rc.1，并保留 0.2.1-rc.5 projection 接口兼容。目录安装通过 DSH Plugin Manager 完成，不需要修改用户配置文件：

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

本地开发使用 Node 24+：

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

client.js 是生成的浏览器模块；修改 src/client.js、src/changes-client.js 或语言资源后需重新构建。更换已安装插件需要重启 DSH 才能保证加载全新的模块，不能仅凭同名插槽推断代码已更新。

DSH 升级兼容策略

• 不是 DSH 每更新一次就必然失效。 旧版插件声明了精确的 engines.dsh: 0.2.1-rc.5，因此即使接口未变，宿主升级也会拒绝加载。现在 engines 和协议 peer 统一为 >=0.2.1-rc.5 <0.3.0-0；DSH 的版本检查包含 prerelease，允许这个范围内的 0.2 系列版本，不跨入 0.3 的预发布版。
• 允许加载不等于未来版本已验证。 当前协议开发依赖固定为 0.2.2-rc.1，回归测试用它及其 Cordis peer 执行。新版本若在 0.2 系列内破坏接口，仍需要插件适配；不使用 *，也不自动申请版本风险豁免。
• 按能力兼容，而非堆版本分支。 0.2.2 的 sessionProjections.register() 改为异步 ready handle，先 await 注册，再通过 handle 读取和释放；旧版 callable disposer / registry stateOf 通过窄适配保留。工作树持久状态与数据版本不变，不重建或删除旧工作树。
• 维护流程： 每次 DSH 升级核对三个 UI 插槽、RPC/访问控制、projection 和 worktree 服务；更新固定的测试协议版本，运行全量测试，再安装并核验实际查询及页面。跨 0.3 时先验证接口并发布新的插件版本，再扩展上界。兼容范围测试防止误回到精确锁定或无上界放行。
• 故障处理： 若升级后不能加载，先查看插件页的 incompatible-version 或激活错误。保留工作目录及 Git 数据，升级已验证的插件；必要时回退 DSH。不要为了强行加载而删除持久状态或自动豁免版本检查。

该策略减少同系列更新的无谓拦截，但不是宿主 API 永远稳定的保证。未配置自动检测、自动发布或定时任务。

结构与验证范围

• index.js：Host 服务、严格 RPC、生命周期和代理工具
• core.js：按会话串行的持久选择、固定提交、一次性准备
• git.js：受限时长/输出、无 shell 的只读 Git 元数据查询
• git-changes.js：仓库级变更摘要、按文件 patch 与有界安全读取
• changes.js：变更请求/结果 schema、会话身份核验与刷新 projection
• names.js：dsh/ 双英文单词随机名称与创建前的分支避重
• src/client.js：新会话的两个选择器
• src/changes-client.js：目录状态栏、变更视图和共享查询资源
• 测试：状态机、Host 服务集成、资源并发及真实临时 Git 仓库回归

UI 和代理的 dsh_worktree 工具共享同一 operate 操作，动作只有 inspect 和 select；select 仅接受打开且未开始的会话，保存选择时不立即分配 worktree。

新增 dsh_worktree_changes 工具与 UI 共用同一 changes 操作：summary 返回真实目录、分支和变更摘要；diff 读取 path 指定的单文件 patch。scope 默认为 all，还可选 unstaged、staged；sessionId 默认当前会话，也可指定其他已打开的会话。已开始的会话也能查询。失败或无法预览均携带原因，没有写入操作。

测试不会操作用户仓库。自动测试不等同于已在真实页面完成点击、浅深色或图标渲染验收；实际安装/页面验证结果以交付说明为准。

许可

MIT。随包 SVG 图标为本项目原创，可按相同许可使用。与 Paseo 无代码或资源依赖关系。