yovision/docs/11-multi-agent-collaboration.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Multi-Agent-Collaboration wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Multi-Agent-Collaboration.- wiki_revision: cc4031224ddd5855250a2441edd53d54baf73b5a synchronized_at: 2026-08-11T11:00:04Z

多 Agent 协作

目标

三名主 agent 尽量并行推进 Sense、Brain、Bell 的独立工单；只有跨项目契约、根级构建或端到端流程需要协作时，才建立协调工单并启用新的协调 agent。

固定建单顺序

客户交付需要三项目并行时，建单必须分为两个阶段：

1. Sense、Brain、Bell 三个项目 agent 并行只读分析并创建各自独立功能工单。每个工单只有一个主项目、一个主 agent 和一组不重叠的 write_paths。
2. 三个项目 agent 只记录协同需求摘要，不在首轮创建共享契约、根级编排或端到端工单，也不取得其他项目或 contracts/ 的写入权。
3. 三端独立工单返回后，主 agent / dispatcher 统一汇总、去重，检查前置依赖、写路径冲突、事实源归属和验收闭环。
4. 汇总完成后，主 agent 再创建共享契约、根级构建/部署、机器鉴权和端到端验收等协同工单，并指定单一 coordination agent。

建单顺序不等于实施顺序。独立登录、项目骨架和合成输入纵切可以先并行；依赖共享契约的实现必须等待协同工单冻结版本。不得为赶进度共享数据库、JWT、Cookie，或让三个项目各复制一份相似契约。

每个单元工单必须填写任务类型、主项目、主 agent、精确 write_paths 和各项目验证。协同工单还必须填写生产者、消费者、契约事实源、兼容策略、被阻塞/适配工单和集成顺序。

固定所有权

角色	默认写路径	禁止默认写入
Sense agent	Sense/**	Brain/**、Bell/**、contracts/**、根级共享文件
Brain agent	Brain/**	Sense/**、Bell/**、contracts/**、根级共享文件
Bell agent	Bell/**	Sense/**、Brain/**、contracts/**、根级共享文件
协调 agent	工单明确列出的 contracts/**、根文件、端到端测试和必要三端适配点	未列入工单的相邻功能

同一路径及父子目录视为冲突。文件少并不允许多个 agent 同时写；单写入者比事后合并更重要。

工单类型

单项目工单

• 只有一个主项目和一个主 agent。
• write_paths 只能覆盖本项目目录及明确的 Wiki 页面。
• 不修改共享契约；若发现契约需要变化，停止并提出协调工单。
• 只运行本项目和必要回归验证。

协调工单

适用于：

• 新增/修改 OpenAPI、JSON Schema、SQL 共享契约；
• Sense↔Brain、Brain/Sense→Bell 端到端链路；
• 根级 CI、compose、版本清单或发布编排；
• 同一验收必须跨两个以上项目才能成立。

协调工单必须写明：生产者、消费者、契约唯一事实来源、兼容策略、各端适配工单、集成顺序、回退和全套验证。协调 agent 是共享路径的唯一写入者；主 agent 可以提供只读分析或在不重叠的分支工单实施各自适配。

推荐并行模型

Epic / MVP
├─ Sense 单元工单 ── Sense agent
├─ Brain 单元工单 ── Brain agent
├─ Bell 单元工单 ─── Bell agent
└─ 集成协调工单 ──── coordination agent
      ├─ 冻结 contracts 版本
      ├─ 汇总三端适配状态
      └─ 运行端到端验收

协调工单可以先冻结契约，三个适配工单再并行；契约未冻结前不得用复制字段、共享表或临时 JWT 打通。

领取与交接

1. 领取前检查前置工单、活跃 agent 和写路径重叠。
2. Issue 记录主 agent、分支、精确写路径、契约版本和验证命令。
3. 新增写路径必须先更新工单并由 dispatcher/负责人复核。
4. 交接记录已完成事实、未完成步骤、测试证据、工作区状态和风险，不复制内部推理。
5. 一个 agent 同时最多一个活跃主工单；只读评审不取得写路径所有权。

Git 与集成建议

• 分支建议：agent/<agent-id>/<issue>-<short-name>。
• 每个工单独立提交和 PR；提交信息引用 Issue。
• 不通过长期共享工作树让三个 agent 同时写；使用独立 worktree/分支或平台隔离工作区。
• 共享契约先合并或固定 revision，再让消费者适配；不能各自维护“差不多”的 schema。
• PR 合并前检查默认分支上的契约版本与任务证据，避免基于过期分支验收。

验证矩阵

变化	最少验证
Sense 内部	Sense 单测/集成测试、凭据泄露检查
Brain 内部	Brain 单测、合成输入、事件 schema
Bell 内部	Bell 单测/数据库/状态机测试
事件契约	Schema 校验、Brain/Sense 生产者测试、Bell 消费者与幂等测试
证据契约	Sense/Brain 生成、Bell 授权请求、降级和超时测试
根级部署	三端独立启动、停止任一产品的隔离测试、端到端测试

停止条件

• 两个 agent 的写路径出现重叠；
• 需要修改共享契约但没有协调工单；
• 需要跨库查询、共享用户/JWT/Cookie 或摄像头凭据；
• 契约破坏性变化没有新版本和回退；
• 三端对字段语义存在分歧且无法从事实源裁决。