treehouse

Treehouse

treehouse 会维护一个预热的 Git 工作树池，并预先安装好依赖项。可针对已获授权的任务自主租用工作树。将空工作树归还到池中，而不是销毁，这样下一项工作就能拿到可直接使用的工作树；只有池中不应保留的工作树才应销毁。结算时，调用会话占用的工作树仍保持租用状态，其会话主机的拓扑也保持开放。

1. 检查已安装的版本和操作帮助。开始新工作时，使用 get --lease --json --lease-holder <effort> -b <branch>，并保存返回的 path、lease_id 和 lease_holder。解析路径的物理位置，并在使用前核实其仓库和分支。后续释放时使用返回的身份信息；持有者标签可能会被重复使用。
2. 释放工作树前，根据记录的获取信息核实其精确规范路径、仓库、分支和当前租约。确认工作树干净，保留所需的忽略文件，并使用调用工作流的合并证明确认分支已合并。如果原始获取信息没有记录身份，请在记录当前租约前核实所有权；仅凭当前池列表并不能授权接管他人的租约。
3. 释放前立即检查占用情况：
   • 来源： 使用 treehouse status --json，并结合对实时调用方、窗格和操作系统进程的检查。
   • 范围： 核实 Agent、空闲会话、Shell、服务及其子进程的实际当前目录，包括工作树路径下的后代进程。解析符号链接并比较路径组件，避免将前缀相似的同级路径误认为目标路径。
   • 不能作为证明的内容： 工作区检出元数据、标题和对话上下文不能证明进程所在位置。
   • 调用方： 单独检查调用方及其祖先，因为 Treehouse 会从报告的进程列表中过滤掉它们。
   • 已知用户： 已知会使用该工作树的服务或会话，即使其当前目录在别处，也算作占用者。
   • 被占用或情况不确定时： 保留租约和分支，并报告占用者或缺失的证据。此规则也适用于调用会话、缺少租约 ID、无法读取相关进程位置、已恢复或损坏的条目，以及身份信息发生变化的情况。status 会静默省略无法读取其目录的进程；进程列表为空本身并不能证明工作树没有被占用。保持拓扑开放，不要安排延迟清理，也不要终止占用者来实现结算。
4. 在目标工作树之外，仅使用 treehouse return <exact-path> --if-lease-id <recorded-id> --if-lease-holder <recorded-holder> 归还已核实的空闲目标。任何期间若有其他操作，重新核实身份和占用情况。这些标志会在分离、终止进程和重置之前以原子方式保护租约，但不会保护占用情况或终端拓扑。指定单个明确目标，因为 return --all 可能会回收被占用的工作树。
5. 归还后：
   • 结果： 检查命令的退出状态，并检查更新后的池和 Git 状态。
   • 删除分支： 只有在确认释放成功、调用工作流的合并证明与已核实的分支提交绑定，并且确认没有工作树仍检出该分支后，才能删除分支。删除前重新核实提交；若提交发生变化，则重新执行合并证明。
   • 归还失败、中断或状态不确定： 状态可能已经发生变化，因此应保留分支，在重试前检查实时状态；仅当原租约身份仍匹配时，才再次使用该身份。工作树槽位已可用或已重新分配，并不是重试归还的理由。 | 需求 | 命令 | 说明 | |---|---|---| | 为某项工作获取持久工作树 | treehouse get --lease --json --lease-holder <effort> -b <branch> | 返回路径和租约标识。 | | 查看工作树池 | treehouse status --json | 报告租约以及 return 将终止的进程；不包括调用者和无法读取其位置的进程。 | | 归还空工作树 | treehouse return <path> --if-lease-id <id> --if-lease-holder <holder> | 验证租约；终止工作树中的进程。 | | 预览彻底移除 | treehouse destroy <exact-path> | 试运行；使用 --yes 执行移除。 |

在新分支上创建工作树

除非 get 创建分支，否则租用的工作树会处于分离的 HEAD 状态。get --lease 会先获取 origin，然后从远程默认分支创建工作树；-b <branch> 会在该工作树上创建此项工作的分支，且不设置上游，因此在首次执行 git push -u 之前，直接运行 git push 不会推送到默认分支。如果分支已存在，-b 会失败。

注意事项

• 租用的工作树在归还之前不会再次分配，也不会被清理。
• return 会终止当前目录位于工作树中的进程，但不会终止 return 进程及其祖先进程；因此，从外部 shell 运行 return 可能会终止调用它的 Agent。如果拒绝清理脏工作树或未作答，命令会以状态码 3 退出并保留租约；其他故障可能发生在分离或终止之后。
• destroy --yes 会执行移除操作，--include-leased 则允许指定已租用的目标。destroy 不验证租约标识：除非能通过执行确认拥有独占所有权，否则应保留已租用的目标，并在移除前重新执行释放检查。
• return 会保留被忽略的文件，即使使用 --force 也不例外；下一个租用该工作树的工作会看到这些文件，例如旧的 .scratch/ 或构建输出。归还前，请复制出值得保留的内容。结项时应使用普通的带保护归还方式；--force 会在未经确认的情况下丢弃更改，但不会让被占用的工作树变得安全。
• destroy 会移除工作树中的所有内容，包括被忽略的文件，且不会发出警告。请先复制出值得保留的内容。
• destroy --include-in-use 会终止进程，--include-unlanded 则允许丢弃工作。这些目标在结项时应予以保留；这些标志不能证明你有权终止某个会话或服务。
• 租约保护并不会让单独的占用检查变成原子操作；如果无法通过执行确认安全的所有权，应保留目标。

说明

本页内容已根据 treehouse v3.1.0 帮助信息以及 kunchenguid/treehouse at c099281010efda0bf82bbaf8d882528fcbed6acc 核查，其中包括隔离的释放和进程测试样例。更新后请重新核查。