Multica 多 Agent 工作模式

Multica 多 Agent 开发工作模式：把多 Agent 协作变成团队可管理的工作流

模式跑通之后，你会撞上另一堵墙

在多 Agent 工作流那篇文章里，你学会了什么时候拆任务、怎么写交接报告、为什么一个文件只能有一个编辑责任人。假设这些你现在都做到了——一种新的摩擦出现了，而它与任务拆解毫无关系。

你的审查 Agent 活在一个终端标签页里，会话一结束就忘光一切。同事问"你那套 API-builder 的配置能给我用用吗？"，诚实的回答是一条塞满待粘贴提示词的消息。你精心封装的 Skill 躺在某一台笔记本的 ~/.claude/skills/ 里。主管问上周这些 Agent 到底干了什么，证据散落在五份终端历史、三个分支和所有人的记忆里。而每一次并行任务的开头，仍然是你把同样的项目背景再解释一遍。

瓶颈已经转移了。问题不再是 Agent 之间如何分工，而是 一个团队如何日复一日地运营这些 Agent：谁能运行哪个 Agent、任务在哪台机器上跑、花了多少钱、产出了什么，以及好用的配置如何被复用而不是被重新敲一遍。

Multica 是一个开源、可自托管的工作区，正是为这个缺口而生：你像给同事派活一样把工作指派给 AI Coding Agent——它认领 Issue、汇报进度、提出阻塞，然后把结果交回给你审查。本文讲清它的运行模型，演示如何把现有 AGENTS.md + Rules/Skill 工作流无损迁移过去，并给出单项目多 Agent 协作和团队落地的一套实践——包括什么时候值得基于 Multica 二次开发，什么时候不值得。

Multica 是什么——以及它刻意不做什么

理解 Multica 要先看它不做什么：它不提供模型，也不替代你的 AI Coding 工具。按照项目 README 的说法，Multica 驱动的是你已经安装并登录好的那些 Agent CLI——Claude Code、Codex、Cursor、Copilot、Qoder、Kimi 等等，截至写作时共支持 23 款——所以换供应商是换一个下拉选项，而不是做一次迁移。

它增加的是一个边界清晰的协调层：

Multica 的运行模型：服务端是协调面，你的机器是执行面

官方架构文档把这条线画得很精确。服务端——Multica Cloud 或你自己的部署——保存工作区、Issue、评论、状态、Agent 配置、Skill 和运行记录。接入的电脑保留 AI Coding 工具及其凭证、代码目录和真实的文件改动。当你把 Issue 指派给某个 Agent 时，服务端创建一个任务；你某台机器上的守护进程认领它，在代码旁拉起本地 CLI，把进度和结果流式写回 Issue。代码和工具凭证不会离开那台机器——只有一个文档明确指出的例外：写进 Agent custom_env 的值保存在服务端，所以文档提醒你不要把绝不能出机器的密钥放进去。

四个对象承载了这套模型的大部分内容，见核心概念页：

Issue 是协作的基本单元：需求描述、讨论、状态和历史。负责人可以是人、Agent 或 Squad。
Agent 是一份可复用的配置——名称、指令、模型、Skill、访问范围、运行时——而不是常驻进程。只有被触发时才执行。
Runtime 是你接入的一台电脑：Agent 是身份，Runtime 是它办公的工位。
Task 是一次具体的运行。一个 Issue 可以累积多次任务；一次运行结束不等于 Issue 完成。

这套模型有两条性质比任何功能列表都重要。第一，Agent 从不自行开工——每次运行都由明确动作触发：指派 Issue、@ 提及、对话，或者定时的 Autopilot。第二，Agent 做的每件事都落在 Issue 上：委派决策、执行日志里的每次工具调用、每次运行的 Token 开销、产出的分支。正是这一点，让没盯着终端的人也能复查多 Agent 的工作。

如果你读过我们的多 Agent 工作流文章，你会认出这套哲学：编排者、有边界的工作者、可持久化的交接、验证关卡。Multica 本质上就是把那套交付系统做成了产品，Issue 就是那份可持久化的交接。

三对绝不能混淆的概念

迁移出问题，多半是因为把旧概念草率地映射到了新概念上。三组区分能解决大部分问题。

Agent 指令 vs. AGENTS.md。 指令属于某一个 Agent，每次运行都会提供：它负责什么、可以改什么、如何交付、什么时候必须停下来问人。而 AGENTS.md 和 Rules 文件描述的是项目本身：构建命令、代码规范、修改边界——也就是你在 Rules 与 AGENTS.md 那篇文章里建立的唯一事实源。Multica 不会吞掉你的仓库文档；因为它驱动的是同一批 CLI，这些工具照常从检出目录里原生读取 AGENTS.md、CLAUDE.md 和 Rules 目录。角色身份上平台，项目事实留在 Git。

