最佳实践

最佳实践

本文档分享了使用 Oh My OpenCode 的最佳实践和高效模式，帮助你充分发挥多代理协作的力量。

ultrawork 魔法关键字

什么是 ultrawork？

ultrawork（简称 ulw）是 Oh My OpenCode 的魔法关键字。在任务描述中添加该词会自动启用所有高级功能。

启用的功能

使用 ultrawork 时，系统会自动启用：

• ✅ 所有配置的专家代理
• ✅ 后台任务并行执行
• ✅ 完整的 LSP 工具集成
• ✅ 智能上下文管理
• ✅ AST-Grep 代码搜索
• ✅ 自动任务拆解与协调

使用示例

# 全称形式
opencode "ultrawork: 重构用户认证系统，添加 OAuth2 支持"

# 简称形式
opencode "ulw: 为整个项目添加 TypeScript 类型"

# 与代理结合
opencode "ultrawork: @oracle 设计微服务架构"

何时使用

建议使用 ultrawork 的场景：

• 🏗️ 大型重构任务
• 🌐 全栈功能开发
• 📚 复杂问题分析
• 🎯 多步骤实现任务

不需要 ultrawork 的场景：

• 🔍 简单查询
• ✏️ 小范围修改
• 📖 单文件编辑
• ❓ 问答类请求

提示

对于复杂任务，请务必优先考虑 ultrawork。它会智能地激活所需功能，而不会浪费资源。

多代理协作模式

模式 1：顺序协作

适用场景：具有清晰顺序依赖的任务

# 第 1 步：架构设计
opencode "@oracle 为用户权限系统设计架构"

# 第 2 步：文档调研
opencode "@librarian 研究 RBAC 和 ABAC 的最佳实践"

# 第 3 步：实现
opencode "@backend-engineer 根据 @oracle 的设计实现权限系统"

优势：

• 职责分工明确
• 每一步结果可人工评审
• 易于追踪问题

模式 2：并行协作

适用场景：子任务相对独立，可以同时进行

# 使用 ultrawork 自动并行化
opencode "ulw: 开发用户仪表板功能，包括前端 UI 和后端 API"

# Sisyphus 自动分配：
# - @frontend-engineer: 实现 UI 组件
# - @backend-engineer: 实现 API 接口
# - @librarian: 研究最佳实践

优势：

• 极大提升工作效率
• 自动协调与整合
• 适合时间紧迫的任务

模式 3：分层协作

适用场景：需要不同层级的决策和实现

# 第 1 层：战略决策
opencode "@oracle 评估是否从 REST 迁移到 GraphQL"

# 第 2 层：技术调研
opencode "@librarian 研究 GraphQL 生态和工具链"

# 第 3 层：原型开发
opencode "@backend-engineer 实现一个 GraphQL 原型"

# 第 4 层：验证测试
opencode "@explore 分析原型的性能和可维护性"

选择合适的代理

任务类型	首选代理	备选代理	备注
架构决策	@oracle	-	最强系统思维
文档编写	@document-writer	@librarian	Document Writer 专注技术写作
文档调研	@librarian	-	擅长信息检索和整理
UI/UX 设计	@frontend-ui-ux-engineer	@frontend-engineer	关注用户体验
前端开发	@frontend-engineer	@frontend-ui-ux-engineer	前端技术专家
API 开发	@backend-engineer	-	后端专家
Bug 调试	@explore	@oracle	Explore 擅长代码分析
性能优化	@oracle	@explore	Oracle 提供策略，Explore 分析细节
视觉分析	@multimodal-looker	-	分析设计稿和 UI 截图

上下文管理最佳实践

AGENTS.md 分层系统

合理利用分层上下文规则：

全局规则（项目根目录）

<!-- project/AGENTS.md -->
# 全局开发规范

## 通用规则
- 使用 TypeScript 严格模式
- 所有函数必须有类型注解
- 使用 ESLint 和 Prettier

## 提交规范
- 遵循 Conventional Commits
- 每次提交必须通过所有测试

模块规则（src 目录）

<!-- project/src/AGENTS.md -->
# 源代码规范

## 代码组织
- 按功能模块组织，而非按类型
- 每个模块包含 index.ts 导出

## 测试要求
- 核心业务逻辑必须有单元测试
- 覆盖率不低于 80%

组件规则（components 目录）

<!-- project/src/components/AGENTS.md -->
# React 组件规范

## when: file.ext == "*.tsx"
- 使用函数组件和 Hooks
- Props 必须定义 TypeScript 接口
- 使用 CSS Modules 进行样式管理

## when: agent == "@frontend-engineer"
- 遵循公司的 UI 设计系统
- 使用 Storybook 文档化组件

使用条件规则

按文件类型激活

## when: file.ext == "*.test.ts"
使用 Jest 和 React Testing Library
遵循 AAA 模式 (Arrange, Act, Assert)

## when: file.ext == "*.spec.ts"
使用 Cypress 进行 E2E 测试

按代理类型激活

## when: agent == "@oracle"
提供详细的技术决策理由
考虑长期可维护性

## when: agent == "@frontend-engineer"
优先考虑用户体验
遵循无障碍权限 (a11y) 标准

