multica-squads

Multica Squads

快速开始

如果要排查某个 squad 为何执行或未执行，先检查：

multica issue get <issue-id> --output json
multica squad get <squad-id> --output json
multica squad member list <squad-id> --output json
multica issue comment list <issue-id> --roots-only --summary --output json
multica issue comment list <issue-id> --thread <thread-id> --tail 30 --output json

这两次评论读取是一个序列：先扫描根评论，再打开看起来相关的线程——提及触发、失败原因和用户指令通常位于回复中，而根评论扫描不会返回这些内容。

如果命令形式不明确，请查看帮助，而不是猜测：

multica squad --help
multica squad member --help
multica issue update --help
multica issue comment add --help

不要仅仅为了测试而分配、评论、提及、更新、删除或记录 squad 活动。这些操作可能会改变工作区状态或触发 Agent 运行。

核心模型

Multica squad 是一个工作区路由与协调对象。

squad 不是 Agent。它本身不运行工作。当前行为：由 squad 路由的工作通过该 squad 的 leader_id Agent 运行。

重要后果：

• 将 issue 分配给 squad 会路由到 leader；
• 提及 squad 会路由到 leader；
• squad 分配的 autopilot 会解析到 leader；
• squad 成员不会自动分发；
• squad instructions 是 leader 简报内容，不是成员提示词。

CLI

Squad 命令：

multica squad list --output json
multica squad get <squad-id> --output json
multica squad create --name <name> --leader <agent-name-or-id> --output json
multica squad update <squad-id> --instructions "<leader coordination policy>" --output json
multica squad delete <squad-id>

成员命令：

multica squad member list <squad-id> --output json
multica squad member add <squad-id> --member-id <id> --type agent|member --role <role> --output json
multica squad member remove <squad-id> --member-id <id> --type agent|member
multica squad member set-role <squad-id> --member-id <id> --member-type agent|member --role <role> --output json

Squad leader 评估命令：

multica squad activity <issue-id> action|no_action|failed --reason "<why>" --output json

activity 是一次写入：它在某个 issue 上记录 leader 的评估决定。仅当作为 squad leader 评估触发后才使用它。

它接受哪个 issue：你当前回合正在运行的 issue。目标 issue 不需要分配给您的 squad —— 在由单个 Agent 拥有的 issue 上 @squad 提及，或绑定到子 issue 的 leader 任务，都可以正常记录。服务器检查的是你的任务行（is_leader_task 加上已标记的 squad_id），而不是该 issue 的受理人。被阶段屏障唤醒的 leader 运行在 PARENT issue 上，因此应针对父 issue 记录，而不是你刚读取的子 issue；传入不相关的 issue id 会被拒绝，并且错误会指出你本应使用的 issue。

如果调用失败，不要静默退出——对 no_action 的评论禁令仅在记录成功后才适用。相反，发布一条简短评论说明结果，并且仅当本回合尚未评论时才这样做：在 action 路径上，你的委派评论已经是该记录。

与 squads 一起经常需要的 Issue/评论命令：

multica issue get <issue-id> --output json
multica issue update <issue-id> --help
multica issue comment list <issue-id> --roots-only --summary --output json
multica issue comment add <issue-id> --help

评论读取保持有界——即上文快速开始中的先扫描再展开序列——绝不要一次无界的 issue comment list 拉取。

读取时优先使用 --output json。写入前使用 --help。

Squad 字段

• id — squad UUID。
• workspace_id — squad 所属的工作区。
• name — 显示名称；每个工作区唯一。
• description — 面向人类的元数据/显示文本。除非源代码证明有消费者，否则不要假设它会影响运行时提示词。
• instructions — 添加到 squad leader 简报中的 squad 级指令。它们不会直接注入到每个 squad 成员。
• avatar_url — 可选的 squad 头像 URL。
• leader_id — squad leader 的 Agent ID；由 squad 路由工作的运行时目标。
• creator_id — squad 的创建者。
• archived_at / archived_by — 归档元数据。已归档的 squad 会被分配/autopilot 路由路径拒绝。
• member_count — 列表响应中的 squad 成员数量。
• member_preview — 列表响应中的 squad 成员预览。

将 instructions 用于面向 leader 的协调策略：squad 职责、委派预期、何时询问人类，以及审查/交接规则。不要把它写成好像每个成员都会自动收到一样。

Squad 成员字段

• member_type — agent 或 member。
• member_id — Agent 或工作区成员的 ID。
• role — 名册角色标签。当前行为：非空 role 会出现在 leader 简报名册中。不要假设它会创建调度、权限或路由行为。

创建与 leader 成员资格

创建 squad 需要 leader_id。leader 必须是工作区 Agent。 创建/更新不会拒绝已归档的 leader：查找逻辑只检查该 Agent 在工作区中是否存在。已归档的 leader 会在后续路由/派发阶段 失败关闭——分配、autopilot 准入门禁，以及评论/提及就绪门禁都会在 任何任务入队之前拒绝已归档的 leader。

创建时，后端会尝试将 leader 添加为 squad 成员，角色为 leader。更新 leader_id 时，如果新 leader 还不是成员， 后端会将新 leader 添加为 squad 成员，角色为 leader。

Leader 简报

对于 squad leader 任务，Multica 会在 leader Agent 指令中追加一份 squad leader 简报。简报包括：

