使用案例

本文档通过 5 个实际场景展示了如何在真实项目中高效使用 Oh My OpenCode。

场景 1：大规模项目重构

场景描述

一个拥有 5 年历史、超过 50 万行代码的电子商务平台需要从 JavaScript 迁移到 TypeScript，同时重构陈旧的架构模式。

挑战

代码库庞大，无法一次性完成迁移
需要保持业务连续性
多个模块相互依赖，影响范围难以评估

解决方案

利用 Oh My OpenCode 的多代理协作和 LSP 工具：

# 第 1 步：架构分析
opencode "@oracle 分析当前项目架构，制定 TypeScript 迁移计划，划分迁移阶段"

# 第 2 步：依赖分析（后台任务）
opencode "ulw: @explore 分析所有模块依赖，生成依赖图，识别关键路径模块"

# 第 3 步：分模块迁移
opencode "ulw: @backend-engineer 将 user-service 模块迁移到 TypeScript，使用 LSP 工具确保类型安全"

# 第 4 步：验证与测试
opencode "@explore 使用 LSP 工具检查类型错误，运行测试套件，生成迁移报告"

配置

{
  "subscription": "claude-max20",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 3
  },
  "agents": {
    "oracle": {
      "enabled": true,
      "prompt_append": "考虑业务连续性，提供增量迁移计划"
    },
    "explore": {
      "enabled": true,
      "tools": {
        "lsp": true,
        "ast_grep": true
      }
    },
    "backend-engineer": {
      "enabled": true,
      "prompt_append": "保持 API 向后兼容，添加完整的类型注解"
    }
  },
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "javascript"]
  },
  "background_task": {
    "enabled": true,
    "defaultConcurrency": 3
  }
}

实施步骤

架构评估 (1 天)

opencode "@oracle 评估当前架构，识别技术债，确立重构优先级"

依赖分析 (并行，2 天)

opencode "ulw: @explore 分析模块依赖，@librarian 调研 TypeScript 迁移最佳实践"

模块迁移 (分批次，4 周)

# 分别迁移每个模块
opencode "ulw: @backend-engineer 迁移 auth 模块，@explore 验证类型覆盖率"

集成测试 (持续进行)

opencode "@explore 运行完整测试套件，报告迁移进度"

结果

✅ 在 4 周内完成了 50 万行代码的迁移
✅ 100% 的 TypeScript 类型覆盖率
✅ 业务零中断
✅ 发现并修复了 47 个潜在 Bug

场景 2：多框架全栈应用开发

场景描述

开发一个拥有 React 前端和 Node.js + Express 后端的 SaaS 产品，要求在 3 周内完成 MVP。

挑战

前后端需要同步开发
API 接口需要频繁调整
时间紧迫，需要高效协作

解决方案

使用多代理并行开发：

# 启动 ultrawork 模式
opencode "ulw: 开发用户认证系统，包括前端登录界面和后端 API，支持 JWT 和 OAuth2"

# Sisyphus 自动分配：
# - @oracle: 设计认证架构和数据模型
# - @frontend-ui-ux-engineer: 实现登录/注册界面和用户体验
# - Sisyphus: 处理后端逻辑和 API 接口实现
# - @librarian: 研究安全最佳实践

配置

{
  "subscription": "claude-max20",
  "sisyphus": {
    "enabled": true,
    "delegation_strategy": "parallel",
    "max_concurrent_tasks": 3
  },
  "agents": {
    "oracle": {
      "enabled": true,
      "temperature": 0.7
    },
    "frontend-engineer": {
      "enabled": true,
      "prompt_append": "请使用 React 18 + TypeScript + Tailwind CSS + React Query"
    },
    "backend-engineer": {
      "enabled": true,
      "prompt_append": "请使用 Node.js + Express + PostgreSQL + Prisma ORM"
    },
    "librarian": {
      "enabled": true
    }
  },
  "context_injection": {
    "enabled": true,
    "files": ["AGENTS.md", ".opencode/TECH_STACK.md"]
  }
}

项目结构与上下文

<!-- project/AGENTS.md -->
# 项目规范

## 技术栈
- 前端：React 18 + TypeScript + Vite + Tailwind
- 后端：Node.js 18 + Express + PostgreSQL + Prisma
- 认证：JWT + OAuth2 (Google, GitHub)

## API 规范
- RESTful API 设计
- 统一的错误处理
- 请求/响应日志记录

## 代码规范
- ESLint + Prettier
- Husky + lint-staged
- 提交必须通过 CI 检查

