AIRAS

AIRAS —— 一个用于自动化研究的开源项目

AIRAS 是用于自动化研究的开源软件。它为编码 Agent（Claude Code、Cursor 或任何 MCP 客户端）提供了所需的一切，让其将一个研究主题依次推进文献综述、提出假设、开展实验，最终完成论文，并确保论文中的主张可验证：任何实验运行之前，论文都会在 git 中预注册；每个报告的数值都由运行输出得出；在生成正式 PDF 之前，CI 会重新检查所有内容。

AIRAS 以一个 PyPI 软件包（airas）的形式发布，提供：

• 一个 MCP 服务，包含工作流所需的研究工具（论文搜索、假设与实验设计、实验结果、图表渲染、LaTeX、Overleaf，以及记录和验证工具），
• 一个 Claude Code 插件，将服务与 auto-research 工作流技能打包在一起，
• 一个精简的 CLI（airas verify-record、airas verify-paper），供实验代码库的 CI 用作验证关卡。

目前，它专注于自动化机器学习研究。

快速开始

无需克隆，无需 Docker。只需安装 uv；uvx 会在首次运行时获取软件包。

1. 安装

AIRAS 旨在通过 Claude Code 插件来驱动。该插件会安装 MCP 服务、auto-research 工作流技能，以及用于记录 Agent 状态的钩子：

/plugin marketplace add airas-org/airas
/plugin install airas@airas

也可以单独使用 MCP 服务，不安装技能和钩子。在 Claude Code 中：

claude mcp add airas -- uvx airas

在任何其他 MCP 客户端中，将其添加到客户端的 MCP 配置中（例如 .mcp.json）：

{
  "mcpServers": {
    "airas": {
      "command": "uvx",
      "args": ["airas"]
    }
  }
}

升级。 uvx 会保留首次获取的版本，因此现有安装不会自动升级到新版本。运行一次 uv cache clean airas（或 uvx airas@latest）即可获取最新版本。

2. 配置凭据

凭据存放在 ~/.airas/credentials.json 中，并会在每次调用工具时重新读取，因此你可以随时创建或编辑该文件：

mkdir -p ~/.airas
cat > ~/.airas/credentials.json <<'EOF'
{
  "GH_PERSONAL_ACCESS_TOKEN": "ghp_...",
  "SEYVAL_API_KEY": "..."
}
EOF
chmod 600 ~/.airas/credentials.json

键	用途
GH_PERSONAL_ACCESS_TOKEN	必需。用于创建并驱动实验代码库（需要 repo + workflow 权限范围，并在该代码库中具有管理员权限）。
SEYVAL_API_KEY（以及可选的 SEYVAL_COMPUTE_ID、SEYVAL_WORKSPACE_ID）	使用 backend="seyval" 时需要：在 Seyval 计算平台上运行实验并交叉核验其来源。参见执行平台。
OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY / OPENROUTER_API_KEY / AWS_BEARER_TOKEN_BEDROCK / VERCEL_AI_GATEWAY_API_KEY	工作流不需要这些密钥：驱动 AIRAS 的 Agent 会在技能的引导下自行编写所有产物，而 get_prompts 会在你自行编写某个步骤时提供写作指导。只有在直接调用后端大模型工具（analyze_experiment，或带有 model 的 verify_paper_values）时才会用到密钥。

3. 启动研究项目

在 Claude Code 中，调用编排技能并提供一个主题：

/airas:auto-research

它会引导你完成以下工作流，并在开始时一次性询问你确定操作选项（代码库可见性、执行平台、计算目标）。其他 MCP 客户端则直接调用工具；每个工具的说明都会指出其前置和后续步骤，MCP 文档也会介绍整个工作流。

自动研究流程

auto-research 只负责步骤的排序以及贯穿各步骤的规则。每个步骤都是独立技能，并有明确的约定，因此你也可以在现有仓库上单独调用某个步骤。

