GitHub Squad：把多智能体协作放进代码仓库，关键不是多开几个模型

下午三点，我同时对着四个智能体窗口下了同一个指令：帮我把这个仓库里关于用户认证的代码梳理一遍，顺便看看有没有安全漏洞。第一个窗口给我吐了一堆文件路径，第二个开始改代码但没告诉我要改什么，第三个卡在“思考中”转了五分钟，第四个直接说“我没法读取这个目录”，而我的屏幕右下角还挂着那只代表忙碌的旋转光标。我真正想要的，是四份结果能拼成一张完整地图，而不是四条方向不同、互相矛盾、合并起来比重新看一遍代码还费劲的线索。看完这个仓库，我最大的收获是：关键不是多开几个模型，而是把角色、记忆和规则写进仓库里。你能带走的东西很具体：理解这种仓库原生编排的思路，并拿到一段能跑起来的最小脚本，亲手复现一个最简版本。

GitHub 为什么把多智能体直接放进代码仓库

到了 2026 年，AI 编程早就不只是能不能写代码的问题了。GitHub Copilot 从最早的行内补全，进化到能跑 Agent 模式，再到支持用项目文件定义定制智能体，方向很清楚：把 AI 从回答问题的窗口变成在仓库里干活的协作者。GitHub 官方介绍 Squad 时说得很直接，它是一个建立在 GitHub Copilot 之上的开源项目，用很少的基础设施，在代码仓库里初始化一支可以由人指导的智能体团队。

Squad 的启动动作只有两步：全局安装@bradygaster/squad-cli，再在项目里执行squad init。初始化的结果不是一个看不懂的控制台，而是一组放在.squad目录里的普通文件。角色说明、路由规则、决策记录和每个成员的项目历史，都可以像源代码一样被打开、修改、提交和审查。

这个设计针对的是一个很实际的痛点。当你有了四五个能读写文件、运行命令、调用工具的智能体，问题就从“它会不会写”变成“它们会不会撞车”。一个智能体改接口，另一个智能体不知道接口已经变了，测试智能体只看到旧分支，协调者又把四份互相矛盾的结果塞回同一个对话。聊天记录可以保留上下文，却很难承担项目状态。

仓库原生编排把问题换了个位置：让仓库文件成为协作协议。智能体的身份是文件，团队决策是文件，任务结果仍然通过分支和提交进入工程流程。这样做不等于不用调度器，而是把调度器保持得很薄，让真正需要长期保存的状态进入开发者已经信任的版本控制系统。

这里的“放进仓库”不是把模型本身提交进代码，而是提交一套能被重复读取的协作上下文。它至少要回答四个问题：这个角色负责什么，什么事情不能做，当前项目已经决定了什么，上一轮工作留下了哪些证据。回答得越具体，下一次会话越少依赖临时提示，团队也越容易判断一次结果到底是新发现还是旧结论的重复。

Squad 的四类角色如何分工

GitHub 官方文章举的默认团队由 lead、frontend developer、backend developer 和 tester 组成。中文可以理解为协调负责人、前端开发、后端开发和测试角色。它们不是四个窗口里轮流换人设，而是四个有不同任务边界的上下文。协调负责人接收目标并拆任务，专业开发者负责实现，测试角色独立检查结果，人的职责则是决定优先级、批准变更和合并 Pull Request。

Squad 仓库的 README 还展示了 scribe 这样的记录角色。它的价值不在于多写一份日报，而在于把团队运行过程中形成的决策、历史和工作痕迹写回仓库。协调者、开发者、测试者和记录者之间可以有重叠，但写入边界要明确，否则“共享记忆”很快会变成任何人都能修改的杂物间。

协调角色最好只做路由和状态管理，不要一边分派任务一边亲自改所有文件。这样它的上下文会比较干净，也不会因为自己先做了一个方案，就把后续所有智能体都带进同一个偏见里。前端角色只需要拿到界面和交互相关的仓库上下文，后端角色重点读取服务、数据模型和接口约定，测试角色则根据需求和现有行为构造验证。

