企业官网建设流程全解析

两个直接可用的Meta-Agent模式：Shepherd实现 best_of_n 与 retry-until-acceptable 实战

【免费下载链接】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是一个为 Meta-Agent（元代理）设计的运行时底座：它把 Agent 的每次执行记录成可逆、可 fork 的 Git 式执行轨迹，让上层 Meta-Agent 能够观察、比较、回滚任意一次运行。围绕"Agent 输出不可预测"这一痛点，仓库内置了两个开箱即用的 Meta-Agent 决策模式——**best_of_n（多候选择优）**与retry-until-acceptable（重试直到可接受），本文带你读懂它们的工作原理并直接跑起来。

为什么 Meta-Agent 需要这两种模式

大模型 Agent 的输出天然带有随机性：同一个任务跑三次，结果可能完全不同。Meta-Agent 要监督、优化、训练下层 Agent，就必须回答两个经典问题：

1. 多个候选结果，留哪一个？→best_of_n
2. 结果不合格，如何修正并再来一次？→retry-until-acceptable

在传统方案里，你只能拿到一个"最终文件"，无法比较、无法回退。Shepherd 把每次运行变成一份保留输出（retained output）：候选结果被安全地"扣"在一旁，你可以审查它的变更集（Changeset），满意才合入，不满意就丢弃，而整个过程的痕迹都记录在可查询的 trace 里。

模式一：best_of_n —— 跑 N 个候选，用证据选出赢家

best_of_n的核心流程只有四步：

• 并行生成 N 个候选：同一个任务从同一仓库起点 fork 出 N 份副本分别执行，互不干扰；
• 保留全部输出：每个候选的结果都不直接落盘，而是作为保留输出被托管；
• 用 Changeset 评判：Meta-Agent 通过每个候选的变更集（改了哪些文件、写了什么内容）打分，而不是盲信返回值；
• 结算（Settlement）：赢家执行select合入工作区，落选者显式release或discard。

在示例 examples/workspace-handles/best_of_n.py 中，"候选生成任务"被注册进工作区，随后三个候选（alpha/winner/omega）各自带着分数写入candidate.txt，Meta-Agent 读取变更集中的内容打分并选出最高分：

# 同一任务 fork 出 N 个保留候选，placement="auto" 记录真实隔离级别 runs = [ task.run(repo=copy_git_repo(repo), label=label, score=score, placement="auto") for label, score in (("alpha", 10), ("winner", 99), ("omega", 20)) ] winner = max(outputs, key=lambda o: review[o.output_id]["score"])

评判与结算发生在 best_of_n.py#L46-L59：

selection = workspace.select(winner) # 赢家合入 released = workspace.release(losers[0]) # 落选者释放 discarded = workspace.discard(losers[1]) # 落选者丢弃

下图来自仓库的可视化示例（examples/notebooks/visual_artifact/）：同一任务 fork 出两个变体，左侧 contour-map 变体通过评审被保留（retained），右侧 uphill-path 变体因方向错误被拒绝并丢弃——这正是 best_of_n"保留全部、择优结算"的画面化呈现。

模式二：retry-until-acceptable —— 不合格就释放，修正后重跑

retry-until-acceptable解决的是另一个问题：候选输出不合格时如何优雅地重来。它的循环是：

1. 跑一次，得到保留输出；
2. 检查输出内容（本例通过 Changeset 读取candidate.txt是否包含accepted）；
3. 不合格 →workspace.release(output)释放该候选，携带修正信息重新运行；
4. 合格 →workspace.select(output)结算合入，循环结束。

关键在 examples/workspace-handles/retry_until_acceptable.py#L35-L57：

first = task.run(repo=copy_git_repo(repo), label="first", score=10, accepted=False) if "accepted" not in candidate_text(first.output()): workspace.release(first.output()) # 不合格候选被释放，不污染工作区 second = task.run(repo=copy_git_repo(repo), label="second", score=90, accepted=True) workspace.select(second.output()) # 合格候选结算合入

注意一个反直觉的细节：被拒绝的候选并不会"失败后消失"——它在 trace 里有完整记录，release只是显式的结算动作。这意味着 Meta-Agent 事后可以复盘"第一次错在哪、修正了什么才通过"。仓库的 Pipeline Recovery 可视化示例展示了这种"v1 被拒 → 修正后重试通过"的前后对比：

重试的失败分类与"重试边界"（在哪个步骤断点重来）由 recovery_core.py 中的classify_failure给出：它输出失败类型、出错步骤、证据、重试边界和推荐修正——这正是 Meta-Agent 做自动恢复决策所需的全部结构化信息。

跑起来：两条命令

两个模式都是独立的 Python 脚本，无需 API key（示例使用确定性 provider）。克隆仓库后（本地环境）：

uv run python examples/workspace-handles/best_of_n.py uv run python examples/workspace-handles/retry_until_acceptable.py

每个脚本默认创建临时 vcs-core 工作区、运行示例、打印 JSON 摘要后自动清理；加--keep可保留临时工作区供检查，加--workspace PATH可指定已有工作区。详细说明见 examples/workspace-handles/README.md。

这两个模式为什么"直接可用"

它们的价值不在于几十行示例代码本身，而在于底层机制已经替你处理好了几件难事：

• 候选天然隔离：每次运行从仓库副本 fork，候选之间、候选与工作区之间互不污染（copy-on-write，比容器docker commit快约 5 倍）；
• 评判有据可查：Meta-Agent 通过 Changeset 这个"结算评判面"审查候选，而非盲信返回值，见 _support.py#L109-L118；
• 结算词汇表统一：select/release/discard/apply四种动作覆盖"保留、释放、丢弃、合入已前进的工作区"，且每个决定都会写入结算证据；
• 全程可追溯：运行的每一次边界穿越（权限、写入、结算）都是 trace 中的类型化事件，shepherd run trace、shepherd run changeset即可回放，详见 docs/shepherd/concepts/runs.md 与 docs/shepherd/concepts/effects.md。

总结

对 Meta-Agent 开发者来说，这两个模式展示了 Shepherd 的核心哲学：Agent 的每次输出都是可比较、可回退、可审计的"提案"，而非不可撤销的事实。把这套"保留—评判—结算"的循环套进你的工作流，监督、优化甚至训练下层 Agent 就有了可靠的地基。

【免费下载链接】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