多代理协作引擎

Voltron项目

V代表全体，全体代表一人

Voltron项目 是存储库； Voltron发动机 这就是它运送的东西。该引擎是一个编排层，它通过一个真正的三层代理团队来驱动Claude Code本身，每个专家都在自己的Docker容器中运行，然后根据它在现场学到的知识对这些代理进行评分和重写。

将其安装为MCP服务器，并为任何项目搭建经过战斗测试的子代理定义，用于Unity游戏开发、web/全栈开发和通用软件工作，以及scrum主协调器、51个微代理和自我改进循环。

发动机由三根支柱支撑：

• 作曲，不要催促。 一个在代码中强制执行的真正的组织结构图：协调员、子经理和微代理的深度受限层次结构，由运行时而不是惯例限制在深度3。次级经理组成单动词微观代理，从不即兴创作一个整体。
• 真正的隔离，真正的并行。 每个代理都在自己的一次性Docker容器中运行，运行真实的 claude CLI，而不是进程内SDK调用。该镜像提供了一个完整的工具链——Node、Python、Ruby、GitHub CLI，以及通过Playwright提供的无头Chromium，因此web和前端代理可以实际渲染和测试页面。在一次批处理调用中扇出多达八个代理，并使用一个在整个机群中共享一个提示缓存写入的头启门。主机Docker套接字默认为拒绝：它仅绑定挂载到可以实际调度（其 tools: 授予 run_agent_in_docker)，因此研究、设计和验证角色永远不会获得主机根等效访问权限。
• 它改善了自己。 每次会话后，代理都会提交结构化的反思。CI运行线束工程师代理来编辑模板并打开PR，voltron在发货前通过其在生产中使用的同一实时MCP路径对线束回归进行评分。

代理团队

Orchestrator（斜线命令，在主Claude Code会话中运行）

专业子代理（核心，所有项目）

统一

run_agent_in_docker 是 主要调度路径 Unity工作：C#脚本、着色器/材质文件编辑、清单更改和文件夹/资产结构都在Docker中运行。一个狭义的例外包括四个需要带有Coplay MCP的实时Unity编辑器的编辑器绑定管理器；scrum master通过内置的 Agent 工具从主机。

网络/全栈

微代理（俳句层，51名专注工作者）

由子经理分派单动词、单文件任务。每个人都做一件事。

网络

统一

开发运维

问答

十字

内部（未搭建成项目）

安装

一个命令设置

git clone https://github.com/7ports/project-voltron.git
cd project-voltron
node scripts/setup.js

安装脚本：

• 安装npm依赖项
• 注册 project-voltron 克劳德代码中的MCP服务器（全局范围）
• 将推荐的allowlist添加到 ~/.claude/settings.json 因此，代理不需要手动批准常见命令
• 验证Docker是否可用

重新启动Claude代码 运行安装程序以加载新的MCP服务器并分配列表后。

必需：珠子依赖跟踪器

scrum master使用 珠子 用于依赖感知任务编排。 这是强制性的 从v3.4.0开始，代理商将拒绝在没有工作的情况下分发工作计划 bd CLI：

curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

如果没有珠子，scrum master就会回到手动依赖推理。

自动恢复（v3.7.0+）： scrum master的飞行前检查现在可以检测到共享dolt服务器（由配置 dolt.shared-server: true 在 .beads/config.yaml)已因重新启动而成为孤儿并运行 bd dolt start 在计划之前自动重新启动它。这消除了最常见的Windows重启后故障模式，在这种模式下，bd命令出错，显示“端口3308上无法访问Dolt服务器”。为了永久解决问题，代理人 珠子回收 部分提供了 Register-ScheduledTask 自动启动的PowerShell代码段 bd dolt 每次登录时。

重新验证安装

在任何Claude Code会话中：

Call mcp__project-voltron__setup_voltron

这可以在不需要终端的情况下检查和修复满负荷表。

亚历山大一体化

Voltron代理商旨在与 亚历山大项目：一个配套的MCP服务器，维护一个共享的工具设置指南库。当两者都安装好后，代理商会咨询亚历山大 之前 任何工具安装，这是强制性的，不是可选的。

这能实现什么：

