一份规则总章
AGENTS.md / CLAUDE.md 是每个 AI 开工前的必读:先协调再干活、分支怎么切、测试怎么算过、人类指令优先级最高。各个平台按需安装入口,规则只写一遍。
CROSS-PLATFORM MULTI-AGENT · 跨平台多 AI 协作 · v1.7.0 · MIT
让你使用的 Codex、Claude Code、Cursor 等 AI 助手 在不同窗口、不同工具里
对着同一份 AGENTS.md 干活:不互相覆盖、不重复劳动,
谁掉线了一目了然。规则与共享黑板只留本机,看板脚本零依赖,Python 3.8+ 直接跑。
它不是又一个 AI 编排器 —— 不负责启动 AI、不给每个 AI 隔离工作区(那是 Claude Squad、Conductor 这类工具的活)。 它管另一半:让已经在同一个项目里干活的多个 AI 会话互相可见、守同一套规矩、听你指挥。
AGENTS.md / CLAUDE.md 是每个 AI 开工前的必读:先协调再干活、分支怎么切、测试怎么算过、人类指令优先级最高。各个平台按需安装入口,规则只写一遍。
.multi-agent-collab/ 就是本机共享记忆:谁在哪个分支干什么、心跳还活不活、有问题问谁、前任走了怎么接手。全是几个 Markdown 小文件,不进 git,切分支不丢。
agents_session.py 登记会话、检查文件占用、更新心跳并收尾;agents_status.py 提供摘要和网页指挥台。两者都只需 Python 标准库。
规则全部来自真实产品 ego-link-esp32 (ESP32-S3 教学硬件 + Python 课堂服务器)在 15+ 个 AI 协作会话里出过的事故与复盘; 抽离为通用套件时,规则正文与排障手册已完全去技术栈化。
个 AI 协作会话的事故复盘
条 TROUBLESHOOTING 排障手册
项看板 selfcheck 内置断言
项回归用例(含策略、接管与平台适配)
操作系统 × Python 版本的 CI 矩阵
第三方依赖 · Python 3.8+ 标准库
开始任务用 agents_session.py start 登记 --files。文件与目录重叠时先协调,扩大范围先检查;状态按会话保存,worklog 只追加。
系统锁仅串行保护状态更新,进程退出会自动释放。心跳超过 15 分钟算失活,文件占用仍保留;接管计划需等待与确认,快照变化就停止,保留原提交和工作文件。
忘了注册会话的 AI 是隐形的。除看板外,还要交叉看 git reflog、文件 mtime、有没有构建进程在跑——三个信号都对上才下手。
独立目录默认写进 .gitignore:本机记录切分支不丢;共享入口已有的 Git 跟踪状态保持不变。代价是没有云端备份——重要节点把 .multi-agent-collab/ 拷到仓库外即可。
心跳长这样:绿色脉冲 = 会话还活着;灰点静止 = 已失联,别人可以在 inbox 声明接管。 长任务前写明预计返回时间,并在阶段间隙更新心跳;失活提醒不会自动让出文件。
# 图形化指挥台
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 看板无告警,可直接开工
按需安装的平台入口,最终指向同一份 AGENTS.md 和启动清单。
保留项目原规则,各平台通过简短入口读取独立协作总章。
图中以六个会话为例:共享记录,协同工作。下方可搜索并选择受支持的平台。
需要 Python 3.8+、Git 和一个已有的 Git 项目。
套件放在用户主目录 ~/multi-agent-collab,多个项目共用同一个安装器。
选择当前项目使用的平台,查看文件,再复制对应提示词。
YOUR TOOLS / YOUR PROJECT
没有匹配的平台。清空搜索可查看全部。
流程不明确时,提示词会先确认。自定义基线和前缀可通过安装器设置。
未选平台时,提示词会让 AI 先确认你正在使用的平台。
另维护 Git 本地忽略。后续新增平台会保留已经安装的入口与协作记录。
帮我把 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 跟踪状态的冲突,再说明具体情况让我决定。
# 仅第一次下载时运行;已经存在则核对后复用
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 .
安装后,确认真实生效
.multi-agent-collab/RULES.md 第 6 节,把示例换成你项目真实的测试 / 构建命令(定制区,升级自动保留)doctor,再运行 python .multi-agent-collab/tools/agents_status.py --brief,检查入口与忽略规则.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 项断言自检 |
site/ 目录跑 python -m http.server 8080 再访问 http://localhost:8080。