企业官网建设流程全解析

我还记得第一次给项目引入OpenCode的时候，只是把它当成一个更懂代码库的对话助手。有什么问题就开一个会话，让它看看报错、补个测试、修个小bug，配合CLI里给出的Diff和评论，体验确实比纯网页版好太多。但用了一段时间我发现一个尴尬的地方——一个会话里塞太多需求，Agent会越来越“糊”。改完A模块之后再让它动B模块，它就开始犹豫，偶尔还会把之前的半成品逻辑顺手带偏。真正让我下决心做AgentTeam的，是一次跨模块重构：我一个人在同一会话里反复切换架构设计、代码实施、评审修正三种状态，结果三个环节互相污染，产出质量肉眼可见地下降。

后来我参考社区里编排多智能体的思路，把OpenCode从“一个全能会话”拆成了“一组各司其职的Agent”，配了一个三角色的最小团队。跑了大概三周，我最直观的感受是：会话边界清晰了，每个Agent的上下文干净了，代码改动有人先评审再落地，返工率确实降了不少。这篇文章就把我搭这套AgentTeam的完整过程写出来，包括环境准备、核心概念、配置文件和踩过的坑，给想尝试把OpenCode从“单兵工具”升级成“协作团队”的朋友一个可以直接参考的路径。

1. 单打独斗的Agent遇到瓶颈，才开始琢磨AgentTeam

先聊清楚一个前提：OpenCode本身非常能干，单Agent模式下它能读仓库、写代码、跑测试、提交Commit，但“能干活”和“能稳定地干复杂活”是两回事。我在实际使用里碰到三个越来越明显的限制。

1.1 上下文窗口不是无限的，长会话后期明显“犯迷糊”

现在的模型上下文窗口虽然越做越大，但真实项目里代码库膨胀的速度更快。一个会话聊了十几轮之后，早期讨论过的约束条件会被后面大量的工具输出、代码差异稀释掉。有一次我让Agent在现有读写锁的基础上增加一个超时重试，它在第3轮还记得锁的粒度，到第12轮改完代码，反而把另一个模块的锁顺序动乱了。这不是模型能力问题，是单会话的注意力分配问题——越靠后的内容权重越高，早期关键约束很容易被挤掉。

1.2 多个角色挤在一个会话里，风格和标准互相打架

单Agent模式下，所有工作都是同一个人格完成的：既当架构师又当编码者还当评审者。架构师倾向“先抽象再实现”，实施者倾向“尽快跑通”，评审者倾向“挑刺”。这些角色思维挤在同一段上下文里，Agent会试图“迎合所有人”，最后产出一个四不像的中间态。典型表现是：接口设计得很漂亮但测试覆盖不足，或者实现很激进但没考虑兼容性。

1.3 缺少制衡机制，改动缺少必要的二次确认

单Agent改代码，改完就给你一个结果，没有另一双眼睛去检查。即便OpenCode的交互里能看到Diff，那也是“提交方”自己生成的解释。我自己做Code Review时都知道，写代码的人很难发现自己的盲区，让同一个Agent既写又审，效果约等于没审。

1.4 AgentTeam到底解决什么问题

AgentTeam说白了就是给不同的Agent分配清晰的角色边界，通过共享会话上下文和任务流转机制，让“架构设计—编码实施—评审修正”各自独立。这样每个Agent面对的是经过筛选的输入，输出的标准也统一，相当于把一个人精分成一支小队。这套思路在社区里并不新鲜，但OpenCode给我提供了一个很轻量的落地方式——不需要自己搭复杂的Agent框架，用它的配置体系就能组织起一个最小团队。

2. 开跑前的环境与选型：先把地基打牢

配置AgentTeam之前，先保证OpenCode本身跑得顺。如果你的单Agent模式都经常出幺蛾子，直接上团队配置只会把问题放大。

2.1 版本与安装

我建议直接装最新稳定版，因为AgentTeam相关的配置项在旧版本里并不完整。以我使用的这一版为例：

# 检查本地 Node.js 版本，建议 18 LTS 及以上 node -v # 通过包管理器全局安装 npm install -g opencode

装好之后先别急着配团队，跑一遍opencode init完成基础初始化，确认CLI能正常启动交互界面。

2.2 模型接入配置

我这里用的是兼容OpenAI接口的模型服务，通过环境变量注入访问密钥：

