# 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 项：数据、权限、批量操作、资源链路相关改动默认视为高风险。