先说结论如果你所在的团队已经用上或正准备用 OpenCode 这类 AI 编程终端那「Oh My OpenCode」就是给这些终端注入团队协作能力的一套编排框架。它解决的不是“怎么让 AI 写一段代码”而是“怎么让多个各司其职的 AI Agent 像一支小队一样围绕同一个任务协同工作”。这篇指南我会从设计思路、安装配置、角色定义、协作流程到问题排查完整过一遍目标是让你看完之后能自己搭出一个最小可用的 AgentTeam。我自己在接手一个已有三年历史的遗留系统时被跨模块改造任务反复折腾过。单个 Agent 在独立对话里能写得挺好但一放进完整的、包含设计约束和历史包袱的真实项目里它经常改一个地方、漏三个地方。后来我把任务拆成架构、编码、评审三个角色才真正体会到“团队协作”对于 AI 编码这件事有多重要。Oh My OpenCode 的设计思路正好和我这套实践对上了所以这篇实战指南我会结合这套思路来写。1. 项目全貌与 AgentTeam 设计思路1.1 从一个让所有开发者皱眉的痛点说起用过 AI 编程助手的人应该都有这种体验在 IDE 里新建一个 Demo、写个算法题、生成一段爬虫脚本AI 的表现堪称惊艳。但一旦把同样的工具扔进一个真实的、多模块、有历史包袱的工程里问题就来了。首先是上下文失焦。一个会话里既能聊需求、又能看代码、还要让它跑测试聊到第十轮之后AI 已经开始“选择性遗忘”早期约束了。其次是职责混乱。同一个 Agent 既当架构师又当实现者还兼职 Code Reviewer你会看到一个非常拧巴的现象它在设计接口时畏手畏脚在实现时又过度设计。单独看每一步好像都对连起来看就像一个没人负责的产品。我试过用纯 Prompt 去约束这个过程也试过把大任务拆成多个独立的 OpenCode 会话手工搬运上下文。效果有但手工成本极高你需要自己维护“这个 Agent 做到了哪一步、下一个 Agent 需要知道什么”的状态同步一旦任务超过五六个步骤这个同步工作本身就会成为新的瓶颈。1.2 AgentTeam 的三种典型角色在我反复试验后一个稳定能出活的 AgentTeam最少需要三类角色而不是越多越好。第一类是架构 Agent它的职责是理解需求、阅读代码结构、产出技术方案。它不需要写很多代码但需要具备很强的代码库全局理解能力能把一个模糊需求翻译成具体的模块改动清单。第二类是开发 Agent它的职责是按照方案实现功能、写测试、处理编译错误。它需要精细化操作文件的能力但它不应该被允许做需求取舍。第三类是评审 Agent它的职责是审查改动是否满足需求、是否引入回归风险、代码风格是否一致。它不直接改代码只产出问题和建议。有人会问这三个角色各用一个独立的 OpenCode 实例不就行了我最初也是这么干的但很快发现缺一个东西编排层。谁来触发下一个 Agent上一个 Agent 的产出物怎么传递给下一个如果开发 Agent 发现方案有漏洞怎么回退给架构 Agent这些问题靠人肉协调在小团队里还能忍一旦任务频繁就完全失控了。1.3 为什么选择 Oh My OpenCode 做编排层Oh My OpenCode 给我的感觉像是给原生的 OpenCode 终端外挂了一套“组织流程”。它通过预定义的 Agent 角色、规则文件和 workflow 配置把多 Agent 的协作流程固化成了项目里看得见、改得动的文件。选择它而不是纯手写脚本最核心的原因是三点。第一点是状态可见。每个 Agent 的输入输出都有明确记录任务进行到哪一步、谁产生的、产生了什么全部有迹可循。第二点是流程可配置。你不需要改代码只需要修改 YAML 格式的工作流配置就能调整协作方式比如先评审后合并、开发失败自动重试几次、关键节点需要人工确认。第三点是权限隔离。可以限制开发 Agent 只读特定目录、限制评审 Agent 只能读取变更内容避免多个 Agent 同时操作文件导致互相覆盖。这三点听着简单但在真实项目里极其重要。状态可见让你敢把任务交给 Agent 之后去干别的事流程可配置让你能根据团队习惯灵活调整权限隔离则避免了很多“两个 Agent 改同一个文件”的灾难性现场。2. 环境准备与核心安装实操2.1 基础环境要求Oh My OpenCode 本身不依赖重型服务它运行在你的开发机或者 CI 容器里。我建议至少准备这样一套环境Linux/macOS 系统Windows 使用 WSL2 也没问题Node.js 18 以上版本Git 2.30 以上以及一个能正常运行的 OpenCode 终端环境。模型层面你需要准备一个兼容 OpenAI 接口的模型服务地址和 API Key。如果公司有内部部署的大模型网关直接填内网地址如果没有可以使用本地启动的模型服务。需要强调的是模型能力直接决定了 AgentTeam 的上限。如果团队在用 7B 量级的小模型那架构 Agent 的代码理解能力和评审 Agent 的上下文推理都会明显受限整个团队的产出质量会打折。我在环境准备上踩过的最大一个坑是忽略了 OpenCode 本身对 function call 能力的依赖。Agent 要和工具交互读文件、执行命令、搜索代码依赖模型原生支持 function calling。如果模型的接口声明支持、实际返回格式不标准Agent 会反复尝试解析工具调用结果表现得像“死循环”。所以模型选型时建议用一个你自己测过 function call 稳定性的大模型再谈后面的一切。2.2 安装 Oh My OpenCode 与初始化安装过程很简单官方提供了脚本方式。打开终端执行curl -fsSL https://install.ohmyopencode.dev | bash脚本会检测环境、安装核心 CLI 到用户目录并自动把oh-my-opencode命令加入 PATH。安装完成后验证一下版本oh-my-opencode --version接下来进入你的项目目录执行初始化命令cd /path/to/your/project oh-my-opencode init初始化会在项目根目录生成一个.oh-my-opencode/文件夹里面包含默认的 agents、rules、workflows 模板。此时我建议你把这些模板文件提交到 Git 仓库让整个团队共享同一套 Agent 配置。Agent 的配置和代码一样也需要版本管理和 Code Review。2.3 配置仓库目录结构与核心文件初始化的目录结构大概是这样的.oh-my-opencode/ ├── agents/ │ ├── architect.md │ ├── developer.md │ └── reviewer.md ├── rules/ │ ├── general.md │ ├── frontend.md │ └── backend.md ├── workflows/ │ └── default.yaml ├── prompts/ │ └── handoff.md └── settings.jsonagents/下面是每个 Agent 的角色定义文件使用 Markdown 格式核心是描述职责边界和工作习惯。rules/是全局或分技术栈的硬性约束。workflows/定义多 Agent 协作流程。prompts/handoff.md是 Agent 之间交接任务时的上下文摘要模板。这个目录结构本身就是一个团队规范。新人加入项目看完agents/和rules/就能理解整个 AI 团队是怎么运作的。它比任何文档都直接因为这套规则就是 AI 实际执行时用的同一套规则。3. 多 Agent 协作编排实战3.1 定义第一个 Agent架构 Agent架构 Agent 的角色文件我建议重点写清三个部分职责边界、工作流程、协作约束。下面这个是我经过多次调整后的模板--- name: architect model: coding-model-1 description: 负责需求分析、代码结构探索与技术方案设计 temperature: 0.2 tools: - code_search - file_read - directory_tree - git_log --- # 职责 - 分析需求描述拆解为具体的模块改动清单 - 阅读关键代码路径确认改动可行性和影响范围 - 输出技术方案文档包含改动步骤、涉及文件、风险点 # 工作流程 1. 先用 directory_tree 了解项目整体结构 2. 用 code_search 定位与需求相关的核心模块 3. 阅读关键文件确认接口和依赖关系 4. 输出方案文档保存到 docs/proposals/ 目录 # 协作约束 - 不直接修改业务代码只产出方案文档 - 如果发现需求本身有歧义在方案文档中标记待确认 - 方案必须包含明确的验收标准供后续开发 Agent 使用注意temperature: 0.2架构 Agent 的任务是理解分析需要尽量低随机性。它不需要创意它需要稳定和准确。协作约束里最重要的就是“不直接修改业务代码”这个边界能有效避免架构 Agent 在分析过程中顺手改几行、结果没人知道的问题。3.2 定义第二个 Agent开发 Agent开发 Agent 是团队里干活最多的角色它的配置重点在工具权限和编辑习惯上。--- name: developer model: coding-model-2 description: 负责按方案实现功能、编写测试与修复问题 temperature: 0.4 tools: - file_read - file_edit - directory_tree - shell_exec - grep_search allowed_paths: - src/ - tests/ - docs/ denied_paths: - .git/ - .oh-my-opencode/ --- # 职责 - 按照架构 Agent 输出的方案文档实现代码 - 为新增功能补充单元测试 - 处理编译错误和测试失败 # 工作流程 1. 读取方案文档 2. 按方案中列出的文件清单逐个实现 3. 每完成一个模块执行一次构建和测试 4. 全部完成后更新方案文档的实现状态 # 协作约束 - 遇到方案无法实现的地方把问题记录到 IMPLEMENTATION_NOTES.md - 不允许修改方案文档中的设计决策部分 - 执行 shell 命令时不允许运行 rm -rf 或 git pushallowed_paths和denied_paths非常重要。前者确保开发 Agent 只碰业务代码和测试不会去乱改框架配置或.oh-my-opencode自身。后者则是对危险操作的一层硬约束就算模型误判了意图也没有对应的工具权限去执行。3.3 任务编排从 Issue 到 MR 的工作流三个 Agent 定义好之后还需要一个工作流把它们串起来。workflows/default.yaml是我日常最常用的一套流程name: default_issue_to_mr description: 从任务描述到产出合并请求的标准流程 trigger: event: manual params: issue: string # 任务描述或 Issue 编号 steps: - id: architecture agent: architect input: task: ${issue} output: proposal: /docs/proposals/${timestamp}-${task_slug}.md next_on_success: development - id: development agent: developer input: proposal: ${architecture.proposal} output: notes: /IMPLEMENTATION_NOTES.md next_on_success: review - id: review agent: reviewer input: proposal: ${architecture.proposal} implementation_notes: ${development.notes} output: review_report: /docs/reviews/${timestamp}-review.md next_on_success: complete - id: complete agent: none action: create_mr这套流程的核心思路是“管线化”。架构阶段产出方案开发阶段按方案实现评审阶段验证质量。每个阶段的输出都会透传给下一个阶段而且原始文档都保存在项目里事后可以追溯任何一次决策过程。用的时候一行命令就能跑完整条流程oh-my-opencode run --workflow default.yaml --param issue把登录模块的接口超时从5秒调整为3秒并补充对应的测试4. 真实场景复现跨模块重构任务全过程4.1 场景设定与分析光说原理有点虚下面我用一个实际跑过的任务来复现整个流程。任务是“把订单模块的状态字段从字符串枚举迁移到整数枚举并保证所有依赖模块不回归”。这是典型的跨模块重构涉及数据库映射、业务逻辑、接口返回、前端展示四个层次。接到任务后我执行了上面那条工作流命令。架构 Agent 首先分析项目结构并定位了相关文件。它产出的方案文档里列出了四类改动点和每类的涉及文件包括持久层映射文件、业务状态判断逻辑、接口文档定义以及前端状态展示组件。方案最后附了三项验收标准所有对外接口的状态码兼容旧值、数据库存量数据有迁移脚本、核心链路测试全部通过。这个产出质量在我预期之上。架构 Agent 没有急于动手改代码而是把影响面完整梳理了出来尤其是“接口兼容旧值”这一点是真实项目里最容易遗漏的隐性需求。4.2 三阶段推进过程拆解开发 Agent 收到方案后的执行过程可以分成三个阶段。第一阶段是状态枚举定义与映射层改动。它新建了枚举类修改了持久层映射配置并跑了一次构建确认编译通过。这里有个细节值得提它每完成一个模块就构建一次而不是攒到最后统一处理这让问题定位变得非常快。第二阶段是业务层依赖调整。方案文档里的模块清单在这一阶段发挥了大作用开发 Agent 按照文件清单逐个修改没有出现“改一个漏一个”的情况。但过程中它发现了一个方案没有预判到的问题某个历史报表查询直接依赖了旧的状态字符串硬编码在 SQL 里。它没有自作主张修改方案而是把这个情况追加写进了 IMPLEMENTATION_NOTES.md。第三阶段是接口层兼容处理。开发 Agent 在对外返回时加了一层状态转换适配把新枚举映射回旧字符串保证调用方不需要改动。这一步直接落实了架构 Agent 定的验收标准也说明了方案里的“验收标准”不是摆设而是给开发 Agent 的明确指令。4.3 结果验收与回放评审 Agent 介入后做了几件事对照方案文档逐条确认开发 Agent 的实现是否覆盖全部改动点检查 IMPLEMENTATION_NOTES.md 里记录的历史报表问题是否处理妥当运行核心链路测试确认迁移脚本能正确处理存量数据。最终评审报告提出了一条需改进项新增枚举类的命名和项目中另一个领域模块的既有枚举风格不一致建议统一。这个属于代码风格问题不影响功能但暴露出一个问题——不同 Agent 各自训练数据里的编码风格偏好不一样需要用项目的rules/文件做统一约束。因为工作流配置了create_mr动作整个流程跑完后Oh My OpenCode 自动生成了一个合并请求草稿包含所有变更文件、方案文档路径、开发过程中的注意记录和评审报告摘要。人只需要打开 MR 检查一下确认没问题后点合并。整个过程中我实际介入的时间不超过十五分钟其中大部分是在最后检查 MR 时花的。对比之前一个 Agent 单打独斗的状态效率和可控性都有明显提升。5. 常见问题与排查技巧实录5.1 问题速查表实践这套方案的时候我整理了一份问题排查速查表基本覆盖了初期最常见的几类问题现象可能原因排查思路解决方案Agent 开始循环执行同一工具调用模型 function call 返回格式不稳定查看该 Agent 的会话日志定位是哪一步调用异常更换更稳定的模型或降低temperature到 0.2 以下开发 Agent 改的文件超出方案范围allowed_paths配置不完整检查该 Agent 的配置文件与变更文件列表完善allowed_paths将核心模块目录显式加入两个 Agent 的产出互相覆盖多个 Agent 同时操作同一路径检查 workflow 步骤之间是否存在并行执行调整为串行执行或按目录拆分 Agent 的职责手写配置不被加载文件名或目录层级错误执行oh-my-opencode doctor检查按模板文件覆盖结构调整架构 Agent 产出方案过于泛化缺少对项目的全局约束查看rules/general.md是否覆盖项目背景在规则文件中补充项目架构说明、编码规范和必读文档评审 Agent 漏掉关键风险评审范围仅限文本 diff检查 workflow 中评审输入是否包含方案文档在评审阶段显式传入方案文档与实施笔记补充一个排查技巧oh-my-opencode doctor这个命令能快速检查配置目录、依赖项和模型接口连通性排查问题第一步跑一遍它能挡掉一大半“低级错误”。5.2 关于这套玩法的三层理解第一层理解是“配置不是越多越好”。我最初给每个 Agent 配了十几个工具权限结果权限之间的边界模糊Agent 反而不知道优先用什么。后来砍到每类角色最少必要权限行为反而更稳定。Agent 团队和真人团队一样明确的职责边界比更多的工具更高效。第二层理解是“规则文件要当成代码维护”。rules/general.md里如果写了“项目使用双引号字符串风格”那就要有意识地让新代码遵循这个风格。如果规则文件长期不更新Agent 会基于自己训练时的常见模式形成一套与团队不一致的风格。最好定期把评审中发现的风格问题沉淀回规则文件形成正向循环。第三层理解是“工作流设计要为失败留出口”。在实际任务中开发 Agent 发现方案不可行的概率并不低。我的做法是在默认 workflow 里预留了一条失败路径开发 Agent 输出失败原因后流程不直接进入评审而是回到架构 Agent 重新调整方案。虽然会让流程多跑一轮但这避免了“带着错误方案硬闯评审”的尴尬局面。你可以在 workflow 配置里增加- id: development_failed trigger: on_failure_of: development agent: architect input: original_proposal: ${architecture.proposal} failure_reason: ${development.notes} next_on_success: development这套回溯机制我愿称之为 AgentTeam 的“容错安全网”。有了它整个团队才算真正具备处理真实世界复杂度的能力。5.3 三条真金白银的避坑心得第一条每个 Agent 都必须在配置里写明“协作约束”里的禁止项。我见过的最痛案例是没有约束评审 Agent 的写权限它为了验证自己的判断直接改掉了开发 Agent 的代码导致最后提交的代码根本不符合实现方案。所以必须明确职责评审永远只输出报告不直接改代码。第二条交接摘要比完整对话历史更可靠。工作流默认会让下游 Agent 读取上游 Agent 的完整产出物如果上游产出物本身有大量无关上下文下游 Agent 会被带偏。在prompts/handoff.md里定义了一套简洁摘要模板强制每个 Agent 在产出物结尾附上一个“交付摘要”写清已完成事项、未完成事项、需要下游特别关注的问题效果比直接透传强很多。第三条不要一次性跑几十个任务的批量工作流先把单个任务的流程跑稳定再并行化。并行跑多个 Agent 会遇到资源争抢和文件互锁的问题初期排查起来能把人折磨疯。先把单条流水线调通等配置和模型表现都稳定之后再扩展是一种务实很多的做法。最后分享一个小技巧我会在每周五下午花三十分钟翻一遍本周 Agent 生成的 review 报告和 IMPLEMENTATION_NOTES.md挑出重复发生的共性问题回写进rules/和 Agent 角色描述里。这个动作看起来不起眼但它是 AgentTeam 配置持续进化的核心机制。你完全可以先照着这篇文章搭一套最小方案从一个小模块开始试跑通流程后再逐步调整角色和规则让这套团队协作体系慢慢适配到你自己的项目里。