first build nexus
This commit is contained in:
billyshen
471
openclaw/yunce/oh-my-opencode-使用指南.md
Normal file
471
openclaw/yunce/oh-my-opencode-使用指南.md
Normal file
@@ -0,0 +1,471 @@
|
||||
# oh-my-opencode 使用指南
|
||||
|
||||
> 多模型 Agent 编排框架 for OpenCode
|
||||
|
||||
---
|
||||
|
||||
## 一、概述
|
||||
|
||||
**oh-my-opencode** 是一个强大的多模型 Agent 编排框架，专为 OpenCode 设计。它通过多个专业化 Agent 的协作，实现复杂任务的自动化处理。
|
||||
|
||||
### 核心理念
|
||||
|
||||
- **多 Agent 协作**：不同 Agent 承担不同角色，各司其职
|
||||
- **意图分类**：自动识别任务类型并路由到合适的 Agent
|
||||
- **计划与执行分离**：战略规划与具体执行解耦
|
||||
|
||||
---
|
||||
|
||||
## 二、安装
|
||||
|
||||
### 方法一：npm 全局安装
|
||||
|
||||
```bash
|
||||
npm install -g oh-my-opencode
|
||||
```
|
||||
|
||||
### 方法二：OpenClaw 内置
|
||||
|
||||
如果已安装 OpenClaw，oh-my-opencode 通常已集成：
|
||||
|
||||
```bash
|
||||
# 检查是否可用
|
||||
oh-my-opencode --version
|
||||
# 或
|
||||
opencode --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、核心命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `oh-my-opencode run <任务>` | 自动执行指定任务 |
|
||||
| `opencode run <任务>` | 同上，快捷命令 |
|
||||
| `Ctrl+P` | 进入 **Prometheus 模式**（计划模式） |
|
||||
| `Ctrl+E` | 启动 **Atlas** 执行计划 |
|
||||
|
||||
### 命令行选项
|
||||
|
||||
```bash
|
||||
# 指定模型
|
||||
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：快速代码搜索
|
||||
|
||||
```bash
|
||||
# 使用 Explore 查找函数定义
|
||||
oh-my-opencode run "查找 auth.py 中的 login 函数"
|
||||
|
||||
# 使用 Librarian 查找文档
|
||||
oh-my-opencode run "查找 React Hooks 文档"
|
||||
```
|
||||
|
||||
### 用例 2：架构咨询
|
||||
|
||||
```bash
|
||||
# 询问 Oracle 架构建议
|
||||
oh-my-opencode run "如何设计微服务架构"
|
||||
```
|
||||
|
||||
### 用例 3：复杂编码任务
|
||||
|
||||
```bash
|
||||
# 使用 Hephaestus 进行深度开发
|
||||
oh-my-opencode run "实现一个 JWT 认证模块"
|
||||
```
|
||||
|
||||
### 用例 4：计划 + 执行
|
||||
|
||||
```
|
||||
1. 按 Ctrl+P 进入 Prometheus 模式
|
||||
2. 对话式描述需求：
|
||||
> 我需要一个用户权限系统
|
||||
3. Prometheus 分析并制定计划
|
||||
4. 确认计划后，按 Ctrl+E
|
||||
5. Atlas 执行计划
|
||||
6. Momus 审查代码
|
||||
```
|
||||
|
||||
### 用例 5：代码审查
|
||||
|
||||
```bash
|
||||
# 使用 Momus 审查代码
|
||||
oh-my-opencode run "审查 src/auth 模块的代码"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、配置
|
||||
|
||||
### 基本配置
|
||||
|
||||
`~/.oh-my-opencode/config.json`:
|
||||
|
||||
```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 别名
|
||||
|
||||
```json
|
||||
{
|
||||
"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 无响应
|
||||
|
||||
```bash
|
||||
# 查看 Agent 状态
|
||||
oh-my-opencode status
|
||||
|
||||
# 重置 Agent
|
||||
oh-my-opencode reset --agent <agent-name>
|
||||
```
|
||||
|
||||
### 模型调用失败
|
||||
|
||||
```bash
|
||||
# 检查 API 配置
|
||||
oh-my-opencode config --show
|
||||
|
||||
# 切换模型
|
||||
oh-my-opencode run <task> --model <alternative-model>
|
||||
```
|
||||
|
||||
### 执行中断恢复
|
||||
|
||||
```bash
|
||||
# 查看执行历史
|
||||
oh-my-opencode history
|
||||
|
||||
# 恢复执行
|
||||
oh-my-opencode resume --task-id <id>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十、进阶技巧
|
||||
|
||||
### 1. Agent 组合使用
|
||||
|
||||
```bash
|
||||
# 先搜索，再编码
|
||||
oh-my-opencode run "查找现有用户认证代码并优化"
|
||||
```
|
||||
|
||||
### 2. 上下文继承
|
||||
|
||||
在对话中连续使用，保持上下文：
|
||||
|
||||
```
|
||||
> 设计一个 API
|
||||
(Plan with Prometheus)
|
||||
> 按这个计划实现
|
||||
(Atlas executes)
|
||||
> 添加单元测试
|
||||
(Hephaestus)
|
||||
```
|
||||
|
||||
### 3. 输出格式
|
||||
|
||||
```bash
|
||||
# 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*
|
||||
Reference in New Issue
Block a user