Autopilot 自动循环编排引擎

SKILL.md

---
name: autopilot
description: 自动循环编排引擎 — Plan(OMC opus) → Build(OMX) → Verify(Orchestrator) 循环执行复杂任务，最多5轮自动收敛。当用户提到"自动执行"、"循环执行"、"帮我自动完成"、需要多步验证的复杂重构、自动修复循环、多模块联动修改时触发。即使用户没有明确说"autopilot"，只要任务复杂度需要计划→执行→验证→修复的循环，就应该建议使用本技能。简单单文件修改直接派发 OMC 或 OMX 即可。
version: 2.2.0
metadata:
  openclaw:
    os: ["darwin", "linux"]
    requires:
      bins: ["claude", "omx", "python3"]
author: user
source: user-created
created_at: '2026-04-29'
updated_at: '2026-04-30'
---

# Autopilot — Plan → Build → Verify 自动循环

## 前置条件

- **`claude -p` 需要 `ANTHROPIC_API_KEY`**：Claude Code 的 `-p/--print` 管道模式依赖 API Key 认证，不支持 OAuth 交互登录。设置：`export ANTHROPIC_API_KEY="sk-ant-..."`
- `claude` CLI 已安装
- `omx` CLI 已安装
- Python 3.9+

Autopilot 让 编排器自动驱动复杂编码任务走向收敛：OMC(opus) 出结构化计划，OMX 按计划写代码（默认 GPT 最新模型），编排器跑测试验证。验证不通过就带着错误报告回到 OMC 重新规划，最多 5 轮。

为什么需要循环？因为单次派发 OMC 或 OMX 适合简单任务，但复杂任务（系统重构、多模块联动、需要测试回归验证）往往一次做不对。Autopilot 通过 Plan→Build→Verify 循环逐步收敛，每轮都知道上一轮哪里错了。

## 快捷指令

| 指令 | 用途 |
|------|------|
| `启动 autopilot <描述>` 或 `启动 autopilot <描述>` | 启动自动循环 |
| `启动 autopilot <描述> -d <目录>` | 指定工作目录 |
| `查看状态 <task_id>` | 查看任务状态和轮次 |
| `恢复任务 <task_id>` | 恢复中断的任务 |

> 匹配规则：消息以 "autopilot" 或 "自动执行" 开头即触发。`-d` 后的路径运行时展开为绝对路径，`task.json` 和命令中禁止保存 `~` 简写。

## 核心角色分工

| 角色 | 谁来做 | 做什么 |
|------|--------|--------|
| **Orchestrator** | 编排器 | 理解需求、补充上下文、驱动循环、检查计划、验证结果、决定继续或退出 |
| **Planner** | OMC (claude opus) | 只读分析项目，输出结构化 `plan-{round}.md`，不修改任何文件 |
| **Builder** | OMX (omx exec) | 根据 plan 写代码、修改文件、补测试 |
| **Verifier** | 编排器 | 跑测试、检查 git diff、逐条比对验收标准 |

为什么这样分工？OMC 的 opus 模型擅长深度分析和结构化思考但不应该动文件；OMX 擅长执行但需要精确指令；验证由编排器自己做是因为 编排器能直接跑测试和读文件，最可靠。

**关键约束**：三个角色之间没有共享内存——所有上下文必须通过任务目录的文件传递。这是设计而非限制：文件传递让每个 agent 拿到的上下文是明确可控的，不会因为隐式上下文导致不一致。

## 循环控制

最多 5 轮（`pbv_max_rounds = 5`）。每轮生成独立的 `plan-{round}.md`、`result-{round}.txt`、`verify_report-{round}.md`。

**退出条件**（任一满足即退出）：
- ✅ `verify_passed`：验收标准全通过，成功退出
- 🛑 `max_rounds(5)`：第 5 轮仍失败，汇报最佳结果和剩余问题
- 🛑 `consecutive_same_error(2轮)`：连续两轮 P0 问题相同——说明当前方案解决不了，再试也是烧钱
- 🛑 `no_progress`：连续两轮验证报告高度相似（问题汇总+修复方向相似度 >80%）
- ⏹ `user_cancel`：用户主动取消，保留任务目录供 恢复操作

