Oh-my-openagent 完整使用教程

方某人不认输
0 阅读14分钟

Oh-my-openagent 完整使用教程

本教程基于官方文档整理，涵盖核心使用要素、基础使用教程和进阶配置玩法。

📚 目录

  1. 核心使用要素

  2. 基础使用教程

  3. 进阶配置与玩法

一、核心使用要素

1.1 Agent 体系架构

Oh-my-openagent 采用多模型 Agent 编排架构，将单一 AI Agent 转变为协调的开发团队：

用户请求
    ↓
[Intent Gate] — 识别用户真实意图
    ↓
[Sisyphus] — 主调度器，规划并委派任务
    ↓
    ├─→ [Prometheus] — 战略规划师（访谈模式）
    ├─→ [Atlas] — 任务执行协调器
    ├─→ [Oracle] — 架构顾问
    ├─→ [Librarian] — 文档/代码搜索
    ├─→ [Explore] — 快速代码库探索
    └─→ [Category-based agents] — 按任务类型分类的专员

核心理念：不同任务分配给最适合的模型，Claude 做编排、GPT 做推理、Kimi 提速度、Gemini 处理视觉任务。

1.2 核心 Agent 介绍

Agent推荐模型职责描述
SisyphusClaude Opus 4.6 / Kimi K2.5 / GLM 5主调度器，制定计划、分配任务、推动任务直至完成
HephaestusGPT-5.4自主深度工作者，端到端独立执行任务，无需手把手指导
PrometheusClaude Opus 4.6 / Kimi K2.5战略规划师，通过访谈模式确定范围并构建执行计划
AtlasClaude Sonnet 4.6任务执行协调器，系统化执行 Prometheus 制定的计划
OracleGPT-5.4只读高智商顾问，用于架构决策和复杂调试
LibrarianMiniMax M2.7多仓库分析，文档查询，开源代码搜索
ExploreGrok Code Fast 1快速代码库探索和上下文感知搜索
MomusGPT-5.4无情审查员，验证计划的清晰度、可验证性和完整性
MetisClaude Opus 4.6差距分析器，捕获 Prometheus 遗漏的内容

1.3 Category 分类系统

Category 是按任务类型优化的 Agent 配置预设。不再按模型名委派，而是按任务类型委派：

Category默认模型适用场景
visual-engineeringGemini 3.1 Pro前端、UI/UX、设计、样式、动画
ultrabrainGPT-5.4 (xhigh)深度逻辑推理、复杂架构决策
deepGPT-5.3 Codex (medium)目标导向的自主问题解决，深度调研
artistryGemini 3.1 Pro (high)高度创意/艺术任务、新颖想法
quickGPT-5.4 Mini简单任务 - 单文件修改、拼写修正
unspecified-highClaude Opus 4.6 (max)不适合其他类别的高工作量任务
writingGemini 3 Flash文档、散文、技术写作

使用方法：

task({
  category: "visual-engineering",
  prompt: "为仪表板页面添加响应式图表组件"
});

1.4 Skill 技能系统

Skill 为特定领域提供专业工作流，包含：

  • 面向特定领域的极度调优系统指令
  • 按需加载的独立 MCP 服务器
  • 对 Agent 能力边界的强制约束

内置 Skill：

Skill触发词描述
playwright浏览器任务、测试、截图通过 Playwright MCP 进行浏览器自动化
git-mastercommit, rebase, squashGit 专家，自动检测提交风格，拆分原子提交
frontend-ui-uxUI/UX 任务、样式设计师转开发者，无需设计稿也能打造精美 UI
dev-browser状态化浏览器脚本持久页面状态的浏览器自动化

加载方式：

task({
  category: "visual-engineering",
  load_skills: ["frontend-ui-ux", "playwright"],
  prompt: "..."
});

1.5 模型适配与选择

Claude-like 模型（指令遵循、结构化输出）：

  • Claude Opus 4.6, Claude Sonnet 4.6, Claude Haiku 4.5
  • Kimi K2.5 — 行为与 Claude 非常相似
  • GLM 5 — Claude-like 行为，适合广泛任务

