# 使用智能体团队
> 用一支有负责人、有分工的常驻智能体团队完成一次任务，并理解它背后的委派与共享机制。
Canonical page: /product/agent-teams
团队是一组常驻成员，不是一次性的临时助手
你只对负责人说话，分工由它来安排
成员之间共享结果，不共享彼此的执行过程
一次普通会话里只有一个 Agent：它自己规划、自己动手、自己检查。任务一旦需要「先设计、再实现、最后有人挑刺」，同一个 Agent 既当作者又当审稿人，往往看不出自己的问题。
**智能体团队**把这件事拆给多个成员：每个成员是一个独立的 Agent，有自己的职责、自己的能力开关和自己的私有会话；其中一位是**负责人**，它是你唯一的对话入口，负责拆解目标、把每一步派给合适的成员、验收结果，并对最终交付负责。
## 团队和子代理不是一回事 [#团队和子代理不是一回事]
Vetta 里有两种「多 Agent」，容易混淆，但边界很清楚：
| | 团队成员 | 子代理（Subagent） |
| ---- | ------------------- | -------------------------- |
| 生命周期 | 常驻。跨回合、跨会话存在，有自己的历史 | 临时。由某个 Agent 在一次任务里创建，用完即弃 |
| 可见性 | 出现在团队名册里，你能点开它的独立会话 | 是发起者的私有助手，不进入团队名册 |
| 归属 | 可以持有团队任务，并以成员身份公开发言 | 不能持有团队任务，也不能作为成员发言 |
| 工具 | 团队协作工具（委派、等待、公开消息…） | 由发起者自己调度 |
因此团队成员**不能**用子代理工具去调度另一个成员：这类工具在团队成员的运行时里被直接摘掉，避免把「团队任务的归属」偷偷转移出去。
## 什么时候用团队 [#什么时候用团队]
工作天然分阶段：先设计、再实现、最后审查。
需要一个独立视角挑错，而不是作者自评。
同一批材料要产出多个角度的结论，再合并成一份交付。
目标单一，一两轮就能做完。
你要边看边改、频繁介入细节。
任务本身没有可以并行或需要交接的部分。
## 智能体与团队：默认给了什么 [#智能体与团队默认给了什么]
入口是侧栏 **智能体**（Agents）。上半部分是**团队**，下半部分是**所有智能体**——团队由智能体编组而成，同一个智能体可以同时在多支团队里任职。
团队卡片显示成员头像与人数，点击选定后可发起会话或进入团队设置；智能体卡片点开就是它的档案。
首次安装会带来 8 个智能体，对应 8 种角色蓝图：
| 智能体 | 角色 | 它负责什么 |
| ----------- | --- | ----------------------- |
| Master | 主控 | 拆解目标、分派任务、验收结果并最终交付 |
| Researcher | 检索员 | 搜集事实、文档、竞品与外部素材并核实来源 |
| Architect | 策划师 | 产出技术架构、接口契约，或文档与 PRD 大纲 |
| Executor | 执行员 | 生产核心资产：代码、成稿或完整分析 |
| Auditor | 审计员 | 红队视角挑错：正确性、安全、边界与无依据的断言 |
| Optimizer | 调优员 | 打磨已完成的成果：性能、可维护性、渠道口吻 |
| Synthesizer | 交付员 | 把多方成果合并成一份一致的报告或交付包 |
| Translator | 转化员 | 跨语言本地化，把技术细节转成业务语言 |
以及 4 支预置团队，每支都是「1 位 Master + 3 位专家」的固定流水线：
| 团队 | 阵容 | 流程 |
| ---------------- | ------------------------------------------- | -------------------------------- |
| Dev Team | Master · Architect · Executor · Auditor | 先出设计与契约，再实现自测，最后审查；有阻塞缺陷就回到实现或设计 |
| Deep Research | Master · Researcher · Auditor · Synthesizer | 把问题拆成多个角度并行取证，剔除无依据的结论，再合成结构化报告 |
| Growth & Content | Master · Researcher · Executor · Optimizer | 先定角度和素材，写一份母稿，再按渠道产出变体 |
| Biz Strategy | Master · Architect · Auditor · Synthesizer | 搭出 PRD 与商业模型，审计致命缺陷，通过后打包成可汇报的方案 |
流程不是写死在代码里的，而是写在这支团队 Master 的**团队任务书**里（见下文「配置团队」）。所以改流程就是改一段文字，不需要等版本更新。
预置内容在首次安装时被物化成普通的团队文件，之后和你自己创建的团队完全一样：可以改名、改职责、增删成员，也可以整支删掉——删掉后不会被重新注入。
## 发起一次团队协作 [#发起一次团队协作]
### 选定团队 [#选定团队]
在**新建会话**页，用输入框上的选择器**指定一个团队或单个智能体**；也可以在智能体页选中团队卡片后点 **发起该团队会话**。选单个智能体是普通会话，只是换了人设；选团队才会进入团队协作。
### 确定工作空间 [#确定工作空间]
不指定项目时，这次会话会拿到一块**新工作空间**（属于它自己的目录）；指定项目则直接在项目目录里工作。工作空间在会话创建时固化，协调与全部成员共用同一个目录，之后不会因为项目列表变化而改道。
### 描述任务并发送 [#描述任务并发送]
直接写目标即可，**不指定成员时由负责人接手**。要点名某位成员，用输入框左下角的 `@`。模型、推理档位和执行模式都属于这个团队会话，成员在排队时捕获当前设置。
主时间线只显示公开进展：负责人的计划、每次
team_delegate_task
委派，以及各成员完成后的结论。
## 看懂并介入这条时间线 [#看懂并介入这条时间线]
| 界面元素 | 含义 |
| ----------------------- | ----------------------------------------------- |
| 顶部成员条 | 本次会话的名册；负责人带皇冠标记。点任一成员进入**它的独立会话**，看它自己那条完整执行记录 |
| 成员卡片与状态 | 等待开始 / 正在思考 / 正在调用工具 / 已完成 / 处理失败，对应该成员当前的任务状态 |
| `team_delegate_task` 步骤 | 负责人把一项有边界的目标交给某位成员，此刻任务才真正开始排队 |
| 齿轮图标 | 进入团队设置：成员、负责人、任务书与能力 |
你随时可以在中途再发一条消息补充要求；要把话说给特定的人，就 `@` 它。团队会话按会话隔离草稿、附件、输入历史与模型配置，因此同一支团队可以同时有多个互不干扰的会话，它们都出现在侧栏的对话列表里，行首是成员的叠放头像。
## 原理：委派、等待与验收 [#原理委派等待与验收]
团队协作不是把一句提示词丢给几个模型各说一遍，而是一组**持久任务**在成员之间流转。负责人手里有一套团队工具，界面上看到的每个步骤都对应其中一次调用：
| 工具 | 作用 | 谁能用 |
| ---------------------------------------- | ------------------------------------------- | ------------ |
| `team_delegate_task` | 把一项有边界的目标交给某位成员，**立刻**返回任务 ID，不等它做完 | 仅负责人 |
| `team_wait_tasks` | 等待最多 8 项任务出现状态变化，可设超时 | 任务相关方 |
| `team_get_task` | 读某项任务的当前状态、等待原因与已发布结果 | 任务相关方 |
| `team_continue_task` / `team_retry_task` | 让中断或失败的任务在原有成员会话里续跑或重试，任务 ID 不变 | 负责人或该任务的承接成员 |
| `team_cancel_task` | 取消派给他人的一项任务 | 仅负责人 |
| `team_send_message` | 向若干成员公开发消息：`inform` 只是知会，`question` 才要求对方回应 | 全体成员 |
| `team_list_members` | 读当前名册：职责、可用状态与生效能力 | 全体成员 |
| `team_read_shared_history` | 按策略读取公开历史原文 | 全体成员 |
这套工具背后有三条硬约束，它们解释了你在界面上看到的大部分行为。
### 派发是异步的，所以能并行 [#派发是异步的所以能并行]
`team_delegate_task` 在任务**被受理**时就返回，因此负责人可以先把互相独立的任务一次性派出去，再统一等待。每位成员拥有一条自己的执行车道：不同成员真正并行，同一成员的多项任务按顺序来。
这也是为什么等待有边界：`team_wait_tasks` 超时只是「这段时间内没有新变化」，**既不代表失败，也不会取消任务**。任务完成时会有一条完成通知主动唤醒发起方，所以负责人不需要空转轮询。
系统还会拒绝**环形等待**：如果 A 正在等 B，B 就不能反过来等 A，否则两边都会永远停住。
### 归属不会被偷偷转移 [#归属不会被偷偷转移]
默认编排策略是「负责人分派」：只有负责人能委派和取消任务，成员只能推进自己手上的那一项。成员的角色提示词里也写明了同一条纪律——信息不足时要么问、要么回报负责人，而不是把任务转手给别人。加上子代理工具在成员运行时里被摘除，一项任务的责任人始终是明确的。
### 失败被分类，而不是一律重试 [#失败被分类而不是一律重试]
任务状态是持久的（排队 / 执行中 / 等待 / 需要处理 / 已完成 / 失败 / 已取消），并且**只有拿到一条已发布的结果消息才能进入「已完成」**——这保证了「完成」在时间线上一定看得到东西。
失败则按原因分类，决定接下来能做什么：
| 原因 | 处理方式 |
| --------- | ------------------------------ |
| 网络波动、限流 | 自动重试 |
| 鉴权失效、余额不足 | 等外部条件变化；你在设置里修好之后，受影响的任务会被唤醒重试 |
| 上下文超长 | 需要人工介入调整 |
| 请求本身非法 | 不重试 |
所以看到某个成员「处理失败」时，先看它属于哪一类：反复重试一个余额不足的任务不会有任何进展。
## 原理：共享结果，不共享过程 [#原理共享结果不共享过程]
一个团队会话里其实有 N+1 条对话：一条**公开的协调对话**，加上每位成员各自的**私有对话**。你在主时间线看到的就是公开那条；点进成员会话看到的是它的私有那条。
成员私有对话
推理、工具调用、失败重试
→
公开协调对话
用户消息 + 成员发布的结论
→
其他成员的上下文
按策略投影的公开记录
默认上下文策略只投影公开内容，这意味着：
* 成员之间**读不到**彼此的思考过程、工具调用正文和私有会话文件；能看到的只有对方公开发布的结论。
* 每位成员有自己的投递游标，同一条公开记录不会被重复塞给它，它自己刚发布的内容也不会再投回给自己。
* 公开历史变长时会被压缩成共享检查点（摘要），全队引用同一份；某位成员觉得摘要不够用时，可以用 `team_read_shared_history` 分页读取被摘要的原文。读回来的内容被当作**引用的对话数据**，不是可以执行的指令。
这条边界是刻意设计的：让每位成员用干净的上下文做自己的判断，而不是把四份完整执行记录互相灌满。代价是——**没有公开出来的东西，队友就不知道**。所以当你希望某个结论影响后续步骤时，让它成为一条公开结论，而不是埋在某个成员的中间过程里。
### 哪些信息是全队公开的 [#哪些信息是全队公开的]
| 内容 | 可见范围 |
| ---------------------- | ------------------ |
| 你发给团队的消息 | 全队 |
| 成员发布的最终结论 | 全队 |
| 成员的**团队内职责**（任务书里的一句话） | 全队名册，负责人据此分派 |
| 成员的**团队内补充指令** | 只有它自己 |
| 成员的推理、工具调用、私有历史 | 只有它自己（你可以点进它的会话查看） |
另外，事件 ID 由会话、请求、成员等稳定字段派生，同一个请求重复提交不会产生重复的公开消息或重复执行——这也是断线重连后时间线不会翻倍的原因。
## 配置团队：任务书、能力与负责人 [#配置团队任务书能力与负责人]
有两个层次可以调：**智能体本身**（在智能体页点开它的档案），和**它在某支团队里的表现**（在团队设置里编辑）。
档案分三块：基本信息（头像、名称、职责说明）、系统提示词、能力。能力开关只影响这个智能体，不会安装或卸载全局能力。
### 智能体档案 [#智能体档案]
| 字段 | 说明 |
| ----- | ---------------------------------------------------- |
| 职责说明 | 一句话，会进入全队名册，是负责人分派的依据 |
| 系统提示词 | 覆盖角色蓝图自带的提示词；留空则用蓝图默认 |
| 能力 | 该智能体可用的技能、场景、MCP 与插件。默认继承**全部**全局可用能力，动过任一开关后变成自定义集合 |
一个智能体被多支团队引用时，保存会先列出受影响的团队让你确认；确认后这些团队的**后续回合**使用新配置。
### 团队设置：成员与任务书 [#团队设置成员与任务书]
齿轮进入团队设置，可以增删成员、更换负责人，并为每位成员写一份**团队任务书**：
| 任务书字段 | 作用 | 谁看得到 |
| ------- | ------------------ | ----- |
| 团队内职责 | 覆盖档案里的职责说明，只在本团队生效 | 全队名册 |
| 团队内补充指令 | 追加在它原有人设之后的团队内交待 | 只有它自己 |
任务书是**增量**：字段留空就回到智能体档案里的设定，也不会影响它在其他团队里的表现。它追加在本体人设与角色协作纪律之后，不替换它们——所以不必在任务书里重写「要向负责人回报」这类规则。
预置团队的固定流水线正是用这个机制实现的：流程写在 Master 的团队内补充指令里。想换流程，改这段文字即可。
添加成员时还要选绑定方式：
* **跟随智能体库更新**（引用）：智能体档案改了，这支团队跟着变。默认选它。
* **仅用于此团队**（复制）：复制一份团队私有的档案，之后与库里的原版互不影响。
### 改动什么时候生效 [#改动什么时候生效]
成员运行时按「档案修订 + 任务书指纹」判断是否需要重建：动了档案或任务书，**下一回合**生效，历史记录保留；只改团队名称、描述这类无关字段，不会牵连正在进行的成员会话。
## 会话、工作空间与文件 [#会话工作空间与文件]
### 一支团队，多个会话 [#一支团队多个会话]
团队是配置，会话是一次具体的工作。同一支团队可以同时开多个会话，各自有独立的工作空间、草稿、附件、模型设置与历史，互不干扰。
工作空间在创建会话时就固定下来：
| 创建时的选择 | 工作目录 |
| ------ | ---------------------------------------------------------- |
| 不指定项目 | 这次会话独占的新目录（`VETTA_HOME/agent-teams/session-workspaces/` 下） |
| 指定项目 | 该项目目录 |
协调运行时和所有成员共用这一个目录，因此成员写出的文件互相看得见——**文件是它们真正的共享工作台**，而消息只传结论。
团队会话的底层存储与普通对话是同一套格式，但会被明确标记归属：它们不会混进普通对话列表和搜索结果，只以团队会话的身份出现在侧栏。活动面板对团队只开放语义明确的**文件**与**浏览器**页签。
### 团队配置就是一组文件 [#团队配置就是一组文件]
所有团队与智能体都落在 `VETTA_HOME/agent-teams/`（生产环境默认 `~/.vetta`）：
结构化元数据（能力选择、成员索引、策略引用）在 `*.json` 里，长文本（职责说明、系统提示词、成员任务书）是独立的 Markdown 文件——可以 diff、可以进版本管理、可以在团队之间复制。目录名由可读名称加不可变 ID 摘要组成，改名不会改目录。
写入使用修订号乐观锁与原子替换：同一份配置被两处同时修改时，后一次保存会失败而不是悄悄覆盖。
## 用好一支团队 [#用好一支团队]
* **把验收标准写进第一句话**。负责人是按你给的目标验收的；「做完发我」和「做完让 Auditor 过一遍，没有阻塞缺陷再交」得到的流程完全不同。
* **让关键结论公开**。队友只看得到公开发布的内容，藏在某个成员中间过程里的判断不会自动传下去。
* **调行为优先改任务书**。只影响这支团队，不会波及同一个智能体在别处的表现。
* **人数不是越多越好**。每多一位成员就多一份模型开销与交接成本；预置团队都是 4 人，通常够用。
* **简单任务别用团队**。一两轮能完成的事，普通会话或单个智能体更快也更便宜。
## 常见问题 [#常见问题]
* **任务一直显示「等待」**：等待不等于失败。先看它是不是在等外部条件（凭证失效、余额不足）——修好之后受影响的任务会被唤醒重试；否则它只是还没轮到或仍在执行。
* **某位成员总是跑偏**：改它在**这支团队**的任务书（团队内职责 + 补充指令），而不是改它的智能体档案，后者会影响引用它的所有团队。
* **改了配置却没变化**：档案与任务书从**下一回合**生效，当前正在跑的回合不受影响。
* **想中途补充要求**：直接在团队会话里发消息；要指定人就用 `@`。
* **删除一个智能体会怎样**：保存前会列出受影响的团队。确认后它会从这些团队移除；如果它是负责人，负责人顺位转交给剩下的成员；如果团队因此一个成员都不剩，这支团队也会被删除。
* **在普通对话列表里找不到团队会话**：团队会话只以团队身份出现在侧栏，不混进普通对话列表和搜索结果。