plan 质量不达标时允许本轮内重试最多 2 次（不增加 `pbv_round`），因为 plan 是整个循环的基础——plan 错了后面全白费。

## 编排流程

### Phase 0: 初始化

1. 解析指令：提取任务描述、`-d` 工作目录（未提供时用当前会话工作目录）
2. **预检**（复用 omc-omx-orchestrator 的 Step 0 逻辑）：
   - 工作目录存在且为目录
   - `which claude` 和 `which omx` 都有输出
   - 非 git 目录时设置 `sandbox_args="--skip-git-repo-check"`
3. 创建任务目录：`~/.openclaw/workspace/tasks/{timestamp}-{slug}/`
4. 写 `task.json`（扩展字段见下方）
5. 写 `spec_plan.md`：用户原始需求 + 编排器补充的上下文（项目路径、技术栈、当前分支、约束、初始验收标准）

### Phase 1: Plan（OMC）

1. 更新 `pbv_round += 1`，`pbv_status = planning`
2. 构建 OMC 命令，spec_plan.md 作为输入，输出重定向到 `plan-{round:03d}.md`：

```bash
cat {task_dir}/spec_plan.md | \
claude -p --output-format text --verbose --model claude-opus-4-6 - \
  > {task_dir}/plan-{round:03d}.md \
  2> {task_dir}/plan-{round:03d}.log ; \
echo $? > {task_dir}/plan-{round:03d}.exit_code
```

> ⚠️ **绝不加 `--max-turns`** — text 模式下 `max-turns` 会过早终止输出。text 模式无 JSONL 膨胀问题，不需要限制 turns。

3. OMC 崩溃时重试一次；仍失败则终止任务
4. **编排器检查 plan 质量**：
   - 有 `## 执行步骤` 和至少一个 `### Step`
   - 有明确可验证的验收标准
   - 有 `## 文件清单`
   - 不通过则补充要求重新生成（本轮内最多 2 次，不算新轮次）

### Phase 2: Build（OMX）

1. 从 plan 构建 `spec_build.md`——必须包含完整上下文：用户需求、项目路径、当前轮计划、上一轮失败摘要（如有）、约束、验收标准、允许修改的文件清单
2. 更新 `pbv_status = building`
3. 构建 OMX 命令：

```bash
cat {task_dir}/spec_build.md | \
omx exec --dangerously-bypass-approvals-and-sandbox \
  -o {task_dir}/result-{round:03d}.txt \
  -C {cwd} \
  {sandbox_args} - \
  2> {task_dir}/build-{round:03d}.log ; \
echo $? > {task_dir}/build-{round:03d}.exit_code
```

4. OMX 崩溃时重试一次；仍失败则终止任务
5. 更新 `pbv_status = build_done`

### Phase 3: Verify（编排器）

1. 更新 `pbv_status = verifying`
2. 从 `plan-{round}.md` 提取验收标准和文件清单
3. 运行验证（详见 `references/verify-guide.md`）：
   - **测试**：优先 `项目测试脚本（如 scripts/run_tests.sh、pytest 等）`，否则 `pytest`/`npm test` 等；无测试时记录 ⚠️
   - **文件变更**：`git diff --stat` 检查实际修改是否和 plan 一致
   - **验收标准**：逐条核对，给出 ✅/❌/⚠️ + 证据
4. 写 `verify_report-{round:03d}.md`（格式见 `references/verify-guide.md`）
5. 通过 → Phase 4；失败 → 提取错误摘要（≤500字），检查退出条件，未触发则回到 Phase 1

### Phase 4: 交付

1. 汇总所有轮次的 plan/result/verify_report
2. 更新 `task.json`：`status=completed`、`completed_at=<ISO时间>`
3. 通知用户：成功时给验证命令；失败时给退出原因和下一步建议

## task.json 扩展字段

