treehouse

无需手动管理 worktree，即可轻松管理 worktree。

你还在一次只处理一个任务吗？你还在手动在同一个 repo 的几个克隆之间来回切换吗？ 或者……你是不是每次 agent 会话都在新建一个 worktree，每次都丢失所有已安装的依赖和构建缓存，然后纳闷为什么你的 agent 这么慢？

Treehouse 可以帮你管理一个可复用、相互隔离的 worktree 池，这样你的每个 agent 都能立即获得自己的环境——无需克隆、无冲突、也没有协调开销。 - **即时隔离** — `treehouse` 能让你毫无负担地进入一个干净的 worktree。 - **可复用 worktree** — 当你完成任务后，worktree 会连同完整的依赖和构建缓存一起保留在池中，随时为下一个 agent 准备就绪。 - **无冲突** — 自动检测正在使用中的 worktree，确保你的 agent 之间绝不会互相干扰。 ## 快速开始 ``` $ cd myproject # start in your repo as usual $ treehouse # get a worktree and drop into a subshell 🌳 Entered worktree at ~/.treehouse/myproject-a1b2c3/1/myproject. Type 'exit' to return. # 你现在处于一个隔离的 worktree 中。 # 运行你的 AI agent，进行更改，做任何你需要做的事。 $ exit # exit the subshell when you're done 🌳 Terminated lingering processes: opencode (pid 12345) 🌳 Worktree returned to pool. ``` ## 安装 **macOS / Linux** ``` curl -fsSL https://kunchenguid.github.io/treehouse/install.sh | sh ``` **Windows (PowerShell)** ``` irm https://kunchenguid.github.io/treehouse/install.ps1 | iex ``` **Nix** ``` nix run github:kunchenguid/treehouse ``` 或者添加到你的 flake inputs 中： ``` treehouse = { url = "github:kunchenguid/treehouse"; inputs.nixpkgs.follows = "nixpkgs"; }; ``` **Go** ``` go install github.com/kunchenguid/treehouse@latest ``` **从源码构建** ``` git clone https://github.com/kunchenguid/treehouse.git cd treehouse make install ``` ## 工作原理 Treehouse 为每个 repo 管理**一个 git worktree 池**，存储在配置的 treehouse 根目录下。 默认的 treehouse 根目录是 `~/.treehouse/`。 ``` treehouse │ ▼ Find repo root │ ▼ git fetch origin │ ▼ ┌───────────────────────────────────────┐ │ Scan pool for available worktree │ │ (not leased, not in-use, not dirty) │ └──────────┬────────────────────────────┘ │ ┌────┴────┐ │ Found? │ └────┬────┘ yes/ \no / \ ▼ ▼ Reset to Create new worktree latest (detached HEAD at default latest default branch branch) & add to pool \ / \ / ▼ Spawn subshell in worktree (agent works here) │ ▼ exit subshell │ ▼ Terminate lingering worktree processes, reset worktree, & return to pool (ready for next agent) ``` - **Detached HEAD** — worktree 使用 detached HEAD 模式，并重置到本地或远程默认分支中最靠前的那个位置，从而完全避免分支名冲突。 - **无 daemon** — 所有操作都是内联 CLI 命令。没有后台进程，也没有会损坏的状态。 - **使用中检测** — treehouse 会扫描运行中的进程以及短暂的持有者预留记录，以确定哪些 worktree 正在使用中。预留状态仅在执行 `get`、`destroy` 和 `prune` 等生命周期任务时进行持久化。 - **持久租约** — `treehouse get --lease` 会将一个 worktree 预留为持久归属地，且不需要在其中保持进程运行。该租约会记录在 treehouse 自身的状态中，因此该 worktree 绝不会被随后的 `get` 分配出去，也绝不会被 `prune` 移除，直到你通过 `treehouse return` 释放它。与基于进程的使用中检测不同，即使 worktree 内部没有任何进程在运行，租约依然有效。 - **脏状态检测** — treehouse 会将已跟踪的修改和未跟踪的文件视为脏状态，即使 repo 配置在正常的 `git status` 输出中隐藏了未跟踪的文件。 - **安全清理** — 默认情况下，`treehouse prune` 仅移除那些 HEAD 已经合并到默认分支且工作树干净的空闲受管 worktree。 `treehouse prune --all` 会对用户级 treehouse 根目录下的每个受管池应用相同的安全检查。 默认情况下会报告缺失底层 repo 的孤立项；`--prune-orphans` 会将它们列为未经验证的清理候选对象，并且在删除前必须要求 `--yes`。 除非你传入 `--yes`，否则它将进行试运行。 ## CLI 参考 | 命令 | 描述 | | -------------------------- | ---------------------------------------------------- | | `treehouse` | 获取一个 worktree 并打开子 shell（`get` 的别名） | | `treehouse get` | 从池中获取一个 worktree | | `treehouse get --lease` | 持久租用一个 worktree 而不开启子 shell；打印其路径 | | `treehouse status` | 显示池状态（高亮显示已租用和当前的 worktree） | | `treehouse return [path]` | 释放任何租约，终止残留的 worktree 进程，并将其返回到池中 | | `treehouse prune` | 试运行移除当前 repo 池中陈旧的空闲 worktree | | `treehouse prune --all` | 试运行移除每个受管池中陈旧的空闲 worktree | | `treehouse destroy [path]` | 从池中移除一个 worktree | | `treehouse init` | 创建默认的 `treehouse.toml` 配置文件 | | `treehouse update` | 将 treehouse 更新到最新版本 | ### 标志 | 命令 | 标志 | 描述 | | --------- | --------- | --------------------------------- | | `get` | `--lease` | 持久租用 worktree 而不打开子 shell；仅将其路径打印到 stdout | | `get` | `--lease-holder` | 作为租约持有者记录的可选标签（默认为 `$TREEHOUSE_LEASE_HOLDER`） | | `return` | `--force` | 无需提示直接清理、重置并返回 | | `prune` | `--yes` | 删除列出的清理候选对象，而不是进行试运行 | | `prune` | `--all` | 扫描用户级 treehouse 根目录下的每个受管池 | | `prune` | `--global` | `--all` 的别名 | | `prune` | `--prune-orphans` | 将缺失底层 repo 的孤立项包含在清理候选对象中 | | `prune` | `--verbose`, `-v` | 显示详细的跳过诊断信息 | | `destroy` | `--force` | 即使正在使用或已租用，也强制销毁 | | `destroy` | `--all` | 销毁池中的所有 worktree | ### 租用 worktree（无子 shell） `treehouse get` 通常会打开一个交互式子 shell，其生命周期即为持有时间：当 shell 退出时，worktree 就会返回到池中。 对于需要一个作为永久归属地且内部没有长期运行进程的调用方来说，这很不方便。 `treehouse get --lease` 提供了一种非交互式、持久化的替代方案： ``` path=$(treehouse get --lease) # $path 是租用的 worktree 的绝对路径；所有 banner 都输出到了 stderr。 ``` 它的获取 worktree 的方式与 `get` 完全相同，但它不会打开子 shell，而是将 worktree 在 treehouse 的持久化状态中标记为**已租用**，并且仅将该 worktree 的绝对路径打印到 stdout（所有面向用户的消息都会进入 stderr，从而保证命令替换输出的纯净）。 只要租约没有被明确释放，无论其中是否有进程在运行，已租用的 worktree 就绝不会随后被 `get` 分配出去，也绝不会被 `prune` 移除。 此外，它还需要使用 `--force` 才能被 `destroy`。 传入 `--lease-holder `（或设置 `$TREEHOUSE_LEASE_HOLDER`）以记录谁持有该租约；随后 `treehouse status` 会在 `leased` 状态旁边显示它。 使用 `treehouse return ` 释放租约，这会清除租约、终止所有残留进程、重置 worktree 并将其返回池中。 当你传入明确的路径时，`treehouse return` 可以在 repo 外部运行，因为它会根据该 worktree 路径解析出对应的受管池。 ### 清理陈旧的 worktree 和孤立项 `treehouse prune` 默认为试运行。 默认情况下，它会列出将要被删除的陈旧空闲受管 worktree，并显示可回收的磁盘空间。 传入 `treehouse prune --yes` 即可删除这些 worktree。 默认情况下，清理仅检查当前 repo 的池，并且必须在 git repo 内部运行。 传入 `treehouse prune --all` 或 `treehouse prune --global` 即可从任意目录检查用户级 treehouse 根目录下的每个受管池。 全局清理会读取用户级的配置和 hooks，从 git 元数据中推导出每个 worktree 所属的 repo，然后针对该 repo 进行拉取并检查合并安全性。 不加 `--prune-orphans` 时，只需传入 `treehouse prune --all --yes` 即可仅删除全局安全的陈旧候选项。 清理会忽略当前正在使用、已租用或被其他生命周期操作预留的 worktree。 它会跳过那些不安全的空闲 worktree 并打印跳过原因，例如未提交的已跟踪或未跟踪的更改，或者尚未合并到默认分支的 HEAD commit。 跳过输出会按原因进行分组，以便在庞大的全局扫描中依然易于浏览。 当存在 `origin` 时，清理会拉取它，并根据当前远程默认分支的跟踪 ref 来验证每个 HEAD。 没有 `origin` 时，清理会使用本地默认分支的 ref。 如果无法访问 `origin`，清理会报告 `origin unreachable (cannot verify)` 并保留该 worktree 不动，即使设置了 `--prune-orphans` 也是如此。 如果链接的 worktree 指向了一个缺失的底层 repo，清理会报告 `orphaned (backing repository missing)`。 普通的 `treehouse prune` 和 `treehouse prune --all` 绝不会删除这些孤立项。 传入 `--prune-orphans` 将真正缺失底层 repo 的孤立项包含在试运行中，然后加上 `--yes` 将其删除。 由于底层 git 元数据丢失后，Treehouse 无法验证孤立项的内容，因此每个孤儿候选项都会被标记为 `content could not be verified`。 使用 `--verbose` 可以显示被跳过 worktree 的底层 git 诊断详细信息。 ## 配置 使用 `treehouse init` 创建一个 repo 配置文件，或者手动添加： **Repo 级别：** repo 根目录下的 `treehouse.toml` **用户级别：** `~/.config/treehouse/config.toml` ``` # 池中 worktree 的最大数量 max_trees = 16 # 可选的 worktree 根目录。 # 留空则使用 $HOME/.treehouse。 # 对于 repo 范围的命令，相对路径是从 repo 根目录解析的。 # 为 treehouse prune --all 使用绝对的用户级 root。 # root = "$HOME/worktrees" ``` 对于 repo 安全设置，repo 级别的配置具有优先权。 `treehouse prune --all` 可以在没有 repo 的情况下运行，因此它仅使用用户级配置，并且在扫描期间不会读取各个 repo 的 `treehouse.toml` 文件。 如果没有找到配置，默认的池大小为 16。 ### Hooks 你可以通过在 `~/.config/treehouse/config.toml` 的用户级配置中添加 `[hooks]` 部分，来在 worktree 生命周期的特定节点自动运行命令。 出于安全考虑，repo 级别 `treehouse.toml` 中的 Hooks 会被忽略。 ``` [hooks] post_create = ["./scripts/setup-venv.sh"] pre_destroy = ["./scripts/teardown.sh"] ``` - `post_create` 会在 worktree 被配置或重置之后，且在 `treehouse get` 将其交付给你之前运行。 对于 `treehouse get --lease`，`post_create` 的 stdout 会被重定向到 stderr，从而确保 stdout 始终是租用的路径。 - `pre_destroy` 会在 worktree 被 `treehouse destroy`、`treehouse destroy --all` 或清理删除命令（例如 `treehouse prune --yes` 和 `treehouse prune --prune-orphans --yes`）移除之前运行。 每个列表中的命令会通过 OS shell（Linux/macOS 上的 `/bin/sh -c`，Windows 上的 `%COMSPEC% /c`）在 worktree 目录中按顺序运行。 如果某个命令的退出码非零，treehouse 会记录该命令、退出码和 stderr，然后继续执行剩余的命令。 Hook 执行失败不会导致整个 `get`、`destroy` 或 `prune` 操作失败。 ## 开发 ``` make build # Build the binary make test # Run tests make lint # Run gofmt + go vet make dist # Cross-compile for all platforms make install # Install to $GOPATH/bin or /usr/local/bin make clean # Remove build artifacts ```

标签：AI工程, EVTX分析, Git, Python安全, SOC Prime, 安全可观测性, 工作树, 开发工具, 日志审计, 版本控制, 网络安全研究, 网络调试, 自动化