AReaL 的 AI 辅助开发体系Codex / OpenCode / Claude Code 三栖配置与实战指南【免费下载链接】AReaLThe RL Bridge for LLM-based Agent Applications. Made Simple Flexible.项目地址: https://gitcode.com/GitHub_Trending/are/AReaL本文围绕 AReaL 仓库内置的 AI 辅助开发AI-Assisted Development配置体系展开系统讲解 Codex、OpenCode、Claude Code 三套编码助手如何在同一个仓库中共存协作从项目上下文AGENTS.md/CLAUDE.md、仓库级技能skills、领域专家 Agent 到可直接执行的 PR 审查与创建工作流。读完本文你将掌握在 AReaL 仓库中启动并配置三套 AI 编码工具、注册自定义专家 Agent、复用内置技能完成新增数据集/工作流/奖励函数/模型架构、分布式调优、PR 全流程等高频任务的完整方法。一、概述AReaL 的一等配置与三套兼容层AReaL 为基于 LLM 的 Agent 应用提供强化学习训练桥接能力其仓库本身也是一座为 AI 而设计的代码库它内置了面向 Codex、OpenCode 和 Claude Code 三套编码助手的一等配置first-class configurations并共享三份核心资产共享项目指令shared project instructions让不同助手获得一致的仓库背景领域专家 Agentdomain expert agents覆盖 FSDP、Archon/MoE、Megatron、RL 算法、启动器等核心域可复用实现技能reusable implementation skills把新增数据集新增工作流等高频开发动作用 SKILL 标准化。官方文档以Codex 作为仓库内本地工作流repo-local workflows的标准执行环境canonical harnessOpenCode 与 Claude Code 则作为保持对齐的兼容层compatibility layers被持续维护。三个环境在概念上完全对齐同一批领域专家fsdp-expert、archon-expert等在不同助手中有对应实现仅接入方式不同。二、Codex标准执行环境2.1 启动 Codex 会话在仓库根目录直接启动即可cd /path/to/AReaL codexCodex 会自动从AGENTS.md读取项目上下文。在 AReaL 中Codex 工具面围绕三层结构组织层级路径作用项目指令AGENTS.md项目背景、硬性规则、仓库地图、代码风格约定仓库级技能.agents/skills/name/SKILL.md可直接执行的端到端工作流自定义 Agent.codex/config.toml .codex/agents/name.toml与.codex/agents/name.md领域专家按需显式调用以AGENTS.md为例它开篇即为 Agent 提供了 Quick reference技术栈Python 3.12 / PyTorch / FSDP2 / Megatron / Archon / SGLang / vLLM、环境安装命令uv sync --extra cuda、pre-commit 安装与执行、测试命令uv run pytest tests/test_topic.py以及永远不可违反的硬性规则禁止通配符导入、禁止硬编码密钥、禁止跳过 pre-commit 钩子、禁止猜测集群配置、集成测试必须显式说明跳过原因等。这些规则直接约束了后续所有 Agent 的工作方式。2.2 自定义 Agent 的注册链路Codex 的自定义 Agent 采用双层配置文件注册在.codex/config.toml中注册并指向 per-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/config.toml 实际注册了 8 个 Agent每个都在description中精确声明其职责边界例如algorithm-expert负责 RL algorithm expert for GRPO, PPO, DAPO, reward shaping, and workflow-level RL decisionscode-verifier负责 Verification agent for pre-commit, lint, formatting, and targeted test runs。以 fsdp-expert.md 为例其指令文件结构非常规范包含When to Activate明确何时激活 / 何时不要使用如 FSDPEngine 的使用指导适用但底层分布式训练理论不适用Core ConceptsFSDPEngine 是基于 PyTorch FSDP2 的通用训练引擎支持 TP/DP/CP 并行与 CPU offload引擎选择原则是稠密模型选 FSDPEngine、MoE 模型选 ArchonEngine、超深流水线模型选 MegatronEngineConfigurationTrainEngineConfigareal/api/cli_args.py、ParallelStrategyareal/api/alloc_mode.py、FSDPEngineConfig的分工与配置顺序Workflow Integration与RLVRWorkflow、MultiTurnWorkflow、SFTWorkflow的集成模式以及 XCCLNCCL 低延迟广播与 Disk-based异构集群/容错两套权重同步机制Common Usage Patterns 与 Troubleshooting常见故障的症状→原因→第一步处理表如初始化失败检查dp * sp * tp world_size、OOM 时开启offload_paramsTrue。Implementation Structure把fsdp_engine.py、fsdp_utils/、models/fsdp/ulysses.py、models/tree_attn/等源码路径映射为清晰的资源地图。这种职责边界 核心概念 配置指引 排障清单 源码地图的 Agent 指令模板是整个仓库 8 个 Codex Agent 的统一风格也是其余两套兼容层 Agent 的对齐基准。2.3 可直接执行的 Codex 工作流Repo-local Skills在 AReaL 中Codex 的主要可执行工作流形式是仓库级技能repo-local skills存放于.agents/skills/每个技能是一个带 frontmatternamedescription的SKILL.md。Codex 在这里不使用/斜杠命令作为主要工作流入口而是通过自然语言请求 Codex 加载匹配技能并端到端执行。官方文档列出的技能清单如下Skill用途add-dataset在areal/dataset/下新增数据集加载器add-workflow创建新的RolloutWorkflow实现add-reward实现新的奖励函数add-archon-model为 Archon 引擎新增模型架构add-unit-tests新增或扩展单元测试debug-distributed排查挂起、OOM、NCCL 问题与启动器配置错误commit-conventions提交前生成 Conventional Commit 消息review-pr执行带风险分析的只读 PR 审查工作流create-prRebase、squash、准备元数据并创建/更新 GitHub PRtranslate-doc-zh将docs/en/内容翻译到docs/zh/update-docker-image更新运行时镜像依赖并驱动 Docker PR 流程upgrade-megatron-core审计并升级 Megatron-Core 兼容性upgrade-vllm审计并升级 vLLM 兼容性仓库实际还包含文档清单之外的upgrade-deps技能.agents/skills/upgrade-deps/内置了 megatron-core、vllm、sglang、peft、transformers、torchao、megatron-bridge、mbridge 的升级检查清单模板可作为上述升级类技能的实现参考。技能实战示例add-workflow以 add-workflow 为例其工作流分四步且每一步都给出可运行的代码骨架Step 1在areal/workflow/name.py创建RolloutWorkflow子类核心是arun_episode必须为async def且非阻塞先用tokenizer.apply_chat_template构造input_ids再用uuid生成请求 ID 构造ModelRequest调用engine.agenerate(req)异步生成最后通过AsyncRewardWrapper异步计算奖励并返回input_ids / output_ids / reward的 tensor 字典。Step 2在areal/workflow/__init__.py注册导出from areal.workflow.name import MyWorkflow并加入__all__。Step 3在训练脚本中按全限定名引用trainer.train(workflowareal.workflow.name.MyWorkflow, ...)。Step 4在tests/test_name_workflow.py补充 pytest 用例。该技能还给出了三条参考实现MultiTurnWorkflow→areal/workflow/multi_turn.py、RLVRWorkflow→areal/workflow/rlvr.py、VisionRLVRWorkflow→areal/workflow/vision_rlvr.py与常见错误清单误用open()而非aiofiles.open()、忘记await、未包AsyncRewardWrapper、tensor 维度约定错误等确保 Agent 一次做对。技能实战示例review-pr 与 create-prPR 相关技能是完整的端到端工作流review-pr 明确声明只读硬规则不编辑文件、不提交、不 push、不运行会改变环境的构建/测试命令其五阶段流程为解析 PR 上下文gh pr view→ 变更分析依据 review-pr-domains-and-signals.md 分类文件并输出风险等级CRITICAL/HIGH/MEDIUM/LOW支持--quick提前终止→ 审查计划从 review-pr-templates.md 选取最小审查遍数→ 专家咨询按需并行调用archon-expert、fsdp-expert等子 Agent→ 最终报告按严重度排序输出每条 finding。仓库还附带 sync_review_pr_refs.py 用于同步跨 harness 的审查参考文件。create-pr 则负责从origin/mainrebase、squash 提交、生成智能提交信息并创建 GitHub PR支持 fork 远端判定git push --dry-run origin探测写权限。2.4 典型 Codex 会话官方文档给出了三类高频会话的预期行为 Add a new rollout workflow for multimodal evaluation Codex: [loads add-workflow, inspects areal/workflow/, implements changes] Review this PR Codex: [loads review-pr, analyzes the diff, consults the matching expert agents] Create or update the PR Codex: [loads create-pr, checks branch state, prepares the PR workflow]即用户提出任务 → Codex 自动装载匹配技能 → 依据技能脚本结合源码执行 → 必要时咨询领域专家 Agent。这正是技能怎么做事 专家专业判断双层分工的体现。三、OpenCode 兼容层OpenCode 与 Codex 共享AGENTS.md作为项目上下文但其 Agent、命令、技能、插件体系独立存放于.opencode/并且也能读取.claude/skills/中的相关内容。3.1 安装与启动curl -fsSL https://opencode.ai/install | bash替代安装方式包括brew install anomalyco/tap/opencode、npm install -g opencode-ai或从 GitHub 获取 release 二进制具体以 OpenCode 官方文档为准。可选的 oh-my-opencode 用于更丰富的编排与工具集成。启动方式与 Codex 对称cd /path/to/AReaL opencode3.2 OpenCode 的工作流表面斜杠命令与技能OpenCode 维护自己的命令与 Agent 体系官方文档列出的命令如下Command用途/create-prRebase、squash 提交并创建 PR/review-pr带风险分析的智能代码审查/translate-doc-zh将英文文档翻译为中文OpenCode 专属资产分布在.opencode/agents/、.opencode/command/、.opencode/skills/与.opencode/package.json。仓库中实际验证到的 OpenCode 侧资产包括5 个专家 Agentalgorithm-expert、archon-expert、fsdp-expert、launcher-expert、megatron-expert以及.opencode/skills/下的 add-archon-model、add-dataset、add-reward、add-unit-tests、add-workflow、commit-conventions、debug-distributed 等与.agents/skills/对齐的技能另有.opencode/data/存放 review-pr 共享参考文档。与 Codex 的一个关键差异在Agent 分派机制OpenCode 采用自动专家路由通过task(subagent_type..., ...)在任务中显式指定子 Agent 类型而 Codex 是显式自定义 Agent 调用要求用户显式请求咨询或依赖仓库指令触发。四、Claude Code 兼容层Claude Code 通过CLAUDE.md加.claude/目录维持兼容支持覆盖 agents、commands、hooks、rules 四类资产。4.1 目录结构与 8 个 Agent官方文档给出的 Claude Code 配置布局如下AReaL/ |-- CLAUDE.md # Project context and constraints -- .claude/ |-- agents/ # 5 domain experts 3 general-purpose (8 total) |-- skills/ # Guided workflows (shared with OpenCode) |-- commands/ # Automated actions (create-pr, gen-commit-msg, review-pr) |-- hooks/ # Pre/post action hooks -- rules/ # Code quality standards仓库实测.claude/agents/下共有 8 个 Agent与文档描述一致。除与 Codex/OpenCode 对齐的领域专家外Claude Code 额外提供 3 个通用 AgentAgent用途planner在复杂多文件变更前创建实现计划code-verifier代码变更后运行 pre-commit 钩子与测试simple-code-reviewer提交前执行快速代码质量检查注意 Claude Code 的专家命名带engine后缀以示区分fsdp-engine-expert、archon-engine-expert、megatron-engine-expert、launcher-scheduler-expert、algorithm-expert。4.2 命令、钩子与规则Commands.claude/commands/create-pr、gen-commit-msg、review-pr、translate-doc-zh四个自动化动作。以 create-pr.md 为例其 frontmatter 声明从最新origin/mainrebase、squash 提交、基于暂存变更生成智能提交信息并创建 GitHub PR用/create-pr触发支持--draft与--base branch参数并内置了分支合法性校验禁止从 main/master 创建 PR、未提交变更检查、ghCLI 可用性检查与 fork 远端判定逻辑。Hooks.claude/hooks/check-expert-update.sh通过 settings.json 中PostToolUse匹配器挂载——当 Agent 执行Write|Edit后触发check-expert-update.sh用于校验专家配置是否需要同步更新。Rules.claude/rules/api-config.md、code-style.md、distributed.md、testing.md分别固化了 API 配置、代码风格、分布式开发与测试相关的代码质量标准。4.3 Agent 分派差异Claude Code 采用自动路由Automatic routing由模型根据上下文自动选择合适的 Agent而非用户显式点名。此外其提交辅助同时提供commit-conventions技能与/gen-commit-msg命令双入口。五、三套 Harness 的统一配置地图官方文档以一棵树清晰地汇总了仓库中全部 AI 辅助配置文件AReaL/ |-- AGENTS.md # Project context (loaded automatically) |-- .agents/ | -- skills/ # Codex repo-local skills |-- .codex/ | |-- config.toml # Registers custom Codex subagents | -- agents/ # Codex agent config files and instruction markdown |-- .opencode/ | |-- agents/ # OpenCode expert agents | |-- command/ # OpenCode slash commands | |-- skills/ # OpenCode skills | -- package.json # OpenCode plugin dependencies -- .claude/ |-- agents/ # Claude Code agents |-- commands/ # Claude Code commands |-- hooks/ # Claude Code hooks -- rules/ # Claude Code rules六、Harness 能力对比表官方文档给出的三套助手逐维度对比是理解整个体系的关键概念CodexOpenCodeClaude Code项目上下文AGENTS.mdAGENTS.mdCLAUDE.md仓库工作流.agents/skills/.opencode/skills/、.opencode/command/.claude/skills/、.claude/commands/自定义子 Agent.codex/config.toml.codex/agents/.opencode/agents/.claude/agents/主要可执行工作流形式仓库级技能斜杠命令或技能斜杠命令或技能Agent 分派显式自定义 Agent 调用task(subagent_type..., ...)自动路由专家命名fsdp-expert、archon-expert、...fsdp-expert、archon-expert、...fsdp-engine-expert、archon-engine-expert、...提交辅助commit-conventions技能commit-conventions技能commit-conventions技能 /gen-commit-msg对开发者的选型建议依据官方文档定位推断以 Codex 为默认文档明确将 Codex 定义为 repo-local 工作流的标准执行环境其技能体系最完整、最受官方维护OpenCode 适合偏好斜杠命令与自动专家路由的用户/create-pr、/review-pr、/translate-doc-zh开箱即用且通过task(subagent_type...)在任务内显式委派子 AgentClaude Code 适合深度依赖自动路由与规则治理的用户8 个 Agent 4 类 rules PostToolUse 钩子治理约束最强。三套体系的专家知识是共享的例如.opencode/data/与.agents/skills/review-pr/references/共用同一套 PR 审查领域信号与模板只是载体不同因此任意一套积累的领域知识都可迁移到其余两套。七、如何为 AReaL 的 AI 辅助体系做贡献AReaL 欢迎对代码库与 AI 开发配置的双重贡献代码贡献新特性、Bug 修复、文档改进AI 配置贡献新增 Codex 技能、自定义 Agent或改进兼容层Codex 配置编辑.codex/、.agents/与AGENTS.mdOpenCode 配置编辑.opencode/下的文件Claude Code 配置编辑.claude/下的文件。详细的贡献规范请参阅仓库根目录的 CONTRIBUTING.md。八、最佳实践小结结合官方文档、AGENTS.md与各技能内容归纳出在 AReaL 中高效使用 AI 辅助开发体系的实践建议让指令文件声明何时用、何时不用参考fsdp-expert.md的做法为每个 Agent 明确 When to Activate 与明确的职责边界避免越权行为技能必须可执行且可验证每个 SKILL 都应给出文件路径、代码骨架、参考实现与常见错误清单如add-workflow的 async 规则保证端到端可运行用技能管流程、用专家管判断流程性工作建 PR、加数据集交给技能专业性判断FSDP 并行策略、MoE 集成、RL 算法选择咨询对应专家 AgentPR 审查默认只读review-pr的硬规则不编辑、不提交、不改变环境是仓库内 AI 协作的安全底线遵守 AGENTS.md 硬性规则无通配符导入、无硬编码密钥、不跳过 pre-commit、提交前运行pre-commit run --all-files、新功能配套测试——这些规则同时约束人类与 AI 贡献者新增技能/Agent 时同步三套兼容层仓库通过.claude/hooks/check-expert-update.sh这类钩子与sync_review_pr_refs.py脚本维持跨 harness 一致性新增或修改专家配置时应同样注意同步。AReaL 的这一整套 AI 辅助开发体系本质上把领域知识 可执行流程 代码库上下文以标准格式固化进了仓库本身无论你使用 Codex、OpenCode 还是 Claude Code都能获得一致的专家知识与工作流能力从而把更多精力聚焦在强化学习桥接本身的算法与工程问题上。【免费下载链接】AReaLThe RL Bridge for LLM-based Agent Applications. Made Simple Flexible.项目地址: https://gitcode.com/GitHub_Trending/are/AReaL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考