ralph (Ouroboros) — 规范优先的 AI 开发

停止提示。开始规范。

“终点即是起点，起点即是终点。”
蛇不会重复——它会进化。

何时使用此技能

• 在编写任何代码之前 — 通过苏格拉底式提问揭示隐藏的假设
• 长时间运行的任务，需要自主迭代直至验证通过
• 模糊的需求 — 将其固化为不可变的规范（模糊度 ≤ 0.2）
• 需要保证完成的任务 — 循环直至验证通过
• 遇到阻碍时 — 5 个横向思维角色打破僵局
• 偏差检测 — 衡量执行过程偏离原始规范的程度

核心架构：循环

    访谈 → 种子 → 执行 → 评估
        ↑                         ↓
        └──── 进化循环 ────┘

每个循环都在进化，而非重复。评估输出作为下一次迭代的输入反馈，直到系统收敛。

双钻模型

    ◇ 探索          ◇ 设计
   ╱  (发散)       ╱  (发散)
  ╱    探索       ╱    创造
 ╱               ╱
◆ ─────────── ◆ ─────────── ◆
 ╲               ╲
  ╲    定义       ╲    交付
   ╲  (收敛)       ╲  (收敛)
    ◇ 本体论        ◇ 评估

第一个钻石是苏格拉底式的：发散成问题，收敛为本体论的清晰。
第二个钻石是实用主义的：发散成设计方案，收敛为已验证的交付。

1. 命令（完整参考）

2. 访谈 → 规范流程

理念：从探索到本体论

探索 → “我该如何生活？” → “‘生活’是什么？” → 本体论 — 苏格拉底

   探索                           本体论
     💡                               🔬
“我想要什么？”    →    “我想要的东西‘是’什么？”
“构建一个任务命令行工具”   →    “任务‘是’什么？优先级‘是’什么？”
“修复认证错误”   →    “这是根本原因，还是症状？”

步骤 1：访谈（揭示隐藏假设）

ooo interview “我想构建一个任务管理命令行工具”

苏格拉底式访谈者会持续提问，直到模糊度 ≤ 0.2。

模糊度公式：

模糊度 = 1 − Σ(清晰度ᵢ × 权重ᵢ)

新项目：目标(40%) + 约束(30%) + 成功标准(30%)
现有项目：目标(35%) + 约束(25%) + 成功标准(25%) + 上下文(15%)

阈值：模糊度 ≤ 0.2 → 准备生成种子

评分示例：

目标：       0.9 × 0.4 = 0.36
约束：       0.8 × 0.3 = 0.24
成功标准：   0.7 × 0.3 = 0.21
                        ──────
清晰度             = 0.81
模糊度 = 1 − 0.81 = 0.19 ≤ 0.2 → ✓ 准备生成种子

步骤 2：种子（固化为不可变规范）

ooo seed

生成 YAML 规范：

goal: 构建一个命令行任务管理工具
constraints:
  - Python 3.14+
  - 无外部数据库
  - 使用 SQLite 进行持久化
acceptance_criteria:
  - 可以创建任务
  - 可以列出任务
  - 可以标记任务完成
ontology_schema:
  name: TaskManager
  fields:
    - name: tasks
      type: array
    - name: title
      type: string

步骤 3：运行（通过双钻模型执行）

ooo run seed.yaml
ooo run  # 使用对话上下文中的种子

步骤 4：评估（三道关卡验证）

ooo evaluate <会话_id>

偏差阈值：

• 0.0 – 0.15 — 优秀：按计划进行
• 0.15 – 0.30 — 可接受：密切关注
• 0.30+ — 超出：需要纠正方向

3. Ralph — 持续循环直至验证通过

ooo ralph “修复所有失败的测试”
/ouroboros:ralph “修复所有失败的测试”

“巨石永不停歇。”
每次失败都是下一次尝试的数据。只有完全成功或达到最大迭代次数才会停止。

Ralph 的工作原理

