机器人强化学习算法开发的全流程编排层 · A Codex-native orchestration layer for robot RL algorithm development

oh-my-algorithm (OMA) 是一个构建在 Codex CLI 之上的机器人算法开发工作流编排层。它将机器人强化学习开发的完整生命周期（需求 → 设计 → 实现 → 训练 → 调优 → 部署）拆分为独立的、上下文感知的 Codex skill，并通过门控状态机管理流程推进。

OMA 不是框架，不是库。它是一套开发工作流协议：用结构化的阶段状态文件、技术文档模板和 skill 提示词，让 Codex 在每个阶段都能做出高质量、领域正确的决策。

• 门控生命周期：六个标准开发阶段，前置条件检查确保不跳步骤
• 单阶段直入：oma go <stage> 绕过门控直接进入任意阶段
• 全局经验库：oma xp 跨项目积累 design/tune/deploy 经验；索引与内容分离，Codex 先扫索引再按需读全文
• 机器人 RL 优先：控制频率、自由度、Sim2Real gap、奖励函数设计是一等公民
• Gradmotion 原生集成：gm CLI、Isaac GYM 镜像、A10 GPU 任务创建规范内置
• 零外部依赖：CLI 仅使用 Node.js 内置模块
• Sim2Real 部署验证：8 类测试模板（延迟/电机/噪声/稳定性/步态/速度/扰动/地形）

# 克隆仓库
git clone https://github.com/yumxcode/oh-my-algorithm.git
cd oh-my-algorithm

# 全局安装（无需 npm install，零依赖）
npm install -g .

# 验证安装
oma --help

安装后 oma 命令全局可用。

# 在你的机器人算法项目目录下
mkdir my-robot-algo && cd my-robot-algo
oma setup

oma setup 会创建 .oma/ 目录结构并引导你完成初始配置。

codex
# Codex 读取 AGENTS.md，自动识别项目阶段，进入 requirement skill

完成每个阶段后，Codex skill 会输出结构化文档到 .oma/ 目录，通过门控条件后自动解锁下一阶段：

requirement → design → implement → train → tune → deploy

# 直接进入训练阶段，无需完整前置
oma go train --reason "已有参考实现，直接开始训练调试"

# 查看当前 standalone 状态
oma go status

# 退出 standalone 模式，恢复门控
oma go off

初始化 OMA 项目结构。

oma setup

在当前目录创建：

• .oma/ — 项目状态目录
• AGENTS.md — Codex 主提示词（如不存在则从模板生成）

单阶段直入：不经过门控，直接进入指定阶段。Codex 启动后读取 .oma/standalone.json，自动切换为 advisory（建议性）门控模式。

oma go requirement          # 进入需求阶段
oma go design               # 进入设计阶段
oma go implement            # 进入实现阶段
oma go train                # 进入训练阶段
oma go tune                 # 进入调优阶段
oma go deploy               # 进入部署阶段
oma go consolidate          # 进入汇总阶段

oma go train --reason "从已有 checkpoint 继续"  # 附加原因
oma go status               # 查看当前 standalone 状态
oma go off                  # 关闭 standalone，恢复门控

有效阶段：requirement design implement train tune deploy consolidate

跨项目积累 design / tune / deploy 三个阶段的成功经验，存储于 ~/.oma/。

~/.oma/
  xp-index.json          ← 轻量索引（id / name / description / stage / tags）
  experiences/
    deploy-001.md        ← 每条经验一个 Markdown 文件，人类可直接编辑
    deploy-002.md
    design-001.md

索引与内容分离：Codex 先读 xp-index.json 快速判断哪些经验相关，再按需读具体 .md 文件——避免经验库增大后每次都加载全部内容。

经验的录入分两步，内容由 Codex 生成、归档由 CLI 完成：

Step 1 — 在 Codex 中生成草稿

在 Codex 对话中输入（关键词触发 xp-generate 协议）：

oma xp --generate "帮我把本次 ankle kd 调参的结论整理成经验，要包含前后参数对比"