在 omc-omx-orchestrator 基础 schema 上增加：

```json
{
  "mode": "autopilot",
  "engine": "autopilot",
  "pbv_round": 0,
  "pbv_status": "planning",
  "pbv_max_rounds": 5,
  "pbv_history": [
    {"round": 1, "plan": "plan-001.md", "result": "verify_failed", "error_summary": "..."}
  ]
}
```

`pbv_status` 流转：`planning` → `plan_done` → `building` → `build_done` → `verifying` → `verify_passed` / `verify_failed`

## 成本预估

| 场景 | 轮次 | 耗时 | 成本 |
|------|------|------|------|
| 简单（1轮过） | 1 | 8-22 min | ~$7.65 |
| 中等 | 2-3 轮 | 16-66 min | ~$15-23 |
| 复杂（4-5轮） | 4-5 轮 | 32-110 min | ~$30-38 |

每轮：OMC ~$1.50 + OMX ~$6.00 + Verify ~$0.15。5轮上限 + 相同错误退出 + 无进展退出 控制成本。

## 故障处理

- **OMC/OMX 崩溃或超时**：重试一次，仍失败则编排器可选择直接接管执行（而非终止任务）
- **编排器中断**：`恢复任务 <task_id>` 从 `pbv_status` 和 `pbv_round` 继续
- **plan 质量不达标**：本轮内最多重试 2 次，不算新轮次
- **无测试**：不能仅因无测试而判定通过，必须逐条验收

### 外部 Agent 全部失败时的编排器接管

当 OMC（Plan）和 OMX（Build）均超时或失败时，编排器作为 Orchestrator 可以直接接管：

1. **Plan 接管**：编排器直接分析需求，写 `plan-{round}.md`
2. **Build 接管**：编排器直接执行文件修改、创建脚本等
3. **Verify**：始终由编排器执行

适用条件：
- 任务需求明确，编排器能理解技术栈和目标
- 不需要深度分析复杂项目结构
- 文件数量可控（<10 个新建/修改）

### Plan 阶段 OMC 故障恢复

**text 模式（默认）故障**：
1. 输出格式不规范 → 补充 `spec_plan.md` 中的格式要求重试
2. 截断 → 检查是否 spec_plan.md 过大，精简后重试

**stream-json 模式故障**：
1. 上下文爆炸（tool 调用过多）→ 降低 `--max-turns` 或改用 text 模式
2. MCP 权限请求循环 → 改用 text 模式
3. 输出全是 JSONL 错误事件 → 改用 text 模式

⚠️ **text 模式绝不加 `--max-turns`** — 会立即终止输出。stream-json 模式必须加 `--max-turns 30-50`。

### Build 阶段 OMX 模型不可用

OMX (Codex) 使用 ChatGPT 账号时，不支持外部模型名（`o3`、`claude-sonnet-4` 等全部报 400）。

**恢复**：改用 OMC 替代 OMX 执行 Build 阶段：
```bash
cat "$TASK_DIR/spec_build.md" | \
claude -p --output-format text --verbose \
  --model claude-sonnet-4-20250514 \
  --dangerously-skip-permissions - \
  > "$TASK_DIR/result-001.txt" 2> "$TASK_DIR/build-001.log"
```

技巧：spec 里已经包含完整的修复方案和精确的代码 diff，OMC 只需照做即可，不需要 OMX 级别的自主决策能力。

## 与现有技能的关系

- **依赖 omc-omx-orchestrator**：本技能的 Plan 和 Build 阶段分别调用 OMC（`claude -p`）和 OMX（`omx exec`），复用其命令模板、目录结构、预检逻辑
- 共享 `~/.openclaw/workspace/tasks/` 和 `task-recovery.py`
- 不修改 omc-omx-orchestrator；`/omc` `/omx` 继续服务单次派发
- 循环控制逻辑完全在本 SKILL.md 中，不创建额外 Python 脚本

## 上下文管理策略

Plan 阶段的 OMC（opus）容易爆上下文，因为 opus 倾向深度阅读所有相关文件。Build 阶段的 OMX 相对稳定（执行型任务）。

