如何为Agent代码写可靠的测试？Shepherd离线确定性测试实践-平芜编程栈

如何为Agent代码写可靠的测试？Shepherd离线确定性测试实践

【免费下载链接】shepherdA runtime substrate that turns an agent's execution into a reversible, Git-like trace, so meta-agents can observe, fork, replay, and revert any run. Couples agent and environments in a copy-on-write fork ~5x faster than docker commit, with ~95% KV-cache reuse on replay. Framework built for meta-agents to supervise, optimize, and train other agents项目地址: https://gitcode.com/gh_mirrors/shepherd16/shepherd

Shepherd 是一个把 Agent 执行过程变成可逆、类 Git 执行轨迹（trace）的运行时底座，支持观察、fork、重放与回退任意一次运行。而 Shepherd 离线确定性测试正是解决「Agent 代码难以测试」这一痛点的核心实践：无需网络、无需 API 密钥、无需花钱，每次运行都得到完全一致的结果，让 CI 里的 Agent 测试告别 flaky（不稳定）。

为什么 Agent 代码的测试这么难 🤔

如果你写过基于大模型的 Agent，大概率遇到过这些问题：

痛点	后果
输出随机	每次断言都可能失败，测试形同虚设
依赖网络与 API 密钥	测试环境配置复杂，密钥泄露风险
调用计费	CI 每跑一轮都在烧钱
环境差异	模型版本、温度、上下文都会改变结果

传统做法是用 mock 模拟模型返回，但 mock 得越多，测试就越偏离真实行为。Shepherd 的思路不同：它把「离线确定性 provider」做成一个一等公民 provider——不是为测试临时糊上的假模型，而是像真实 provider 一样被选择、被调用，只是回答来自录制好的转录（transcript）。

核心机制：离线 provider + 可逆执行轨迹

Shepherd 中，任务（task）只声明「想要什么」——类型化的契约和 docstring，从不在代码里指定「谁来回答」。由 workspace 统一选择 provider：

import shepherd as sp with sp.workspace(model="claude:sonnet-4-5"): ... # 这里面的每次任务调用都由同一个 provider 应答

文档与 CI 默认使用离线确定性 provider（在 retained run 中它叫static）：调用不读任何凭证、不发出任何网络请求，答案由录制的转录重放。官方文档里所有示例都跑在它上面，「你读到的就是运行到的」。

同时，Shepherd 把每次运行记录为持久的执行轨迹：workspace 基于写时复制（copy-on-write）fork，Agent 的产物以「retained output（保留输出）」形式暂存在一旁，供你先检查、再决定select（采纳）、apply（合并）还是discard（丢弃）。这个可逆性正是可靠测试与可恢复运行的基础。

实践一：测试与程序走完全相同的调用路径 ✅

写测试时，用和生产程序完全一样的方式调用任务：在 workspace 里打开离线 provider，然后在测试体内调用任务。这样测的就是真实运行路径，而不是一个孤立的 mock。官方 quickstart 的最小示例 hello.py 连续跑两遍，输出的 review 逐字符相同——确定性本身就是目标。

实践二：断言类型化返回值，而不是解析文本

任务声明了返回类型，Shepherd 会把模型回答强制转换为该类型再交给你。测试因此可以直接读字段：

def test_triage_matches_contract(): with sp.workspace(model="claude:sonnet-4-5"): triage = triage_change(SAMPLE_DIFF) assert isinstance(triage, Triage) assert (triage.category, triage.priority) == ("bugfix", "high")

返回类型就是契约。没有 JSON 解析、没有正则刮字符串，契约变了测试立刻红。若回答无法转成声明的类型，会得到明确的sp.DeliveryFailed，而不是一个模棱两可的坏字符串。

实践三：把失败契约也纳入测试 🧪

Shepherd 的类型化失败同样是行为的一部分，值得逐个钉住：

sp.DeliveryFailed：录制答案无法转成声明的返回类型——说明返回类型或 docstring 契约已经漂移，收紧类型再跑。
RuntimeError（workspace 相关）：任务在with sp.workspace(...)之外被调用。Shepherd 没有「隐藏的默认模型」，无 workspace 立即失败，而不是偷偷回退。

这两类断言能抓住绝大多数「悄悄变坏」的场景。

实践四：让 CI 直接运行文档里的示例 🚀

Shepherd 的文档本身就是被测试的。看 test_hello.py 的做法：CI 测试直接把hello.py当作真实脚本跑一遍，再断言文档承诺的输出片段确实被打印——文档展示什么，测试就运行什么，杜绝文档与实现脱节。

更进一步，test_world_hero.py 验证的是「执行证据」：它在真实安装环境中新建一个shepherd init工作区，把发布页面里逐字节相同的 hero 代码片段作为真正的__main__脚本运行，断言输出包含['NOTE.txt']和预期文本。这意味着用户照着文档敲的每一行，都在 CI 里被原样执行过。

实践五：用可逆轨迹重放失败运行，而非盲目重试

当一次运行失败或产物不合预期时，Shepherd 的轨迹让你可以精确回到失败现场：检查 retained output 想改什么、读取它的变更内容、然后 select/discard/apply。重放时离线 provider 保证结果逐字节一致，配合写时复制 fork（比 docker commit 快约 5 倍）和重放时约 95% 的 KV-cache 复用，「复现—定位—重试」循环的成本极低。相关的视觉化恢复示例可在 visual_artifact 示例集中查看。