CROSS-PLATFORM MULTI-AGENT · 跨平台多 AI 协作 · v1.7.0 · MIT

多个平台,一个项目。 一块黑板,一套规矩。

让你使用的 Codex、Claude Code、Cursor 等 AI 助手 在不同窗口、不同工具里 对着同一份 AGENTS.md 干活:不互相覆盖、不重复劳动, 谁掉线了一目了然。规则与共享黑板只留本机,看板脚本零依赖,Python 3.8+ 直接跑。

.multi-agent-collab/ 共享黑板 LIVE
  • sessions/ 3 个会话 · 谁在哪个分支
  • worklog/ 今日 4 条 · 做完了什么
  • inbox/ 1 条待答 · 问谁、谁接手
MULTI-PLATFORM ▸ ONE BOARD 点击画面 = 下发一条人类指令
01WHAT它是什么

AI 各干各的, 规矩只有一套。

它不是又一个 AI 编排器 —— 不负责启动 AI、不给每个 AI 隔离工作区(那是 Claude Squad、Conductor 这类工具的活)。 它管另一半:让已经在同一个项目里干活的多个 AI 会话互相可见、守同一套规矩、听你指挥。

PILLAR 01

一份规则总章

AGENTS.md / CLAUDE.md 是每个 AI 开工前的必读:先协调再干活、分支怎么切、测试怎么算过、人类指令优先级最高。各个平台按需安装入口,规则只写一遍。

PILLAR 02

一块共享黑板

.multi-agent-collab/ 就是本机共享记忆:谁在哪个分支干什么、心跳还活不活、有问题问谁、前任走了怎么接手。全是几个 Markdown 小文件,不进 git,切分支不丢。

PILLAR 03

一组协作命令

agents_session.py 登记会话、检查文件占用、更新心跳并收尾;agents_status.py 提供摘要和网页指挥台。两者都只需 Python 标准库。

没有它有 MULTI-AGENT-COLLAB
文件被覆盖 两个 AI 改了同一处,后保存的把先保存的覆盖掉,白干一半 先登记任务和文件范围;同工作区或重叠范围会被拦截,独立 worktree 可处理不同文件
重复劳动 两个 AI 各自去修同一个 bug,改动最后冲突 开工先看板 + 必查 open PR,判活三信号交叉验证
干到一半失踪 窗口被关掉,没人知道它改到哪、下一步是什么 会话注册 + 15 分钟心跳;失联接管先核对计划、等待与确认,保留原提交和工作文件
想喊停 「先别碰那个文件」没有任何途径告诉它们 人类指令走 inbox,优先级最高,看板实时显示回复闭环
02LOG规则来自事故

每条规矩, 都拿事故换的。

规则全部来自真实产品 ego-link-esp32 (ESP32-S3 教学硬件 + Python 课堂服务器)在 15+ 个 AI 协作会话里出过的事故与复盘; 抽离为通用套件时,规则正文与排障手册已完全去技术栈化。

0+

个 AI 协作会话的事故复盘

0

条 TROUBLESHOOTING 排障手册

0

项看板 selfcheck 内置断言

0

项回归用例(含策略、接管与平台适配)

0×0

操作系统 × Python 版本的 CI 矩阵

0

第三方依赖 · Python 3.8+ 标准库

事故现场 SYMPTOM▸写进规矩的姿势 RULE
两个 AI 改了同一个文件,后保存的把先保存的覆盖掉,白干一半 → 先声明文件范围:会话工具串行检查并登记占用;按会话保存状态,日志只追加,冲突先协调
两个 AI 各自去修同一个 bug,改动最后冲突 → 开工先协调:fetch → 看板一行摘要 → 读 inbox → 必查 open PR,再动手
一个 AI 干到一半窗口被关掉,没人知道它改到哪、下一步是什么 → 会话注册 + 心跳:超 15 分钟仍保留占用;接管需检查、声明、等待 5 分钟与用户确认,并保留原文件
每个平台的规则文件各写各的,换个 AI 工具就等于没有规则 → 一份 AGENTS.md:面向 coding agent 的开放格式,各平台按需使用入口,内容同一份
想中途喊一句「先别碰那个文件」,没有任何途径告诉它们 → 人类指令通道:从看板网页直接下发,落盘成标准 inbox 留言条,手头任务都要为它让路
看板显示「无活跃会话」,以为没人,上手就是覆盖别人的改动 → 判活三信号交叉:看板 + git reflog / 文件 mtime + 构建进程,不 registered 的 AI 是隐形的
03SOP四条交规

四条交规, 写在 AGENTS.md 里。

RULE 01 · 文件纪律

先声明范围,再修改文件

开始任务用 agents_session.py start 登记 --files。文件与目录重叠时先协调,扩大范围先检查;状态按会话保存,worklog 只追加。

RULE 02 · 判活方式

心跳判活,系统锁保护登记

