Treehouse 工作区租用生命周期IntelliJ Community 仓库隔离工作区的获取、检查与归还实战指南【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community在 IntelliJ Platform Community 这样体量巨大的仓库中为每个任务创建临时的 Git worktree 或额外克隆会带来难以承受的开销因此仓库引入了一套基于 Treehouse 的“租用式”隔离工作区方案。本指南以仓库技能文档 .agents/skills/treehouse/SKILL.md 为骨架结合 .ai/workspace-isolation.md 的策略约束与 build/treehouse/ 下的 Go 源码实现完整讲解 Treehouse 工作区的获取acquire、检查status与归还return三个命令的使用方法、失败处理原则以及 Codex 沙箱下的权限注意事项。读完本文你将能够安全地在隔离工作区中开展开发或 Agent 任务并在任务结束后正确归还租约。一、为什么需要 Treehouse 工作区隔离仓库策略文档 .ai/workspace-isolation.md 开宗明义地指出本仓库规模太大Agent 无法通过临时创建 Git worktree 或额外克隆来实现工作区隔离。这意味着在默认情况下任何 Agent 都不得自行执行git worktree add、克隆本仓库用于隔离或实现其他自定义的隔离机制除非用户为当前任务明确要求使用 Git worktree此时可以且只能创建一个任务范围内的 worktree。正确的做法是使用 Treehouse 技能其完整操作流程记录在 .agents/skills/treehouse/SKILL.md 中并且绝不绕过 wrapper 直接使用原始的 Treehouse 生命周期命令绝不运行treehouse enter、init、update、prune、destroy或--force因为这些操作可能进入、篡改甚至删除其他会话的工作区绝不自动安装、初始化、配置或升级 Treehouse 或其他工作区管理器。这套约束的核心思想是wrapper封装层只暴露“租用”这一最小安全子集把破坏性操作彻底挡在门外。二、理解 wrapper两个设计基石在深入命令之前先理解 wrapper 的两个关键设计它们直接决定了所有命令的形态与使用方式。1. 只封装“租用生命周期”wrapper 的命令行只暴露三个操作read status、write acquire、write return。它从不安装 Treehouse也不暴露enter、init、update、prune、destroy或--force。这一设计在 build/treehouse/main.go 的包注释中有明确阐述其语法采用“访问词 动作词”的两个 token 结构treehouse read status treehouse write acquire [--holder session-id] treehouse write return --workspace leased-path [--confirm-preserved]这种结构的一个重要收益是Bash 审批可以按前缀精确授权批准read前缀的审批永远不会授权任何write操作反之亦然。这一点在 Codex 沙箱一节还会详细展开。2. 统一的 JSON 输出与退出码约定wrapper 的所有输出都是 JSON成功时在stdout输出{ok:true,data:...}失败时在stderr输出{ok:false,error:...,details:...}并设置退出码退出码 2表示用法错误或前置条件不满足例如缺少必选参数、在错误目录运行退出码 127表示被固定的pinnedTreehouse CLI 二进制无法解析——这是 Bazel 构建失败或 runfiles 解析失败不是宿主环境缺少安装。三、运行 CLI 的前提条件技能文档明确要求CLI 由 Bazel 从固定版本源码构建因此会话中的第一次调用会耗时更长需要先完成构建从仓库根目录运行在 Ultimate 检出中为./community/tools/treehouse.cmd在 Community 检出中为./tools/treehouse.cmd技能文档中的示例均使用 Ultimate 拼写保持读调用与写调用分离这样审批可以保持狭窄且可复用若使用 Codex请先阅读本文第九节对应原文档的 “Codex sandbox” 一节。从源码角度wrapper 是一个仅依赖标准库的 Go 程序。在 build/treehouse/BUILD.bazel 中可以看到上游 Treehouse 模块通过独立的二进制目标//build/treehouse/cli在 runfiles 中被引用data [//build/treehouse/cli]从不通过 Go import 直接依赖pure on则禁用了 cgo以保证与仓库 hermetic LLVM 工具链的兼容性。这一点与技能文档“CLI 由 Bazel 从固定源码构建”的描述完全对应。四、检查工作区池read status检查当前工作区池的状态是唯一纯粹的只读操作./community/tools/treehouse.cmd read status返回结果会列出每一个工作区及其租约信息和进程列表。源码实现上build/treehouse/status.go 会调用底层的treehouse status --json并解析为结构化的工作区条目。每个条目包含的字段见 status.go包括字段含义name工作区名称path工作区绝对路径status工作区状态如 available / leasedlease_id租约 ID无租约时为空lease_holder租约持有者无租约时为空processes该工作区中的活动进程列表含 pid 与 commandleased_at租约开始时间无租约时为 null使用read status时务必注意status只用于检查。一个显示为 available 的工作区可能带有旧的 detached HEAD但绝不要对从status中拿到的路径执行 enter、edit、reset、rebase 或 synchronize只有write acquire才会真正预留并准备一个工作区。这一点有测试用例佐证build/treehouse/treehouse_test.go 中的TestReadStatusReturnsStructuredWorkspaceAndProcessData验证了read status会原样透出工作区与进程数据并确认底层只发起一次treehouse status --json调用TestReadStatusReportsAnUnavailableExecutable则验证了可执行文件不可用退出码 127时错误消息会明确提示“不要安装Do not install”。五、获取工作区write acquire获取一个隔离工作区是写操作的入口./community/tools/treehouse.cmd write acquire --holder session-id1. --holder 的解析优先级技能文档规定在有当前开发或 Agent 会话 ID 时应通过--holder传入。省略该选项时CLI 依次使用TREEHOUSE_LEASE_HOLDER环境变量最后才会生成一个agent-UUID标签。源码实现位于 build/treehouse/acquire.go 的holderFrom函数优先使用--holder选项值未传入时读取环境变量TREEHOUSE_LEASE_HOLDER仍不存在时生成agent-UUID若最终 holder 为空白则视为用法错误退出码 2——因为归还时的守卫需要用到它。对应的测试TestWriteAcquireUsesTheHolderEnvironmentVariable与TestWriteAcquireGeneratesAStableHolder分别验证了环境变量与自动生成两种回退路径。2. acquire 到底做了什么技能文档明确指出 acquire 的语义源码中也能一一对应以--no-fetch取得一个干净的租约底层调用treehouse get --lease --json --no-fetch --lease-holder holder见 acquire.go跳过对 origin 的 fetch在调用方当前的精确 HEAD 上做 detached checkout通过git checkout --force --detach source-head实现见 git.go。需要说明的是这里的--force是Git 的forcewrapper 仍然绝不向 Treehouse CLI 传递--force不传输任何 index、工作树或未跟踪变更也不执行 fetch、rebase、stash、cherry-pick 或文件复制仅在当前检出本身已持有租约时拒绝——因此一个检出可以同时持有多个租约。对应实现是 acquire.go 中针对当前 workspace 的活动租约检查拒绝时退出码为 2。在 detach 之前prepareAcquiredWorkspaceacquire.go还做了一系列安全校验确认获取到的路径就是其 Git 工作区根、确认其 Git common dir 与源仓库共享证明它属于源仓库、确认工作区初始是干净的detach 之后还会再次校验 HEAD 精确匹配且无变更任何一环失败都会触发回滚归还。3. 租约回执receiptacquire 的结果会包含工作区路径、租约 IDlease_id、持有者lease_holder以及回执路径receipt_path。回执文件位于被获取工作区内部的out/treehouse/lease.json结构为schema version 2见 build/treehouse/receipt.go{ schema_version: 2, path: workspace-path, lease_id: lease-id, lease_holder: holder, acquired_at: ISO-8601-timestamp, source_head: captured-source-head }其中source_head记录的是获取时捕获的源 HEAD。由于两种仓库布局Ultimate / Community都会忽略out/目录回执可以安全地存放其中。不要编辑、移动或复制这份回执——归还命令会把它与 Treehouse 的实时状态进行比对。六、归还工作区write return归还操作是整个生命周期中最需要谨慎的一步技能文档给出了严格的前置条件检查清单确认所有预期变更都已提交或另行保存且不存在任何有意的未提交、未跟踪工作残留停止read status报告的所有属于该工作区的进程——因为只要 Treehouse 报告有进程存在wrapper 就会拒绝归还从原始检出目录运行或从租用工作区之外的另一个目录运行——从外部运行可以让 wrapper 及其父 shell 不进入该工作区的进程列表避免“自己拒绝自己”。完成上述检查后执行./community/tools/treehouse.cmd write return --workspace leased-pathwrapper 的处理流程对应 build/treehouse/returncmd.go如下检查当前工作目录不在租用工作区之内否则退出码 2 拒绝读取工作区内的回执要求其为 schema version 2且回执中的path与请求路径一致校验该路径是其 Git 工作区根通过treehouse status --json读取实时状态校验回执的lease_id与lease_holder两个身份守卫都与实时租约一致检查工作区没有活动进程检查工作区是否 dirty。关键设计是wrapper 只会在 Treehouse 报告成功之后才删除回执而且它校验的是“实时租约状态”而非命令的退出码。这正是verifyReturnedreturncmd.go的职责——即使 Treehouse CLI 以 0 退出若实时池仍显示租约存在例如 CLI 在自己的 dirty 确认提示处中止了操作但仍以 0 退出wrapper 也会判定失败并保留回执与租约身份。处理 dirty 工作区--confirm-preserved当工作区存在未提交变更时普通归还会被拒绝退出码 2并在 details 中列出变更清单。如果你已确认所有工作都已妥善保存可以附加确认标志./community/tools/treehouse.cmd write return --workspace leased-path --confirm-preserved该标志的作用是替用户回答 Treehouse 的Clean and return? [Y/n]确认提示因此无需 TTY 交互即可完成 dirty 归还。源码中对应的是 receipt.go 的returnPromptAnswer y\n——wrapper 会向子进程 stdin 写入该答案测试TestWriteReturnAnswersThePromptOfAConfirmedDirtyReturn验证了这一点。需要注意只有在上述检查全部通过之后才应传入该标志因为归还会清理工作区没有该标志时wrapper 会拒绝 dirty 归还并且绝不用--force来替代。归还守卫的测试佐证build/treehouse/treehouse_test.go 对归还路径覆盖得非常细致可作为理解行为的参考TestWriteReturnReturnsACleanWorkspaceWithBothLeaseGuards验证底层调用为treehouse return path --if-lease-id id --if-lease-holder holder并在成功后删除回执TestWriteReturnRefusesAReceiptThatDoesNotMatchTheLiveLease本地回执与实时租约不一致时拒绝归还TestWriteReturnRefusesToRunFromInsideTheLeasedWorkspace从租用工作区内部运行时拒绝TestWriteReturnRefusesAWorkspaceWithLiveProcesses存在活动进程如 bazel时拒绝TestWriteReturnRejectsAVersionOneReceiptschema version 1 的旧回执来自已退役的 Bun 脚本在任何 spawn 之前就会被拒绝。七、命令失败时怎么办技能文档规定了失败场景的处理原则这些原则同样能在源码中找到对应实现失败时 CLI 会向 stderr 输出一份 JSON 失败文档包含消息error、退出码进程退出码与细节details退出码 2用法或前置条件失败例如缺少--workspace、传入了未知动作write destroy、尝试传--force。对应测试为TestCommandSurfaceRejectsDestructiveOperationsAndForce——它确认write destroy、write return --force、缺少--workspace都会以退出码 2 失败且不发起任何 spawn退出码 127被固定的 CLI 二进制无法解析。这在 main.go 的nativeFailure中有专门处理——错误消息会明确提示“Treehouse 不可用不要自行安装它也不要擅自回退到其他工作区机制如果用户为当前任务明确要求 Git worktree则可以使用一个”绝不安装 Treehouse也绝不擅自回退到 Git worktree、克隆或其他工作区管理器。安全时在当前检出中继续工作否则请用户提供一个隔离工作区只有在用户明确要求时才为当前任务创建一个 Git worktree当租约在失败后仍然存续时保留该租约并从错误中报告路径、租约 IDlease_id与持有者lease_holder。此外build/treehouse/main.go 的processExitCode会把超出进程可报告范围的退出码收敛到 1同时保留未收敛的native_exit_code细节字段确保诊断信息不丢失。值得一提的还有 acquire 的回滚机制acquire.go当回执写入失败、HEAD 准备失败或实时身份发生变更时wrapper 会立即尝试归还新拿到的租约并再次以实时池状态确认归还结果。如果回滚返回在 “Clean and return?” 提示处中止会留下一个无人能归还的租约因此回滚同样会写入确认答案测试TestWriteAcquireRollbackAnswersTheReturnPrompt验证了Stdin: y\n。八、源码视角wrapper 如何守住“绝不 --force”的底线整个技能的纪律核心是wrapper 从不向 Treehouse CLI 传递--force但实现中有一个看起来“矛盾”的细节值得专门解释Git detach 命令本身携带--force。build/treehouse/git.go 的注释说明了原因在大小写不敏感的文件系统上仅大小写不同的重命名会被git status隐藏但 Git 仍能看到两种拼写并拒绝普通 checkout。因此对一个所有检查都报告为“干净”的工作区普通 checkout 会中止。这个 force 是安全的因为有双重校验兜底prepareAcquiredWorkspace在 detach之前调用gitChanges检查dirty 直接拒绝detach之后再次读取 HEAD 并调用gitChanges只要有一项与源 HEAD 不一致就失败。也就是说Git 的 force 只作用于“git status无法报告”的条目而 Treehouse CLI 层面的--force从未被传递。测试TestWriteAcquireForcesTheDetachButNeverForcesTheCLI与TestTheWrapperNeverPassesForce专门锁定了这一行为。另一个值得关注的实现细节是 git.go 中的gitCommand所有 Git 调用都带-c core.fsmonitorfalse避免在工作区中启动或使用文件系统监视器守护进程防止它被计入工作区的进程列表而阻碍后续归还。九、Codex 沙箱下的使用规范技能文档最后一部分专门针对 Codex 沙箱环境规定了四个步骤的硬性要求acquire 之前先确认内置的request_permissions工具可用。若不可用不要获取租约并报告“本会话无法使用 Treehouse”不要请用户修改权限设置、以--add-dir重启或授予对 Treehouse 池的访问权限。从本技能目录运行并请求两个审批前缀../../../community/tools/treehouse.cmd read../../../community/tools/treehouse.cmd write在 Community 检出中两个前缀都要去掉community/。注意write 审批只允许 wrapper 触达 Treehouse 池并不授权具体的 acquire 或 return。改变工具的工作目录并不会把租用工作区加入会话的可写根目录。应保持从原始检出运行并使用request_permissions为恰好返回的那个path申请会话级写权限且必须在工作区内任何编辑之前完成。不要申请 Treehouse 池、源检出、共享 Git 目录或完全访问权限也不要用逐命令升级替代单次授权。获得授权后后续所有工具都应以该工作区路径作为工作目录。若授权被拒绝不要进入、编辑或在租用工作区中运行任何命令立即从原始检出归还这个未触碰的租约不要请用户重新配置权限。这套规则的本质是把“获取租约”与“写入工作区”拆成两个独立的权限步骤让审批粒度精确到单一路径同时保证失败路径上租约不会被泄漏或遗弃。十、参考文件速查本文所依据的技能文档与源码文件均可直接在仓库中查阅内容路径技能文档本文主体.agents/skills/treehouse/SKILL.md工作区隔离策略.ai/workspace-isolation.mdCLI 入口、JSON 封装与退出码build/treehouse/main.goacquire 流程与回滚build/treehouse/acquire.gostatus 解析build/treehouse/status.goreturn 流程与实时校验build/treehouse/returncmd.go回执 schema 与身份守卫build/treehouse/receipt.goGit 封装fsmonitor、detach、changesbuild/treehouse/git.goBazel 构建与 CLI 固定版本build/treehouse/BUILD.bazel行为测试套件build/treehouse/treehouse_test.go结语Treehouse 技能把“工作区隔离”收敛为read status、write acquire、write return三个可审计、可授权的操作配合回执schema v2、双身份守卫、实时池校验与回滚机制为大型仓库中的开发与 Agent 任务提供了可靠的安全边界。使用时只要记住三条主线读操作只做检查、写操作严格按前置条件执行、失败时既不擅自安装也不擅自回退就能在隔离工作区中安全地完成各项任务。【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Treehouse 工作区租用生命周期：IntelliJ Community 仓库隔离工作区的获取、检查与归还实战指南
Treehouse 工作区租用生命周期IntelliJ Community 仓库隔离工作区的获取、检查与归还实战指南【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community在 IntelliJ Platform Community 这样体量巨大的仓库中为每个任务创建临时的 Git worktree 或额外克隆会带来难以承受的开销因此仓库引入了一套基于 Treehouse 的“租用式”隔离工作区方案。本指南以仓库技能文档 .agents/skills/treehouse/SKILL.md 为骨架结合 .ai/workspace-isolation.md 的策略约束与 build/treehouse/ 下的 Go 源码实现完整讲解 Treehouse 工作区的获取acquire、检查status与归还return三个命令的使用方法、失败处理原则以及 Codex 沙箱下的权限注意事项。读完本文你将能够安全地在隔离工作区中开展开发或 Agent 任务并在任务结束后正确归还租约。一、为什么需要 Treehouse 工作区隔离仓库策略文档 .ai/workspace-isolation.md 开宗明义地指出本仓库规模太大Agent 无法通过临时创建 Git worktree 或额外克隆来实现工作区隔离。这意味着在默认情况下任何 Agent 都不得自行执行git worktree add、克隆本仓库用于隔离或实现其他自定义的隔离机制除非用户为当前任务明确要求使用 Git worktree此时可以且只能创建一个任务范围内的 worktree。正确的做法是使用 Treehouse 技能其完整操作流程记录在 .agents/skills/treehouse/SKILL.md 中并且绝不绕过 wrapper 直接使用原始的 Treehouse 生命周期命令绝不运行treehouse enter、init、update、prune、destroy或--force因为这些操作可能进入、篡改甚至删除其他会话的工作区绝不自动安装、初始化、配置或升级 Treehouse 或其他工作区管理器。这套约束的核心思想是wrapper封装层只暴露“租用”这一最小安全子集把破坏性操作彻底挡在门外。二、理解 wrapper两个设计基石在深入命令之前先理解 wrapper 的两个关键设计它们直接决定了所有命令的形态与使用方式。1. 只封装“租用生命周期”wrapper 的命令行只暴露三个操作read status、write acquire、write return。它从不安装 Treehouse也不暴露enter、init、update、prune、destroy或--force。这一设计在 build/treehouse/main.go 的包注释中有明确阐述其语法采用“访问词 动作词”的两个 token 结构treehouse read status treehouse write acquire [--holder session-id] treehouse write return --workspace leased-path [--confirm-preserved]这种结构的一个重要收益是Bash 审批可以按前缀精确授权批准read前缀的审批永远不会授权任何write操作反之亦然。这一点在 Codex 沙箱一节还会详细展开。2. 统一的 JSON 输出与退出码约定wrapper 的所有输出都是 JSON成功时在stdout输出{ok:true,data:...}失败时在stderr输出{ok:false,error:...,details:...}并设置退出码退出码 2表示用法错误或前置条件不满足例如缺少必选参数、在错误目录运行退出码 127表示被固定的pinnedTreehouse CLI 二进制无法解析——这是 Bazel 构建失败或 runfiles 解析失败不是宿主环境缺少安装。三、运行 CLI 的前提条件技能文档明确要求CLI 由 Bazel 从固定版本源码构建因此会话中的第一次调用会耗时更长需要先完成构建从仓库根目录运行在 Ultimate 检出中为./community/tools/treehouse.cmd在 Community 检出中为./tools/treehouse.cmd技能文档中的示例均使用 Ultimate 拼写保持读调用与写调用分离这样审批可以保持狭窄且可复用若使用 Codex请先阅读本文第九节对应原文档的 “Codex sandbox” 一节。从源码角度wrapper 是一个仅依赖标准库的 Go 程序。在 build/treehouse/BUILD.bazel 中可以看到上游 Treehouse 模块通过独立的二进制目标//build/treehouse/cli在 runfiles 中被引用data [//build/treehouse/cli]从不通过 Go import 直接依赖pure on则禁用了 cgo以保证与仓库 hermetic LLVM 工具链的兼容性。这一点与技能文档“CLI 由 Bazel 从固定源码构建”的描述完全对应。四、检查工作区池read status检查当前工作区池的状态是唯一纯粹的只读操作./community/tools/treehouse.cmd read status返回结果会列出每一个工作区及其租约信息和进程列表。源码实现上build/treehouse/status.go 会调用底层的treehouse status --json并解析为结构化的工作区条目。每个条目包含的字段见 status.go包括字段含义name工作区名称path工作区绝对路径status工作区状态如 available / leasedlease_id租约 ID无租约时为空lease_holder租约持有者无租约时为空processes该工作区中的活动进程列表含 pid 与 commandleased_at租约开始时间无租约时为 null使用read status时务必注意status只用于检查。一个显示为 available 的工作区可能带有旧的 detached HEAD但绝不要对从status中拿到的路径执行 enter、edit、reset、rebase 或 synchronize只有write acquire才会真正预留并准备一个工作区。这一点有测试用例佐证build/treehouse/treehouse_test.go 中的TestReadStatusReturnsStructuredWorkspaceAndProcessData验证了read status会原样透出工作区与进程数据并确认底层只发起一次treehouse status --json调用TestReadStatusReportsAnUnavailableExecutable则验证了可执行文件不可用退出码 127时错误消息会明确提示“不要安装Do not install”。五、获取工作区write acquire获取一个隔离工作区是写操作的入口./community/tools/treehouse.cmd write acquire --holder session-id1. --holder 的解析优先级技能文档规定在有当前开发或 Agent 会话 ID 时应通过--holder传入。省略该选项时CLI 依次使用TREEHOUSE_LEASE_HOLDER环境变量最后才会生成一个agent-UUID标签。源码实现位于 build/treehouse/acquire.go 的holderFrom函数优先使用--holder选项值未传入时读取环境变量TREEHOUSE_LEASE_HOLDER仍不存在时生成agent-UUID若最终 holder 为空白则视为用法错误退出码 2——因为归还时的守卫需要用到它。对应的测试TestWriteAcquireUsesTheHolderEnvironmentVariable与TestWriteAcquireGeneratesAStableHolder分别验证了环境变量与自动生成两种回退路径。2. acquire 到底做了什么技能文档明确指出 acquire 的语义源码中也能一一对应以--no-fetch取得一个干净的租约底层调用treehouse get --lease --json --no-fetch --lease-holder holder见 acquire.go跳过对 origin 的 fetch在调用方当前的精确 HEAD 上做 detached checkout通过git checkout --force --detach source-head实现见 git.go。需要说明的是这里的--force是Git 的forcewrapper 仍然绝不向 Treehouse CLI 传递--force不传输任何 index、工作树或未跟踪变更也不执行 fetch、rebase、stash、cherry-pick 或文件复制仅在当前检出本身已持有租约时拒绝——因此一个检出可以同时持有多个租约。对应实现是 acquire.go 中针对当前 workspace 的活动租约检查拒绝时退出码为 2。在 detach 之前prepareAcquiredWorkspaceacquire.go还做了一系列安全校验确认获取到的路径就是其 Git 工作区根、确认其 Git common dir 与源仓库共享证明它属于源仓库、确认工作区初始是干净的detach 之后还会再次校验 HEAD 精确匹配且无变更任何一环失败都会触发回滚归还。3. 租约回执receiptacquire 的结果会包含工作区路径、租约 IDlease_id、持有者lease_holder以及回执路径receipt_path。回执文件位于被获取工作区内部的out/treehouse/lease.json结构为schema version 2见 build/treehouse/receipt.go{ schema_version: 2, path: workspace-path, lease_id: lease-id, lease_holder: holder, acquired_at: ISO-8601-timestamp, source_head: captured-source-head }其中source_head记录的是获取时捕获的源 HEAD。由于两种仓库布局Ultimate / Community都会忽略out/目录回执可以安全地存放其中。不要编辑、移动或复制这份回执——归还命令会把它与 Treehouse 的实时状态进行比对。六、归还工作区write return归还操作是整个生命周期中最需要谨慎的一步技能文档给出了严格的前置条件检查清单确认所有预期变更都已提交或另行保存且不存在任何有意的未提交、未跟踪工作残留停止read status报告的所有属于该工作区的进程——因为只要 Treehouse 报告有进程存在wrapper 就会拒绝归还从原始检出目录运行或从租用工作区之外的另一个目录运行——从外部运行可以让 wrapper 及其父 shell 不进入该工作区的进程列表避免“自己拒绝自己”。完成上述检查后执行./community/tools/treehouse.cmd write return --workspace leased-pathwrapper 的处理流程对应 build/treehouse/returncmd.go如下检查当前工作目录不在租用工作区之内否则退出码 2 拒绝读取工作区内的回执要求其为 schema version 2且回执中的path与请求路径一致校验该路径是其 Git 工作区根通过treehouse status --json读取实时状态校验回执的lease_id与lease_holder两个身份守卫都与实时租约一致检查工作区没有活动进程检查工作区是否 dirty。关键设计是wrapper 只会在 Treehouse 报告成功之后才删除回执而且它校验的是“实时租约状态”而非命令的退出码。这正是verifyReturnedreturncmd.go的职责——即使 Treehouse CLI 以 0 退出若实时池仍显示租约存在例如 CLI 在自己的 dirty 确认提示处中止了操作但仍以 0 退出wrapper 也会判定失败并保留回执与租约身份。处理 dirty 工作区--confirm-preserved当工作区存在未提交变更时普通归还会被拒绝退出码 2并在 details 中列出变更清单。如果你已确认所有工作都已妥善保存可以附加确认标志./community/tools/treehouse.cmd write return --workspace leased-path --confirm-preserved该标志的作用是替用户回答 Treehouse 的Clean and return? [Y/n]确认提示因此无需 TTY 交互即可完成 dirty 归还。源码中对应的是 receipt.go 的returnPromptAnswer y\n——wrapper 会向子进程 stdin 写入该答案测试TestWriteReturnAnswersThePromptOfAConfirmedDirtyReturn验证了这一点。需要注意只有在上述检查全部通过之后才应传入该标志因为归还会清理工作区没有该标志时wrapper 会拒绝 dirty 归还并且绝不用--force来替代。归还守卫的测试佐证build/treehouse/treehouse_test.go 对归还路径覆盖得非常细致可作为理解行为的参考TestWriteReturnReturnsACleanWorkspaceWithBothLeaseGuards验证底层调用为treehouse return path --if-lease-id id --if-lease-holder holder并在成功后删除回执TestWriteReturnRefusesAReceiptThatDoesNotMatchTheLiveLease本地回执与实时租约不一致时拒绝归还TestWriteReturnRefusesToRunFromInsideTheLeasedWorkspace从租用工作区内部运行时拒绝TestWriteReturnRefusesAWorkspaceWithLiveProcesses存在活动进程如 bazel时拒绝TestWriteReturnRejectsAVersionOneReceiptschema version 1 的旧回执来自已退役的 Bun 脚本在任何 spawn 之前就会被拒绝。七、命令失败时怎么办技能文档规定了失败场景的处理原则这些原则同样能在源码中找到对应实现失败时 CLI 会向 stderr 输出一份 JSON 失败文档包含消息error、退出码进程退出码与细节details退出码 2用法或前置条件失败例如缺少--workspace、传入了未知动作write destroy、尝试传--force。对应测试为TestCommandSurfaceRejectsDestructiveOperationsAndForce——它确认write destroy、write return --force、缺少--workspace都会以退出码 2 失败且不发起任何 spawn退出码 127被固定的 CLI 二进制无法解析。这在 main.go 的nativeFailure中有专门处理——错误消息会明确提示“Treehouse 不可用不要自行安装它也不要擅自回退到其他工作区机制如果用户为当前任务明确要求 Git worktree则可以使用一个”绝不安装 Treehouse也绝不擅自回退到 Git worktree、克隆或其他工作区管理器。安全时在当前检出中继续工作否则请用户提供一个隔离工作区只有在用户明确要求时才为当前任务创建一个 Git worktree当租约在失败后仍然存续时保留该租约并从错误中报告路径、租约 IDlease_id与持有者lease_holder。此外build/treehouse/main.go 的processExitCode会把超出进程可报告范围的退出码收敛到 1同时保留未收敛的native_exit_code细节字段确保诊断信息不丢失。值得一提的还有 acquire 的回滚机制acquire.go当回执写入失败、HEAD 准备失败或实时身份发生变更时wrapper 会立即尝试归还新拿到的租约并再次以实时池状态确认归还结果。如果回滚返回在 “Clean and return?” 提示处中止会留下一个无人能归还的租约因此回滚同样会写入确认答案测试TestWriteAcquireRollbackAnswersTheReturnPrompt验证了Stdin: y\n。八、源码视角wrapper 如何守住“绝不 --force”的底线整个技能的纪律核心是wrapper 从不向 Treehouse CLI 传递--force但实现中有一个看起来“矛盾”的细节值得专门解释Git detach 命令本身携带--force。build/treehouse/git.go 的注释说明了原因在大小写不敏感的文件系统上仅大小写不同的重命名会被git status隐藏但 Git 仍能看到两种拼写并拒绝普通 checkout。因此对一个所有检查都报告为“干净”的工作区普通 checkout 会中止。这个 force 是安全的因为有双重校验兜底prepareAcquiredWorkspace在 detach之前调用gitChanges检查dirty 直接拒绝detach之后再次读取 HEAD 并调用gitChanges只要有一项与源 HEAD 不一致就失败。也就是说Git 的 force 只作用于“git status无法报告”的条目而 Treehouse CLI 层面的--force从未被传递。测试TestWriteAcquireForcesTheDetachButNeverForcesTheCLI与TestTheWrapperNeverPassesForce专门锁定了这一行为。另一个值得关注的实现细节是 git.go 中的gitCommand所有 Git 调用都带-c core.fsmonitorfalse避免在工作区中启动或使用文件系统监视器守护进程防止它被计入工作区的进程列表而阻碍后续归还。九、Codex 沙箱下的使用规范技能文档最后一部分专门针对 Codex 沙箱环境规定了四个步骤的硬性要求acquire 之前先确认内置的request_permissions工具可用。若不可用不要获取租约并报告“本会话无法使用 Treehouse”不要请用户修改权限设置、以--add-dir重启或授予对 Treehouse 池的访问权限。从本技能目录运行并请求两个审批前缀../../../community/tools/treehouse.cmd read../../../community/tools/treehouse.cmd write在 Community 检出中两个前缀都要去掉community/。注意write 审批只允许 wrapper 触达 Treehouse 池并不授权具体的 acquire 或 return。改变工具的工作目录并不会把租用工作区加入会话的可写根目录。应保持从原始检出运行并使用request_permissions为恰好返回的那个path申请会话级写权限且必须在工作区内任何编辑之前完成。不要申请 Treehouse 池、源检出、共享 Git 目录或完全访问权限也不要用逐命令升级替代单次授权。获得授权后后续所有工具都应以该工作区路径作为工作目录。若授权被拒绝不要进入、编辑或在租用工作区中运行任何命令立即从原始检出归还这个未触碰的租约不要请用户重新配置权限。这套规则的本质是把“获取租约”与“写入工作区”拆成两个独立的权限步骤让审批粒度精确到单一路径同时保证失败路径上租约不会被泄漏或遗弃。十、参考文件速查本文所依据的技能文档与源码文件均可直接在仓库中查阅内容路径技能文档本文主体.agents/skills/treehouse/SKILL.md工作区隔离策略.ai/workspace-isolation.mdCLI 入口、JSON 封装与退出码build/treehouse/main.goacquire 流程与回滚build/treehouse/acquire.gostatus 解析build/treehouse/status.goreturn 流程与实时校验build/treehouse/returncmd.go回执 schema 与身份守卫build/treehouse/receipt.goGit 封装fsmonitor、detach、changesbuild/treehouse/git.goBazel 构建与 CLI 固定版本build/treehouse/BUILD.bazel行为测试套件build/treehouse/treehouse_test.go结语Treehouse 技能把“工作区隔离”收敛为read status、write acquire、write return三个可审计、可授权的操作配合回执schema v2、双身份守卫、实时池校验与回滚机制为大型仓库中的开发与 Agent 任务提供了可靠的安全边界。使用时只要记住三条主线读操作只做检查、写操作严格按前置条件执行、失败时既不擅自安装也不擅自回退就能在隔离工作区中安全地完成各项任务。【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考