# 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`。