Ultrawork 模式

目标驱动而非指令驱动：让 Agent（智能体） 自主探索代码库、研究模式、实现功能并验证结果的全自动工作流。

文章概述

Ultrawork 模式是 oh-my-openagent 的旗舰工作流。它的核心思路是：你不需要告诉 Agent 怎么做，只需要告诉它做什么。Agent 会自动探索代码库、研究现有模式、实现功能、通过 LSP 验证结果，然后根据结果决定下一步。这是从“给指令“到“给目标“的转变。

读完本文，你将能够启用 Ultrawork 模式让 Agent 自主完成从探索到验证的全流程，掌握 Ralph Loop 实现自我迭代直到任务完成，以及在合适的场景做出正确的模式选择。

本文从原理出发，深入讲解 Ultrawork 的工作机制和适用场景。你将学习如何启用 Ultrawork 模式（对话输入 ulw 或设置为默认模式），以及如何配合 Ralph Loop（/ulw-loop）实现自我迭代直到 100% 完成。我们还通过对比表分析 Ultrawork 与传统 Prompt（提示词） 方式在精准度、探索深度、Token 消耗和人工介入方面的差异，帮助你在合适的场景做出正确选择。

学习本文后，你会明白 Ultrawork 的核心价值：在不确定性和探索成本之间取得平衡。这在上下文复杂的任务、快速原型和大型重构中尤其有用。

⚠️ 何时不适合使用 Ultrawork：Ultrawork 的自主探索特性在某些场景下反而会成为问题。以下情况不建议使用：（1）严格合规要求——如金融审计、医疗合规等场景，需要每一步都有明确记录，Ultrawork 的过程不透明特性无法满足审计需求；（2）成本敏感环境——Ultrawork 的探索阶段会消耗大量 Token（典型会话 50K-200K tokens），在 API 调用成本受限时不宜使用；（3）精确输出要求——需要严格按照特定格式或规范输出的场景，Ultrawork 的自主判断可能导致输出偏差；（4）完全确定性的变更——如生产环境的关键配置修改，每一步都需要人工确认。在这些场景中，建议使用 Prometheus 规划模式 或传统 Prompt。

⏱ 时间有限？先读这些： Ultrawork 的工作原理 → Ultrawork 使用方式 → Ultrawork vs 传统 Prompt 对比 → Ralph Loop 机制

Ultrawork 的工作原理

定义：“懒得想“模式

Ultrawork 的核心理念可以用一句话概括：你只说目标，Agent 自己想办法。这是一种“懒得想“模式——当你不想花时间写详细的需求文档、不想逐步指导 Agent 如何实现时，Ultrawork 让 Agent 自主完成从探索到验证的全过程。

闭环工作机制

Ultrawork 的工作流程是一个持续迭代的闭环：

flowchart TB
    subgraph 探索阶段
        A[用户目标] --> B[探索代码库]
        B --> C[识别现有模式]
    end

    subgraph 实现阶段
        C --> D[制定实现方案]
        D --> E[编写代码]
    end

    subgraph 验证阶段
        E --> F[Oracle 验证]
        F --> G{VERIFIED?}
        G -->|否| H[分析错误]
        H --> D
        G -->|是| I[运行测试]
    end

    subgraph 决策阶段
        I --> J{测试通过?}
        J -->|否| K[定位失败原因]
        K --> D
        J -->|是| L{完成度评估}
        L -->|未完成| B
        L -->|完成| M[输出结果]
    end

    style A fill:#4A90D9,color:#fff
    style B fill:#50C878,color:#fff
    style C fill:#50C878,color:#fff
    style D fill:#FF9F43,color:#fff
    style E fill:#FF9F43,color:#fff
    style F fill:#A66CFF,color:#fff
    style M fill:#4A90D9,color:#fff

各阶段详解：

与传统 Prompt 的本质区别

传统 Prompt 模式是“指令驱动“：你需要详细说明每一步怎么做。Ultrawork 是“目标驱动“：你只说想要什么结果。

传统 Prompt 示例：