这里还有一个容易被忽略的区别：多个角色不是在同一个上下文窗口里轮流发言。官方文章将这种方法称为“上下文复制”而不是“上下文切分”。每个专业角色有自己的推理上下文，同时读取与项目相关的文件。这样做会增加调用成本，却避免了让一个智能体把大量精力花在管理其他智能体的思考上。

角色分工的收益不是把人换掉，而是让人的检查点更清楚。人不必盯着四个窗口里每一句过程话，但需要看任务分配、关键决策、测试结果和最终变更。机器负责并行，人负责取舍，这比把“自主完成”当成目标更适合真实项目。

把共享记忆写进 decisions.md

很多多智能体系统把记忆放在外部向量数据库里，每次调用都查相似度，再把若干片段塞回上下文。Squad 走的是更容易审计的路径：把共享决策追加到版本化的decisions.md。官方文章把它称为 drop-box 模式。一个架构选择、一条命名约定或一次取舍，都可以作为结构化块写进这份文件。

文件记忆有一个外部数据库不容易提供的优点：它和代码的生命周期相同。你切换分支时能看到对应的决策，回滚提交时能一起回滚错误的判断，断线后也能从仓库恢复工作。新成员不需要翻几百条聊天记录，只要读团队文件和最近的提交，就能知道项目为什么采用当前方案。

但把所有信息都塞进一份长文档也会失控。适合进入共享决策的内容，应该是会影响其他人的稳定规则，例如接口版本如何同步、某类数据必须经过哪一层校验、某个依赖为什么不能升级。一次性的调试输出、个人猜测和没有验证的想法，应当留在个人历史或任务分支里，等证据充分后再提升。

在自建的仓库原生编排里，可以把写入过程分成提案、审核、接受三个状态。提案先进入单独目录或任务分支，审核者确认它有代码位置、测试证据和适用范围，再由有权限的角色合并到decisions.md。这不是为了制造流程，而是防止某个智能体把自己的偏好伪装成团队共识。

Squad 的另一个重要做法，是把成员身份拆成 charter 和 history。charter 说明它是谁、擅长什么、应该遵守什么边界；history 记录它在当前项目里学到了什么。两者都放在.squad中，意味着“智能体记得什么”不再是隐藏在模型权重或某个会话里的黑箱，而是可以被人阅读和修订的工程资产。

文件记忆并不意味着每次调用都要把全部历史塞进上下文。协调者可以先读团队决策，再按任务把相关文件路径交给专业角色；专业角色完成工作后，只把经过验证的变化写回自己的 history 或共享决策。这个顺序很重要：先缩小读取范围，再扩大共享范围。否则一份不断增长的决策文档会像另一个没有索引的聊天窗口，名字虽然变了，问题没有消失。

这种记忆还有一个现实好处：它能抵抗重启。外部会话结束后，模型不会自动保留全部现场；仓库中的决策、角色历史和提交记录却不会因为浏览器关掉就消失。对需要跨天推进的任务来说，恢复能力往往比一次回答的聪明程度更重要。

从版本控制角度看，决策文件还提供了时间线。某条约定在什么时候出现，后来被谁修改，修改后哪些测试跟着变化，都能通过提交记录还原。遇到“为什么不能这样改”的争论时，团队不必靠记忆投票，而是回到当时的任务、差异和验证结果。对智能体来说，这相当于给长期记忆加了一层可回放的来源。

评审协议怎样阻止同一个智能体自改

多智能体协作最隐蔽的坑，不是智能体不够聪明，而是自己写的东西自己审核等于没有审核。你让一个智能体写了认证代码，再让它检查自己的认证代码，它很可能只会重新解释原来的假设。问题不一定出在模型能力，而在评审关系没有独立性。