Codex 读取当前会话上下文（.oma/ 状态文件、本次对话内容），生成结构化草稿文件到当前目录，例如 ankle_kd_tuning_experience.md，并告知下一步命令。

Step 2 — 用户确认后 CLI 归档

检查草稿内容，满意后运行：

oma xp add --file ankle_kd_tuning_experience.md \
           --name "ankle-kd-tuning" \
           --description "将 ankle kd 从 2.0 降至 0.8 消除 20Hz 颤振" \
           --stage deploy

CLI 自动从文件解析背景/核心经验/结果等字段，分配 ID，归档到 ~/.oma/experiences/，更新全局索引。原草稿文件保留在原位置。

# Step 1：扫索引（只读 xp-index.json，轻量）
oma xp index --stage deploy --format md

# Step 2：读相关经验的完整内容
oma xp show deploy-001

# 有明确关键词时：两阶段搜索（索引命中 + 全文）
oma xp search "ankle chatter" --stage deploy

# 归档经验
oma xp add --file ankle_kd_experience.md --name "ankle-kd-tuning" \
           --description "降低 ankle kd 消除颤振" --stage deploy   # 文件模式（推荐）
oma xp add --stage deploy --name "..." --description "..."          # 纯 flag 模式
oma xp add --stage tune                                             # 纯交互模式

# 标签管理
oma xp tag deploy-001 biped locomotion    # 为已有经验追加标签

# 查阅
oma xp index --format md                  # 扫轻量索引（Codex 入口）
oma xp index --stage deploy --tag ankle --format md
oma xp show deploy-001                    # 读单条完整内容
oma xp search "reward hacking"            # 两阶段全文搜索
oma xp search "biped latency" --stage deploy

# 维护
oma xp delete tune-003
oma xp reindex                            # 从 experiences/*.md 重建索引

经验条目字段（索引中）：id / name / stage / robot_type / task / description / tags
经验文件完整字段：以上全部 + 背景 / 核心经验 / 结果 / 来源项目

质量原则：只存已验证的成功路径；description 一句话让 Codex 判断相关性，要具体（"将 ankle kd 从 2.0 降至 0.8"，不是"优化了参数"）；outcome 优先量化；tags 必含机器人类型和任务类型。

检查项目健康状态：阶段文件完整性、门控条件、上下文可用性。

oma doctor

示例输出：

✓ .oma directory exists
✓ config.json found
⚠ Standalone mode: ACTIVE (stage=train, entered 2h ago)
✗ design.md missing — train gate requires design document
  Hint: Or run `oma go train` to enter directly (bypass gate)

显示当前项目状态概览。

oma status

查看阶段推进历史记录。

oma log
oma log --stage train       # 过滤特定阶段

从 Codex 对话中提取结构化输出并写入 .oma/ 状态文件。

oma extract

注册开源参考代码库，供 implement 阶段的 Path A（改造现有代码）使用。

oma index --src ~/code/legged_gym
oma index --src https://github.com/leggedrobotics/rsl_rl   # Git 地址自动 clone

注册后生成 .oma/config.json，implement skill 自动检测并提示选择 Path A。

在已注册的代码库中搜索相关实现。

oma search "reward function"
oma search "observation space"

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  requirement │───▶│    design    │───▶│  implement   │
│              │    │              │    │              │
│ 机器人平台参数│    │ 网络/奖励/DR │    │ Path A/B选择 │
│ 任务/环境定义│    │ 完整RL规格   │    │ 开源参考询问 │
└──────────────┘    └──────────────┘    └──────────────┘
                                                │
                                                ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│    deploy    │◀───│     tune     │◀───│    train     │
│              │    │              │    │              │
│ Sim2Real测试 │    │ 超参调优     │    │ gm任务创建   │
│ 8类验证模板  │    │ 消融实验     │    │ 失效模式分类 │
└──────────────┘    └──────────────┘    └──────────────┘

Skill 引导完成：

