gongxiangp2/docs/CODEX_MULTI_AGENTS.md

Codex Multi-agents 团队方案

本文件只服务当前项目，不写入全局配置。

1. 团队目标

把 Codex 5.4 的内置多代理能力，升级成适合本项目的“项目级协作流程”，重点解决：

• 任务拆分更准
• 审查范围更全
• UI 统一性有专门审查
• 发布前有明确门禁
• 输出格式统一，方便复核

2. 团队结构

核心 5 角

1. orchestrator

   • 拆解任务
   • 选择需要出动的角色
   • 汇总冲突意见
   • 给最终执行顺序
   • 作为团队唯一对外接口，直接和用户沟通

2. backend

   • 审查接口、数据、存储、转码、权限、日志链路
   • 重点目录：app/api/**、lib/**、prisma/**

3. frontend

   • 审查页面交互、状态流、用户路径
   • 重点目录：app/**、components/**、hooks/**

4. ui_auditor

   • 审查颜色、字体、间距、圆角、阴影、组件状态一致性
   • 默认优先输出问题，不直接主导业务改动

5. release_gate

   • 汇总所有角色输出
   • 按证据判定：
     • 可上线
     • 有条件上线
     • 不可上线

2.1 对话方式

• 用户默认只和 orchestrator 对话。
• orchestrator 负责理解需求、追问缺口、决定是否派发子代理。
• 子代理默认不直接对用户说话，只向 orchestrator 回传结果。
• orchestrator 对外输出的内容应是整理后的统一结论，而不是把子代理原文直接堆给用户。

辅助 2 角

6. explorer

   • 适合先做跨文件摸底、找影响范围、找入口文件
   • 不承担最终结论

7. worker

   • 适合在边界明确后，处理单一子任务的修改
   • 不能替代主控做总调度

3. 三种工作模式

A. 审查模式

适用场景：

• 上线前检查
• 大改前摸底
• 不确定该不该动代码

推荐编组：

• orchestrator
• backend
• frontend
• ui_auditor
• release_gate

B. 修复模式

适用场景：

• 已经确定问题所在，需要定点修改
• 既要修功能，也要看 UI 回归

推荐编组：

• orchestrator
• explorer
• backend 或 frontend
• worker
• 需要时追加 ui_auditor

C. 发布模式

适用场景：

• 发版前最终门禁
• 需要形成可复核结论

推荐编组：

• orchestrator
• backend
• frontend
• ui_auditor
• release_gate

4. 调度规则

本项目默认采用“用户只对 orchestrator 提需求，由 orchestrator 自动派单”的方式。

自动派单总原则

• 用户不需要手动指定角色。
• orchestrator 负责判断是否启用团队，以及需要出动哪些角色。
• 如果任务很小，允许不启用完整团队。
• 如果任务高风险、影响范围大、或准备上线，优先扩大编组。

仅后端类任务

例如：

• 下载
• 上传
• 转码
• 批量删除
• 外部接口
• 管理后台统计接口

推荐角色：

• orchestrator
• backend
• 必要时加 release_gate

仅前端类任务

例如：

• 首页
• 分享页
• 上传弹窗
• 管理后台页面

推荐角色：

• orchestrator
• frontend
• ui_auditor

全链路联动任务

例如：

• 上传后展示异常
• 后台统计与页面表现同时改
• 下载接口和前端下载入口一起变

推荐角色：

• orchestrator
• backend
• frontend
• ui_auditor
• release_gate

影响范围不清的任务

例如：

• 不确定问题在前端还是后端
• 不确定影响几个目录
• 只是看到现象，还没看到根因

推荐角色：

• orchestrator
• explorer

说明：

• 先摸底，再扩编
• 避免一开始全员出动造成重复劳动

5. 每个角色的标准输出

orchestrator

• 任务目标
• 角色分派
• 依赖关系
• 验收标准
• 风险分级

backend

• 发现的问题
• P0 / P1 / P2
• 影响接口或数据范围
• 修复建议
• 验证清单

frontend

• 发现的问题
• P0 / P1 / P2
• 影响页面和交互路径
• 修复建议
• 验证清单

ui_auditor

• 视觉一致性问题
• 组件一致性问题
• 页面级问题
• 必须统一项
• 可迭代项

release_gate

• 门禁汇总
• 是否可上线
• 阻塞项
• 上线前必须完成项
• 上线后观察项

6. 发布判定规则

• 任一 P0 未关闭：不可上线
• 关键链路未验证：不可上线
• 只有可控 P1，且有回滚方案：有条件上线
• 无阻塞项，验证通过：可上线

6.2 默认门禁严格度

• 当前项目默认采用“偏严格”的发布门禁。
• 原因：
  • 项目已经在线上运行
  • 任务经常跨前后端和 UI
  • 用户默认不是程序员，应该尽量减少“技术上能上线、实际很难判断风险”的情况

默认解释如下：

• 严格拦截

  • 只要有 P0
  • 只要关键链路没验证
  • 只要没有明确回滚路径
  • 结论就是 不可上线

• 有限放行

  • 如果只有少量 P1
  • 且不影响核心链路
  • 且有明确回滚方案和后续跟踪项
  • 可以给 有条件上线

• 正常放行

  • 没有 P0
  • 核心链路验证通过
  • UI 没有明显破坏统一性的问题
  • 就给 可上线

6.3 高风险边界

当前项目默认把下面这些改动视为高风险：

• 数据类

  • 数据库写入
  • 批量更新
  • 批量删除
  • 数据恢复
  • 会影响现有线上数据结果的逻辑调整

• 权限类

  • 登录后权限判断
  • 角色判断
  • 管理员能力
  • 下载资格
  • 外部接口访问控制

• 批量与资源类

  • 上传
  • 下载
  • 转码
  • 批量操作
  • 外部接口
  • 后台导出
  • 操作日志与审计记录

对应规则：

• 命中高风险边界时，orchestrator 默认至少启用 backend
• 同时影响页面体验时，追加 frontend
• 同时影响视觉统一时，追加 ui_auditor
• 需要上线判断、范围大、或风险不清时，追加 release_gate
• 高风险任务默认采用更保守的门禁和验证要求

6.1 UI 基线

• 当前项目的 UI 统一标准默认以首页为基线。
• 基线文件：app/page.tsx
• ui_auditor 审查其它页面时，默认对齐以下维度：
  • 视觉语言
  • 主按钮样式
  • 标题与信息层级
  • 间距与留白节奏
  • loading / empty / error / success 状态反馈
• 如果某个页面因为管理后台密度、特殊业务流程或设备限制必须偏离首页风格，需要单独说明理由，不默认视为统一标准。

7. 推荐用法

进入本项目后，如果要启用内置多代理，建议以当前项目目录启动，并在任务里明确写出采用哪种模式。

当用户明确写出下面这些触发语时，orchestrator 默认应真正派发子代理，而不是只停留在口头说明：

• “按项目的审查模式处理这次改动”
• “按项目的修复模式处理这次任务”
• “按项目的发布模式做门禁”
• “用项目团队处理”
• “启用 Multi-agents”

示例表达：

• “按项目的审查模式处理这次改动。”
• “按项目的修复模式先拆任务，再定点修改。”
• “按项目的发布模式做一次完整门禁。”

如果当前 Codex 会话未启用多代理能力，可在启动时临时开启，不写入全局：

codex --enable multi_agent -C "D:\AI Code\gongxiangp2"

8. 目前还不能自动决定的四件事

这些问题我已经预留好团队位置，但还需要你和我一个一个定：

1. UI 统一标准到底以哪套页面为基线
2. 发布门禁的阈值要多严格
3. 哪些任务必须全队出动，哪些只需要局部编组
4. 数据、权限、批量操作的高风险边界怎么划

当前已确定第 1 项：UI 基线默认以首页为准。 当前已确定第 2 项：发布门禁默认采用偏严格标准。 当前已确定第 3 项：用户只和 orchestrator 对话，由 orchestrator 自动派单。 当前已确定第 4 项：数据、权限、批量操作、资源链路相关改动默认视为高风险。