• 所有专业代理致电 quick_setup 在安装任何工具、库或服务之前，以及 search_guides 如果没有确切的指南
• scrum-master 电话 get_project_setup_recommendations 在规划新项目时，需要专业代理在每个工具设置任务中检查亚历山大
• 完成设置后，代理呼叫 update_guide 记录发现（平台怪癖、版本说明、工作命令）
• 来自会议的工具知识回流到亚历山大，而不仅仅是进入Voltron的反思管道

内容边界： Alexandria只适用于非项目特定的、可重复使用的文档、工具设置指南、平台怪癖、版本说明、API模式。项目特定知识（业务逻辑、自定义架构、团队惯例）属于 CLAUDE.md 以及当地的项目文件，而不是亚历山大。

设置： 在中全局安装两个MCP服务器 ~/.claude.json。不需要额外的配置，代理模板已经包含了相关的 mcp__alexandria__* 工具。

看 亚历山大项目 有关设置说明。

MCP工具

用法

安装后，询问Claude Code：

• “与Voltron代理商一起为Unity项目搭建脚手架” → scaffold_project 与 project_type: "unity"
• “用Voltron代理商搭建这个网络项目” → scaffold_project 与 project_type: "web"
• “我该如何使用Voltron代理商？” → get_agent_usage_guide
• “检查我的代理是否是最新的” → check_for_updates
• “将自动更新挂钩添加到此项目” → get_auto_update_hook

工作流

1. 脚手架：run scaffold_project 在项目根目录中使用项目类型
2. 配置：填写 CLAUDE.md 使用您的项目细节并设置Docker执行（请参阅脚手架输出）
3. 研究：对于新项目，调用 @agent-project-planner 研究技术栈与设计架构
4. 计划：调用 /scrum-master （斜线命令，在主会话中运行）与项目计划一起获得结构化的工作分解
5. 开发：根据计划调用专业代理；他们向亚历山大咨询工具设置
6. 反映：scrum-master在阶段完成、阻塞和会话结束时自动提交反射；还将工具发现同步到Alexandria

代理自动更新

scaffold_project 输出a .claude/settings.json 包含a UserPromptSubmit 钩子。这个钩子能跑 scripts/auto-update-agents.js 在每次Claude Code会话开始时。如果安装的版本与本地Voltron安装不同，所有过时的文件都会自动更新到位。

什么会自动更新：

• 所有代理 .md 文件在 .claude/agents/
• Slash命令 .md 文件在 .claude/commands/ （例如。 scrum-master.md)
• Dockerfile.voltron （如果存在，只适用于使用Docker的项目）
• scripts/voltron-run.sh （如果存在）
• v3.11迁移： v3.11之前搭建的项目将 .claude/agents/scrum-master.md 自动移动到 .claude/commands/scrum-master.md 在下一个会话中，将删除旧的子代理文件。无需手动操作。
• v3.12.1脚手架固定： scaffold_project 现在写 .claude/commands/scrum-master.md 为了 每 项目类型（之前已为类型化脚手架删除），自动更新钩子会自动修复已搭建项目上丢失的命令文件，因此现有签出会自动执行 /scrum-master 在他们的下一次会议上。

什么不是自动更新的 （用户自定义文件）：

• CLAUDE.md，包含您填写的项目特定上下文
• .claude/settings.json，您可能已经自定义的钩子配置

A. [VOLTRON] Auto-updated N file(s) 当发生更新时，消息会出现在上下文中。对于添加此功能之前搭建的项目，运行 get_auto_update_hook 获取要手动添加的设置条目。

自我完善

代理人通过以下方式提交会后反思 submit_reflectionscrum master现在会在阶段完成、严重阻塞后和会话结束时自动提交反射。反思在 reflections/ 目录，并由运行的GitHub Actions工作流自动处理 每周一10:00 UTC:

只写反射提交（v3.13.1）： submit_reflection 现在只写 reflections/<file>.json 在本地并返回已保存但未提交的状态时，它不再自动git add/commit/push。稍后通过专门的反射扫描/PR收集和提交反射，因此它们不再将提交绑定到受保护的 main 或污染无关的特征PR。

1. 这 harness-engineer 代理读取所有未处理的反射
2. 按代理对反馈进行分组，并按频率进行优先级排序
3. 将有针对性的改进应用于 src/templates.js
4. 缓冲补丁版本并提交
5. 在更改到达之前打开PR供人工审核 main

