如何为Agent代码写可靠的测试Shepherd离线确定性测试实践【免费下载链接】shepherdA runtime substrate that turns an agents 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/shepherdShepherd 是一个把 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 统一选择 providerimport shepherd as sp with sp.workspace(modelclaude:sonnet-4-5): ... # 这里面的每次任务调用都由同一个 provider 应答文档与 CI 默认使用离线确定性 provider在 retained run 中它叫static调用不读任何凭证、不发出任何网络请求答案由录制的转录重放。官方文档里所有示例都跑在它上面「你读到的就是运行到的」。同时Shepherd 把每次运行记录为持久的执行轨迹workspace 基于写时复制copy-on-writeforkAgent 的产物以「retained output保留输出」形式暂存在一旁供你先检查、再决定select采纳、apply合并还是discard丢弃。这个可逆性正是可靠测试与可恢复运行的基础。实践一测试与程序走完全相同的调用路径 ✅写测试时用和生产程序完全一样的方式调用任务在 workspace 里打开离线 provider然后在测试体内调用任务。这样测的就是真实运行路径而不是一个孤立的 mock。官方 quickstart 的最小示例 hello.py 连续跑两遍输出的 review 逐字符相同——确定性本身就是目标。实践二断言类型化返回值而不是解析文本任务声明了返回类型Shepherd 会把模型回答强制转换为该类型再交给你。测试因此可以直接读字段def test_triage_matches_contract(): with sp.workspace(modelclaude: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 契约已经漂移收紧类型再跑。RuntimeErrorworkspace 相关任务在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 示例集 中查看。快速上手清单pip install shepherd-ai要求 Python 3.11Windows 请用 WSLmkdir demo cd demo shepherd init把目录变成 Shepherd 工作区编写任务函数签名 docstring 即契约测试中用sp.workspace(model...)固定离线 provider断言类型化返回值把文档示例本身纳入 pytest让 CI 跑文档延伸阅读测试指南test-shepherd-code.md确定性演示deterministic-demo.mdprovider 概念离线 provider 是一等公民providers.md离线 quickstart 示例offline_task.py文档系统的「跑文档即测试」实现test_docs_system.py项目总览与离线快速开始README.md【免费下载链接】shepherdA runtime substrate that turns an agents 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
