14 KiB
14 KiB
title, source, author, published, created, description, tags
| title | source | author | published | created | description | tags |
|---|---|---|---|---|---|---|
| oh-my-opencode 使用指南 | shenwei |
oh-my-opencode 使用指南
多模型 Agent 编排框架 for OpenCode
一、概述
oh-my-opencode 是一个强大的多模型 Agent 编排框架，专为 OpenCode 设计。它通过多个专业化 Agent 的协作，实现复杂任务的自动化处理。
核心理念
- 多 Agent 协作：不同 Agent 承担不同角色，各司其职
- 意图分类：自动识别任务类型并路由到合适的 Agent
- 计划与执行分离：战略规划与具体执行解耦
二、安装
方法一：npm 全局安装
npm install -g oh-my-opencode
方法二：OpenClaw 内置
如果已安装 OpenClaw，oh-my-opencode 通常已集成：
# 检查是否可用
oh-my-opencode --version
# 或
opencode --version
三、核心命令
| 命令 | 说明 |
|---|---|
oh-my-opencode run <任务> |
自动执行指定任务 |
opencode run <任务> |
同上，快捷命令 |
Ctrl+P |
进入 Prometheus 模式（计划模式） |
Ctrl+E |
启动 Atlas 执行计划 |
命令行选项
# 指定模型
oh-my-opencode run <任务> --model opencode/claude-opus-4-6
# 指定 Agent
oh-my-opencode run <任务> --agent sisyphus
# dry-run 预览
oh-my-opencode run <任务> --dry-run
# 输出 JSON 格式
oh-my-opencode run <任务> --json
四、Agent 介绍
oh-my-opencode 包含多个专业化 Agent，形成完整的任务处理生态系统。
| Agent | 角色 | 主要职责 |
|---|---|---|
| Sisyphus | 主编排器 | 分类意图、委派任务、结果汇总 |
| Prometheus | 战略规划师 | 访谈式计划、深入分析需求 |
| Atlas | 执行者 | 执行 Prometheus 制定的计划 |
| Oracle | 架构顾问 | 技术架构咨询、最佳实践建议 |
| Hephaestus | 深度编码 Agent | GPT 原生深度代码生成 |
| Explore | 代码搜索 | 快速定位代码库中的内容 |
| Librarian | 文档搜索 | 文档和知识库检索 |
| Metis | 计划漏洞分析 | 识别计划中的潜在问题 |
| Momus | 严格审查 | 代码审查、质量把关 |
Agent 详细说明
Sisyphus（西西弗斯）- 主编排器
角色：团队 leader
特点：智能路由、任务分解
Sisyphus 是整个系统的核心，负责：
- 接收用户任务输入
- 识别任务意图和类型
- 决定调用哪个 Agent
- 汇总各 Agent 的结果
- 返回最终响应
Prometheus（普罗米修斯）- 战略规划师
角色：策略顾问
特点：访谈式、深入分析
Prometheus 专注于长期规划：
- 与用户进行问答式对话
- 深入理解需求和约束
- 制定详细的执行计划
- 识别潜在风险
激活方式：按 Ctrl+P 进入计划模式
Atlas（阿特拉斯）- 执行者
角色：执行者
特点：高效执行、结果导向
Atlas 负责执行：
- 读取 Prometheus 的计划
- 逐步执行任务
- 报告执行进度
- 处理执行中的问题
激活方式：按 Ctrl+E 启动执行
Oracle（甲骨文）- 架构顾问
角色：技术顾问
特点：全局视角、最佳实践
提供架构层面的指导：
- 系统设计建议
- 技术选型咨询
- 性能优化方案
- 代码规范
Hephaestus（赫菲斯托斯）- 深度编码
角色：高级工程师
特点：深度思考、复杂代码
专注于高质量代码生成：
- 复杂业务逻辑实现
- 算法设计与优化
- 代码重构
- 测试用例编写
Explore（探索者）- 代码搜索
角色：搜索专家
特点：快速定位、精准匹配
快速找到目标代码：
- 函数定义查找
- 代码片段搜索
- 依赖关系追踪
- 文件结构分析
Librarian（图书管理员）- 文档搜索
角色：知识管家
特点：信息检索、知识整合
文档和知识检索：
- API 文档查找
- 技术文章搜索
- 示例代码定位
- 问题解决方案
Metis（弥涅尔瓦）- 计划漏洞分析
角色：审计员
特点：批判性思维、风险识别
分析计划的问题：
- 逻辑漏洞检测
- 边界条件分析
- 依赖关系审查
- 风险点标注
Momus（摩墨斯）- 严格审查
角色：质量守门人
特点：严格标准、一丝不苟
代码审查：
- 代码质量评估
- 安全漏洞检测
- 风格一致性检查
- 最佳实践验证
五、工作流程
标准流程
┌─────────────────────────────────────────────────────────┐
│ 用户输入任务 │
└─────────────────────┬───────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ Sisyphus 分类意图 & 委派 │
│ (判断任务类型 → 选择合适 Agent) │
└─────────────────────┬───────────────────────────────────┘
▼
┌────────────┼────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Oracle │ │ Hephaestus│ │ Explore │
│ (架构) │ │ (编码) │ │ (搜索) │
└─────────┘ └─────────┘ └─────────┘
│ │ │
└────────────┼────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ Sisyphus 结果汇总 │
└─────────────────────┬───────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ 返回结果 │
└─────────────────────────────────────────────────────────┘
计划模式流程（Prometheus + Atlas）
┌─────────────────────────────────────────────────────────┐
│ 按 Ctrl+P → 进入 Prometheus 模式 │
└─────────────────────┬───────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ Prometheus 访谈式计划 │
│ - 询问需求细节 │
│ - 分析约束条件 │
│ - 制定执行计划 │
└─────────────────────┬───────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ 可选：Metis 漏洞分析 │
└─────────────────────┬───────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ 按 Ctrl+E → 启动 Atlas 执行计划 │
└─────────────────────┬───────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ Atlas 逐步执行 & 报告 │
└─────────────────────┬───────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ 可选：Momus 代码审查 │
└─────────────────────┬───────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ 完成 │
└─────────────────────────────────────────────────────────┘
六、常见用例
用例 1：快速代码搜索
# 使用 Explore 查找函数定义
oh-my-opencode run "查找 auth.py 中的 login 函数"
# 使用 Librarian 查找文档
oh-my-opencode run "查找 React Hooks 文档"
用例 2：架构咨询
# 询问 Oracle 架构建议
oh-my-opencode run "如何设计微服务架构"
用例 3：复杂编码任务
# 使用 Hephaestus 进行深度开发
oh-my-opencode run "实现一个 JWT 认证模块"
用例 4：计划 + 执行
1. 按 Ctrl+P 进入 Prometheus 模式
2. 对话式描述需求：
> 我需要一个用户权限系统
3. Prometheus 分析并制定计划
4. 确认计划后，按 Ctrl+E
5. Atlas 执行计划
6. Momus 审查代码
用例 5：代码审查
# 使用 Momus 审查代码
oh-my-opencode run "审查 src/auth 模块的代码"
七、配置
基本配置
~/.oh-my-opencode/config.json:
{
"defaultAgent": "sisyphus",
"model": "opencode/claude-opus-4-6",
"timeout": 300,
"agents": {
"sisyphus": {
"enabled": true
},
"prometheus": {
"enabled": true,
"questions": ["需求详情", "约束条件", "时间要求"]
},
"atlas": {
"enabled": true,
"stepDelay": 1000
}
}
}
Agent 别名
{
"aliases": {
"p": "prometheus",
"a": "atlas",
"o": "oracle",
"h": "hephaestus",
"e": "explore",
"l": "librarian",
"m": "metis",
"mo": "momus"
}
}
八、快捷键参考
| 快捷键 | 功能 |
|---|---|
Ctrl+P |
进入 Prometheus 计划模式 |
Ctrl+E |
启动 Atlas 执行 |
Ctrl+C |
中断当前任务 |
Ctrl+L |
清除输出 |
Tab |
自动补全 |
九、故障排除
Agent 无响应
# 查看 Agent 状态
oh-my-opencode status
# 重置 Agent
oh-my-opencode reset --agent <agent-name>
模型调用失败
# 检查 API 配置
oh-my-opencode config --show
# 切换模型
oh-my-opencode run <task> --model <alternative-model>
执行中断恢复
# 查看执行历史
oh-my-opencode history
# 恢复执行
oh-my-opencode resume --task-id <id>
十、进阶技巧
1. Agent 组合使用
# 先搜索，再编码
oh-my-opencode run "查找现有用户认证代码并优化"
2. 上下文继承
在对话中连续使用，保持上下文：
> 设计一个 API
(Plan with Prometheus)
> 按这个计划实现
(Atlas executes)
> 添加单元测试
(Hephaestus)
3. 输出格式
# JSON 输出
oh-my-opencode run <task> --json
# Markdown 报告
oh-my-opencode run <task> --report
# 仅显示差异
oh-my-opencode run <task> --diff
附录：Agent 选择指南
| 任务类型 | 推荐 Agent |
|---|---|
| 日常任务、简单咨询 | Sisyphus |
| 复杂需求、长期规划 | Prometheus |
| 执行既定计划 | Atlas |
| 架构设计、技术选型 | Oracle |
| 深度编码、复杂逻辑 | Hephaestus |
| 代码搜索、定位 | Explore |
| 文档查找、知识检索 | Librarian |
| 计划审查、漏洞分析 | Metis |
| 代码审查、质量把关 | Momus |
文档版本：1.0
最后更新：2026-03-16