docs: finalize runbook and verification evidence

README.md

@@ -0,0 +1,92 @@
+# 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
+```
+
+如果需要浏览器视觉验证，由主智能体或可用浏览器工具访问 `http://127.0.0.1:13083/` 后记录截图结果；不要伪造截图记录。
+
+## 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。