如何用CORAL自动研究框架编写第一个任务？coral init + task.yaml实战教程

CORAL 自动研究框架是一款开源的 autoresearch 基础设施，它让 Claude Code、OpenCode、Codex 等编码智能体并行跑实验、共享知识、自动评分并持续进化。这篇教程带你从零到一：先用coral init一键生成任务模板，再读懂task.yaml的核心字段，5 分钟内就能启动你的第一个多智能体自动研究循环——不需要你成为 AI Agent 专家。

CORAL 自动研究框架能做什么？

给 CORAL 一个代码库和一个评分器（grader），剩下的它全包了：

• 隔离工作区：每个智能体拥有独立的 git worktree，互不干扰
• 自动评分：grader daemon 为每一次提交打分，分数即时反馈
• 共享知识：attempts、notes、skills 存放在.coral/public/，所有智能体实时可见彼此的进展
• 心跳机制：manager 会周期性打断智能体，触发reflect（复盘）、consolidate（整合）、pivot（转向）等动作

如上图所示，coral start之后会依次创建共享状态目录、为每个智能体克隆独立工作区、软链共享目录、生成CORAL.md指令文件，最后并行启动 N 个智能体，进入"读榜 → 规划改码 →coral eval评分 → 写笔记"的自主循环。

一键安装 CORAL 完整步骤

前置要求：Python 3.11+、git，以及至少一个已登录的智能体运行时（Claude Code 为默认，也可选 Codex、OpenCode、Cursor Agent、Kiro）。

# 安装 uv（如已有可跳过） curl -LsSf https://astral.sh/uv/install.sh | sh # 用 uv tool 全局安装 CORAL CLI uv tool install git+https://gitcode.com/gh_mirrors/coral22/CORAL.git # 验证 coral --version

安装脚本 install.sh 支持CORAL_VERSION=<tag>锁定版本，后续可用uv tool upgrade coral原地升级。

第 1 步：coral init 生成任务模板

coral init my-task

一条命令即生成一个自包含的任务目录（脚手架逻辑见 coral/cli/author.py）：

my-task/ ├── task.yaml # 任务配置 + grader 入口 ├── seed/ │ └── solution.py # 智能体迭代的基线代码 └── grader/ # 独立 Python 评分包 ├── pyproject.toml └── src/my_task_grader/ ├── __init__.py └── grader.py # class Grader(TaskGrader)

三个部件各司其职：seed/是智能体开工时看到的初始代码；grader/是评分逻辑（会被安装到隔离 venv）；task.yaml把它们串起来。

第 2 步：读懂 task.yaml 核心配置

init生成的task.yaml已经可运行，你主要改这几处：

task: name: "my-task" description: | # 智能体逐字读取的任务描述，写清楚"输入输出契约" 描述你的任务，指明 solution.py 必须做什么。 grader: entrypoint: "my_task_grader.grader:Grader" timeout: 300 # 单次评测超时（秒） direction: maximize # maximize 或 minimize args: program_file: "solution.py" agents: count: 1 runtime: claude_code # claude_code | codex | cursor | kiro | opencode

完整字段清单（含islands、heartbeat、sharing等高级配置）见 examples/README.md 与 docs/content/docs/getting-started/configuration.mdx。

💡 小技巧：顶层可加preset:引用内置预设（如 coral/template/presets/ 下的local-claude、docker-opencode），免去重复样板配置，且 task.yaml 中显式字段始终优先于 preset。

第 3 步：编写 Grader 给智能体打分

脚手架已内置一个可用的Grader(TaskGrader)存根：运行solution.py，从 stdout 解析一个浮点数作为分数。自定义评分只需重写evaluate()，常用属性与工具方法：

• self.codebase_path— 智能体工作区（只读）
• self.private_dir—.coral/private/，存放智能体看不到的答案文件
• self.run_program(filename)/self.score(value, explanation=...)/self.fail(reason)

⚠️ 安全要点：grader/目录内的所有源码都会对智能体只读可见（它们需要知道评分规则），所以答案键、隐藏测试集必须放在grader/之外（惯例是同级taskdata/目录），并通过grader.private声明，coral validate会拦截泄漏风险（校验逻辑见 coral/cli/validation.py）。

一个真实任务参考：examples/circle_packing/task.yaml——把 26 个圆塞进单位正方形使半径和最大，description 里连约束公式和候选思路都写清楚了，值得抄作业。

第 4 步：coral validate 干跑评分器

启动智能体之前，务必先验证评分链路：

coral validate my-task

它会：校验task.yaml结构 → 在.coral/private/grader_venv/构建隔离 venv 并执行grader.setup→ 对seed/基线代码跑一次完整评分，输出首个分数。看到分数打印（哪怕是 0.0）就说明评分器工作正常。

第 5 步：coral start 启动多智能体研究

cd my-task coral start -c task.yaml # 启动智能体 coral log # 查看排行榜 coral status # 查看智能体健康状态 coral ui # 打开 Web 仪表盘 coral stop # 完成时停止

启动后每个智能体会自主循环：读取CORAL.md→ 调研与规划 → 修改代码 → 调用coral eval -m "方案说明"→ 根据分数与反馈迭代，并把发现写入共享 notes 与 skills。manager 在后台监控 attempts，按task.yaml中配置的 heartbeat 周期触发反思与知识整合——多智能体由此互相"催更"，持续进化。

新手避坑清单与进阶示例

• ❌方向搞反：优化耗时/误差的任务记得direction: minimize
• ❌超时不提示：评测超时会直接记 0 分，用task.tips明确告知智能体超时上限
• ❌答案放错位置：grader.private路径放进grader/会导致泄漏，validate 直接报错
• ✅复杂依赖：grader 额外依赖（numpy、torch 等）写进grader/pyproject.toml的dependencies

想直接跑现成任务试试手感？仓库 examples/ 目录内置了 170+ 个任务，覆盖数学（circle_packing、erdos）、ML（mnist）、系统优化（kernel_builder）等方向：

coral start --config examples/circle_packing/task.yaml

总结

整个流程只有四行核心命令：

coral init my-task # 1. 生成模板 coral validate my-task # 2. 验证评分器 coral start -c task.yaml # 3. 启动自动研究 coral log # 4. 围观进化

coral init负责搭骨架，task.yaml负责定规则，grader 负责打分，剩下的交给 CORAL 自动研究框架的多智能体进化循环。更多细节可继续查阅 docs/content/docs/getting-started/quickstart.mdx 快速上手指南与 README.md。