Task_docs/CORAL_TASK_CONFIGURATION_GUIDE.md

CORAL Task 文件夹说明

1. 常见目录结构

task_name/
├── task.yaml          # Task 主配置
├── snapshot.yaml      # 可选：开启 snapshot 收集
├── seed/              # Agent 的初始代码和可见文件
├── eval/              # Legacy grader 使用
└── grader/            # Packaged grader 使用

eval/ 和 grader/ 通常只使用其中一种。

组成	用途
task.yaml	配置任务描述、grader、Agent、workspace 和运行方式
snapshot.yaml	配置是否导出 snapshot 以及输出路径
seed/	Agent 最初拿到并持续修改的代码，可以包含 pyproject.toml、opencode.json 和数据文件
eval/	Legacy grader 及其隐藏测试数据，运行时复制到 .coral/private/eval/
grader/	Packaged grader 的独立 Python package

task.yaml 的主要部分：

• task：任务名称、描述和提示；
• grader：评分器、分数方向、超时和参数；
• agents：正常 CORAL 使用的 Agent、模型和 heartbeat；
• workspace：seed 路径、结果目录和 Agent 代码环境的安装命令；
• run：local、tmux 或 docker 等运行方式。

2. Legacy grader：支持

task_name/
├── task.yaml
├── seed/
└── eval/
    └── grader.py

grader:
  timeout: 600
  direction: maximize
  args:
    program_file: solution.py

识别方式：

• 没有 grader.entrypoint；
• 存在 eval/grader.py；
• grader.py 导出 Grader(TaskGrader)；
• grader 不需要 grader.setup，也不需要独立 grader venv。

这里的“不需要 uv”只指 grader。Agent 代码有依赖时，workspace.setup 仍可使用 uv sync。

示例：CORAL/examples/math/signal_processing/。

3. 静态 Packaged grader：支持

task_name/
├── task.yaml
├── seed/
└── grader/
    ├── pyproject.toml
    └── src/task_grader_package/grader.py

grader:
  entrypoint: "task_grader_package.grader:Grader"
  setup:
    - "uv pip install -e ./grader"
  timeout: 600
  direction: maximize
  args:
    program_file: solution.py

识别方式：

• task.yaml 有 grader.entrypoint；
• grader.setup 将 package 安装到独立 grader venv；
• 使用固定测试、数据和评分规则；
• 一次评分不会改变后续评分所使用的 reward。

写入本次 eval logs 或临时文件不算动态，只要它们不改变后续评分规则。

示例：CORAL/examples/erdos/、dna_design/、drug_design/。

4. 动态 Packaged grader：不支持 Trajectory collection

它的目录结构与静态 packaged grader 相同，必须查看 grader 行为才能区分。

以下情况属于动态 grader：

• 持续修改 rubric；
• 保存并恢复 judge session；
• 根据历史 attempt 改变测试集、阈值或评分标准；
• 在 .coral/private/ 保存会影响后续 reward 的状态；
• 不同 tree branch 不能彼此独立评分。

示例：CORAL/examples/apex-eggshell-skull/、apex-frontier-bu/。

这类任务可能支持普通 CORAL，但当前 snapshot-rooted trajectory collection 不支持。

5. 合法性与支持情况

类型	正常 CORAL	Snapshot	Trajectory collection
Legacy grader	支持	支持	支持
静态 packaged grader	支持	支持	支持
动态 packaged grader	可能支持	不完整	不支持

以下配置非法或不可用：

• 既没有 eval/grader.py，也没有 grader.entrypoint；
• grader.entrypoint 不是 module.path:ClassName；
• entrypoint 不存在或不是 TaskGrader 子类；
• grader.setup 失败，package 无法导入；
• grader.private 指向不存在的文件；
• grader.direction 不是 maximize 或 minimize；
• seed 缺少 grader 要求的文件或接口；
• task 描述、文件名、函数签名或分数方向与 grader 不一致。

6. 快速判断

1. 有 eval/grader.py、无 grader.entrypoint：Legacy grader，支持；
2. 有 grader.entrypoint：Packaged grader；
3. Packaged grader 没有影响后续 reward 的持久状态：静态，支持；
4. Packaged grader 会改变后续 reward：动态，当前不支持。