GPT 模型（显式推理、原则驱动）：

  • GPT-5.4 — 深度编码强大，Hephaestus 和 Oracle 必需
  • GPT-5-Nano — 超便宜、快速工具任务

差异化行为模型：

  • Gemini 3.1 Pro — 擅长视觉/前端任务
  • MiniMax M2.7 / M2.7-highspeed — 快速智能的工具任务
  • Grok Code Fast 1 — 针对代码搜索优化

默认配置建议：

{
  "agents": {
    "sisyphus": { "model": "kimi-for-coding/k2p5" },
    "librarian": { "model": "google/gemini-3-flash" },
    "oracle": { "model": "openai/gpt-5.4", "variant": "high" }
  },
  "categories": {
    "visual-engineering": { "model": "google/gemini-3.1-pro" },
    "ultrabrain": { "model": "openai/gpt-5.4", "variant": "xhigh" },
    "quick": { "model": "openai/gpt-5.4-mini" }
  }
}

二、基础使用教程

2.1 安装与初始化

给用户的安装方式：
复制以下提示词给你的 LLM Agent（Claude Code, AmpCode, Cursor 等）：

Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

给 LLM Agent 的安装方式：

curl -s https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

深度上下文初始化：
执行 /init-deep 生成树状的 AGENTS.md 文件系统：

project/
├── AGENTS.md              ← 全局级架构与约定
├── src/
│   ├── AGENTS.md          ← src 级规范
│   └── components/
│       └── AGENTS.md      ← 组件级详细说明

2.2 三种工作模式详解

模式一：简单任务 —— 直接提示

适用场景：简单任务、快速修复、单文件修改

使用方法：直接描述你的需求

修复 auth.ts 中的类型错误
模式二：Ultrawork 模式 —— 懒人模式

适用场景：复杂任务但懒得解释上下文，让 Agent 自己搞定

使用方法：

ultrawork
# 或简写
ulw

特点：

  • Agent 自动探索代码库
  • 研究已有模式
  • 实现功能
  • 用诊断工具验证
  • 持续工作直到完成

示例：

ulw 修复失败的测试
ulw 为 API 添加输入验证
ulw 实现 JWT 认证，遵循现有模式
模式三：Prometheus 模式 —— 精确模式

适用场景：多步骤复杂任务、关键生产环境变更、复杂重构、需要文档化决策轨迹

使用方法：

  1. 按 Tab 进入 Prometheus 模式，描述工作：
我想重构认证系统

  1. 回答访谈问题 —— Prometheus 会像真正的工程师那样采访你：

    • 目标是什么？
    • 范围边界在哪里？
    • 有什么硬性约束？
    • 测试策略是什么？

  2. 生成计划 —— Prometheus 在 .sisyphus/plans/ 创建详细计划

  3. 执行计划 —— 输入 /start-work，Atlas 接管执行：

/start-work

流程图：

User: 我想重构认证系统
    ↓
Prometheus: 你有什么测试来验证当前行为？
    ↓
User: 有 auth.test.ts 和 integration.test.ts
    ↓
Prometheus: 回滚策略是什么？
    ↓
User: 可以回滚到上一个 commit
    ↓
Prometheus: [生成计划 .sisyphus/plans/auth-refactor.md]
    ↓
User: /start-work
    ↓
Atlas: 开始执行任务 1/5...

2.3 常用命令速查

命令描述使用场景
/init-deep初始化分层 AGENTS.md 知识库新项目首次使用
/start-work从 Prometheus 计划开始执行已有计划，开始执行
/ralph-loop启动自引用开发循环直到完成需要持续迭代直到完成的复杂任务
/ulw-loop启动 ultrawork 循环高强度自动模式
/cancel-ralph取消活跃的 Ralph 循环需要停止循环
/refactor智能重构需要安全重构代码
/stop-continuation停止所有继续机制想让 Agent 停止当前工作流
/handoff创建详细上下文摘要需要在新会话中继续工作

2.4 简单任务示例

示例 1：修复类型错误
修复 src/utils/auth.ts 中的类型错误

Agent 会自动定位错误、分析原因并修复。

示例 2：添加新功能
ulw 为用户资料页面添加暗黑模式切换功能

Agent 会：

  1. 探索现有代码库找到相关文件
  2. 研究当前主题实现方式
  3. 实现暗黑模式切换组件
  4. 更新样式
  5. 验证无错误