合并后，安装了自动更新挂钩的项目将在下一个会话开始时自动接收新模板。没有钩子的项目可以通过以下方式手动进行改进 check_for_updates。也可以从“操作”选项卡手动触发工作流。需要 ANTHROPIC_API_KEY 设置为存储库机密。

第二工作流程， .github/workflows/voltron-evals.yml，运行 voltron阀门 按每月节奏（UTC时间每月1日12:00）加上手动佩戴安全带 workflow_dispatch。它对每个代理模板执行完整的Deep+Broad eval扫描，Opus对Deep任务进行判断，并对Broad实例进行Haiku/程序化评分。已键入内容哈希缓存 src/templates.js 和 voltron-evals/lib/template-hash.js 重用之前的记分卡，这样只有自上次扫描以来模板发生更改的代理才能支付LLM成本。记分卡作为CI工件上传。

强化亚历山大回写合同（v3.20.0）： 现在，每个记录到亚历山大港的代理角色都共享一份规范合同，取代了“如果你学到了什么，就记录调查结果”这样的软措辞。它有三个部分： 行动前回忆 （电话 quick_setup / search_guides / list_guides 第一在任何工具设置或非琐碎的技术决策之前，从亚历山大已经知道的事情开始）； 回写触发器 （一个固定的五项列表——在任何工具/MCP设置、任何不明显的错误修复、任何版本/平台怪癖、任何棘手的配置在多次尝试后着陆，以及在会话结束时——使录制成为默认设置，而不是事后补充）；和 泛泛而谈，不要抛弃 （剥离主机/路径/秘密/客户端/项目细节，并使用占位符记录一般课程，如 <your-project> / <API_KEY> 而不是跳过）。每个块的现有内容边界语句（纯粹是项目特定的知识，属于CLAUDE.md，而不是Alexandria）被逐字保存。同一版本扩展了scrum master的主机↔Docker git分歧指南分为一个完整的小节——为什么会发生（容器代理在主机的分支上提交，产生分歧历史），何时进行协调（在任何容器提交波之后，在主机推送之前），顺序 fetch → pull --no-rebase -X ours → verify → push 序列加上 git merge -X ours <branch> 变体，the -X ours 数据丢失警告，以及只有主机会话推送和注释良性会话的规则 bd dolt 如预期的那样，“没有共同祖先”自动推送警告 shared-server: true + git-push: false.

