docs: finalize runbook and verification evidence
This commit is contained in:
Yoilun
@@ -4,9 +4,9 @@
|
||||
|
||||
构建一个本机 Codex 智能体管理台，用中文管理 agent 配置、项目运行状态、动态工作流和安全写回流程。
|
||||
|
||||
## Target Architecture
|
||||
## Final Architecture
|
||||
|
||||
计划架构为：Go 后端提供 localhost HTTP API，Vue 3 + Vite 前端提供中文工作台界面。当前后端已提供健康检查、`.codex/agents/*.toml` 读取、项目配置只读读取、运行线程只读模型、动态工作流事件模型，以及单个智能体 TOML 的草稿校验和确认写回；前端已通过集中 API client 接入这些端点并显示加载中、连接失败、空数据和写回状态。
|
||||
最终实现为：Go 后端提供 localhost HTTP API，Vue 3 + Vite 前端提供中文工作台界面。后端已提供健康检查、`.codex/agents/*.toml` 读取、项目配置只读读取、运行线程只读模型、动态工作流事件模型，以及单个智能体 TOML 的草稿校验和确认写回；前端已通过集中 API client 接入这些端点并显示加载中、连接失败、空数据、来源/置信度和写回状态。
|
||||
|
||||
## Configuration
|
||||
|
||||
@@ -80,7 +80,7 @@ pnpm test
|
||||
pnpm build
|
||||
```
|
||||
|
||||
启动 Phase 4 只读前端工作台：
|
||||
启动前端工作台：
|
||||
|
||||
```bash
|
||||
cd web
|
||||
@@ -89,6 +89,16 @@ 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，但用户界面必须显示中文来源和 `高 / 中 / 低` 置信度。
|
||||
|
||||
## 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`。
|
||||
@@ -98,21 +108,23 @@ pnpm dev
|
||||
- 运行线程 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` 状态返回，不导致服务崩溃。
|
||||
- `/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 和计划文件证据生成事件流/交接边/阶段状态，不写死固定流程。
|
||||
- Phase 4 前端不调用真实 API、不保存草稿、不写回 `.codex/agents/*.toml`；所有写回相关控件仅作为只读步骤展示。
|
||||
- Phase 6 前端仅在智能体视图提供单文件草稿入口，按钮为“校验 TOML”“查看差异”“创建备份并写回”；只有校验成功且存在 currentHash 时才允许写回，写回前使用浏览器确认。
|
||||
- Phase 5 前端 normalizer 负责把 source kind、confidence、状态和 parseStatus 转成中文显示，并过滤工作流中非阶段表格行。
|
||||
- `/api/projects` 只读解析 `.codex/config.toml` 中的 `[projects."..."]`，展示路径、显示名、信任等级和目录存在性。
|
||||
- `/api/workflow/events` 从运行线程、spawn edges、goals 和计划文件证据生成事件流/交接边/阶段状态，不写死固定流程。
|
||||
- 前端仅在智能体视图提供单文件草稿入口，按钮为“校验 TOML”“查看差异”“创建备份并写回”；只有校验成功且存在 currentHash 时才允许写回，写回前使用浏览器确认。
|
||||
- 前端 normalizer 负责把 source kind、confidence、状态和 parseStatus 转成中文显示，并过滤工作流中非阶段表格行。
|
||||
|
||||
## Known Risks
|
||||
|
||||
- Codex 内部 SQLite schema 可能变化。
|
||||
- 运行状态由多来源推断，必须显示置信度。
|
||||
- Phase 3 真实 SQLite 读取已覆盖临时测试库；如果真实 Codex schema 新增字段或缺少可选字段，应继续走 schema-aware 查询和来源证据，而不是让 API 500。
|
||||
- Phase 4 只读工作台是静态壳；如果用户误以为它展示真实状态，应优先检查界面是否仍清楚显示来源、置信度和“等待连接 API”提示。
|
||||
- Phase 5 agent 接口当前不返回原始 TOML 文本；智能体只读编辑区展示的是接口返回的已解析字段，并在代码区说明“接口未返回原始 TOML”。
|
||||
- 真实 SQLite 读取已覆盖临时测试库；如果真实 Codex schema 新增字段或缺少可选字段，应继续走 schema-aware 查询和来源证据，而不是让 API 500。
|
||||
- Agent 列表接口不返回原始 TOML 文本；智能体编辑区展示的是接口返回的已解析字段，并在代码区说明“接口未返回原始 TOML”。
|
||||
- 浏览器视觉验证需要可用浏览器工具或主智能体执行；文档记录不得伪造截图结果。
|
||||
- 写回只覆盖单个已有 agent TOML，不支持创建新 agent、批量写回或自动保存草稿。
|
||||
|
||||
Reference in New Issue
Block a user