为什么 treehouse 没有守护进程：worktree 管理工具的安全优先与无状态设计指南-开发者社区

【免费下载链接】treehouse

Manage worktrees without managing worktrees.

项目地址：https://gitcode.com/gh_mirrors/treehou/treehouse

treehouse 是一款面向 AI 编码代理的 Git worktree 池管理工具，它用"零守护进程 + 无状态 CLI"的架构，让你一条命令就能获得隔离、可复用的工作目录环境。本文将从安全优先与无状态设计两个角度，讲清楚它为什么坚决不做后台常驻服务。

🌳 treehouse 是什么：先弄懂"worktree 池"

如果你用过git worktree，大概知道痛点：每个代理会话都要新建 worktree、重新装依赖、重建缓存，慢得心疼。treehouse 把一堆 worktree 组成一个池（pool）：

代理来了，从池里"领"一个干净环境，秒进；
干完活退出子 shell，环境自动清理、归还，留给下一个代理复用；
全程treehouse一条命令进入、exit返回，不需要你手动管理 worktree。

官方定位一句话就是：Manage worktrees without managing worktrees.

为什么不用守护进程：无守护 CLI 设计的 3 个理由

很多工具喜欢做一个常驻后台服务来"记住"状态。treehouse 的设计文档里写得很直白：

No daemon — all operations are inline CLI commands.（无守护进程 —— 所有操作都是内联 CLI 命令。）

这条不变式记录在 docs/design.md 的开头，是项目的核心原则。背后的理由可以拆成三层：

1. 没有"总在跑"的东西，就没有可攻击的运行时守护进程意味着一个长期存活的进程：它占内存、持有状态、可能监听端口，出问题时要查它的日志和崩溃转储。而 treehouse 的每个命令（get、status、prune…）执行完就退出，不留下任何后台实体。跨 macOS / Linux / Windows 三平台时，也完全省掉了"服务怎么装、怎么开机自启"的烦恼。

2. 状态不在内存里，就不会被"悄悄改坏"守护进程的状态通常只存在于进程内存中，进程一死状态就丢，或者进程升级后新旧状态打架。treehouse 把池状态放在磁盘上一个小小的状态文件treehouse-state.json里——状态即文件，文件即事实。你随时可以用cat看它，也随时可以用treehouse status看它。

3. 愿景层面的明确拒绝项目的 VISION.md 甚至把"拒绝守护进程"写成了评审标准：

当一项变更会……使 daemon 或托管服务成为必需、用安全性换取便利性时，应该被抵制。

也就是说，这不是"暂时没做"，而是"永远不该做"。

没有进程，状态放哪？——一个小状态文件 + 文件锁

无守护设计的关键问题是：并发安全谁来保证？答案在 internal/pool/state.go：

文件锁串行化：所有命令读写状态前，先通过WithStateLock拿到池目录下的锁文件。Unix 平台用flock排他锁（见 internal/pool/lock_unix.go），Windows 有对应实现（internal/pool/lock_windows.go）。同一时刻只有一个命令能改状态，等效于守护进程内部互斥，但零常驻成本。
原子写入：状态文件永远走"写临时文件 → fsync → 原子替换"的路径（WriteState/atomicWriteFile）。写一半崩溃也不可能留下半截文件，崩溃只会让你看到"新的完整文件"或"旧的完整文件"，没有第三种情况。

崩溃了怎么办：无状态设计的自恢复兜底

无守护工具最怕"意外死机后世界变脏"。treehouse 的做法是fail closed（保守失败）：

如果状态文件损坏、被截断或丢失，命令不会直接报错罢工，而是扫描池目录里真实存在于磁盘上的 worktree，把每一条恢复成leased（已租出）并隔离，附上一条人话提示：

recovered: state file was corrupt or truncated; verify before reuse

隔离意味着：get不会再把它发出去，prune不会删它，只有你检查确认后、用精确路径加--include-leased --yes才能移除。在"状态不明"时宁可不用，也绝不冒进——这正是安全优先哲学的落地细节。

🔒 安全优先：无守护 + 无状态带来的 4 重保护

这套设计不是白付成本的，它换来了实打实的安全性：

保护层	具体机制
无运行时攻击面	无常驻进程、不监听端口、不持有长期凭证
仓库配置不可执行	仓库级`treehouse.toml`中的 hooks 一律被忽略——在不受信任的 clone 里运行 treehouse，不可能自动执行仓库里藏着的 shell 脚本（只有用户级配置可定义生命周期 hooks）
状态防伪	种子文件清单用 HMAC 摘要写入状态文件；worktree 里的文件被篡改无法绕过校验，验证失败即隔离
删除永远双确认	`prune`/`destroy`默认 dry-run，每类风险（未合并、使用中、已租出）各需独立 opt-in 标志；旧版一刀切的`--force`已被彻底移除

简单说：攻击者拿到的最多是一个文件，而不是一个活着的进程。

权衡时刻：这种设计的代价是什么？

公允地讲，无守护也有取舍，理解它才能选对工具：

每次命令都要现查进程表：判断 worktree 是否"占用中"靠实时扫描系统进程（internal/process/detect.go），而不是问守护进程要缓存。换来的是永远"所见即真"，代价是多一点 CPU 开销。
没有内存态智能：池的"聪明"全靠文件 + 锁 + 磁盘扫描重建，逻辑复杂度更高（状态文件要带版本号、键文件、HMAC），但换来的是可移植、可审计、可崩溃恢复。
它不是沙箱：VISION.md 明确 treehouse 隔离的是工作目录和生命周期归属，不替代系统级安全边界。