42 lines
3.0 KiB
Markdown
42 lines
3.0 KiB
Markdown
# 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 全中文，技术缩写保留英文。
|
||
- Phase 3 使用纯 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` 证据构建，不假设固定角色顺序。
|
||
- Phase 4 前端使用 Vue 3 + Vite 和本地静态示例数据实现中文只读工作台；所有示例状态显示来源和置信度，不调用真实 API，不提供保存或写回按钮。
|
||
- Phase 5 前端新增集中 API client，仅调用 `/api/agents`、`/api/projects`、`/api/runtime/threads`、`/api/workflow/events` 四个 GET 只读端点。
|
||
- Phase 5 前端 normalizer 统一把后端 source kind、confidence、状态、parseStatus 转为中文展示；空 runtime/workflow 不回退到示例数据，连接失败时示例数据必须标注“示例/等待连接”。
|
||
- 工作流 phases 需要在前端过滤计划文件中误解析出的非阶段表格行，并把数字阶段名展示为“阶段 N”，避免出现内部英文或无效状态。
|
||
- Phase 6 写回只支持单个已有 agent TOML 文件，不创建新 agent；validate 返回当前 sha256，write 使用 expectedHash 阻止校验后覆盖用户改动。
|
||
- Phase 6 备份文件写在目标文件旁边，命名为 `*.bak-<timestamp>`；只有备份创建成功后才使用同目录临时文件和 rename 替换目标。
|
||
- Phase 6 前端不维护批量草稿队列，不使用 localStorage 自动保存草稿；写回入口在智能体视图，用户确认后才调用 write API。
|