请帮我实现用户登录功能：
1. 先阅读 src/auth/ 目录下的现有认证代码
2. 参考 AuthService 的实现风格
3. 在 src/auth/LoginService.ts 中创建 LoginService 类
4. 实现 login 方法，使用 bcrypt 验证密码
5. 添加单元测试到 tests/auth/LoginService.test.ts
6. 运行测试确保通过

Ultrawork 示例：

ulw 实现用户登录功能

Agent 会自动完成上述所有步骤，无需你逐条指定。

Ultrawork 使用方式

方式一：对话中临时激活

在任意对话中输入 ulw 或 ultrawork，即可将当前会话切换到 Ultrawork 模式：

# 简写形式
ulw 为订单模块添加批量导出功能

# 完整形式
ultrawork 重构用户服务，提取公共逻辑

特点：

• 仅对当前任务生效
• 任务完成后恢复默认模式
• 适合临时性、探索性任务

方式二：设置为默认模式

在 .opencode/oh-my-openagent.jsonc 中配置默认模式（OMO v4.12.0+），让所有任务都使用 Ultrawork：

{
  "ultrawork": true,
  "ralph_loop": true
}

注：ultrawork 和 ralph_loop 是 oh-my-openagent（OMO）v4.12.0+ 的原生配置项，非 OpenCode 核心配置。OMO 采用扁平 boolean schema，不需要嵌套 default_mode 结构。

特点：

• 所有任务默认使用 Ultrawork
• 适合探索性开发、原型项目
• 可通过 /plan 命令临时切换到精确模式

方式三：配合 Ralph Loop 使用

使用 /ulw-loop 命令（OMO v1.15+）启动带自我迭代的 Ultrawork：

# 基础用法
/ulw-loop 实现用户登录功能

# 指定最大迭代次数
/ulw-loop --max-iterations=20 重构订单模块

# 自定义完成承诺
/ulw-loop --completion-promise="tests_pass" 添加单元测试

Ultrawork vs 传统 Prompt 对比

四维度对比表

决策指南：何时选择 Ultrawork

选择 Ultrawork 的场景：

1. 不熟悉的项目：Agent 自主探索比你自己研究更高效
2. 快速原型开发：时间紧迫，不需要完美方案
3. 探索性编程：不确定最佳实现路径，让 Agent 尝试
4. 大型重构：涉及多个模块，难以预见所有依赖
5. 文档补全：让 Agent 自动发现缺失文档的 API

选择传统 Prompt 的场景：

1. 关键业务逻辑：需要精确控制每个细节
2. 安全敏感代码：不允许自主决策
3. 需要审计轨迹：每一步都要有记录
4. 团队协作项目：变更需要可预测
5. 性能关键路径：实现方式有严格要求

Ultrawork 审计限制与弥补方案

Ultrawork 的“过程不透明“特性是其与 Prometheus 和传统 Prompt 的核心差异之一。了解具体哪些信息被记录、哪些未被记录，有助于在需要审计的场景中制定弥补策略。

已记录的信息：

未记录的信息：

弥补策略：

最佳实践：对于需要中等审计强度的场景，推荐“Prometheus 规划 + Ultrawork 执行“的组合模式。规划阶段生成的结构化计划作为审计基线，执行阶段的 Git 变更作为实现证据，两者结合即可覆盖大部分审计需求。

混合策略

实际项目中，建议采用混合策略：

graph LR
    A[新任务] --> B{熟悉项目?}
    B -->|否| C[Ultrawork 探索]
    B -->|是| D{任务关键性?}
    C --> E[理解上下文]
    E --> D
    D -->|高| F[传统 Prompt 精确控制]
    D -->|低| G[Ultrawork 快速实现]
    F --> H[完成]
    G --> H

    style C fill:#50C878,color:#fff
    style F fill:#4A90D9,color:#fff
    style G fill:#50C878,color:#fff

Ralph Loop 机制

什么是 Ralph Loop

Ralph Loop（/ulw-loop）是 Ultrawork 的自我迭代机制。与普通 Loop 不同，Ralph Loop 不是预设步骤的重复执行，而是 Agent 根据当前完成情况自主决定下一步行动。

