omh-autopilot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OMH Autopilot — End-to-End Autonomous Pipeline

OMH Autopilot — 端到端自主工作流

When to Use

适用场景

End-to-end feature implementation from idea to verified, reviewed code
The user says: "autopilot", "build me", "handle it all", "e2e this"

从想法到经过验证、评审的代码的端到端功能实现
用户提出：“autopilot”、“帮我构建”、“全权处理”、“完成这个端到端流程”

When NOT to Use

不适用场景

Single-file changes or trivial tasks (just do them)
You want to stay in one continuous session (autopilot is multi-session)
You only need planning (omh-ralplan) or execution (omh-ralph)

单文件修改或琐碎任务（直接处理即可）
希望保持连续会话（autopilot为多会话模式）
仅需要规划（omh-ralplan）或执行（omh-ralph）功能

Prerequisites

前置条件

The
```
omh
```
plugin must be installed (
```
~/.hermes/plugins/omh/
```
)

必须安装
```
omh
```
插件（路径：
```
~/.hermes/plugins/omh/
```
）

Architecture: One Phase Step Per Invocation

架构：每次调用执行一个阶段步骤

Each autopilot invocation reads state, does ONE unit of work, exits. The caller re-invokes. This preserves fresh context at every level — including during the ralph loop.

Invocation 1:   Phase 0 — requirements (or skip)
Invocation 2:   Phase 1 — planning (or skip)
Invocations 3-N: Phase 2 — ralph iterations (one per call)
Invocation N+1: Phase 3 — QA cycle         [FRESH SESSION]
Invocation M:   Phase 4 — validation round  [FRESH SESSION]
Final:          Phase 5 — cleanup → complete

See

references/caller-examples.md

for how to drive the loop.

每次autopilot调用会读取状态，完成一项工作单元后退出。调用方会重新发起调用。这种方式在每个层级都能保留最新上下文——包括在ralph循环期间。

Invocation 1:   Phase 0 — requirements (or skip)
Invocation 2:   Phase 1 — planning (or skip)
Invocations 3-N: Phase 2 — ralph iterations (one per call)
Invocation N+1: Phase 3 — QA cycle         [FRESH SESSION]
Invocation M:   Phase 4 — validation round  [FRESH SESSION]
Final:          Phase 5 — cleanup → complete

更多调用示例请参考

references/caller-examples.md

。

Procedure

流程步骤

Step 0: Resolve Instance and Acquire Lock

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

Autopilot drives a goal through spec → plan → ralph → QA → validation. Two autopilot sessions on the same goal would race on

autopilot

ralph

, and

ralph-tasks

state simultaneously. Use per-instance state

advisory lock.

Resolve
instance_id
in this order:

If a confirmed spec exists at

.omh/specs/{name}-spec.md

, use

instance_id = "{name}"

Else if a plan exists at

.omh/plans/ralplan-{slug}.md

, use

instance_id = "{slug}"

Else derive from the goal:
```
instance_id = kebab(goal)[:60]
```
.

Acquire the autopilot lock:

lock = omh_state(action="lock", mode="autopilot",
                 lock_key="{instance_id}",
                 session_id="{HERMES_SESSION_ID or uuid}",
                 holder_note="autopilot driving {goal_or_plan}")

acquired=false

, report

held_by

, offer wait/cancel/different goal. Stale-pid auto-release applies.

Pass
instance_id
to every
omh_state
call in this invocation (autopilot, ralph, ralph-tasks).
When dispatching to ralph in Phase 2, pass the same
```
instance_id
```
in the delegation context so the ralph subagent acquires
```
mode="ralph"
```
lock on the same slug.

Release the autopilot lock at every exit point (paused, blocked, complete, exception):

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

Singleton fallback (legacy). Omitting
instance_id
writes
.omh/state/autopilot-state.json
and skips locking. Acceptable only when running one autopilot at a time.

Autopilot会推动目标从需求规格→规划→ralph执行→QA→验证的全流程。针对同一目标的两个autopilot会话会在

autopilot

、

ralph

和

ralph-tasks

状态上产生竞争。需使用每个实例的独立状态+建议性锁。

按以下顺序解析
instance_id
：

如果
```
.omh/specs/{name}-spec.md
```
存在已确认的需求规格，使用
```
instance_id = "{name}"
```
。

如果

.omh/plans/ralplan-{slug}.md

存在规划文档，使用

instance_id = "{slug}"

