beaker-setup

Beaker 设置

将仓库中真实的 LLM 或 Agent 任务转化为仓库优化集成。在完成集成前，先找到应用入口点、候选源、模型调用、评分器和带标签的数据。如果有真实的带标签示例，请完成本地结构冒烟检查并确保通过；只有开发者提出要求时，才远程启动。

首先加载已安装的技能

当开发者要求安装或更新此技能时，请先完成该命令，再加载并遵循新安装的副本。切勿在加载技能的同时并行安装或更新它。如果本会话在替换前加载了旧副本，请重新加载已安装的技能；如果 Agent 宿主无法就地刷新技能，请启动新的 Agent 会话，而不要继续使用过期指令。已经安装了所请求版本的用户无需重新安装，可直接正常加载。

版本检查

此技能（0.6.5）适用于 beaker-sdk 0.6.5。技能与 SDK 同步发布，版本号相同，因此两者版本不同就意味着其中一方已过期。在执行顺利流程前，运行 beaker --version（如果 Beaker 尚未安装在项目中，则运行 uvx --from 'beaker-sdk>=0.6.5' beaker --version）。如果已安装的 CLI 版本低于 0.6.5，或无法识别 --version，请通过项目的开发依赖工作流升级 beaker-sdk，然后再继续；较旧的 CLI 可能缺少此技能所依赖的命令或标志。如果 CLI 版本高于 0.6.5，则此技能已过期：运行 npx skills update beaker-setup 和 npx skills update beaker-usage，然后按照上文说明重新加载技能。请勿通过猜测 CLI 行为来绕过版本不匹配问题。

顺利路径

按此顺序执行。其余内容是约束和恢复措施。

1. 运行 beaker auth status（仅在失败时运行 beaker login），然后运行 beaker agent list --json。直到项目依赖安装完成前，使用 uvx --from beaker-sdk beaker ...。
2. 确定要优化的包或服务，而不是 Git 根目录：在 monorepo 中，这是存放任务自身 pyproject.toml 的目录。
3. 选择该项目现有的 Beaker 配置，或进入项目根目录并运行 beaker init。
4. 立即检查生成的 integrations.<id>.source_dir：它必须是相对于项目 Git 根目录的目录，例如 services/invoices；只有当项目本身就是 Git 根目录时，才使用 "."。如果不一致，立即修正。
5. 将 beaker init 输出的 beaker-sdk 依赖安装命令，添加到项目的开发/工具依赖组中。
6. 初步了解情况后，将当前已知的所有未决事项一次性询问清楚，例如要优化的指标、带标签数据的来源、快速启动还是使用完整数据集、Agent 名称、裁判模型或所需凭据。不要等到信息全部查清才提问；开发者回复期间，继续独立开展了解和实现工作。尽量合并问题；如果后续发现还有其他必须确认的事项，应届时询问，不要猜测或拖延当前工作。
7. 替换集成中的每个 TODO(beaker)，并接入真实模型调用。
8. 运行 beaker agent setup "<Agent Name>"（如果配置中有多个集成，则添加 --integration-id <id>）。Setup 会将 Agent 密钥记录在 integrations.<id>.agent_key 中。开发者提供名称即表示已批准；不要再次询问。
9. beaker onboarding status 报告新的 GitHub、带标签数据和凭据相关操作后，立即转达这些操作；要求开发者马上开始处理，然后继续由 Agent 独立完成的工作。
10. 上传或选择带标签的数据集，保留其不可变的 name@revision 或制品 ID，并将同一选择器显式传给 smoke 和 launch；确认所需的托管环境变量，然后通过 beaker run smoke --strict 验证。默认不要将组织专用的数据集选择器提交到 YAML；YAML 中的数据集默认值是可选的。
11. 选定配置和数据集后，一次性提交并推送至 beaker/<YYYYMMDD-HHMM>-<agent-name>。
12. 首次托管运行使用 beaker run trigger（Beaker Agent、数据集、可选的 --ref，以及适用时所需的裁判配置）。除非开发者明确要求比较特定模型，否则不要传入 --optimization-model。运行一旦启动，立即告知开发者仓库设置已完成，说明运行状态，并明确剩余等待时间是用于 Beaker 托管运行，而非继续进行集成工作。
13. 每完成上述一个步骤后，都运行 beaker onboarding status；只读探查后不要运行。

明确保持引导循环

beaker onboarding status 是用于控制设置流程的命令：