核心理念：Agent 会持续工作直到任务 100% 完成，而非单次执行后停止。

Ralph Loop vs 普通 Loop

Ralph Loop 决策流程

下图展示了 Ralph Loop 的决策流程，从目标设定到完成验证的循环迭代步骤。

flowchart TB
    A[启动 /ulw-loop] --> B[执行当前任务]
    B --> C[评估完成度]
    C --> D{检测到 DONE 标签?}
    D -->|是| E[输出最终结果]
    D -->|否| F{达到最大迭代?}
    F -->|是| G[汇报当前进度<br/>等待用户决策]
    F -->|否| H[分析剩余工作]
    H --> I[规划下一步行动]
    I --> B

    G --> J{用户选择}
    J -->|继续| I
    J -->|调整目标| K[更新任务目标]
    K --> B
    J -->|终止| L[输出当前结果]

    style A fill:#4A90D9,color:#fff
    style E fill:#50C878,color:#fff
    style G fill:#FF9F43,color:#fff
    style L fill:#A66CFF,color:#fff

控制参数

完成承诺机制：

Ralph Loop 不依赖 stop_condition 或完成度百分比。它的停止机制基于 完成承诺（Completion Promise）——Agent 在输出中写入 DONE 标签声明任务完成。Loop 扫描到该标签即停止。

这是 Agent 自主报告的机制，并非系统级强制执行。Agent 可能在不适当的时候输出完成标签（见“已知限制“）。

完整配置示例

{
  "ultrawork": true,
  "ralph_loop": true
}

配置说明：

OMO 采用扁平 boolean schema，不存在 default_mode 嵌套结构或 ultrawork.enabled/ultrawork.maxParallelAgents/ultrawork.autoVerify/ultrawork.verificationLevel 等配置项。上述配置中 ultrawork 和 ralph_loop 是 OMO 插件提供的能力，非 OpenCode 核心配置。

当 max_iterations 达到时，循环自动终止。max_iterations 通过命令行参数 --max-iterations 传入，不在配置文件中设置。

实战案例：使用 Ultrawork 为开源项目添加功能

场景描述

假设你刚接手一个不熟悉的开源项目，需要为其添加“用户头像上传“功能。项目使用 React + Node.js + PostgreSQL 技术栈，但你不确定：

• 现有的文件上传机制是什么
• 用户模型如何定义
• API 路由如何组织
• 数据库迁移如何处理

使用 Ultrawork 完成

步骤 1：启动 Ultrawork

ulw 为用户添加头像上传功能，支持 JPG/PNG 格式，最大 2MB

步骤 2：观察 Agent 的探索过程

Agent 会自动执行以下操作：

[探索阶段]
→ 扫描项目结构，识别技术栈
→ 查找现有文件上传相关代码
→ 阅读用户模型定义
→ 分析 API 路由组织方式
→ 检查数据库迁移文件

[发现]
→ 项目已有 multer 中间件处理文件上传
→ 用户模型在 src/models/User.ts
→ API 路由在 src/routes/api/ 目录
→ 数据库迁移使用 Knex.js

[实现阶段]
→ 创建 src/routes/api/avatar.ts 路由
→ 扩展 User 模型添加 avatar_url 字段
→ 创建数据库迁移文件
→ 添加文件大小和格式验证
→ 编写单元测试

[验证阶段]
→ 运行 TypeScript 编译检查
→ 执行单元测试
→ 检查代码风格

[完成度评估]
→ 功能实现：100%
→ 测试覆盖：85%
→ 文档更新：待完成

[继续迭代]
→ 添加 API 文档
→ 更新 README

步骤 3：验收结果

Agent 会输出完整的变更摘要：

任务完成！已实现用户头像上传功能：

新增文件：
- src/routes/api/avatar.ts（头像上传路由）
- src/middleware/avatarValidator.ts（文件验证中间件）
- migrations/20260602_add_avatar_url.ts（数据库迁移）
- tests/api/avatar.test.ts（单元测试）

