核心功能

Oh My OpenCode 提供了一系列强大的企业级功能，将 OpenCode 提升到了专业水平。本文档详细介绍了每个核心功能的工作原理及其使用方法。

Sisyphus 代理编排系统

什么是 Sisyphus？

Sisyphus 是 Oh My OpenCode 的核心编排系统，充当“主代理”的角色。它的名字源于希腊神话中的西西弗斯，他不断地将巨石推向山顶，象征着持久的任务执行和管理。

使用的模型：Sisyphus 通常使用最强大的模型，如 Claude Opus 4.5 High 或 Claude Sonnet 4，以确保卓越的任务拆解和协调能力。

为什么我们需要编排器？

在复杂的开发任务中，单个 AI 代理往往难以处理所有方面。编排器的价值在于：

任务拆解：将大型任务分解为可管理的子任务
专业匹配：为每个子任务选择最合适的专家代理
资源协调：管理多个代理的并行执行和资源分配
结果整合：将各个代理的工作汇总为完整的解决方案
上下文管理：确保不同代理之间的上下文共享和一致性

工作原理

用户任务
    ↓
Sisyphus 分析任务需求
    ↓
自动选择合适的专家代理
    ↓
协调多个代理并行工作
    ↓
整合结果并返回

核心能力

1. 智能任务拆解

Sisyphus 可以将复杂任务分解为多个子任务：

# 用户输入
opencode "重构整个认证系统，添加 OAuth2 和 JWT 支持"

# Sisyphus 内部拆解
# - 子任务 1: @oracle 设计新的认证架构
# - 子任务 2: @librarian 研究 OAuth2 和 JWT 最佳实践
# - 子任务 3: @backend-engineer 实现服务端逻辑
# - 子任务 4: @frontend-ui-ux-engineer 更新登录界面

2. 自动代理选择

根据任务类型自动选择最合适的代理：

任务类型	选择的代理	原因
架构设计	@oracle	系统思维和技术决策
文档调研	@librarian	信息检索和整理
UI 开发	@frontend-ui-ux-engineer	前端技术专长
API 开发	@backend-engineer	后端技术专长
代码分析	@explore	深度代码库分析

3. 并行任务协调

多个代理可以同时工作，由 Sisyphus 进行协调：

{
  "main_task": "开发用户仪表板",
  "parallel_tasks": [
    {
      "agent": "@oracle",
      "task": "设计组件架构",
      "status": "进行中"
    },
    {
      "agent": "@librarian",
      "task": "研究 UI 库文档",
      "status": "通过"
    },
    {
      "agent": "@frontend-engineer",
      "task": "实现基础组件",
      "status": "进行中"
    }
  ]
}

配置选项

{
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 3,        // 最大并发任务数
    "task_timeout": 300,               // 任务超时时间（秒）
    "auto_delegate": true,             // 自动下发任务
    "delegation_strategy": "optimal"   // 下发策略：optimal (最优), balanced (平衡), sequential (顺序)
  }
}

专业代理团队

@oracle - 架构师

专长：系统架构设计、技术决策、模式选择

使用场景：

设计新的系统架构
选择技术栈
重大重构决策
性能优化方案

示例用法：

# 直接调用
opencode "@oracle 分析当前微服务架构中的瓶颈"

# 结合 ultrawork
opencode "ulw: @oracle 设计一个高可用的分布式缓存系统"

配置：

{
  "agents": {
    "oracle": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.7,
      "max_tokens": 4096,
      "prompt_append": "请提供详细的技术决策理由和权衡分析"
    }
  }
}

@librarian - 文档专家

使用的模型：GPT-4 Turbo, Claude Sonnet 3.5 或类似模型

专长：文档调研、知识整理、信息检索

使用场景：

研究框架/库的文档
整理技术资料
编写技术文档
学习新技术

示例用法：

# 研究文档
opencode "@librarian 研究 React Server Components 的最佳实践"

