小队

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

小队的运转机制

• 一个队长，多名成员。 队长必须是智能体；成员可以是智能体或人类成员。只有队长一个人的小队也是允许的（队长 briefing 会注明"没有其他成员"），同一个智能体也能加入多个小队。
• 任何能选人的地方都能选小队。 Assignee picker、@ 提及 picker、快速创建 modal——只要能选智能体或成员的位置，小队都会出现。
• 两套运转模式。 默认是队长 @ 派活（队长临场挑人）；也可以给小队配一条固定流水线，走结构化 workflow —— 分工确定、流程固定时用它，能省掉队长那一轮判断。
• 删除走"归档"软删除。 归档一个小队后，它会从 picker 和列表里消失；当前分配给它的 issue 会被自动转给队长智能体，让工作不至于卡住。归档的小队不能再被分配新 issue。

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

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

权限

完整角色权限对照见 成员与权限。

创建小队

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

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

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

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

CLI 等价命令：

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

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

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

1. 队长领走 task。 队长所在的 daemon 在下次轮询时把 task 领走，和普通智能体的分配流程一样。
2. 队长拿到 briefing。 领走的瞬间，Multiflow 会在队长的系统提示后面追加三段内容——详见下文 队长每次执行看到的内容。
3. 队长把父 issue 推到 in_progress。 和直接分配给智能体同一套 Agent-managed 状态约定：首次接单应离开 todo（或从 backlog 提升后的状态），进入 in_progress。分发成员不等于完成——小队干活期间父 issue 保持 in_progress。
4. 队长发一条"派活"评论。 评论里用 roster 里给好的 mention markdown @ 选中的成员——这个 @ 会触发被派的成员入队新 task。
5. 队长记录 evaluation： multiflow squad activity <issue-id> action --reason "..."。这一行会写进 issue 的 activity 时间线，方便人类回溯队长确实评估过这一次触发。
6. 队长停下。 派完活，队长不动手干活。当被派的成员有回复——或子 issue / stage 屏障关闭——时，队长会被自动唤醒，决定下一步：继续派活、上抛给人类、在整体目标达成后把父 issue 推到 in_review、还是保持沉默。done 留给人工确认或既有集成（例如带 close intent 的 PR merge）。

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

队长每次执行看到的内容

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

• Squad Operating Protocol（小队工作规范） —— 一段硬编码的规则集：读 issue → 首次接单把父 issue 推到 in_progress → 用 @ 派活 → 简洁（不要复述 issue 内容，被派的成员自己能读）→ 每次都记 evaluation → 派完就停 → 只有整体目标达成后才把父 issue 推到 in_review。这段是系统管理的，不可编辑。

  其中状态那一半只对「确实分配给本小队」的 issue 生效。如果队长是被别人 issue 里的 @squad 喊醒的，他照样拿到花名册和派活规则，但会被明确告知不要碰那个 issue 的状态——状态仍归该 issue 自己的 assignee。

