使用 CodeBuddy IDE 构建真正的 Agent Team：从 Skill 隐式编排到 team_create 工具链

上一篇用 Skill 编排搭了一个 Agent Team——5 个角色、网状通信、自主决策。CodeBuddy 的 Team 模式确实提供了独立上下文、点对点通信、并行执行这些基础设施但那篇文章的编排方式是隐式的团队的组建、成员的派发、协作的启动全部藏在 Skill 的 prompt 设计和文件组织里看不到 team_create看不到 task也看不到显式的 send_message 调用。这篇讲怎么用 team_create/task/send_message/team_delete 四个显式工具函数把同样 5 个角色从Skill 隐式编排改造成工具链显式编排——让团队的创建、通信、生命周期全部可见可控。第一章旧文章到底搭了个什么——Skill 编排的隐式 Agent Team先回顾上一篇《使用 CodeBuddy IDE 构建 Agent Team》做了什么一个 Skill 入口SKILL.md、一个编排命令commands/article-team.md、5 个成员 prompt 文件agents/目录下的 scout、architect、writer、reviewer、polisher。目录结构清晰角色分工明确prompt 里写好了通信规则——reviewer 可以send_message给 writer 退回修改architect 可以直接找 scout 讨论选题。旧文章确认了 CodeBuddy 的 Team 模式已经具备三项关键基础设施能力说明独立上下文Team 模式下每个 member 有自己的对话历史点对点通信send_message的recipient可以是任意 member并行执行Team 模式支持并行启动这三项都是真实存在的平台能力不是旧文章编造的。旧文章的 Agent Team 也确实建立在这些能力之上。那问题出在哪问题不在能力有没有而在**“能力怎么被调用的”**。旧文章的编排方式是写一组 Skill 文件SKILL.md 编排命令 成员 prompt用户触发/article-team后由 Skill 的加载机制把这些 prompt 送进运行时。团队的组建、成员的派发、协作的启动——这些事情都发生在 Skill 加载和 prompt 注入的过程中在运行时看不到一行team_create调用看不到一行task派发send_message也是写在 prompt 的通信规则描述里。打个比方就像一个工厂旧方案是把组织架构图贴在墙上prompt 文件工人看了架构图自行组织协作新方案是用 ERP 系统下工单、派任务、追踪进度team_create/task/send_message/team_delete每一步操作都有系统记录。工人Agent可能是同一批人工厂CodeBuddy 的 Team 模式基础设施也是同一个——但管理方式完全不同。三个实际局限旧方案的隐式编排带来三个具体问题1. 团队组建不透明团队是怎么建起来的成员是什么时候加入的哪些成员在运行——这些问题在 Skill 编排方式下只能通过阅读 prompt 文件来推断运行时没有显式的创建动作可追溯。2. 通信过程不可控prompt 里写了reviewer 可以 send_message 给 writer但这条通信规则是描述性的——它描述了 Agent 应该做什么而不是给了 Agent 一个它能感知到的工具调用指令。Agent 是否真正调用了send_message、消息是否投递成功、对方是否收到——在隐式编排下不容易确认。3. 生命周期无管理Skill 执行完了就结束了。成员是什么时候退出的有没有正在进行的任务被中断资源有没有释放——没有显式的shutdown_request和team_delete这些问题缺少可控的管理手段。对照图隐式编排 vs 显式编排Skill 隐式编排 工具链显式编排 .codebuddy/skills/article-team/ team_create(article-team-20260410) ├── SKILL.md │ ├── commands/article-team.md ├─ task(scout) ← 显式派发 └── agents/ ├─ task(architect) ← 显式派发 ├── scout.md ├─ task(writer) ← 显式派发 ├── architect.md ├─ task(reviewer) ← 显式派发 ├── writer.md ├─ task(polisher) ← 显式派发 ├── reviewer.md │ └── polisher.md ├─ send_message ← 显式通信 ├─ shutdown_request← 显式关闭 触发/article-team └─ team_delete() ← 显式销毁 团队组建隐式Skill 加载时发生 通信方式prompt 描述通信规则 运行时每一步操作都有对应的工具调用 生命周期隐式Skill 结束时结束一句话总结旧文章用 Skill 的文件组织和 prompt 设计来隐式编排 Agent Team新方案用 team_create/task/send_message/team_delete 四个工具来显式编排——底层的 Team 模式能力是同一套区别在编排层。这不是说隐式编排没有价值——对很多场景它够用了第六章会讲什么时候够用。但当需要精确控制团队的创建时机、成员的派发顺序、通信的可追溯性和资源的显式释放时就需要换成工具链显式编排。第二章显式编排需要什么——从隐式到显式的四个跨越从 Skill 的隐式编排升级到工具链的显式编排核心是让四个原本藏在 Skill 加载过程中的能力变得可见、可控、可追溯四个显式化要求简单说就是把四件原来自动发生的事变成亲手调用建团队——用team_create替代 Skill 加载时的隐式组建派成员——用task替代读取agents/目录的隐式加载发消息——用send_message工具调用替代 prompt 里的通信规则描述关团队——用shutdown_requestteam_delete替代 Skill 结束时的隐式清理每一个的具体做法和差异第三章逐个展开。对照表Skill 隐式编排 vs 工具链显式编排维度Skill 隐式编排工具链显式编排团队创建Skill 加载时隐式发生team_create显式调用成员派发读取 agents/ 目录的 prompt 文件task逐个显式派发独立实例通信方式prompt 里的通信规则描述send_message工具的显式调用执行控制由 Skill 编排命令统一驱动协调者按需派发可控制顺序和时机生命周期Skill 结束时隐式结束shutdown_requestteam_delete显式管理可追溯性低——需要读 prompt 文件推断高——每一步操作都有对应的工具调用显式编排的代价是搭建成本更高——需要手写 team_create、task 调用逻辑、处理 send_message 的路由和时序。隐式编排的优势正是简单——写好 prompt 文件、触发 Skill 就能跑。选哪种取决于对可控性的需求第六章详谈。第三章四个工具串起整条链路——team_create / task / send_message / team_delete上一篇文章《CodeBuddy 的多 Agent 协作是怎么搭起来的》已经详细拆解了四个工具的参数和用法。这里不重复参数细节重点讲每个工具在从隐式编排到显式编排这个改造过程中解决了什么问题。3.1 team_create建团队容器——Skill 编排版没有这一步Skill 编排版的团队是什么是.codebuddy/skills/article-team/目录下的一组文件。触发 Skill 后团队的组建隐式发生在 Skill 加载过程中——没有显式的建团队动作。team_create(team_name: article-team-20260410, description: 文章编写协作工作流)team_create做的事是在运行时创建一个真正的团队容器。这个容器提供成员注册表后续通过task加入的 Agent 在这里注册send_message的路由依赖它消息路由Agent A 发给 Agent B 的消息靠团队容器找到 B 的收件箱并投递生命周期管理团队里有谁、谁还活着、谁已关闭容器统一管理没有这一步后面的task没有地方注册 Agentsend_message发出去找不到人。3.2 task异步团队模式派发独立 Agent 实例——关键差异是 name team_name 触发异步Skill 编排版的派发 Agent是怎么发生的Skill 加载时自动把成员 prompt 注入运行时成员的创建和启动由 Skill 机制内部完成——在运行时看不到task调用。显式编排版的派发task( subagent_name: scout, name: scout, team_name: article-team-20260410, mode: bypassPermissions, description: 选题调研, prompt: 搜索 AI 工程化近期热点阅读作者已有文章避免重复选题 给出 3-5 个选题方案。完成后使用 send_message 通知 main。 )关键差异同时传入name和team_name触发异步团队模式。task会创建一个独立的 Agent 实例——有自己的上下文窗口、自己的执行线程。创建后它在后台运行不阻塞调用方。subagent_name 从哪里来task的subagent_name引用的是已注册的 Agent 类型名称。文章编写团队的scout/architect/writer/reviewer/polisher不是内置 Agent。自定义注册如果用的是自定义多 Agent 插件需要先在plugin.json中注册为 subagenttask才能找到它们。详见第五章踩坑记录中的Agent 注册失败。快捷方式如果不想自定义注册可以统一用内置的code-explorer作为subagent_name把角色职责全部放在prompt参数里。对比一下Skill 隐式编排成员的创建和派发由 Skill 加载机制自动完成在运行时看不到派发过程工具链显式编排task显式创建独立实例 → 实例在后台运行 → 通过send_message通信 → 派发时机和顺序完全由协调者控制3.3 send_message显式的消息投递这是隐式编排和显式编排差异最明显的地方。Skill 隐式编排版里prompt 写了reviewer 可以 send_message 给 writer。这是一条通信规则描述——它告诉 Agent 应该做什么但 Agent 是否真正调用了send_message工具、消息投递过程是否可追踪在隐式编排下不容易确认。显式编排版里# reviewer 调用 send_message( type: message, recipient: writer, content: 第三节的代码示例有误task 的 name 参数不是必填项请修正。, summary: 审稿意见 )这条消息会被 reviewer 的 Agent 实例生成为一个 Function Call运行时解析这个 Function Call找到团队容器里注册的 writer把消息投递到 writer 的收件箱writer 在下一个执行轮次读到这条消息并处理消息经过了真正的投递过程reviewer 和 writer 是两个不同的 Agent 实例。这就是显式编排的优势——每条消息的发送者、接收者、内容都是可追踪的工具调用reviewer 退回修改后writer 在自己的上下文里处理审稿意见不会被其他角色的历史内容干扰。3.4 team_delete显式销毁Skill 隐式编排版没有显式的销毁步骤——Skill 执行流程结束时团队的清理隐式发生。显式编排版需要明确清理# 先逐个关闭成员 send_message(type: shutdown_request, recipient: scout) send_message(type: shutdown_request, recipient: architect) send_message(type: shutdown_request, recipient: writer) send_message(type: shutdown_request, recipient: reviewer) send_message(type: shutdown_request, recipient: polisher) # 等所有成员确认关闭后 team_delete()为什么需要因为每个 Agent 实例占用独立的资源上下文窗口、执行线程。不清理就一直挂着。而且shutdown_request给了 Agent 一个收尾机会——polisher 可能正在写最后一段直接杀掉会丢数据。3.5 完整流程对照Skill 隐式编排版 工具链显式编排版 触发 /article-team team_create(article-team-20260410) │ │ ├─ Skill 加载隐式组建团队 ├─ task(scout) → 选题完成后 ├─ 成员 prompt 自动注入运行时 ├─ task(architect) → 大纲确认后 ├─ 通信规则写在 prompt 描述中 ├─ task(writer) → 初稿完成后 ├─ 协作过程由 Skill 机制内部驱动 ├─ task(reviewer) → 审稿通过后 │ ├─ task(polisher) → 按需派发 │ │ └─ Skill 结束隐式清理 ├─ Agent 之间通过 send_message 显式通信 ├─ reviewer → writer 消息真正可追踪 ├─ shutdown_request → 逐个关闭 └─ team_delete() → 显式销毁 团队组建/通信/清理隐式 团队组建/通信/清理显式、每一步有对应工具调用第四章每个角色的 prompt 怎么改——从描述通信规则到使用真正的工具这是全文最关键的落地章节。Skill 隐式编排版和工具链显式编排版的 prompt 差异不在于角色定义或职责描述那些基本一样而在于通信和协作的部分怎么写。4.1 总体原则Skill 隐式编排版的 prompt 写的是通信规则描述——描述 Agent 应该和谁沟通、沟通什么但通信的实际发生由 Skill 机制内部驱动。工具链显式编排版的 prompt 写的是工具使用指令——告诉一个独立运行的 Agent 实例有 send_message 这个工具用它给 writer 发消息。这些指令会被 Agent 显式执行为 Function Call。核心区别就一句话隐式编排版写的是应该怎么做的描述显式编排版写的是用什么工具做的指令。4.2 逐角色对比协调者编排命令Skill 隐式编排版commands/article-team.md你是文章编写团队的协调者。 按顺序读取 agents/ 目录下的 prompt组织各角色完成任务。 通信规则在 prompt 中描述由 Skill 机制驱动执行。工具链显式编排版你是文章编写团队的协调者。 ## 你的工具 - team_create创建团队容器 - task派发独立 Agent 实例注意 name team_name 触发异步模式 - send_message和团队成员通信 - team_delete工作完成后销毁团队 ## 工作流程 1. 用 team_create 建团队 2. 按需用 task 派发成员不一次性全派根据流程节点决定 3. 接收成员的 send_message 通知在关键节点请用户确认 4. 全部完成后先 shutdown_request 所有成员再 team_delete ## 你不做的事 - 不中转成员之间的消息让他们直接 send_message - 不决定文章退不退回修改reviewer 自己决定关键差异隐式编排版协调者通过 Skill 的 prompt 组织来驱动流程显式编排版协调者用task派发独立实例、用send_message通信——每一步操作都有对应的工具调用。技术审稿人reviewerSkill 隐式编排版## 审查结果处理 - 有严重问题send_message 给 writer附上具体问题和修改建议 - 无严重问题审稿通过send_message 给 polisher 启动润色 ## 通信规则 - send_message 给 writer退回修改 - send_message 给 polisher审稿通过 - send_message 给 main需要用户介入时工具链显式编排版## 审查结果处理——用 send_message 工具执行 - 有严重问题 调用 send_message(type: message, recipient: writer, content: 具体问题和修改建议, summary: 审稿退回) 不用经过 main不用等任何人批准 - 无严重问题 调用 send_message(type: message, recipient: polisher, content: 审稿通过请开始润色, summary: 审稿通过) ## 通信工具使用 - send_message(recipient: writer)退回修改 - send_message(recipient: polisher)审稿通过 - send_message(recipient: main)超 3 轮需用户介入 - send_message(recipient: scout/architect)讨论选题或结构问题 ## 重要 - 你是一个独立运行的 Agent 实例writer 是另一个独立实例 - 你发给 writer 的消息会真正进入 writer 的收件箱 - 退回决策完全自主审查-修改循环最多 3 轮关键差异显式编排版明确告诉 Agent你有 send_message 工具“writer 是另一个独立实例”“消息会真正投递”。这些不是废话——Agent 需要知道自己的操作会被执行为真正的 Function Call否则它可能只是描述一下发消息的意图而不是真正调用工具。初稿写手writerSkill 隐式编排版## 自主判断 - 大纲某部分不合理直接 send_message 给 architect 讨论 - reviewer 要求修改时自行判断修改方案不用等 main 指示 - 修改完成后直接通知 reviewer 重新审查工具链显式编排版## 协作工具使用 - 发现大纲问题调用 send_message(recipient: architect, content: 具体问题) - 收到 reviewer 的修改意见直接修改文章完成后调用 send_message(recipient: reviewer, content: 已修改请重新审查) - 初稿完成调用 send_message(recipient: main, content: 初稿已完成, summary: 初稿完成) ## 你会收到的消息 - 来自 main 的任务指令包含大纲内容 - 来自 reviewer 的审稿意见需要处理并回复 - 来自 architect 的大纲调整通知需要据此修改关键差异显式编排版增加了你会收到的消息这一段。因为 writer 是独立实例它需要知道自己的收件箱里可能出现哪些来源的消息以及如何响应。隐式编排版不需要这个——通信的接收和处理由 Skill 机制内部管理。选题侦察员scout和大纲架构师architect改法和上面类似核心变化是把send_message 给 XXX从描述性文字改成工具调用指令增加你会收到的消息部分明确告知你是独立实例对方也是独立实例终稿润色师polisher## 协作工具使用 - 发现技术错误调用 send_message(recipient: reviewer, content: 发现技术问题详情如下...) - 标题问题调用 send_message(recipient: scout, content: 标题建议调整...) - 润色完成调用 send_message(recipient: main, content: 终稿已完成, summary: 终稿待确认) ## 你会收到的消息 - 来自 reviewer 的审稿通过通知表示可以开始润色 - 来自 main 的任务指令4.3 可复用的通信规则 prompt 模板不管哪个角色通信相关的 prompt 都可以套用这个模板## 你的通信工具 你有 send_message 工具可以直接和团队成员通信。 ## 发送消息 - 发给 [角色名]send_message(type: message, recipient: [角色名], content: 消息内容, summary: 5-10字摘要) - 发给协调者send_message(type: message, recipient: main, content: 消息内容, summary: 摘要) ## 你会收到的消息 - 来自 [角色A] 的 [什么类型的消息][如何响应] - 来自 [角色B] 的 [什么类型的消息][如何响应] - 来自 main 的任务指令[如何响应] ## 通信原则 - 直接发给目标角色不经过 main 中转 - 需要用户确认时才发给 main - 每条消息附上 summary方便协调者追踪把角色名和消息类型填进去就能用。这个模板的关键是三段式能发什么 会收到什么 发送原则。注意send_message的四个参数中只有type是必填的参见 schema 定义required: [type]。recipient、content、summary都是可选参数视场景使用。但在实际团队通信中recipient和content几乎必带——不指定收件人和内容的消息没有意义。第五章踩坑记录从 Skill 隐式编排改造到工具链显式编排的过程中以下问题大概率会遇到。踩坑现象原因解法Agent 注册失败task调用报错未注册为 subagent只写了 Agent 定义文件如agents/reviewer.md没有在plugin.json中注册在插件的plugin.json中把自定义 Agent 注册为 subagenttask的subagent_name引用的是注册表里的名称不是文件路径消息发出去没人接reviewer 发了 send_message 给 writer但 writer 没有任何反应writer 还没被task派发到团队里团队注册表里找不到 writer确保task派发的顺序合理——收消息的 Agent 必须先于发消息的 Agent 被加入团队或者在发送前确认目标 Agent 已注册无限退回循环reviewer 和 writer 之间不断来回退回修改停不下来prompt 里没有写退出条件两个 Agent 各自按规则执行在 reviewer 的 prompt 里设置轮次上限如审查-修改循环最多 3 轮超过后汇总发给 main 让用户介入同时设置task的max_turns参数作为硬兜底上下文膨胀Agent 运行一段时间后开始忘记早期指令输出质量下降虽然每个 Agent 有独立上下文但长时间运行后单个 Agent 的上下文也会很长——特别是 writer 和 reviewer 之间多次来回后在 send_message 里传结构化摘要而非全文比如 reviewer 只发具体问题列表不把整篇文章的审查详情都塞进 content关键文件产出写入磁盘而非留在上下文里调试困难多个 Agent 同时运行出了问题不知道是谁的锅Agent 之间的消息和执行过程分散在各自独立的上下文中没有统一的日志视图在每个 Agent 的 prompt 里要求关键动作前发一条摘要给 main如即将退回 writer 修改让协调者的上下文成为事实上的日志聚合点team_delete 后资源残留删了团队但有些 Agent 似乎还在运行没有先 shutdown_request 就直接 team_deleteAgent 实例还在后台严格执行先逐个 shutdown_request等 shutdown_response 确认再 team_delete的流程这些坑不是理论推演——每一个都是实际改造过程中真实遇到的。其中无限退回循环和Agent 注册失败出现频率最高。第六章适用边界——什么时候 Skill 隐式编排够用什么时候必须上工具链显式编排Skill 隐式编排够用的场景角色之间没有复杂交互流程是线性的A 做完给 BB 做完给 C不存在退回、并行、讨论。比如简单的选题→大纲→写稿→润色流水线每一步输出直接作为下一步输入。总上下文长度可控所有角色的输入输出加起来不超过模型的有效注意力范围。一篇 3000 字的短文5 个角色的总产出可能只占 10K token模型处理起来毫无压力。不需要并行任务本身是串行的没有architect 设计大纲的同时 scout 继续搜索这种需求。快速原型先用 Skill 隐式编排跑通流程逻辑验证角色分工和通信规则是否合理再决定要不要升级到工具链显式编排。必须上工具链显式编排的场景需要精确控制成员派发时机比如 reviewer 必须在 writer 完成后才启动而不是一开始就全部加载进来。需要可追踪的通信reviewer 退回 writer 修改后需要确认消息是否投递成功、writer 是否收到并处理了。需要并行加速长文写作时不同章节可以由不同 writer 实例并行撰写或者 reviewer 审前几章的同时 writer 继续写后几章。角色之间需要多轮异步交互architect 和 scout 就选题方向来回讨论三轮这种多轮交互需要每条消息都是可追踪的工具调用而不是隐藏在 prompt 驱动的内部过程中。需要显式的资源管理团队什么时候建、成员什么时候关、资源什么时候释放——这些需要明确的team_create和team_delete来保障。渐进式迁移路径不需要一步到位。推荐的升级路线第 1 阶段Skill 隐式编排 └─ 一个 Skill 入口 多个角色 prompt └─ 适合验证流程、短文写作、线性任务 ↓ 当需要上下文隔离但流程仍是线性时 第 2 阶段Subagent 星形 └─ 用 task 同步模式逐个调用 Agent └─ 每个 Agent 有独立上下文但不能互相通信 └─ 适合需要上下文隔离、但流程仍是线性的场景 ↓ 当需要 Agent 之间直接对话和并行执行时 第 3 阶段Agent Team 网状 └─ team_create task 异步模式 send_message 网状通信 └─ 适合复杂协作、多轮退回、并行执行选型决策表判断维度Skill 隐式编排Subagent 星形Agent Team 网状角色数量3-5 个3-7 个5 个角色间是否需要直接通信否否是是否需要退回修改简单退回简单退回多轮退回是否需要并行否否是上下文总长度 30K token不限独立上下文不限独立上下文调试难度低中高搭建成本低只写 prompt中需要编排逻辑高需要团队管理和通信设计推荐场景快速原型、短文、线性流程需要上下文隔离的线性流程复杂协作、长文写作、多角色讨论结论Skill 隐式编排和工具链显式编排的分界线在于团队的创建、通信和生命周期是否被显式控制。两者都建立在 CodeBuddy Team 模式的同一套基础设施之上——独立上下文、点对点通信、并行执行——区别只在编排层前者由 Skill 机制自动驱动后者由team_create/task/send_message/team_delete四个工具显式调用。这四个工具各自解决了一个跨越team_create让团队组建可见task的异步模式让成员派发可控send_message让通信可追踪team_delete让资源清理可确认。但它们的代价也很明确——搭建成本高、调试链路长。所以选型的判断标准不是哪个更先进而是对可控性的需求到了哪一级。线性流程、短文写作、快速验证——Skill 隐式编排完全够用。等遇到多轮退回、并行写作、通信追溯这些硬需求时再沿着Skill → Subagent 星形 → Agent Team 网状的路径渐进迁移。本文由本人构思并把控借助 AI 辅助整理成文仅代表个人观点欢迎交流。