244 lines
8.5 KiB
Markdown
244 lines
8.5 KiB
Markdown
# Codex 智能体管理台 AI 协作规范
|
||
|
||
本文件约束后续 AI 在本仓库中的开发、优化、审查和维护行为。所有非简单修改都必须先阅读并遵守本文件。
|
||
|
||
## 仓库快照
|
||
|
||
- 项目名称：`codex-agent-manager`
|
||
- 项目目的：提供一个本机 localhost 图形工具，用中文管理 Codex 智能体配置、查看项目内智能体运行情况、观察动态工作流进度和智能体交接。
|
||
- 后端：Go；必须支持只读 SQLite、TOML 解析、路径安全、备份与原子写回。
|
||
- 前端：Vue 3 + Vite；界面必须全中文。
|
||
- 数据来源：
|
||
- `/Users/yoilun/.codex/agents/*.toml`
|
||
- `/Users/yoilun/.codex/config.toml`
|
||
- `/Users/yoilun/.codex/state_5.sqlite`
|
||
- `/Users/yoilun/.codex/goals_1.sqlite`
|
||
- 本机 Codex 相关进程
|
||
- 项目内 `task_plan.md`、`findings.md`、`progress.md`、`docs/project.md`
|
||
- 默认运行环境：用户本机 macOS，本机访问，不设计云端多用户系统。
|
||
|
||
## 仓库地图
|
||
|
||
- `docs/superpowers/specs/`：设计规格文档。
|
||
- `task_plan.md`：实施阶段总计划、阶段状态和验收标准，实施开始后必须创建。
|
||
- `findings.md`：代码阅读、数据源、约束、风险和关键决策。
|
||
- `progress.md`：执行记录、测试结果、审查循环、已修改文件。
|
||
- `docs/project.md`：项目目标、架构、配置、运行方式、安全边界和恢复方式。
|
||
- `agent.md`：本文件，约束后续 AI 协作。
|
||
|
||
## 工作流要求
|
||
|
||
### 1. 非简单任务必须先计划
|
||
|
||
满足任一条件即为非简单任务：
|
||
|
||
- 需要 3 个以上步骤。
|
||
- 涉及架构、数据模型、跨文件修改或安全边界。
|
||
- 改变 UI、API、持久化、写回逻辑或工作流显示逻辑。
|
||
- 需要测试、构建、截图或审查链路验证。
|
||
|
||
非简单任务开始前必须创建或更新 `task_plan.md`，写明范围、风险、阶段和验证方式。
|
||
|
||
### 2. 必须使用文件化计划
|
||
|
||
实施阶段必须维护以下文件：
|
||
|
||
- `task_plan.md`
|
||
- `findings.md`
|
||
- `progress.md`
|
||
- `docs/project.md`
|
||
|
||
每个阶段开始前读取这些文件；每个阶段结束后更新状态、测试结果、审查结论和风险。
|
||
|
||
### 3. 每阶段必须代码审查
|
||
|
||
每个实现阶段必须有：
|
||
|
||
- coding agent：只负责当前阶段实现，不处理未来阶段，不做无关重构。
|
||
- testing/code review agent：只测试、审查和报告问题，不直接修改代码。
|
||
|
||
审查失败后，问题报告返回 coding agent 修复。每阶段最多 3 轮修复循环；连续 3 次仍失败，暂停并向用户报告。
|
||
|
||
### 4. 主智能体负责监管
|
||
|
||
主智能体必须：
|
||
|
||
- 拆分阶段。
|
||
- 派发子智能体。
|
||
- 维护计划文件。
|
||
- 判断阶段是否通过。
|
||
- 记录交接、审查、修复循环。
|
||
- 阶段通过后关闭当前阶段子智能体。
|
||
|
||
不要让子智能体自行扩大范围或改变阶段目标。
|
||
|
||
## 产品与 UI 规则
|
||
|
||
- 界面、按钮、状态、错误提示、文档标题默认使用中文。
|
||
- 技术缩写如 PID、TOML、SQLite、API 可以保留英文。
|
||
- 视觉方向是“温和的本地工作台 + 编辑器质感”，不要做成工业监控大屏。
|
||
- 不要使用大面积黑底荧光绿、密集硬边框、无解释的红绿灯状态或全页面等宽字体。
|
||
- 页面必须清楚区分：
|
||
- 项目视图：项目里的智能体执行情况、工作流批次、阶段进度、交接、审查循环、主智能体监管。
|
||
- 智能体视图：名称、描述、角色设定编辑。
|
||
- 草稿：TOML 校验、diff、备份、写回。
|
||
- 设置：Codex 路径和数据源配置。
|
||
- 状态必须显示来源和置信度，不允许只给一个无解释的状态点。
|
||
|
||
## 数据与安全边界
|
||
|
||
### 允许读取
|
||
|
||
- `.codex/agents/*.toml`
|
||
- `.codex/config.toml`
|
||
- `.codex/state_5.sqlite`
|
||
- `.codex/goals_1.sqlite`
|
||
- 本机进程表中与 Codex 相关的进程信息
|
||
- 用户项目内的工作流文件：`task_plan.md`、`findings.md`、`progress.md`、`docs/project.md`
|
||
|
||
### 禁止读取或展示
|
||
|
||
- `.codex/auth.json`
|
||
- 明显包含 token、密钥、cookie、Webhook 密钥的文件
|
||
- 与本工具无关的用户隐私内容
|
||
|
||
### 允许写入
|
||
|
||
- 本项目目录内文件。
|
||
- 用户确认后的 `.codex/agents/*.toml` 写回。
|
||
- 写回前创建的备份文件。
|
||
|
||
### 禁止写入
|
||
|
||
- `.codex/config.toml`，除非用户另行明确批准并有单独审查。
|
||
- `.codex/*.sqlite` 及其 WAL/SHM 文件。
|
||
- `.codex/auth.json`。
|
||
- 不在允许范围内的任意 Codex 配置或状态文件。
|
||
|
||
## 写回规则
|
||
|
||
写回 `.codex/agents/*.toml` 必须遵守以下顺序：
|
||
|
||
1. 生成草稿。
|
||
2. 校验 TOML。
|
||
3. 展示 diff。
|
||
4. 创建时间戳备份。
|
||
5. 用户确认。
|
||
6. 原子写回。
|
||
7. 显示结果和备份路径。
|
||
|
||
如果 TOML 无效、备份失败、目标文件已在校验后变化，必须阻止写回。
|
||
|
||
## 工作流显示规则
|
||
|
||
- 工作流必须建模为动态事件流或有向图，不允许写死固定流程。
|
||
- 项目内工作流必须先按“工作流批次”分组，再按阶段分组；同一项目的 `v1.0 初始搭建`、`v1.1 优化修复`、`v2.0 重构升级` 必须清楚区分。
|
||
- `thread_spawn_edges` 是派发关系的主要结构化来源。
|
||
- `threads` 表用于补充智能体昵称、角色、项目路径和更新时间。
|
||
- `thread_goals` 用于补充目标状态。
|
||
- 项目内计划文件用于识别阶段、审查循环和门禁证据。
|
||
- 没有计划文件时，只显示通用事件和推断，不强行命名阶段。
|
||
- 所有推断必须标注来源和置信度。
|
||
|
||
### 子智能体派发元数据
|
||
|
||
主智能体派发任何子智能体任务时，必须在任务标题、目标或首段说明中保留以下元数据，方便本项目页面从 Codex 运行记录中准确归类：
|
||
|
||
```text
|
||
[项目: /Users/yoilun/Code/codex-agent-manager]
|
||
[工作流批次: v1.1 优化修复]
|
||
[阶段: 优化阶段 1]
|
||
[角色: 代码审查员]
|
||
```
|
||
|
||
本项目当前已完成初始搭建后进入 `v1.1 优化修复`，当前优化改造归入 `优化阶段 1`。后续如果开启 `codex-agent-manager v2.0`，必须显式写成类似：
|
||
|
||
```text
|
||
[项目: /Users/yoilun/Code/codex-agent-manager]
|
||
[工作流批次: v2.0 重构升级]
|
||
[阶段: 阶段 1 产品规划]
|
||
[角色: 产品经理]
|
||
```
|
||
|
||
如果继续派发下一级子智能体，必须把同一组元数据继续传递给下一级任务。`项目` 必须写完整项目路径，不要只写项目名；不要只写“继续优化”或“修一下页面”，否则页面只能低置信度推断批次和阶段。
|
||
|
||
## 状态规则
|
||
|
||
运行状态至少包含：
|
||
|
||
- `运行中`
|
||
- `最近活跃`
|
||
- `空闲`
|
||
- `未知`
|
||
- `冲突`
|
||
|
||
每个状态必须包含：
|
||
|
||
- 中文说明。
|
||
- 数据来源。
|
||
- 置信度：高、中、低。
|
||
- 最近更新时间。
|
||
- 若为冲突，必须显示冲突原因。
|
||
|
||
## 代码规则
|
||
|
||
- 遵循项目既有结构；没有既有结构时，按设计规格中的模块划分创建。
|
||
- Go 后端应保持路径安全，所有访问都必须经过 Codex home 边界检查。
|
||
- SQLite 必须只读打开。
|
||
- TOML 解析失败不能导致服务崩溃。
|
||
- 文件写回必须可测试、可恢复、可解释。
|
||
- 不做无关重构。
|
||
- 不引入大型依赖来解决小问题。
|
||
- 不把 mock 数据混入真实数据路径；演示数据必须清楚标记。
|
||
|
||
## 文档规则
|
||
|
||
涉及下列内容时必须更新文档：
|
||
|
||
- 数据源变化。
|
||
- API 变化。
|
||
- 写回或备份策略变化。
|
||
- 运行命令变化。
|
||
- UI 导航或核心工作流变化。
|
||
- 安全边界变化。
|
||
|
||
`docs/project.md` 必须记录：
|
||
|
||
- 项目目标。
|
||
- 架构。
|
||
- 配置。
|
||
- 运行方式。
|
||
- 数据来源。
|
||
- 写回和恢复流程。
|
||
- 已知风险。
|
||
|
||
## 验证矩阵
|
||
|
||
实施后根据实际技术栈替换为具体命令。
|
||
|
||
- 后端变更：
|
||
- 运行后端单元测试。
|
||
- 覆盖 TOML 解析、路径限制、SQLite 只读、备份和写回失败场景。
|
||
- 前端变更：
|
||
- 运行构建或类型检查。
|
||
- 用浏览器检查项目视图、工作流视图、智能体视图、草稿页和设置页。
|
||
- 工作流模型变更：
|
||
- 验证有计划文件和无计划文件两种项目。
|
||
- 验证动态派生关系不会被固定模板误判。
|
||
- 写回变更：
|
||
- 验证备份成功后才能写回。
|
||
- 验证失败时原文件不变。
|
||
- 文档变更：
|
||
- 检查文档与实际命令、路径和安全边界一致。
|
||
|
||
## 完成定义
|
||
|
||
非简单任务只有满足以下条件才能结束：
|
||
|
||
1. 用户请求已完整覆盖。
|
||
2. 计划文件已更新。
|
||
3. 关键测试、构建或浏览器验证已执行。
|
||
4. 每阶段审查结果已记录。
|
||
5. 安全边界没有被放宽，或已获得用户明确批准。
|
||
6. 残余风险、未运行检查和假设已明确说明。
|