工作流

# 第 1 天：架构设计
opencode "@oracle 设计用户认证系统架构，包括数据模型、API 接口和前端路由"

# 第 2-3 天：并行开发
opencode "ulw: @frontend-ui-ux-engineer 实现登录/注册界面，Sisyphus 实现认证 API"

# 第 4 天：联调与优化
opencode "@explore 分析前后端联调问题，调整 API 接口"

# 第 5 天：测试与加固
opencode "ulw: @frontend-ui-ux-engineer 添加 E2E 测试，添加后端单元测试"

结果

✅ 在 5 天内完成了认证系统
✅ 前后端完全解耦
✅ 测试覆盖率达到 85%
✅ 支持多个 OAuth2 提供商

场景 3：开源项目文档建设

场景描述

一个功能丰富但缺乏文档的热门开源库需要建设完整的文档网站。

挑战

代码库复杂，需要深度理解
文档必须准确、全面
示例代码必须可运行

解决方案

利用 @librarian 进行调研，@document-writer 进行编写：

# 第 1 步：项目分析
opencode "@explore 分析项目结构，列出所有公开 API 和核心功能"

# 第 2 步：文档调研
opencode "@librarian 深入研究项目代码，理解每个 API 的用途和参数，阅读现有注释"

# 第 3 步：编写文档
opencode "ulw: @document-writer 为项目编写完整的文档，包括：
- README.md (概览、快速开始、安装)
- API.md (完整的 API 参考)
- GUIDE.md (使用指南和最佳实践)
- EXAMPLES.md (常见场景示例)
使用 LSP 工具验证 API 信息的准确性"

# 第 4 步：示例代码
opencode "@backend-engineer 为每个 API 编写可运行的示例代码，添加详细注释"

配置

{
  "subscription": "chatgpt-plus",
  "agents": {
    "librarian": {
      "enabled": true,
      "model": "gpt-4-turbo",
      "temperature": 0.5,
      "prompt_append": "仔细阅读代码和注释，确保文档准确无误，提供清晰的解释和示例"
    },
    "explore": {
      "enabled": true,
      "tools": {
        "lsp": true,
        "ast_grep": true
      }
    },
    "backend-engineer": {
      "enabled": true,
      "prompt_append": "示例代码必须可运行，包含错误处理，并添加详细注释"
    }
  },
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "javascript"]
  }
}

文档结构

# 生成文档大纲
opencode "@librarian 分析项目，生成文档大纲，包含需要覆盖的所有主题"

# 文档大纲示例：
# docs/
# ├── README.md              # 项目概览
# ├── getting-started.md     # 快速开始
# ├── installation.md        # 安装指南
# ├── api/
# │   ├── configuration.md   # 配置 API
# │   ├── core.md           # 核心 API
# │   └── utilities.md      # 工具函数
# ├── guides/
# │   ├── basic-usage.md    # 基础用法
# │   ├── advanced.md       # 高级技巧
# │   └── best-practices.md # 最佳实践
# └── examples/
#     ├── quickstart.md     # 快速示例
#     └── real-world.md     # 真实案例

结果

✅ 在 2 天内完成了完整的文档网站
✅ 所有公开 API 均有文档记录
✅ 提供了 30 多个可运行的示例
✅ GitHub Star 增长了 300%

场景 4：复杂 Bug 调试

场景描述

生产环境出现偶发性的性能问题，错误日志不清晰，难以复现。

挑战

问题难以复现
代码库庞大，定位困难
影响生产环境，需要快速解决

解决方案

使用 Oracle + Explore 进行深度分析：

# 第 1 步：收集信息
opencode "@explore 分析错误日志和监控数据，识别异常模式"

# 第 2 步：代码追踪
opencode "ulw: @explore 使用 LSP 工具分析可疑模块的调用链，@oracle 评估可能的根因"

# 第 3 步：假设验证
opencode "@oracle 根据分析结果提出 3 个假设，@explore 为每个假设寻找证据"

# 第 4 步：修复与验证
opencode "@backend-engineer 实现修复方案，添加监控和日志，@explore 验证修复效果"

配置

{
  "subscription": "claude-max20",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2
  },
  "agents": {
    "oracle": {
      "enabled": true,
      "temperature": 0.7,
      "prompt_append": "系统地分析问题，考虑并发、缓存、网络等多种因素"
    },
    "explore": {
      "enabled": true,
      "temperature": 0.3,
      "tools": {
        "lsp": true,
        "ast_grep": true
      },
      "prompt_append": "仔细追踪代码执行路径，关注边缘情况和异常处理"
    },
    "backend-engineer": {
      "enabled": true,
      "prompt_append": "修复必须向后兼容，添加防御性编程措施"
    }
  }
}