按任务阶段激活

## when: phase == "design"
输出架构图和技术选型文档

## when: phase == "implementation"
编写可测试的代码
添加必要的注释

后台任务使用技巧

合理设置并发数

根据订阅计划进行调整：

Claude Max20 配置：

{
  "sisyphus": {
    "max_concurrent_tasks": 3
  }
}

ChatGPT Plus / Gemini 配置：

{
  "sisyphus": {
    "max_concurrent_tasks": 2
  }
}

免费或受限计划：

{
  "sisyphus": {
    "max_concurrent_tasks": 1
  }
}

后台任务使用场景

适合后台执行的：

• 📖 文档调研
• 🔍 代码库分析
• 📊 性能基准测试
• 🧪 测试执行
• 📝 辅助文档生成

不适合后台执行的：

• ✏️ 直接修改代码
• 🚀 关键路径任务
• 👤 需要用户确认的操作

监控后台任务

# 查看当前运行的后台任务状态
opencode "显示所有后台任务状态"

# 取消特定后台任务
opencode "取消任务 ID: abc123"

# 等待所有后台任务完成
opencode "等所有后台任务完成后继续"

代码质量控制策略

自动注释检查

配置代理自动添加必要的注释：

{
  "code_quality": {
    "enforce_comments": true,
    "comment_rules": {
      "functions": "复杂度 > 10 需要注释",
      "classes": "公开类需要注释",
      "exports": "导出的函数/类需要注释"
    }
  }
}

代码评审集成

让代理协助评审代码：

# 评审特定文件
opencode "@oracle 评审 src/auth/login.ts 的代码质量"

# 评审整个 PR
opencode "ulw: 评审当前分支的所有更改"

# 检查安全问题
opencode "@explore 检查代码中的安全漏洞"

任务续传执行器

使用 Todo 系统追踪长期任务：

# 创建 Todo
opencode "创建待办：重构用户认证模块"

# 查看 Todo
opencode "列出所有未完成的待办"

# 继续执行 Todo
opencode "继续执行待办：重构用户认证模块"

提示

任务续传执行器会保留上下文，即使跨会话也能继续之前的工作。

性能优化建议

优化模型选择

针对不同任务使用不同模型：

{
  "agents": {
    "oracle": {
      "model": "claude-sonnet-4",  // 复杂决策使用最强模型
      "temperature": 0.7
    },
    "explore": {
      "model": "claude-sonnet-3.5",  // 代码分析使用中档模型
      "temperature": 0.3
    },
    "librarian": {
      "model": "gpt-4-turbo",  // 文档调研可以使用其他模型
      "temperature": 0.5
    }
  }
}

控制 Token 使用

{
  "token_management": {
    "max_context_tokens": 4096,
    "summarize_long_context": true,
    "cache_common_queries": true
  }
}

优化任务描述

❌ 模糊描述：

opencode "改进代码"

✅ 清晰描述：

opencode "@explore 分析 UserService.ts 中的性能瓶颈，然后由 @backend-engineer 优化数据库查询"

使用缓存

{
  "caching": {
    "enabled": true,
    "cache_lsp_results": true,
    "cache_duration": 3600,  // 1 小时
    "cache_directory": ".opencode/cache"
  }
}

常见误区与对策

误区 1：过度使用 ultrawork

问题：对于简单任务也使用 ultrawork，浪费资源

解决：

# ❌ 过度使用
opencode "ulw: 查看 package.json 内容"

# ✅ 简单任务直接执行
opencode "查看 package.json"

误区 2：代理选择不当

问题：让不擅长的代理执行任务

解决：

# ❌ 错误选择
opencode "@librarian 实现一个 React 组件"

# ✅ 正确选择
opencode "@frontend-engineer 实现一个 React 组件"

误区 3：忽视上下文管理

问题：没有为项目配置 AGENTS.md

解决：创建分层的 AGENTS.md 文件提供必要上下文

误区 4：并发任务过多

问题：将 max_concurrent_tasks 设置过高导致 API 频率限制

解决：根据实际订阅计划调整并发数

实用技巧总结

快速启动模板

# 新功能开发
opencode "ulw: @oracle 设计 [功能名] 的架构，@librarian 调研相关技术，@frontend-engineer 和 @backend-engineer 并行实现"

# Bug 修复
opencode "@explore 分析 [Bug 描述] 的根本原因，然后进行修复"

# 代码评审
opencode "@oracle 评审当前 PR 的架构合理性，@explore 检查潜在问题"

# 文档编写
opencode "@librarian 研究项目结构，然后编写完整的 README.md"

效率提升自检表

• ✅ 为项目配置了 AGENTS.md 分层规则
• ✅ 根据订阅计划调整了并发数
• ✅ 对复杂任务使用了 ultrawork
• ✅ 为任务选择了合适的代理
• ✅ 利用后台任务提升效率
• ✅ 使用 Todo 系统追踪长期任务
• ✅ 定期清理缓存和会话

后续步骤

掌握最佳实践后，我们建议：

1. ⚙️ 探索 高级配置 进行深度定制
2. 💡 参考 使用案例 获取更多灵感
3. 🔧 根据团队需求定制你的工作流程