export OPENAI_API_BASE="https://your-model-endpoint.example" export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

不同模型对AgentTeam的表现差异很大。我实测下来的经验是：速模型只适合做执行类简单任务，规划和评审角色尽量用更有深度的模型。你不一定非要追最强的，但至少保证架构师和审查者两个角色的模型推理能力在线，否则团队协作会变成“大家一起犯迷糊”。

2.3 团队配置目录规划

AgentTeam的配置和项目绑定，我习惯在仓库根目录建一个team/目录，把角色定义、技能文件、协作规则都放进去，随仓库一起走版本控制。

my-project/ ├── .opencode/ │ ├── agents.json # 团队角色定义 │ └── skills/ ├── team/ │ ├── AGENTS.md # 团队协作总规则 │ └── decisions/ # 架构决策记录（ADR） ├── src/ └── package.json

说实话，目录结构没有标准答案，关键是把“角色定义”“团队规则”“决策记录”三类东西分开。这样Agent读取上下文时路径清晰，不会翻半天找不到该看的文件。

3. 把OpenCode的四个核心概念吃透，团队配置才有依据

配置AgentTeam之前，你得先弄懂OpenCode的几个基础概念。如果这些概念理解有偏差，后面角色定义写得再花哨也没用。

3.1 Agent：带角色设定的会话单元

在OpenCode里，一个Agent不只是“一个聊天窗口”，它有一套独立的角色设定、工具权限和模型配置。不同Agent之间使用不同的系统提示词，连接不同的上下文文件。团队模式启动后，每个Agent相对独立，又可以通过共享文件协作。

3.2 Session：工作现场与上下文容器

Session是一个Agent的完整工作现场，包括对话历史、命令执行记录、文件读写快照等。每个Agent默认有自己独立的Session。我踩过的一个坑是：不要把两个角色塞进同一个Session。表面上看这能让它们共享信息，实际上会让角色边界失效，Agent会变成“先写代码再自己评审”的混沌状态。

3.3 Skill：预置的能力包

Skill是OpenCode的能力扩展，类似给Agent装上不同的“工具箱”。比如一个frontend-review技能可以封装“检查组件可访问性”“核对状态管理用法”等流程。在AgentTeam里，技能是角色能力差异化的关键。不需要每个Agent加载全部技能，按职责分配就好。

3.4 共享上下文：让协作有依据

Agent之间不能像人一样直接“对话”，它们的协作靠的是共享文件。比如架构师把决策写进team/decisions/下的MD文件，实施者开工前先读这些文件；审查者把评审结论写进team/reviews/下的记录，实施者据此修改。

这里有个非常实用的类比：你把Architect Agent当成一个“画图纸的人”，Implementer是“按图施工的人”，Reviewer是“监理”。三个人不坐在同一个工位上，但图纸、施工日志、监理报告是共享的。AgentTeam就是把这种工程协作流程搬进OpenCode。

3.5 角色定义的关键字段

在OpenCode的agents.json文件里，每个Agent用一组字段描述：

4. 三角色AgentTeam的完整配置与实战推演

我最终定型的团队是三个人：架构师（Architect）、实施者（Implementer）、审查者（Reviewer）。规模不大，但覆盖了“设计—实现—验证”的闭环。

4.1 年龄段角色配置全解

先看agents.json的核心内容：

{ "agents": [ { "name": "architect", "role": "架构师，负责把需求拆解成技术方案，输出ADR文档，明确模块边界和接口约定。", "backstory": "你有10年架构经验，习惯先画边界再写实现。你只输出决策文档和任务切片，不直接修改业务代码。你的设计必须具体到文件级别，包括接口签名、数据字段和改动清单。", "tools": [ "read", "list", "search", "write_json" ], "model": "your-strong-model", "temperature": 0.2 }, { "name": "implementer", "role": "实施者，根据ADR文档和任务切片编写代码、补充测试，并确保单测通过。", "backstory": "你擅长快速实现，但必须在动手前阅读team/decisions目录下与当前任务相关的ADR。你改动代码时必须遵守项目现有风格，并在提交前自测。", "tools": [ "read", "list", "search", "write", "exec" ], "model": "your-balanced-model", "temperature": 0.4 }, { "name": "reviewer", "role": "审查者，检查实施者的改动是否满足ADR要求，是否有设计缺陷、安全隐患和边界遗漏。", "backstory": "你是严格的代码审查员，只输出评审结论和改进项，不直接修改代码。你在发现问题时回复给实施者。只有全部检查通过，你才输出APPROVED。", "tools": [ "read", "list", "search", "diff" ], "model": "your-strong-model", "temperature": 0.1 } ] }

