Refinex-OMX

仓库：Refinex-OMX
上游：Yeachan-Heo/oh-my-codex
英文版 README：docs/readme/README.en.md
品牌话术：docs/refinex-branding.zh.md
吸收路线图：docs/refinex-harness-roadmap.zh.md

基于 oh-my-codex 的 Refinex fork：保留 OMX runtime，吸收 Harness 治理纪律，构建更适合真实仓库长期协作的 Codex 工作流层。

Refinex-OMX 是一个基于 oh-my-codex 的 Refinex fork。它保留 OMX 已经验证过的运行时外壳，包括 CLI、team runtime、HUD、wiki、MCP、hooks 与技能生态，同时把 Refinex 在 harness-* 上沉淀出的仓库治理纪律逐步吸收进主工作流。

它的目标不是再造一套平行平台，而是在已经跑通的 OMX runtime 之上，强化更适合真实仓库长期协作的交付纪律：

• 先做任务路由，再决定工作流归属
• 先做 preflight，再进入实现或修复
• 先有执行计划，再做结构化交付
• 先有复现和根因，再做最小修复
• 先有验证证据，再宣称完成

一句话定位：

Refinex-OMX = OMX runtime + Harness discipline

为什么要 Fork

直接沿用 upstream OMX 有两个优点：

• 它已经拥有成熟的运行时表面，包括 team/tmux、hooks、HUD、wiki、MCP、native integration
• 它仍在高频发布和修复，继续跟随 upstream 的性价比远高于自己重造一层 runtime

但我们也明确看到了 upstream 的边界：

• 它更强在“把 Codex 用起来”，不够强在“把仓库治理收紧”
• 它有稳定的工作流习惯，但缺少我们想要的 repo-aware governance gate
• 它更像一个强运行时产品，不是一个以仓库控制面为中心的交付协议

因此这个 fork 的策略不是“重写 OMX”，而是：

1. 保留上游的运行时能力
2. 吸收 Harness 的治理方法
3. 只在必要时做最小 runtime patch

当前阶段

当前仓库处于 upstream-tracking + workflow-first enhancement 阶段：

• 运行时层：优先继承 upstream OMX 的 CLI、tmux/team、hooks、HUD、MCP 与状态管理能力
• 工作流层：优先吸收 Harness 的任务路由、计划约束、修复协议、验证门禁与防漂移机制
• 演进策略：先做 skill / prompt / workflow contract 增强，再决定是否需要最小化 runtime 改动

这意味着仓库里的大多数命令、目录结构和启动方式目前仍与 upstream OMX 一致；变化会优先落在技能、文档、流程门禁和仓库治理语义上。

设计原则

Refinex-OMX 当前遵循这些原则：

• 跟随 upstream，不盲目深叉：尽量减少与 upstream runtime 的分叉面
• 治理优先于提示词堆叠：尽量把约束做成稳定 workflow，而不是临时 prompt
• 证据优先于信心表达：完成、修好、ready 这类结论必须绑定验证证据
• 仓库上下文优先于单轮聪明：让 AGENTS.md、skills、plan、state 真正形成控制面
• 最小补丁优先于系统重写：只有扩展点不够时才改 runtime

推荐工作流

在 Refinex 路线下，我们更看重下面这条主路径：

1. 路由任务，判断是解释、建设、修复还是治理维护
2. 做 preflight，确认控制面、环境和验证基线
3. 建立计划或 bug brief，明确目标、范围、非目标与验证方式
4. 小步执行，保持 diff 与计划/根因/验证的可追溯关系
5. 用新鲜证据收口，而不是用口头信心收口

如果延续 OMX 现有使用方式，典型路径仍然是：

$deep-interview "clarify the task boundary"
$ralplan "approve the implementation path"
$ralph "carry the approved plan to completion"
$team 3:executor "execute the approved plan in parallel"

后续我们会逐步把 Harness 风格的 route / preflight / verify 纪律，吸收到这些主路径里。

快速开始

依赖

• Node.js 20+
• OpenAI Codex CLI
• macOS / Linux + tmux 为推荐路径

安装

推荐通过 Refinex-OMX 的公开 npm 包安装：

npm install -g @openai/codex
npm install -g @refinex/omx
omx doctor

如果你当前只是研究或本地二开，使用源码路径：

npm install
npm run build
npm link
omx doctor

如果你面向真实环境运行，建议先确认 Codex 可正常认证，再启动 OMX：

codex login status
omx doctor
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"

首次会话

omx --madmax --high

进入 Codex 后，可先使用：

$deep-interview "clarify the task boundary"
$ralplan "approve the safest path"
$ralph "carry the approved plan to completion"

主要能力

Refinex-OMX 当前继承并使用 upstream OMX 的这些能力：

• omx：启动 Codex 工作流层
• omx setup：安装 prompt / skill / config / AGENTS scaffolding
• omx doctor：检查安装与运行时边界
• omx team ...：协调 tmux/worktree 场景下的并行 worker
• omx hud ...：观察运行时状态
• omx explore / omx sparkshell：做只读探索与受控检查
• wiki / MCP / hooks：连接本地知识、运行时状态和扩展面

仓库目录

Refinex-OMX/
├── src/          # TypeScript runtime and workflow implementation
├── crates/       # Rust-native helper binaries
├── skills/       # OMX skills and future Refinex workflow overlays
├── prompts/      # Agent prompt surfaces
├── docs/         # Product docs, release notes, contracts, localized README
├── templates/    # AGENTS and setup templates
└── missions/     # Evaluation and sandbox missions

文档入口

• Getting Started
• 用户手册
• Agents
• Skills
• Integrations
• Refinex 品牌话术
• Harness 吸收路线图
• Troubleshooting
• Codex Native Hook Mapping
• OpenClaw Integration
• Changelog

语言

• 简体中文（当前）
• English

与上游的关系

这个仓库当前明确遵循以下策略：

• 尊重 upstream oh-my-codex 作为运行时能力来源
• 优先通过 skills / prompts / workflow contracts 做增强
• 尽量保持可持续 rebase / merge，而不是快速走向不可维护深叉

如果某项能力在 upstream 已经足够好，我们倾向于复用；只有当仓库治理、验证闭环或 repo-aware discipline 明确需要时，才考虑引入 Refinex 特有补丁。

License

MIT