blender-agent-benchmark

Blender Agent Benchmark

每项任务开始时，阅读一次共享执行指南，了解自主决策、证据采集频率和长任务连续性。

使用相同的任务、模型、投入程度、限制、Blender 构建版本和评估器来衡量变化。保留 Agent 的自然行为。

随附的运行器通过 --agent codex（默认值）或 --agent claude-code 选择受测 Agent。从 Claude Code 启动运行器不会改变此选择。报告记录的 Agent CLI、请求的模型和观测到的模型标识符；不要根据启动运行器的主机推断这些信息。

保护基准完整性

1. 为每种条件和每次重复创建隔离目录。
2. 不要让另一种条件的代码、渲染图、指标或预期修复出现在 Agent 能发现的位置。
3. 除插件条件中明确调用技能外，面向用户的任务提示必须保持一致。
4. 无插件基线使用 codex exec --ignore-user-config。
5. 插件条件使用全新调用，并指定固定的插件目录。默认使用包含运行器的插件；--skill-root 可选择其他快照。
6. 记录 CLI 版本、模型、投入程度、Blender 构建版本、耗时、工具调用、失败情况和输出哈希。
7. 在生成完成后评估输出。不要向 Agent 泄露隐藏的评分细则。

更改测试夹具、评分或对比结论前，请阅读 references/methodology.md。 选择加入的 scenes 和 game_characters 套件各增加三项任务，其中包括独立留出任务。请阅读场景与角色协议，了解自定义摄像机证据、仅交付渲染图和变形检查。 设计新套件或借鉴其他 Blender 基准的评估思路时，请阅读 references/open-source-benchmark-landscape.md。 仅在审查插件记录的验证结果时阅读 references/validated-results.md，不要在生成基准提交内容时阅读。

快速开发循环

改进工作应从已保存的失败证据着手，而不是再次运行完整生成套件。针对单项定向修复，默认将墙上耗时预算设为 5 分钟：

1. 找出现有已保存资产中影响最大的可见缺陷。
2. 将其持久源文件和输入复制到新的修复目录。保留原始资产和图像，作为修复前状态。
3. 使用选定的模型进行一次本地源文件修复。在受影响区域之外保留良好的比例、轮廓、材质和细节；不要从头重建资产，也不要为了满足数值检查而简化资产。
4. 重新生成一次，并使用 blender_render_evidence，请求分辨率为 256 的两个相关固定视图。修复前后使用相同且明确的展示和取景输入。打开图像；必要时检查完整尺寸视图。
5. 检查结果，确认所述缺陷是否已修复，以及成品效果是否有损失。只有在实验明确要求时才使用单独的模型。如果修复没有带来可见改善，则保留原始版本。记录耗时、具体的源文件更改和任何尚未解决的弱点。

这是修复演示，并不能证明模型的整体能力有所提升。输入未变时，复用现有的确定性指标。编辑后运行受影响的技术测试；对保留的候选版本完整运行一次导出/多视图检查。只有在提出发布级能力结论或收到明确要求时，才反复从头生成并使用多个独立评审。不要把小型修复变成无人值守、持续数小时的任务。

运行套件

对于 Astra，传入 --profile astra（模型为 gpt-6-astra，推理力度为 medium）。sol、terra 和 luna 配置会以相同的推理力度选择各自对应的 GPT-5.6 模型。显式指定 --reasoning 会覆盖推理力度，而不会覆盖模型。要进行可复现的比较，请使用显式配置或 --model；使用 configured default 运行仅供探索，因为模型身份并未固定。

将实验分开进行：先在 Astra 上测试旧版和修订版技能，再在 Astra/Sol/Terra/Luna 上测试固定的修订版技能。固定测试样例、实际推理力度、Blender 版本、限制、权限和评估器。现有的非回归门槛要求模型一致；跨模型结果仅用于描述模型间的差异，不能证明技能修订带来了改进。绝不要将历史结果标签替换为 Astra，也不要将模型和技能同时变更的结果归因于其中任何一项。

使用 scripts/run_benchmark.ts：

bun "<skill-root>\scripts\run_benchmark.ts" `
  --suite quick `
  --mode baseline `
  --output "<run-root>\baseline"

bun "<skill-root>\scripts\run_benchmark.ts" `
  --suite quick `
  --mode plugin `
  --output "<run-root>\plugin"

先用冒烟任务验证测试框架。要声称整体能力有所提升，至少使用三个有代表性的任务，并重复运行。

使用 scripts/compare_runs.ts 进行随机盲法多视角评审。使用 scripts/rescore_run.ts 在更改评分器后重新计算确定性分数，无需重新运行 Agent。

将 full 作为历史回归测试套件。使用选择性启用的 challenge 套件测试更具挑战性的环境、程序化建模、绑定／形变和仿真任务，避免因扩大覆盖范围而在不知情的情况下改变传统比较：

对静态角色造型、行走循环、面部表情组合、液体倾倒和布料悬垂使用 quality。对双视图图像重建，使用带有 --reference-dir 的 reference。这些套件会添加需要评估的动作和烘焙前置条件，但不能替代视觉审查。有关输入约定和局限，请阅读质量套件协议。请使用受理案例单独评估澄清能力；完整定义的资产测试样例明确禁止追问，因此无法衡量澄清质量。

bun "<skill-root>\scripts\run_benchmark.ts" `
  --suite challenge `
  --mode skills `
  --condition-label revised-plugin `
  --output "<run-root>\revised-challenge"

challenge 套件还包含 realistic_fire_lantern_showcase，这是一个独立的、接近作品集展示水准的灯具任务，包含一段 360 帧的移动火焰动画，并要求生成 15 秒的 MP4。使用选择性启用的迭代工作流，只运行此任务：

