Human-Agent-Society/CORAL · 上手攻略

  • 仓库：Human-Agent-Society/CORAL
  • 链接：https://github.com/Human-Agent-Society/CORAL
  • 分类：AI / Agent Infra / 自动研究（autoresearch）
  • 作者：spark
  • 更新：2026-08-23

1. 是什么

CORAL 是一个面向「自动研究 / 自动进化」场景的多智能体基础设施。它不是某个具体模型，而是把"让多个 coding agent 持续跑实验、共享笔记、互相学习、迭代解法"这件事做成一套可以一键拉起的运行时：把现有代码库喂给它，再配一个打分器（grader），CORAL 就接管剩下的活——隔离工作区、跑评估、维护共享状态、调度多 agent 协作。

原生对接 5 个 agent runtime：Claude Code、OpenCode、Codex、Cursor Agent、Kiro。论文《CORAL: Towards Autonomous Multi-Agent Evolution for Open-Ended Discovery》已被 COLM 2026 接收（arXiv: 2604.01658）。当前版本 v0.7.14（2026-07/08 期间发布），仓库 Apache-2.0。

2. 解决什么问题

如果你做过下面任何一件事，就会懂它的价值：

  • 让一个 coding agent 反复改同一段代码、调超参、跑测试，希望它自己越改越好；
  • 想并行跑多份「改动方案」对比效果，又不想让它们互相踩踏工作树；
  • 每次跑完想让 agent 把「这次为什么有效/无效」记下来，下次不要重复犯；
  • 想用 Claude Code 写、又偶尔想切到 Codex，但不想重新搭一遍评估框架。

传统做法是手搓 shell 脚本 + git worktree + cron。CORAL 把这套工程模式产品化：

  • 每个 agent 跑在独立的 git worktree 里，互不干扰；
  • 共享状态（attempts / notes / skills）放在 .coral/public/，通过符号链接实时同步到所有 worktree——agent 之间能看到彼此的工作；
  • grader 守护进程给每次 commit 打分，分数持久化；
  • manager 用「heartbeat」节奏打断 agent 去做反思 / 整理 / 必要时换方向（pivot）；
  • v0.6.0 起支持多岛（multi-island）：把 agent 分成几个独立群组，各自在自己的小生态里探索，再做岛间迁移，拓宽探索面。

适用边界：任务是「有可量化指标 + 可以在代码层修改」的开放式问题（数学猜想、kernel 优化、Kaggle 比赛、mRNA 预测等都行）。如果任务只能靠人主观判断、或者没有代码改动空间，CORAL 帮不上忙。

3. 快速安装

3.1 一键安装（推荐）

# 全局安装最新发布版（通过 uv tool install）
curl -fsSL https://raw.githubusercontent.com/Human-Agent-Society/CORAL/main/install.sh | sh

# 如需固定版本
CORAL_VERSION=v0.7.14 curl -fsSL https://raw.githubusercontent.com/Human-Agent-Society/CORAL/main/install.sh | sh

依赖前置：Python 3.10+、uv（推荐用于包管理与隔离）、网络可达 GitHub。部分内置 grader（如 SWE-bench、terminal-bench）依赖 Harbor 在 Docker 容器里跑评估，CORAL 自身不要跑在 Docker 里（不支持 Docker-in-Docker），宿主机直跑。

3.2 手动 / 开发者安装

git clone https://github.com/Human-Agent-Society/CORAL.git
cd CORAL
uv sync --extra dev          # 装开发依赖
uv run pytest tests/ -v      # 跑测试
uv run ruff check .          # lint
uv run ruff format .         # format

3.3 装 Agent 插件（可选，但更顺手）

如果你平时就在 Claude Code / Codex 里干活，推荐装 CORAL 的 plugin：它不引入 MCP，而是把整套工作流（setup → init/validate → start/status/log）拆成一组 skills，会话启动时自动检查 coral 是否装好。

Claude Code：

/plugin marketplace add Human-Agent-Society/CORAL
/plugin install coral@coral-marketplace

Codex（v0.117.0+）：

codex plugin marketplace add Human-Agent-Society/CORAL
codex plugin add coral@coral-marketplace

4. 核心用法

4.1 三行上手

coral init my-task            # 在当前目录生成任务脚手架（含 task.yaml 等）
cd my-task
coral start -c task.yaml      # 启动 agents，开始自动迭代

4.2 最小可跑示例（Plugin 路径）

最舒服的入口是让 Claude Code / Codex 替你完成「scaffold + grader 编写 + 启动前校验」这一长串琐事。比如打开任意代码仓库，对 Claude Code 说：

use coral to optimize this — make sample() in saga/decode.py faster without changing its output

Plugin 会自动：

  1. 在仓库里建一个 gitignored 的 .coral_workspace/；
  2. 把目标代码复制进 seed/；
  3. 根据你的目标指标写一个 grader；
  4. 反复跑 coral validate，直到 task 达到可启动状态；
  5. 把 coral start 命令交给你运行。

Claude Code 还内置了 coral-task-author 子 agent（包揽整套脚手架）与 coral-run-doctor（运行卡住时诊断）。

4.3 看运行状态 / 日志

coral status                  # 查看本次任务的实时状态
coral log                     # 查看 agent 输出与打分日志