Squad 的协作方式把测试角色放在独立上下文里。后端角色先完成实现，测试角色针对行为运行测试；如果测试发现问题，修复动作不必回到原作者身上。GitHub 官方文章特别提到，评审协议可以阻止原作者直接修改被驳回的工作，让另一个智能体接手修复，形成真正的独立检查。

这套协议不靠提示词里写一句“请扮演 reviewer”来维持，而是让任务状态、分支和 Pull Request 记录承担约束。谁写了代码，谁提出了问题，哪个测试失败，哪次修复由谁完成，都可以在版本历史里找到。审查从一句礼貌建议变成了一条可追踪的工程记录。

评审也不能被包装成自动发布。Squad 的 README 明确把它描述为 human-directed 的开发团队，人的责任仍然包括优先级、审批和最终变更。比较稳妥的做法，是让智能体完成并行实现、测试和初审，再由人阅读差异、关注高风险文件，确认通过后合并。机器把等待时间压下来，人把错误扩散的边界守住。

如果团队不想一开始就引入完整工具链，也可以先只实现三个规则：作者和评审者不能是同一角色；所有共享决策必须有文件位置和测试依据；没有人工批准的分支不能进入主分支。规则很少，但能覆盖多智能体最容易失控的地方。

评审结果最好写成可执行的状态，而不是一句“看起来没问题”。例如把测试命令、影响文件和未解决风险记录在 Pull Request 描述中，协调者只根据这些证据决定是否继续路由。这样，智能体换了模型，甚至换了供应商，评审协议仍然成立。协议保护的是工程过程，不是某一次模型输出。

用最小脚本复现仓库原生编排

前面讲了很多机制，如果不能在本地跑起来，终究只是纸上谈兵。Squad 官方给出的路径是先安装命令行工具，再执行squad init，然后用copilot --agent squad --yolo打开团队。第一次启动时，系统会根据项目目标提出团队成员方案，确认后再进入工作阶段。Squad 目前仍是实验性软件，命令和接口可能随版本变化，生产项目应先在隔离仓库验证。

初始化后，可以先检查.squad目录。常见文件包括team.md、routing.md、decisions.md，以及保存成员 charter 和 history 的agents目录。它们是 Markdown 文本，不需要先搭消息队列，也不要求为了保存一条决策再部署一个向量库。

下面这段 Node.js 代码不依赖第三方包。它把一个经过人工确认的决策追加到仓库里的决策文件，演示的正是 drop-box 的最小落点。保存为record-decision.js后，在项目根目录执行node record-decision.js即可；传入的两个参数可以换成自己的内容。

const fs = require('node:fs'); const path = require('node:path'); const root = process.cwd(); const squadDir = path.join(root, '.squad'); const file = path.join(squadDir, 'decisions.md'); const decision = process.argv[2] || '所有接口变更先补充回归测试'; const reason = process.argv[3] || '避免并行开发时的行为漂移'; fs.mkdirSync(squadDir, { recursive: true }); const stamp = new Date().toISOString(); const block = `\n## ${stamp}\n- 决策：${decision}\n- 依据：${reason}\n`; fs.appendFileSync(file, block, 'utf8'); console.log(`已写入 ${file}`);

这段代码只负责记录，不负责替团队批准决策。真正接入 Agent 时，可以把写文件动作放在协调者的受控工具里，并要求提案带上任务编号、影响范围和验证命令。测试角色读取决策文件后，仍然要对当前分支重新运行测试，不能因为文件里写过一句“已经验证”就跳过事实检查。

如果要继续扩展，可以把路由规则放进routing.md，把成员约束放进各自的 charter，把运行记录放进单独的日志目录。每增加一个文件，都要先问它解决的是哪种协作问题。能被 Git 审查的文本越多，系统越容易恢复；没有明确用途的配置越多，团队越难判断哪条规则才有效。

从这里往上搭，才轮到模型选择、MCP 工具和并行策略。模型可以变化，工具也会变化，但仓库里的任务边界、决策证据和评审流程应当保持稳定。这样更换模型时，变的是执行者，不是项目的记忆和责任链。