容器git配置EBUSY修复（v3.20.1）： 宿主 ~/.gitconfig 以只读方式直接绑定到容器上 全球 git配置路径(~/.gitconfig 在容器内），因此每次全局git写入都在代理容器内-- git config --global, gh auth setup-git，启动时GitHub引导程序失败 EBUSY （“设备或资源繁忙”）。这表现为提交者的警告，错误 max_turns 失败，约10分钟git忙锁挂起。主机配置现在以只读方式装载在非全局路径上(/etc/voltron/host.gitconfig)虽然 GIT_CONFIG_GLOBAL 将git指向一个可写文件 [include]是的，所以主机身份， credential.helper，以及 includeIf 仍然继承（读取） git config --global / gh auth setup-git 写作成功。回购本地提交者身份回退未受影响。

反射驱动导向强化（v3.20.2）： 将一批场反射处理成四个模板锐化。这 scrum大师 现在治疗a max_turns/超时退出 不 自动失败——它在阻止珠子或重做工作之前验证工作树（或greps接受令牌），并更喜欢廉价的验证修复通行证，因为最常见的错误是代理完成编辑，然后在验证过程中筋疲力尽；它还指出，在大型Windows绑定挂载上，容器端git可以挂起（通过grep验证，提交主机端）。任何Voltron版本的碰撞调度现在都有一个明确的验收标准来运行 npm run build:apm 并保持 git diff --exit-code .apm apm.yml clean，或者CI的APM清单漂移门在合并时变红 线束工程师 获得了一个匹配的漂移门提醒，以及一个“将单个版本部署到主”的樱桃采摘配方，用于从堆叠的WIP中隔离一个可交付的版本。这 质量保证测试仪 将夹具保真度扩展到内部格式——在真实系统永远不会发出的预制有效载荷上构建的绿色测试掩盖了漏洞；从真实捕获源夹具，并在每次解析时验证字段名→ 状态→ 运输→ 前端跳转。

珠子/夹子可靠性修复（v3.21.0）： 珠子问题跟踪器依赖项现在是 无阻塞 --运行时行为契约会发生变化，因此不稳定或不可用的跟踪器永远不会使会话搁浅。飞行前准备闸门现在打开 bd ready --json 退出0（真正的健康调查）而不是存在检查；检测并自动清除之前运行崩溃留下的陈旧pid/lock文件，而不是楔入启动；如果beads服务器真的宕机，会话 优雅地降级 --进展情况通过以下方式报告 update_progress 并且工作继续进行，而不是在跟踪层中断时硬失败（STOP）整个会话。

Docker执行

scrum master通过以下方式自动启动Docker容器内的每个专业代理 run_agent_in_docker MCP工具。你通常在桌面上运行Claude Code，Docker是在幕后处理的。

当scrum主机调用代理时， run_agent_in_docker:

1. 为项目上下文加载代理的模板和CLAUDE.md
2. 构建Docker镜像 Dockerfile.voltron （首次构建后缓存）
3. 将项目目录和OAuth凭据装载到容器中
4. 运行代理 --dangerously-skip-permissions 完全自主执行
5. 完成时返回代理的输出

先决条件： Docker必须安装并运行。 Dockerfile.voltron 和 scripts/voltron-run.sh 由生成 scaffold_project启动脚本也可以手动用于独立代理会话。

并行调度（v3.12.1）： 当多个代理可以并行运行时，Voltron会暴露 run_agent_in_docker_batch，一个接受一系列分派并在并发容器中运行它们的MCP工具。这是任何无依赖性扇出的推荐路径（例如一次处理多个bd-ready任务），并避开了Claude Code主会话应用的每个MCP服务器工具调用序列化。

有界代理结果输出（v3.13.1）： run_agent_in_docker 和 run_agent_in_docker_batch 现在返回一个大小有限制的结果，返回的输出尾部限制在~4000个字符以内(MAX_TAIL_CHARS)因此结果不再超出工具结果限制。完整的、未删节的成绩单仍将发送至 .voltron/logs/ 以供检查。

身份验证（v3.4.1）： Docker工具挂载 ~/.claude/.credentials.json:ro 这样Claude Max OAuth登录就可以重复用于代理会话。他们故意这样做 不 山 ~/.claude 或 ~/.claude.json，后者包含在启动时挂起Linux容器的主机路径MCP服务器注册（60-90秒以上）。身份验证解析顺序：

1. ~/.claude/.credentials.json （如果存在，请安装）
2. CLAUDE_CODE_OAUTH_TOKEN env-var（如果设置，则传递）
3. ANTHROPIC_API_KEY env-var（如果设置，则传递；保留给CI）

在Windows上，默认情况下OAuth存储在凭据管理器中 ~/.claude/.credentials.json 不存在。跑 claude setup-token 一旦在普通终端中在该路径上实现了一个长期令牌，Voltron Docker代理就会自动获取它。

身份验证模型（v3.13.0）： 代理容器内的Claude身份验证仅从挂载的 ~/.claude/.credentials.json，飞行前不再检查 CLAUDE_CODE_OAUTH_TOKEN env var.在Unix上运行 claude setup-token 一次实现文件；Windows更新 ~/.claude/.credentials.json 如果它丢失或过时，请手动操作。

从容器内部推送Git（v3.13.0）： 这 committer 和 pr-opener 代理现在可以从Docker容器内部推送提交和打开PR。要启用此功能，请设置 GH_TOKEN 在您的主机上 一次 在启动Claude Code之前，Voltron会将其传递到代理容器中（一个细粒度的PAT repo 范围也有效；Voltron回落到 GITHUB_TOKEN 如果设置）：

# Unix / WSL
export GH_TOKEN="$(gh auth token)"

# Windows PowerShell
$env:GH_TOKEN = (gh auth token)

集装箱入口点运行 gh auth setup-git 因此HTTPS推送和PR创建无需进一步配置即可工作。

零设置GitHub身份验证（v3.14.0）： 手册 GH_TOKEN 不再需要出口。在一次性主机之后 gh auth login，Voltron从主机中获取令牌 gh auth token 在调度时将其注入到每个代理容器中，因此 committer 和 pr-opener 无需手动即可推送提交和打开PR GH_TOKEN 没有重新启动。一个明确的 GH_TOKEN/GITHUB_TOKEN env覆盖仍然优先；设置 VOLTRON_DISABLE_GH_AUTOTOKEN 完全禁用自动令牌。看 docs/voltron-gh-credentials-automount-plan.md 了解设计细节。

成本优化（v3.15.0）： 行为保持改进 run_agent_in_docker 和 run_agent_in_docker_batch，提示缓存重用静态角色模板前缀（Haiku/Sonet代理的系统提示重新定位），消除重复的CLAUDE.md和bd prime上下文，交错批处理扇出以减少冷启动峰值，并按代理提高 max_turns代理行为或输出没有变化；MCP服务器重启后生效。看 docs/voltron-cost-optimization-plan.md 了解详情。

反射驱动的模板改进（v3.15.1）： Docker主机凭据边界记录在commiter/pr opener/deploy触发器中（仅在容器中提交；主机处理推送/发布/bd 写），预算意识 [DONE] 跨提交者/测试编写者/全栈开发/质量保证测试人员退出，git身份已预先配置（否 git config writes），加上fullstack-dev（在声明干净的类型检查之前运行tsc，通过返回类型进行线程泛型，在分解时填充beads图），qa-tester（大约10分钟的时钟大小），css writer（JS风格对象），配置编辑器（vitest --config 用于排除的套件）和测试编写器（密封IO），这些都是从会话反射中得出的。

反射驱动的模板改进（v3.14.1）： 全栈开发提交预算规则、提交者超过验证上限和pr开启器GH_TOKEN飞行前，源自会话反射。

嵌套三层调度（v3.8.0）

集装箱化的子经理或 harness-engineer 现在可以通过以下方式派遣自己的Tier-3微代理 run_agent_in_docker端到端，从容器内部。scrum master不再需要将工作计划扁平化到一个层次：在Docker中运行的二级子管理器驱动执行文件编辑的三级微代理，并且链底部干净，因为每个三级模板都被标记了 nestable: false.

它是如何工作的：

• run_agent_in_docker 通过解析主机路径 VOLTRON_HOST_ROOT / VOLTRON_HOST_HOME / VOLTRON_HOST_TMPDIR 所以内部 docker run 看到真实的主机文件系统（而不是容器的视图）。
• 嵌套代理通过过滤套接字代理sidecar到达主机Docker守护进程(voltron-socket-proxy)而不是原始的套接字绑定。sidecar保存真实的 /var/run/docker.sock派遣有能力的代理人接收 DOCKER_HOST=tcp://voltron-socket-proxy:2375 在专用专用专用网络上(voltron-proxy-net)永远看不到自己的插座。（该网络是一个专用网桥，而不是 internal: true，因为Voltron代理需要用于Anthropic API的出站互联网， git push和包管理器；守护进程-API安全边界由代理allowlist强制执行，与出口无关。)
• A. container-mcp.json 在启动时生成并装载到内部容器中，因此嵌套的Claude代码有自己的 project-voltron MCP可用。
• 深度盖帽后卫拒绝任何四级发射，微特工无法进一步派遣。

套接字代理隔离（S1阶段B，v3.18.0）。 两层控件缩小了可用于嵌套代理的Docker API曲面。

A阶段（v3.17.2）： 主机套接字默认为拒绝。它仅绑定到以下代理中 tools: 授予 run_agent_in_docker，因此研究、设计和验证角色根本就没有套接字。

B阶段（v3.18.0）： 拥有调度权限的代理不再接收原始套接字。相反，一个长寿命的过滤套接字代理sidecar(wollomatic/socket-proxy（被摘要固定）掌握着真实 /var/run/docker.sock 并在 tcp://voltron-socket-proxy:2375 在专用的专用网络上。无需主机配置：Voltron通过其已经使用的Docker API在运行时建立代理和专用网络。这适用于Docker桌面（Windows/macOS）和Linux，没有 /etc/docker/daemon.json 编辑，无需重新启动Docker。

代理允许什么： 容器创建/启动/附加/等待/删除、图像检查、容器列表和检查（用于 --volumes-from 分辨率），加上ping和版本。

代理阻止的内容： POST /build （图像构建）， /containers/<id>/exec （执行到兄弟容器中）， POST /commit （快照到图像）， /networks/create, /volumes/create，所有swarm/services/secrets/configs/plugins端点，并在工作区前缀之外绑定挂载源（因此 -v /:/host 并且在创建时拒绝任意主机根装载）。

绑定源过滤仅适用于Linux/macOS主机（v3.18.1）： 底层代理需要一个Linux主机路径作为其绑定源列表。在Docker桌面/Windows上，工作区是一个Windows路径（例如。 C:\Users\...)，因此Voltron省略了这一规则，而不是让代理无法启动并阻止所有调度。上述所有其他允许/拒绝规则仍然适用于所有平台。

剩余风险： 代理不会检查 Privileged 或 PidMode 创建正文中的字段。代理仍然可以请求特权容器，除非可选的OPA AuthZ插件(voltron/socket-proxy/opa-authz/voltron-authz.rego)部署在主机守护进程上。代理增加了有意义的深度防御；它并没有消除在共享守护进程上授予任何代理容器创建权限的核心风险。 仅在受信任的开发人员计算机上运行Voltron，并使用您信任的提示。

Unity编辑器异常：通过代理工具自动编排

run_agent_in_docker 是 主要调度路径 （Docker，隔离，并行安全）用于所有项目类型中95%以上的工作。Unity项目有一个狭隘的例外：四个编辑器绑定的管理器需要一个带有Coplay MCP的实时Unity编辑器，而Docker无法提供。scrum master通过内置的 Agent 工具代替。

• 编辑器异常管理器（仅限Unity）： scene-architect （场景层次结构、预制件、组件）， build-validator （播放模式、控制台、编译状态）和编辑器预览切片 shader-artist （视觉材质/着色器预览）和 asset-manager （纹理/音频/网格导入设置）。所有四个都通过主机运行 Agent 使用Coplay MCP驱动实时编辑器。
• 只有文件的Unity工作仍然通过Docker： C#脚本编写/重构(csharp-dev)，着色器代码编辑(.shader/.hlsl/.shadergraph), Packages/manifest.json 更新， asmdef 编辑和文件夹/资产结构更改都是通过以下方式发送的 run_agent_in_docker如果一个任务可以在没有实时编辑器反馈的情况下表示为文件编辑，那么它就是Docker的工作。
• Web/一般项目：也不例外。 web、全栈或通用项目中的每个代理都要经过 run_agent_in_docker。编辑器例外仅适用于Unity。

管理者组成微代理，他们从不直接写文件

副经理喜欢 csharp-dev, fullstack-dev, qa-tester, devops-engineer, scene-architect, shader-artist, build-validator，以及 asset-manager 他们是管弦乐者。对于每次文件更改，他们都会调度匹配的Tier-3微代理（例如。 csharp-script-writer, route-adder, test-writer, config-editor)via run_agent_in_docker。这是每个子经理模板中的停止规则，经理们从不DIY。

