# Conflicts: # packages/experimental/client-ui-forge/README.i18n.yaml # packages/experimental/worktree/README.i18n.yaml # packages/experimental/worktree/README.md # packages/experimental/worktree/README.zh.md
9.6 KiB
description, kind
| description | kind |
|---|---|
| 按照调用 Session 的文件策略创建并进入保留的 Git 工作树。 | package-reference |
@deepseek-ai/dsh-experimental-worktree
English | 中文
概述
从本地提交创建隔离的检出目录,并在其中继续同一个 Session。每次操作创建新的具名分支,源检出目录保持不变。所有写入均受现有沙箱约束。离开检出目录会保留文件与分支。
目录
使用本包
将服务与 workingDirectory、fs、subprocess、sandbox、sandboxPolicy 和 sessionProjections 提供方一起挂载。归档清理还需要 workspaceRegistry 与 sessionQuery,并在挂载了 sessionProjectionCache 时使用它;缺少前两者时服务只创建与恢复。模型需要此操作时,再添加工具包。
- name: '@deepseek-ai/dsh-experimental-worktree'
- name: '@deepseek-ai/dsh-experimental-tool-worktree'
ctx.worktrees.create(agent, { name?, from? }, signal?, onPhase?) 创建新分支与检出目录,再通过 ctx.workingDirectory.set 进入规范化的检出目录。from 在创建前解析为本地提交,默认是 HEAD;暂存、未暂存、未跟踪以及被忽略的源文件均不复制。baseCommit 报告解析出的提交对象名称;仓库本地的替换引用仍作用于检出的内容。检出操作禁用已配置的 Git clean、smudge 和 process 过滤器,不修改仓库配置。分支或检出路径已存在时会报错。返回记录包含 path、branch、baseCommit 和 repositoryRoot。可选的第四个参数 onPhase 在校验、分配目录与创建分支之前收到 prepare,在写入文件并进入检出之前收到 checkout;它不得抛出异常。
ctx.worktrees.restore(agent, { path, branch, baseCommit, repositoryRoot }, signal?, onPhase?) 在记录的目录重新检出被删除的 worktree。它在修改前校验记录中的仓库根目录、完整提交对象名、分支和配置池内的规范目标路径。它只通过 git worktree remove 移除缺失目标的未锁定登记;其他 worktree 与锁定登记保持不变。随后在分支仍存在时检出该分支,否则在 baseCommit 重新创建同名分支,并通过 branchRecreated 报告是哪种情况。目录已存在时会报错。调用方 Session 的工作目录不变,从未提交的修改无法恢复。检出与创建时一样禁用过滤器。onPhase 在检查目录、清理登记与创建分支之前收到 prepare,在写入文件之前收到 checkout;它不能抛出异常。
每次创建都会在目录切换之后向 Session 日志追加一条 plugin:worktree/created 事件,因此 worktree 投影列出该 Session 的检出目录,位于 fork 继承前缀内的条目 owned 为 false。Workspace 归档某个 Session 时,服务为该 Session 自己创建的第一个检出目录登记一条 scheduled 清理并立即返回;检查在后台进行。retainOnArchive 开启时,归档不登记任何清理,所有检出目录都保留;该字段是 volatile 字段,每次归档时读取,Forge 面板在插件页该套件的 worktree 行上以开关编辑它。只要任一未归档 Session 仍引用该目录——通过记录的创建,或通过位于其中的工作目录(祖先子代理已归档的 Session 视为已归档;冷 Session 从投影缓存或其日志读取)——或创建者的沙箱策略为只读,目录就保留。符合条件的目录在路径锁内再做一次使用检查后,用创建者的策略执行不带 force 的 git worktree remove;路径锁同时通过 working-directory/access 阻塞进入该路径的 ensure 与 set;分支及其提交保留。跟踪文件改动、未跟踪文件、隐藏的索引标记、子模块、锁、分离 HEAD、分支不匹配以及位于配置池之外的目标都会保留目录;被忽略的文件不会,因为 Git 自身会丢弃它们。不检查进程:仍在写入的进程会让 Git 拒绝删除,空闲进程的下一条命令会失败。取消归档会取消尚未获准的删除,并等待已获准的删除结束。cleanupOf(session, revision) 读取本次尝试,或等待指定修订号结束,状态为 scheduled、retained、removed 或 failed;失败时 Session 仍保持归档并记录警告。此事件存在之前创建的检出目录,以及更早归档的 Session,不会被扫描。
默认检出目录是 <current checkout root>/.agents/worktrees/<name>。返回的 repositoryRoot 是调用方当前检出目录的顶层目录;如果它是链接检出目录,工作树父目录就嵌套在其中。省略名称时,名称由前缀 dsh-、Session id 中 UUID 的前 8 位十六进制数、一个连字符和 4 位随机十六进制数组成,例如 dsh-6b1f02c4-9a3e;Session id 不含 UUID 时,前缀后接 8 位随机十六进制数。generatedWorktreeName 导出同一规则,供在创建前确定名称的调用方使用。仅当服务的分配操作创建了父目录时,服务才会写入内容为 * 加换行符的 .gitignore;已有文件与忽略规则保持不变。每条 Git 和 Node 命令各自受 timeoutMs 时限约束,默认 5 分钟,使大仓库在较慢的文件系统上也能完成检出;取消仍会终止正在运行的命令。相对路径 directory、生成名称使用的 namePrefix、可执行程序、进程限制与 retainOnArchive 可在配置目录中查阅。
了解实现
实现细节——点击展开
Git 与目录分配通过挂载的子进程及沙箱提供方执行,沿用调用 Session 的文件策略。创建操作不会扩大目标目录或共享 Git 管理目录的写权限。目录创建独占申请目标路径;取消或初始化失败可能留下已有产物,错误会包含其路径。服务销毁会中止待完成操作,并等待它们结束。
| 源码 | 职责 |
|---|---|
src/index.ts |
解析源提交、创建检出目录并发布新的工作目录 |
src/process.ts |
约束字面参数、限制输出并等待进程终止 |
src/directory.ts |
申请目标目录并初始化新建工作树父目录的忽略文件 |
本包不发布运行时不变量伴随入口:Git 拥有工作树注册信息,工作目录服务拥有 Session 目录;本包不保留二者的独立投影。
深入探索
- 工作树子系统——请求、结果与服务参考。
- 工作目录 — 记录的 Session 目录与目录切换。
- 工作树工具 — 面向模型的创建操作。
- 子进程 — 进程所有权与执行环境。
- 创建决策 — 保留检出目录与既有写权限。
模型体验
通过工作树工具的创建结果与工作目录服务记录的 Session 上下文间接影响模型。
KV Cache 影响
本包不贡献提示文本。其消费方负责追加工具结果与记录的目录上下文。
已知限制与待办工作
- 保留的产物——离开工作树时保留其分支和文件,归档清理也从不删除分支。安装失败同样可能保留部分产物;删除失败可能留下部分目录,可在保留的分支上恢复覆盖。
- 仅限本地提交——创建操作不会获取远端提交或部分克隆中缺失的对象、初始化子模块、安装依赖或复制未提交文件。Git 满足执行要求时,本地对象缺失会导致创建失败。
- 过滤器处理前的内容——检出时跳过已配置的过滤器,以避免执行仓库配置的程序或隐式下载。Git LFS 指针与加密 blob 保持存储时的形式;拉取实体内容或解密由用户另行执行。
- 执行要求——子进程提供方必须在与文件系统提供方相同的执行环境中提供 Git 与 Node。Git 必须识别
GIT_NO_LAZY_FETCH:Git 2.45 及 2.39.4、2.40.2、2.41.1、2.42.2、2.43.4、2.44.1 维护版本均支持;更早的版本会忽略该变量并继续执行而不报错,因此创建操作可能从 promisor 远程获取缺失的部分克隆对象。git --no-lazy-fetch选项会拒绝这些版本,但它仅在 Git 2.45 及以后存在,也会拒绝上述已修补的维护版本。现有沙箱必须允许写入检出目录与共享 Git 元数据。