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