。

否则从目标推导：
```
instance_id = kebab(goal)[:60]
```
。

获取autopilot锁：

lock = omh_state(action="lock", mode="autopilot",
                 lock_key="{instance_id}",
                 session_id="{HERMES_SESSION_ID or uuid}",
                 holder_note="autopilot driving {goal_or_plan}")

如果

acquired=false

，报告

held_by

信息，提供等待/取消/更换目标的选项。过期进程会自动释放锁。

在本次调用的所有
omh_state
请求中传入
instance_id
（包括autopilot、ralph、ralph-tasks相关调用）。
在阶段2调度ralph时，在委托上下文中传入相同的
```
instance_id
```
，以便ralph子代理获取同一标识的
```
mode="ralph"
```
锁。

在所有退出点释放autopilot锁（暂停、阻塞、完成、异常）：

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

单例回退（旧版）：如果省略
instance_id
，会写入
.omh/state/autopilot-state.json
并跳过锁机制。仅在同时运行一个autopilot时适用。

On Every Invocation: Dispatch

每次调用：调度逻辑

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

Not found: Fresh start → Smart Detection (below)
Found: Check
```
context_checkpoint
```
flag → if true, clear it and exit (phase boundary)
Check staleness:
```
state.stale = true
```
→ warn, offer fresh start
Check pause: if
```
pause_after_phase
```
matches current completed phase → set phase="paused", exit
Dispatch to current phase handler

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

未找到状态：全新启动→智能检测（见下文）
找到状态：检查
```
context_checkpoint
```
标记→如果为true，清除标记并退出（阶段边界）
检查状态过期：
```
state.stale = true
```
→发出警告，提供重新启动选项
检查暂停设置：如果
```
pause_after_phase
```
与当前已完成阶段匹配→设置phase="paused"并退出
调度到当前阶段的处理逻辑

Smart Detection (Fresh Start)

智能检测（全新启动）

When no autopilot state exists, detect artifacts:

Confirmed spec in
```
.omh/specs/*-spec.md
```
→ create state at Phase 1
Consensus plan in
```
.omh/plans/ralplan-*.md
```
→ create state at Phase 2

Ralph complete (

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

→ phase="complete") → create state at Phase 3

Nothing → create state at Phase 0

Check for active ralph:

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

→ if active, warn about existing session.

omh_state(action="write", mode="autopilot", instance_id="{instance_id}", data={
    "phase": "requirements", "goal": "...", "ralph_iteration": 0,
    "qa_cycle": 0, "max_qa_cycles": 5, "validation_round": 0,
    "max_validation_rounds": 3, "validation_verdicts": {},
    "skip_qa": false, "skip_validation": false, "pause_after_phase": null
})

当不存在autopilot状态时，检测已有产物：

```
.omh/specs/*-spec.md
```
中存在已确认的需求规格→创建阶段1的状态
```
.omh/plans/ralplan-*.md
```
中存在共识规划→创建阶段2的状态
Ralph执行完成（
```
omh_state(action="check", mode="ralph", instance_id="{instance_id}")
```
返回phase="complete"）→创建阶段3的状态
无任何产物→创建阶段0的状态

检查是否有活跃的ralph会话：

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

→如果活跃，警告用户存在现有会话。

omh_state(action="write", mode="autopilot", instance_id="{instance_id}", data={
    "phase": "requirements", "goal": "...", "ralph_iteration": 0,
    "qa_cycle": 0, "max_qa_cycles": 5, "validation_round": 0,
    "max_validation_rounds": 3, "validation_verdicts": {},
    "skip_qa": false, "skip_validation": false, "pause_after_phase": null
})

Phase 0: Requirements

阶段0：需求确认

Goal: Ensure a confirmed spec exists.

Check
```
.omh/specs/*-spec.md
```
with
```
status: confirmed
```
→ found? Set
```
spec_file
```
, advance to Phase 1, exit
Not found — assess input:
- Concrete (file paths, function names, specific tech): generate inline spec, advance
- Vague: Load
```
omh-deep-interview
```
  and follow it. This phase is interactive.
Update state:
```
phase: "planning"
```
,
```
spec_file: "<path>"
```
. Exit.

For fully autonomous runs: run

omh-deep-interview

separately first.

目标：确保存在已确认的需求规格。