步骤	技能	在仓库中留下的内容
1	setup-repository	基于 airas-template 创建并克隆实验仓库，配置 Actions 密钥，并保护 main 分支。此后，所有研究状态都保存在这里。
2	search-papers	在各个来源中找到论文，包括 airas-papers-db，并下载全文，供下一步阅读。
3	hypothesize-and-design	提出可证伪的假设，并设计实验，固定运行 ID、指标、模型、数据集和计算环境。
4	preregister-paper	在任何实验开始之前撰写完整论文，将内容写成带有判定标准和预测区间的编号声明。此步骤的提交是冻结点；.research/record.json 也在此处创建。
5	write-experiment-code	按照固定的执行约定编写实验代码（Hydra 入口点、sanity / pilot / full 模式），并通过锁文件和 Dockerfile 固定环境。指标由 airas-eval 生成，而非由代码本身生成。
6	run-experiments	在选定的后端（GitHub Actions 或 Seyval）上执行运行，并将输出连同溯源信息放回 .research/results/。请参阅执行平台。
7	analyze-results	进行分析并生成可验证的图表（Vega-Lite 图表、文本定义的图示）。
8	publish-paper	从记录中生成所有声明的数值，在本地通过编译和验证后推送。CI 会重新运行验证，并将 paper.pdf 提交到受保护分支，作为正式论文记录。

流程保证

• 先声明，再运行。 预注册提交创建之前，不会派发任何任务；每次运行都以该提交为基础。修正会在其上继续提交，不会通过变基将其抹去。
• 记录只增不减。 .research/record.json 是由假设、声明、设计、运行和结果组成的只追加树。改写声明、更改运行条件或删除结果，都会被同一项检查拦截。未达到判定标准的声明会作为负面结果报告，而不会被改写。
• 绝不手动输入实验数值。 论文中的数值只能通过 \airasval{...} 引用某次运行测得的指标或声明的参数，并从记录中生成。其他数值都会标记为 \unverified{...}。
• 门禁会强制执行，而非仅供参考。 分支保护会将验证工作流设为必需检查，因此红色运行无法被推送。
• 仓库就是状态本身。 后续步骤所需的一切都会提交到仓库，因此新的会话只需克隆仓库即可继续工作。

执行平台和大模型

无论使用哪种后端，实验都通过相同的三个 MCP 工具运行：dispatch_experiment 启动运行，get_experiment_run_status 跟踪运行状态，import_run_outputs 则从后端存储的位置（Seyval 的存储空间，或 GitHub Actions 中工作流的构件）复制输出，并附带溯源清单保存到 .research/results/。记录门禁会将已提交的字节与同一存储中的内容交叉核对；存储删除该次运行后，则会与导入时记录的 sha256 哈希值交叉核对。目前支持 Seyval（自带 Slurm 计算资源）和 GitHub Actions；暂不支持由你自行运行的机器（RunPod、实验室集群）作为后端，因为这类后端需要一个 Agent 无法改写的存储空间。

此工作流无需 LLM 密钥：Agent 在技能的指导下自行编写假设、设计、分析和论文。后端大模型工具（analyze_experiment，以及带有 model 的 verify_paper_values）和 get_prompts（向客户端提供它们所用的提示词）可在此工作流之外使用；前者需要提供商密钥（get_available_llms 会列出你的密钥可使用的模型）。支持的提供商：OpenAI、Anthropic、Google Gemini、OpenRouter、Amazon Bedrock 和 Vercel AI Gateway。

配套仓库

AIRAS 依赖 airas-org 组织下的三个同级仓库。每个仓库负责将工作流的一部分置于 Agent 的控制范围之外。

仓库	作用
airas-template	每个实验仓库都基于此模板创建。它提供 CI 工作流、执行约定和验证门禁。
airas-papers-db	精选的顶级会议论文数据库，Agent 可通过 search_papers 搜索，也可搜索 OpenAlex、Semantic Scholar 和 arXiv。
airas-eval	集中管理评估逻辑。指标由 airas-eval 根据运行的评估输入计算，而非由实验代码计算，因此 Agent 无法篡改自己的评分。

MCP 工具

auto-research 工作流使用以下工具；上文所述的技能是基于这些工具编写的简明约定。服务还提供更多工具，但以下是研究项目会用到的工具。

步骤	工具
setup-repository	prepare_repository、set_github_actions_secrets
search-papers	search_papers、dispatch_literature_fetch
hypothesize-and-design	get_prompts、retrieve_models、retrieve_datasets、search_huggingface_hub
preregister-paper	preregister_record、get_prompts、append_to_record、update_record、verify_latex
write-experiment-code	get_prompts、get_library_docs
run-experiments	dispatch_experiment、get_experiment_run_status、import_run_outputs、fetch_experiment_results
analyze-results	fetch_experiment_results、analyze_experiment / get_prompts、render_chart、render_diagram、append_to_record、update_record
publish-paper	verify_record、verify_paper_values、verify_latex、open_in_overleaf、get_workflow_runs