• 进入循环前，先完成 安全启动 中的仓库和 Agent 发现。适用时，选择现有 Agent 的 beaker_config_path，或者确认不存在匹配的 Agent。状态检查会从工作目录向上搜索；不会在 Git 根目录下发现嵌套配置。
• 完成引导步骤后运行此命令，例如 beaker init、安装依赖、进行有意义的集成编辑、beaker agent setup、推送、选择数据集、运行 smoke、设置触发器；如果不清楚下一步该做什么，也要运行此命令。咨询此命令之前，不要询问开发者接下来该做什么。
• 在运行 --help、--print、仅用于发现信息的 beaker agent list 或其他只读探查后，不要运行此命令，除非你陷入困境。
• 严格按照其返回的唯一下一步操作执行。返回的操作通常是按规范顺序排列的 Agent 所有步骤中第一个尚未完成的步骤。
• 如果 blocked_on_developer 列出了已知尚未完成、由开发者负责的步骤，只将本会话中新发现的操作原样告知开发者，不要自行尝试，并跟踪本会话中已报告的内容。汇总当前已知操作，要求开发者立即开始，然后继续执行返回的 next.action，以便与开发者的工作并行进行。此报告不会中断可独立开展的工作。dataset_available 或 required_env_configured 尚未完成时，不要执行 integration_pushed；若没有更早的 Agent 工作待办，请等待开发者完成这些操作后再进行最终推送。
• unknown 步骤表示尚未检查，不代表必须由开发者采取行动。
• 仅当 next 本身由开发者负责时才停止并等待。next.id 为 null 时即表示完成。
• 使用通俗的英语与开发者沟通。状态更新、问题和说明应简洁、直接，避免内部术语。
• 跟踪是可选的，仅供参考：如果所选用例包含跟踪，应尽力接入跟踪，并在推送前将接入内容与已完成的集成一同提交，但绝不要因此阻止或延迟必要的推送。
• integration_pushed 是 Agent 负责的最后一个阻塞步骤。最终推送前，先完成 dataset_available 和 required_env_configured；通常由 Agent 完成数据集选择和 experiment_launched，但开发者也可以通过平台 UI 完成这些步骤。

自行提交并推送集成

integration_pushed 属于 Agent 的工作：提交已完成的集成并推送，无需向开发者确认，除非开发者已告知你不要自主操作。推送到专用分支，名称格式为 beaker/<YYYYMMDD-HHMM>-<agent-name>，其中 <agent-name> 使用所选 Beaker Agent 的名称并转换为 slug，例如 beaker/20260821-1339-invoice-extraction：

git checkout -b beaker/$(date +%Y%m%d-%H%M)-invoice-extraction
git status --short
git add -- "<selected-config>" "<integration-and-helper-files>" \
  "<dependency-and-lock-files>" "<intentional-tracing-files>"
git diff --cached --name-only
git commit -m "Add Beaker integration"
git push -u origin HEAD

将占位符替换为此集成中变更的确切路径。包括所选配置和目标、.beaker/.gitignore、依赖元数据及其锁文件，以及任何有意添加的追踪或应用接缝。 不要将整个选定源目录加入暂存区。绝不要仅为使引导通过，就暂存无关的未跟踪数据集或源文件。 提交前检查已暂存的路径列表，并确保其中包含所有有意新增的集成文件。

如果当前检出状态已位于某个 beaker/<YYYYMMDD-HHMM>-<agent-name> 分支上，该分支对应所选 Agent 且时间戳不到一小时，则复用该分支，而不是另建分支：集成失败或未完成后重试时，应继续使用已推送的分支。较早的分支、其他 Agent 的分支以及任何其他分支，都意味着需要新建分支。beaker onboarding status 会在 integration_pushed 操作中指出要使用的分支；请遵循该指示。

不要先推送未完成的集成，之后再仅为添加数据集选择器或其他已知设置变更而再次推送。先上传或选择数据集，完成所选配置并进行验证，然后一次性完成最终的集成推送。

除非开发者要求，否则绝不要将集成推送到 main、master 或仓库的默认分支，也绝不要创建拉取请求。只暂存集成文件；绝不要暂存任何机密文件。报告你推送的分支。

保持 Beaker 隔离

将 Beaker 视为开发／评估工具，而非应用运行时。尽可能将所有由 Beaker 管理的文件放在所选项目的 .beaker/ 下：配置、集成、辅助代码、凭据、gitignore 和追踪记录。不要在应用包下添加 Beaker 模块，不要从生产入口点导入或初始化 Beaker，不要更改部署／运行时配置，不要添加或修改测试或 CI/CD 自动化，也不要让常规流量经过 Beaker。

仅在必要时才允许在 .beaker/ 之外添加文件：

• 将现有的事实来源数据集保留在原处；不要将其复制或移动到 .beaker/；
• 如有帮助，可将现有测试作为只读证据查看，但绝不要创建、编辑、移动或挪作他用测试文件、夹具、快照或测试配置，也不要在引导期间运行仓库的测试套件；
• 如果项目支持将开发／工具依赖与运行时依赖分开，则在开发／工具依赖元数据及其锁文件中记录 Beaker；
• 仅当 .beaker/ 下的集成和辅助代码无法复用现有接口时，才添加最精简的可选应用注入接缝。保留完全相同的生产默认行为，并将所有非追踪相关的 Beaker 导入限制在 .beaker/ 内。唯一可修改应用代码的例外是范围严格受限的追踪接线：在没有捕获时，current_trace() 是空操作；Beaker 仍是开发／工具依赖。

