教程概述

.omx/ 是 oh-my-codex 的状态管理目录，提供计划、日志、记忆、状态的持久化存储，以及 Hooks 扩展系统。

你将学到

• ✅ .omx/ 目录结构详解
• ✅ plans、logs、memory、state 的作用
• ✅ Hooks 系统：pre/post 钩子
• ✅ 状态持久化机制
• ✅ 与 Codex 原生状态的对比

触发方式标识

trigger_mode: "自动（技能调用时）"
codex_native_alternative: "无（临时会话）"
superpowers_equivalent: ".superpowers/ 目录"
when_to_use_omx: "需要状态持久化的任何任务"
when_to_skip_omx: "一次性、无需追踪的任务"

为什么需要 .omx/？

无状态的问题

flowchart TD
    A[开始任务] --> B[会话 1]
    B --> C[任务中断]
    C --> D[会话 1 结束]
    D --> E[状态丢失]
    E --> F[会话 2]
    F --> G[从头开始]

    style E fill:#ffcccc
    style G fill:#ffcccc

状态持久化的优势

flowchart TD
    A[开始任务] --> B[会话 1]
    B --> C[保存到 .omx/]
    C --> D[会话 1 结束]
    D --> E[状态保留]
    E --> F[会话 2]
    F --> G[从断点恢复]

    style C fill:#e1f5ff
    style G fill:#e8f5e9

.omx/ 目录结构

.omx/
├── plans/              # 计划存储
│   ├── 20260325-feature-a/
│   │   ├── PRD.md
│   │   └── tasks.json
│   └── 20260325-feature-b/
│       ├── PRD.md
│       └── tasks.json
├── logs/               # 执行日志
│   ├── 20260325-session-1.log
│   └── 20260325-session-2.log
├── memory/             # 持久记忆
│   ├── project-context.md
│   ├── decisions.md
│   └── patterns.md
├── state/              # 运行时状态
│   ├── current-task.json
│   └── session-state.json
└── hooks/              # 钩子脚本
    ├── pre-plan.sh
    ├── post-plan.sh
    ├── pre-execute.sh
    └── post-execute.sh

各目录作用

plans/ 目录

存储 $plan 生成的 PRD

.omx/plans/
├── 20260325-auth-system/
│   ├── PRD.md              # 产品需求文档
│   ├── tech-spec.md        # 技术规格
│   └── tasks.json          # 任务清单
└── 20260325-payment-module/
    ├── PRD.md
    ├── tech-spec.md
    └── tasks.json

PRD 版本管理

# 查看所有计划
$ ls -la .omx/plans/

# 查看特定计划
$ cat .omx/plans/20260325-auth-system/PRD.md

# 恢复历史计划
$ plan restore 20260325-auth-system

logs/ 目录

执行日志记录

.omx/logs/
├── 2026/
│   ├── 03/
│   │   ├── 25/
│   │   │   ├── session-001.log
│   │   │   ├── session-002.log
│   │   │   └── error-001.log
│   │   └── 26/
│   └── 04/

日志内容

[2026-03-25 10:30:00] INFO: Session started
[2026-03-25 10:30:05] INFO: $plan "实现用户认证"
[2026-03-25 10:30:30] INFO: PRD generated
[2026-03-25 10:30:35] INFO: /prompts:executor "开始实现"
[2026-03-25 10:45:00] ERROR: Build failed
[2026-03-25 10:45:05] INFO: /prompts:debugger "分析错误"

查看日志

# 查看最新日志
$ omx logs --tail 50

# 查看错误日志
$ omx logs --level error

# 查看特定日期
$ omx logs --date 2026-03-25

memory/ 目录

持久记忆存储

.omx/memory/
├── AGENTS.md           # 项目指导
├── decisions.md        # 决策记录
├── patterns.md         # 代码模式
├── tech-stack.md       # 技术栈
└── lessons-learned.md  # 经验教训

AGENTS.md

项目级 AI 指导文档：

# Project Agents

## Tech Stack
- Framework: Next.js 14
- ORM: Prisma
- Database: PostgreSQL
- Auth: NextAuth.js

## Coding Standards
- Use TypeScript strict mode
- Follow ESLint config
- Write tests for critical paths

## Architecture
- Domain-driven design
- Repository pattern
- Service layer abstraction

decisions.md

决策记录：

# Decisions

## 2026-03-25: Use PostgreSQL over MongoDB
- Context: Need ACID transactions for payments
- Decision: Use PostgreSQL
- Consequences: Better consistency, harder to scale