这段最小代码也暴露了真实系统必须补上的三件事。写入前要检查当前分支，避免把别人的变更覆盖掉；写入内容要限制长度和字段，防止错误输出污染共享记忆；写入后要让测试或人工审核接手，不能把“文件成功写入”误当成“决策已经正确”。仓库只是事实载体，事实是否可靠仍然要靠验证链。

在实际项目里，还应给每条决策加上适用范围。比如一条关于数据库连接池的约定，可能只适用于服务端，而不适用于脚本工具；一条关于接口版本的约定，可能只对当前主分支有效。记录范围能避免智能体把局部经验推广成全局规则，也方便后续在项目结构变化后清理过期内容。

工具权限也应该跟角色分开。测试角色可以运行测试和读取日志，却没有必要拥有发布权限；文档角色可以修改说明文件，却不应直接改动认证逻辑。权限越接近任务边界，错误就越容易被限制在一个分支里。不要把所有工具都交给协调者，再期待它靠提示词记住每一种风险。

这套方法适合什么团队

如果你是一个人在维护一个小项目，Squad 不一定马上带来收益。你自己就是协调者、审核者和最终决策者，额外增加多个智能体可能只是增加管理成本。此时先把需求、测试和变更记录写清楚，效果可能比一开始搭完整团队更好。

它更适合需求多、人员紧、上下文经常断的团队。每次新来一个任务，智能体不必从空白会话重新询问项目背景；它可以读取已经提交的团队文件。新成员也能从仓库里看到项目约定，而不是依赖某位老成员记得哪些聊天内容。

它也适合需要并行处理不同边界的开发团队。例如一个人处理接口，一个人处理界面，另一个人准备测试。前提是任务真的可以拆开，而且合并点清晰。若几个人都在改同一个核心模块，强行并行只会把冲突推迟到合并时，仓库原生记忆也不能替你解决错误的任务切分。

采用之前还要看团队能不能接受三个变化：智能体配置会进入代码审查，决策文件会成为正式资产，自动化结果必须留下证据。如果大家只想要一个“问完就走”的聊天机器人，这套方法会显得笨重；如果大家已经在为上下文丢失、重复劳动和审查疲劳付出时间，它就有了落地的理由。

可以先用一个低风险任务试运行，例如补齐一组单元测试或整理接口文档，观察四个指标：任务是否能被拆开，角色之间是否重复修改，决策记录能否被新人看懂，人工审查是否真的变轻。试运行不需要把整个组织的开发流程一次改掉，先让仓库文件证明它能减少返工，再决定是否接入更多工具和更长的自动化链路。

试运行时不要只看生成速度快了多少。更值得记录的是返工次数、评审找到的问题类型、任务中断后能否恢复，以及新人能否在没有口头交接的情况下继续工作。如果速度上去了，返工和沟通成本却一起上升，团队得到的只是更快地产生混乱。仓库原生编排的价值，应该用整个交付环节的稳定性来衡量。

这也是为什么它更像开发流程改造，而不是一个新聊天插件。投入的时间主要花在整理边界和证据，而不是反复调教一句提示词。只要这部分规则能被提交、审查和恢复，团队就有机会把一次性的经验变成下一次任务可以直接复用的工作方式。

对个人开发者来说，也可以只借用其中一部分：用一份决策文件保存重要取舍，用一个独立测试角色检查高风险改动，用提交记录保存每次交接。先把最容易丢失的上下文留下来，再决定是否需要完整的多智能体团队。

这一步已经足以改变协作质量。

而且不需要先改造整套系统。

这就够用了。

多智能体真正进入团队，不靠把模型数量堆上去，而靠把角色、记忆、评审和证据写进团队每天都在使用的仓库。仓库不是智能体的临时工作台，而是它们共同接受约束、留下记录、等待人批准的地方。