工作区 Skill vs. 仓库 Skill。 Multica 的工作区 Skill 是保存在服务端的 SKILL.md 加附属文件，可以挂载到任意多个 Agent，一处维护。每次运行前，Multica 会把 Agent 绑定的 Skill 注入当前工具能原生发现的路径——Claude Code 是 .claude/skills/，Codex 是任务级的 $CODEX_HOME/skills/，Qoder CLI 是 .qoder/skills/，详见工具对比表。仓库里已有的 Skill 永远不会被覆盖；重名时注入副本会换一个目录名，运行结束后 Multica 只清理自己创建的文件。所以仓库 Skill 和工作区 Skill 可以共存——前者跟代码一起进版本管理，后者跨 Agent、跨工具共享。

Squad vs. Subagent。 Subagent 是单个工具会话内部的实现细节。Squad 是工作区里的路由结构：一个 Leader Agent 加若干成员（Agent 或人类）。把 Issue 指派给 Squad 只会唤醒 Leader，它阅读上下文，发一条 @ 提及选定成员的委派评论，在 Issue 时间线上记录自己的评估理由，然后停下。Leader 从不亲自实现。Squad 回答的是"这活该给谁"——它不会把多个 Agent 合并成一个超级 Agent，也不会自动提高并发。

迁移一套 AGENTS.md + Rules/Skill 工作流

先说好消息，也是最重要的一条迁移事实：仓库里的东西一个都不用改。 迁移是给那些一直放在 Git 或个人 dotfiles 里不舒服的资产重新安家。

迁移地图：仓库事实原样保留，Skill 一次性导入，MCP 迁到 Agent，克隆变成项目资源

按层推进：

第 1 步——盘点现有资产。 大多数成熟的配置包含四类资产：仓库里的项目文档（AGENTS.md、Rules）、Skill 目录（个人的或仓库级的）、散落在各工具配置文件里的 MCP 服务器配置，以及那层非正式资产——每次会话开头都要粘贴的角色提示词（“你是审查者，永远不要直接改代码”）。

第 2 步——项目事实留在仓库。 别只是相信，要验证：跑一个 Multica 任务，在执行日志里确认工具确实加载了你的 AGENTS.md。图里那条经验法则值得写进团队文档：描述代码库的内容留在 Git；描述角色、方法或机器的内容迁到 Multica。

第 3 步——把会话角色提示词变成 Agent 指令。 每一个你反复敲的角色，都变成一个具名 Agent。接好 Runtime 之后：

multica agent create \
  --name "Frontend Reviewer" \
  --runtime-id <runtime-id> \
  --description "审查前端 Pull Request" \
  --instructions "先读 diff 和相关测试。只检查 React/TS 正确性、
可访问性和组件模式一致性。永远不要直接修改代码；
按严重程度排序，把结论以 Issue 评论的形式发布。"

Agent 配置文档推荐的内容正是你过去粘贴的那些：职责范围、先检查什么、可以改什么、如何交付、什么时候停下来问人。

第 4 步——Skill 导入一次，挂载给多个 Agent。 工作区 Skill 可以手工创建、从本地目录或 .skill/.zip 压缩包导入、从 URL 导入（GitHub、ClawHub、Skills.sh），或者从已接入的 Runtime 复制——最后一种会扫描你机器上已装好的 Skill。用 CLI：

multica skill import --file ./review-helper.skill
multica skill refresh <skill-id>   # 从来源重新拉取 URL 导入的 Skill

有两个行为对团队很关键：从 Runtime 复制的 Skill 是快照（之后本地怎么改都不会同步）；从 URL 导入的 Skill 会保留来源引用，可以原地更新，Agent 的绑定关系不受影响。

第 5 步——MCP 配置迁到 Agent 上。 对于支持 Multica 托管 MCP 的工具，你在 Agent 上声明一次服务器配置，Multica 在每次运行前传给工具——不用再为每个工具、每位同事分别维护 .mcp.json、config.toml、settings.json。不要把凭证塞进自定义参数；custom_env 的值虽有访问控制和审计，但在服务端是明文存储的，高价值长期凭证干脆不要放。