修改应用代码前，先解释为何 .beaker/ 下的集成和辅助代码不足以满足需求。不要为了 Beaker 重构生产代码。

不编写测试，也不添加 CI/CD 自动化

Beaker 入门流程不会添加测试代码或持续集成配置，也不会运行仓库的测试套件。集成通过 beaker run smoke --strict 和托管运行进行验证。对于隔离方面的风险，还应使用 validation-and-handoff.md 中描述的有界临时并行执行检查；这不会添加仓库测试或 CI/CD 自动化。

请勿创建或修改：

• .beaker/ 下用于该集成或任何其他用途的测试文件、固定数据、快照、测试辅助工具或测试配置；
• CI/CD 工作流或作业，包括 GitHub Actions 工作流、其他流水线定义及其现有内容；
• pre-commit 钩子、Makefile 目标、任务运行器条目，或任何用于自动运行 Beaker 的脚本。

尤其不要编写导入 beaker_integration.py、断言 Integration 模块、加载器或评分器，或运行 smoke 的测试；也不要添加定时或由推送触发、运行 beaker run smoke 或 beaker run trigger 的作业。

可以对已修改的文件运行仓库现有的代码检查工具、格式化工具或类型检查工具。入门流程中不要运行仓库的测试套件：这通常很耗时，也无法证明集成有效，而 beaker run smoke --strict 会对此进行验证。应通过阅读现有测试来获取证据。如果开发者明确要求编写测试或添加流水线作业，则只构建他们要求的内容。

安全起步

1. 确定所处的 Git 根目录及其 GitHub owner/name。在运行 beaker init 或首次运行 beaker onboarding status 之前，检查身份验证状态并列出 Agent。在 Beaker 安装到项目之前，通过 uvx 运行这些命令：

   uvx --from beaker-sdk beaker auth status
   uvx --from beaker-sdk beaker login  # only when auth status requires it
   uvx --from beaker-sdk beaker agent list --json
   

   安装项目依赖后，改用常规的 beaker 命令。

2. 将 Agent 筛选为 github_repository 完全匹配项。如果某个 Agent 明确符合任务，则使用其 beaker_config_path。如果有多个 Agent 可能符合，请询问开发者应使用哪个目标。从 Git 根目录开始，选定该配置，读取相对于 Git 根目录的 integrations.<id>.source_dir，然后进入该源目录／项目根目录。不要初始化或扫描替代配置。

3. 大多数新用户还没有 Agent。如果没有 Agent 与该仓库匹配，请检查检出内容中的 pyproject.toml、现有导出的 Integration 值、beaker.yaml、提示词定义、模型／Agent 调用、评测以及带标签的固定数据。在 monorepo 中，选择配置位置前先确定要优化的包或服务；不要假定 Git 根目录就是项目根目录。如果有多个可能的任务，请概述这些任务，并询问应先优化哪个。

4. 只有在发现过程中没有找到适用的配置时，才进入选定的项目根目录，并为 init、Agent 设置、验证和运行选择一个配置文件：

   cd services/invoices
   
   # Default location in this project.
   uvx --from beaker-sdk beaker init --print
   uvx --from beaker-sdk beaker init
   
   # Another path is supported when the developer explicitly wants it.
   uvx --from beaker-sdk beaker --config-file config/beaker.yaml init --print
   uvx --from beaker-sdk beaker --config-file config/beaker.yaml init
   

   BEAKER_CONFIG_FILE=config/beaker.yaml 等同于全局 --config-file 选项。如果已安装 Beaker，请省略 uvx --from beaker-sdk。配置路径必须是 Git 仓库内的文件； 不接受绝对路径和包含 .. 的路径。命令可以从所选项目根目录（使用其默认配置）运行，也可以从 Git 根目录（使用完整的仓库相对选择器）运行，例如 beaker --config-file services/invoices/.beaker/beaker.yaml run smoke --strict --integration-id <id>； 两者选择的是同一配置。在单体仓库中， 托管构建期间，integrations.<id>.source_dir 相对于 Git 检出根目录， 而 integrations.<id>.package_import_root 相对于 source_dir，而不是 YAML 文件。 对于位于 services/invoices/.beaker/beaker_integration.py 的集成，请使用 source_dir: services/invoices 和 package_import_root: .beaker。 启动任何嵌套项目集成之前，请阅读 cli-and-hosted-operations.md。

5. 切勿覆盖现有集成或已填写内容的配置。请填写现有集成；如果它已完整，请按照 复用仓库中已有的集成 操作。

6. 安装 beaker init 打印的依赖项命令；如果项目支持，请使用项目的开发／工具依赖组。不要让生产启动依赖 Beaker。

