agentenv 是一个沙箱工具。AI Agent 在里面干活时，环境会自动保存每一步的快照。搞砸了？一条命令就能回到之前任意一个"存档点"，就像游戏里的存档/读档。
Agent 本身完全不需要做任何适配——它甚至不知道 agentenv 的存在。
AI Agent 在执行编程任务时，经常需要安装依赖、修改配置文件、执行 shell 命令。这些操作有可能把环境搞坏——装错了包、改坏了配置、执行了有副作用的命令。
传统方案是重建整个环境，代价很高。agentenv 的做法是：环境随时可以"倒带"回去，就像录像机的回放功能。
每次文件系统发生变化（不管是 Agent 执行命令还是手动编辑文件），agentenv 都会自动拍一个快照。快照是只读的，保存了那个时刻文件系统的完整状态。
你可以把它想象成 Git 的 commit，但记录的不是代码仓库，而是整个操作系统的文件系统。
回滚就是"读档"：把文件系统恢复到某个快照的状态，同时终止环境内的所有进程，然后重新启动 Agent。
什么能回滚：文件系统的一切——安装的软件、配置文件、临时文件。
什么不能回滚：已经发出去的网络请求、已经过去的时间。发出去的 HTTP 请求收不回来。
当需要尝试多个方案时，agentenv 可以同时开 N 个独立的环境副本，每个副本跑一个候选方案并执行测试，自动保留第一个通过测试的方案。
类似于同时开 N 个平行世界，选最好的那个。
agentenv 分三层，Agent 只感知到最里面一层：
┌─────────────────────────────────────────────────────┐
│ 第 1 层：启动器（Launcher） │
│ 负责创建沙箱，只在启动时运行一次。 │
│ 实际就是 docker run 或 k8s pod 的启动命令。 │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 第 2 层：管理者（Supervise） │ │
│ │ 常驻后台进程。负责监控文件变化、自动拍快照、 │ │
│ │ 执行回滚。它自己永远不会被回滚。 │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ 第 3 层：内部环境 │ │ │
│ │ │ Agent 实际运行的地方。 │ │ │
│ │ │ Shell、软件包、Agent 进程，都在这里。 │ │ │
│ │ │ 回滚 = 杀掉这里的进程 + 恢复文件系统。 │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
为什么要分层？因为"管理回滚的人"不能自己也被回滚，否则就没人来执行恢复操作了。所以管理者（第 2 层）始终待在安全区，只有内部环境（第 3 层）会被回滚。
agentenv 支持两种方式来管理快照，启动时自动选择合适的那个：
| copy 模式（默认） | btrfs 模式 | |
|---|---|---|
| 适用场景 | 大多数环境，包括受限的 K8s Pod | 有 root 权限且使用 btrfs 文件系统 |
| 是否需要 root | 不需要 | 需要 |
| 快照速度 | 通过硬链接共享不变的文件，只复制有变化的部分。如果文件系统支持 reflink（如 XFS、ZFS），速度接近瞬时 | 瞬时（利用 btrfs 的写时复制） |
| 编译方式 | 默认，纯 Go 静态编译 | 需要加 -tags btrfs，依赖 cgo |
简单理解：copy 模式就像"复制文件夹但跳过没改的文件"，btrfs 模式就像"文件系统帮你管理副本，改了才占空间"。
/agentfs/ ← 默认根目录
├── nodes/ ← 所有快照存在这里
│ ├── abc123/ ← 快照 1（只读）
│ └── def456/ ← 快照 2（只读）
├── work/current/ ← Agent 当前工作的目录（可读写）
├── meta.json ← 快照之间的关系（谁是谁的父节点）
├── agentenv.sock ← 管理用的通信接口
└── agentenv.lock ← 防止多个进程同时操作
| 命令 | 做什么 |
|---|---|
agentenv init --from <目录> |
从一个已有目录创建初始环境 |
agentenv init --tarball <文件> |
从压缩包创建初始环境 |
agentenv init --sync --from <目录> |
增量同步：把目录中新增的文件合并进来 |
agentenv export |
把环境导出为 tar 包（可以给 docker import 用） |
agentenv import <文件> |
导入一个环境包 |
| 命令 | 做什么 |
|---|---|
agentenv supervise -- <命令> |
启动 Agent 并自动管理快照和回滚 |
agentenv daemon |
启动后台守护进程，通过 socket 接受管理命令 |
agentenv mcp |
启动 MCP 服务器，让 Claude Code 等工具通过 MCP 协议来管理环境 |
agentenv exec -- <命令> |
在环境内执行一次性命令（适合脚本和 CI） |
| 命令 | 做什么 |
|---|---|
agentenv commit -m "说明" |
手动创建一个快照（通常不需要，系统会自动创建） |
agentenv checkout <快照ID> |
回滚到指定快照 |
agentenv tag <名字> <快照ID> |
给快照取一个好记的名字 |
agentenv log |
查看快照历史 |
agentenv status |
查看当前环境状态 |
agentenv diff |
查看当前环境和某个快照的差异 |
agentenv gc |
清理不再需要的旧快照，释放磁盘空间 |
| 命令 | 做什么 |
|---|---|
agentenv tournament --test "测试命令" -- "方案1" "方案2" |
并行尝试多个方案，自动选出通过测试的那个 |
agentenv ctl <操作> |
在 Agent 运行时从外部发送管理命令（不会打断 Agent） |
当执行 checkout 回滚时，实际发生的事情：
- 终止进程 — 杀掉内部环境里所有正在运行的程序
- 恢复文件系统 — 从目标快照还原
work/current目录 - 更新指针 — 把 HEAD 指向目标快照，安全写入元数据
- 重启 Agent — 如果在
supervise模式下，自动从恢复后的环境重新启动 Agent
整个过程中，管理者进程（supervise）始终在线，不受影响。
- 网络操作不可逆：已发出的 API 请求、已发送的消息无法撤回，这是物理限制
- 不是安全隔离：agentenv 提供的是环境隔离，不是安全沙箱。如果要运行不信任的代码，应该再套一层虚拟机
- Linux 限定：核心功能依赖 Linux 命名空间，macOS 上只能编辑代码，实际运行需要 Linux 环境
- 受限环境的额外要求：在某些安全策略较严格的 Linux 环境（如 Ubuntu 22.04+ 的 AppArmor）中，可能需要额外放宽安全策略才能运行