omh-ralph

OMH Ralph — 经验证的执行（v2）

需要 OMH 插件。 从此仓库将 plugins/omh/ 安装到 ~/.hermes/plugins/omh/。

适用场景

• 你有一个计划（来自 omh-ralplan 或手动制定），需要经验证的执行
• 用户说：“ralph”“不要停”“直到完成”“必须完成”“继续”
• 你需要有保证的验证——不只是“看起来完成了”，而是有证据支持的完成
• 多步骤实现，其中每项任务都必须单独验证

不适用场景

• 不存在计划或规格说明（请先使用 omh-deep-interview 和/或 omh-ralplan）
• 简单的单文件更改（直接完成即可）
• 用户明确要求跳过验证

架构：每次调用处理一项任务

每次 ralph 调用只执行一项工作，然后退出。调用方会再次调用，以处理下一项任务。这样可以避免上下文窗口耗尽，并让每次调用都成为一个干净的检查点。

Invocation N:  read state → pick task → execute → verify → update state → EXIT
Invocation N+1: read state → pick next task → execute → verify → update state → EXIT
...
Final invocation: all tasks pass → architect review → mark complete → EXIT

流程

步骤 0：解析实例并获取锁

Ralph 和 autopilot 会修改共享的 .omh/plans/ 计划。两个会话同时针对同一计划运行 ralph，会导致 ralph-tasks 状态发生竞争，并产生不确定的结果。使用按实例划分的状态和咨询锁，确保并发计划安全。

1. 根据计划路径解析 instance_id：
   • 默认计划来源：.omh/plans/ralplan-*.md 或 .omh/plans/ralph-plan.md。
   • instance_id = basename(plan_path) without ".md"（引擎会生成 slug）。
   • 如果计划尚不存在（步骤 2 将会选择计划），则使用 instance_id="default"。
2. 在读取/写入状态前获取锁：

   lock = omh_state(action="lock", mode="ralph",
                    lock_key="{instance_id}",
                    session_id="{HERMES_SESSION_ID or uuid}",
                    holder_note="ralph executing {plan_path}")
   

   • acquired=true：继续。
   • acquired=false：向用户报告 held_by（pid + session_id + started_at）。提供以下选项：等待 / 取消持锁方 （omh_state(action="cancel", mode="ralph", instance_id="{instance_id}")， 然后在下一次调用时，系统会通过过期 PID 检测自动释放已失效持锁方的锁）/ 选择其他计划。
3. 在本次调用的后续每个 omh_state 调用中传入 instance_id——ralph 模式和 ralph-tasks 模式都要传入。
4. 在每个退出点释放锁（成功、受阻、取消、达到最大迭代次数、异常）：

   omh_state(action="unlock", mode="ralph",
             lock_key="{instance_id}",
             session_id="{HERMES_SESSION_ID or uuid}")
   

   将流程主体包裹起来，确保即使出错也会触发解锁。

单例回退方案（旧版）。 如果调用方省略 instance_id， 引擎会写入旧版 .omh/state/ralph-state.json 并跳过加锁。 仅在一次只处理一个计划的设置中使用此方案。

步骤 1：读取状态

state = omh_state(action="read", mode="ralph", instance_id="{instance_id}")

• state.exists=false：全新开始——转到步骤 2（规划门控）。
• state.data.active=true：恢复执行——转到步骤 3。
• state.data.phase="complete"：报告完成情况。询问用户是否要重新开始。
• state.data.phase="blocked"：报告阻碍因素。询问问题是否已解决。
• state.data.active=false, phase="cancelled"：报告取消情况。提供恢复执行的选项。

检查取消信号：

cancel = omh_state(action="cancel_check", mode="ralph", instance_id="{instance_id}")

如果 cancel.cancelled=true：将 phase 设为 "cancelled"，写入状态，然后退出。

检查状态是否过期：如果 state.stale=true，警告用户并提供继续执行或重新开始的选项。

递增 state.data.iteration。如果 iteration > max_iterations（默认值为 100）： 将 phase="blocked" 写入状态，报告“已达到最大迭代次数”，然后退出。

步骤 2：规划门槛

Ralph MUST 先有计划才能执行。按顺序检查来源：

1. omh_state(action="check", mode="ralph-tasks", instance_id="{instance_id}") → exists=true — 已解析，跳到步骤 3
2. .omh/plans/ralplan-*.md — 解析为 ralph-tasks 状态：omh_state(action="write", mode="ralph-tasks", instance_id="{instance_id}", data={...})
3. .omh/plans/ralph-plan.md — 解析为 ralph-tasks 状态
4. 未找到任何内容 → 告知用户：“未找到计划。请先运行 omh-ralplan。”

计划解析规则：

• 提取带有标题、描述和验收标准的编号任务
• 拒绝“实现已完成”等泛化标准——必须可测试
• 确保任务原子化：将多部分任务拆分为单独条目
• 按依赖顺序分配优先级（无依赖的任务优先）
• 将所有任务设为 passes: false

写入初始状态：

omh_state(action="write", mode="ralph", instance_id="{instance_id}", data={
  "active": true, "phase": "execute", "iteration": 0,
  "session_id": "<uuid>", "max_iterations": 100,
  "task_prompt": "<original user request>",
  "current_task_id": null,
  "started_at": "<ISO 8601 timestamp>",
  "project_path": "<absolute path to project root>",
  "files_modified": [],
  "error_history": [],
  "completed_task_learnings": []
})