第 6 步——把仓库关联为项目资源。 项目资源告诉 Agent 这批工作用哪份代码。Git 仓库资源默认以 worktree 模式运行，同一仓库上的任务可以并发而互不干扰。本地目录是超大检出的逃生通道；它默认的 in_place 模式下任务串行执行、Agent 直接编辑你的真实工作副本，所以只要目录是正常的 Git 仓库，优先用 worktree 模式。

迁移期还有一座好用的桥：Multica CLI Skill 能让 Codex、Claude Code 或 Cursor 直接操作 Multica，团队过渡期间，你现有的交互式会话就能创建 Issue、查任务状态。

一个 Issue 走到底：还是那个订单导出需求

拿多 Agent 工作流文章里用过的同一个需求——订单页的 CSV 导出，横跨 API、UI、审计事件和对抗性测试——在 Multica 里跑一遍。

一次性配置：项目「订单交付」关联好仓库；三个 Agent（api-builder、ui-builder、security-reviewer），各自带角色指令并挂上团队 Skill；一个 Squad「订单交付」，Leader 是 delivery-lead，Squad 指令写着"API 和持久化给 api-builder；UI 给 ui-builder；任何改动进 in_review 前必须过一遍 security-reviewer"。

之后的日常循环短到可以完整展示：

创建 Issue。 MUL-231：给订单页增加 CSV 导出，把上一篇文章里的契约——路由、权限、审计事件、成功规则——贴进描述，指派给 Squad。
Leader 分派。 Multica 只唤醒 delivery-lead，给它注入系统管理的运行协议、成员名册和你写的 Squad 指令。它发一条 @ 提及 api-builder 和 ui-builder 的委派评论，把评估理由记到时间线上，然后停下。Issue 进入 in_progress。
成员在隔离环境里实现。 每个 @ 提及创建一个任务；守护进程让每个任务在自己的 Git worktree 里运行，谁也碰不到你的工作副本，也碰不到彼此。进度和阻塞以评论形式出现在 MUL-231 上。每次运行的产出是一个名为 agent/<agent>/<task> 的分支——Multica 永远不会替你合并。
审查是关卡，不是祈祷。 推上去的分支变成 PR；GitHub 集成靠分支名里的编号或 Closes MUL-231 关闭意图把 PR 自动关联到 MUL-231，把 CI 状态和可合并性映射到 Issue 上——它是只读的，从不向 GitHub 推送或评论。security-reviewer 读合并后的 diff，发布检查结论。人类读审查结论、执行日志和每次运行的 Token 开销，然后合并。
Done 是挣来的。 只有当某个已合并的关联 PR 带着关闭意图、且没有其他仍处于 Open 或 Draft 的工作 PR 时，Issue 才会进入 Done——Agent 自己止步于 in_review。

一次 Squad 运行：从 Issue 指派、并行 worktree 到人类合并 PR

和终端版的同一个需求对比：分工完全一样，但契约、委派决策、每个 Agent 跑过的每条命令、分支、审查结论和成本，现在都挂在同一个 Issue 上，你的同事——或者未来的你——可以完整回放。

单项目多 Agent 的实践

多 Agent 工作流文章里的工程判断全部继续有效；平台只是给每条规则找到了落脚点。下面这些实践来自 Multica 的文档化行为，以及它们各自防住的失败：

“一个文件一个责任人"要靠角色设计保证，不能靠运气。 Worktree 防的是文件系统冲突，不是语义冲突——两个 Agent 仍可能在并行分支里各自重新设计同一个模块。把所有权写进指令（“永远不要直接改代码”、“只负责 services/orders/"）和 Squad 路由规则里，让边界在每次运行时生效，而不是指望有人记得。

让 Leader 只分派，绝不实现。 Multica 把这一点硬编码了——Leader 的分派回合以一条委派评论结束——这也正是编排者模式的要求：一个还亲自改代码的 Leader 会和自己的工作者争夺所有权。把路由知识写进 Squad 指令（“数据库的活给 Alice，前端给 Bob”），只有 Leader 能看到。

责任人明确时直接指派。 Squad 文档说得很直白：范围清晰时，直接指派给匹配的 Agent。只有当合适的责任人真的取决于 Issue 内容时，Squad 的开销才值得付。

并发要刻意设置。 每个 Agent 默认并发 6 个任务，每个守护进程上限 20，实际生效取两者较小值。审查 Agent 很少需要超过 1–2；热点仓库上的构建者可以多一些。你来不及审查的并发不是吞吐量，是排队返工。

把 Issue 当作契约的家。 冻结的决策（路由、权限、事件名、成功规则）写进 Issue 描述，每个被触发的 Agent 都会收到。评论用来汇报进度和发现，不能悄悄改契约——契约要变，由人来改描述并明说。

