跳转到内容
展示 生态 源码解读 文档

最佳实践

最佳实践

充分利用 Oh My OpenAgent 的模式和策略。

使用模式

单任务模式

直接描述你的任务。Sisyphus 自动处理委派：

refactor the auth module to use JWT instead of sessions

最适合：专注、定义明确的任务。

ultrawork 模式

一个词激活一切：

ultrawork: migrate the entire project from JavaScript to TypeScript

或者：

ulw: fix all ESLint warnings and add missing types

最适合：大型任务、多步骤工作、需要并行执行的任何任务。

何时使用 ultrawork：

  • 大规模重构任务
  • 全栈功能开发
  • 复杂问题分析
  • 多步骤实现

何时不使用 ultrawork：

  • 简单查询
  • 小范围单文件修改
  • 快速提问

访谈模式（Prometheus）

对于需要先规划的复杂任务：

/start-work

Prometheus 进入访谈模式 — 提出澄清问题，明确范围，构建经过验证的计划。然后 Sisyphus 执行。

最适合：需求不明确、高风险变更、规划节省的时间多于规划花费的时间的任务。

多模型策略

Oh My OpenAgent 自动将工作路由到最佳模型。但了解各模型的优势有助于你编写更好的提示词：

模型最擅长类别
Claude Opus 4.6编排、规划、细致推理Sisyphus、Prometheus
GPT-5.4深度自主推理、复杂调试Hephaestus、ultrabrain
Kimi K2.5快速编排、高性价比规划Sisyphus（替代）
GLM-5中文任务、通用编排Sisyphus（替代）

框架处理路由。你的任务是描述你想要什么，而不是怎么做。

上下文管理

AGENTS.md 层级结构

创建分层上下文文件以提升代理理解：

project/
├── AGENTS.md              ← 项目级标准
├── src/
│   ├── AGENTS.md          ← 源代码约定
│   └── components/
│       └── AGENTS.md      ← 组件专用规则

使用 /init-deep 自动生成这些文件。

条件规则

规则根据上下文自动激活：

## when: file.ext == "*.test.ts"
Use Jest and React Testing Library
Follow AAA pattern (Arrange, Act, Assert)

## when: agent == "oracle"
Provide detailed technical decision rationale
Consider long-term maintainability

故障排除

插件未加载

症状： 代理不使用 Oh My OpenAgent 功能。

修复：

  1. 检查 opencode.json 的 plugin 数组中是否包含 "oh-my-openagent"（或旧的 "oh-my-opencode"）
  2. 运行 bunx oh-my-opencode doctor
  3. 验证插件条目拼写正确

模型不可用

症状： 任务因模型错误失败。

修复：

  1. 检查是否为对应服务商配置了 API 密钥
  2. 配置 fallback_models，当服务商宕机时任务路由到替代方案
  3. 运行 bunx oh-my-opencode doctor 验证模型访问

上下文过长

症状： 代理触及上下文窗口限制。

修复：

  1. 启用激进截断："experimental": { "aggressive_truncation": true }
  2. 启用自动恢复："experimental": { "auto_resume": true }
  3. 使用 /init-deep 创建聚焦的 AGENTS.md 文件，而非大型单体文件

后台任务超时

症状： 并行代理在完成前失败。

修复：

  1. 降低并发："background_tasks": { "max_concurrent": 2 }
  2. 检查你的订阅级别的 API 频率限制
  3. 如有需要，添加按服务商的限制

真实案例研究

大规模 ESLint 修复

“用 Oh My Opencode 一天就搞定了 8000 个 eslint 警告” — Jacob Ferrari

模式：ulw: fix all ESLint warnings

  • Sisyphus 按文件组分解任务
  • 多个代理并行修复
  • Ralph Loop 确保不遗漏任何问题

全栈应用转换

“我用 Ohmyopencode 和 ralph loop 一夜之间将一个 4.5 万行的 tauri 应用转换为 SaaS Web 应用。从 interview me 提示词开始……看着它工作真是太神奇了，今天早上醒来看到了一个基本可用的网站！” — James Hargis

模式：/start-work（Prometheus 访谈） → ultrawork（执行）

  • Prometheus 规划迁移策略
  • Sisyphus 协调前端和后端代理并行工作
  • Hephaestus 自主处理深度转换工作
  • Ralph Loop 保持一切通宵运行

复杂 Bug 调试

模式：@explore + @oracle 协作

  1. @explore 追踪执行路径并识别可疑代码
  2. @oracle 分析潜在根因并提出假设
  3. 代理实施修复并验证
  4. LSP 工具确保修复不会破坏引用

最适合：生产问题、间歇性 bug、竞态条件。

文档生成

模式：@librarian + 上下文注入

  1. 运行 /init-deep 为代理提供项目上下文
  2. 使用 ultrawork: write complete API documentation
  3. Librarian 研究代码库
  4. 代理使用 LSP 验证的类型信息生成文档

快速参考

任务类型推荐命令涉及代理
大规模重构ulw: [任务描述]Sisyphus + Hephaestus + 专家
架构决策/start-workPrometheus → Sisyphus
Bug 修复@explore [bug 描述]Explore → Oracle
文档编写ulw: write docs for [功能]Librarian + 专家
快速修改[简单描述]Sisyphus（quick 类别）

后续步骤