步骤 3：选择下一个任务

读取任务列表：

tasks = omh_state(action="read", mode="ralph-tasks", instance_id="{instance_id}")

1. 如果所有任务的 passes: true → 前往步骤 7（最终审查）
2. 查找符合条件的任务：passes=false 且所有依赖均已满足
3. 如果没有符合条件的任务，但仍有未完成任务 → 依赖死锁 → 设置 phase="blocked"，写入状态，然后退出
4. 在符合条件的任务中，按优先级选择（数字越小越优先）

**并行执行：**如果有 2-3 个符合条件且相互独立的任务（没有共同的文件 影响范围，且彼此没有依赖关系），将它们合并到一次 delegate_task 调用中。

步骤 4：执行

委派给执行器子 Agent：

delegate_task(
    goal="[omh-role:executor] Implement this task:\n\n{task.title}\n{task.description}\n\nAcceptance Criteria:\n{task.acceptance_criteria}",
    context="Project Context:\n{tech stack, conventions, relevant paths}\n\nPrevious Feedback (if retry):\n{task.verifier_verdict}\n\nLearnings from prior tasks:\n{state.data.completed_task_learnings}"
)

目标中的 [omh-role:executor] 标记会使 OMH 插件自动将执行器角色提示词 注入子 Agent 的系统提示词中——无需内联。 （不使用插件时的备用方案：将该标记替换为 omh_state(action="load_role", role="executor") 并在上下文中传入返回的提示词文本。）

解析执行器的响应：COMPLETE → 步骤 5，PARTIAL → 步骤 5， BLOCKED → 记录阻塞原因，必要时添加发现的任务，更新状态，然后退出。

步骤 5：验证

A 部分：收集证据

evidence = omh_gather_evidence(commands=[
    "{project build command}",
    "{project test command}",
    "{project lint command}"
])

使用项目实际的构建、测试和 lint 命令。该工具会捕获输出、 强制执行超时，并返回 {results, all_pass, summary}。

B 部分：委派给验证器

delegate_task(
    goal="[omh-role:verifier] Verify whether this task's acceptance criteria are met:\n\n{task.title}\n{task.acceptance_criteria}\n\nExecutor Report:\n{task.executor_report}",
    context="Evidence:\n{evidence.results}"
)

解析验证器的响应：

• APPROVE / PASS：设置 task.passes = true。向学习记录追加： {task_id, summary, files_changed, gotchas}。追加到 .omh/logs/ralph-progress.md。
• REQUEST_CHANGES / FAIL：记录 task.verifier_verdict。检查三次失败规则（步骤 6）。

步骤 6：错误处理

**三次失败断路器：**构造错误指纹 {task_id, category, error_key}。 将其添加到 task.error_fingerprints。如果有 3 个指纹具有相同的 category + error_key： 将任务标记为阻塞，记录错误，并在下次调用时继续处理下一个符合条件的任务。 如果所有剩余任务都被阻塞：写入 phase="blocked"，报告情况，然后退出。

取消检测（如果用户说“停止”“取消”“中止”）：

omh_state(action="cancel", mode="ralph", instance_id="{instance_id}", reason="user request")

然后将 phase="cancelled" 写入状态，并退出，同时提供恢复说明。

步骤 7：最终审查

所有任务的 passes: true 时：

evidence = omh_gather_evidence(commands=["{build command}", "{test command}"])

delegate_task(
    goal="[omh-role:architect] Review the complete implementation for architectural soundness.\n\nOriginal Plan:\n{source plan text}\n\nTasks Completed:\n{summary of all tasks + learnings}",
    context="Evidence:\n{evidence.results}\n\nFiles Changed Across All Tasks:\n{aggregate file list}"
)

• APPROVE：写入 {active: false, phase: "complete"}，清除状态文件，保留进度日志。
• REQUEST_CHANGES：添加带有 discovered: true 的新任务，并设置 phase="execute"。

步骤 8：更新状态并退出

每次操作后：

omh_state(action="write", mode="ralph", instance_id="{instance_id}", data={...updated state...})

正常退出。调用方会再次调用以进行下一轮迭代。

易忽略事项

• 绝不要跳过规划关卡。 没有计划，就不能执行。
• 绝不要在没有验证者证据的情况下相信执行者的说法。 验证者必须查看 omh_gather_evidence 的输出。
• 不要在委派给验证者的过程中收集证据。 委派前先收集证据。
• 不要混淆验证者和架构师。 两者的工作、提示词和阶段都不同。
• 遵守 3 次错误规则。 同一错误出现 3 次 → 提出根本问题。
• 将经验教训传递下去。 在每次委派给执行者时都包含 completed_task_learnings。
• 使用 [omh-role:NAME] 标记——OMH 插件会自动将角色提示词注入子代理会话。绝不要手动内联角色提示词文本。可用角色：executor、verifier、architect、planner、critic、analyst、security-reviewer、code-reviewer、test-engineer、debugger。未安装插件时的替代方案：omh_state(action="load_role", role="NAME")，并在上下文中传入返回的提示词。

Sentinel 约定

其他技能会检测 ralph 状态：

• omh_state(action="check", mode="ralph", instance_id="{instance_id}") → {exists, active, phase, stale}
• phase="complete" → ralph 已成功完成
• phase="blocked" → ralph 需要介入