# Codex 智能体管理台

Codex 智能体管理台是一个本机 localhost 工具，用中文浏览和维护 Codex agent 配置、项目配置、运行线程、动态工作流证据，并对单个 agent TOML 执行受控写回。

项目由 Go 后端和 Vue 3 + Vite 前端组成。后端默认只读取当前用户的 `CODEX_HOME`，前端通过集中 API client 调用后端端点，并把来源、置信度、状态和写回结果转换为中文展示。

## 启动后端

默认配置：

- `CODEX_HOME`: 未设置时使用当前用户主目录下的 `.codex`
- HTTP 地址：`127.0.0.1:18083`
- 工作区根目录：后端进程当前目录，用于读取 `task_plan.md` 等计划证据

启动命令：

```bash
go run ./cmd/codex-agent-manager
```

健康检查：

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

如需指向测试用 Codex home，可在启动前设置 `CODEX_HOME`。

## 启动前端

前端位于 `web/`，默认 dev 地址为 `127.0.0.1:13083`，Vite 代理本机后端 API。

```bash
cd web
pnpm install
pnpm dev
```

打开 `http://127.0.0.1:13083/` 查看工作台。

## 验证命令

后端和整体检查：

```bash
go test ./...
go test -count=1 ./...
git diff --check
```

前端检查：

```bash
cd web
pnpm test
pnpm build
```

浏览器视觉验证已在 2026-05-25 使用本机 Chrome 访问 `http://127.0.0.1:13083/` 完成，覆盖项目视图、工作流视图、智能体视图、草稿和设置页。内置浏览器插件若返回 `Browser is not available: iab`，可改用 Chrome 做只读页面核验，并在 `progress.md` 记录 fallback。

## API 概览

- `GET /api/health`: 健康检查，返回 `{ "status": "ok" }`
- `GET /api/agents`: 只读列出 `CODEX_HOME/agents/*.toml` 直属文件；坏 TOML 作为 invalid 条目返回
- `POST /api/agents/{id}/validate`: 校验单个 agent TOML 草稿，返回 diff、字段变化、目标路径和当前 sha256 hash；不写文件
- `POST /api/agents/{id}/write`: 使用 `expectedHash` 写回单个已有 agent TOML；写回前重新校验、创建备份并做原子替换
- `GET /api/projects`: 只读解析 `.codex/config.toml` 中的项目配置
- `GET /api/runtime/threads`: 只读读取 Codex SQLite 运行线程、spawn edges 和 goals，并返回来源证据
- `GET /api/workflow/events`: 从运行线程、goals、spawn edges 和计划文件生成动态工作流事件、交接边和阶段状态

前端 API client 位于 `web/src/api/client.js`，中文 normalizer 位于 `web/src/api/normalizers.js`。

## 安全边界

- 不读取或展示 `.codex/auth.json`
- 不写入 Codex SQLite
- 项目配置只读解析 `.codex/config.toml`，默认不写配置文件
- agent 写回仅限 `CODEX_HOME/agents/{id}.toml` 的已有直属普通文件
- agent id 只允许字母、数字、下划线和连字符，不能包含路径、扩展名或子目录
- 拒绝 `agents` 目录 symlink、目标叶子 symlink、非普通文件和路径穿越
- 写回请求体限制为 1 MiB，拒绝无效 JSON 和 trailing JSON
- 错误响应对路径和系统错误做中文安全映射，避免泄漏敏感路径细节

## 写回流程

1. 用户在智能体视图编辑单个 agent TOML 草稿。
2. 前端调用 `POST /api/agents/{id}/validate`，后端读取当前目标文件、校验草稿、生成 diff 和 `currentHash`。
3. 只有校验通过且存在 `currentHash` 时，前端才允许发起写回，并要求用户确认。
4. 前端调用 `POST /api/agents/{id}/write`，携带同一份草稿和 `expectedHash`。
5. 后端重新校验 TOML、重新读取目标文件并比较 hash；不匹配则返回冲突，不写文件。
6. 后端在目标旁创建 `*.bak-<timestamp>` 备份；备份成功后才通过同目录临时文件和 rename 原子替换目标。
7. 写回的读取、备份、临时文件和 rename 绑定到已打开的 `agents` dirfd，并在关键步骤复核目录身份和目标文件 hash。