## 2026-03-20: Adopt Tailwind CSS
- Context: Need rapid UI development
- Decision: Use Tailwind CSS
- Consequences: Faster styling, larger bundle

state/ 目录

运行时状态

.omx/state/
├── current-task.json     # 当前任务
├── session-state.json    # 会话状态
├── team-state.json       # 团队状态（如使用 $team）
└── ralph-state.json      # Ralph 状态（如使用 $ralph）

current-task.json

{
  "taskId": "task-123",
  "name": "实现用户认证",
  "status": "in_progress",
  "startTime": "2026-03-25T10:30:00Z",
  "planId": "20260325-auth-system",
  "progress": 0.65,
  "completedSteps": [
    "设计数据库模型",
    "实现注册 API"
  ],
  "remainingSteps": [
    "实现登录 API",
    "实现 token 刷新",
    "添加测试"
  ]
}

Hooks 系统

Hooks 类型

Hook 示例

pre-plan.sh:

#!/bin/bash
# .omx/hooks/pre-plan.sh

echo "Running pre-plan hook..."

# 检查环境
if [ ! -f "package.json" ]; then
    echo "Error: package.json not found"
    exit 1
fi

# 记录开始时间
echo "Plan started at $(date)" >> .omx/logs/plan.log

# 备份当前代码
git stash push -m "pre-plan-backup"

post-execute.sh:

#!/bin/bash
# .omx/hooks/post-execute.sh

echo "Running post-execute hook..."

# 运行测试
npm test

# 如果测试通过，自动提交
if [ $? -eq 0 ]; then
    git add .
    git commit -m "Auto-commit: $(date)"
    echo "Changes committed"
fi

配置 Hooks

# 启用 Hooks
$ omx hooks enable

# 查看 Hooks 状态
$ omx hooks status

# 手动运行 Hook
$ omx hooks run pre-plan

状态持久化机制

自动保存

flowchart TD
    A[技能调用] --> B[执行中]
    B --> C[自动保存状态]
    C --> D[存储到 .omx/state/]
    D --> E[继续执行]

    style C fill:#e3f2fd
    style D fill:#e8f5e9

会话恢复

# 恢复上次会话
$ omx resume

# 恢复到特定计划
$ omx resume --plan 20260325-auth-system

# 查看可恢复会话
$ omx sessions list

完整实战案例

场景：开发过程中断恢复

第 1 天：开始任务

$plan "实现用户认证系统"
# PRD 生成并保存到 .omx/plans/20260325-auth/

$ /prompts:executor "实现注册 API"
# 完成 50%，状态自动保存

# 会话中断（电脑关机）

第 2 天：恢复任务

# 查看状态
$ cat .omx/state/current-task.json
{
  "taskId": "auth-implementation",
  "status": "in_progress",
  "progress": 0.5,
  "completedSteps": ["设计模型", "注册 API"],
  "remainingSteps": ["登录 API", "token 刷新"]
}

# 恢复会话
$ omx resume
# 自动从断点继续

$ /prompts:executor "实现登录 API"
# 继续剩余任务

vs 原生 Codex

vs Superpowers

快速参考

目录速查

# 查看计划
$ ls .omx/plans/

# 查看最新日志
$ tail .omx/logs/$(date +%Y/%m/%d)/session.log

# 查看记忆
$ cat .omx/memory/AGENTS.md

# 查看状态
$ cat .omx/state/current-task.json

# 运行 Hook
$ .omx/hooks/pre-plan.sh

配置初始化

# 初始化 .omx/
$ omx init

# 创建 AGENTS.md
$ omx init --agents

# 创建示例 Hooks
$ omx init --hooks

反模式与常见错误

反模式 1：手动修改状态文件

❌ 错误：
手动编辑 .omx/state/current-task.json

✅ 正确：
使用 omx 命令管理状态
$ omx state update

反模式 2：忽略 .omx/ 备份

❌ 错误：
.gitignore 排除 .omx/

✅ 正确：
提交 .omx/ 到版本控制
或定期备份

反模式 3：Hooks 过度使用

❌ 错误：
每个操作都运行复杂 Hook

✅ 正确：
只在关键节点使用 Hooks
保持轻量快速

小结

.omx/ 提供完整的状态管理和扩展能力，是 oh-my-codex 的持久化基础。

核心要点：

1. plans/ 存储计划
2. logs/ 记录执行
3. memory/ 保存项目知识
4. state/ 维护运行时状态
5. hooks/ 实现自定义扩展

上一篇：教程 6：$team 多代理协调

下一篇：教程 8：HUD、OpenClaw 与自定义技能