请参阅 MCP 文档，了解工具说明、各工具所需凭据及配置选项。

命令行

uvx airas                 # MCP server on stdio (default)
uvx airas verify-record   # check .research/record.json against run outputs, git history, and the platform
uvx airas verify-paper    # check paper values and citations against the record and run outputs — no PDF build
uvx airas verify-record --implementation-verifier-model <name>   # review implementation against declared designs
uvx airas verify-paper --citation-verifier-model <name>   # judge unjudged passage citations
uvx airas publish-paper   # build the paper's PDF for publishing (values already verified by the gate)

verify-record 会检查声明和执行证据；verify-paper 会独立核对论文与这些内容是否一致。这是实验仓库在受保护分支上运行 CI 时必须执行的两项检查；publish-paper 则会在单独的非必需发布工作流中构建 PDF。

开发

cd backend
uv sync
uv run airas

Lint 和类型检查通过 pre-commit 配置（每次克隆后运行一次 pre-commit install）。请参阅 CONTRIBUTING.md。

路线图

AIRAS 分阶段开发。可靠性优先：只有当输出值得信赖且可复现时，自动化研究流水线才值得扩展。

1. 可靠性（进行中）。 目前，研究记录保证论文中的每个数字都可追溯至已声明的运行及其输出；每项主张的判定结果均根据其在运行前声明的标准得出；CI 也会对此进行强制检查。这覆盖了论文，但还未覆盖论文上游的所有环节：操纵基准测试、泄漏测试数据或偏离设计的实验代码，仍会通过检查。目前的重点是弥合这一差距，从实验代码和评估输入一直追溯到设计。

• 预注册：在任何实验运行前，将主张、标准和预测结果冻结在 git 中
• 仅追加的研究记录：从运行输出中得出实际数字，并在 CI 中验证
• 实验代码和评估本身的完整性（操纵基准测试、数据泄漏、偏离设计）

2. 可复现性。 当 Agent 驱动研究时，Agent 的执行轨迹就是方法的一部分。保存这段轨迹，并能够据此重放工作流，是实现结果可复现的必要条件。

• 将 Agent 执行轨迹与仓库状态一并保存
• 根据记录的执行轨迹重放研究工作流

3. 研究质量。 可靠性和可复现性到位后，提升研究本身的质量：提出更好的假设、设计更强的实验，并进行更严谨的分析。

并行推进：其他领域。 机器学习是首个目标，因为实验以代码实现。除上述阶段外，我们也在与生命科学、机器人技术和材料科学等其他领域合作，将同一套完整性模型拓展到它们的工作流中。

联系方式

我们的目标是构建一个自动化研究操作系统，助力人类发现尚未实现的科学突破。

如果您对这一主题感兴趣，欢迎通过 [email protected] 联系我们。

关于 AutoRes

此 OSS 是 AutoRes 项目的一部分。

许可证

本项目采用 MIT 许可证。 详情请参阅 LICENSE 文件。

贡献

通过为本项目做出贡献，您同意您的贡献受贡献者许可协议（CLA）的约束，且项目所有者可以使用、修改、再分发和重新许可这些贡献，包括用于商业、企业和 SaaS 产品。

详情请参阅 CLA.md。

相关项目

• AI-Research-SKILLs（Orchestra Research，MIT）——一个针对特定库的机器学习工程技能库。AIRAS 的实验模板会在代码生成运行器上安装它，为 Agent 提供框架级指导（微调、分布式训练、推理）；AIRAS 的 get_library_docs MCP 工具则通过指向各个库不断更新的文档（llms.txt 端点）为 Agent 提供补充。

引用

如果您在研究中使用 AIRAS，请按以下格式引用：

@software{airas2025,
  author = {Toma Tanaka, Takumi Matsuzawa, Yuki Yoshino, Ilya Horiguchi, Shiro Takagi, Ryutaro Yamauchi, Wataru Kumagai},
  title = {AIRAS},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/airas-org/airas}
}