docs: add codex agent manager design
This commit is contained in:
Yoilun
5
.gitignore
vendored
Normal file
5
.gitignore
vendored
Normal file
@@ -0,0 +1,5 @@
|
||||
.DS_Store
|
||||
.superpowers/
|
||||
dist/
|
||||
node_modules/
|
||||
*.log
|
||||
221
agent.md
Normal file
221
agent.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 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 无效、备份失败、目标文件已在校验后变化，必须阻止写回。
|
||||
|
||||
## 工作流显示规则
|
||||
|
||||
- 工作流必须建模为动态事件流或有向图，不允许写死固定流程。
|
||||
- `thread_spawn_edges` 是派发关系的主要结构化来源。
|
||||
- `threads` 表用于补充智能体昵称、角色、项目路径和更新时间。
|
||||
- `thread_goals` 用于补充目标状态。
|
||||
- 项目内计划文件用于识别阶段、审查循环和门禁证据。
|
||||
- 没有计划文件时，只显示通用事件和推断，不强行命名阶段。
|
||||
- 所有推断必须标注来源和置信度。
|
||||
|
||||
## 状态规则
|
||||
|
||||
运行状态至少包含：
|
||||
|
||||
- `运行中`
|
||||
- `最近活跃`
|
||||
- `空闲`
|
||||
- `未知`
|
||||
- `冲突`
|
||||
|
||||
每个状态必须包含：
|
||||
|
||||
- 中文说明。
|
||||
- 数据来源。
|
||||
- 置信度：高、中、低。
|
||||
- 最近更新时间。
|
||||
- 若为冲突，必须显示冲突原因。
|
||||
|
||||
## 代码规则
|
||||
|
||||
- 遵循项目既有结构；没有既有结构时，按设计规格中的模块划分创建。
|
||||
- Go 后端应保持路径安全，所有访问都必须经过 Codex home 边界检查。
|
||||
- SQLite 必须只读打开。
|
||||
- TOML 解析失败不能导致服务崩溃。
|
||||
- 文件写回必须可测试、可恢复、可解释。
|
||||
- 不做无关重构。
|
||||
- 不引入大型依赖来解决小问题。
|
||||
- 不把 mock 数据混入真实数据路径；演示数据必须清楚标记。
|
||||
|
||||
## 文档规则
|
||||
|
||||
涉及下列内容时必须更新文档：
|
||||
|
||||
- 数据源变化。
|
||||
- API 变化。
|
||||
- 写回或备份策略变化。
|
||||
- 运行命令变化。
|
||||
- UI 导航或核心工作流变化。
|
||||
- 安全边界变化。
|
||||
|
||||
`docs/project.md` 必须记录：
|
||||
|
||||
- 项目目标。
|
||||
- 架构。
|
||||
- 配置。
|
||||
- 运行方式。
|
||||
- 数据来源。
|
||||
- 写回和恢复流程。
|
||||
- 已知风险。
|
||||
|
||||
## 验证矩阵
|
||||
|
||||
实施后根据实际技术栈替换为具体命令。
|
||||
|
||||
- 后端变更：
|
||||
- 运行后端单元测试。
|
||||
- 覆盖 TOML 解析、路径限制、SQLite 只读、备份和写回失败场景。
|
||||
- 前端变更：
|
||||
- 运行构建或类型检查。
|
||||
- 用浏览器检查项目视图、工作流视图、智能体视图、草稿页和设置页。
|
||||
- 工作流模型变更：
|
||||
- 验证有计划文件和无计划文件两种项目。
|
||||
- 验证动态派生关系不会被固定模板误判。
|
||||
- 写回变更：
|
||||
- 验证备份成功后才能写回。
|
||||
- 验证失败时原文件不变。
|
||||
- 文档变更：
|
||||
- 检查文档与实际命令、路径和安全边界一致。
|
||||
|
||||
## 完成定义
|
||||
|
||||
非简单任务只有满足以下条件才能结束：
|
||||
|
||||
1. 用户请求已完整覆盖。
|
||||
2. 计划文件已更新。
|
||||
3. 关键测试、构建或浏览器验证已执行。
|
||||
4. 每阶段审查结果已记录。
|
||||
5. 安全边界没有被放宽，或已获得用户明确批准。
|
||||
6. 残余风险、未运行检查和假设已明确说明。
|
||||
434
docs/superpowers/specs/2026-05-25-codex-agent-manager-design.md
Normal file
434
docs/superpowers/specs/2026-05-25-codex-agent-manager-design.md
Normal file
@@ -0,0 +1,434 @@
|
||||
# Codex 智能体管理台设计规格
|
||||
|
||||
日期：2026-05-25
|
||||
状态：已获口头批准，待书面规格确认
|
||||
目标目录：`/Users/yoilun/Code/codex-agent-manager`
|
||||
|
||||
## 1. 产品定位
|
||||
|
||||
Codex 智能体管理台是一个本机 localhost 工具，用来管理本机 Codex 智能体配置、查看不同项目里的智能体运行情况，并观察动态工作流的阶段、交接、审查循环和主智能体监管状态。
|
||||
|
||||
它不是固定流程播放器，也不是通用系统监控面板。它应像一个温和、清晰的本地工作台：能让用户放心查看、修改和追踪 Codex 智能体相关信息，同时对数据来源和置信度保持诚实。
|
||||
|
||||
## 2. 目标用户与核心问题
|
||||
|
||||
主要用户是本机 Codex 使用者，尤其是会使用多个角色智能体和多阶段工作流的用户。
|
||||
|
||||
需要解决的问题：
|
||||
|
||||
- 管理 `.codex/agents/*.toml` 中的智能体名称、描述和角色设定。
|
||||
- 按项目查看哪些智能体最近运行过、可能正在运行、已结束或状态未知。
|
||||
- 查看一次任务中主智能体如何派发子智能体，以及子智能体之间是否发生了代码实现、审查、修复循环。
|
||||
- 判断主智能体是否仍在监管当前工作流。
|
||||
- 在修改智能体配置时有 TOML 校验、差异预览、备份和确认写回，避免静默破坏 Codex 配置。
|
||||
|
||||
## 3. 范围
|
||||
|
||||
### 3.1 MVP 必做
|
||||
|
||||
- 独立项目：`/Users/yoilun/Code/codex-agent-manager`。
|
||||
- 本机 Web 工具，通过 localhost 访问。
|
||||
- 全中文界面，技术缩写如 PID、TOML、SQLite 保留英文。
|
||||
- 读取 `.codex/agents/*.toml`，展示智能体文件、名称、描述、角色设定摘要和修改时间。
|
||||
- 读取 `.codex/config.toml` 中的项目配置，展示项目路径、信任等级和目录存在性。
|
||||
- 读取 `.codex/state_5.sqlite` 和 `.codex/goals_1.sqlite` 的只读状态，展示线程、子智能体关系、目标状态和更新时间。
|
||||
- 使用本机进程表辅助判断 Codex 是否仍在运行。
|
||||
- 解析项目内工作流文件：`task_plan.md`、`progress.md`、`findings.md`、`docs/project.md`。如果存在，显示阶段、审查循环、测试结果和门禁证据。
|
||||
- 将运行状态显示为 `运行中`、`最近活跃`、`空闲`、`未知`、`冲突`，并显示数据来源和置信度。
|
||||
- 将工作流显示为动态事件流和有向关系图，不写死固定流程。
|
||||
- 支持智能体配置草稿编辑、TOML 校验、diff 预览、自动备份、用户确认后写回 `.codex/agents/*.toml`。
|
||||
- 写回前显示目标文件路径、备份路径、变更数量和校验状态。
|
||||
|
||||
### 3.2 明确不做
|
||||
|
||||
- 不启动、停止或杀死 Codex 智能体。
|
||||
- 不修改 Codex SQLite 数据库。
|
||||
- 不读取或展示 `.codex/auth.json`。
|
||||
- 不做云端同步、多用户权限或远程管理。
|
||||
- 不把推断状态伪装成确定事实。
|
||||
- 不将工作流固定为某个模板，例如“代码员 -> 审查员”。
|
||||
|
||||
## 4. 信息架构
|
||||
|
||||
主导航使用五个标签页：
|
||||
|
||||
- `项目视图`：按项目查看智能体执行情况、最近活动、置信度和来源。
|
||||
- `工作流视图`：查看当前项目的阶段进度、智能体交接、审查/修复循环和主智能体监管状态。
|
||||
- `智能体视图`：集中查看和编辑智能体名称、描述、角色设定。
|
||||
- `草稿`：查看未写回草稿、TOML 校验结果、diff、备份记录和写回状态。
|
||||
- `设置`：配置 Codex 路径、状态数据源、备份目录和扫描规则。
|
||||
|
||||
全局搜索应支持项目名、路径、智能体名、描述关键词、线程 ID、PID 和阶段关键词。
|
||||
|
||||
## 5. 页面设计
|
||||
|
||||
### 5.1 项目视图
|
||||
|
||||
布局为三栏：
|
||||
|
||||
- 左侧：项目列表。显示项目名、路径短名、运行中智能体数量、最近活动时间、是否有草稿或状态不确定。
|
||||
- 中间：项目内智能体状态矩阵。每行一个智能体，显示智能体名称、当前状态、目标状态、本机进程、来源、置信度、最近活动时间和快捷操作。
|
||||
- 右侧：详情面板。显示选中智能体的角色摘要、运行证据、置信度解释、最近备份、草稿状态和进入编辑入口。
|
||||
|
||||
### 5.2 工作流视图
|
||||
|
||||
工作流视图必须基于动态数据渲染，而不是写死阶段。
|
||||
|
||||
核心组件：
|
||||
|
||||
- 阶段时间线：当项目内存在标准计划文件时，显示阶段名称、状态、验收标准和门禁结果。
|
||||
- 智能体交接流：显示谁派发给谁、发生时间、角色、当前状态和来源。
|
||||
- 交接图：基于 `thread_spawn_edges` 绘制主线程和子线程关系。
|
||||
- 审查/修复循环：当从 `progress.md` 或事件顺序中识别到审查返回时，显示当前第几轮、最多几轮、问题摘要和复测结果。
|
||||
- 监管面板：显示主智能体是否仍活跃、最近计划更新时间、当前门禁和证据文件状态。
|
||||
|
||||
如果没有标准计划文件，工作流视图仍显示通用事件流，例如：
|
||||
|
||||
- 主线程派生了哪些子智能体。
|
||||
- 哪些子智能体仍打开。
|
||||
- 哪些子智能体已关闭。
|
||||
- 哪些关系和阶段属于推断，并标注置信度。
|
||||
|
||||
### 5.3 智能体视图
|
||||
|
||||
布局为双栏：
|
||||
|
||||
- 左侧：智能体列表，支持搜索、排序、按角色过滤，显示是否有草稿、是否被多个项目最近使用。
|
||||
- 右侧：编辑工作区。
|
||||
|
||||
编辑工作区上方显示结构化表单：
|
||||
|
||||
- 名称
|
||||
- 描述
|
||||
- 角色设定
|
||||
- 附加说明或范围备注
|
||||
|
||||
下方使用子标签：
|
||||
|
||||
- `预览`：人类可读的智能体信息。
|
||||
- `TOML`：结构化 TOML 视图。
|
||||
- `差异`：草稿与当前文件的差异。
|
||||
- `备份`：历史备份、备份路径和恢复入口。
|
||||
|
||||
### 5.4 草稿
|
||||
|
||||
草稿页显示所有未写回变更：
|
||||
|
||||
- 智能体文件路径。
|
||||
- 变更字段。
|
||||
- TOML 校验状态。
|
||||
- 最近备份状态。
|
||||
- 写回步骤：`草稿` -> `已校验` -> `已备份` -> `已写回`。
|
||||
- 可批量放弃草稿，但批量写回应默认禁用，避免误操作。
|
||||
|
||||
### 5.5 设置
|
||||
|
||||
设置页包含：
|
||||
|
||||
- Codex home 路径，默认 `/Users/yoilun/.codex`。
|
||||
- 是否启用 SQLite 状态读取。
|
||||
- 是否启用本机进程辅助判断。
|
||||
- 备份目录策略，默认备份到原 TOML 文件旁边或项目定义的备份目录。
|
||||
- 状态刷新间隔。
|
||||
- 敏感文件黑名单，至少包含 `auth.json`。
|
||||
|
||||
## 6. 数据模型
|
||||
|
||||
### 6.1 AgentDefinition
|
||||
|
||||
- `id`：由文件名或路径生成的稳定 ID。
|
||||
- `filePath`
|
||||
- `name`
|
||||
- `description`
|
||||
- `developerInstructions`
|
||||
- `extraFields`
|
||||
- `modifiedAt`
|
||||
- `parseStatus`
|
||||
- `draftStatus`
|
||||
|
||||
### 6.2 ProjectInfo
|
||||
|
||||
- `path`
|
||||
- `displayName`
|
||||
- `trustLevel`
|
||||
- `exists`
|
||||
- `lastActivityAt`
|
||||
- `activeAgentCount`
|
||||
- `hasDrafts`
|
||||
- `hasUncertainStatus`
|
||||
|
||||
### 6.3 RuntimeThread
|
||||
|
||||
- `threadId`
|
||||
- `cwd`
|
||||
- `title`
|
||||
- `agentNickname`
|
||||
- `agentRole`
|
||||
- `agentPath`
|
||||
- `createdAt`
|
||||
- `updatedAt`
|
||||
- `archived`
|
||||
- `source`
|
||||
|
||||
### 6.4 WorkflowEdge
|
||||
|
||||
- `parentThreadId`
|
||||
- `childThreadId`
|
||||
- `status`
|
||||
- `parentAgent`
|
||||
- `childAgent`
|
||||
- `inferredMeaning`
|
||||
- `confidence`
|
||||
|
||||
### 6.5 WorkflowEvent
|
||||
|
||||
- `id`
|
||||
- `timestamp`
|
||||
- `projectPath`
|
||||
- `type`
|
||||
- `actor`
|
||||
- `target`
|
||||
- `summary`
|
||||
- `source`
|
||||
- `confidence`
|
||||
|
||||
事件类型示例：
|
||||
|
||||
- `主智能体派发`
|
||||
- `子智能体启动`
|
||||
- `子智能体完成`
|
||||
- `阶段开始`
|
||||
- `阶段完成`
|
||||
- `审查开始`
|
||||
- `审查失败`
|
||||
- `修复请求`
|
||||
- `复测通过`
|
||||
- `用户门禁`
|
||||
- `状态冲突`
|
||||
|
||||
### 6.6 StatusEvidence
|
||||
|
||||
- `status`：`running`、`recent`、`idle`、`unknown`、`conflict`
|
||||
- `labelZh`：中文显示文本
|
||||
- `confidence`：`high`、`medium`、`low`
|
||||
- `sources`：`sqlite_threads`、`sqlite_goals`、`process_table`、`plan_files`、`inferred`
|
||||
- `explanation`
|
||||
- `updatedAt`
|
||||
|
||||
## 7. 状态与工作流推断规则
|
||||
|
||||
状态判断采用综合来源：
|
||||
|
||||
- SQLite 线程仍显示近期更新，且存在相关 Codex 进程：`运行中`，高置信度。
|
||||
- SQLite 线程近期更新，但没有匹配进程：`最近活跃`，中置信度。
|
||||
- 项目有历史线程但超过阈值未更新：`空闲`，中或高置信度。
|
||||
- 缺少足够数据源：`未知`，低置信度。
|
||||
- SQLite、目标状态和进程表互相矛盾：`冲突`，显示冲突原因。
|
||||
|
||||
工作流推断规则：
|
||||
|
||||
- `thread_spawn_edges` 是派发关系的主要结构化来源。
|
||||
- `threads.agent_role`、`threads.agent_nickname`、`threads.cwd` 用于识别角色和项目。
|
||||
- `thread_goals.status` 用于判断目标是否仍 active、blocked 或 complete。
|
||||
- 标准计划文件用于更准确地识别阶段、门禁和审查循环。
|
||||
- 没有计划文件时，只显示通用事件流和派生关系，不强行命名阶段。
|
||||
- 所有非结构化推断都必须显示置信度。
|
||||
|
||||
## 8. 安全写回流程
|
||||
|
||||
写回仅允许目标文件位于 `.codex/agents/*.toml`。
|
||||
|
||||
流程：
|
||||
|
||||
1. 用户在智能体视图中修改草稿。
|
||||
2. 后端解析并校验 TOML。
|
||||
3. 生成字段级 diff。
|
||||
4. 用户点击创建备份。
|
||||
5. 后端创建时间戳备份，例如 `agent.toml.bak.20260525-153000`。
|
||||
6. 用户确认写回。
|
||||
7. 后端使用原子写入策略更新 TOML。
|
||||
8. UI 显示写回结果和备份路径。
|
||||
|
||||
失败处理：
|
||||
|
||||
- TOML 无效时禁止写回。
|
||||
- 备份失败时禁止写回。
|
||||
- 写回失败时保留原文件和草稿。
|
||||
- 不覆盖用户在校验后又改动过的文件；写回前比较 mtime 或文件哈希。
|
||||
|
||||
## 9. 架构
|
||||
|
||||
建议使用单体本机 Web 工具：
|
||||
|
||||
- 后端：Go。用于处理只读 SQLite、TOML 解析、路径安全、本机进程读取、备份和原子写回。
|
||||
- 前端：Vue 3 + Vite，保持轻量，并匹配用户本机已有 Vue/Vite 项目经验。
|
||||
- 通信：localhost HTTP API。
|
||||
- 存储：不新建复杂数据库。草稿可先保存在项目工作目录下的本地 JSON 文件，或内存加文件备份。
|
||||
|
||||
后端模块建议：
|
||||
|
||||
- `codexhome`：路径和安全边界。
|
||||
- `agents`：读取、解析、校验、diff、备份、写回 agent TOML。
|
||||
- `projects`：读取 `.codex/config.toml` 项目信任配置。
|
||||
- `runtime`：只读 SQLite 和进程状态。
|
||||
- `workflow`：聚合线程、目标、计划文件和推断事件。
|
||||
- `server`：HTTP API。
|
||||
|
||||
前端模块建议：
|
||||
|
||||
- `ProjectView`
|
||||
- `WorkflowView`
|
||||
- `AgentView`
|
||||
- `DraftsView`
|
||||
- `SettingsView`
|
||||
- `StatusBadge`
|
||||
- `ConfidenceBadge`
|
||||
- `HandoffTimeline`
|
||||
- `WorkflowGraph`
|
||||
- `DiffViewer`
|
||||
- `WritebackSteps`
|
||||
|
||||
## 10. API 草案
|
||||
|
||||
- `GET /api/health`
|
||||
- `GET /api/agents`
|
||||
- `GET /api/agents/:id`
|
||||
- `POST /api/agents/:id/draft`
|
||||
- `POST /api/agents/:id/validate`
|
||||
- `GET /api/agents/:id/diff`
|
||||
- `POST /api/agents/:id/backup`
|
||||
- `POST /api/agents/:id/write`
|
||||
- `GET /api/projects`
|
||||
- `GET /api/projects/:projectId/runtime`
|
||||
- `GET /api/projects/:projectId/workflow`
|
||||
- `GET /api/workflows/:threadId`
|
||||
- `GET /api/settings`
|
||||
- `PUT /api/settings`
|
||||
|
||||
所有写接口必须限制在允许路径内，并返回明确的错误码和中文错误信息。
|
||||
|
||||
## 11. 视觉方向
|
||||
|
||||
采用“温和的本地工作台 + 编辑器质感”：
|
||||
|
||||
- 背景使用温暖浅灰或淡墨色。
|
||||
- 操作主色使用深青、墨绿或靛蓝。
|
||||
- 草稿和警告使用琥珀色。
|
||||
- 成功和运行中使用低饱和绿色。
|
||||
- 状态数据可使用紧凑等宽字体，但整页不要全等宽。
|
||||
- 控件圆角控制在 6-8px。
|
||||
- 避免大面积黑底、荧光绿、硬表格边框和系统监控大屏风格。
|
||||
|
||||
## 12. 阶段计划与审查门禁
|
||||
|
||||
代码阶段必须参考 `/Users/yoilun/Code/goal-subagents-workflow-prompt.md`。
|
||||
|
||||
每个阶段都要创建新的 coding agent 和 testing/code review agent。testing/code review agent 只审查和测试，不直接修改代码。每阶段最多 3 轮修复循环。阶段通过后更新 `task_plan.md`、`findings.md`、`progress.md` 和必要的 `docs/project.md`，并关闭本阶段子智能体。
|
||||
|
||||
### 阶段 0：项目初始化与风险边界
|
||||
|
||||
目标：
|
||||
|
||||
- 创建项目结构和文件化计划。
|
||||
- 确认 `.codex` 可读/可写边界。
|
||||
- 明确禁止读取和禁止写入范围。
|
||||
|
||||
审查门禁：
|
||||
|
||||
- 不得读取 `auth.json`。
|
||||
- 不得修改 `.codex` 文件。
|
||||
- 必须列出数据源、风险和安全边界。
|
||||
|
||||
### 阶段 1：只读数据层
|
||||
|
||||
目标：
|
||||
|
||||
- 读取 agents TOML、config projects、SQLite threads、spawn edges、goals。
|
||||
- 提供只读 API。
|
||||
|
||||
审查门禁：
|
||||
|
||||
- SQLite 必须只读打开。
|
||||
- TOML 解析失败不能导致服务崩溃。
|
||||
- 路径访问必须限制在允许目录。
|
||||
|
||||
### 阶段 2：运行状态与动态工作流模型
|
||||
|
||||
目标：
|
||||
|
||||
- 实现综合运行状态判断。
|
||||
- 实现 workflow event 和 handoff graph 聚合。
|
||||
- 支持计划文件存在和不存在两种情况。
|
||||
|
||||
审查门禁：
|
||||
|
||||
- 不允许写死固定流程。
|
||||
- 推断状态必须带来源和置信度。
|
||||
- 数据不足时必须显示未知，而不是编造状态。
|
||||
|
||||
### 阶段 3：中文 UI 只读工作台
|
||||
|
||||
目标：
|
||||
|
||||
- 实现项目视图、工作流视图、智能体视图的只读版本。
|
||||
- 使用中文界面和温和工作台视觉风格。
|
||||
|
||||
审查门禁：
|
||||
|
||||
- 页面在空数据、坏 TOML、无项目、无计划文件时可用。
|
||||
- 状态和置信度解释清晰。
|
||||
- 不出现未实现的危险操作入口。
|
||||
|
||||
### 阶段 4：草稿、校验和差异预览
|
||||
|
||||
目标：
|
||||
|
||||
- 实现 agent 配置草稿编辑。
|
||||
- 实现 TOML 校验、字段级 diff 和草稿列表。
|
||||
|
||||
审查门禁：
|
||||
|
||||
- 无效 TOML 必须阻止写回。
|
||||
- diff 必须明确显示目标文件和变更字段。
|
||||
- 草稿不能覆盖原文件。
|
||||
|
||||
### 阶段 5：备份与确认写回
|
||||
|
||||
目标：
|
||||
|
||||
- 实现备份创建和确认写回。
|
||||
- 使用原子写入和 mtime/hash 防并发覆盖。
|
||||
|
||||
审查门禁：
|
||||
|
||||
- 备份失败不得写回。
|
||||
- 写回目标必须限制在 `.codex/agents/*.toml`。
|
||||
- 写回失败必须保留原文件和草稿。
|
||||
|
||||
### 阶段 6：集成验证与文档
|
||||
|
||||
目标：
|
||||
|
||||
- 完成端到端验证、运行说明和恢复说明。
|
||||
- 验证代码阶段工作流本身也能在工作流视图中展示。
|
||||
|
||||
审查门禁：
|
||||
|
||||
- 构建和测试通过。
|
||||
- 文档说明运行方式、数据来源、安全边界、备份恢复。
|
||||
- 最终审查确认没有静默修改 `.codex` 配置或 SQLite。
|
||||
|
||||
## 13. 验收标准
|
||||
|
||||
- 能启动本机管理台并访问中文 UI。
|
||||
- 能列出本机 Codex 智能体和项目。
|
||||
- 能按项目查看智能体运行状态、来源和置信度。
|
||||
- 能看到动态工作流交接和阶段进度；流程变化时仍能显示事件流。
|
||||
- 能编辑智能体草稿、校验 TOML、预览 diff、创建备份并确认写回。
|
||||
- 所有危险操作都有明确确认和恢复路径。
|
||||
- 每个实现阶段都有审查记录和测试证据。
|
||||
|
||||
## 14. 未决问题
|
||||
|
||||
- 工作流图初版使用列表/时间线还是引入图布局库，需要在 UI 实现阶段决定。
|
||||
- 草稿持久化位置需要在阶段 0 定义，建议放在项目目录内，不放入 `.codex`。
|
||||
Reference in New Issue
Block a user