系统锁仅串行保护状态更新,进程退出会自动释放。心跳超过 15 分钟算失活,文件占用仍保留;接管计划需等待与确认,快照变化就停止,保留原提交和工作文件。

RULE 03 · 交叉验证

看板上没人 ≠ 真的没人

忘了注册会话的 AI 是隐形的。除看板外,还要交叉看 git reflog、文件 mtime、有没有构建进程在跑——三个信号都对上才下手。

RULE 04 · 数据边界

协作文件只留本机,不进 git

独立目录默认写进 .gitignore:本机记录切分支不丢;共享入口已有的 Git 跟踪状态保持不变。代价是没有云端备份——重要节点把 .multi-agent-collab/ 拷到仓库外即可。

心跳长这样:绿色脉冲 = 会话还活着;灰点静止 = 已失联,别人可以在 inbox 声明接管。 长任务前写明预计返回时间,并在阶段间隙更新心跳;失活提醒不会自动让出文件。

04TOWER你的指挥台

AI 看文件, 你看网页。

  • 01每 5 秒自动刷新。每个 AI 一张卡片:哪个平台、在哪个分支、做什么任务、几分钟前还有心跳(绿 = 正常,红 = 失联)。
  • 02问题与交接一眼可见。未答复的 inbox 留言、前任留下的「下一步 / 阻塞点」,不用去翻文件。
  • 03worktree 告警。有 AI 在没登记过的目录里动了手脚,红色告警直接拍在页面上。
  • 04直接对 AI 下指令。在卡片上输入「先停一下,别碰登录模块」——AI 在下个阶段间隙读到并执行,回复实时回到网页,可开桌面通知。人类指令优先级最高。
  • 05三档安全。默认只听本机;局域网可以只读大屏,或设密码后可指挥——「对外可写又无密码」的组合会被拒绝启动。
127.0.0.1:8731 · python .multi-agent-collab/tools/agents_status.py --web
演示数据 · demo-shop 项目里四个平台协作。打开交互演示 →
terminal · powershell / bash
# 图形化指挥台
python .multi-agent-collab/tools/agents_status.py --web

# 单文件快照(不需要服务)
python .multi-agent-collab/tools/agents_status.py --html

# AI 开工协调用的一行摘要
python .multi-agent-collab/tools/agents_status.py --brief
# 示例输出:OK 看板无告警,可直接开工
05MAP协作拓扑

不同平台, 同一块黑板。

按需安装的平台入口,最终指向同一份 AGENTS.md 和启动清单。 保留项目原规则,各平台通过简短入口读取独立协作总章。 图中以六个会话为例:共享记录,协同工作。下方可搜索并选择受支持的平台。

平台会话共享黑板 .multi-agent-collab/你 · 人类指令 拖拽旋转 · 数据包 = 会话读规则 / 写心跳 / 读指令
06GO按需安装

下载一次, 按需接入。

需要 Python 3.8+、Git 和一个已有的 Git 项目。 套件放在用户主目录 ~/multi-agent-collab,多个项目共用同一个安装器。 选择当前项目使用的平台,查看文件,再复制对应提示词。

YOUR TOOLS / YOUR PROJECT

这个项目,你用哪些 AI?

选择当前项目使用的平台,可多选

流程不明确时,提示词会先确认。自定义基线和前缀可通过安装器设置。

未选平台时,提示词会让 AI 先确认你正在使用的平台。