• 任务描述（locomotion / manipulation / navigation）
• 机器人平台参数（必填）：robot_model、DoF、sim_env、control_hz、obs_dim、action_dim
• Domain Randomization 风险点识别
• 约束条件与成功指标

门控输出：.oma/requirement.md

Skill 生成完整的 RL 算法规格：

• 策略网络：架构类型、输入维度、输出维度（= DoF）、激活函数、动作缩放
• 价值网络：独立规格
• 奖励函数：每个奖励项必须包含公式 + 系数 + 目的 + 奖励黑洞风险
• 观测空间：标准本体感知模板（关节位置/速度、IMU、速度指令、上一步动作）
• 动作空间：PD 控制 Kp/Kd 规格
• Domain Randomization：Kp/Kd/质量/摩擦/延迟/噪声参数范围表
• 训练课程：阶段划分与切换条件
• RL 算法：PPO/SAC 具体超参（clip_range、tau 等）
• 消融实验计划：最少 5 个变量

门控输出：.oma/design.md

Phase 0（必须执行）：Skill 首先询问：

"实现阶段开始。请问你是否有可以参考或复用的开源代码库？"

• 有 → Path A：在其基础上改造（使用 oma index --src <path> 注册）
• 没有 → Path B：按设计文档从零实现

门控输出：.oma/implement.md、代码文件

Skill 内置 Gradmotion (gm) 平台操作规范：

训练任务配置（create-train.json）：

{
  "taskName": "your-task-name",
  "image": "registry.cn-hangzhou.aliyuncs.com/...:isaac-gym-preview-4",
  "goodsId": "<A10-GPU-goodsId>",
  "startScript": "gm-run your_project/scripts/train.py --task=your_task --headless --max_iterations=500",
  "codeType": 2,
  "repoUrl": "https://github.com/your-org/your-repo.git"
}

关键规范：

• 镜像：固定使用 Isaac GYM preview-4 官方镜像
• 算力：goodsName == "1*A10*24G" 的 goodsId
• 执行命令：gm-run（平台专用，相当于 python）不需要 cd 到项目目录
• 创建方式：始终 gm task create --file ./create-train.json

RL 失效模式分类与处置：

门控输出：.oma/train.md、checkpoint 路径、训练曲线

超参数调优与消融实验：

• 基于 design.md 中的消融计划执行
• 每次实验记录超参变化 + 结果
• 识别关键敏感超参

门控输出：.oma/tune.md

内置 8 类 Sim2Real 验证测试，每类包含 measure.py + analyze.py：

测试模板位于 templates/deploy-tests/，配置参考 templates/deploy-config.json。

your-robot-project/
├── AGENTS.md                  # Codex 主提示词（OMA 核心，oma setup 生成）
│
├── .oma/                      # OMA 状态目录（由 oma setup 创建，gitignore 覆盖工具文件）
│   ├── config.json            # 项目配置（robot platform, Gradmotion IDs）
│   ├── requirements.md        # 需求文档（$requirement skill 输出，LOCKED）
│   ├── knowledge.md           # 论文知识提取（$requirement skill 输出，LOCKED）
│   ├── memory.md              # 实验记忆（Dead Ends / Working Patterns / Open Hypotheses）
│   ├── designs/               # 设计文档（$design skill 输出）
│   │   └── design-{id}.md
│   ├── impl/                  # 实现记录
│   │   ├── impl-checklist.md  # 逐项实现进度追踪
│   │   └── github.json        # 代码仓库信息
│   ├── experiments/           # 每次训练/调优实验目录
│   │   └── exp-{id}/
│   │       ├── config.json
│   │       └── results.json
│   ├── leaderboard.json       # 调优排行榜（$tune 维护）
│   ├── best.json              # 最优实验（deploy gate 依赖）
│   ├── trajectory.jsonl       # 阶段事件流水账
│   ├── standalone.json        # Standalone 模式状态（oma go 写入）
│   │
│   ├── skills/                # Codex skill 提示词（gitignored，oma setup 安装）
│   │   ├── deploy/SKILL.md
│   │   ├── design/SKILL.md
│   │   └── ...
│   └── templates/             # 部署测试脚本与配置模板（gitignored，oma setup 安装）
│       ├── deploy_info_template.json
│       ├── sim2real_checklist_template.md
│       └── deploy-tests/
│
└── [你的机器人代码文件]        # 原工程文件，不受 OMA 污染