修改文件：
- src/models/User.ts（添加 avatar_url 字段）
- src/routes/index.ts（注册新路由）

测试结果：12/12 通过
代码风格检查：通过

使用 Ralph Loop 确保完整交付

如果需要确保测试覆盖率达到目标：

/ulw-loop --max-iterations=15 --completion-promise="coverage>80" 为用户添加头像上传功能

Agent 会持续迭代直到测试覆盖率达标：

[迭代 1] 实现基础功能，覆盖率 45%
[迭代 2] 添加边界条件测试，覆盖率 62%
[迭代 3] 添加错误处理测试，覆盖率 78%
[迭代 4] 添加文件验证测试，覆盖率 85%
[完成] 覆盖率达标，任务完成

前端组件开发工作流

对于前端开发者，Agent 编排可以将组件开发从“手写 boilerplate“转变为“描述目标 → Agent 生成 → 人工微调“的高效模式。下图展示了从设计稿到可用组件的完整 Agent 编排流程：

flowchart TB
    Input["设计稿 / 组件规格"] --> Step1

    subgraph Step1["步骤 1：生成组件骨架"]
        direction TB
        A1["Agent 生成 Props 类型定义"] --> A2["Agent 生成组件 Shell"]
        A2 --> A3["Agent 生成 Storybook 模板"]
    end

    Step1 --> Step2

    subgraph Step2["步骤 2：实现组件逻辑"]
        direction TB
        B1["Agent 实现状态管理"] --> B2["Agent 实现事件处理"]
        B2 --> B3["Agent 实现生命周期"]
    end

    Step2 --> Step3

    subgraph Step3["步骤 3：添加样式"]
        direction TB
        C1["Agent 应用 CSS/Tailwind"] --> C2["Agent 处理响应式布局"]
        C2 --> C3["Agent 适配暗色模式"]
    end

    Step3 --> Step4

    subgraph Step4["步骤 4：编写测试"]
        direction TB
        D1["Agent 生成单元测试"] --> D2["Agent 生成集成测试"]
        D2 --> D3["Agent 运行测试套件"]
    end

    Step4 --> Step5

    subgraph Step5["步骤 5：审查与迭代"]
        direction TB
        E1["Oracle 验证代码质量"] --> E2{测试通过?}
        E2 -->|否| E3["Agent 修复问题"]
        E3 --> E1
        E2 -->|是| E4["LSP 类型检查"]
    end

    Step5 --> Output["可用组件"]

    style Input fill:#FF9F43,color:#fff
    style Step1 fill:#4A90D9,color:#fff
    style Step2 fill:#4A90D9,color:#fff
    style Step3 fill:#50C878,color:#fff
    style Step4 fill:#50C878,color:#fff
    style Step5 fill:#FF9F43,color:#fff
    style Output fill:#4A90D9,color:#fff

这个流程的核心优势在于：前端开发者只需提供设计稿或组件规格描述，Agent 会自动完成从类型定义到测试的全流程。步骤 1-3 对应组件的“结构-逻辑-样式“三层分离，步骤 4-5 通过自动化测试和验证确保质量。整个过程中，开发者专注于设计意图的传达和最终审查，而非逐行编写 boilerplate 代码。

Ultrawork 的最佳实践

1. 提供清晰的目标描述

虽然 Ultrawork 是“目标驱动“，但目标本身的清晰度直接影响结果质量。

好的目标描述：

ulw 实现用户头像上传功能，支持 JPG/PNG，最大 2MB，存储到 S3

不好的目标描述：

ulw 加个头像功能

2. 利用 AGENTS.md 提供上下文

在项目的 AGENTS.md 中记录关键信息，帮助 Ultrawork 更好地理解项目：

## 技术栈

- 前端：React 18 + TypeScript
- 后端：Node.js + Express
- 数据库：PostgreSQL + Knex.js
- 文件存储：AWS S3

## 编码规范

- 所有 API 路由放在 src/routes/api/ 目录
- 使用 Zod 进行请求验证
- 测试文件与源文件同名加 .test.ts 后缀