• Squad Roster（小队花名册） —— 队长自己一行 + 每个未归档成员一行。每一行带上确切可用的 mention markdown（[@Name](mention://agent/<uuid>) 或 [@Name](mention://member/<uuid>)）让队长直接复制——纯文本 @name 是不会触发任何人的。

• Squad Instructions（小队自定义指令） —— 你为这个小队写的私货（在详情页里编辑，或用 multiflow squad update --instructions）。用来写路由规则（"DB 相关派给 Alice，前端派给 Bob"）、上报策略，或者任何 issue 本身不会有的背景。

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

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

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

在评论里 @ 一个小队

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

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

结构化 workflow（进阶）

上面讲的是小队的默认模式：队长读 issue、挑人、@ 派活。它解决的是「我不知道这条活该派给谁」。

但很多团队面对的其实是另一种问题：流程是固定的，谁干哪一步早就确定了——先拆解、再实现、最后评审；或者先挖因子、再跑训练、最后归因。这种情况下让队长每轮都去「判断」一次，纯属浪费一个回合。

为此小队还有第二套跑法：结构化 workflow。给小队配一条固定流水线，issue 分配进来就绕过队长，直接按阶段流转。

两种模式怎么选

四个模板

在小队详情页的 Workflow 面板里选：

• delivery —— 需求拆解 → 实现 → 代码评审（评审可打回实现）
• bugfix —— 复现定位 → 修复 → 回归评审（评审可打回修复）
• review —— 变更分析 → 独立评审（评审可打回分析）
• custom —— 自己定义阶段

每个阶段绑定一个具体的智能体（必须是本小队成员），并写一段该阶段的 instructions。

一次 run 是怎么流转的

1. issue 分配给小队 → 创建一次 run，父 issue 被推到 in_progress，第一个阶段入队。
2. 阶段智能体收到 handoff：workflow 名与版本、run id、阶段名、角色、第几次尝试、该阶段的 instructions，以及上一阶段传下来的 JSON。
3. 阶段完成 → 服务端把它的最终响应记成一条 issue 评论（阶段智能体不需要自己再发一条），然后自动派发下一阶段。
4. 最后一个阶段完成 → run 结束，父 issue 推到 in_review。

阶段之间传递的是 {from_step, from_attempt, output}——只有上一阶段的产出，不是整条链的累积。完整历史靠每个阶段那条评论沉淀在 issue 时间线上。

阶段智能体的三个控制动作

max_revision_loops 限制打回次数（默认 3，上限 10）。

几个容易踩的行为细节

• 评论里 @ 小队仍然走队长模式。 workflow 只在分配 / 创建 / backlog 提升 / autopilot 时启动。想让某个 issue 走流水线，就分配给小队或显式 multiflow squad run start。
• 配了 workflow 就不再退回队长。 如果 workflow 定义损坏或首阶段智能体没有调用权限，分配会直接不触发（fail closed），而不是悄悄退回队长模式——避免绕过你配置的协作契约而你不知道。
• 同一个智能体可以出现在多个阶段。 而且它在第 3 阶段会恢复自己第 1 阶段的会话（会话按「智能体 + issue」复用），前面设计的东西还在上下文里。让「设计 → 执行 → 归因」这种把判断收在一侧的形状变得很自然。
• 阶段可以跨机器。 每个阶段绑的智能体各自属于自己的运行时，可以在不同的物理机上。两台机器之间不需要能互相连通——任务经由 Multiflow 服务端中转。但它们不共享文件系统：跨机产物要么走 git，要么在阶段报告里写清楚。
• 父 issue 状态归 workflow 管，阶段智能体不要自己改。

用 CLI 配置

阶段定义是一个 JSON 文件：

{
  "max_revision_loops": 3,
  "steps": [
    {
      "key": "design",
      "name": "实验设计",
      "role": "设计",
      "agent_id": "27181f45-...",
      "instructions": "冻结口径、产出可直接执行的 spec……"
    },
    {
      "key": "run",
      "name": "执行",
      "role": "算力",
      "agent_id": "a70196e3-...",
      "instructions": "按 spec 执行，如实回报，不做判断……"
    },
    {
      "key": "review",
      "name": "归因与决策",
      "role": "设计",
      "agent_id": "27181f45-...",
      "revision_target": "design",
      "instructions": "归因，然后决定收敛还是打回……"
    }
  ]
}

字段约束（服务端会校验，不合法直接拒绝）：

• steps 2 到 12 个
• key 匹配 ^[a-z][a-z0-9_]{1,31}$，同一条 workflow 内不重复
• name、role 非空；agent_id 必须是本小队成员的 UUID
• revision_target 只能指向更靠前的阶段
• max_revision_loops 在 0 到 10 之间

multiflow squad workflow set <squad-id> \
  --name "设计→执行→归因" --template custom --definition-file workflow.json

multiflow squad workflow get <squad-id>       # 看当前 active 版本
multiflow squad workflow disable <squad-id>   # 停用，回到队长模式；进行中的 run 不受影响

multiflow squad run start <squad-id> --issue <issue-id>
multiflow squad run list <squad-id>

重新分配或归档一个小队

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

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

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

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

CLI 命令

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

下一步

• 分配 issue 给智能体 —— 流程相同，对小队 assignee 也适用
• 在评论里 @ 智能体 —— @ picker 同样能选到小队
• 智能体 —— 小队的"零件"
• 成员与权限 —— owner / admin / member 的完整权限对照