┌─────────────────────────────────┐
│  1. 执行（并行）                  │
│     独立任务                     │
│     并发调度                     │
├─────────────────────────────────┤
│  2. 验证                          │
│     检查完成情况                   │
│     验证测试通过                   │
│     衡量与种子的偏差               │
├─────────────────────────────────┤
│  3. 循环（如果失败）                │
│     分析失败原因                   │
│     修复已识别的问题               │
│     从步骤 1 重复                  │
├─────────────────────────────────┤
│  4. 持久化（检查点）                │
│     .omc/state/ralph-state.json │
│     中断后恢复                     │
└─────────────────────────────────┘

状态文件

启动时创建 .omc/state/ralph-state.json：

{
  "mode": "ralph",
  "session_id": "<uuid>",
  "request": "<用户请求>",
  "status": "running",
  "iteration": 0,
  "max_iterations": 10,
  "last_checkpoint": null,
  "verification_history": []
}

循环逻辑

当 迭代次数 < 最大迭代次数 时：
    结果 = 并行执行(请求， 上下文)
    验证 = 验证结果(结果， 验收标准)
    状态.验证历史.追加({
        “迭代”： 迭代次数，
        “通过”： 验证.通过，
        “分数”： 验证.分数，
        “时间戳”： <当前时间>
    })
    如果 验证.通过：
        保存检查点(“complete”)
        跳出循环
    迭代次数 += 1
    保存检查点(“iteration_{迭代次数}”)

进度报告格式

[Ralph 迭代 1/10]
正在并行执行...

验证：失败
分数：0.65
问题：
- 仍有 3 个测试失败
- src/api.py 中存在类型错误

巨石永不停歇。继续...

[Ralph 迭代 3/10]
正在并行执行...

验证：通过
分数：1.0

Ralph 完成
==============
请求：修复所有失败的测试
耗时：8 分 32 秒
迭代次数：3

验证历史：
- 迭代 1：失败 (0.65)
- 迭代 2：失败 (0.85)
- 迭代 3：通过 (1.0)

取消操作

4. 进化循环 (Evolve)

ooo evolve “构建一个任务管理命令行工具”
ooo evolve “构建一个任务管理命令行工具” --no-execute  # 仅本体论，快速模式

流程

第 1 代：访谈 → 种子(O₁) → 执行 → 评估
第 2 代：探索 → 反思 → 种子(O₂) → 执行 → 评估
第 3 代：探索 → 反思 → 种子(O₃) → 执行 → 评估
...直到本体论收敛（相似度 ≥ 0.95）或达到最大 30 代

收敛公式

相似度 = 0.5 × 名称重叠 + 0.3 × 类型匹配 + 0.2 × 完全匹配
阈值：相似度 ≥ 0.95 → 已收敛

第 1 代：{Task, Priority, Status}
第 2 代：{Task, Priority, Status, DueDate}  → 相似度 0.78 → 继续
第 3 代：{Task, Priority, Status, DueDate}  → 相似度 1.00 → 已收敛 ✓

停滞检测

Ralph 在进化模式中

Ralph 循环 1：进化_步骤(谱系， 种子) → 第 1 代 → 操作=继续
Ralph 循环 2：进化_步骤(谱系)       → 第 2 代 → 操作=继续
Ralph 循环 3：进化_步骤(谱系)       → 第 3 代 → 操作=已收敛 ✓
                                                └── Ralph 停止。
                                                    本体论已稳定。

回滚

ooo evolve --status <谱系_id>          # 检查谱系状态
ooo evolve --rewind <谱系_id> <代_N>  # 回滚到第 N 代

5. 九种思维（智能体）

按需加载——永不预加载：

6. 摆脱困境 — 横向思维

当反复失败被卡住时，选择一个角色：

ooo unstuck                 # 根据情况自动选择
ooo unstuck simplifier      # 缩减范围到最小可行产品 — “从正好 2 张表开始”
ooo unstuck hacker          # 先让它工作，优雅稍后再说
ooo unstuck contrarian      # 挑战所有假设
ooo unstuck researcher      # 停止编码，寻找缺失信息
ooo unstuck architect       # 完全重组方法

何时使用每个角色：