示例 3：代码重构
/refactor src/components/Button.tsx --scope=module

Agent 会使用 LSP、AST-grep、架构分析和 TDD 验证进行智能重构。

示例 4：浏览器自动化
/playwright 导航到 example.com 并截图

或使用 agent-browser：

使用 agent-browser 导航到 example.com 并提取主标题

三、进阶配置与玩法

3.1 编排系统深度使用

3.1.1 Prometheus + Atlas 完整工作流

Step 1: 规划阶段

# 切换到 Prometheus 模式（按 Tab 选择 Prometheus）
我想构建一个带有用户认证的 REST API

Prometheus 会问你：

  • 核心目标是什么？
  • 范围边界？
  • 技术栈选择？
  • 认证策略？
  • 测试策略？

Step 2: Metis 差距分析
Prometheus 会自动咨询 Metis，捕获遗漏：

  • 隐藏的用户意图
  • 可能导致偏差的模糊性
  • AI 反模式（过度工程、范围蔓延）
  • 缺失的验收标准

Step 3: Momus 审查（高精度模式）
如果用户要求高精度，Momus 会验证计划：

  1. 清晰度：每个任务是否指定了查找实现细节的位置？
  2. 可验证性：验收标准是否具体且可测量？
  3. 上下文：是否有足够上下文进行而无需 >10% 的猜测？
  4. 大局观：目的、背景和工作流程是否清晰？

Step 4: 执行阶段

/start-work

Atlas 会：

  1. 读取计划
  2. 分析任务
  3. 积累智慧
  4. 委派任务
  5. 验证结果
  6. 最终报告

Wisdom 积累系统：

.sisyphus/notepads/{plan-name}/
├── learnings.md      # 模式、约定、成功方法
├── decisions.md      # 架构选择和理由
├── issues.md         # 问题、阻碍、遇到的陷阱
├── verification.md   # 测试结果、验证结果
└── problems.md       # 未解决问题、技术债务
3.1.2 何时使用什么模式

决策流程图：

是快速修复或简单任务吗？
  └─ 是 → 正常提示
  └─ 否 → 解释完整上下文是否繁琐？
              └─ 是 → 输入 "ulw" 让 Agent 自己搞定
              └─ 否 → 需要精确、可验证的执行吗？
                         └─ 是 → 使用 @plan 进行 Prometheus 规划，然后 /start-work
                         └─ 否 → 使用 "ulw"
复杂度方法何时使用
简单直接提示简单任务、快速修复、单文件修改
复杂 + 懒人输入 ulw 或 ultrawork复杂任务但解释上下文很繁琐
复杂 + 精确@plan → /start-work需要真正编排的精确多步骤工作

3.2 Category + Skill 组合策略

3.2.1 组合公式

Category（类别）描述"这是什么类型的工作？"，Skill（技能）提供"需要什么工具和知识？"。两者结合产生最优 Agent。

组合示例：

角色Categoryload_skills效果
设计师（UI 实现）visual-engineering["frontend-ui-ux", "playwright"]实现美学 UI 并直接在浏览器中验证渲染结果
架构师（设计审查）ultrabrain[]利用 GPT-5.4 xhigh 推理进行深入的系统架构分析
维护者（快速修复）quick["git-master"]使用成本效益模型快速修复代码并生成干净提交
3.2.2 委派 Prompt 黄金法则

委派时必须包含这 7 个元素：

  1. TASK：需要做什么？（单一目标）
  2. EXPECTED OUTCOME：可交付成果是什么？
  3. REQUIRED SKILLS：通过 load_skills 加载哪些技能？
  4. REQUIRED TOOLS：必须使用哪些工具？（白名单）
  5. MUST DO：必须做什么（约束）
  6. MUST NOT DO：绝不能做什么
  7. CONTEXT：文件路径、现有模式、参考资料

❌ 错误示例：

"修复这个"

✅ 正确示例：

TASK：修复 LoginButton.tsx 中的移动端布局破坏问题
CONTEXT：src/components/LoginButton.tsx，使用 Tailwind CSS
MUST DO：在 md: 断点处更改 flex-direction
MUST NOT DO：修改现有桌面布局
EXPECTED：按钮在移动端垂直对齐