**Plan 阶段（OMC）管道模式**：

默认使用 **text 模式**（`--output-format text`，不加 `--max-turns`）。优势：
- 无 JSONL 膨胀，上下文利用率高
- 适合大多数计划生成场景（Round 1 的深度分析 + Round 2+ 的修复规划）
- 不需要 `--input-format stream-json` 的 JSON 封装

**何时用 stream-json**：
- 轻中度任务（不需要深度探索项目结构）
- OMC 只需读少量文件 + 产出 plan
- 必须加 `--max-turns 30-50` 防止 JSONL 膨胀撑爆上下文
- ⚠️ stream-json 下 tool 调用次数受限（30-50），**无法完成复杂分析任务**

**核心区别**：

| | text 模式（默认） | stream-json 模式 |
|---|---|---|
| tool 调用 | 不限轮次，OMC 自由探索 | 限制 30-50 轮（JSONL 膨胀） |
| 上下文 | 纯文本，无膨胀 | JSONL 元数据膨胀快 |
| 适合场景 | 复杂深度分析（默认） | 轻中度任务、简单修复计划 |
| max-turns | 不设 | 必须 30-50 |

stream-json 命令（轻中任务备选）：
```bash
cd {cwd} && \
python3 -c "import json, pathlib; \
  p = pathlib.Path('{task_dir}/spec_plan.md'); \
  print(json.dumps({'type':'user','message':{'role':'user','content': \
    p.read_text() + '\n\n要求：只读分析，输出符合 autopilot plan 格式的结构化计划，不要修改文件。'}}))" | \
claude -p --input-format stream-json --output-format stream-json \
  --verbose --max-turns 40 --model claude-opus-4-6 --tools default - \
  > {task_dir}/plan-{round:03d}.md \
  2> {task_dir}/plan-{round:03d}.log ; \
echo $? > {task_dir}/plan-{round:03d}.exit_code
```

## plan.md 格式（OMC 必须遵循）

```markdown
# Plan: {task description}
> Round: {round_number} | Task: {task_id}

## 任务概述
{一段话说清楚要达成什么}

## 执行步骤

### Step 1: {标题}
- **目标**: {本步骤要达成的目标}
- **操作**: {具体要做什么}
- **预期输出**: {完成后应该看到什么}
- **验收标准**:
  - [ ] {可验证标准1}

## 文件清单
| 文件路径 | 操作 | 说明 |
|---------|------|------|

## 风险点
1. {风险}: {缓解措施}

## 完成标准
- [ ] 所有Step执行完成
- [ ] 所有验收标准通过
- [ ] 测试套件通过
```

## verify_report.md 格式（编排器必须遵循）

```markdown
# Verify Report - Round {round_number}
> Task: {task_id} | Status: PASSED/FAILED

## 总结
{一句话描述验证结果}

## 验证详情

### 测试运行
- **命令**: {执行的测试命令}
- **退出码**: {code}
- **结果**: PASSED/FAILED
- **关键错误**: {前5个最关键的错误，去重去噪}

### 文件变更检查
- **预期修改**: {plan中的文件清单}
- **实际修改**: {git diff结果}
- **差异**: {不在plan中但被修改的文件}

### 验收标准核对
| 标准 | 状态 | 备注 |
|------|------|------|
| {标准1} | ✅/❌/⚠️ | {说明} |

## 问题汇总
1. **P0**: {关键问题}
2. **P1**: {重要问题}

## 建议修复方向
1. {针对P0的修复建议}
```

错误摘要规则：只保留 P0/P1，每个一句话+文件定位，总长 ≤500字，P0 优先截断。连续两轮 P0 相同 → `consecutive_same_error` 退出。

## 参考文件

详细说明和检查清单在 `references/` 目录：

- `references/plan-format.md` — plan 格式设计要点 + Plan 检查清单
- `references/verify-guide.md` — 验证操作完整步骤 + 错误摘要生成规则详解 + 500字限制原因