介绍
# Oh My OpenCode
多智能体编排插件，将 OpenCode 转变为一个完整的智能体系统，配备专用智能体、后台任务执行、基于类别的模型路由和自主工作模式。
**包名**: `oh-my-opencode` (通过 `bunx oh-my-opencode install` 安装) **代码仓库**: https://github.com/code-yeongyu/oh-my-opencode **Schema**: https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json
---
## 前置要求
1. **OpenCode** 已安装并配置（`opencode --version` 应为 1.0.150+） ```bash curl -fsSL https://opencode.ai/install | bash # or: npm install -g opencode-ai # or: bun install -g opencode-ai ``` 2. 至少配置了一个 LLM 提供商（`opencode auth login`） 3. **强烈推荐**: Anthropic Claude Pro/Max 订阅（Sisyphus 使用 Claude Opus 4.5）
---
## 安装
运行交互式安装程序：
```bash bunx oh-my-opencode install ```
带提供商标志的非交互模式：
```bash bunx oh-my-opencode install --no-tui \ --claude=<yes|no|max20> \ --openai=<yes|no> \ --gemini=<yes|no> \ --copilot=<yes|no> \ --opencode-zen=<yes|no> \ --zai-coding-plan=<yes|no> ```
验证：
```bash opencode --version cat ~/.config/opencode/opencode.json # should contain "oh-my-opencode" in plugin array ```
---
## 两种工作流模式
### 模式 1: Ultrawork (快速自主工作)
在你的提示词中包含 `ultrawork` 或 `ulw`。就这样。
``` ulw add authentication to my Next.js app ```
智能体将自动： 1. 探索你的代码库以了解现有模式 2. 通过专用后台智能体研究最佳实践 3. 遵循你的规范实现功能 4. 通过诊断和测试进行验证 5. 持续工作直到 100% 完成
### 模式 2: Prometheus (精准规划工作)
对于复杂或关键任务：
1. **按下 Tab 键** → 切换到 Prometheus（规划器）模式 2. **描述你的工作** → Prometheus 采访你，在研究你的代码库时提出澄清性问题 3. **确认计划** → 在 `.sisyphus/plans/*.md` 中查看生成的计划 4. **运行 `/start-work`** → Atlas 编排器接管： - 将任务分发给专用子智能体 - 独立验证每个任务的完成情况 - 在任务间积累学习成果 - 跨会话跟踪进度（随时恢复）
**关键规则**：切勿在没有 `/start-work` 的情况下使用 Atlas。Prometheus 和 Atlas 是一对组合——始终一起使用。
---
## 智能体
默认情况下启用所有智能体。每个智能体都有默认模型和提供商优先级回退链。
| Agent | Role | Default Model | Provider Priority Chain | |-------|------|---------------|------------------------| | **Sisyphus** | 主编排器 | `claude-opus-4-5` | anthropic → kimi-for-coding → zai-coding-plan → openai → google | | **Sisyphus-Junior** | 专注任务执行者（通过带有类别的 `delegate_task` 使用） | 由类别决定 | 每类别特定链 | | **Hephaestus** | 自主深度工作者——目标导向，行动前先探索 | `gpt-5.2-codex` (medium) | openai → github-copilot → opencode (requires gpt-5.2-codex) | | **Oracle** | 架构、调试、高智商推理（只读） | `gpt-5.2` | openai → google → anthropic | | **Librarian** | 官方文档、OSS 搜索、远程代码库分析 | `glm-4.7` | zai-coding-plan → opencode → anthropic | | **Explore** | 快速代码库 grep（上下文搜索） | `claude-haiku-4-5` | anthropic → github-copilot → opencode | | **Multimodal Looker** | 图像/PDF/图表分析 | `gemini-3-flash` | google → openai → zai-coding-plan → kimi-for-coding → anthropic → opencode | | **Prometheus** | 工作规划器（基于访谈的计划生成） | `claude-opus-4-5` | anthropic → kimi-for-coding → openai → google | | **Metis** | 预规划顾问（歧义/失败点分析） | `claude-opus-4-5` | anthropic → kimi-for-coding → openai → google | | **Momus** | 计划审查者（清晰度、可验证性、完整性） | `gpt-5.2` | openai → anthropic → google | | **Atlas** | 计划编排器（通过 `/start-work` 执行 Prometheus 计划） | `k2p5` / `claude-sonnet-4-5` | kimi-for-coding → opencode → anthropic → openai → google | | **OpenCode-Builder** | 默认构建智能体（当 Sisyphus 激活时默认禁用） | 系统默认 | 系统默认 |
### 智能体调用
智能体通过 `delegate_task()` 或 `--agent` CLI 标志调用——而不是使用 `@` 前缀。
```javascript // Invoke a specific agent delegate_task(subagent_type="oracle", prompt="Review this architecture...")
// Invoke via category (routes to Sisyphus-Junior with category model) delegate_task(category="visual-engineering", load_skills=["frontend-ui-ux"], prompt="...")
// Background execution (non-blocking) delegate_task(subagent_type="explore", run_in_background=true, prompt="Find auth patterns...") ```
CLI：
```bash opencode --agent oracle opencode run --agent librarian "Explain how auth works in this codebase" ```
### 何时使用哪个智能体
| Situation | Agent | |-----------|-------| | 通用编码任务 | Sisyphus (default) | | 自主目标导向的深度工作 | Hephaestus (requires gpt-5.2-codex) | | 架构决策，2 次以上失败后的调试 | Oracle | | 查阅库文档，查找 OSS 示例 | Librarian | | 在代码库中查找代码模式 | Explore | | 分析图像、PDF、图表 | Multimodal Looker | | 需要计划的复杂多日项目 | Prometheus + Atlas (via Tab → `/start-work`) | | 预规划范围分析 | Metis | | 审查生成的计划是否有漏洞 | Momus | | 快速单文件更改 | 使用 `quick` 类别的 delegate_task |
---
## 类别
类别通过 `delegate_task()` 将任务路由到使用域优化模型的 Sisyphus-Junior。
| Category | Default Model | Variant | Provider Priority Chain | Best For | |----------|---------------|---------|------------------------|----------| | `visual-engineering` | `gemini-3-pro` | — | google → anthropic → zai-coding-plan | 前端、UI/UX、设计、样式、动画 | | `ultrabrain` | `gpt-5.2-codex` | `xhigh` | openai → google → anthropic | 深度逻辑推理、复杂架构 | | `deep` | `gpt-5.2-codex` | `medium` | openai → anthropic → google | 目标导向的自主问题解决（Hephaestus 风格） | | `artistry` | `gemini-3-pro` | `max` | google → anthropic → openai | 创意/新颖方法、非常规解决方案 | | `quick` | `claude-haiku-4-5` | — | anthropic → google → opencode | 琐碎任务、单文件更改、拼写错误修正 | | `unspecified-low` | `claude-sonnet-4-5` | — | anthropic → openai → google | 通用任务、低投入 | | `unspecified-high` | `claude-opus-4-5` | `max` | anthropic → openai → google | 通用任务、高投入 | | `writing` | `gemini-3-flash` | — | google → anthropic → zai-coding-plan → openai | 文档、散文、技术写作 |
### 类别用法
```javascript delegate_task(category="visual-engineering", load_skills=["frontend-ui-ux"], prompt="Create a dashboard component") delegate_task(category="ultrabrain", load_skills=[], prompt="Design the payment processing flow") delegate_task(category="quick", load_skills=["git-master"], prompt="Fix the typo in README.md") delegate_task(category="deep", load_skills=[], prompt="Investigate and fix the memory leak in the worker pool") ```
### 关键：模型解析优先级
除非已配置，否则类别**不会**使用其内置默认值。解析顺序：
1. **用户配置的模型**（在 `oh-my-opencode.json` 中）——最高优先级 2. **类别的内置默认值**（如果类别在配置中） 3. **系统默认模型**（来自 `opencode.json`）——回退选项
要使用最佳模型，请将类别添加到你的配置中。参见 [references/configuration.md](references/configuration.md)。
---
## 内置技能
| Skill | Purpose | Usage | |-------|---------|-------| | `playwright` | 通过 Playwright MCP 进行浏览器自动化（默认浏览器引擎） | `load_skills=["playwright"]` | | `agent-browser` | 带会话管理的 Vercel agent-browser CLI | 通过 `browser_automation_engine` 配置切换 | | `git-master` | Git 专家：原子提交、rebase/squash、历史搜索 | `load_skills=["git-master"]` | | `frontend-ui-ux` | 转行开发者的设计师，打造惊艳的 UI/UX | `load_skills=["frontend-ui-ux"]` |
技能通过 `delegate_task(load_skills=[...])` 注入到子智能体中。
---
## 斜杠命令
| Command | Description | |---------|-------------| | `/init-deep` | 初始化分层 AGENTS.md 知识库 | | `/start-work` | 使用 Atlas 编排器执行 Prometheus 计划 | | `/ralph-loop` | 启动自指开发循环直到完成 | | `/ulw-loop` | 启动 ultrawork 循环——持续直到完成 | | `/cancel-ralph` | 取消活动的 Ralph 循环 | | `/refactor` | 智能重构，结合 LSP、AST-grep、架构分析、TDD | | `/stop-continuation` | 停止所有延续机制（ralph 循环、todo 延续、boulder） |
---
## 进程管理
### 后台智能体
并行启动多个智能体进行探索和研究：
```javascript // Launch background agents (non-blocking) delegate_task(subagent_type="explore", run_in_background=true, prompt="Find auth patterns in codebase") delegate_task(subagent_type="librarian", run_in_background=true, prompt="Find JWT best practices")
// Collect results when needed background_output(task_id="bg_abc123")
// Cancel all background tasks before final answer background_cancel(all=true) ```
### 并发配置
```json { "background_task": { "defaultConcurrency": 5, "staleTimeoutMs": 180000, "providerConcurrency": { "anthropic": 3, "google": 10 }, "modelConcurrency": { "anthropic/claude-opus-4-5": 2 } } } ```
优先级：`modelConcurrency` > `providerConcurrency` > `defaultConcurrency`
### Tmux 集成
在单独的 tmux 窗格中运行后台智能体，以实现可视化多智能体执行：
```json { "tmux": { "enabled": true, "layout": "main-vertical", "main_pane_size": 60 } } ```
需要在 tmux 会话内的服务器模式下运行 OpenCode：
```bash tmux new -s dev opencode --port 4096 ```
布局选项：`main-vertical`（默认）、`main-horizontal`、`tiled`、`even-horizontal`、`even-vertical`
---
## 并行执行模式
### 模式 1: Explore + Librarian（研究阶段）
```javascript // Internal codebase search delegate_task(subagent_type="explore", run_in_background=true, prompt="Find how auth middleware is implemented") delegate_task(subagent_type="explore", run_in_background=true, prompt="Find error handling patterns in the API layer")
// External documentation search delegate_task(subagent_type="librarian", run_in_background=true, prompt="Find official JWT documentation and security recommendations")
// Continue working immediately — collect results when needed ```
### 模式 2: 基于类别的委托（实现阶段）
```javascript // Frontend work → visual-engineering category delegate_task(category="visual-engineering", load_skills=["frontend-ui-ux"], prompt="Build the settings page")
// Quick fix → quick category delegate_task(category="quick", load_skills=["git-master"], prompt="Create atomic commit for auth changes")
// Hard problem → ultrabrain category delegate_task(category="ultrabrain", load_skills=[], prompt="Design the caching invalidation strategy") ```
### 模式 3: 会话连续性
```javascript // First delegation returns a session_id result = delegate_task(category="quick", load_skills=["git-master"], prompt="Fix the type error") // session_id: "ses_abc123"
// Follow-up uses session_id to preserve full context delegate_task(session_id="ses_abc123", prompt="Also fix the related test file") ```
---
## CLI 参考
### 核心命令
```bash opencode # Start TUI opencode --port 4096 # Start TUI with server mode (for tmux integration) opencode -c # Continue last session opencode -s <session-id> # Continue specific session opencode --agent <agent-name> # Start with specific agent opencode -m provider/model # Start with specific model ```
### 非交互模式
```bash opencode run "Explain closures in JavaScript" opencode run --agent oracle "Review this architecture" opencode run -m openai/gpt-5.2 "Complex reasoning task" opencode run --format json "Query" # Raw JSON output ```
### 认证与提供商管理
```bash opencode auth login # Add/configure a provider opencode auth list # List authenticated providers opencode auth logout # Remove a provider opencode models # List all available models opencode models anthropic # List models for specific provider opencode models --refresh # Refresh models cache ```
### 会话管理
```bash opencode session list # List all sessions opencode session list -n 10 # Last 10 sessions opencode export <session-id> # Export session as JSON opencode import session.json # Import session opencode stats # Token usage and cost statistics opencode stats --days 7 # Stats for last 7 days ```
### 插件与 MCP 管理
```bash bunx oh-my-opencode install # Install/configure oh-my-opencode bunx oh-my-opencode doctor # Diagnose configuration issues opencode mcp list # List configured MCP servers opencode mcp add # Add an MCP server ```
### 服务器模式
```bash opencode serve --port 4096 # Headless server opencode web --port 4096 # Server with web UI opencode attach http://localhost:4096 # Attach TUI to running server ```
---
## 内置 MCP
Oh My OpenCode 开箱即用地包含这些 MCP 服务器：
| MCP | Tool | Purpose | |-----|------|---------| | **Exa** | `web_search_exa` | 网页搜索，提供干净的、适合 LLM 的内容 | | **Context7** | `resolve-library-id`, `query-docs` | 官方库/框架文档查询 | | **Grep.app** | `searchGitHub` | 从公共 GitHub 仓库搜索真实世界的代码示例 |
---
## 钩子 (Hooks)
默认情况下启用所有钩子。通过 `disabled_hooks` 配置禁用特定钩子：
| Hook | 用途 | |------|---------| | `todo-continuation-enforcer` | 强制代理在半途退出时继续执行 | | `context-window-monitor` | 监控和管理上下文窗口使用情况 | | `session-recovery` | 在崩溃后恢复会话 | | `session-notification` | 在会话事件时发送通知 | | `comment-checker` | 防止 AI 添加过多的代码注释 | | `grep-output-truncator` | 截断过大的 grep 输出 | | `tool-output-truncator` | 截断过大的工具输出 | | `directory-agents-injector` | 注入子目录中的 AGENTS.md（在 OpenCode 1.1.37+ 上自动禁用） | | `directory-readme-injector` | 注入 README.md 上下文 | | `empty-task-response-detector` | 检测并处理空的任务响应 | | `think-mode` | 扩展思考模式控制 | | `anthropic-context-window-limit-recovery` | 从 Anthropic 上下文限制中恢复 | | `rules-injector` | 注入项目规则 | | `background-notification` | 在后台任务完成时发送通知 | | `auto-update-checker` | 检查 oh-my-opencode 更新 | | `startup-toast` | 显示启动通知（auto-update-checker 的子功能） | | `keyword-detector` | 检测如 `ultrawork`/`ulw` 等关键字以触发模式 | | `agent-usage-reminder` | 提醒使用专用代理 | | `non-interactive-env` | 处理非交互式环境 | | `interactive-bash-session` | 管理交互式 bash/tmux 会话 | | `compaction-context-injector` | 在压缩期间注入上下文 | | `thinking-block-validator` | 验证思考块 | | `claude-code-hooks` | Claude Code 兼容性钩子 | | `ralph-loop` | Ralph Loop 继续执行机制 | | `preemptive-compaction` | 在上下文溢出前触发压缩 | | `auto-slash-command` | 自动触发斜杠命令 | | `sisyphus-junior-notepad` | Sisyphus-Junior 子代理的记事本 | | `edit-error-recovery` | 从编辑错误中恢复 | | `delegate-task-retry` | 重试失败的任务委托 | | `prometheus-md-only` | 强制 Prometheus 仅输出 Markdown | | `start-work` | 处理 /start-work 命令 | | `atlas` | Atlas 编排器钩子 |
---
## 最佳实践
### 推荐操作
- **使用 `ulw` 进行快速自主任务** —— 只需在提示词中包含该关键字 - **使用 Prometheus + `/start-work` 处理复杂项目** —— 基于访谈的规划能带来更好的结果 - **为您的提供商配置类别** —— 确保最佳模型选择，而不是回退到系统默认值 - **并行启动 explore/librarian 代理** —— 始终使用 `run_in_background=true` - **使用会话连续性** —— 传递 `session_id` 以便与同一子代理进行后续交互 - **让代理进行委托** —— Sisyphus 是编排器，而非独立实施者 - **运行 `bunx oh-my-opencode doctor`** 以诊断问题
### 禁止操作
- **不要在没有 `/start-work` 的情况下使用 Atlas** —— Atlas 需要一个 Prometheus 计划 - **不要为每个代理手动指定模型** —— 回退链会处理这个问题 - **不要禁用 `todo-continuation-enforcer`** —— 它是确保代理完成工作的关键 - **不要使用 Claude Haiku 作为 Sisyphus** —— 强烈建议使用 Opus 4.5 - **不要同步运行 explore/librarian** —— 始终将它们置于后台运行
### 何时使用此技能
- 安装或配置 oh-my-opencode - 理解代理角色和委托模式 - 排查模型解析或提供商问题 - 设置 tmux 集成以实现可视化的多代理执行 - 配置类别以优化成本 - 理解 ultrawork 与 Prometheus 工作流的选择
### 何时不使用此技能
- 与 oh-my-opencode 插件功能无关的常规 OpenCode 使用 - 提供商身份验证问题（直接使用 `opencode auth`） - OpenCode 核心配置（使用 OpenCode 文档 https://opencode.ai/docs/）
---
## 代理规则
1. **包名为 `oh-my-opencode`** —— 不是 `@anthropics/opencode` 或任何其他名称 2. **使用 `bunx`（官方推荐）** —— 不要使用 `npx` 来运行 oh-my-opencode CLI 命令 3. **代理调用使用 `--agent` 标志或 `delegate_task()`** —— 不要使用 `@agent` 前缀 4. **切勿更改模型设置或禁用功能**，除非用户明确要求 5. **Sisyphus 强烈建议使用 Opus 4.5** —— 使用其他模型会显著降低体验 6. **除非已配置，否则类别不使用内置默认值** —— 始终使用 `bunx oh-my-opencode doctor --verbose` 进行验证 7. **Prometheus 和 Atlas 始终搭配使用** —— 永远不要在没有 Prometheus 计划的情况下使用 Atlas 8. **后台代理应始终使用 `run_in_background=true`** —— 切勿在探索时阻塞 9. **会话 ID 应保留并重用** —— 可在后续交互中节省 70% 以上的 token 10. **使用 Ollama 时，设置 `stream: false`** —— 必须设置以避免 JSON 解析错误
---
## 完成时自动通知
后台任务完成后会通过 `background-notification` 钩子自动发送通知。无需轮询 —— 系统会推送完成事件。仅当需要读取结果时才使用 `background_output(task_id="...")`。
---
## 参考文档
- [配置参考](references/configuration.md) —— 包含所有代理、类别、提供商链、钩子和选项的完整配置 - [故障排除指南](references/troubleshooting.md) —— 常见问题和解决方案