3. 合理设置迭代参数

根据任务复杂度调整 max_iterations（默认 100，Ultrawork 默认 500）：

4. 监控 Token 消耗

Ultrawork 的探索过程会消耗较多 Token。Ralph Loop 默认 100 次迭代（Ultrawork 默认 500），Token 消耗可达常规模式的 5-10 倍。建议：

• 设置 max_iterations 限制迭代次数，避免无限消耗
• 使用 priority_patterns 优先探索关键文件
• 定期检查 Token 使用情况

5. 与版本控制配合

Ultrawork 完成后，建议：

1. 使用 git diff 审查所有变更
2. 运行完整测试套件
3. 检查是否有意外的文件修改
4. 确认变更符合预期后再提交

常见问题

Q: Ultrawork 会修改我不想修改的文件吗？

A: Ultrawork 遵循 AGENTS.md 中的约束规则。你可以在 AGENTS.md 中明确禁止修改某些文件：

## 约束规则

- 禁止修改 config/ 目录下的配置文件
- 禁止修改 migrations/ 目录下已执行的迁移文件
- 禁止直接修改数据库 schema

Q: Ultrawork 的探索过程会泄露敏感信息吗？

A: Ultrawork 只读取本地文件，不会将代码发送到外部服务器（除了发送给 LLM API）。建议：

• 不要在代码中存储敏感信息
• 使用环境变量管理密钥
• 将敏感文件添加到 .gitignore

Q: 如何中断 Ultrawork 的执行？

A: 在任何时候输入 /cancel-ralph 即可中断当前任务。Agent 会保存当前进度并输出已完成的工作。

Q: Ultrawork 适合生产环境部署吗？

A: Ultrawork 更适合开发阶段。生产环境的变更建议使用 Prometheus 模式，确保每一步都有审计轨迹。

已知限制

诚信系统漏洞（Honor System）

完成承诺机制（Completion Promise）依赖 Agent 自主报告。Agent 在输出中包含 DONE 标签即声明任务完成，Loop 扫描到该标签便停止。

这是一个“诚信系统“——系统不验证 Agent 是否真的完成了所有工作。已知问题：Agent 可能在不适当的时候输出完成标签，导致任务被过早标记为完成。

追踪：OMO issue #1921 — Agent 可能在未实际完成工作的情况下输出 DONE 标签。

缓解措施：

• 设置 verificationLevel: "strict" 启用严格的 Oracle 验证
• 降低 max_iterations 避免因迭代过多导致 Agent 过早声明完成
• 审查 Agent 输出的变更摘要，确认完成质量

流程图非系统级状态机

本书中的 Ultrawork 工作流流程图（探索 → 实现 → 验证 → 决策）表示的是 通过 Prompt 注入引导的 Agent 预期行为，而非系统级强制的状态机。Agent 的行为受 LLM 能力限制，实际执行路径可能与图示有偏差。

延伸阅读：Prometheus 规划模式

Ultrawork 的“先做再说“风格在处理探索性任务时非常高效。但对于另一些场景——需要审计轨迹、需求模糊或涉及多方利益时——我们提供了 Prometheus 规划模式。

Prometheus 模式（@plan）采用访谈式需求收集的工作方式。与 Ultrawork 的“你说目标我干活“不同，Prometheus 会主动向你提问，逐步澄清需求，直到形成一份结构化的执行计划，再由 Atlas 指挥官执行。

→ Prometheus 规划模式详解 — 了解访谈式规划、Atlas 执行指挥官和三模式决策框架的完整内容。

以下对比表帮助你在三种模式中快速选择：

选择指南：

需求明确 + 需要精确控制 → 传统 Prompt
需求模糊 + 需要审计轨迹 → Prometheus 模式
需求模糊 + 追求效率 → Ultrawork 模式

小结

Ultrawork 模式代表了 AI 编程的一次范式转变：从“告诉 Agent 怎么做“到“告诉 Agent 做什么“。这种目标驱动的方式在探索性任务、快速原型和不熟悉的项目中尤其有价值。

