AI Coding 越来越快，但一个更难的问题也跟着浮出水面：
当 Agent 一口气调用几十次工具、修改十几个文件之后，我们该如何确认它做对了？如果结果不理想，能不能保留现场、比较多个方案，或者直接拒绝这次修改？
Shepherd 想解决的，正是这个问题。
可以把它理解成：给 AI Agent 用的“Git + 沙箱 + 审计日志 + 事务系统”。
它不是另一个和你对话、替你写代码的 Agent，而是运行 Claude、OpenAI 等模型驱动 Agent 的底层基础设施。
01｜它要改变的，不是模型，而是执行方式
普通 Coding Agent 往往直接在真实工作区里操作。成功时很方便，失败时却很难回答几个基本问题：
- Agent 到底调用了哪些工具、改了哪些文件？
- 能不能同时运行多个候选方案，再选择测试结果最好的一份？
- 能不能在确认之前完全不碰真实文件？
- 能不能从中间状态分叉、回退或重放？
- 如何限制 Agent 只能读某个仓库、写另一个仓库？
Shepherd 的核心思路，是把一次 Agent 执行也变成类似 Git commit 和 branch 的一等对象。
模型请求、工具调用、环境变化和文件修改会组成结构化的 execution trace。Agent 的产出先留在隔离工作区中，成为一份 retained output；你检查 changeset 之后，再决定接受、应用、释放或丢弃。
换句话说，Agent 不再“做完就算”，而是先提交一笔等待结算的候选事务。
02｜一次任务是怎样运行的
在 Shepherd 里，任务可以先被声明成一个没有函数体的 Python 函数。下面只是任务声明片段；实际运行还需要注册任务，并通过 workspace.run(...) 调用：
def fix_bug(repo: sp.GitRepo, issue: str) -> None:
"""定位并修复 issue 描述的问题。"""
这里的 docstring 是交给 Agent 的任务说明；repo: GitRepo 不只是类型标注，也表示这个任务获得了该仓库的权限。
随后，Shepherd 会把执行放进隔离环境：
- 创建隔离工作区；
- 让 Agent 在权限边界内调用模型和工具；
- 记录调用、轨迹与文件变化；
- 生成可检查的候选 changeset；
- 由人决定 select、apply、release 或 discard；团队也可以在外层 Python 中自建监督逻辑。
需要注意的是，后者不等于 v0.3.0 已经交付了论文设想中的完整 meta-agent 接口。自然的 task-to-task supervision 等能力，仍在官方 roadmap 上。
在 jail 模式下，权限会落到操作系统层：macOS 使用 Seatbelt，Linux 使用 Landlock。当前权限粒度主要是整个仓库的只读或读写，还不是任意目录级的通用安全沙箱。
03｜为什么这个方向值得关注
第一，它让 Best-of-N 变得自然。
同一个任务可以同时交给多个 Coding Agent，每个 Agent 在自己的隔离分支里工作。最后不必比较聊天记录，而是直接比较 changeset、测试结果和完整执行轨迹。
第二，失败不再只剩一句报错。
Agent 中途失败后，工作区和 trace 可以被保留下来，用于复盘、回归测试或评测数据采集。对需要审计的团队来说，这比“看模型最后说了什么”可靠得多。
第三，它给监督 Agent 一个可操作的对象。
监督者不只能评价最终答案，还可以观察执行过程、拒绝候选结果，或者要求 worker 从某个方向重试。论文把这一能力用于多 Agent 协作、工作流优化和 Agent 训练。
作者在 CooperBench 的 479 对任务上报告：没有监督者的协作基线通过率为 28.8%，使用 Opus 4.7 监督者后达到 54.7%。这里的数字是特定实验设置下的 pair pass rate，不是通用的“编码成功率”。
在论文选取的 Terminal-Bench 2.0 子集上，CRO 方法的得分从 31.2 提升到 35.2——绝对提升 4.0 个百分点，相对提升 12.8%；同时 wall-clock 从 173 分钟降到 73 分钟，约减少 58%。这些都是作者报告的结果，目前仍需要更多独立验证。
04｜但它并不是“所有操作都能撤销”
“可回退”是 Shepherd 最吸引人的想象之一，也最容易被夸大。
论文把副作用分成了不同类型：
- 文件系统和沙箱状态等 reversible effects，可以原生回退；
- 数据库写入等 compensable effects，需要开发者提供补偿处理；
- 模型调用、邮件发送等 irreversible effects，只能被记录和审计，不能真正撤销。
所以更准确的说法不是“Agent 的所有行为都能回滚”，而是：Shepherd 尽量让可逆的环境变化进入事务边界，并为不可逆动作保留清晰记录。
05｜论文愿景与当前产品，要分开看
截至 2026 年 8 月 10 日，PyPI 最新版本是 shepherd-ai 0.3.0。官方将它标为 early alpha，并把当前真正交付的核心称为一台 “settlement machine”。
目前相对完整的能力包括：
- 隔离运行和 retained output；
- 基于签名的权限与 named bindings；
- 可检查的 changeset 和 recorded trace；
- 对候选结果执行一次性的 select、apply、release 或 discard。
而论文中更完整的 meta-agent 体验，还没有全部进入公开版本。包括 task-as-value delegation、durable child agents、typed result projection，以及更自然的 task-to-task 调用，都仍在 roadmap 上。
此外，当前版本要求 Python 3.11+，支持 macOS 和 Linux；Windows 需要通过 WSL。鉴于它仍是 early alpha、API 还可能变化，我们不建议把它当作稳定的生产依赖。
06｜我们的判断
Shepherd 最值得关注的，不是又多了一个 Agent 框架，而是它重新定义了 Agent 的“执行结果”。
结果不再只是一段回答，也不只是写进工作区的一堆文件；它是一份包含权限、轨迹、环境变化和候选修改的可检查对象，必须经过明确结算，才进入真实世界。
如果你的目标是安装一个成熟的多 Agent 框架，马上承载生产工作，它现在还不合适。
但如果你在做 Coding Agent 基础设施、Agent 评测、Best-of-N、审计或强化学习，Shepherd 提供了一套很有价值的设计语言：
让 Agent 的修改先成为可检查、可拒绝的候选事务，而不是直接落进真实工作区。
模型能力继续增长之后，真正稀缺的可能不再是“让 Agent 多写一点”，而是让它的每一步都可观察、可约束、可结算。