# 编写文档
opencode "@librarian 为当前项目编写 API 文档"

@frontend-ui-ux-engineer - 前端 UI/UX 工程师

使用的模型：Claude Sonnet 4, GPT-4 或类似模型

专长：前端开发、UI/UX 设计、用户体验优化

使用场景：

设计并实现用户界面
优化用户体验
响应式设计
无障碍改进

示例用法：

# UI/UX 开发
opencode "@frontend-ui-ux-engineer 设计并实现一个现代化的登录页面"

# 用户体验优化
opencode "@frontend-ui-ux-engineer 优化表单交互和验证反馈"

@frontend-engineer - 前端工程师

使用的模型：Claude Sonnet 4, GPT-4 或类似模型

专长：React/Vue/Angular 开发、UI/UX 实现

使用场景：

前端组件开发
UI 实现
样式调整
前端性能优化

示例用法：

# UI 开发
opencode "@frontend-engineer 实现一个响应式的用户卡片组件"

# 性能优化
opencode "@frontend-engineer 优化首页加载性能"

@backend-engineer - 后端工程师

使用的模型：Claude Sonnet 4, GPT-4 或类似模型

专长：Node.js/Python/Go 开发、API 设计、数据库

使用场景：

API 接口开发
数据库设计
业务逻辑实现
后端性能优化

示例用法：

# API 开发
opencode "@backend-engineer 实现支持 JWT 的用户认证 API"

# 数据库优化
opencode "@backend-engineer 优化订单查询的数据库索引"

@explore - 探索者

使用的模型：Claude Sonnet 3.5, GPT-4 或类似模型

专长：代码库分析、问题追踪、依赖关系

使用场景：

Bug 调试
代码库探索
依赖分析
影响范围评估

示例用法：

# Bug 调试
opencode "@explore 查找导致内存泄漏的代码位置"

# 依赖分析
opencode "@explore 分析这个函数是从哪里被调用的"

@document-writer - 技术写作专家

使用的模型：GPT-4, Claude Sonnet 3.5 或类似模型

专长：技术文档编写、API 文档、教程创建

使用场景：

编写技术文档
创建 API 参考
编写教程和指南
维护项目 README

示例用法：

# 文档编写
opencode "@document-writer 为新功能编写完整的用法文档"

# API 文档
opencode "@document-writer 生成完整的 RESTful API 文档"

@multimodal-looker - 视觉内容分析专家

使用的模型：Claude Sonnet 4 (Vision), GPT-4 Vision 或类似的多模态模型

专长：视觉内容分析、图像理解、设计评审

使用场景：

分析设计草图
理解 UI 截图
评审视觉设计
从图像中提取信息

示例用法：

# 设计分析
opencode "@multimodal-looker 分析此设计草图并提供实现建议"

# UI 评审
opencode "@multimodal-looker 评审当前页面的视觉设计和布局"

LSP 工具集成

什么是 LSP？

语言服务器协议 (LSP) 是微软开发的一项协议，为编辑器提供语言智能功能。Oh My OpenCode 集成了 LSP 供 AI 代理使用，使它们具备与 IDE 相同的代码理解能力。

可用的 LSP 功能

lsp_hover - 查看定义

查看符号的类型定义和文档：

// AI 可以使用 lsp_hover 工具
// 查看 UserService 的类型信息
const service = new UserService();

lsp_goto_definition - 跳转到定义

跳转到符号的定义位置：

# AI 可以使用 lsp_goto_definition 进行自动定位
"查找 authenticateUser 函数的实现"

lsp_rename - 安全重命名

安全的跨文件符号重命名：

opencode "使用 lsp_rename 工具将 getUserData 重命名为 fetchUserProfile"

lsp_find_references - 查找引用

查找符号的所有引用位置：

opencode "使用 lsp_find_references 查找所有使用已废弃 API 的位置"

lsp_code_actions - 代码操作