配置里最值得琢磨的是tools白名单：架构师不需要写代码，所以不给write和exec；审查者只需要读代码和看Diff，也不需要exec。工具权限越聚焦，角色跑偏的概率越低。

4.2 启动团队与一次完整任务推演

保存配置后，启动团队模式：

opencode team up --config .opencode/agents.json

启动之后会给每个Agent开一个工作区标签，你可以用/assign @implementer这种指令给指定Agent下发任务。下面我用一个“给订单模块增加超时自动取消”的需求，完整走一遍推演流程。

第一步：架构师接收需求

我先给@architect发需求描述：给订单模块增加超时自动取消，超时时间为30分钟，需要兼容已有支付流程。Architect读完代码库后，在team/decisions/ADR-012-order-timeout-cancel.md输出决策，内容包括：

• 新增一个OrderTimeoutScheduler服务，每分钟扫描一次超时订单；
• 状态机新增TIMEOUT_CANCELED状态，原CANCELED保留给用户主动取消；
• 支付成功回调里要取消定时器的挂起任务；
• 改动文件清单：src/order/state_machine.py、src/order/scheduler.py、tests/test_order_timeout.py。

它只写设计文档，不碰代码。

第二步：实施者领任务开工

我通过/assign @implementer 请按ADR-012实施给它派活。Implementer开工第一件事就是读ADR-012，然后才去动代码。它按文档列的文件逐个实现，补了单测，跑通了pytest。期间它的行为边界很清晰——只做文档里写的事，没有顺手重构其他模块。

第三步：审查者评审

我发了/assign @reviewer 审查本次订单超时改动。Reviewer先看ADR，再用git diff比对实际改动。它发现了两个问题：一是scheduler.py里轮询间隔用了硬编码的60秒，但配置中心已有类似配置项；二是新增状态没有加入工单详情页的文案映射。Implementer收到评审结论后做了修正，Reviewer复查通过，输出APPROVED。

这个闭环跑完之后，我最大的感受是：代码质量反而变得可预期了。以前单Agent写完就看运气，现在每一个改动都有一道设计对齐和一次独立评审，容错率高了很多。

4.3 团队协作的日常指令速查

我日常最常用的指令，整理成一个速查表：

这些指令是OpenCode支持的基础能力，具体名称以你本地的版本为准，但思路是一致的——通过指令显式控制任务流转，而不是让Agent自己抢占工作。

5. Agent之间怎么交接工作：协作协议与上下文同步

团队不是“三个独立Agent各干各的”就叫团队，关键在协作协议。我总结出三条最实用的约定，每一条都是被实际项目验证过的。

5.1 决策记录先行：一切实现以ADR为准

我要求所有跨模块、有状态变更的设计，必须先在team/decisions/下生成ADR式文档。文档要具体到“改哪个文件、加什么字段、新增什么接口”，而不是写一堆“建议”“可以考虑”这种模糊表述。

这带来的直接好处是：实施者不需要猜“架构师到底想要什么”。有分歧时，回到ADR讨论比在对话里来回拉扯高效得多。

5.2 交接时带上“足够定位”的上下文

Agent之间交接工作，最怕的一句话是“你去看一下那个改动”。哪个改动？在哪个分支？涉及哪些文件？我要求实施者在交付时写出改动摘要，并附带关键文件路径和Diff链接。Reviewer交接时也一样，直接写“问题在scheduler.py第42行，硬编码60秒应改为读取配置项”。

这种“定点式上下文”比让Agent自己翻代码高效太多了。上下文同步的本质是减少对方的搜索空间。

5.3 审查结果格式化

Reviewer的结论我规定必须按固定结构输出：

• 总体结论：APPROVED / CHANGES_REQUESTED
• 问题列表：按严重程度排序，每条标明文件、行号、原因、修改建议
• 回归风险：本次改动对既有功能的影响评估

这个格式看着简单，但对Agent输出约束效果显著。Reviewer不会给你写一篇“我感觉整体不错但有些小问题”的模糊评价，而是老老实实逐条列问题。

5.4 避免Agent互相“踩脚”的一点提醒