默认情况下，beaker init 会在所选项目根目录下创建 .beaker/beaker.yaml，并在需要时创建 .beaker/beaker_integration.py。--config-file 或 BEAKER_CONFIG_FILE 可将 YAML 文件移至该项目内的其他位置。Init 不会创建凭据或占位数据集。持久化的 integrations.<id>.source_dir 值始终相对于 Git 根目录，而不是 YAML 文件所在目录。例如，初始化 services/invoices 时会记录 source_dir: services/invoices；package_import_root 仍相对于该源目录。即使所选 YAML 文件位于嵌套目录中，source_dir: "." 始终表示 Git 根目录。绝对路径和包含 .. 的路径无效。如果 smoke 或 onboarding 报告了路径修正建议，例如 Set source_dir to services/invoices，请将现有 YAML 更新为该确切的仓库相对值，然后重新运行失败的检查；不要移动或重新创建配置。 使用 --agent-key、--target 和 --integration-id 指定 init 的值。若要在默认文件之外注册 Integration，请传入 --target path/to/integration.py 或 --target module:attribute；init 不会扫描仓库以查找 Integrations。

在 Agent 设置、入门引导状态、环境检查、smoke 和启动命令中，始终指定所选的 --integration-id <id>。每条命令都会重新解析集成；在先前命令中选择集成不会更改配置的默认值。

在托管验证或启动之前，请完成 cli-and-hosted-operations.md 中的 Beaker YAML 预检。请根据仓库检查托管源路径、依赖项安装情况和环境允许列表，不要盲目信任生成的默认值。在启动新运行之前，提交并推送所有 YAML 修正；已有运行不会应用之后的配置或 Agent 设置更改。

通过所选 Agent 的页面查看其运行情况和得分趋势。

复用仓库已提供的集成

如果 .beaker/ 中已经有可运行的集成（例如，某个烹饪手册示例的分支），除非用户另有要求，否则应复用它：不要运行 beaker init，不要重写，也不要提交拉取请求。选择现有的 .beaker/beaker.yaml，使用此检出仓库自身的 GitHub 仓库运行 beaker agent setup（beaker agent setup --repo <owner/name>），选择数据集，运行 beaker run smoke --strict，只推送 beaker onboarding status 要求的内容，然后运行 beaker run trigger。 onboarding status 只接受仓库为此检出的 origin（或其唯一 GitHub 远程仓库）且 beaker_config_path 为所选配置的 Agent；如果已提供的 agent_key 指向绑定到其他位置的 Agent（例如上游烹饪手册），则运行 beaker agent setup "<New Agent Name>" --repo <owner/name>，让 setup 创建新的 Agent 并记录其 key。

实现真正的集成

在 .beaker/ 下使用模块级的 integration = Integration(...)。从 beaker 导入契约类型。集成需声明 targets、一个 run_setup 类，以及异步的 run_case 和 score_case 可调用对象；它不保存运行状态。

• 将真实且有类型定义的数据集行声明为 run_setup.row_model。Beaker 会据此生成 JSON Schema，并在 setup 执行任何 I/O 之前验证所有行。
• 实现异步的 load_cases(row, *, runtime)，以生成一个或多个 Case(id=..., input=..., expected=...) 值。ID 在一次尝试中必须唯一。通过 runtime.case_files_dir(case_id) 暂存输入文件，并使用 CaseFile 声明这些文件。
• 在异步上下文管理器 prepare_run(*, runtime) 中打开用于加载用例或设置文档的客户端。清理工作由 Beaker 负责。仓库候选项会在单独的评估器进程中执行；多个用例和重试可能共用该进程。setup 客户端和内存状态不会传递给 run_case。请明确管理每个用例的状态和清理工作（包括失败时），并考虑已配置的并发数。客户选项通过 SetupRuntime.config 从启动时的 extra 传入，可按运行单独提供，也可通过可选的 config_defaults.extra 提供。
• 实现 run_case(*, case_input, runtime)，调用真实应用。返回包含 JSON 应用结果的 CaseResult(output=..., output_kind=...)。输出会作为预测结果保留，因此请精简保存评分器所需的观测状态。使用 runtime.trace 记录模型/工具遥测。将终止视为钩子契约的一部分：一旦应用无法生成完整结果，应及时让异常向上传播，而不是吞掉异常或让 run_case 持续等待。只有在再次尝试可能成功时才使用 RetryableCaseError。如果应用捕获了提供方或基础设施错误，请在返回 CaseResult 之前对错误进行分类，具体说明见 datasets-and-integration.md。捕获到的错误不一定就是一个被测量的错误答案。
• 使用真实的质量指标实现 score_case(*, case, result, case_files_dir)。返回 CaseScore(objective=..., field_scores=..., checks=...)，并提供通过和未通过的检查。如果仓库尚未明确规定要优化的指标及其权重，请询问；等待期间继续完成独立的接线工作。切勿虚构带标签的数据或评分。

请阅读 datasets-and-integration.md，了解有类型定义的行、setup、输出/检查指南和可执行示例。

确保用例可以安全地并发运行

Beaker 可能会在同一个评估器进程中执行多个用例和重试。 在接入 run_case 之前，请检查应用程序的初始化、执行 和清理流程，包括相关依赖项，确认是否存在共享的可变状态。常见 风险包括全局设置、冻结的时钟、数据库缓存、嵌入式解释器、固定输出路径，以及会影响其他用例的 清理操作，例如 close_all()。