Ralph Loop（/ulw-loop）进一步增强了 Ultrawork 的能力，让 Agent 能够自我迭代直到任务完全完成。通过合理配置控制参数，你可以在效率和可控性之间找到平衡。

接下来 → Prometheus 规划模式 探讨了“计划优先“的方法论，它补充了 Ultrawork 的“探索优先“哲学。理解何时使用每种模式是 Harness Engineering（驾驭工程） 的核心能力之一。

常见反模式

目标设置过于宽泛

现象：给 Ultrawork 指定模糊目标，如“优化项目代码质量“，没有具体的衡量标准和范围界定。

原因：Ultrawork 的目标驱动特性要求目标明确可衡量。模糊目标导致 Agent 漫无目的地修改、引入不必要的变化。

对策：目标需要包含三个要素：做什么、范围在哪里、完成标准是什么。“优化 src/auth/ 模块的错误处理，使所有数据库操作都有 try/catch 和回滚机制“就是一个合格的目标。

不给 Agent 设置完成条件

现象：Ultrawork 启动后进入无限循环，不断探索和修改，始终不输出 DONE 标签。

原因：Agent 不知道任务何时算完成。没有明确的完成承诺（Completion Promise），Agent 倾向于持续优化。

对策：在 AGENTS.md 或 Prompt 中明确完成条件。“完成标准：所有测试通过，代码覆盖率 >= 80%，无 lint 错误”。设置 max_iterations 作为安全阀。

常见错误与陷阱

Agent 陷入无限循环

场景：Ultrawork 在执行“探索 → 实现 → 验证“循环时，验证失败后反复修改同一段代码，始终无法通过。

后果：Token 大量消耗，Agent 陷入局部最优陷阱，无法跳出当前问题。

预防：配置 max_iterations（默认 20）作为电路断路器。开启 verificationLevel: "strict" 让外部 Oracle 验证，减少 Agent 自我验证的幻觉。当发现 Agent 在同一个问题上循环 3 次以上，手动中断并重新调整方向。

上下文膨胀导致 Agent 行为异常

场景：Ultrawork 运行多轮迭代后，Agent 开始忽略早期的重要指令，输出质量下降。

后果：Agent 产生幻觉（如引用不存在的文件）、忘记关键约束、重复已经完成的工作。

预防：控制每次任务的目标范围。复杂项目拆分为多个 Ultrawork Session。使用 /new-session 清理上下文后继续下一步。

适用场景与限制

Ultrawork 最适合探索性任务、快速原型开发、技术调研和 Bug 修复等目标明确但实现路径不清晰的场景。它的自动化程度最高，人工介入最少。

以下情况 Ultrawork 不是最佳选择：需要严格审计轨迹的生产环境变更——建议使用 Prometheus 模式；需求模糊且涉及多方利益时——需要人工逐步澄清；对 Token 消耗敏感的场景——Ultrawork 的探索阶段有额外开销；涉及数据库写操作或生产配置变更——建议使用传统 Prompt + 人工确认。

Ultrawork 的 DONE 标签依赖 Agent 自主报告（诚信系统），系统不强制验证完成质量。建议在关键任务上配合 Code Review 或测试流程进行最终验证。

学习检查清单

完成本章学习后，请确认你能够：

• 解释 Ultrawork 的“目标驱动“理念与传统 Prompt 的区别
• 使用三种方式启用 Ultrawork：临时激活、默认模式、Ralph Loop
• 配置 Ultrawork 的控制参数（max_iterations、completion_promise 等）
• 判断何时选择 Ultrawork、何时选择传统 Prompt
• 使用 /ulw-loop 实现自我迭代的任务执行
• 了解 Prometheus 规划模式与 Ultrawork 的差异和配合方式（→ Prometheus 规划模式）

关联章节

• ← 工作流模式 — Command 触发 Ultrawork
• ← oh-my-openagent 集成 — OMO 配置是 Ultrawork 的基础
• → Prometheus 规划模式 — 对比探索优先 vs 计划优先
• → 多 Agent 协作 — Ultrawork 与多 Agent 协作的关系