142 lines
5.0 KiB
Markdown
142 lines
5.0 KiB
Markdown
# 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/` 查看工作台。
|
||
|
||
## Docker 启动
|
||
|
||
构建镜像：
|
||
|
||
```bash
|
||
docker build -t codex-agent-manager:local .
|
||
```
|
||
|
||
启动容器，并把本机 Codex 配置和当前项目目录挂载进去：
|
||
|
||
```bash
|
||
docker run --rm \
|
||
--name codex-agent-manager \
|
||
-p 0.0.0.0:18083:18083 \
|
||
-e CODEX_HOME=/codex-home \
|
||
-e WORKSPACE_ROOT=/Users/yoilun/Code/codex-agent-manager \
|
||
-v /Users/yoilun/.codex:/codex-home \
|
||
-v /Users/yoilun/Code/codex-agent-manager:/Users/yoilun/Code/codex-agent-manager:ro \
|
||
codex-agent-manager:local
|
||
```
|
||
|
||
然后打开 `http://127.0.0.1:18083/`。Docker 镜像内由 Go 后端同时提供 API 和前端静态页面，不需要再单独启动 Vite。
|
||
|
||
如果要让局域网内其他设备访问，保持上面的 `0.0.0.0:18083:18083` 端口映射，然后在同一局域网的设备上打开：
|
||
|
||
```text
|
||
http://你的电脑局域网IP:18083/
|
||
```
|
||
|
||
在 macOS 上可用下面命令查看当前 Wi-Fi/LAN IP：
|
||
|
||
```bash
|
||
ipconfig getifaddr en0
|
||
```
|
||
|
||
也可以使用 Compose：
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
如需改挂载路径，可在启动前设置本机环境变量：
|
||
|
||
```bash
|
||
CODEX_HOME=/path/to/.codex \
|
||
CODEX_AGENT_MANAGER_PROJECT=/path/to/codex-agent-manager \
|
||
docker compose up --build
|
||
```
|
||
|
||
## 验证命令
|
||
|
||
后端和整体检查：
|
||
|
||
```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。
|