如果调用可以安全地重叠执行，请使用应用程序现有的异步入口。 如果应用程序依赖进程级全局状态，请通过 .beaker/ 下的异步包装器，在全新的 子进程中执行每个用例。线程无法隔离全局状态。如果初始化或依赖项也会修改共享状态，仅移除全局清理操作并不足以解决问题。

子进程必须导入候选检出版本的代码，接收 JSON 输入和暂存的用例文件， 保留所选的模型路由，并返回现有的 CaseResult 格式。为每个用例提供独立的可写输出；只共享可安全共享的资源。使用受支持的 SDK 接口保留模型/工具调用轨迹和用量归属。传播执行错误，并附上错误诊断和重试分类。取消时，终止并等待工作进程及其所有后代进程退出。将预期答案和评分策略置于候选代码执行范围之外。

让 Beaker 控制用例的准入。不要添加第二个调度器，不要用全局锁串行化整个用例，也不要仅为掩盖共享状态的不安全问题而设置 max_concurrency: 1。如果资源或外部系统的合理限制要求降低并发，请记录原因并说明由此造成的吞吐量变化。独立进程无法隔离共享的远程账户或数据库。

将修复限制在集成层，并复用现有应用程序接口。如果所需的路由或追踪信息无法通过受支持的接口跨越进程边界，请指出具体缺口，而不是悄悄丢弃信息或杜撰 SDK API。对于存在这些风险的集成，在最终推送集成之前，按照 validation-and-handoff.md 执行有界并行执行检查。

选择可编辑范围

普通的仓库优化请使用 targets=repository() 和 RunSetup 子类；其默认的 prepare_run() 已会返回 {"repository": RepositoryRunSetupResult()}。需要时，可使用 repository(("src/invoice_agent", "config/prompts")) 缩小符合条件的源文件范围。这些是相对于所选集成的 source_dir 的规范化文件或目录路径，而不是 YAML 或导入根目录。Beaker 会保护 .beaker/、隐藏路径、依赖项、锁文件、构建配置、供应商文件和二进制文件，以及声明范围之外的文件。请将评分和评估策略保留在 .beaker/ 下；不要将其移入可编辑的应用程序源代码以绕过保护。

如果只需更改文档（例如在运行时获取的 wiki、提示词或知识文件），而应用程序代码固定不变，请使用 targets=documents(groups=("wiki",))，并使用覆盖 prepare_run() 的 RunSetup 子类。仅当单个候选项必须同时更改应用程序代码和文档时，才以相同方式使用 targets=(repository(...), documents(groups=("wiki",)))。最多声明一个 repository()；如果只需更改代码，单独使用 repository() 即可。每个单独应用的文档存储声明一个 documents() 目标，例如，两个 S3 存储桶中的 wiki 可使用 targets=(documents(groups=("wiki-a",)), documents(groups=("wiki-b",)))；所有文档目标的组名必须唯一。 prepare_run() 会返回一个字典，其中每种已声明的目标类型各有一个结果：仅处理文档时为 {"documents": DocumentRunSetupResult(target_documents=...)}；同时处理两者时为 {"repository": RepositoryRunSetupResult(), "documents": DocumentRunSetupResult(target_documents=...)}，其中包含实际的种子文档。这个文档结果包含每个文档目标的种子；每个文档的 group 指明其所属目标。 run_case 会从 runtime.targets_dir 读取候选项的文档，每个组对应一个目录。若要构建候选项的每个用例共享的内容（例如其文档索引），请传入 Integration(open_candidate=...)：这是一个 asynccontextmanager，接收 (*, targets_dir, scratch_dir)；Beaker 会在每个 rollout 进程开始、运行任何用例之前进入该上下文，并在最后一个用例结束后退出；run_case 会将其生成的内容作为 runtime.candidate 读取。每个候选项（包括仅处理文档的候选项）都在独立进程中运行：它只能看到不含隐藏目录或依赖目录的检出副本、明确声明的环境变量、每个用例的超时时间，以及每个用例结果 8 MiB 的大小限制（超出限制时会先丢弃 context）。 每个文档目标的获胜结果都会作为独立的 DocumentChangeSet 报告（其中列出其 groups），包含创建／更新／删除操作，并以种子内容哈希和可选版本为条件（如果代码也可编辑，还会包含一个仓库候选项）；开发者应分别应用这些更改集；不要自动应用。不要将 beaker-repository 用作文档组名。

每个集成都支持明确请求的模型比较，包括获胜者的 DocumentChangeSet。请保留所选的可编辑范围；绝不要为了启用运行而更改它。 命名目标为 Beaker agent；运行类型为 agent optimization。

在不更改生产默认值的情况下路由模型

将 Beaker 选择的模型路由保留在 .beaker/ 和评估／集成路径中。先通过 .beaker/ 下的集成或辅助代码接入。只有在无法复用现有注入接口时，才修改应用代码。如果未设置 runtime.model，则保留应用现有的客户端和模型默认值。