• Squad Operating Protocol；
• Squad Roster；
• Squad Instructions，仅当 instructions 非空时。

Roster 条目包括成员名称、成员类型、提及 markdown，以及非空 角色。对于 Agent 成员，roster 还会列出其已分配的技能 （skills: a, b，如果该 Agent 没有技能则为 no skills assigned），以便 leader 能够按能力进行委派，而不是根据角色标签猜测；人类 成员不包含技能片段。内置的 multica-* 技能不会列出—— 只列出显式附加到该 Agent 的工作区技能。已归档的 Agent 成员会从简报 roster 中跳过。

Issue 分配行为

Issue 可以分配给 squad，使用：

assignee_type = "squad"
assignee_id = <squad-id>

当前行为：

• 分配会将工作路由到 squad.leader_id；
• 它不会将每个 squad 成员都入队；
• 当状态为 backlog 时进行分配不会立即开始工作；
• 将已分配给 squad 的 issue 移出 backlog 可以触发 leader；
• 更改 assignee 会取消该 issue 的现有任务，然后再将 新的 assignee 路径入队；
• 父 issue 状态由 Agent 管理（与直接分配 Agent 相同的模型）： leader 的第一个分配回合应将父 issue 移至 in_progress 并在成员工作期间保持该状态；leader 只有在后续重新触发确认 总体目标已达成时，才将父 issue 移至 in_review。完成 leader 的 task（包括首次派发）本身不会 改变 issue 状态；
• 该状态权限仅在 issue 的 assignee_type / assignee_id 指向此 squad 时授予。Leader 简报会在每个 leader 路径上注入，包括对由普通 Agent 拥有的 issue 进行 @squad 提及 ——在这些路径上，协议会改为携带明确的“不要更改此 issue 的状态”。

上述状态名称是类别规则：工作区可以定义内置状态之外的自定义 状态，每个自定义状态都会完整继承其类别的行为 （当存在任何自定义状态时，运行时简报会列出工作区目录）。

分配校验会拒绝缺失 type/id 对、不存在的 squad、 已归档的 squad、已归档的 leader，以及当执行者无法访问时拒绝私有 leader。

评论与提及行为

如果某个 issue 分配给了 squad，新评论可以唤醒 squad leader。这 是 leader 路由，而不是成员扇出。

Squad 提及格式：

[@Squad Name](mention://squad/<squad-id>)

当前行为：解析 squad，读取 leader_id，将 leader 任务入队， 并使用当前评论作为触发评论。它不会将每个 squad 成员都入队。

Autopilot 行为

Autopilot 可以分配给 squad。对于 assignee_type = "squad"：

• 可执行 Agent 从 squad.leader_id 解析；
• 准入/就绪检查针对 leader 运行；
• 已归档的 squad 会失败关闭 / 跳过派发；
• 运行归因会在适用时记录 squad id。

对于 create_issue autopilot，创建的 issue 保持 assignee_type = "squad" 和 assignee_id = <squad-id>，而实际执行的 Agent 是解析出的 leader。对于 run_only autopilot，不会创建 issue；任务会直接 为解析出的 leader Agent 创建。

处理投诉或产品缺口

当用户说 squad 行为错误、令人困惑或令人失望时，不要 立即假设代码已损坏，也不要仅仅因为当前行为已存在就为其辩护。先分类：

• 预期的当前行为；
• 配置问题；
• 产品限制；
• 实际 bug。

解释当前有源码支持的行为。如果该行为在技术上 正确但在产品层面很糟糕，请说明并提议一个有范围的产品/代码变更。

未经确认，不要悄悄更改 squad 路由、成员扇出、leader briefing、autopilot 行为或 comment-trigger 行为。这些是具有副作用的 产品契约变更。

副作用

这些操作可能触发 Agent 工作或改变持久状态：

• 创建 squad；
• 更新 squad 字段；
• 更改 leader_id；
• 添加/移除成员；
• 更改成员角色；
• 将 issue 分配给 squad；
• 将已分配给 squad 的 issue 移出 backlog；
• 对已分配给 squad 的 issue 发表评论；
• 提及 squad；
• 创建或触发已分配给 squad 的 autopilot；
• 使用 multica squad activity 记录 squad 活动；
• 删除/归档 squad。

除非用户明确授权，不要将产生副作用的操作作为测试执行。

常见错误假设

• Squad 不是 Agent。
• Squad 工作路由到 leader_id，而不是每个成员。
• Squad 提及路由到 leader，而不是每个成员。
• Squad 分配路由到 leader，而不是每个成员。
• Squad autopilot 解析为 leader 作为可执行 Agent。
• instructions 是 leader briefing 内容，不是自动的成员提示词。
• description 并未被证实是运行时提示词内容。
• role 是 roster 上下文，不是自动调度。
• Backlog 分配不会立即开始工作。
• 首次 leader 派发不是父级完成 —— 父级保持 in_progress 状态，直到 leader 之后确认总体目标并将其移至 in_review。
• 子 issue 完成时，服务不会自动翻转父级状态；它只会 以明确请求唤醒 leader（包括收尾时的 in_review）。
• 获得 leader briefing 并不意味着拥有状态权限。Squad 被 @ 提及到一个分配给其他人的 issue 时是访客：roster 和 委派规则适用，multica issue status 不适用。

参考

有关源路径、测试、边缘情况和确切路由细节，请参阅：

references/squad-source-map.md