Multica Squads 全解squad 是工作区路由对象而非 Agent理解 leader 路由与 multica CLI 实战【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multicaMultica 的 Squad小队是一个面向工作区的路由与协调对象把 Issue 指派给 squad、在 Issue 中squad提及、把 Autopilot 绑定到 squad实际承接执行的都只有一个实体——squad 的 leader agent。本指南以仓库内置技能文档 multica-squads/SKILL.md 为主体结合服务端 handler、迁移 SQL 与 CLI 实现完整讲解 squad 的领域模型、multicaCLI 全部相关命令、Leader Briefing 组装规则、状态权威边界以及排障时必须规避的常见误区读完你可以独立完成 squad 的创建、成员编排、指派排障与行为核验。本文涉及内容在仓库中的官方表述位于 SKILL.md其全部源码证据迁移、handler、测试收录于配套的 squad-source-map.md文章中的代码事实均可回溯到这两份文件列出的路径。Squad 核心模型路由与协调对象不是 AgentSKILL.md 开头一句话定义了整个模型A Multica squad is a workspace routing and coordination object. A squad is not an agent. It does not run work by itself.当前行为是所有 squad 路由的工作都通过 squad 的leader_id指向的 agent 运行。由此产生一系列关键推论全部体现在 SKILL.md 的 Core model 与 Common wrong assumptions 中把 Issue 指派给 squad ⇒ 路由到 leader提及mentionsquad ⇒ 路由到 leadersquad 绑定的 autopilot ⇒ 解析为 leader 执行squad 成员不会被自动 fan-out不会自动分摊工作squad 的instructions是给 leader 的简报内容不是给每个成员的系统提示词。从数据库层看这一模型非常直接。squad与squad_member两张表定义在 084_squad.up.sqlsquadid、workspace_id、name、description、leader_idREFERENCES agent(id) ON DELETE RESTRICT所以 leader 必须是 agent 且不可被删掉、creator_id并有UNIQUE(workspace_id, name)同一工作区内名字唯一。squad_membermember_type TEXT NOT NULL CHECK (member_type IN (agent, member))、member_id、role TEXT NOT NULL DEFAULT 以及UNIQUE(squad_id, member_type, member_id)防止重复入队。同一个迁移还扩展了 Issue 的指派语义issue.assignee_type约束被改写为CHECK (assignee_type IN (member, agent, squad))即 Issue 现在可以指派给 squad。存档与指令字段由后续迁移补齐085_squad_archive.up.sql 增加archived_at/archived_by088_squad_instructions.up.sql 增加instructions TEXT NOT NULL DEFAULT 。服务端与前端共享的类型定义见 packages/core/types/squad.ts其中Squad接口完整对应上面的字段集含member_count?、member_preview?等列表响应字段并定义了SquadActivityOutcome action | no_action | failed。排障入口先读后写SKILL.md 的 Quick start 给出了 debug 一条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后两条评论读取命令是有顺序的两个阶段先扫根评论roots再按需展开看起来相关的 thread——mention 触发器、失败原因、用户指令通常都藏在回复里而 roots 扫描永远拿不到回复内容。评论读取要保持有界绝不执行一次不加边界的issue comment list全量拉取。当不确定命令形态时用 help 而不是瞎猜multica squad --help multica squad member --help multica issue update --help multica issue comment add --help读操作一律偏好--output json写操作前一律先跑--help。且禁止为了测试而执行 assign、comment、mention、update、delete、记录 squad 活动等操作——它们会改动工作区状态或触发 agent 运行。multica squad 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-idCLI 实现位于 server/cmd/multica/cmd_squad.golist默认文本输出会渲染成表格ID / NAME / LEADER ID / MEMBERS--output json返回member_count。get文本模式下打印 ID、Name、Description、Leader ID、Createdinstructions非空时才打印。create--name与--leader都是必填--leader接受agent 名称或 ID代码先经resolveAgent解析成leader_id再 POST/api/squads见runSquadCreatecmd_squad.go还支持可选的--description。update只有显式变更的字段才会写入请求体支持--name、--description、--instructions、--leader再次经resolveAgent解析与--avatar-url一个字段都没给时会报错no fields to update。delete真实语义是归档archive——文本输出写的是Squad %s deleted.但服务端走的是设置archived_at/archived_by而非物理删除对应 085_squad_archive.up.sql。成员命令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注意add使用--type指定成员类型而set-role使用--member-typeadd时--type只接受agent或member两个值runSquadMemberAdd中显式校验。list的文本输出为MEMBER ID / TYPE / ROLE。Leader 评估记录squad activity写操作multica squad activity issue-id action|no_action|failed --reason why --output jsonactivity是写操作它记录 squad leader 对一个 Issue 做出的评估决策只会也只需要在你作为 squad leader、针对一个触发器完成评估之后调用。CLI 侧实现见runSquadActivitycmd_squad.go服务端侧为RecordSquadLeaderEvaluationserver/internal/handler/squad.go。SKILL.md 对这条命令的使用边界给了极其明确的约束它接受哪个 Issue是你当前 turn 正在处理的那个 Issue。目标 Issue不需要指派给你的 squad——squad提及了一个个人 agent 拥有的 Issue、或 leader task 绑定在子 Issue 上都能正常记录。服务端校验的是你的任务行is_leader_task为真且盖了章squad_id而不是 Issue 的 assignee。被 stage barrier 唤醒的 leader 运行在父 Issue上所以应记录到父 Issue而不是你刚读到的那个子 Issue传一个无关的 Issue id 会被拒绝且错误信息会点明你本应使用的那个 Issue。调用失败时不要静默退出——no_action上的禁评论规则只在记录成功后才生效。此时应补发一条简短评论说明结果且仅当本 turn 尚未评论过时才发在action路径上你的委派评论本身已经是记录无需再发。与 squad 搭配的 Issue / Comment 命令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评论读取遵循 quick start 里先扫根、再展开的有界序列。Squad 字段一览SKILL.md 用逐字段的方式给出了语义与该字段到底会不会影响运行时 prompt的诚实边界字段语义运行时影响idSquad UUID—workspace_id所属工作区—name展示名工作区内唯一提及 markdown、简报标题会用到description人类可读的元数据/展示文本不要假设它影响运行时 prompt除非源码证明存在消费方instructionssquad 级指令追加进squad leader 的 briefing不会直接注入每个 squad 成员avatar_url可选头像 URL展示leader_idsquad leader 的 agent IDsquad 路由工作的运行时目标指派/提及/autopilot 都解析到这里creator_id创建者—archived_at/archived_by归档元数据已归档 squad 会被指派/autopilot 路由路径拒绝member_countlist 响应中的成员数—member_previewlist 响应中的成员预览—instructions的正确用法是写给 leader 看的协作策略squad 职责范围、委派预期、何时需要询问人类、review/handoff 规则。不要把它写得像是每个成员都会自动收到。Squad Member 字段一览member_type—agent工作区里的 agent或member工作区成员即人类用户。member_id— agent 或工作区成员的 ID。role— 名册角色标签。当前行为非空的role会出现在 leader briefing 的名册里不要假设它会产生调度、权限或路由行为。数据库层面对member_type的取值有CHECK约束见 084_squad.up.sql类型不合法时根本写不进去。创建与 Leader 自动入队创建 squad 必须提供leader_id且 leader 必须是工作区 agent。CreateSquad/UpdateSquad都通过GetAgentInWorkspace校验SQL 为WHERE id $1 AND workspace_id $2见 server/pkg/db/queries/agent.sql这一查询没有 archived 过滤因此create/update不会拒绝已归档的 leader只要能查到它在工作区内就能设上已归档 leader 的拒绝发生在更晚的路由/派发阶段fail closed指派校验issue.go 的 assignee 校验、autopilot 准入、评论/提及就绪门isSquadLeaderReady → service.AgentReadiness都会在入队任何任务之前拒绝已归档 leader。创建成功后后端会自动把 leader 以角色leader加为 squad 成员squad.go 的CreateSquad更新leader_id时若新 leader 还不是成员后端同样会自动以角色leader加入UpdateSquad。Leader Briefing给谁的、装了什么、谁有状态权威squad leader 任务入队后Multica 会把一段 squad leader briefing追加到 leader agent 的系统提示词里注入点在 server/internal/handler/daemon.go 的 leader task claim 路径。组装逻辑集中在 server/internal/handler/squad_briefing.go 的buildSquadLeaderBriefing第 180 行起包含三个部分Squad Operating Protocol恒定协议 按需替换的状态条款Squad Roster名册Squad Instructions——仅当instructions非空时才会出现代码先TrimSpace判空避免留下悬空标题。buildSquadLeaderBriefing接收一个ownsIssueStatus布尔参数只有当 Issue 的assignee_type squad且assignee_id squad.id时才为真。squadOperatingProtocolFor(ownsIssueStatus)依此在两个状态条款间二选一squadParentStatusOwned拥有父 Issue 状态或squadParentStatusNotOwned显式禁止改该 Issue 状态。协议在第 154 行起组装即协议头 状态条款 硬性规则。名册部分buildSquadRoster第 197 行起每个条目包含成员名、成员类型、可粘贴的提及 markdown以及非空 role。对 agent 成员还会通过loadSquadMemberSkillNames拉取其挂载的工作区技能并渲染成skills: a, b或no skills assigned让 leader 能按能力而非按角色名委派人类成员没有技能段。两个重要的裁剪规则内置multica-*技能不出现在名册里——只列出显式挂到 agent 上的工作区技能已归档的 agent 成员直接从简报名册中跳过同样底层记录加载失败的成员也被静默跳过防止把已退役/已删除的 agent 推荐给 leader 去委派。leader 自己如果也在成员列表里会被跳过代码第 222-226 行专门处理避免自我委派。关键设计briefing 的注入范围比状态权威更宽。注入以任务行的is_leader_task为键因此squad提及到他人拥有的 Issue上的场景也会注入 briefing——此时协议会带上显式的不得改动该 Issue 状态。也就是说拿到 leader briefing ≠ 拥有状态修改权。Issue 指派行为都指向 leader状态权威只在自家 Issue 上把 Issue 指派给 squad即设置assignee_type squad assignee_id squad-id当前行为逐条核对如下指派把工作路由到squad.leader_id不会把每个成员都入队状态处于backlog时的指派不会立刻开始工作把 squad 指派的 Issue 移出backlog可能触发 leader更换 assignee 会先取消该 Issue 的既有任务再为新的 assignee 路径入队父 Issue 状态由 agent 托管与直接指派 agent 同一模型leader 的第一个指派 turn 应把父 Issue 移到in_progress并在成员工作期间保持只有当后续 re-trigger 确认整体目标达成时leader 才把父 Issue 移到in_review。完成 leader task包括第一次派发本身不会改变 Issue 状态——StartTask/CompleteTask不写状态派发成员 ≠ 交付所以派发 turn 后父 Issue 保持in_progressin_review要等确认整体目标的 re-trigger 到来这份状态权威仅当Issue 的assignee_type/assignee_id正指向本 squad 时才授予。leader briefing 在每条 leader 路径上都注入包括squad提及到普通 agent 拥有的 Issue——在这些路径上协议改而携带显式的不要改变该 Issue 状态条款。被squad请进他人 Issue 的 leader 是访客名册与委派规则可用multica issue status不可用。上面提到的状态名是类别规则工作区可以定义内建于体系之外的自定义状态每个自定义状态完整继承其所属类别的行为Effective/Resolve逻辑位于 server/internal/issuestatus/issuestatus.go当存在任何自定义状态时运行时 brief 会列出工作区状态目录。指派校验会拒绝缺失的 type/id 配对、不存在的 squad、已归档的 squad、已归档的 leader、以及调用方无法访问的私有 leader指派时在 issue.go 校验、入队时经canEnqueueSquadLeader二次校验。pending 任务去重同样生效避免重复入队。评论与 squad 提及leader 唤醒而非成员扇出如果某个 Issue 指派给了 squad一条新评论可以唤醒 squad leader——这是leader routing不是 member fan-out。评论触发路径在 server/internal/handler/comment.gocomputeCommentAgentTriggers计算触发器其 squad 指派分支为computeAssignedSquadLeaderCommentTrigger第 1162-1199 行显式 squad 提及分支约在第 1352 行。Squad 提及格式Squad Name行为解析 squad → 读取leader_id→ 以is_leader_tasktrue入队一条 leader 任务EnqueueTaskForSquadLeader→ 把当前评论作为触发评论。不会把每个成员都入队。服务端还内置了防自触发循环的保护同 leader / last-task-was-leader 守卫lastTaskWasLeader在 server/internal/handler/squad.go 第 915 行以及成员被显式提及时的跳过逻辑。Autopilot 绑定 SquadAutopilot 可以指派给 squad。当assignee_type squad时可执行 agent 从squad.leader_id解析resolveAutopilotLeader的 squad 分支约在 server/internal/service/autopilot.go 第 639-651 行准入/就绪检查针对 leader 执行保存期校验拒绝已归档 squad/leaderhandler/autopilot.go 第 881-891 行派发时再次执行resolveAutopilotLeaderAgentReadiness已归档 squadfail closed / 跳过派发errSquadArchived运行归属attribution在适用处记录 squad id。两类 autopilot 有不同落点create_issue型创建的 Issue 保持assignee_type squad、assignee_id squad-id实际执行的 agent 是解析出的 leaderautopilot.go 第 88-97 行run_only型不创建 Issue直接为解析出的 leader agent 建任务autopilot.go 第 99-106 行。子任务完成触发父级 leader当子 Issue 关掉某个 stage barrier、而父 Issue 指派给了 squad 时父级的 squad leader 会被触发triggerChildDoneSquad见 server/internal/handler/issue_child_done.go。要点只路由 leader——在 leader 上执行一次EnqueueTaskForSquadLeader无成员扇出这一唤醒是串行交接到父 Issue 上的唯一载体也是 stage barrier继续推进 / 收尾指令的唯一携带者同 squad 或共享 leader 的子 Issue 完成也会唤醒父级 squad leader父 Issue 状态不会被 barrier 自动推进系统评论要求 leader 继续推进或当整体目标达成时运行multica issue status parent-id in_review。父 Issue 的状态in_progress→ 确认后in_review由 leader 在 Squad Operating Protocol 的Own the parent issue status职责下自行维护done仍归人类 / 集成侧所有该唤醒路径不做二次 leader 调用权限检查父 Issue 在 squad 指派时已经过validateAssigneePair校验唤醒自家 leader 属于协作交接而非新发起调用历史上二次检查曾对默认私有 leader fail closed卡死整条流程级联修复后 agent 与 squad 共用一条无门禁路径。私有 Leader 的调用门禁squad 路由最终要往 leader agent 上入队任务因此存在一条触发期门禁区别于查看期门禁canEnqueueSquadLeader加载 leader 后委托给canInvokeAgent两者都在 server/internal/handler/agent_access.go前者约第 261-267 行。判定规则以有效调用者为准member 发起者即其本人agent/system 发起者取调用链顶端的人类发起人originatorUserID解析不到则为空串agent 拥有者永远可以调用自己的 agentpermission_mode ! public_to即私有是默认拒绝——无管理员旁路、无 agent-to-agent 旁路只有 owner 分支能过public_to咨询调用目标 allow-listworkspace目标放行任何工作区成员及工作区内部 agent/system 主体即使解析不到人类member目标要求解析出的人类匹配team目标在 V1 中不生效。这一门禁被接到enqueueSquadLeaderTasksquad.go 第 955-974 行squad 指派/提升路径在调用方无法调用 leader 时拒绝入队。当用户抱怨 Squad 行为时先分类再解释SKILL.md 要求面对用户说 squad 行为不对/困惑/失望时不要条件反射地断定代码坏了也不要因为行为存在就为现状辩护而是先分四类预期的当前行为expected current behavior配置问题configuration issue产品局限product limitation真正的 bugactual bug。然后解释有源码支撑的当前行为如果行为技术上正确但产品上糟糕就直说并提出有边界的产品/代码改动方案。squad 路由、成员扇出、leader briefing、autopilot 行为、评论触发行为都属于有副作用的产品契约变更——在未经确认前不得擅自改动。副作用清单不要用写操作做测试以下是会触发 agent 工作或改动持久化状态的动作SKILL.md 明令除非用户明确授权否则不要拿它们当测试创建 squad更新 squad 字段更换leader_id增删成员修改成员角色把 Issue 指派给 squad把 squad 指派的 Issue 移出 backlog在 squad 指派的 Issue 上评论提及 squad创建或触发 squad 绑定的 autopilot用multica squad activity记录 squad 活动删除/归档 squad。常见错误假设速查SKILL.md 在文末集中给出了最容易踩坑的假设清单逐一对照可避免绝大多数误判Squad不是agentsquad 工作路由到leader_id不是每个成员squad 提及路由到 leader不是每个成员squad 指派路由到 leader不是每个成员squad autopilot 解析到 leader 作为可执行 agentinstructions是 leader briefing 内容不是自动的成员提示词description未经证明是运行时 prompt 内容role是名册上下文不是自动调度backlog 指派不会立刻开工首次 leader 派发 ≠ 父级完成——父级保持in_progress直到 leader 稍后确认整体目标并把父级移到in_review服务端不会在子 Issue 完成时自动翻转父级状态只会用一次显式询问唤醒 leader收尾时含in_review指示拿到 leader briefing不代表拥有状态权威——被squad请进他人 Issue 的 squad 是访客名册和委派规则可用multica issue status不可用。测试验证与源码证据索引SKILL.md 是给 agent 的操作规范而每条行为声明都有对应的 Go handler 测试与迁移/SQL 证据。想验证或深挖的读者可以从这些入口入手对象模型与约束084_squad.up.sql、085_squad_archive.up.sql、088_squad_instructions.up.sql、packages/core/types/squad.tsCLI 实现server/cmd/multica/cmd_squad.gocreate/update/活动记录/leader 入队server/internal/handler/squad.goleader briefing 组装server/internal/handler/squad_briefing.go注入点 server/internal/handler/daemon.go评论与提及触发server/internal/handler/comment.go子任务完成触发server/internal/handler/issue_child_done.go私有 leader 调用门禁server/internal/handler/agent_access.goautopilot 解析与派发server/internal/service/autopilot.go 与 server/internal/handler/autopilot.go测试分组均在server/internal/handlersquad_assign_trigger_test.go、squad_comment_trigger_test.go、squad_briefing_test.go、squad_private_leader_test.go、autopilot_private_leader_test.go、squad_no_action_test.go。对应的验证命令go test ./internal/handler -run Test.*Squad|Test.*squad|Test.*Autopilot.*Squad|Test.*ChildDone.*Squad更完整的逐条证据含精确行号、边界案例与相关 issue 编号请直接查阅配套的 squad-source-map.md。【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multica创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考