AI 辅助开发

AI 辅助开发#

AReaL 开箱即用提供 Codex、 OpenCode 和 Claude Code 三套一等配置。仓库中包含共享的项目指令、领域专家代理和可复用技能，以保证三套 harness 尽量保持一致。

本文以 Codex 作为仓库级工作流的主线说明；OpenCode 和 Claude Code 保持兼容支持。

Codex#

启动 Codex 会话#

cd /path/to/AReaL
codex

Codex 会从 AGENTS.md 读取项目上下文。在本仓库中，Codex harness 的组织方式是：

  • 项目指令：AGENTS.md

  • 仓库级 skills：.agents/skills/<name>/SKILL.md

  • 自定义 agents：.codex/config.toml，以及 .codex/agents/<name>.toml 和 .codex/agents/<name>.md

自定义 agent 先在 .codex/config.toml 里注册，再指向各自的 agent TOML：

[agents.fsdp-expert]
description = "FSDP2 expert for configuration, parallel strategy, weight sync, and integration guidance."
config_file = "./agents/fsdp-expert.toml"

每个 agent TOML 再指向自己的 markdown 指令文件：

name = "fsdp-expert"
model_instructions_file = "./fsdp-expert.md"

Codex 的“可直接执行工作流”#

在 AReaL 里，Codex 的“可直接执行工作流”就是放在 .agents/skills/ 下的仓库级 skill。Codex 这里不把 / 命令作为主要工作流表面，而是让你请求相应的 skill， 然后由 Codex 端到端执行该流程。

Skill

用途

add-dataset

向 areal/dataset/ 添加新的数据集加载器

add-workflow

创建新的 RolloutWorkflow 实现

add-reward

实现新的奖励函数

add-archon-model

向 Archon 引擎添加新的模型架构

add-unit-tests

添加或扩展单元测试

debug-distributed

排查卡死、OOM、NCCL 和 launcher 配置问题

commit-conventions

在提交前准备 Conventional Commit 信息

review-pr

执行只读 PR 审查工作流并输出风险分析

create-pr

变基、压缩提交、准备元数据并创建或更新 GitHub PR

translate-doc-zh

将 docs/en/ 下的文档翻译到 docs/zh/

update-docker-image

更新运行时镜像依赖并驱动 Docker PR 流程

upgrade-megatron-core

审计并升级 Megatron-Core 兼容性

upgrade-vllm

审计并升级 vLLM 兼容性

这就是“Codex 在本仓库里可直接执行的工作流是什么”的答案。

Codex 自定义 agents#

Codex 自定义 agents 是在 .codex/config.toml 中注册的专用顾问。它和 OpenCode 的自动专家路由不同，属于显式调用的能力表面：你可以直接要求 Codex 咨询某个 agent， 或者依赖仓库指令在合适时机触发它们。

Agent

用途

planner

为多文件改动和架构变更制定实现计划

simple-code-reviewer

做快速的变更后风险检查

code-verifier

运行定向格式化、lint 和验证命令

fsdp-expert

提供 FSDP2 配置、并行策略和权重同步指导

archon-expert

提供 Archon 与 MoE 集成指导

megatron-expert

提供 Megatron 流水线并行训练指导

algorithm-expert

提供 PPO、GRPO、DAPO、reward shaping 等指导

launcher-expert

提供本地、Ray、Slurm 和推理 launcher 指导

典型 Codex 会话#

> 为多模态评测添加一个新的 rollout workflow

Codex: [加载 add-workflow，检查 areal/workflow/，实现修改]

> 审查这个 PR

Codex: [加载 review-pr，分析 diff，并咨询匹配的 expert agents]

> 创建或更新这个 PR

Codex: [加载 create-pr，检查分支状态，并执行 PR 工作流]

OpenCode 兼容性#

安装 OpenCode 和 oh-my-opencode#

curl -fsSL https://opencode.ai/install | bash