初始集成时，优先使用 Beaker 平台密钥进行自动托管提供商路由。如果设置无法使用此方式，并且 OpenAI Chat Completions 兼容客户端和 SDK 能够处理调用，则使用显式网关。客户的客户端和凭据仅作为最后手段，或在开发者明确要求时使用。默认情况下，不要将本地提供商密钥复制到托管设置中；保留现有的托管凭据选择。如果未配置 Agent 或组织密钥，显式网关会使用平台密钥。在托管运行中，OpenAI、Anthropic、Google/Gemini 和 OpenRouter 密钥均为可选项；不要将它们列入 integrations.<id>.required_env。

如果存在范围明确的注入接口，请在设置期间识别并接入可选的模型／客户端覆盖，这样后续比较就无需重写代码。当前的 inference_target(runtime) 辅助函数要求选定 runtime.model；普通运行时不要凭空设置该值。自动路由不会选择模型：比较仍需要注入和验证。保留原生请求结构和客户端类型。不要为了绕过调用失败而切换路由。

如果集成必须支持模型选择、LLM-as-a-judge 评分、框架插桩或跟踪证据，请阅读 model-routing-and-tracing.md。

连接托管访问并进行验证

安全起步已完成身份验证、发现 Agent 并选择配置。除非 beaker onboarding status 报告登录或选择已失效，否则不要重复执行这些发现步骤。以下信息仅用于剩余的托管设置。

连接 Beaker GitHub App

托管运行会通过 Beaker GitHub App 读取代码仓库，因此组织需要先完成安装，然后才能运行 beaker agent setup 或 beaker run trigger。

• beaker github status 只读，且绝不会打开浏览器。请先运行；退出代码 0 表示已连接，1 表示缺少连接或代码仓库访问权限，2 表示检查本身失败。知道目标代码仓库后，添加 --repo <owner/name>，以确认此安装可以读取该代码仓库。

• 只有开发者可以授予访问权限。如果状态报告存在缺失，请要求他们完成安装：

  beaker github connect
  beaker github connect --repo <owner/name>
  

• beaker github connect 会打开 GitHub App 安装页面，然后阻塞并轮询，直到检测到安装。请明确告知开发者命令正在等待他们操作；如果浏览器无法打开，请原样转达打印出的安装 URL，并让命令继续运行，直到他们完成操作。不要终止命令、将其置于后台或循环重试。

• beaker agent setup --repo <owner/name> 会隐式运行相同的连接流程，也可能以完全相同的方式阻塞等待浏览器操作。先运行 beaker github status，可将这项意外等待变成明确步骤。

代码仓库选择、安装批准和超时详情请参见 cli-and-hosted-operations.md。

选择 Agent

安全起步已选择现有 Agent，或确认不存在匹配的 Agent。在上传数据或启动运行之前，请告知开发者你选择了哪个 Agent。

使用以下命令选择现有 Agent：

beaker agent setup "<selected-agent>"

beaker agent setup 会将所选 Agent 键记录到 integrations.<id>.agent_key， 因此 beaker onboarding status 和 beaker run trigger 会选择同一个 Beaker Agent。如果配置中有多个集成，请添加 --integration-id <id>。对于明确需要 此行为的命令，已导出的 $BEAKER_AGENT_KEY 仍会覆盖 YAML。当开发者提供了 Agent 名称时，应将其视为已获批准，不要再次询问。

仅当所选 Agent 仍需要关联该仓库时，才传入 --repo <owner/name>。如果发现 没有匹配的 Agent，只有在确认优化目标和名称后才能创建：

beaker agent setup "<New Agent Name>" --repo <owner/name>

未知名称会创建一个 Agent，因此不要猜测名称，也不要使用通用 仓库名称。

请从同一个已选项目根目录运行 beaker agent setup，并传入 init 时使用的相同全局 --config-file/BEAKER_CONFIG_FILE 选项。如果之后改为从 Git 根目录运行命令，请使用完整的 相对仓库路径，例如 --config-file services/invoices/.beaker/beaker.yaml。Setup 会将发现的 YAML 路径以相对于 Git 根目录的形式存储在 Agent 的 beaker_config_path 中。Setup 不允许将已有的仓库关联 Agent 重新指向不同的配置路径；请为新任务选择新的 Agent 名称。这样，托管 运行就能找到 services/invoices/.beaker/beaker.yaml 之类的配置，无需再添加路径条目。 YAML 中的 integrations.<id>.source_dir 则独立标识相对于 Git 根目录的项目源目录，供本地验证和托管构建使用。

Agent setup 会在 beaker.yaml 中记录所选 Agent，但不会配置 运行时密钥。运行时 API 密钥来自 Settings → Credentials → API keys， 可通过 $BEAKER_API_KEY 提供给开发者自有的 CI 流水线；本地 提供商和客户密钥仍可存放在 .beaker/.env 中。不要在引导流程中创建该流水线。切勿打印、回显或提交密钥。 在处理凭据、数据集、托管环境变量或运行之前，请阅读 cli-and-hosted-operations.md。

