yangyl/codex-agent-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: finalize runbook and verification evidence

Browse Source
This commit is contained in:
Yoilun
2026-05-25 21:50:51 +08:00
parent d3bc73ba29
commit 0047448e9d
5 changed files with 148 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
README.md Normal file
View File

@@ -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。

36
docs/project.md
View File

@@ -4,9 +4,9 @@
构建一个本机 Codex 智能体管理台，用中文管理 agent 配置、项目运行状态、动态工作流和安全写回流程。 构建一个本机 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 ## Configuration
@@ -80,7 +80,7 @@ pnpm test
pnpm build pnpm build
``` ```
启动 Phase 4 只读前端工作台： 启动前端工作台：
```bash ```bash
cd web 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，但用户界面必须显示中文来源和 `高 / 中 / 低` 置信度。 前端开发地址为 `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 ## Security Boundaries
- 不读取 `.codex/auth.json`。 - 不读取 `.codex/auth.json`。
@@ -98,21 +108,23 @@ pnpm dev
- 运行线程 API 返回聚合 `source` 和分数据源 `sources`；仅 `state_5.sqlite` 或仅 `goals_1.sqlite` 缺失时，聚合来源为 `sqlite_partial` / `medium`，缺失的一侧为 `sqlite_missing` / `low`。 - 运行线程 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 和数值字段按空字符串或文本值处理。 - 运行线程读取使用 `PRAGMA table_info` 适配 schema drift；缺关键列时对应表返回空列表和 `sqlite_schema_drift` / `low` 证据，可选列缺失、NULL 和数值字段按空字符串或文本值处理。
- `.codex/agents/*.toml` 写回必须先备份。 - `.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}/validate` 只校验请求体中的 TOML 草稿、生成 diff、返回目标路径、当前 sha256 hash 和字段变更；该端点不写文件。
- `POST /api/agents/{id}/write` 会重新校验 TOML，重新读取目标文件并比较 `expectedHash`，先创建 `*.bak-<timestamp>` 备份，备份成功后通过同目录临时文件和 rename 原子写回。 - `POST /api/agents/{id}/write` 会重新校验 TOML，重新读取目标文件并比较 `expectedHash`，先创建 `*.bak-<timestamp>` 备份，备份成功后通过同目录临时文件和 rename 原子写回。
- 写回的目标读取、备份、临时文件和 rename 绑定到已打开的 `agents` dirfd；关键步骤会复核 `agents` 目录路径身份、目标文件身份和目标 hash，减少 TOCTOU 窗口。
- 写回 id 只允许安全 bare file stem：字母、数字、下划线、连字符，且不能包含路径分隔符、绝对路径、`.toml` 扩展名或子目录。`agents` 目录 symlink、目标叶子 symlink、非普通文件和路径穿越都会被拒绝。 - 写回 id 只允许安全 bare file stem：字母、数字、下划线、连字符，且不能包含路径分隔符、绝对路径、`.toml` 扩展名或子目录。`agents` 目录 symlink、目标叶子 symlink、非普通文件和路径穿越都会被拒绝。
- validate/write POST body 限制为 1 MiB，拒绝 trailing JSON；路径、系统错误和无效请求统一映射为中文安全响应。
- 无效 TOML、hash 冲突、备份失败或临时文件写入失败都不会替换原文件；临时文件会尽量清理。 - 无效 TOML、hash 冲突、备份失败或临时文件写入失败都不会替换原文件；临时文件会尽量清理。
- 当前 `/api/projects` 只读解析 `.codex/config.toml` 中的 `[projects."..."]`，展示路径、显示名、信任等级和目录存在性。 - `/api/projects` 只读解析 `.codex/config.toml` 中的 `[projects."..."]`，展示路径、显示名、信任等级和目录存在性。
- 当前 `/api/workflow/events` 从运行线程、spawn edges、goals 和计划文件证据生成事件流/交接边/阶段状态，不写死固定流程。 - `/api/workflow/events` 从运行线程、spawn edges、goals 和计划文件证据生成事件流/交接边/阶段状态，不写死固定流程。
- Phase 4 前端不调用真实 API、不保存草稿、不写回 `.codex/agents/*.toml`；所有写回相关控件仅作为只读步骤展示。 - 前端仅在智能体视图提供单文件草稿入口，按钮为“校验 TOML”“查看差异”“创建备份并写回”；只有校验成功且存在 currentHash 时才允许写回，写回前使用浏览器确认。
- Phase 6 前端仅在智能体视图提供单文件草稿入口，按钮为“校验 TOML”“查看差异”“创建备份并写回”；只有校验成功且存在 currentHash 时才允许写回，写回前使用浏览器确认。 - 前端 normalizer 负责把 source kind、confidence、状态和 parseStatus 转成中文显示，并过滤工作流中非阶段表格行。
- Phase 5 前端 normalizer 负责把 source kind、confidence、状态和 parseStatus 转成中文显示，并过滤工作流中非阶段表格行。
## Known Risks ## Known Risks
- Codex 内部 SQLite schema 可能变化。 - Codex 内部 SQLite schema 可能变化。
- 运行状态由多来源推断，必须显示置信度。 - 运行状态由多来源推断，必须显示置信度。
- Phase 3 真实 SQLite 读取已覆盖临时测试库；如果真实 Codex schema 新增字段或缺少可选字段，应继续走 schema-aware 查询和来源证据，而不是让 API 500。 - 真实 SQLite 读取已覆盖临时测试库；如果真实 Codex schema 新增字段或缺少可选字段，应继续走 schema-aware 查询和来源证据，而不是让 API 500。
- Phase 4 只读工作台是静态壳；如果用户误以为它展示真实状态，应优先检查界面是否仍清楚显示来源、置信度和“等待连接 API”提示。 - Agent 列表接口不返回原始 TOML 文本；智能体编辑区展示的是接口返回的已解析字段，并在代码区说明“接口未返回原始 TOML”。
- Phase 5 agent 接口当前不返回原始 TOML 文本；智能体只读编辑区展示的是接口返回的已解析字段，并在代码区说明“接口未返回原始 TOML”。 - 浏览器视觉验证需要可用浏览器工具或主智能体执行；文档记录不得伪造截图结果。
- 写回只覆盖单个已有 agent TOML，不支持创建新 agent、批量写回或自动保存草稿。

17
findings.md
View File

@@ -27,15 +27,18 @@
- 工作流显示使用动态事件流/DAG，不写死阶段或 agent 顺序。 - 工作流显示使用动态事件流/DAG，不写死阶段或 agent 顺序。
- 所有推断状态必须显示来源和置信度。 - 所有推断状态必须显示来源和置信度。
- UI 全中文，技术缩写保留英文。 - UI 全中文，技术缩写保留英文。
- Phase 3 使用纯 Go `modernc.org/sqlite v1.35.0` 读取 SQLite，避免 CGO 运行时依赖，并保持项目 `go 1.22` 兼容。 - 使用纯 Go `modernc.org/sqlite v1.35.0` 读取 SQLite，避免 CGO 运行时依赖，并保持项目 `go 1.22` 兼容。
- SQLite 文件不存在时返回空列表和 `sqlite_missing`/`low` 来源证据；仅 state 或仅 goals 缺失时返回 `sqlite_partial`/`medium` 聚合证据，并在 `sources.state` / `sources.goals` 分别标注缺失或只读来源。 - SQLite 文件不存在时返回空列表和 `sqlite_missing`/`low` 来源证据；仅 state 或仅 goals 缺失时返回 `sqlite_partial`/`medium` 聚合证据，并在 `sources.state` / `sources.goals` 分别标注缺失或只读来源。
- Runtime SQLite 读取先检查 `PRAGMA table_info`；缺关键列时对应表返回空列表和 `sqlite_schema_drift`/`low` 证据，可选列缺失、NULL 值和数值类型字段不导致 Snapshot 失败。 - Runtime SQLite 读取先检查 `PRAGMA table_info`；缺关键列时对应表返回空列表和 `sqlite_schema_drift`/`low` 证据，可选列缺失、NULL 值和数值类型字段不导致 Snapshot 失败。
- Workflow store 未配置 runtime reader 时返回空视图和 `runtime_missing`/`low` 证据，不 panic、不让 API 500。 - Workflow store 未配置 runtime reader 时返回空视图和 `runtime_missing`/`low` 证据，不 panic、不让 API 500。
- 动态工作流事件从 threads、spawn edges、goals、`task_plan.md` 证据构建，不假设固定角色顺序。 - 动态工作流事件从 threads、spawn edges、goals、`task_plan.md` 证据构建，不假设固定角色顺序。
- Phase 4 前端使用 Vue 3 + Vite 和本地静态示例数据实现中文只读工作台；所有示例状态显示来源和置信度，不调用真实 API，不提供保存或写回按钮。 - 前端使用 Vue 3 + Vite，真实数据通过集中 API client 接入；连接失败时才展示明确标注的示例/等待连接状态。
- Phase 5 前端新增集中 API client，仅调用 `/api/agents`、`/api/projects`、`/api/runtime/threads`、`/api/workflow/events` 四个 GET 只读端点。 - 前端集中 API client 调用 `/api/agents`、`/api/projects`、`/api/runtime/threads`、`/api/workflow/events` 四个 GET 只读端点，以及 agent validate/write 两个 POST 写回端点。
- Phase 5 前端 normalizer 统一把后端 source kind、confidence、状态、parseStatus 转为中文展示；空 runtime/workflow 不回退到示例数据，连接失败时示例数据必须标注“示例/等待连接”。 - 前端 normalizer 统一把后端 source kind、confidence、状态、parseStatus 转为中文展示；空 runtime/workflow 不回退到示例数据，连接失败时示例数据必须标注“示例/等待连接”。
- 工作流 phases 需要在前端过滤计划文件中误解析出的非阶段表格行，并把数字阶段名展示为“阶段 N”，避免出现内部英文或无效状态。 - 工作流 phases 需要在前端过滤计划文件中误解析出的非阶段表格行，并把数字阶段名展示为“阶段 N”，避免出现内部英文或无效状态。
- Phase 6 写回只支持单个已有 agent TOML 文件，不创建新 agent；validate 返回当前 sha256，write 使用 expectedHash 阻止校验后覆盖用户改动。 - 写回只支持单个已有 agent TOML 文件，不创建新 agent；validate 返回当前 sha256，write 使用 expectedHash 阻止校验后覆盖用户改动。
- Phase 6 备份文件写在目标文件旁边，命名为 `*.bak-<timestamp>`；只有备份创建成功后才使用同目录临时文件和 rename 替换目标。 - 备份文件写在目标文件旁边，命名为 `*.bak-<timestamp>`；只有备份创建成功后才使用同目录临时文件和 rename 替换目标。
- Phase 6 前端不维护批量草稿队列，不使用 localStorage 自动保存草稿；写回入口在智能体视图，用户确认后才调用 write API。 - 前端不维护批量草稿队列，不使用 localStorage 自动保存草稿；写回入口在智能体视图，用户确认后才调用 write API。
- 最终写回绑定到已打开的 `agents` dirfd：目标读取、备份、临时文件创建和 rename 都使用 `Openat`/`Renameat`，并在关键步骤复核目录身份、目标文件身份和 expectedHash。
- 前端 API client 集中在 `web/src/api/client.js`，封装 agents/projects/runtime/workflow 的 GET，以及 agent validate/write 的 POST；错误通过 `APIError` 带 status 和响应体传递给视图。
- 前端中文 normalizer 集中在 `web/src/api/normalizers.js`，负责 source kind、confidence、status、parseStatus、trust、workflow phase 和写回结果的中文兜底，避免未知后端枚举直接暴露到 UI。

8
progress.md
View File

@@ -31,6 +31,8 @@
| 2026-05-25 | 6 | spec review | 规格审查未通过：TOML 字符串解析错误泄漏英文 `invalid syntax` | coding agent 按 blocking 范围修复 | | 2026-05-25 | 6 | spec review | 规格审查未通过：TOML 字符串解析错误泄漏英文 `invalid syntax` | coding agent 按 blocking 范围修复 |
| 2026-05-25 | 6 | security review | 安全审查未通过：写回存在 TOCTOU、备份后 CAS 缺失、POST body 无限制、错误响应泄漏路径/英文 | coding agent 按 blocking 范围修复 | | 2026-05-25 | 6 | security review | 安全审查未通过：写回存在 TOCTOU、备份后 CAS 缺失、POST body 无限制、错误响应泄漏路径/英文 | coding agent 按 blocking 范围修复 |
| 2026-05-25 | 6 | security review | 安全复审未通过：复核后到 createBackup/rename 前仍可能重新解析被替换的 `agents` 路径 | coding agent 按 blocking 范围修复 | | 2026-05-25 | 6 | security review | 安全复审未通过：复核后到 createBackup/rename 前仍可能重新解析被替换的 `agents` 路径 | coding agent 按 blocking 范围修复 |
| 2026-05-25 | 7 | coding agent | 新增 README，并更新 docs/project.md、task_plan.md、findings.md 的最终状态和安全边界 | 完成；浏览器截图验证待主智能体执行 |
| 2026-05-25 | 7 | coding agent | 运行阶段 7 完整验证命令 | Go 全量测试、非缓存测试、前端单测、前端构建和 whitespace 检查均通过 |
## Test Results ## Test Results
@@ -177,6 +179,12 @@
| 2026-05-25 | `cd web && pnpm test` | PASS | Phase 6 dirfd 绑定修复后前端单测验证通过；共 13 个单测 | | 2026-05-25 | `cd web && pnpm test` | PASS | Phase 6 dirfd 绑定修复后前端单测验证通过；共 13 个单测 |
| 2026-05-25 | `cd web && pnpm build` | PASS | Phase 6 dirfd 绑定修复后前端生产构建通过 | | 2026-05-25 | `cd web && pnpm build` | PASS | Phase 6 dirfd 绑定修复后前端生产构建通过 |
| 2026-05-25 | `git diff --check` | PASS | Phase 6 dirfd 绑定修复 whitespace 检查通过 | | 2026-05-25 | `git diff --check` | PASS | Phase 6 dirfd 绑定修复 whitespace 检查通过 |
| 2026-05-25 | `go test ./...` | PASS | Phase 7 最终 Go 全量验证通过；缓存包通过 |
| 2026-05-25 | `go test -count=1 ./...` | PASS | Phase 7 最终非缓存 Go 全量验证通过 |
| 2026-05-25 | `cd web && pnpm test` | PASS | Phase 7 前端单测通过；13 个测试全部通过 |
| 2026-05-25 | `cd web && pnpm build` | PASS | Phase 7 前端生产构建通过；Vite 构建成功 |
| 2026-05-25 | `git diff --check` | PASS | Phase 7 whitespace 检查通过 |
| 2026-05-25 | Browser visual verification | PENDING_MAIN_AGENT | 阶段 7 不伪造浏览器截图；待主智能体执行并记录 |
## Bug Loop ## Bug Loop

28
task_plan.md
View File

@@ -6,12 +6,12 @@
## Stop Conditions ## Stop Conditions
- [ ] 所有阶段完成 - [x] 所有阶段完成
- [ ] Go 测试通过 - [x] Go 测试通过
- [ ] 前端构建通过 - [x] 前端构建通过
- [ ] 浏览器验证关键页面 - [ ] 浏览器验证关键页面
- [ ] docs/project.md 记录目标、架构、配置、运行方式、安全边界和恢复方式 - [x] docs/project.md 记录目标、架构、配置、运行方式、安全边界和恢复方式
- [ ] 无 blocking bug 或未处理高风险问题 - [x] 无 blocking bug 或未处理高风险问题
## Phases ## Phases
@@ -24,7 +24,7 @@
| 4 | complete | 中文 UI 只读工作台 | 项目/工作流/智能体视图可浏览；空数据可用 | | 4 | complete | 中文 UI 只读工作台 | 项目/工作流/智能体视图可浏览；空数据可用 |
| 5 | complete | API 集成和只读数据显示 | 前端连接只读 API；显示真实 agent 数据和错误状态 | | 5 | complete | API 集成和只读数据显示 | 前端连接只读 API；显示真实 agent 数据和错误状态 |
| 6 | complete | 草稿、TOML 校验、diff、备份、写回 | 草稿不覆盖原文件；无效 TOML 阻止写回；备份成功后才能写回 | | 6 | complete | 草稿、TOML 校验、diff、备份、写回 | 草稿不覆盖原文件；无效 TOML 阻止写回；备份成功后才能写回 |
| 7 | pending | 集成验证与文档 | 测试/构建/浏览器验证通过；文档完整 | | 7 | complete | 集成验证与文档 | 测试/构建通过；浏览器验证待主智能体执行；文档完整 |
## Errors Encountered ## Errors Encountered
@@ -34,11 +34,11 @@
| 2026-05-25 | 1 | 规格复审发现 `ResolveAgentTOML` 可通过 `agents/*.toml` symlink 指向 root `auth.json` 绕过 forbidden 检查 | TDD 补充 symlink-to-auth 测试后检查 resolved final target | 已通过最终验证 | | 2026-05-25 | 1 | 规格复审发现 `ResolveAgentTOML` 可通过 `agents/*.toml` symlink 指向 root `auth.json` 绕过 forbidden 检查 | TDD 补充 symlink-to-auth 测试后检查 resolved final target | 已通过最终验证 |
| 2026-05-25 | 2 | 规格审查发现重复键 TOML 被报告为 valid，且 agent symlink 可读取 Codex home 内非 agent TOML | TDD 补充 duplicate key、invalid key、symlink-to-config 测试后修复 parser 和 agent store 边界 | 已通过最终验证 | | 2026-05-25 | 2 | 规格审查发现重复键 TOML 被报告为 valid，且 agent symlink 可读取 Codex home 内非 agent TOML | TDD 补充 duplicate key、invalid key、symlink-to-config 测试后修复 parser 和 agent store 边界 | 已通过最终验证 |
| 2026-05-25 | 2 | 复审发现 `agents -> .` 目录 symlink 可把 root `config.toml` 当作 agent 读取 | TDD 补充 symlinked agents directory 测试后在 `Store.List` 拒绝 symlinked `agents` 目录 | 已通过最终验证 | | 2026-05-25 | 2 | 复审发现 `agents -> .` 目录 symlink 可把 root `config.toml` 当作 agent 读取 | TDD 补充 symlinked agents directory 测试后在 `Store.List` 拒绝 symlinked `agents` 目录 | 已通过最终验证 |
| 2026-05-25 | 4 | 规格审查发现 UI 直接展示 `local_sample`、`low` 等内部英文值 | 将状态徽标、示例数据和硬编码来源/置信度改为中文展示 | 待复审 | | 2026-05-25 | 4 | 规格审查发现 UI 直接展示 `local_sample`、`low` 等内部英文值 | 将状态徽标、示例数据和硬编码来源/置信度改为中文展示 | 已通过最终验证 |
| 2026-05-25 | 5 | 规格复审发现 UI 残留英文 `agent` 和 `Codex home` | 改为“智能体”和“Codex 主目录”，并补中文文案测试 | 待复审 | | 2026-05-25 | 5 | 规格复审发现 UI 残留英文 `agent` 和 `Codex home` | 改为“智能体”和“Codex 主目录”，并补中文文案测试 | 已通过最终验证 |
| 2026-05-25 | 5 | 规格审查发现 valid agent 未明确显示 TOML 状态，且 UI 仍有 `handoffEdges`、`主 agent`、`developer_instructions` 可见文案 | TDD 补 valid agent 状态和 workflow 空交接文案测试后修复 normalizer 与 WorkflowView 文案 | 待复审 | | 2026-05-25 | 5 | 规格审查发现 valid agent 未明确显示 TOML 状态，且 UI 仍有 `handoffEdges`、`主 agent`、`developer_instructions` 可见文案 | TDD 补 valid agent 状态和 workflow 空交接文案测试后修复 normalizer 与 WorkflowView 文案 | 已通过最终验证 |
| 2026-05-25 | 5 | 代码质量审查发现未知后端枚举值会直接暴露到 UI | TDD 补 unknown source/confidence/status/trust 测试后将未知 label 统一降级为中文兜底 | 待复审 | | 2026-05-25 | 5 | 代码质量审查发现未知后端枚举值会直接暴露到 UI | TDD 补 unknown source/confidence/status/trust 测试后将未知 label 统一降级为中文兜底 | 已通过最终验证 |
| 2026-05-25 | 5 | 质量复审发现未知 workflow phase status 会导致真实阶段被过滤消失 | TDD 补 `in_progress` phase 测试后只过滤表头/伪行，未知状态显示“未知” | 待复审 | | 2026-05-25 | 5 | 质量复审发现未知 workflow phase status 会导致真实阶段被过滤消失 | TDD 补 `in_progress` phase 测试后只过滤表头/伪行，未知状态显示“未知” | 已通过最终验证 |
| 2026-05-25 | 6 | 规格审查发现 malformed TOML 会通过 `strconv.Unquote` 泄漏英文 `invalid syntax` | TDD 补 List/Validate/Write 中文错误断言后包装字符串解析错误 | 待最终验证 | | 2026-05-25 | 6 | 规格审查发现 malformed TOML 会通过 `strconv.Unquote` 泄漏英文 `invalid syntax` | TDD 补 List/Validate/Write 中文错误断言后包装字符串解析错误 | 已通过最终验证 |
| 2026-05-25 | 6 | 安全审查发现写回 TOCTOU、备份后 CAS 缺失、POST body 无限制、错误响应泄漏路径/英文 | TDD 补目录替换、备份后修改、请求体限制和错误脱敏测试后加身份复核/CAS/MaxBytesReader/中文错误映射 | 待最终验证 | | 2026-05-25 | 6 | 安全审查发现写回 TOCTOU、备份后 CAS 缺失、POST body 无限制、错误响应泄漏路径/英文 | TDD 补目录替换、备份后修改、请求体限制和错误脱敏测试后加身份复核/CAS/MaxBytesReader/中文错误映射 | 已通过最终验证 |
| 2026-05-25 | 6 | 安全复审发现复核后到 createBackup/rename 前仍通过路径重新解析父目录 | TDD 补复核后替换 `agents` 为 symlink 测试后，将备份、临时文件和 rename 绑定到已打开的 agents dirfd | 待最终验证 | | 2026-05-25 | 6 | 安全复审发现复核后到 createBackup/rename 前仍通过路径重新解析父目录 | TDD 补复核后替换 `agents` 为 symlink 测试后，将备份、临时文件和 rename 绑定到已打开的 agents dirfd | 已通过最终验证 |