调试过程

# 1. 日志分析
opencode "@explore 分析过去 7 天的错误日志，识别最高频的错误和时间规律"

# 2. 性能分析
opencode "@explore 使用 LSP 工具分析性能瓶颈模块，找到所有数据库查询和 API 调用"

# 3. 代码审查
opencode "@oracle 审查可疑代码，识别潜在的并发问题、内存泄漏或资源竞争"

# 4. 修复实现
opencode "@backend-engineer 实现修复：
- 添加数据库连接池管理
- 优化查询，添加索引
- 添加超时和重试机制
- 完善错误处理和日志记录"

# 5. 验证
opencode "@explore 在测试环境复现问题，验证修复效果，进行压力测试"

结果

✅ 在 4 小时内准确定位根因
✅ 修复后性能提升了 60%
✅ 错误率降低了 95%
✅ 增加了完善的监控和报警

场景 5：UI/UX 快速原型开发

场景描述

产品经理提出了一个新的功能想法，需要快速实现一个可交互的原型进行用户测试。

挑战

时间紧迫（2 天）
需要接近真实的交互效果
可能需要后续反复调整

解决方案

利用前端专业代理进行快速迭代：

# 快速原型开发
opencode "@frontend-engineer 实现用户仪表板原型，包括：
- 数据可视化图表 (使用 Recharts)
- 响应式布局 (使用 Tailwind CSS)
- Mock 数据和交互
- 平滑的动画效果
请使用 React + TypeScript + Vite"

配置

{
  "subscription": "chatgpt-plus",
  "agents": {
    "frontend-engineer": {
      "enabled": true,
      "model": "gpt-4",
      "temperature": 0.6,
      "prompt_append": "快速原型要求：\n- 优先保证核心交互流程\n- 使用现成的 UI 组件库 (shadcn/ui, Headless UI)\n- Mock 数据和 API 调用\n- 关注视觉效果和用户体验\n- 代码编写需简洁，方便调整"
    }
  }
}

原型开发过程

# 第 1 步：布局与导航
opencode "@frontend-engineer 实现仪表板布局：侧边栏导航、顶栏、主内容区"

# 第 2 步：核心组件
opencode "ulw: @frontend-engineer 实现核心组件：
- 数据卡片 (KPI 指标)
- 图表组件 (折线图、饼图)
- 数据表格 (支持排序、筛选)
- 操作按钮和表单"

# 第 3 步：交互与动画
opencode "@frontend-engineer 添加交互效果：
- 页面切换动画
- 数据加载状态
- 悬停和点击反馈
- 响应式适配"

# 第 4 步：数据 Mock
opencode "@frontend-engineer 创建 Mock 数据和接口，使用 MSW (Mock Service Worker)"

项目配置

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000,
    open: true
  }
})

// package.json (依赖项)
{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "recharts": "^2.10.0",
    "tailwindcss": "^3.4.0",
    "@headlessui/react": "^1.7.0",
    "framer-motion": "^10.16.0"
  }
}

结果

✅ 在 1.5 天内完成了可交互原型
✅ 包含 15+ 个精美的组件
✅ 完整的数据 Mock 和接口
✅ 用户测试反馈极佳

总结

场景对比

场景	主要代理	时间	核心功能
大型重构	Oracle + Explore	4 周	LSP + 并行任务
全栈开发	前端 + 后端	5 天	多代理协作
文档建设	Librarian + Explore	2 天	LSP + 代码分析
Bug 调试	Oracle + Explore	4 小时	LSP + 深度分析
UI 原型	前端工程师	1.5 天	快速迭代

关键经验

选择合适的代理：根据任务类型选择对应的专家代理
发挥 ultrawork 威力：对于复杂任务，启用所有功能
并行执行：将独立任务并行处理，提升效率
利用 LSP 工具：它是代码分析和重构的强大武器
上下文管理：通过 AGENTS.md 提供项目特定的规则

通用配置建议

{
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 3  // 根据订阅调整，这是 Claude Max20 的建议值
  },
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "python", "go"]  // 项目使用的语言
  },
  "background_task": {
    "defaultConcurrency": 5,
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 5
    }
  },
  "context_injection": {
    "enabled": true,
    "files": ["AGENTS.md", ".opencode/CONTEXT.md"]
  }
}