4.4 切换 Agent Runtime

默认是 Claude Code。要切到别的 runtime，改 task.yaml 里 agents.runtime：

agents:
  runtime: codex        # 可选：claude_code / codex / cursor / kiro / opencode

⚠️ 每个 agent runtime 必须单独装好并完成登录授权，CORAL 不会替你管理它们的 API key。

4.5 自定义 Grader

v0.6.x 起，旧的 eval/grader.py 自动发现机制已被移除（2026-06-13 起）。grader 必须通过 grader.entrypoint 指向一个已打包的 grader 包。具体写法见官方 custom grader guide。

如果你想做"开放式任务"（写报告、法律分析、备忘录之类没有标准答案），可以用官方提供的 rubric judges——两个可复用的 LLM-judge grader 包，详见 Rubric Judges guide。

4.6 用 LiteLLM 网关接自定义模型

如果你的主力模型不在 Claude Code / Codex 默认支持名单里，可以挂 LiteLLM 网关做统一代理。配置在 agents.runtime 下，文档见 Agent Runtimes 与 LiteLLM gateway 指南。

4.7 跑现成任务

仓库自带 7 个可跑示例，覆盖优化、数学、系统、ML、生物等领域：

任务 领域 说明
circle_packing 优化 在单位方格里塞 26 个圆，最大化半径之和
erdos 数学 解一个数学猜想
kernel_builder 系统 VLIW SIMD kernel 优化
kernel_engineering 系统 GPU kernel 优化
mnist ML 手写数字分类
spaceship_titanic ML Kaggle 比赛
stanford_covid_vaccine Bio/ML mRNA 降解预测

完整目录与每条任务的手把手讲解见 Examples docs。

5. 典型适用场景

  • 代码级优化 / 重构类开放任务：性能调优、kernel 编写、模型压缩、超参搜索。比人肉 prompt 更适合"需要反复试 + 需要记住前几次为什么失败"的场景。
  • Kaggle / 评测类比赛：因为 grader 简单（直接读分数文件），起一个 agent 群跑 ensemble / 特征工程。
  • 学术 / 工程研究中的小探索：对某个小问题（比如"在这个数据集上有没有更好的损失函数"），让 CORAL 跑一晚上，第二天看 attempts 摘要。
  • 多 agent 对比实验：想看不同 agent 在同一任务上的策略差异，可以分岛跑，结束时对比 attempts。

不适用：纯对话场景、纯写作（没有代码改动空间）、一次性脚本、单文件改改就完的事（用 CORAL 反而是杀鸡用牛刀）。

6. 坑与注意

  • ⚠️ 不要把 CORAL 跑在 Docker 里：用 Harbor 评估 SWE-bench / terminal-bench 等任务时需要 Docker，但 CORAL 自身不支持 DinD，必须宿主机直跑。
  • ⚠️ grader venv 是「private」：2026-06-24 起 Docker session 会把 agent 隔离到非特权用户，agent 看不到 .coral/private/（grader 的 venv、答案 key 等），Bash 也读不到。要在宿主机上给 grader 留特权时，开 agents.isolate_user（opt-in）。
  • ⚠️ 每次跑前先 coral validate：直接 coral start 一个没校验过的 task 容易卡在 grader 报错上。Plugin 路径会自动跑校验。
  • ⚠️ 多 agent 跑久后日志会爆：attempts / notes / skills 全在 .coral/public/ 里，长跑（几天）要注意磁盘。仓库本身没有内置自动 rotate，需要自己管。
  • ⚠️ arXiv ID 是 2604.01658，不是 2604.01658v1 后被替换的版本：论文就是 v1，引用时按 v1 写。
  • ⚠️ v0.7.14 是本文撰写时 GitHub releases 页最新的 tag（PR #223 之后），具体 hex SHA 未在 README 直接给出，运行建议显式 pin tag。

7. 与同类对比

  • vs Karpathy 的 autoresearch：autoresearch 是单 agent、单任务的极简脚本；CORAL 是多 agent + 多 runtime + 共享状态 + 多岛的产品化版本。
  • vs OpenEvolve：OpenEvolve 偏 LLM-driven 进化算法研究框架，强调遗传算法风格；CORAL 更像「基础设施 + 工作流」，多 agent 协作 + git worktree 是默认形态。
  • vs TTT Discover：TTT Discover 是学术论文层面的思路（test-time training for discovery）；CORAL 是把类似思路工程化落地的实现层。
  • vs 自己搓 cron + worktree 脚本：CORAL 省掉 80% 工程量，代价是多一层抽象（多学一组 CLI），且共享状态模型需要适应一下。

8. 一句话推荐

如果你的研究 / 工程任务属于「代码层能改 + 有量化指标」这一类，CORAL 是当前（2026-08）最省心的多 agent 自动研究基础设施——装好 plugin、丢一段 prompt，剩下的让 agent 群自己卷。

参考链接：

  • 论文：https://arxiv.org/abs/2604.01658v1
  • 文档站：https://coral.compounding-intelligence.ai/docs/
  • 示例集：https://coral.compounding-intelligence.ai/docs/examples
  • 博客：https://coral.compounding-intelligence.ai/blogs/evolve-like-coral/