~/.oma/                        # 全局经验库（跨项目共享）
  ├── xp-index.json            # 轻量索引（id / name / description / stage / tags）
  └── experiences/
      ├── deploy-001.md        # 每条经验一个 Markdown 文件
      └── ...

门控系统确保流程质量，但有时你需要直接进入某个阶段（例如快速调试训练、基于已有设计继续）。Standalone 模式提供无门控的单阶段入口：

# 进入 train 阶段（不检查前置文件）
oma go train --reason "已有 checkpoint，继续 finetune"

# 此时 .oma/standalone.json 被创建
# Codex 读取 AGENTS.md 时检测到该文件，切换为 advisory 门控
# 所有门控条件变为"建议"而非"阻止"

# 退出 standalone
oma go off

.oma/standalone.json 内容：

{
  "stage": "train",
  "skill": "train",
  "enteredAt": "2025-01-15T10:30:00.000Z",
  "reason": "已有 checkpoint，继续 finetune"
}

AGENTS.md 是 OMA 的核心。Codex CLI 每次启动时读取它，内容包括：

• 启动协议：检查 standalone 状态、读取当前阶段、加载上下文
• 阶段门控规则：每个阶段的前置文件要求
• 机器人 RL 操作原则：
  • Sim2Real gap 是部署的首要风险
  • 奖励黑洞是行为崩塌的根因
  • 控制频率 (control_hz) 决定推理延迟预算
  • 所有设计决策必须有 Sim2Real 理由
• 关键词检测：识别 PPO/SAC/sim2real/reward/gm/gradmotion 相关上下文
• 平台规范：Gradmotion gm CLI 操作规范

# 查询可用算力（找 A10）
gm goods list

# 查询可用镜像（找 isaac-gym-preview-4）
gm image official list
gm image versions --image <image-id>

# 创建训练任务
gm task create --file ./create-train.json

# 查看任务状态
gm task list
gm task log --task <task-id>

# 删除任务
gm task delete --task <task-id>

为什么不用 Python？ OMA CLI 使用纯 Node.js 内置模块（fs、path、readline），零 npm 依赖，npm install -g . 即可全局使用，无需虚拟环境、无版本冲突。

为什么基于 Codex 而不是自建 Agent？ Codex CLI 已经解决了工具调用、代码执行、文件编辑的基础设施问题。OMA 只需要提供高质量的领域知识（AGENTS.md + skill prompts），让 Codex 在正确的上下文中做出正确决策。

为什么每个阶段要写文件？ .oma/*.md 文件是跨 Codex 会话的状态记忆。Codex 无法记住上次对话，但可以读取文件。OMA 把"记忆"外化为结构化文档，让每次 Codex 会话都有完整上下文。

为什么经验库是全局的？ ~/.oma/ 跨项目积累，不绑定单个仓库。在二足机器人项目 A 里发现的奖励函数技巧，在四足项目 B 里同样可以参考。越用越有价值。

为什么经验库索引与内容分离？ xp-index.json 只存 name + description + tags，让 Codex 能用极低成本扫描"有哪些经验"，再决定是否读具体 .md 文件的完整内容。随着经验库增长，这个设计让查阅成本保持稳定，不随条目数量线性增长。

欢迎 PR 和 Issue。主要贡献方向：

• 新的 deploy 测试类别
• 更多机器人平台的 skill 适配（手臂/无人机/轮式）
• oma CLI 新命令
• AGENTS.md / skill 提示词优化

MIT © 2025 oh-my-algorithm contributors