必须区分sub-agent与agent team：前者是单会话内轻量角色封装，后者是多实例并行的重量级团队框架；混用会导致配置失效。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在CodeBuddy中构建可复用的专项智能体协作单元，必须明确区分子代理（Sub-agent）与Agent Team两种机制——前者是轻量级、单会话内派生的角色封装，后者是多实例并行、独立上下文、点对点通信的重量级团队框架。两者创建路径完全不同，混用会导致配置失效或命令不识别。
创建子代理（Sub-agent）
子代理适用于将高频重复角色（如“SQL优化师”“日志分析员”）封装为CLI可调用命令，它运行在主会话上下文中，不启动新实例。
第一步：在项目根目录下创建.codebuddy/agents/sql-optimizer/文件夹。
第二步：在该文件夹中新建agent.md，写入角色定义和能力描述，例如：
name: SQL优化师
description: 分析慢查询，重写JOIN逻辑，添加索引建议
skills:
- 解析EXPLAIN输出
- 识别WHERE条件失效场景
- 输出带hint的优化语句
```
第三步：保存后，在CLI中执行codebuddy agent list，确认sql-optimizer已注册；此后可在任意会话中直接调用codebuddy agent run sql-optimizer --input "SELECT * FROM orders WHERE status = 'pending'"。
【注意：agent.md必须放在以小写字母命名的子目录中，且目录名即为子代理ID；若目录名为SQL-Optimizer或SqlOptimizer，CLI将无法识别】
创建Agent Team（显式工具链编排）
Agent Team用于需要多角色异步协作、共享任务列表、独立上下文的真实团队场景，必须通过四个核心工具函数显式控制生命周期。
方法一：使用team_create初始化团队容器
CodeBuddy Code CLI 的安装、配置与使用指南。CodeBuddy Code 是腾讯推出的 AI 驱动 CLI 编程助手，支持自然语言驱动开发。 - 必备触发词：CodeBuddy, codebuddy, AI CLI, Tencent AI coding, @tencent-ai/codebuddy-code, terminal AI assistant - 适用场景：安装 CodeBuddy CLI、配置 CodeBuddy、使用 CodeBuddy 命令、排查 CodeBuddy 问题
在CodeBuddy CLI中执行：codebuddy team create --name article-team --members scout,architect,writer,reviewer,polisher。这一步会生成一个具备独立消息信箱和任务队列的团队实例，而非加载Skill文件。
方法二：逐个派发成员任务
执行codebuddy task start --team article-team --member scout --prompt "调研近期AI编程工具评测趋势，输出3个关键结论"。每个task start调用都会启动一个独立CodeBuddy实例，该实例只加载对应成员的prompt，不读取其他角色文件。
方法三：显式触发成员间通信
当reviewer完成初审后，需退回writer修改，此时必须用send_message工具而非在prompt里写“请找writer沟通”——执行：codebuddy send_message --team article-team --from reviewer --to writer --content "第2段技术描述不准确，请依据2026年Q2 Benchmark数据重写"。这条消息会进入writer的私有信箱，触发其自动响应。
方法四：显式终止团队
全部任务完成后，必须执行codebuddy team delete --name article-team释放资源。不调用此命令，团队实例将持续占用内存且无法被新同名团队覆盖。