启动前，请完成 cli-and-hosted-operations.md 中的凭据预检。根据设置、案例加载、候选项初始化、应用程序 执行和评分路径推导必需变量，然后在 integrations.<id>.required_env 中声明；OpenAI、Anthropic、Google/Gemini 和 OpenRouter 密钥是可选项，不要纳入其中。 使用以下命令检查托管就绪状态：

beaker agent env check --integration-id <id> --agent <selected-agent>

此检查会识别已存储的 Agent 变量、组织提供商凭据，以及服务器确认的 Beaker 提供商路由（适用于受支持的托管调用）。启动前，请解决报告中的所有缺失必需变量。本地 shell 变量和 .beaker/.env 中的值不是托管设置。冒烟检查通过并不能证明凭据已就绪，因为冒烟检查不会执行 run_case。

只有在有真实的带标签示例可用后，才运行结构性冒烟验证。如果源数据仍在磁盘上，请使用本地路径：

beaker run smoke --strict --integration-id <id> --config '{"local_dataset_path":"<dataset-dir>"}'

如果本地数据不可用，或临时转换后已删除，请使用所选的托管数据集。优先使用其不可变修订版；artifact id 也等效：

beaker run smoke --strict --integration-id <id> --agent <selected-agent> --dataset <name@revision>
beaker run smoke --strict --integration-id <id> --agent <selected-agent> --dataset-id <artifact-id>

• Smoke 会在进入 prepare_run() 前验证类型化行，加载用例并检查其文件，同时验证目标文档。对于文档目标，它会创建种子副本。所有设置资源都会关闭。它不会调用 run_case() 或 score_case()；设置钩子可能会执行外部 I/O。
• 本地路径 smoke 会读取本地行；客户设置钩子仍可能执行外部 I/O。远程数据集 smoke 会通过 Beaker 进行身份验证，解析所选快照，并通过预签名 URL 下载数据集，然后验证每一行。它不会启动托管运行。
• Smoke 和之后的托管运行使用相同的不可变 name@revision 或 artifact id。不要同时提供 --dataset 和 --dataset-id。
• 如果检查失败，请查看其分阶段输出中的 PASS/FAIL 以及客户代码回溯。
• 该输出中的追踪警告不会阻止 CLI 运行。如果适用追踪，请在必需的最终推送前，尽力完成集成所需的配置，然后重新运行 smoke；不要让追踪阻碍推送。
• 如果需要执行证据，请运行 beaker trace instrument --check，在本地 Beaker 捕获环境下，执行以 Integration.run_case 内主工作流 Agent 为根节点的仓库候选工作流；然后运行 beaker trace doctor --require-model-calls，并使用 beaker trace inspect 检查 .beaker/traces。请包含工作流的子 Agent、工具、检索器和嵌套模型调用；仅捕获评审器或评分器的运行不满足运行时追踪验证要求。

在声明设置完成或远程启动前，请阅读 validation-and-handoff.md。

不可妥协的规则

