用Shepherd构建第一个可逆Agent应用30分钟两任务代码审查器实战教程【免费下载链接】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想用 Shepherd 做一个真正可逆的 Agent 应用吗本教程带你用 30 分钟构建一个两任务代码审查器第一个任务只读审查代码第二个任务把修复写进仓库——但所有改动都先成为可回滚的保留输出retained output你可以随时查看、选择、应用或丢弃你的文件在被批准之前不会被改动。Shepherd 是什么它是一个 Agent 运行时底座把 Agent 的每次运行记录成持久、可检查的执行轨迹reversible execution trace工作区改动以写时复制方式分叉比 docker commit 快约 5 倍重放时还能复用约 95% 的 KV-cache。详见 README.md。⏱️ 30分钟路线图时间你将会完成0–5 分钟安装 Shepherd 并初始化工作区5–15 分钟编写只读审查 可写修复两个任务15–25 分钟运行代码审查器产出保留输出25–30 分钟检查执行轨迹并结算select / discard准备工作5分钟安装 ShepherdShepherd 要求Python 3.11支持 macOS 与 LinuxWindows 请使用 WSL。安装只需一条命令pip install shepherd-ai然后初始化你的第一个 Agent 工作区以代码审查器为例mkdir my-reviewer cd my-reviewer git init shepherd init # 把当前目录变成 Shepherd 工作区 没有 API key 也没关系Shepherd 提供确定性离线 Provider可先跑 examples/quickstart/offline_task.py 感受保留输出机制完全免费。第一步30秒看懂两任务设计我们的代码审查器包含两个任务对应 Shepherd 的核心思想——函数签名就是权限面Task 1 · 只读审查用只读句柄打开 Git 仓库输出结构化审查结论工作区保证零改动✍️Task 2 · 可写修复拿到读写授权把修复代码写进仓库——但改动不会直接落盘而是作为候选保留等你结算。参考实现就在仓库里只读审查场景见 shepherd/examples/scenarios/review_code.py它用 git diff 做分支审查并产出 findingsAgent 写文件场景见 examples/quickstart/agent_task.py。第二步编写只读代码审查任务只读任务的关键是签名里的May[GitRepo, ReadOnly]——在受沙箱约束的设备上任何越权写入会在操作系统级系统调用层被直接拒绝而不是事后提醒。权限细节可查 docs/shepherd/concepts/permissions.mdimport shepherd as sp def review_branch(repo: sp.May[sp.GitRepo, sp.ReadOnly], branch: str) - None: 只读审查 branch 相对 main 的改动 输出问题清单与 approve / request_changes 建议。函数没有函数体——运行时由 Agent 来履行契约docstring 就是任务说明书。第三步编写可写修复任务权限即签名第二个任务声明May[GitRepo, ReadWrite]表示它对绑定仓库拥有整仓读写授权def apply_fix(repo: sp.May[sp.GitRepo, sp.ReadWrite], branch: str) - None: 根据审查结论修复代码。 改动先保留为候选等你选择后才真正生效。✅新手要点repo: sp.GitRepo是简洁写法等价于读写授权无注解的repo参数只是普通参数不是句柄。想看最佳N选一的多候选玩法见 examples/workspace-handles/best_of_n.py。第四步运行两任务代码审查器注册两个任务并依次运行placementjail表示在原生系统调用沙箱macOS Seatbelt / Linux Landlock中执行with sp.open(.) as ws: ws.tasks.register(review_branch, task_idapp.review) ws.tasks.register(apply_fix, task_idapp.fix) run1 ws.run(app.review, repows.git_repo(), branchfeature/login, placementjail) run2 ws.run(app.fix, repows.git_repo(), branchfeature/login, placementjail) print(保留改动, run2.output().changeset().changed_paths)跑完之后你的工作区里什么都没变——修复结果被安全地留在一边这正是可逆执行的价值。第五步审查与结算——选择、应用或丢弃这是 Shepherd 的结算词汇表也是教程标题中可逆的落点shepherd run show --latest # 查看完整运行记录 shepherd run changeset --latest # 查看候选改了什么 shepherd run select run-ref # 保留它写入工作区 shepherd run apply run-ref # 三方合并到已前进的工作区 shepherd run discard run-ref # 不要了轨迹仍会记住无论保留还是丢弃执行轨迹都完整持久化meta-agent 可以观察、分叉、重放、回滚任何一次运行。进阶玩法重试直到合格真实审查往往一次过不了关。Shepherd 支持拒绝一次 → 重试 → 保留合格候选的循环第一次不合格的输出直接discard第二次合格后再select全程可审计。官方示例 examples/workspace-handles/retry_until_acceptable.py 展示了完整流程。延伸阅读项目里的相关资料 运行概念详解docs/shepherd/concepts/runs.md 工作流指南run-a-workflowdocs/shepherd/guides/run-a-workflow.md PR Review 工作流docs/shepherd/workflows/authoring/pr-review.md 只读分析场景shepherd/examples/scenarios/readonly_analysis.py 修复 Bug 场景shepherd/examples/scenarios/fix_bug.py想浏览完整示例克隆仓库即可git clone https://gitcode.com/gh_mirrors/shepherd16/shepherd❓ 常见问题Q必须配置 API key 才能开始吗不需要。离线 Quickstart 用确定性 Provider 跑同一套保留输出机制见 examples/quickstart/README.md。Q我的文件会被 Agent 改坏吗不会直接改。可写任务的产出都是保留输出只有你执行select/apply之后才生效只读任务在 OS 层面就无法写入。Q30分钟够用吗示例脚本本身运行时间取决于 Agent 响应官方 Agent 演示约 1 分钟。若只是熟悉机制离线模式几分钟即可跑通。⭐下一步建议把上面的两任务审查器接到你自己团队的 PR 流程里——审查、修复、回滚全部有迹可循。【免费下载链接】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），仅供参考