检查
```
.omh/specs/*-spec.md
```
中是否有
```
status: confirmed
```
的文档→找到？设置
```
spec_file
```
，推进到阶段1并退出
未找到→评估输入：
- 具体需求（含文件路径、函数名、特定技术）：生成内嵌需求规格，推进阶段
- 模糊需求：加载
```
omh-deep-interview
```
  并执行流程。本阶段为交互式。
更新状态：
```
phase: "planning"
```
，
```
spec_file: "<path>"
```
。退出。

完全自主运行建议：先单独运行

omh-deep-interview

。

Phase 1: Planning

阶段1：规划制定

Goal: Ensure a consensus plan exists.

Check
```
.omh/plans/ralplan-*.md
```
→ found? Set
```
plan_file
```
, advance to Phase 2, exit
Not found: Load
```
omh-ralplan
```
, follow its procedure with the spec as input

Update state:

phase: "execution"

plan_file

ralph_iteration: 0

context_checkpoint: true

. Exit.

目标：确保存在共识规划文档。

检查
```
.omh/plans/ralplan-*.md
```
→找到？设置
```
plan_file
```
，推进到阶段2并退出
未找到：加载
```
omh-ralplan
```
，以需求规格为输入执行其流程

更新状态：

phase: "execution"

，

plan_file

，

ralph_iteration: 0

，

context_checkpoint: true

。退出。

Phase 2: Execution (Ralph Iterations)

阶段2：执行（Ralph迭代）

Each invocation performs exactly ONE ralph iteration:

Run one ralph iteration via

delegate_task

with the omh-ralph skill context:

delegate_task(goal="[omh-role:executor] Follow the omh-ralph skill procedure:
  read state, pick the next incomplete task, execute it, verify, update state, exit.",
  context="<current ralph state + plan file contents>")

After ralph completes its step, check ralph status:

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

```
active=true
```
→ increment
```
ralph_iteration
```
, exit (caller re-invokes)

phase="complete"

→ advance:

phase: "qa"

context_checkpoint: true

, exit

```
phase="blocked"
```
→ set autopilot
```
phase: "blocked"
```
, report, exit

每次调用仅执行一次ralph迭代：

通过

delegate_task

调用一次ralph迭代，传入omh-ralph技能上下文：

delegate_task(goal="[omh-role:executor] Follow the omh-ralph skill procedure:
  read state, pick the next incomplete task, execute it, verify, update state, exit.",
  context="<current ralph state + plan file contents>")

ralph完成步骤后，检查其状态：

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

```
active=true
```
→递增
```
ralph_iteration
```
，退出（调用方重新发起调用）

phase="complete"

→推进阶段：

phase: "qa"

，

context_checkpoint: true

，退出

```
phase="blocked"
```
→设置autopilot的
```
phase: "blocked"
```
，报告状态并退出

Phase 3: QA Cycling

阶段3：QA循环

Each invocation performs ONE QA cycle. Starts in fresh session (context_checkpoint).

skip_qa: true

→ advance to Phase 4, exit.

Gather evidence using the project's actual build/test/lint commands (check for Makefile, package.json, Cargo.toml, pyproject.toml, etc. to determine the right commands):
```
evidence = omh_gather_evidence(commands=["<build>", "<test>", "<lint>"])
```

evidence.all_pass

→ advance:

phase: "validation"

context_checkpoint: true

, exit

If failures:
- Increment
```
qa_cycle
```
  . Check 3-strike on
```
qa_error_history
```
  . If triggered → phase="blocked", exit
- If
```
qa_cycle > max_qa_cycles
```
  (default 5) → phase="blocked", exit
- Delegate diagnosis to architect subagent (read-only)
- Delegate fix to executor subagent
- Update state, exit (next invocation re-runs QA)

每次调用执行一次QA循环。在全新会话中启动（context_checkpoint）。

如果

skip_qa: true

→推进到阶段4并退出。

使用项目实际的构建/测试/代码检查命令收集证据（检查Makefile、package.json、Cargo.toml、pyproject.toml等文件以确定正确命令）：
```
evidence = omh_gather_evidence(commands=["<build>", "<test>", "<lint>"])
```

如果

evidence.all_pass

→推进阶段：

phase: "validation"

，

context_checkpoint: true

，退出

如果存在失败：
- 递增
```
qa_cycle
```
  。检查
```
qa_error_history
```
  是否达到3次错误触发阈值→如果触发，设置phase="blocked"并退出
- 如果
```
qa_cycle > max_qa_cycles
```
  （默认5次）→设置phase="blocked"并退出