未来增强： 将每个试剂容器分开，以便在专业试剂之间隔离爆炸半径。

动态模型选择

Voltron根据每个代理的角色为其分配默认模型层。当微代理失败或产生低质量输出时，子经理和协调员可以在每次调用时覆盖此设置。

以（权力）否决 通过 model: "sonnet" 或 model: "opus" 到 run_agent_in_docker / run_agent_in_docker_batch 在更高层重试微代理。当输出不令人满意时，指示副经理自动执行此操作。这 list_templates 该工具显示每个代理的默认模型层。

进度跟踪

scrum master使用内置的MCP工具跟踪代理任务进度。当创建工作计划时，scrum master会立即将所有任务注册为“排队”，然后在代理被派遣和完成时更新其状态。

• update_progress，记录任务状态更改（排队、正在进行、已完成、失败、已阻止）
• get_progress，在聊天窗口中返回格式化的进度摘要或详细的任务表

进度数据保存在 .voltron/progress.json.

Eval安全带(voltron-evals/)

Voltron自我评级。这 voltron-evals/ 目录包含一个小的Node工具，它可以对任何可调度的代理运行基准任务，捕获运行的工件，并调度一个新的内部 voltron-judge 代理人根据固定的、版本化的评分标准对跑步进行评分。

双层设计：