查看将安装的协作文件

    另维护 Git 本地忽略。后续新增平台会保留已经安装的入口与协作记录。

    发给目标项目里的 AI · 跟随上方选择
    帮我把 multi-agent-collab 安装到当前项目,并验证所选平台的新对话入口。
    套件仓库:https://github.com/AiFLYF/multi-agent-collab
    
    1. 检查 Python 3.8+ 和 Git,确认当前项目的 Git 根目录并记下绝对路径 TARGET。缺依赖时说明,不自行安装软件或 git init。
    2. 优先根据当前对话确认正在使用的平台并告诉我;无法确认时先问我使用哪些平台(可多选):codex、claude、opencode、pi、trae、workbuddy、cursor、copilot、windsurf、gemini、qwen、cline、roo、continue、kiro。使用对应的 --platforms 名称;不要根据电脑里装过哪些软件就全部安装。
       读取项目现有分支约定与 .multi-agent-collab/policy.json;已有策略沿用,首次安装按已确认流程选择 git-flow、github-flow 或 custom。只有 main 的项目可使用 github-flow;无法确认时只询问分支流程,不擅自建立 develop 或改变远端结构。
    3. 套件默认放在用户主目录的 multi-agent-collab:Windows 为 $HOME\multi-agent-collab,macOS/Linux 为 ~/multi-agent-collab。这里是可供多个项目复用的源码目录,不要 clone 到 TARGET 内。
       目录不存在时执行 git clone https://github.com/AiFLYF/multi-agent-collab "<用户主目录>/multi-agent-collab"。已存在时核对 origin 和 install.py 后复用;来源不符或有本地修改时保留现场并说明,不覆盖、不删除、不重置。只有确认工作区干净且配置了上游后,才用 git pull --ff-only 更新。
    4. 使用绝对路径运行 python "<套件目录>/install.py" install "<TARGET>" --platforms <已选名称> --dry-run;首次安装附加已确认的 --workflow 参数,自定义流程还要 --base-branch 和 --task-prefixes。核对文件清单与分支策略后执行同一条命令去掉 --dry-run;不要默认 all。只选原生平台时不生成其它平台配置。
    5. 新安装把套件规则、工具、记录放入 .multi-agent-collab/,默认在项目 .gitignore 的标记区忽略该目录;平台入口按精确路径写入 .git/info/exclude。已有 AGENTS.md 等共享入口保留原文,只维护小段标记。已跟踪入口的差异正常显示,不取消跟踪,不隐藏索引改动。来源不明的独立目录、损坏标记或被修改的套件文件先报告并保留现场。
    6. 结合项目真实配置填写 .multi-agent-collab/RULES.md 第 6 节缺少的测试/构建命令,项目既有测试要求和已确认策略继续有效。保留已有规则、会话、日志和备份。旧版安装沿用 .agents/ 路径,不自动搬迁;新增平台使用 sync。
    7. 执行 python "<套件目录>/install.py" doctor "<TARGET>",并核对 git status --short;可用 clients "<TARGET>" --versions 检查 CLI 可用性,不启动模型。汇报套件复用路径、已选平台、项目分支策略、生成文件和体检结果;解释 WARN,版本查询不代表新对话已加载规则。
    8. 告诉我新开对话验证:让 agent 读取 .multi-agent-collab/START_HERE.md,报告当前分支、看板和 inbox 的实际结果。之后增加平台用 sync "<TARGET>" --platforms <新增名称>,无需重复 clone;旧对话需要主动重新读取规则。
    
    执行安装范围内可恢复的修复即可;遇到需要改变现有项目规则或 Git 跟踪状态的冲突,再说明具体情况让我决定。
    • AI 会核对主目录中的套件副本、按选择安装并体检,已有副本直接复用
    • 当前平台明确时直接使用;不明确时先询问。使用 fork 可替换仓库地址
    terminal
    # 仅第一次下载时运行;已经存在则核对后复用
    git clone https://github.com/AiFLYF/multi-agent-collab "$HOME/multi-agent-collab"
    
    # 在目标项目目录运行,首次会询问平台
    python "$HOME/multi-agent-collab/install.py" install .
    python "$HOME/multi-agent-collab/install.py" doctor .
    
    # 刷新已选平台入口
    python "$HOME/multi-agent-collab/install.py" sync .
    • 命令兼容 Bash 与 PowerShell;请在目标项目目录执行。clone 只在首次下载时运行
    • 后续新增平台用 sync --platforms 名称;升级核心规则用 install,都会沿用已保存的选择

    安装后,确认真实生效

    1. ① 打开项目里的 .multi-agent-collab/RULES.md 第 6 节,把示例换成你项目真实的测试 / 构建命令(定制区,升级自动保留)
    2. ② 执行安装器 doctor,再运行 python .multi-agent-collab/tools/agents_status.py --brief,检查入口与忽略规则
    3. ③ 新开一个 AI 对话,确认它实际读取 .multi-agent-collab/START_HERE.md,并报告分支、看板和 inbox 的当前结果
    命令速查 · 点击行内命令即可复制
    命令作用
    python .multi-agent-collab/tools/agents_status.py --brief一行摘要:无事只回 OK,AI 开工首选
    python .multi-agent-collab/tools/agents_status.py完整终端看板
    python .multi-agent-collab/tools/agents_status.py --web图形化看板,可直接对 AI 下指令
    python .multi-agent-collab/tools/agents_status.py --html导出零外链单文件 HTML 快照
    python .multi-agent-collab/tools/agents_status.py --json结构化输出,给脚本用
    python .multi-agent-collab/tools/agents_status.py --selfcheck看板内置 48 项断言自检

    ✓ 适合

    • 同一台电脑、同一个 git 工作区
    • 多个 AI 会话(含真人)同时干活
    • 不想搭任何服务器、任何账号
    • 和 Claude Squad / Conductor 这类编排器叠加使用

    ? 想清楚再用

    • 跨电脑协作(需要真正的远程同步,本工具刻意不做)
    • AI 之间要毫秒级实时通信(这里最快是「下次工具调用时读到留言」)
    • AI 完全不遵守 AGENTS.md(退回最朴素规矩:同一时间一个 AI 动一个文件)
    • 想把 AGENTS.md 提交进仓库全团队共享(本套件取舍:规则本机私有、各自定制)
    检测到你是直接双击打开的 本页信号流与拓扑图全部走本地资源,画布场景可以直接看;仅自托管字体会被浏览器的 file:// 策略拦下,回退为系统字体。想完全还原,在 site/ 目录跑 python -m http.server 8080 再访问 http://localhost:8080。