把证据写成交付要求。 写进每个构建型 Agent 的指令里：以 Issue 评论汇报分支、执行过的命令、测试结果和剩余风险。执行日志反正会记录发生过什么；评论才是审查时你真正会读的、给人看的交接。

团队协作的实践

团队落地会带来单人工作流从未问过的问题。通用策略见团队落地与治理那篇文章；下面是 Multica 特有的控制点。

限定谁能运行什么。 访问范围是按 Agent 设置的——仅自己、指定成员或整个工作区——而且值得注意的是，只有 Agent 的所有者能改它；工作区管理员无法给自己授予运行别人 Agent 的权限。新 Agent 先设为私有，行为经过审查后再放宽。Squad 继承这一点：不能运行 Leader 的成员就不能使用这个 Squad。

像管理共享库一样治理 Skill，而不是像维基。 任何成员都能创建或导入 Skill，但只有创建者、所有者和管理员能修改，删除会同时从所有 Agent 上解绑。团队共享的方法优先用带托管来源的 URL 导入 Skill，这样"从来源更新"是一个可审计的动作，而不是拷一次文件夹。文档的警告要当真：导入的 Skill 会原样交给 Agent——Multica 不做审查、签名或沙箱——所以对待第三方 Skill 导入，要像对待新增一个依赖一样多疑。

把 Runtime 放在爆炸半径可接受的地方。 安全模型文档异常坦诚：任务以运行守护进程的操作系统用户的完整权限执行，而且因为 Agent 无人值守运行，审批提示会被自动应答——默认路径下 Codex 以 sandbox_mode = "danger-full-access" 运行，Claude Code 以 --permission-mode bypassPermissions 运行。Multica 明确拒绝假装自己是沙箱。文档给出的建议由轻到重：一个专用的 multica 系统用户，只拥有 Agent 需要的仓库和限权凭证；一个只挂载所需目录和密钥的容器；一台虚拟机。对团队来说，行之有效的模式是一两台按此配置的共享 Runtime 机器，加上按用途分配的 Deploy Key，而不是任何人的个人 SSH 私钥。

云端还是自托管，看数据，不看立场。 两种模式下代码和工具凭证都留在你的 Runtime 上；服务端保存的是 Issue、讨论、配置、Skill 和运行记录。如果这些必须留在内网——或者你需要自托管 GitLab/Gitea/Forgejo 集成（这是自托管独有的功能）——就用 Docker Compose 或 Helm 自己部署。按照 Multica License，单一组织内部使用不需要商业授权。

在团队已经聊天的地方接入。 Slack 和 Lark 集成是官方维护的；钉钉、企业微信和 Telegram 由社区维护。在 Bug 被报出来的那个群里直接触发 Agent，消灭"我回头建个单"的时间差——但审查要留在工作区里做，因为执行日志和 diff 在那里。

基于 Multica 二次开发：先配置，再脚本，最后才是 Fork

“能不能改源码来适配我们的流程？“通常是个问错顺序的问题。Multica 的扩展面是一架梯子，每一级都比下一级便宜得多。

第 1 级——配置。 Agent、指令、Skill、带路由规则的 Squad、定时的 Autopilot、Agent 级 MCP 服务器，已经覆盖了大多数"我们团队不一样"的场景，一行代码都不用写。每天早晨跑一次站会汇总的 Autopilot 是配置，不是开发。

第 2 级——CLI 和 API。 每个界面都可以脚本化——Agent 操作 Multica 用的就是你用的那个 CLI。一个从工单系统同步创建 Issue 的脚本，或者 PR 打上某个标签就 @ 审查 Agent 的 CI 任务，都是你完全掌控的薄集成层，Multica 升级在契约上不会弄坏它。

第 3 级——Fork。 只有需要结构性改动时才合理：自定义触发源、任务生命周期中间插入内部审批流、集成没有覆盖的自研 Git 托管。动手之前，掂量三个有文档依据的事实。第一，许可证：单一组织内部使用无需商业授权，但把你的 Fork 作为托管服务提供给第三方——即使免费——也需要商业授权；未获得书面豁免前，UI 的品牌标识和署名信息必须保留；只用后端做集成也必须在面向用户的文档中注明基于 Multica。第二，迭代速度：项目自述几乎每个工作日发版、main 分支移动很快——深度 Fork 从切出那天就开始漂移。第三，结构：代码库是 Go 后端、Next.js 前端加守护进程，可持续的 Fork 模式和面对任何快速演进的上游一样——把你的改动收敛为薄且隔离良好的一层（新增 handler、新增集成模块），而不是散落在核心逻辑里的修改，并按节奏 rebase。