• 绝不根据代码、架构、提示词、README 文本或合理的领域知识编造带标签的示例。
• 遵循 Start safely 中关于是否使用现有 Agent 的决策。绝不创建以仓库命名的通用 Agent，也绝不替换匹配 Agent 已选定的配置。
• 除非用户要求，否则绝不重新创建或改写仓库已附带的集成；应复用现有集成。
• 绝不代替开发者尝试授予 GitHub 访问权限，也绝不猜测或传入 --installation-id；应提供安装 URL，并等待开发者确认。
• 当 beaker github connect 或 beaker agent setup 等待浏览器授权时，绝不终止进程、将其置于后台或循环重试；它正在轮询，并未卡住。
• 将选定的 Agent 视为其运行及运行历史的直接所有者。只有在确认存在不同的优化目标时，才创建另一个 Agent。
• 绝不在多个合理任务之间默默做出选择。
• 当存在多个合理指标，或评分会汇总或平均多个指标时，绝不擅自决定优化要爬升的质量指标；应询问开发者要优化哪个指标及其权重。一旦发现多个合理的评分字段，就应立即询问。询问并不意味着暂停：等待期间继续替换 TODO(beaker)、接入 run_case 并准备数据集转换；收到答复后，再将选定字段加入评分器。若只有一个明确确定的指标，则无需确认。
• 始终使用通俗易懂的英语与开发者沟通，避免内部行话和深奥技术术语。
• 完成仓库和 Agent 探索后，在使用选定配置运行 beaker onboarding status 之前，绝不询问开发者接下来要做什么；应遵循其返回的操作，并逐字转达需要开发者执行的操作。
• 在单体仓库中，绝不假定 Git 根目录就是 Beaker 项目根目录；应选择目标项目，并确保所有命令中的配置选择保持一致。
• 只要 Beaker 管理的代码或文件可以放在 .beaker/ 中，就绝不将其放在该目录之外。
• 绝不将生成的 JSONL 数据集文件保存在用户的仓库中或 .beaker/ 下；应在操作系统管理的临时目录中暂存转换结果，并在清理前上传。
• 绝不为 Beaker 创建或修改测试、固定数据、快照、测试辅助工具或测试配置；现有测试是只读的事实来源，运行仓库的测试套件也不属于入门流程。
• 绝不为 Beaker 添加 CI/CD 自动化：不得添加 GitHub Actions 工作流或其他流水线任务、pre-commit 钩子、Makefile、任务运行器或运行 Beaker 的脚本入口。烟雾测试和托管运行是验证途径。仍可运行现有的代码检查工具和格式化工具。
• 绝不从生产入口、应用启动、请求处理或部署配置中导入或初始化 Beaker；在实际模型调用位置进行范围严格受限的追踪接线除外。
• 绝不让生产执行依赖 Beaker；如果项目支持区分依赖，应将 Beaker 保留在开发/工具依赖中。
• 在穷尽仅限集成和 .beaker/ 辅助方案之前，绝不编辑应用代码；如果不可避免地必须编辑，只能添加一个默认行为不变的可选接入点，明确允许的追踪接线除外。
• 绝不询问开发者是否允许提交或推送集成；integration_pushed 由 Agent 负责。唯一例外是开发者已告知你不要采取自主行动。
• 除非开发者要求，否则绝不将集成推送到 main、master 或默认分支；应使用 beaker/<YYYYMMDD-HHMM>-<agent-name>。
• 绝不在 .beaker/.env 之外写入真实密钥；托管密钥值应使用 --value-stdin。
• 在设置期间保留声明的仓库或文档目标。
• 切勿将环境值放入 beaker.yaml；integrations.<id>.required_env 中只能包含名称。
• 切勿让正常的生产流量经过 Beaker 推理。
• 切勿让托管 LLM 评审器绕过 scoring_inference_target()；直接使用提供商客户端仅作为本地应用/评估的回退方式。
• 切勿为评分器、评分标准评审器、评估器、后处理或发布后的模型调用添加埋点。候选追踪覆盖以 Integration.run_case 中的主工作流 Agent 为根的工作流，包括其子 Agent、工具、检索器和嵌套模型调用。应在候选工作流的调用边界限定追踪范围，即使客户端或包装器被共享，也要排除这些调用。评分器流量通过 scoring_inference_target() 单独核算。
• 切勿向应用或基准测试框架提供透明的 Python 代理、__getattr__ 转发器或猴子补丁式模型客户端替代品。应在调用点或通过框架集成进行追踪，并且只注入应用本来就接受的客户端类型；客户端类型检查会拒绝这些包装器，导致每个用例在运行前失败。唯一例外是特定于框架且保留类型的适配器：它必须继承框架验证的公开客户端基类，正确初始化该基类，委托其原生转换、生命周期和请求方法，并通过应用的解析器或类型检查，然后才能运行托管基线。如果追踪无法保留该类型，就保留原始客户端并报告追踪缺口。
• 对于确定性评分器，切勿设置 scorer_model 或调用 scoring_inference_target()。对于 LLM 评审器，请确认其已获批准的固定 scorer_model 已包含在启动配置中；切勿从 runtime.model 推断，也不要臆造默认值。
• 对于常规应用/评估运行或仅优化提示词，切勿要求提供 runtime.model。
• 切勿将 Beaker 所有的 S3 URI 用作面向用户的数据集选择器。
• 默认情况下，切勿将组织专属的 dataset_ref 或 dataset_id 提交到 YAML。应在入门设置会话中保留上传后不可变的选择器，并在冒烟测试和启动时显式传入；将仓库数据集设为默认值属于有意选择启用的行为。
• 除非开发者明确要求，否则切勿触发托管 Agent 优化运行。
• 首次托管运行是对生产系统进行 Agent 优化。使用 beaker run trigger 启动（Beaker agent、数据集、可选的 --ref，以及适用时必需的评审器配置）。 除非开发者明确要求比较指定模型，否则不要传入 --optimization-model。仓库集成和文档集成支持比较模型。集成运行不支持 --test-all-candidates。
• 将指定目标称为 Beaker agent（beaker agent setup、--agent），将运行类型称为 agent optimization。不要用“Agent”同时指代两者。
• 启动托管 Agent 优化运行前，先将已完成的 Beaker 集成提交并推送到所选 Beaker agent 仓库中的一个分支。不要提交 *.env 或其他机密文件。追踪适用时，应尽力包含追踪变更，但绝不要让追踪阻碍推送。
• 满足文档规定的前置条件后，将 beaker dataset upload 和 beaker agent env ... 视为已获授权的合作方操作。
• 仅使用 beaker run trigger 启动托管 Agent 优化。若不传入 --ref，它会优先使用当前关联的远程分支，并在该分支不可用时回退到仓库的 GitHub 默认分支。只有在明确覆盖远程分支时才使用 --ref <remote-branch>。切勿传入标签或提交 SHA；托管源必须是 GitHub 分支。
• 目标 Python 仓库必须包含 pyproject.toml。