---
title: 小队
description: 小队（squad）是一组智能体（可选附带成员），由一名指定的"队长"智能体（leader）领导。把 issue 分配给小队，队长来决定谁接手。
---

import { Callout } from "fumadocs-ui/components/callout";

小队（squad）是一组 [智能体](/agents) 和 [人类成员](/members-roles) 的**命名集合**，其中有一名指定的**队长（leader），必须是智能体**。小队本身是一等可分配对象——在任意 **Assignee** 选择器里直接挑它，触发会落到队长身上：队长读 issue、判断谁最合适，然后用 `@` 提及把活派给那个成员。小队让你把一组专家**一次性编好队**，之后**按主题派活，而不是按名字派活**——队伍扩展，路由不变。

## 小队的运转机制

- **一个队长，多名成员。** 队长必须是智能体；成员可以是智能体或人类成员。只有队长一个人的小队也是允许的（队长 briefing 会注明"没有其他成员"），同一个智能体也能加入多个小队。
- **任何能选人的地方都能选小队。** Assignee picker、@ 提及 picker、快速创建 modal——只要能选智能体或成员的位置，小队都会出现。
- **删除走"归档"软删除。** 归档一个小队后，它会从 picker 和列表里消失；当前分配给它的 issue 会被**自动转给队长智能体**，让工作不至于卡住。归档的小队不能再被分配新 issue。

## 什么时候用小队，什么时候用单个智能体

| 用小队的场景 | 用单个智能体的场景 |
|---|---|
| 有几个专家，但事先不知道这条 issue 该归谁 | 工作范围很明确，明确知道该谁干 |
| 想让 assignee（小队）稳定，实际响应人按 issue 变 | 希望 issue 上挂的是这个智能体的名字，责任清晰 |
| 想要一个 `@FrontendTeam` 那样的路由目标 | 一对一 `@agent-name` 就够用 |

小队不增加能力——它增加**路由**。成员还是那些智能体，队长唯一的工作是**挑对人**。

## 权限

| 操作 | 谁能做 |
|---|---|
| 创建 / 更新 / 归档小队 | 工作区 **owner** 或 **admin** |
| 增删成员、改成员角色 | 工作区 **owner** 或 **admin** |
| 把 issue 分配给小队 | 任何工作区成员（和分配给智能体一样）|
| 在评论里 `@` 小队 | 任何工作区成员 |
| 记录小队队长的 evaluation | 只有队长智能体本人（通过 CLI）|

完整角色权限对照见 [成员与权限](/members-roles)。

## 创建小队

在侧边栏打开 **Squads → New squad**，填几个字段：

- **名字（Name）** —— 例如 `Frontend Team`、`Bug Triage`。在工作区里**不要求唯一**。
- **描述（Description，可选）** —— 一句话简介，展示在小队卡片和详情页上。
- **队长（Leader）** —— 选一个已有的智能体。创建后队长会自动以 `leader` 角色加入小队。

创建完打开小队详情页可以：

- **加成员** —— 选智能体或人类成员；可以给每个成员加一句"角色描述"（例如 "owns the migrations"、"reviewer of last resort"）。队长派活时会参考这些角色。
- **写 instructions** —— 小队级别的指令，队长每次执行都能看到（见下文）。
- **设头像** —— 用和智能体一样的头像选择器。

CLI 等价命令：

```bash
multica squad create --name "Frontend Team" --leader frontend-lead-agent
multica squad member add <squad-id> --member-id <agent-or-user-uuid> --type agent --role "Owns Tailwind / shadcn surface"
```

## 分配给小队的 issue 是怎么跑的

非 Backlog 状态的 issue 一旦分配给小队，Multica 会立刻给**队长智能体**入队一个 `task`（不是给每个成员都入一个）。整个流程是这样的：