• 深：手工编写的T1/T2/T3任务，针对夹具端到端地锻炼特定代理。每个任务都有一个配对的量规和 voltron-judge 引用文件的记分卡：行证据。
• 宽的：代理模板驱动的覆盖率。每个代理声明一个“形状”（输入合同+调度期望+接受信号）；运行者为每个shape×agent枚举一个实例，并使用程序信号和Haiku判断器进行判断。目前生成了70个Broad实例。

在本地运行它：

node voltron-evals/runner.js --tier=pr           # PR-tier: all Tier-1 Deep + 10-instance Broad sample (fast)
node voltron-evals/runner.js --tier=all          # full Deep + Broad sweep
node voltron-evals/runner.js --tier=deep         # Deep only
node voltron-evals/runner.js --tier=broad        # Broad only
node voltron-evals/runner.js --task=T1-001       # one specific task
node voltron-evals/runner.js --doctor            # validate schemas, rubrics, shapes, instance enumeration (no LLM)

完整设计规范： voltron-evals/DESIGN.md，涵盖了两层架构、形状契约、判断路由（Opus for Deep，Haiku for Broad）、内容哈希缓存 src/templates.js，以及量规固定协议。

CI节奏： .github/workflows/voltron-evals.yml 对 每月1日12:00 UTC，加上手动 workflow_dispatch内容哈希缓存意味着只有自上次扫描以来模板发生更改的代理才支付LLM成本；记分卡作为CI工件上传。