3.3 自定义配置详解

3.3.1 配置文件位置
~/.config/opencode/oh-my-openagent.json    # 全局用户配置
.opencode/oh-my-openagent.json             # 当前项目配置
3.3.2 完整配置示例
{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json",

  "agents": {
    // 主调度器：Claude Opus 或 Kimi K2.5 效果最佳
    "sisyphus": {
      "model": "kimi-for-coding/k2p5",
      "ultrawork": { "model": "anthropic/claude-opus-4-6", "variant": "max" }
    },

    // 研究 Agent：便宜模型即可
    "librarian": { "model": "google/gemini-3-flash" },
    "explore": { "model": "github-copilot/grok-code-fast-1" },

    // 架构咨询：GPT 或 Claude Opus
    "oracle": { "model": "openai/gpt-5.4", "variant": "high" }
  },

  "categories": {
    // 前端工作：Gemini 主导视觉任务
    "visual-engineering": {
      "model": "google/gemini-3.1-pro",
      "variant": "high"
    },

    // 一般高工作量任务
    "unspecified-high": {
      "model": "anthropic/claude-opus-4-6",
      "variant": "max"
    },

    // 快速任务：使用 GPT-5.4-mini（快速且便宜）
    "quick": { "model": "openai/gpt-5.4-mini" },

    // 深度推理：GPT-5.4
    "ultrabrain": {
      "model": "openai/gpt-5.4",
      "variant": "xhigh"
    }
  },

  "tmux": {
    "enabled": true,
    "layout": "main-vertical"
  },

  "ralph_loop": {
    "enabled": true,
    "default_max_iterations": 100
  }
}
3.3.3 Category 配置字段详解
字段类型描述
descriptionstring类别用途的人类可读描述
modelstring使用的 AI 模型 ID
variantstring模型变体（如 max, xhigh）
temperaturenumber创造力水平（0.0 ~ 2.0），越低越确定性
top_pnumber核采样参数（0.0 ~ 1.0）
prompt_appendstring选择此类别时附加到系统提示的内容
thinkingobject思考模型配置 { type: "enabled", budgetTokens: 16000 }
reasoningEffortstring推理努力程度（low, medium, high）
maxTokensnumber最大响应 token 数
toolsobject工具使用控制（用 { "tool_name": false } 禁用）
3.3.4 自定义 Category 示例
{
  "categories": {
    // 1. 定义新的自定义类别
    "korean-writer": {
      "model": "google/gemini-3-flash",
      "temperature": 0.5,
      "prompt_append": "你是韩语技术写手。保持友好清晰的语气。"
    },

    // 2. 覆盖现有类别（更改模型）
    "visual-engineering": {
      "model": "openai/gpt-5.4",
      "temperature": 0.8
    },

    // 3. 配置思考模型并限制工具
    "deep-reasoning": {
      "model": "anthropic/claude-opus-4-6",
      "thinking": {
        "type": "enabled",
        "budgetTokens": 32000
      },
      "tools": {
        "websearch_web_search_exa": false
      }
    }
  }
}

3.4 自动化工作流

3.4.1 Ralph Loop（自我引用闭环）

用途：自我引用开发循环，达到 100% 完成度才停止

使用方法：

/ralph-loop "构建带有用户认证的 REST API"
/ralph-loop "重构支付模块" --max-iterations=50

工作原理：

  • Agent 持续朝着目标工作
  • 检测 <promise>DONE</promise> 标记知道何时完成
  • 如果 Agent 停止但未完成，自动继续
  • 结束条件：检测到完成、达到最大迭代次数（默认 100）、或执行 /cancel-ralph
3.4.2 Ultrawork Loop

用途：与 ralph-loop 相同，但以 ultrawork 模式运行

特点：

  • 一切以最大强度运行
  • 并行 Agent、后台任务、激进探索
3.4.3 后台 Agent 并行执行

用途：同时启动 5+ 个专家并行工作

使用方法：

// 后台启动
task(
  subagent_type="explore",
  load_skills=[],
  prompt="查找认证实现",
  run_in_background=true
);

// 继续工作...
// 系统完成时通知