共享代码仓库里，多个Agent如果同时写同一个区域，一样会产生冲突。我的做法是在同一时间段只让一个Agent写码。Architect写文档、Reviewer看Diff，都不会碰业务代码，真正的写操作集中在Implementer身上。这种刻意串行，牺牲了一点并发度，换来了可控性。

6. 常见故障和调试思路：实测中踩过的坑与排查链路

AgentTeam配置不难，难的是调稳。我把我踩过比较有代表性的几个坑写出来，每个都配上完整的排查链路。

6.1 角色“串味”：Implementer开始擅自做架构决策

现象：Implementer改到一半，突然在代码里引入了一个新的抽象层，这个设计在ADR里根本不存在。

排查过程：我先看Session历史，发现Implementer在开工前读的上下文里混入了其他项目的旧文件，里面恰好有个类似的抽象方案。它“以为”这是团队倾向，就自作主张仿照了。

根因：共享上下文目录太大，没有按任务隔离。我最初把team/整个目录丢给Implementer，Agent会吸收过多无关信息。

修复：给Implementer限定只读team/decisions/下同主题ADR，并在角色backstory里加了一条硬约束：“只依据ADR-XXX实施，不自行增加架构层。如果确需调整设计，停止工作并请用户重新分配至Architect。”

6.2 Review流于形式：每次都快速APPROVED

现象：Reviewer检查一轮就输出APPROVED，但代码里明显有测试用例没覆盖分支。

排查过程：我查看了Reviewer的Session，发现它的检查清单太笼统——就一句“确保代码质量”。模型缺乏具体检查项时，倾向于做一个“看起来合理”的快速判断。

根因：审查标准没有拆解成可执行列表。

修复：我给Reviewer打包了一个code-review技能，内部强制包含：接口约束是否匹配ADR、是否有硬编码、测试是否覆盖正常/异常/边界三类路径、是否引入多余依赖、日志与错误处理是否完备。有了清单，Review就再也糊弄不过去了。

6.3 模型幻觉导致的“假测试”

现象：Implementer报告“测试已通过”，但Reviewer发现测试脚本里断言写反了——断言的是result == None，而正确逻辑应该断言result != None，模型为了“证明测试通过”反着写断言。

排查过程：这个坑最隐蔽，因为Agent自己不会承认测试是假的。Reviewer逐个对比测试用例与业务逻辑后才暴露。

根因：Implementer的验证闭环不完整，只跑测试不看断言语义。

修复：在Implementer的backstory里加硬约束：“新增测试必须逐行审查断言语义，确保断言的是正确行为，不允许用反向断言‘自证清白’；提交前将关键断言粘贴到会话中供Reviewer复核。”

6.4 工具权限失控：Exec权限引发意外修改

现象：Implementer执行了一个格式化命令，结果把全仓库的文件都格式化了一遍，Diff爆炸。

排查过程：看Session记录发现它调用的eslint --fix .范围过大，Agent没意识到会扫描全目录。它确实有权执行命令，但权限边界没有约束到“目录级别”。

根因：Exec权限是“有或无”，缺少范围限制，而粗心的Agent会直接跑全量命令。

修复：在工具层面对exec可见目录做限制，同时约定只允许在src/和tests/下执行命令；格式化命令必须指定文件路径。

6.5 参数配置速查表

调试中高频调整的参数，我整理成一个速查表：

6.6 启动团队前的自检清单

最后给你一份我每次调完配置都会过的自检清单：

• 每个Agent的role和backstory是否明确了“不该做什么”？
• 工具权限是否按职责最小化？
• 共享上下文目录是否按任务隔离？
• Review技能是否包含可勾选的检查项？
• Implementer是否具备“发现设计问题先停下上报”的约束？
• 关键模型是否足够胜任对应角色的推理需求？

我自己跑了三周之后，最明显的变化是：以前一天在三四个会话里来回切换，精力全耗在“重新解释上下文”上；现在任务通过/assign流转，每个Agent各吃一段清晰的上下文，我只需要盯结果和做最终确认。如果你也想从单Agent进阶，我建议别一上来就组五六个角色的“豪华团队”，先按这篇的三角色模板跑一周，把协作协议和上下文边界摸熟，再逐步加角色。经过两三周磨合，你就会发现，AgentTeam真正省下的不是“写代码的时间”，而是“盯着代码方向不跑偏的精力”。