布局：

voltron-evals/
  DESIGN.md                       - full design spec (architecture, shapes, caching, judge routing)
  README.md                       - quick-start
  schemas/task.schema.json        - JSON Schema for task YAMLs
  shapes/                         - Broad-layer shape definitions (input / dispatch / acceptance)
  tasks/                          - hand-authored Deep task definitions
  instances/                      - generated Broad instances (one per agent × shape)
  rubrics/                        - pinned, versioned rubrics (rubric_version frontmatter)
  lib/artifacts.js                - capture helpers (git diff, bd list, log tail)
  lib/programmatic-scorers.js     - deterministic no-LLM signals (turns, [DONE], dispatch grep, …)
  lib/template-hash.js            - content-hash key for scorecard caching
  lib/fixtures/                   - per-task fixtures the AUT operates on
  runner.js                       - orchestrator (loads YAML, dispatches AUT + judge, merges scorecard)
  results/<task>/<ts>/            - per-run artifact bundles + scorecard.json

跑步是如何进行的：

1. Runner加载任务YAML并验证 schemas/task.schema.json.
2. Runner快照预状态(git rev-parse HEAD, bd list --json, reflections/ 上市）。
3. 跑步者通过以下方式派遣AUT run_agent_in_docker 随着任务提示和 max_turns 预算。
4. Runner在状态后进行快照，跟踪AUT的日志，捕获任何新的反射。
5. 程序化记分员先跑，然后进行回合计数， [DONE] 存在、预算利用率、文件更改、子调度grep、beads diff。这些作为法官不能不同意的原始测量值注入到法官提示符中。
6. 跑步者派遣 voltron-judge （默认模型：Sonnet），带有量规和工件路径。法官发出一声围栏 json 根据标准判断的记分卡块(MET / UNMET / PARTIAL / CANNOT_ASSESS)并引用文件：行证据。
7. Runner解析带围栏的JSON，与编程信号合并，并写入 voltron-evals/results/<task>/<ts>/scorecard.json.
8. 记分卡镜像到 reflections/<ts>-eval-<task>.json 包裹在标准反射封套中，因此现有 harness-engineer 自我改进循环将失败的标准作为可操作的模板编辑建议。

压条钉扎： 每个任务用YAML命名一个量规路径和一个 rubric_version_expected （森弗）。如果评分标准是 rubric_version frontmatter不匹配，这防止了目录编辑和用于评分的量规权重之间的无声漂移。

防回路保护： 该线束产生的反射(project_name: voltron-eval-harness)不得由以下人员使用 harness-engineer 要修改 voltron-judge 模板。这将使法官忽略检测失败。仅在以下情况下进行人为变更控制 voltron-judge.

添加任务： 放入一个YAML tasks/，写一个标题Markdown rubric_version: 1.0.0 frontmatter，可选择在下面添加固定装置 lib/fixtures/<task-id>/，然后运行 node voltron-evals/runner.js --task=<id>.

许可证

麻省理工学院