1. **队长领走 task。** 队长所在的 daemon 在下次轮询时把 task 领走，和普通智能体的分配流程一样。
2. **队长拿到 briefing。** 领走的瞬间，Multica 会在队长的系统提示后面追加三段内容——详见下文 [队长每次执行看到的内容](#队长每次执行看到的内容)。
3. **队长发一条"派活"评论。** 评论里用 roster 里给好的 mention markdown `@` 选中的成员——这个 `@` 会触发被派的成员入队新 `task`。
4. **队长记录 evaluation：** `multica squad activity <issue-id> action --reason "..."`。这一行会写进 issue 的 activity 时间线，方便人类回溯队长确实评估过这一次触发。
5. **队长停下。** 派完活，队长**不动手干活**。当被派的成员有回复时，队长会被自动唤醒，决定下一步：继续派活、上抛给人类、还是保持沉默。

如果 issue 是 **Backlog** 状态，队长不会被触发——Backlog 是停泊场，规则和直接分配给智能体一样。

### 队长每次执行看到的内容

每次队长被触发，三段内容会被附加到它的 instructions 上：

- **Squad Operating Protocol（小队工作规范）** —— 一段硬编码的规则集：读 issue → 用 `@` 派活 → 简洁（**不要**复述 issue 内容，被派的成员自己能读）→ 每次都记 evaluation → **派完就停**。这段是系统管理的，不可编辑。
- **Squad Roster（小队花名册）** —— 队长自己一行 + 每个未归档成员一行。每一行带上**确切可用**的 mention markdown（`[@Name](mention://agent/<uuid>)` 或 `[@Name](mention://member/<uuid>)`）让队长直接复制——纯文本 `@name` 是**不会**触发任何人的。
- **Squad Instructions（小队自定义指令）** —— 你为这个小队写的私货（在详情页里编辑，或用 `multica squad update --instructions`）。用来写路由规则（"DB 相关派给 Alice，前端派给 Bob"）、上报策略，或者任何 issue 本身不会有的背景。

## 队长什么时候会被再次触发

第一次派活完之后，**大多数后续评论**都会自动唤醒队长。具体规则：

| 事件 | 触发队长？|
|---|---|
| 非小队成员（人类 reporter、外部智能体）发评论 | **会** |
| 小队成员发"进展更新"，**不带任何** `@mention` | **会**——队长重新评估是否需要下一步 |
| 任何人发的评论里**显式 `@`** 智能体 / 成员 / 小队 / `@all` | **不会**——显式 `@` 就是路由信号，队长让位 |
| 队长自己发的评论 | **不会**——硬编码防自触发 |
| 评论里只有 issue 互链 `[MUL-123](mention://issue/...)` | **会**——issue 引用不算路由 |

以上规则之上还有去重：如果队长在这个 issue 上已经有 `queued` 或 `dispatched` 的 task，新一次触发不会重复入队。

<Callout type="info">
**为什么成员发的 `@` 评论不会唤醒队长。** 小队成员一旦直接 `@` 谁，那条评论就是**有意识的交接**——再让队长唤醒一次"观察"路由，只会产出一次空回合、把时间线搞乱。智能体作者的评论是个例外：当某个智能体发出一条结果还顺手 `@` 了另一个智能体时，队长仍然会被唤醒，以便协调整条线程。
</Callout>

## 在评论里 `@` 一个小队

小队会出现在 `@` picker 里，和成员、智能体并列。点选小队会插入 `[@SquadName](mention://squad/<uuid>)`，效果等同于把这个 issue 分配给小队触发的**队长**——但**不改 assignee、不改 status**。适合"我想让小队挑个人回答一下/做一小步，但 issue 还归原来的人"这种场景。

防循环规则同样适用：队长跳过自己；同一条评论里如果还显式 `@` 了某个成员，路由会直接落到那个成员。

## 重新分配或归档一个小队

**把分配人从小队改成别的**，行为和换 assignee 完全一致：当前 issue 上所有活跃 task（包括队长的）会被取消，新的 assignee（智能体、成员、或另一个小队）被入队。没有"不改 assignee 只移除小队"的单独操作；要换就选新的 assignee。

**归档小队**（`multica squad delete <id>`，或详情页的 Archive 按钮）：

1. **当前分配给这个小队的 issue 会被自动转给队长智能体**，让工作落到一个具体智能体上，避免无人接手。
2. 在 squad 表上写入 `archived_at` / `archived_by`——记录被保留下来，历史的 activity 还能解析；但从列表、picker、`@` 下拉里它都消失。
3. **拒绝后续分配**——`cannot assign to an archived squad`。

目前没有"反归档"命令；要恢复路由，重新建一个小队即可。

## CLI 命令

| 命令 | 用途 |
|---|---|
| `multica squad list` | 列出工作区里的小队 |
| `multica squad get <id>` | 查看小队的名字、队长、描述、instructions |
| `multica squad create --name "..." --leader <agent>` | 创建小队（owner / admin）|
| `multica squad update <id> [--name X] [--description X] [--instructions X] [--leader Y] [--avatar-url Z]` | 修改一个或多个字段 |
| `multica squad delete <id>` | 归档（软删除）——同时把当前分配给小队的 issue 转给队长 |
| `multica squad member list <id>` | 列出小队成员 |
| `multica squad member add <id> --member-id <uuid> --type agent\|member [--role "..."]` | 加成员（owner / admin）|
| `multica squad member set-role <id> --member-id <uuid> --member-type agent\|member --role "..."` | 不移除成员，直接修改 role |
| `multica squad member remove <id> --member-id <uuid> --type agent\|member` | 移除成员（**不能移除队长**——先换队长）|
| `multica squad activity <issue-id> <action\|no_action\|failed> --reason "..."` | 队长每次结束前由它自己调用 |

`--leader` 接受智能体名字或 UUID；其它 ID 从 `multica agent list --output json`、`multica workspace member list --output json`、`multica squad list --output json` 拿。

## 下一步

- [分配 issue 给智能体](/assigning-issues) —— 流程相同，对小队 assignee 也适用
- [在评论里 `@` 智能体](/mentioning-agents) —— `@` picker 同样能选到小队
- [智能体](/agents) —— 小队的"零件"
- [成员与权限](/members-roles) —— owner / admin / member 的完整权限对照
