第 4 章 · SpectrAI 桌面端 v1.0.4多 Agent 协同
SpectrAI 操作手册 v1.0.4 · 桌面端 · 第 4 章
SpectrAI 的差异化在于让多个 AI 同时为你工作，且能分工、复盘、互相纠偏。本章覆盖 Supervisor、Mission、Teams 三套会话内机制，以及跨会话协作与子 Agent 调度池等配套能力。会话里被邀请的「专家席位」是另一种多智能体协作形态，单独见 第 12 章 专家与专家团。
4.1 概述
单个 AI 面对「实现完整 Todo 应用」往往会跑偏：上下文爆掉、前端做完忘后端、代码没人审。SpectrAI 把会话变成 多智能体编队——主 Agent 拆任务，子 Agent 并行执行，角色复审。三套核心机制：
| 机制 | 适用场景 | 自动规划 | 用户介入 |
|---|---|---|---|
| Supervisor | 需求清楚，希望主 Agent 边做边拆（Pro 模式） | 即时拆解 | 低 |
| Mission（组队任务） | 需求复杂，先看完整方案再执行 | 四阶段编排 | 中 |
| Agent Teams | 已有稳定角色模板，重复同类任务 | 按模板分工 | 中 |
除三套机制外，本章还讲 子 Agent 调度池（限定子 Agent 可用的 Provider 与模型）、会话状态条（子 Agent 进度与跳转）与 跨会话协作（一个会话给另一个会话发消息、监控其进度）。此外，普通会话本身即可按需自主派子 Agent，Supervisor 不再是「让会话能派活」的前置门槛，而是可选的「专职编排」Pro 模式。
💡 提示原先负责「守护会话健康」的 Butler 已升级为桌面助手「小黑」——从会话巡检者变成可直接吩咐、替你操作软件的整页助手，详见 第 14 章 桌面助手。
4.2 核心概念
- 主 Agent / 子 Agent：主 Agent 是用户直接对话的会话；主 Agent 派发出来的独立子会话就是子 Agent，带独立 Worktree 与 Provider。
- 子 Agent 调度池：限定 Supervisor / Mission 可派遣的 Provider 与模型的白名单，全局生效（详见 §4.6）。
- 角色 / 团队：角色（现称专家）是一份预设（系统提示词 + 默认 Provider + 适用阶段 + 绑定技能与 MCP）；团队是一组角色的组合。角色与专家团的管理见 第 12 章。
- Mission 阶段：Mission 把任务拆成 4 个阶段（头脑风暴 → 团队设计 → 阶段规划 → 准备就绪），每阶段都有确认门。
- 5 维度评分：
completeness（完整性）、accuracy（准确性）、codeQuality（代码质量）、adherence（规范遵循）、innovation（创新性），合格线 7.0/10。 - 漂移检测：评估器比对产物与原始目标，输出 7 类漂移标签（详见 §4.5.5）。
- 跨会话协作：一个会话可给另一个会话发消息、监控其进度，并在侧栏展示监控绑定关系（详见 §4.8）。
4.3 在 Supervisor 模式下让 AI 自动分工
Supervisor 模式适合「我有一个大目标，希望主 Agent 专职调度、不亲自改代码」的场景。它是一档 Pro 会话模式，可在会话内的「会话模式」选择器里从「通用」就地热切到「Supervisor」。普通会话本身也能按需自主派子 Agent，Supervisor 只是把主 Agent 收敛为「专注编排、不亲自改代码」的编排者。每个子 Agent 都跑在自己的 Worktree 上，结果通过系统事件回流。
4.3.1 操作步骤
- 新建会话。点左侧栏新建对话入口（详见第 3 章 §3.2）。
- 切换会话模式为 Supervisor。在会话工具栏的「会话模式」选择器里，从「通用」切到「Supervisor」（芯片显示为青色）。选择器悬停说明：「专职编排：AI 专注调度子 Agent、不亲自改代码（Pro）」。「组队任务」档会跳转到新建入口，不在此就地切换。
- 确认调度池与 Worktree。在「更多」菜单的「子 Agent 调度池」里勾选允许派遣的 Provider（详见 §4.6），保持「启用 Worktree」开启。
- 输入大目标，点发送。例如：「实现一个支持本地存储和导入导出的 Todo 应用」。
- 观察会话状态条。会话顶部出现可点击的会话状态条，展示子 Agent 进度：每个子 Agent 一项，含状态点、子 Agent 名与状态徽章。子 Agent 状态文案：准备中、运行中、已完成、失败、已取消。点状态条可原地下拉展开子 Agent 列表，点某个子 Agent 项跳转到它的子会话；空间不足时状态条折叠为胶囊态。详见 §4.7。
- 等待事件驱动回报。子 Agent 完成后主对话自动收到系统完成通知附带产物摘要，主 Agent 据此推进，用户此期间无需操作。
- 审阅并合并 Worktree。所有子 Agent 完成后，主 Agent 列出每个子 Worktree 分支名请求合并，具体见第 2 章 §2.5。
4.3.2 中途追加约束的正确做法
这是 SpectrAI 的一条硬规则：
**禁止在子 Agent 处于 running / pending / waiting_input 时，调用
send_to_agent追加指令。**
如果你在子 Agent 跑到一半时想新增约束（例如「前端要用 Tailwind」），正确做法是：
- 等子 Agent 进入终态（完成 / 失败 / 已取消）。
- 把完整修订需求告诉主 Agent，由主 Agent 重新派发新的子 Agent。
主 Agent 的系统提示里对此做了硬约束：拒绝运行期下发 send_to_agent，并回报错误码 supervisor_follow_up_forbidden。
4.3.3 并行调度规则
子 Agent 的 running / pending / waiting_input 状态 不构成调度锁。只要写入范围不冲突，主 Agent 可同时派发多个子 Agent，各自跑在独立 Worktree。子 Agent 能用哪些 Provider 与模型由「子 Agent 调度池」统一约束（详见 §4.6）。
4.4 用 Mission 完成四阶段规划
Mission 模式（会话模式选择器里显示为「组队任务」）适合复杂、长链路、希望「先看完方案再启动」的任务：先出分析报告，你确认后再组建团队执行。它把整个交付过程切成 4 个阶段，每个阶段都是一道用户确认门。Mission 会话是独立形态，从新建入口创建，不在已有会话里就地切换。
4.4.1 四个阶段
| 阶段 | 内部状态 | UI 文案 | 你能做什么 |
|---|---|---|---|
| 1 头脑风暴 | brainstormed | 头脑风暴 | AI 出方案、列假设、识别风险 |
| 2 团队设计 | team_designed | 团队设计 | AI 推荐角色组合 + Provider，可改 |
| 3 阶段规划 | phases_planned | 阶段规划 | AI 细化子任务 DAG |
| 4 准备就绪 | confirmed → running | 准备就绪 | 启动并行执行 + 自动评估 |
「执行」「评估」合并到「准备就绪」之后的运行期，所以向导上是 4 步。
4.4.2 操作步骤
- 新建组队任务会话。在会话模式选择器点「组队任务」，会跳转到新建入口创建 Mission 会话；也可在新建对话入口直接选「组队任务」。
- 填写目标和约束。目标（goal）：至少 1 句话；约束（constraints）：可选，每条一行，如「必须用 React」。
- 选择自动模式：
manual（每阶段确认）、supervised（AI 自审但仍弹窗）、full（仅阶段失败才弹）。 - 阶段 1 头脑风暴。AI 输出方案后，stepper 第一个圆点变实心，下方列出方案要点、假设、风险。底部「打回重做」/「确认并进入团队设计」。
- 阶段 2 团队设计。AI 推荐角色组（如产品经理 + 架构师 + 前端 + 后端 + QA）。卡片显示中文名、推荐 Provider（colored 徽章：claude-code 琥珀、codex 翠绿、gemini-cli 蓝、opencode 紫）、能力标签。内置 18 角色覆盖分析/设计/实现/验证/文档五大类，点笔形图标可改 Provider。
- 阶段 3 阶段规划。AI 拆 DAG（React Flow 渲染），节点标注名称、复杂度、工作量、分配角色；箭头表依赖；无依赖节点自动并行。颜色：紫=头脑风暴、青=规划、淡黄=待确认、青柠=执行中、翠绿=完成。
- 阶段 4 准备就绪。点「启动 Mission」，所有节点进入执行池。底部「Mission 控制台」显示进度条与暂停 / 恢复 / 跳过 / 终止。
- 运行期评估。节点完成后自动触发 5 维度评分（§4.5.4）和漂移检测（§4.5.5）。低于阈值（默认 7.0）的进入「待人工复核」。
4.4.3 关于「返工」与「跳过」
- 打回（仅阶段 1～3）：在确认门点「打回重做」，AI 基于反馈重新跑当前阶段，先前阶段产物保留。
- 跳过当前阶段（运行期）：把该阶段标为
skipped，但不回退已完成的阶段。跳过的阶段留下(用户跳过此阶段)占位记录，依赖它的下游节点可能因上游缺失而失败。
没有「整段回退」按钮。若在阶段 3 后才发现阶段 1 有问题，建议终止并新开 Mission——先前产物保存在
docs/missions/<missionId>/可复用。
4.5 组建 Agent Teams 让多 AI 协作
Teams 适合「反复做同一类任务」的场景（如每周一次代码审查）。配置好团队后，每次只需提交任务到队列，Agent 自动认领、协作、互评。当前团队协作采用 SQUAD-first 模式：一个 Leader 带一队成员，Leader 负责拆活、直投消息、汇总评审，成员各自在私有 Worktree 里干活；切轮换 Leader 时会自动注入团队基线包，团队还共享一层知识（team_knowledge），减少重复探索与返工。
4.5.1 进入 Teams 看板
- 最左侧 Activity Bar 点「Agent Teams」图标（第三栏）。
- 主区域切换为 Teams 看板，顶部 Tab：成员 / 任务 / 消息 / 模板 / 复审池 / 驾驶舱。
4.5.2 新建团队
- 右上角点「+ 新建团队」。
- 选择模板（内置 8 个）：
| 模板 | 角色组成 | 适用 |
|---|---|---|
| 全栈功能开发小队 | 产品经理 → 架构师 → 前端 → 后端 → QA | 端到端交付 |
| Bug 定位修复小队 | 需求分析 → 后端 → 前端 → 自动化测试 → 代码审查 | 故障修复 |
| 代码审查小队 | 代码审查 → 安全审查 → 性能优化 | PR 复审 |
| 产品方案打磨小队 | 产品经理 → 需求分析 → UX → 架构师 | 立项前 |
| UI/UX 设计小队 | 产品经理 → UX → 前端 → QA | 界面改版 |
| 文档与教程小队 | 技术文档 → 教程编写 → 代码审查 | 文档输出 |
| AI 视频创作小队 | 视频脚本 → 提示词 → 社交文案 → QA | 内容生产 |
| 工作流自动化小队 | 工作流设计 → Agent 编排 → MCP → 后端 | 自动化搭建 |
- 进入编辑视图后，每个角色可单独修改 Provider / 模型 / 系统提示词 / 工具范围。
4.5.3 提交任务并观察协作
- 「任务」Tab 点「+ 新任务」，填写标题、描述、目标锚点（用于漂移检测）。
- 任务进「待领取」队列，Agent 按角色自动认领，无冲突时多角色并行。
- 「消息」Tab 显示 Agent 间消息流，含发送方、接收方、ACK 状态、合并标记。支持 消息直投（直接投给指定成员）与 插队（把消息提到队首优先处理）。
- 任务流转：
待领取 → 进行中 → 待复审 → 已完成 / 已驳回。进行中的任务可 重新投递或改派 给其他成员；成员静默超时后会先再确认，而不是直接判定卡死。 - 「复审池」Tab 汇总待评审产物，评审结论与 5 维度评分卡在此展示；团队面板顶部的干预对话框可在运行期给团队下达指令、查看进度或广播。
4.5.4 5 维度评分雷达
任务完成后复审池自动打分，结果在「评估详情」抽屉里：
| 维度 | 字段名 | 含义 | 权重 |
|---|---|---|---|
| 完整性 | completeness | 是否完整满足目标与交付要求 | 30% |
| 准确性 | accuracy | 实现是否正确、结论是否可靠 | 25% |
| 代码质量 | codeQuality | 代码可维护性与健壮性 | 20% |
| 规范遵循 | adherence | 是否遵循项目规范与风格 | 15% |
| 创新性 | innovation | 是否具备合理优化或创新点 | 10% |
各维度评分 0～10，加权得综合分，默认合格线 7.0。低于阈值的任务进入「驳回 / 重做」，可自动重试最多 2 轮。
4.5.5 漂移检测
评估器比对目标锚点与产物，输出最多 7 类漂移标签：
| 字段名 | 中文标签 | 严重度 | 触发 |
|---|---|---|---|
goal_changed | 目标偏移 | critical | 产物与原始目标偏离明显 |
deliverable_missing | 交付缺失 | major | 缺少声明的交付物 |
scope_expanded | 范围膨胀 | major | 做了目标外的事 |
scope_reduced | 范围收缩 | minor | 做的事少于目标 |
quality_degraded | 质量退化 | major | 引入回归或降低稳定性 |
style_inconsistent | 风格偏移 | minor | 风格与项目规范不一致 |
over_engineering | 过度设计 | minor | 引入不必要的复杂度 |
漂移标签以彩色徽章显示在评估抽屉顶部。critical（goal_changed）强制打回，不能自动放行。
4.6 用子 Agent 调度池限定派遣范围
子 Agent 调度池是一份 全局白名单，限定 Supervisor / Mission 能派遣给子 Agent 的 Provider 与模型。避免主 Agent 把子任务误派到已关闭或不合适的模型上。
4.6.1 从设置页配置
- 打开「设置 → AI 模型」，找到「子 Agent 调度池」分区。
- 勾选允许派遣的 Provider。不勾选某个 Provider 下的具体模型 = 该 Provider 全部模型都可用。
- Provider 勾选后其模型 chips 默认折叠，点开可展开逐个勾选，或用「全选模型」一次选中。
- 点「保存并应用到所有会话」。调度池 热更新：保存后对所有会话（含已存在的活跃会话）与之后新建的会话统一生效，无需重启。
4.6.2 从会话内配置
在会话工具栏点「更多」→「子 Agent 调度池」，弹出同一套编辑器；它与设置页共用全局池，改动同样对所有会话生效。
⚠️ 注意调度池为空（一个 Provider 都没勾）时无法保存，会提示「至少选择一个 Provider」；请确保至少放行一个可用 Provider，否则子 Agent 无从派遣。
4.7 会话状态条与子智能体名单
会话里的多智能体活动通过两处 UI 呈现：顶部的会话状态条，与对话流中的子智能体名单。
4.7.1 会话状态条
- 状态条位于会话顶部，整体可点击。展示当前会话的子 Agent 数量与聚合状态。
- 点状态条原地下拉，展开子 Agent 列表；点某个子 Agent 项跳转到它的子会话。
- 空间不足时状态条折叠为胶囊态；在组队任务 / 团队会话里，顶部还有团队驾驶舱条与「返回父会话」入口，便于在父会话与子会话间来回。
4.7.2 对话流中的子智能体名单
- 主 Agent 派子 Agent 时，对话流里会按发生顺序露出子智能体名单卡片，含名字、身份与指令摘要，点「打开子会话」跳转。
- 名单默认收起只留一行摘要，展开后按创建轮次分组，仅最新一组默认展开。
- 身份分栏：专家席位派发的走「专家」身份（紫色），团队成员标「团队」，其余普通子智能体标「智能体」，三类身份在名单里区分展示。
4.7.3 父会话的子 Agent 文件改动汇总条
父会话的对话区会聚合展示子 Agent 的文件改动汇总条：一处集中列出本轮 / 本会话被子 Agent 改动的文件，提供「撤销」本轮改动与「审核」本会话改动两个动作，并可定位到对应的产物锚点。文件改动的审阅、Diff 与撤销细节见 第 6 章 终端与文件。
4.8 跨会话协作
多个会话之间可以互相发消息、互相监控，把独立会话串成一张协作网。
4.8.1 让一个会话给另一个会话发消息
跨会话发消息与监控主要通过 Agent 工具完成，没有独立的一键按钮。在会话里让 AI 调用即可：
- 让 AI「给某个会话发一条消息」，它会把消息以
cross_session来源投递到目标会话；投递是可信可审计的，目标会话能看到消息来源标记。 - 让 AI「监控某个会话的进度」，它会订阅目标会话的进度事件（默认不含正文，需要看对方在说什么要显式要求订阅消息正文）。
4.8.2 在侧栏查看与管理监控关系
- 会话之间建立监控后，侧栏会话项上出现监控徽标：绿色「主导」表示该会话在监控别人，蓝色「被监控」表示它被别的会话监控。
- 点绿色「主导」徽标弹出浮层，列出正在监控的目标会话及其状态与最新活动预览；点目标名跳转到该会话。
- 浮层底部可 手动绑定 新的会话进行监控；对已绑定但未订阅正文的目标，点「订阅」升级为订阅正文；点「取消」解除监控。
💡 提示手动绑定与徽标操作默认订阅正文（你显式操作时通常想看对方在说什么）；AI 自己发起的监控默认只看进度、不含正文，两者有意分开。
4.9 让小黑守护你的会话
原先负责「守护会话健康、外围巡检所有会话」的 Butler，已升级为桌面助手「小黑」——从会话巡检者变成可直接吩咐、替你操作软件的整页助手。它仍能盯会话、在你不在时代为处理，但入口与玩法已整体迁移。启用、灵敏度、决策历史、语音与日报等完整说明见 第 14 章 桌面助手。
💡 提示想让小黑在 Mission 或团队跑长任务时兜底监督，先在第 14 章开启并配置好小黑，再叠加到本章的机制上使用。
4.10 详细配置一览
本章涉及的全部设置，路径从「设置」根菜单开始。
| 设置项 | 路径 | 默认 | 说明 |
|---|---|---|---|
| 会话模式 | 会话工具栏 → 会话模式 | 通用 | 通用 / Supervisor（Pro）就地切换；组队任务走新建入口 |
| 子 Agent 调度池 · Provider | 设置 → AI 模型 → 子 Agent 调度池 | 全部已启用 Provider | 限定可派遣的 Provider，全局生效 |
| 子 Agent 调度池 · 模型 | 设置 → AI 模型 → 子 Agent 调度池 | 不勾=全模型可用 | 逐个勾选或「全选模型」 |
主 Agent 拒绝 send_to_agent | 系统硬规则 | 启用 | 不可关闭 |
| Mission 默认自动模式 | 组队任务新建入口 | manual | manual/supervised/full |
| Mission 每阶段确认门 | 组队任务新建入口 | 启用 | 关闭等价于 full |
| Mission 阶段错误策略 | 组队任务新建入口 | retry | retry(≤2)/skip/abort |
| Teams 5 维度权重 | Teams → 评分 | 30/25/20/15/10 % | 和需为 100% |
| Teams 合格阈值 | Teams → 评分 | 7.0/10 | 低于则驳回 |
| Teams 漂移检测开关 | Teams → 漂移 | 开 | 关闭不输出标签 |
Butler 相关设置已随桌面助手「小黑」迁移，见 第 14 章 桌面助手。
4.11 常见问题
子 Agent 跑了 10 分钟没动静怎么办
看会话状态条。若还停在「运行中」，点状态条展开、点该子 Agent 项进入子会话查看输出，必要时在子会话里终止。不要 追加 prompt 试图唤醒（§4.3.2）。若已启用小黑，它会在会话卡死时兜底处理（见第 14 章）。
能不能给运行中的子 Agent 追加新约束
不能。主 Agent 会拒绝并返回 supervisor_follow_up_forbidden。等子 Agent 进入终态后，把完整修订需求告诉主 Agent，由它重新派发。
Mission 返工后之前阶段的产物会丢吗
不会。阶段 1～3 的「打回重做」只重跑当前阶段，先前产物保留并喂回 AI；运行期的「跳过当前阶段」也不回退已完成节点，但被跳过的阶段留下占位，依赖它的下游可能因上游缺失而失败。
Teams 的任务谁来认领
任务挂「适用阶段」标签，命中的角色进候选池，按 Provider 可用性、当前负载、最近完成时间排序，由最空闲角色认领，同一任务不会被两角色同时认领。
子 Agent 被派到了已关闭的模型怎么办
在「子 Agent 调度池」里只勾选可用的 Provider 与模型即可（§4.6）。调度池是全局白名单，保存后热更新，子 Agent 只会在池内的 Provider / 模型中派遣。
几套机制可叠加吗
常见组合：Mission + 小黑（Mission 跑任务，小黑兜底）、Supervisor + Teams（主 Agent 把任务塞 Teams 队列）。不建议同会话把 Supervisor 与组队任务混用——组队任务是独立会话形态，走新建入口而非就地切换。
4.12 相关章节
- 第 2 章 项目与工作区 — 所有子 Agent / Mission 节点 / Teams 任务都跑在独立 Worktree。
- 第 3 章 AI 会话基础 — 「新建会话」「切换模式」的基础流程。
- 第 6 章 终端与文件 — 子 Agent 文件改动的审阅、Diff 与撤销。
- 第 12 章 专家与专家团 — 会话内邀请专家席位的多智能体协作。
- 第 14 章 桌面助手 — 由 Butler 升级而来的桌面助手小黑。