Project Documentation

Goal

构建一个本机 Codex 智能体管理台，用中文管理 agent 配置、项目运行状态、动态工作流和安全写回流程。

Final Architecture

最终实现为：Go 后端提供 localhost HTTP API，Vue 3 + Vite 前端提供中文工作台界面。后端已提供健康检查、.codex/agents/*.toml 读取、项目配置只读读取、运行线程只读模型、动态工作流事件模型，以及单个智能体 TOML 的草稿校验和确认写回；前端已通过集中 API client 接入这些端点并显示加载中、连接失败、空数据、来源/置信度和写回状态。

Configuration

CODEX_HOME: 默认 /Users/yoilun/.codex
后端监听地址：默认 127.0.0.1:18083
前端开发地址：默认 127.0.0.1:13083
WorkspaceRoot: 默认当前进程工作目录，用于读取 task_plan.md 等计划文件证据。
Go module 目标：go 1.22
SQLite 驱动：modernc.org/sqlite v1.35.0

Runbook

启动后端：

go run ./cmd/codex-agent-manager

健康检查：

curl http://127.0.0.1:18083/api/health

读取智能体定义：

curl http://127.0.0.1:18083/api/agents

校验智能体草稿，不写文件：

curl -X POST http://127.0.0.1:18083/api/agents/backend/validate \
  -H 'Content-Type: application/json' \
  -d '{"content":"name = \"后端架构师\"\n"}'

创建备份并写回单个智能体文件：

curl -X POST http://127.0.0.1:18083/api/agents/backend/write \
  -H 'Content-Type: application/json' \
  -d '{"content":"name = \"后端架构师\"\n","expectedHash":"<validate 返回的 currentHash>"}'

读取项目配置：

curl http://127.0.0.1:18083/api/projects

读取运行线程：

curl http://127.0.0.1:18083/api/runtime/threads

读取动态工作流事件：

curl http://127.0.0.1:18083/api/workflow/events

安装并构建前端：

cd web
pnpm install
pnpm test
pnpm build

启动前端工作台：

cd web
pnpm dev

前端开发地址为 http://127.0.0.1:13083/。前端按视图调用 API：项目视图读取 /api/projects 和 /api/runtime/threads，工作流视图读取 /api/workflow/events，智能体视图读取 /api/agents，并仅对当前选中的智能体调用 /api/agents/{id}/validate 和 /api/agents/{id}/write。静态示例数据仅在接口连接失败时作为 fallback 展示，并必须明确标注“示例/等待连接”；真实接口返回空列表时展示空状态和来源证据，不回退到示例数据。前端可保留 local_sample、api_missing 等内部 source kind，但用户界面必须显示中文来源和 高 / 中 / 低 置信度。2026-05-25 已通过 Chrome 验证项目视图、工作流视图、智能体视图、草稿和设置页；内置浏览器插件返回 Browser is not available: iab，视觉核验使用本机 Chrome 完成。

API Overview

GET /api/health: 健康检查。
GET /api/agents: 只读列出 CODEX_HOME/agents/*.toml 直属文件；坏 TOML 以单条 invalid 状态返回。
POST /api/agents/{id}/validate: 校验单个智能体 TOML 草稿、生成 diff、返回字段变化、目标路径和当前 sha256 hash；不写文件。
POST /api/agents/{id}/write: 使用 expectedHash 写回单个已有智能体 TOML；写回前重新校验、复读目标、创建备份并原子替换。
GET /api/projects: 只读解析 .codex/config.toml 中的 [projects."..."]。
GET /api/runtime/threads: 只读读取 state_5.sqlite 和 goals_1.sqlite，返回 threads、spawn edges、goals、聚合来源和分数据源证据。
GET /api/workflow/events: 从运行线程、spawn edges、goals 和计划文件证据生成事件流、交接边和阶段状态。

Security Boundaries

不读取 .codex/auth.json。
不写入 Codex SQLite。
不读取或写入 .codex/config.toml 以外的项目只读解析；写回目标仅限 CODEX_HOME/agents/{id}.toml 直属文件。
SQLite 通过纯 Go modernc.org/sqlite v1.35.0 和 mode=ro&immutable=1 打开；缺失 SQLite 返回空列表和低置信度来源说明。
运行线程 API 返回聚合 source 和分数据源 sources；仅 state_5.sqlite 或仅 goals_1.sqlite 缺失时，聚合来源为 sqlite_partial / medium，缺失的一侧为 sqlite_missing / low。
运行线程读取使用 PRAGMA table_info 适配 schema drift；缺关键列时对应表返回空列表和 sqlite_schema_drift / low 证据，可选列缺失、NULL 和数值字段按空字符串或文本值处理。
.codex/agents/*.toml 写回必须先备份。
/api/agents 只读列出 .codex/agents 直属 .toml 文件，读取前通过 Codex home 边界和 agent TOML 专用 resolver；坏 TOML 以单条 invalid 状态返回，不导致服务崩溃。
POST /api/agents/{id}/validate 只校验请求体中的 TOML 草稿、生成 diff、返回目标路径、当前 sha256 hash 和字段变更；该端点不写文件。
POST /api/agents/{id}/write 会重新校验 TOML，重新读取目标文件并比较 expectedHash，先创建 *.bak-<timestamp> 备份，备份成功后通过同目录临时文件和 rename 原子写回。
写回的目标读取、备份、临时文件和 rename 绑定到已打开的 agents dirfd；关键步骤会复核 agents 目录路径身份、目标文件身份和目标 hash，减少 TOCTOU 窗口。
写回 id 只允许安全 bare file stem：字母、数字、下划线、连字符，且不能包含路径分隔符、绝对路径、.toml 扩展名或子目录。agents 目录 symlink、目标叶子 symlink、非普通文件和路径穿越都会被拒绝。
validate/write POST body 限制为 1 MiB，拒绝 trailing JSON；路径、系统错误和无效请求统一映射为中文安全响应。
无效 TOML、hash 冲突、备份失败或临时文件写入失败都不会替换原文件；临时文件会尽量清理。
/api/projects 只读解析 .codex/config.toml 中的 [projects."..."]，展示路径、显示名、信任等级和目录存在性。
/api/workflow/events 从运行线程、spawn edges、goals 和计划文件证据生成事件流/交接边/阶段状态，不写死固定流程。
前端仅在智能体视图提供单文件草稿入口，按钮为“校验 TOML”“查看差异”“创建备份并写回”；只有校验成功且存在 currentHash 时才允许写回，写回前使用浏览器确认。
前端 normalizer 负责把 source kind、confidence、状态和 parseStatus 转成中文显示，并过滤工作流中非阶段表格行。

Known Risks

Codex 内部 SQLite schema 可能变化。
运行状态由多来源推断，必须显示置信度。
真实 SQLite 读取已覆盖临时测试库；如果真实 Codex schema 新增字段或缺少可选字段，应继续走 schema-aware 查询和来源证据，而不是让 API 500。
Agent 列表接口当前返回原始 TOML 文本供草稿编辑；前端仍必须只在“校验 TOML -> 查看差异 -> 创建备份并写回”的显式流程中写回。
内置浏览器插件可能不可用；若返回 Browser is not available: iab，可使用本机 Chrome 做只读页面核验，并在进度记录中注明 fallback。
写回只覆盖单个已有 agent TOML，不支持创建新 agent、批量写回或自动保存草稿。

7.3 KiB Raw Blame History Unescape Escape