其他安装方式包括 brew install anomalyco/tap/opencode、npm install -g opencode-ai 或直接下载发布二进制。具体以 OpenCode 官方文档为准。

oh-my-opencode 仍然是可选增强项， 适合需要更强 OpenCode 编排和工具集成时使用。

启动 OpenCode#

cd /path/to/AReaL
opencode

OpenCode 会读取 AGENTS.md，并从 .opencode/ 目录发现 agents、commands、skills 和 plugins；在相关场景下它也可以读取 .claude/skills/。

OpenCode 的工作流表面#

OpenCode 维持自己的 command 和 agent 体系：

命令

用途

/create-pr

变基、压缩提交并创建 PR

/review-pr

智能代码审查，带风险分析

/translate-doc-zh

将英文文档翻译为中文

OpenCode 相关资产位于 .opencode/agents/、.opencode/command/、 .opencode/skills/ 和 .opencode/package.json。

Claude Code 兼容性#

Claude Code 继续通过 CLAUDE.md 与 .claude/ 目录提供兼容支持，其中包括 agents、commands、hooks 和 rules。

配置文件#

AReaL/
|-- AGENTS.md                # 项目上下文（自动加载）
|-- .agents/
|   +-- skills/              # Codex 仓库级技能
|-- .codex/
|   |-- config.toml          # 注册自定义 Codex 子代理
|   +-- agents/              # Codex agent 配置和指令文件
|-- .opencode/
|   |-- agents/              # OpenCode expert agents
|   |-- command/             # OpenCode slash commands
|   |-- skills/              # OpenCode skills
|   +-- package.json         # OpenCode plugin 依赖
+-- .claude/
    |-- agents/              # Claude Code agents
    |-- commands/            # Claude Code commands
    |-- hooks/               # Claude Code hooks
    +-- rules/               # Claude Code rules

Harness 对照#

AReaL 同时支持三套 harness，但三者暴露可复用工作流的方式不同：

概念

Codex

OpenCode

Claude Code

项目上下文

AGENTS.md

AGENTS.md

CLAUDE.md

仓库级工作流

.agents/skills/

.opencode/skills/、.opencode/command/

.claude/skills/、.claude/commands/

自定义子代理

.codex/config.toml + .codex/agents/

.opencode/agents/

.claude/agents/

主要可执行工作流形态

仓库级 skill

slash command 或 skill

slash command 或 skill

代理调度方式

显式调用 custom agent

task(subagent_type="...", ...)

自动路由

专家命名

fsdp-expert、archon-expert、…

fsdp-expert、archon-expert、…

fsdp-engine-expert、archon-engine-expert、…

提交辅助

commit-conventions skill

commit-conventions skill

commit-conventions skill + /gen-commit-msg

Claude Code 还提供一些额外的通用代理：

代理

用途

planner

在复杂多文件更改之前创建实现计划

code-verifier

在代码更改后运行 pre-commit 钩子和测试

simple-code-reviewer

在提交前执行快速代码质量检查

Claude Code 配置位于：

AReaL/
|-- CLAUDE.md              # 项目上下文和约束
+-- .claude/
    |-- agents/            # 5 个领域专家 + 3 个通用代理（共 8 个）
    |-- skills/           # 引导式工作流（与 OpenCode 共享）
    |-- commands/         # 自动化操作（create-pr、gen-commit-msg、review-pr）
    |-- hooks/            # 预/后操作钩子
    +-- rules/            # 代码质量标准

贡献#

我们欢迎对代码库和 AI 开发配置的贡献：

  • 代码贡献：新功能、bug 修复、文档改进

  • AI 配置贡献：新增 Codex skills、custom agents，或兼容层改进

  • Codex 配置：编辑 .codex/、.agents/ 和 AGENTS.md

  • OpenCode 配置：编辑 .opencode/ 中的文件

  • Claude Code 配置：编辑 .claude/ 中的文件

参见 CONTRIBUTING.md 获取指南。