执行代码重构和快速修复：

opencode "使用 lsp_code_actions 自动修复类型错误"

支持的语言

✅ TypeScript/JavaScript
✅ Python
✅ Go
✅ Rust
✅ Java
✅ C/C++

配置 LSP

{
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "python", "go"],
    "servers": {
      "typescript": {
        "command": "typescript-language-server",
        "args": ["--stdio"]
      },
      "python": {
        "command": "pylsp",
        "args": []
      }
    }
  }
}

AST-Grep 代码搜索

什么是 AST-Grep？

AST-Grep 是一种基于抽象语法树 (AST) 的代码搜索工具，比简单的文本搜索更精确、更强大。

核心能力

1. ast_grep_search - 结构化搜索

# 查找所有使用 useState 的组件
opencode "使用 ast_grep_search 查找所有使用 useState 的 React 组件"

# 查找特定代码模式
opencode "使用 ast_grep_search 查找所有没有使用 try-catch 的异步函数"

2. ast_grep_replace - 代码重构

# 批量重构
opencode "使用 ast_grep_replace 将所有 var 声明改为 const"

# 模式替换
opencode "使用 ast_grep_replace 将所有类组件转换为函数组件"

示例

# .ast-grep.yml 配置
rule:
  pattern: console.log($$$ARGS)
fix: logger.debug($$$ARGS)
language: typescript

后台任务并行执行

工作机制

在主任务执行的同时，后台代理可以并行处理其他工作：

主任务：实现用户登录功能
    ↓ (进行中)
后台任务 1: @librarian 研究安全最佳实践
后台任务 2: @explore 分析现有认证代码
后台任务 3: @oracle 设计新的会话管理
    ↓ (并行处理)
整合所有结果

优势

⚡ 效率提升：工作效率提升 3 倍以上
🧠 智能协作：任务自动共享上下文
🎯 自动平衡：根据资源动态调整任务分配

配置

{
  "background_task": {
    "enabled": true,
    "defaultConcurrency": 3,
    "priority": "balanced",  // high (高), balanced (平衡), low (低)
    "auto_merge_results": true
  }
}

Claude Code 兼容层

无缝迁移

Oh My OpenCode 提供完整的 Claude Code 兼容性，现有配置无需修改即可工作：

Claude Code 配置示例：

// Claude Code 配置
{
  "custom_instructions": "使用 TypeScript 严格模式",
  "context_files": [".claud/CONTEXT.md"]
}

自动转换为 Oh My OpenCode 格式：

{
  "agents": {
    "default": {
      "prompt_append": "使用 TypeScript 严格模式"
    }
  },
  "context_injection": {
    "files": [".claud/CONTEXT.md"]
  }
}

支持的功能

✅ custom_instructions
✅ context_files
✅ project_rules
✅ custom_tools
✅ hooks

会话管理工具

功能

会话持久化：保存并恢复工作会话
上下文累积：跨会话保持上下文记忆
任务关联：将相关任务关联起来

用法

# 保存会话
opencode "将当前会话保存为 refactor-auth"

# 恢复会话
opencode "恢复 session refactor-auth 并继续"

# 列出会话
opencode "列出所有已保存的会话"

智能上下文注入

AGENTS.md 分层系统

支持项目级和目录级的上下文规则：

project/
├── AGENTS.md                    # 全局规则
├── src/
│   ├── AGENTS.md               # src 目录规则
│   └── components/
│       └── AGENTS.md           # components 目录规则

条件规则激活

根据条件自动激活规则：

<!-- AGENTS.md -->
# 条件规则

## when: file.ext == "*.test.ts"
使用 Jest 和 React Testing Library

## when: agent == "@frontend-engineer"
遵循公司的 UI 设计系统

后续步骤

了解核心功能后，我们建议：

📖 查看 最佳实践 学习高效使用模式
⚙️ 探索 高级配置 进行深度定制
💡 参考 使用案例 获取灵感