- 将问题诊断委托给架构师子代理（只读权限）
- 将修复任务委托给执行者子代理
- 更新状态，退出（下一次调用会重新运行QA）

Phase 4: Multi-Reviewer Validation

阶段4：多评审者验证

Each invocation performs ONE validation round. Starts in fresh session.

skip_validation: true

→ advance to Phase 5, exit.

Gather evidence using the project's actual build/test commands:
```
evidence = omh_gather_evidence(commands=["<build>", "<test>"])
```

Delegate 3 parallel reviews (exactly 3 = Hermes concurrent limit):

delegate_task(tasks=[
    {goal: "[omh-role:architect] Architectural review:\n{spec + plan}", context: "{evidence}"},
    {goal: "[omh-role:security-reviewer] Security review:\n{changed files list}", context: "{evidence}"},
    {goal: "[omh-role:code-reviewer] Code quality review:\n{changed files list}", context: "{evidence}"}
])

Record verdicts in
```
validation_verdicts
```
All APPROVE → advance to Phase 5, exit
Any REQUEST_CHANGES → delegate fix to executor, increment
```
validation_round
```
, exit

validation_round > max_validation_rounds

(default 3) → phase="blocked", exit

每次调用执行一次验证轮次。在全新会话中启动。

如果

skip_validation: true

→推进到阶段5并退出。

使用项目实际的构建/测试命令收集证据：

evidence = omh_gather_evidence(commands=["<build>", "<test>"])

委托3个并行评审任务（最多3个=Hermes并发限制）：

delegate_task(tasks=[
    {goal: "[omh-role:architect] Architectural review:\n{spec + plan}", context: "{evidence}"},
    {goal: "[omh-role:security-reviewer] Security review:\n{changed files list}", context: "{evidence}"},
    {goal: "[omh-role:code-reviewer] Code quality review:\n{changed files list}", context: "{evidence}"}
])

将评审结果记录到
```
validation_verdicts
```
全部通过APPROVE→推进到阶段5并退出
存在任何REQUEST_CHANGES→将修复任务委托给执行者，递增
```
validation_round
```
并退出
如果
```
validation_round > max_validation_rounds
```
（默认3次）→设置phase="blocked"并退出

Phase 5: Cleanup

阶段5：清理

Set
```
phase: "complete"
```
(safety — if interrupted, re-invocation retries cleanup)

Delete state files:

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

Preserve:
```
.omh/logs/
```
,
```
.omh/plans/
```
,
```
.omh/specs/
```
Report completion summary: goal, phases completed, ralph iterations, QA cycles, validation rounds

设置
```
phase: "complete"
```
（安全机制——如果被中断，重新调用会重试清理步骤）

删除状态文件：

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

保留以下目录：
```
.omh/logs/
```
、
```
.omh/plans/
```
、
```
.omh/specs/
```
报告完成总结：目标、已完成阶段、ralph迭代次数、QA循环次数、验证轮次

State Management

状态管理

All state via

omh_state

tool. Atomic writes and staleness handled automatically.

所有状态通过

omh_state

工具处理。自动处理原子写入和状态过期逻辑。

Sentinel Convention

哨兵约定

omh_state(action="check", mode="autopilot", instance_id="{instance_id}")
→ {exists, active, phase, stale}

omh_state(action="check", mode="autopilot", instance_id="{instance_id}")
→ {exists, active, phase, stale}

Pitfalls

注意事项

Don't loop ralph in a single session. Each ralph iteration is a separate invocation. Context exhaustion is real.
Don't reimplement ralph. Load the skill, follow its procedure.
Phase boundaries = fresh sessions. Respect
```
context_checkpoint
```
.
Don't skip QA. Ralph verifies per-task. QA catches integration issues.
Phase 0 is interactive if no spec exists. Pre-create specs for automated runs.
3 subagent limit. Phase 4 uses all 3 slots for parallel review.

不要在单个会话中循环调用ralph。每次ralph迭代都是独立的调用。上下文耗尽是真实存在的问题。
不要重新实现ralph。加载对应的技能并遵循其流程。
阶段边界=全新会话。请遵守
```
context_checkpoint
```
标记。
不要跳过QA。Ralph仅验证单个任务，QA能捕获集成问题。
如果没有需求规格，阶段0是交互式的。自动化运行请预先创建需求规格。
子代理限制为3个。阶段4会使用全部3个插槽进行并行评审。