// 需要时检索结果
background_output(task_id="bg_abc123");

场景示例：

  • GPT 调试时 Claude 尝试不同方法
  • Gemini 写前端时 Claude 处理后端的
  • 启动大规模并行搜索，继续实现，就绪时使用结果
3.4.4 Tmux 可视化多 Agent

启用 tmux.enabled 在单独的 tmux 窗格中查看后台 Agent：

{
  "tmux": {
    "enabled": true,
    "layout": "main-vertical"
  }
}

在 tmux 中运行时：

  • 后台 Agent 在新窗格中生成
  • 实时观看多个 Agent 工作
  • 每个窗格显示 Agent 输出
  • Agent 完成时自动清理

3.5 人类介入机制

3.5.1 Intent Gate（意图门）

在执行任何请求前，Sisyphus 会分类用户的真实意图：

意图类型路由决策
研究/理解explore/librarian → 综合 → 回答
实现（显式）计划 → 委派或执行
调查explore → 报告发现
评估评估 → 提议 → 等待确认
修复诊断 → 最小化修复
开放式变更首先评估代码库 → 提议方法

为什么这很重要：

  • 告别被字面意思误导的 AI 废话
  • Agent 理解上下文、细微差别和真实目标
  • 减少误解，获得更好结果
3.5.2 Prometheus 访谈模式

Prometheus 会像真正的主管那样采访你：

重构任务的问题：

  • "什么测试验证当前行为？"
  • "回滚策略是什么？"

从零构建的问题：

  • "在代码库中发现了模式 X。遵循它还是偏离？"

中等规模任务的问题：

  • "什么绝对不能包含？硬性约束？"

架构任务的问题：

  • "预期生命周期？规模要求？"
3.5.3 何时让人类介入

应该质疑用户的情况：

  • 设计决策会导致明显问题
  • 方法与代码库中既定模式矛盾
  • 请求似乎误解了现有代码的工作原理

质疑格式：

我注意到 [观察]。这可能因为 [原因] 导致 [问题]。
替代方案：[你的建议]。
我应该继续你原来的请求，还是尝试替代方案？
3.5.4 工作交接（Handoff）

用途：创建详细上下文摘要以在新会话中继续工作

使用方法：

/handoff

生成内容：

  • 当前状态
  • 已完成内容
  • 剩余内容
  • 相关文件路径

使用场景：

  • 当前会话上下文窗口已满
  • 需要切换到不同设备
  • 长时间任务需要分段进行

🎯 最佳实践总结

1. 任务委派黄金法则

  • 多步骤任务 → 先创建 todo 列表
  • 每个 todo 必须是可在 1-3 个工具调用内完成的原子操作
  • 一次只有一个进行中的任务
  • 完成后立即标记完成（不要批量）

2. 模型选择速查

  • Claude Opus 4.6: 最佳整体体验，编排首选
  • Kimi K2.5: 优秀的 Claude 替代，很多用户专用此组合
  • GLM 5: 通过 Z.ai 的可靠选项
  • GPT-5.4: 深度架构推理，Hephaestus 和 Oracle 必需
  • Gemini 3.1 Pro: 视觉/前端任务王者

3. 常见反模式避免

  • ❌ 用 as any, @ts-ignore, @ts-expect-error 压制类型错误
  • ❌ 没有明确要求就提交
  • ❌ 在未读代码的情况下推测
  • ❌ 修复失败后让代码保持损坏状态
  • ❌ 向 explore/librarian 委托后，自己又手动搜索同样信息
  • ❌ 轮询 background_output 运行中的任务
  • ❌ 未收集 Oracle 结果就交付答案

4. 效率提升技巧

  • ✅ 并行启动 2-5 个 explore/librarian Agent
  • ✅ 使用 session_id 继续子 Agent 对话（节省 70%+ token）
  • ✅ 使用 Category 而非模型名进行委派
  • ✅ 使用 ulw 关键词激活 ultrawork 模式
  • ✅ 复杂任务使用 Prometheus 规划 + Atlas 执行

📖 延伸阅读

开始体验：安装完成后，输入 ultrawork 看看协调的 AI 团队能做什么！

avatar
文章
阅读
粉丝