• 反复出现类似失败 → contrarian（挑战假设）
• 选择过多 → simplifier（减少范围）
• 信息缺失 → researcher（寻找数据）
• 分析瘫痪 → hacker（先让它工作）
• 结构性问题 → architect（重新设计）

7. 平台安装与使用

Claude Code（原生插件 — 完整模式）

# 安装
claude plugin marketplace add Q00/ouroboros
claude plugin install ouroboros@ouroboros

# 一次性设置
ooo setup

# 使用
ooo interview "我想构建一个任务命令行工具"
ooo seed
ooo run
ooo evaluate <会话_id>
ooo ralph "修复所有失败的测试"

所有 ooo 命令原生工作。钩子自动激活：

• UserPromptSubmit → keyword-detector.mjs 检测触发词
• PostToolUse(Write|Edit) → drift-monitor.mjs 跟踪偏差
• SessionStart → 会话初始化

Claude Code hooks.json（安装在 ${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json）：

{
  "hooks": {
    "SessionStart": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-start.mjs\"", "timeout": 5 }] }],
    "UserPromptSubmit": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/keyword-detector.mjs\"", "timeout": 5 }] }],
    "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/drift-monitor.mjs\"", "timeout": 3 }] }]
  }
}

Codex CLI（适配模式 — bash 循环）

Codex CLI 没有原生的 AfterAgent 钩子。使用设置脚本配置：

# 设置
bash <您的智能体技能目录>/ralph/scripts/setup-codex-hook.sh

# 重启 Codex，然后使用：
/prompts:ralph              # 加载 ralph 循环上下文
/prompts:ouroboros          # 加载完整 ouroboros 上下文

# 在对话中使用 ooo 命令：
ooo interview "构建一个 REST API"
ooo ralph "修复所有 TypeScript 错误"

Codex ralph 循环契约：

1. 将 /ralph “<任务>” [--completion-promise=文本] [--max-iterations=次数] 视为契约命令
2. 解析 XML 内的完成信号：<promise>值</promise>
3. 如果缺少承诺且迭代次数 < 最大迭代次数 → 立即使用相同原始命令继续
4. 如果找到承诺或达到最大迭代次数 → 以状态报告结束

完成承诺语法：

<promise>完成</promise>

Codex 的手动状态管理：

• 循环开始时创建 .omc/state/ralph-state.json
• 每个周期更新 iteration 计数器
• 找到承诺时将 status： “complete”
• 默认完成承诺：完成 | 默认最大迭代次数：10

Gemini CLI（AfterAgent 钩子模式）

# 通过扩展安装
gemini extensions install https://github.com/Q00/ouroboros
# 或者安装技能模板
gemini extensions install https://github.com/supercent-io/skills-template

需要在 ~/.gemini/settings.json 中：

{
  "hooksConfig": { "enabled": true },
  "context": {
    "includeDirectories": ["~/.gemini/extensions/ralph"]
  }
}

用于循环继续的 AfterAgent 钩子（添加到 ~/.gemini/settings.json）：

{
  "hooks": {
    "AfterAgent": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "bash ~/.gemini/hooks/ralph-check.sh",
        "timeout": 10
      }]
    }]
  }
}

以沙盒 + YOLO 模式运行，防止持续确认提示：

gemini -s -y

然后直接使用 ooo 命令：

ooo interview “构建一个任务命令行工具”
ooo ralph “修复所有测试”

⚠️ Gemini v0.30.0 错误：钩子 JSON 中的 stop_hook_active 始终为 false。
解决方法：直接检查 .omc/state/ralph-state.json，而不是依赖钩子字段。

8. 平台支持矩阵

9. 快速参考

10. 安装

# Claude Code
claude plugin marketplace add Q00/ouroboros
claude plugin install ouroboros@ouroboros
ooo setup

# Codex CLI
bash <技能目录>/ralph/scripts/setup-codex-hook.sh

# Gemini CLI (扩展)
gemini extensions install https://github.com/Q00/ouroboros

# 所有平台通过技能模板
npx skills add https://github.com/supercent-io/skills-template --skill ralph

来源：Q00/ouroboros — MIT 许可证