bun "<skill-root>\scripts\run_benchmark.ts" `
  --suite challenge `
  --tasks realistic_fire_lantern_showcase `
  --mode skills `
  --condition-label cached-iterative-fire-lantern `
  --skill-root "<installed-plugin-directory>" `
  --output "<run-root>\fire-lantern"

此测试样例要求提供 lamp_fire_15s.mp4、iteration_review.json、在 24 fps 下制作并导出的第 1 至 360 帧动作、六视图证据，以及采样的火焰帧。运行器会使用 PATH 中的 ffprobe，或在设置了 FFPROBE_EXECUTABLE 时使用该路径下的可执行文件，来检查视频时长、帧率和帧数。

对刻意未饱和的集成任务，使用选择性启用的 gauntlet 套件。该套件在同一个因果场景中组合了环境、可编辑的程序化传送带、已绑定的机器人、由仿真驱动的胶囊体运动、确定性动画、材质、灯光、导出，以及修复前后的证据：

bun "<skill-root>\scripts\run_benchmark.ts" `
  --suite gauntlet `
  --mode skills `
  --condition-label candidate-gauntlet `
  --output "<run-root>\candidate-gauntlet"

使用至少三名盲法评审员比较 gauntlet 提交结果。比较报告会为此任务提供 verifiedScores：60% 为确定性评分，25% 为任务专属视觉标准，15% 为广泛的多视角质量评分。硬性门槛未通过时，结果上限为 49；任一关键标准未获多数通过时，上限为 84；任一标准未获多数通过时，上限为 94；若确定性评分并非满分、标准未获一致通过，或任一视觉维度未达到优异水平，结果上限为 99。这样既能获得部分得分，也不会让单纯钻指标空子就足以达到饱和分数。

每项任务都包含明确标注类别的视觉标准。盲法评审员必须分别回答两位候选者是否满足每项标准；请将各项标准的通过率与广泛的审美维度评分及确定性评分分开统计。

非交互式 Codex 会取消需要审批的 MCP 工具调用。如果要测试 MCP 条件，请对所有比较条件传入 --bypass-approvals，并使用相互隔离的基准测试目录。不要只给 MCP 条件更宽泛的权限。 使用 scripts/benchmark_mcp.ts --asset <path> --output <new-dir>，验证 MCP 传输返回的确定性指标是否与直接 CLI 评估相同。结果一致证明的是传输正确性，而非建模质量提升。

对比条件

运行器通过进程本地 CLI 参数禁用全局插件、记忆、宿主技能条目和自动项目指令注入，同时保留明确提示的快照技能和 MCP。它不会编辑用户配置。仅使用 --ignore-user-config 无法隔离宿主技能。开展基准测试前，请在已安装的 CLI 上确认这些控制项。如果不支持这些开关，或 Windows 参数列表过长，必须先解决问题，再启动基准测试生成任务。

如果 Codex WebSocket 反复出现空闲失败，请在两个生成器和 compare_runs.ts 中使用 --codex-transport http。此进程本地的提供方保留现有的 OpenAI 登录，并选择 HTTP Responses 流式传输；它不会编辑全局配置。默认值为 auto。在溯源信息中记录传输方式，将中断的跟踪记录为基础设施故障，并在全新的目录中重启双方。恢复传输不代表建模质量提升。

固定插件运行会忽略用户配置，并按路径加载所选技能。在 skills_mcp 模式下，运行器会明确以 bas_benchmark 身份启动该快照的 mcp/server.ts，检查其工具清单，并通过源指纹记录该服务。请在 Agent 跟踪记录中确认是否实际使用了新工具；仅有可用工具但从未调用，无法证明其建模收益。Agent 事件和 stderr 会实时写入，并记录 PID 以便无人值守监控。重启工作前，请检查进程及最终进程记录。

评审完成前，请将评审身份保存在内存中。不要将条件映射文件放在评审者的工作目录中。每组对比使用相同的评审模型和推理力度，并明确记录所选模型。

请将以下维度分开评估：

• 执行／导出有效性；
• 提示词与结构合规性；
• 几何／游戏适用性；
• 表面处理风格合规性，包括精致平滑与明确的低多边形意图；
• UV、着色、细化、材质、纹理和呈现信号；
• 多视角视觉质量；
• 物理合理性；
• 适用时的动画质量；
• 上下文／导出正确性；
• 时间、轮次、工具故障和成本。

加权评分前先应用硬性门槛。与未经校准的绝对审美评分相比，优先采用盲测的两两视觉评审。 在不同评审者之间交替调整 A/B 图像顺序，并保留每位评审者的映射关系。 不要让较低的三角形数量抵消最终资产看起来像灰盒模型的问题。

将某个修订版本与当前插件进行比较时，请为运行指定不同的 --condition-label 值，并运行 compare_runs.ts --require-non-regression。 传入 --skill-root <plugin-directory>，将每次运行固定到确切的已检出或已安装插件版本，而不是全局当前启用的插件版本。 如果缺少基线配对、硬性门槛失守、任何单任务自动评分下降、盲测视觉评审多数评为较差，或某项关键视觉标准从多数通过变为多数不通过，门槛检查就会失败。不要用新挑战任务上的提升抵消历史测试集上的退步。

使用 compare_runs.ts --tasks <comma-separated-task-ids>，可将修复后的任务子集与较大的已保存基线进行比较，而不会把有意省略的基线任务视为缺失证据。

迭代

1. 检查失败指标、渲染图、视频和跟踪记录。
2. 找出一个可迁移的工作流缺陷。
3. 修改最小范围内相关的技能、确定性工具或 MCP 接口。
4. 重跑同一任务子集。
5. 保留修改前，先运行一个留出任务。

不要保留会泄露测试样例答案或损害常规建模行为的基准测试专用指令。