codex-agent-manager/findings.md

Findings

Architecture

• 后端使用 Go。
• 前端使用 Vue 3 + Vite。
• 工具以 localhost Web 应用运行。

Data Sources

• .codex/agents/*.toml: 智能体配置。
• .codex/config.toml: 项目信任配置。
• .codex/state_5.sqlite: threads、thread_spawn_edges；Phase 3 通过 mode=ro&immutable=1 只读打开。
• .codex/goals_1.sqlite: thread_goals；Phase 3 通过 mode=ro&immutable=1 只读打开。
• 本机进程表：Codex 进程辅助判断。
• 项目工作流文件：task_plan.md、findings.md、progress.md、docs/project.md。

Constraints

• 禁止读取或展示 .codex/auth.json。
• 禁止写入 SQLite。
• 默认不写 .codex/config.toml。
• .codex/agents/*.toml 仅允许经草稿、校验、diff、备份、确认后写回。

Decisions

• 工作流显示使用动态事件流/DAG，不写死阶段或 agent 顺序。
• 所有推断状态必须显示来源和置信度。
• UI 全中文，技术缩写保留英文。
• 使用纯 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 分别标注缺失或只读来源。
• Runtime SQLite 读取先检查 PRAGMA table_info；缺关键列时对应表返回空列表和 sqlite_schema_drift/low 证据，可选列缺失、NULL 值和数值类型字段不导致 Snapshot 失败。
• Workflow store 未配置 runtime reader 时返回空视图和 runtime_missing/low 证据，不 panic、不让 API 500。
• 动态工作流事件从 threads、spawn edges、goals、task_plan.md 证据构建，不假设固定角色顺序。
• 前端使用 Vue 3 + Vite，真实数据通过集中 API client 接入；连接失败时才展示明确标注的示例/等待连接状态。
• 前端集中 API client 调用 /api/agents、/api/projects、/api/runtime/threads、/api/workflow/events 四个 GET 只读端点，以及 agent validate/write 两个 POST 写回端点。
• 前端 normalizer 统一把后端 source kind、confidence、状态、parseStatus 转为中文展示；空 runtime/workflow 不回退到示例数据，连接失败时示例数据必须标注“示例/等待连接”。
• 工作流 phases 需要在前端过滤计划文件中误解析出的非阶段表格行，并把数字阶段名展示为“阶段 N”，避免出现内部英文或无效状态。
• 写回只支持单个已有 agent TOML 文件，不创建新 agent；validate 返回当前 sha256，write 使用 expectedHash 阻止校验后覆盖用户改动。
• 备份文件写在目标文件旁边，命名为 *.bak-<timestamp>；只有备份创建成功后才使用同目录临时文件和 rename 替换目标。
• 前端不维护批量草稿队列，不使用 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。