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/shepherdAgent 流水线跑到一半跑偏了开源项目Shepherd是一个 Agent 执行运行时底座runtime substrate它把 Agent 的每次执行记录成可逆的、类 Git 的执行轨迹reversible execution trace——当多步流水线中某一步出错时你不需要从头重跑整条流水线而是基于轨迹找到最后的安全边界做边界重试boundary retry失败的执行还会原样保留为证据。本文用 Shepherd 仓库自带的可视化案例带你完整走一遍发现跑偏 → 诊断 → 从边界重试 → 结算的恢复流程。为什么一步跑偏这么难处理一条典型的 Agent 流水线是串行的规划plan→ 起草draft→ 审查review→ …。麻烦在于错误会向下污染中间一步产出了错误结果后面每一步都建立在这个错误之上越往后修复越贵。传统补救很粗糙要么整条流水线从头重跑浪费已完成步骤的成本要么直接在已有输出上打补丁输出变成黑盒无法审计。失败现场会丢失重跑之后当时到底哪里错了只剩下记忆和碎片日志复盘无从谈起。Shepherd 的思路是把每一次执行本身变成一份持久、可检查的记录run失败的 run 不是信息的缺失而是更多信息——失败前发生的一切都被完整保留见 docs/shepherd/concepts/runs.md。Shepherd 的四个关键概念概念作用Run运行一次执行的完整记录结果、轨迹、产物、成本四种结局成功/失败/预算耗尽/被取消都有据可查Trace轨迹所有边界跨越的有序记录——每个模型请求、每次任务调用、每个产物输出调试变成读记录而不是猜Artifact保留产物任务执行中保留的输出以引用ref形式流转可被后续步骤只读引用Settlement结算显式处置select保留、apply合并、discard丢弃、release释放底层机制上Shepherd 通过 copy-on-write fork 把 Agent 和执行环境耦合在一起比 docker commit 快约 5 倍replay 时可复用约 95% 的 KV-cache——这让重试这件事在成本上真正可行。上图为 UC3 案例中跑偏的草稿本应向下走向极小值的更新路径被画成了上坡完整说明见 examples/notebooks/visual_artifact/README.md实战案例当流水线中间步骤跑偏时Shepherd 仓库内置了一个确定性的可视化案例UC3 Pipeline Recovery位于 examples/notebooks/visual_artifact/notebooks/visual_pipeline_recovery.ipynb。任务是绘制一张梯度下降信息图流水线为plan规划✅ 正常→ 产出plan.jsondraft-v1起草❌ 跑偏→ 方向画反review审查→ 标记问题inspector诊断→ 读取审查结论输出结构化诊断retry重试→ 一个新 run引用保留的 plan 产物重新起草第一步定位最后的安全边界恢复的核心是回答从哪里开始重试案例中审查发现的缺陷只出现在 draft 这一步而 plan 是干净的——所以重试边界就是plan 之后、draft 之前。恢复计划的分类逻辑在 examples/notebooks/visual_artifact/shepherd_usecases/visual_artifact/recovery_core.py 中RecoveryPlan结构给出五个关键字段failure_type: wrong_direction # 失败类型方向错误/结构损坏/渲染问题 bad_step: draft # 坏在哪一步 evidence: … # 证据产物路径 审查问题 retry_boundary: after plan, before draft # 重试边界 recommended_change: … # 重试时的修正指令同时把 plan 的产物登记为引用它是重试要站上去的地基plan_ref launch.artifact_ref(plan_run, launch.PLAN_PATH, labelretry-plan)第二步重试是一个新 run而不是改旧输出这是 Shepherd 恢复模型最重要的一点重试不是往已有输出里写分支而是一个全新的 run通过产物引用artifact ref因果地连接上下文中的一切retry launch.run_with_artifact_refs( workspace, nameretry, refs{plan: plan_ref, diagnosis: diagnosis_ref}, # 只读引用 plan 与诊断 after[plan_run, inspector], # 声明因果链 output_textlaunch.draft_html(brief, corruptFalse), # 修正后的输出 )after[plan_run, inspector]让工作区轨迹记录下了这次重试因果上紧随失败的 draft 与 inspector。而那个失败的 draft-v1原封不动地留在原地当证据——你可以随时对比两次输出。上图为重试前后对比左侧draft v1被标记 discard丢弃右侧run retry引用保留的计划产物后产出正确方向并被 select选中第三步用结算settlement把决策写进记录最后一步是把人类/审查者的决策显式化——丢弃坏的、释放辅助 run、选中好的draft_v1.output().discard() # 丢弃失败草稿记录保留 plan_run.output().release() # 释放 plan 输出 reviewer.output().release() inspector.output().release() retry.output().select() # 选中重试结果对应地CLI 侧也有同样的操作面见 README.md 的 Quickstart 部分shepherd run select run-ref # 保留 shepherd run apply run-ref # 合并到已前进的工作区 shepherd run discard run-ref # 丢弃 shepherd run trace run-ref # 读该 run 的完整轨迹上图为重试成功的输出更新路径正确地沿下坡方向逐步走向极小值最后workspace.flow会给出整条流水线的可视化轨迹——plan、draft_v1、review、inspector、retry 五个节点及其因果连线一目了然包括plan_run与inspector指向retry的那条恢复边。边界重试最佳实践清单 先分类再重试像RecoveryPlan那样先判定失败类型方向错误 / 结构损坏 / 渲染问题不同类型对应不同的修正指令避免盲目重跑。重试边界要选在最后一步干净输出之后案例中是 plan 之后。边界太靠后 带着错误重试太靠前 浪费已完成工作。重试永远是新 run 只读引用通过 artifact ref 引用上游产物用after[...]声明因果链绝不直接改写旧输出。保留失败现场失败的 run 不删除它是诊断证据也是后续对比、审计、训练 meta-agent 的数据源。决策必须显式结算select/discard/release写进记录让为什么留下这个、丢掉那个成为轨迹的一部分而不是口头约定。延伸阅读仓库内路径完整恢复案例 notebookexamples/notebooks/visual_artifact/notebooks/visual_pipeline_recovery.ipynb恢复分类与重试计划实现recovery_core.py案例说明与运行方式examples/notebooks/visual_artifact/README.md直到可接受的重试示例循环重试工作区句柄examples/workspace-handles/retry_until_acceptable.pyrun / trace / artifact 概念文档docs/shepherd/concepts/runs.md工作区句柄示例总览examples/workspace-handles/README.md一句话总结在 Shepherd 里流水线跑偏不再是灾难——轨迹记住了每一步边界重试只重做坏掉的那一段而失败的执行永远留在轨迹里当证据。这就是可逆执行对多步 Agent 流水线的意义。【免费下载链接】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），仅供参考