给大多数团队的一个务实解读：先把第 1、2 级用尽；只为一个能叫出名字的结构性缺口去 Fork，并指定专人跟踪上游。

失败模式与适用边界

平台不是隔离边界。 这是最咬人的失败。一个在你个人笔记本上以 danger-full-access 无人值守运行的 Agent，读得到你的 SSH 私钥和浏览器配置。真正的边界是你把守护进程放进去的那个系统用户、容器或虚拟机——在第一个正式任务之前建好它，而不是在第一次事故之后。

一次绿色运行不等于 Issue 完成。 文档把这个区分讲得很明白：执行日志里的 Completed 只表示一次运行结束了。把"Agent 跑完了"直连到"工单关闭"的团队，交付的是没人审过的代码。守住关卡：Agent 止步于 in_review；进入 Done 靠带关闭意图的合并或者人。

Skill 在三份副本之间漂移。 同一份检查清单可能同时存在于仓库、工作区和某台 Runtime 上。给每个 Skill 指定唯一权威来源并写进它自己的描述里——和代码强耦合的流程放仓库，跨项目的方法放工作区——否则两个 Agent 会遵循两个版本的"同一套"流程。

Leader 因被滥用而成为瓶颈。 如果每个鸡毛蒜皮的 Issue 都走 Squad，你为每个 Issue 多付一次 Leader 运行，换来的是复述显而易见内容的委派评论。Squad 留给真正路由不明的工作；其余一律直接指派。

有些场景干脆不该用 Multica。 一个人、一个仓库、一个工具的独立开发者，从协调面得到的收益很少；上一篇文章里的终端加 worktree 更简单。需要亚秒级反馈的紧密探索式结对编程属于 IDE。Multica 的价值在于工作必须经受交接的时候——在人与人之间、Agent 与 Agent 之间、或者今天与下周之间。另外，用上它也不会自动产生治理：它给你审计轨迹、访问范围和审查关卡，但 diff 还是得有人看。一块摆满绿色运行记录却没人审查的看板，只是排版更好看的风险。

一周内可以验证的试点

在任何全团队宣布之前，先跑一个有边界的试点，收集证据而不是印象：

Runtime 运行在专用系统用户或容器下，只持有限权的仓库凭证——用"列出这个用户实际能读什么"来验证。
对你的仓库跑过一个真实任务，执行日志显示工具加载的 AGENTS.md 与 Git 里的完全一致。
两个 Agent 以 worktree 模式并发处理了同一个仓库，git branch 显示两个 agent/... 分支，没有人的工作副本被写入。
一个指派给 Squad 的 Issue，时间线上有 Leader 的委派评论和评估记录——并且没有任何 Leader 亲自写的代码。
一个 PR 通过分支名自动关联到了 Issue，CI 状态显示在 Issue 上，并且 Issue 只通过带关闭意图的人工合并才进入 Done。
一个 Skill 只导入一次，挂载到两个使用不同 CLI 的 Agent 上，两次运行都能看到它被注入各工具的原生 Skill 路径。
每次运行的 Token 用量在 Issue 上可见，试点成本可以用数字说清。
至少一位非 Agent 所有者的同事运行过 Agent——通过授予的访问权限，而不是共享账号。

如果有哪一项勾不上，你就找到了真正的迁移工作——通常是 Runtime 放置或所有权边界的问题，而不是工具本身。

你的工作方式究竟改变了什么

你已经掌握的多 Agent 模式——有边界的工作者、共享契约、带证据的交接、人类验证关卡——都不会变。变的是它们住在哪里。契约从临时的 Markdown 搬进每次运行都会收到的 Issue 描述。角色提示词变成具名的、有访问控制的 Agent。Skill 不再是你来回拷贝的文件夹，而是可以挂载的、有版本的资产。“Agent 都干了什么"不再是一场考古，而是一条带日志、分支和成本的时间线。

更深的转变发生在组织层面：多 Agent AI Coding 不再是一个随某位工程师的终端生灭的个人生产力技巧，而成为一种团队能力——可检查、可转移、可治理。这才是"Agent 即队友"这句话背后真正的承诺：不是 Agent 变聪明了，而是它们的工作终于和所有人的工作出现在同一块看板上。

权威资料

最后更新于 2026 年 8 月 27 日

AI Coding 的多 Agent 工作流