94 lines
3.6 KiB
Markdown
94 lines
3.6 KiB
Markdown
# Project Documentation
|
||
|
||
## Goal
|
||
|
||
构建一个本机 Codex 智能体管理台，用中文管理 agent 配置、项目运行状态、动态工作流和安全写回流程。
|
||
|
||
## Target Architecture
|
||
|
||
计划架构为：Go 后端提供 localhost HTTP API，Vue 3 + Vite 前端提供中文工作台界面。当前后端已提供健康检查、`.codex/agents/*.toml` 只读读取、项目配置只读读取、运行线程只读模型和动态工作流事件模型；目标后端后续仅在用户确认后写回 `.codex/agents/*.toml`。
|
||
|
||
## Configuration
|
||
|
||
- `CODEX_HOME`: 默认 `/Users/yoilun/.codex`
|
||
- 后端监听地址：默认 `127.0.0.1:18083`
|
||
- 前端开发地址：默认 `127.0.0.1:13083`
|
||
- `WorkspaceRoot`: 默认当前进程工作目录，用于读取 `task_plan.md` 等计划文件证据。
|
||
- Go module 目标：`go 1.22`
|
||
- SQLite 驱动：`modernc.org/sqlite v1.35.0`
|
||
|
||
## Runbook
|
||
|
||
启动后端：
|
||
|
||
```bash
|
||
go run ./cmd/codex-agent-manager
|
||
```
|
||
|
||
健康检查：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18083/api/health
|
||
```
|
||
|
||
读取智能体定义：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18083/api/agents
|
||
```
|
||
|
||
读取项目配置：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18083/api/projects
|
||
```
|
||
|
||
读取运行线程：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18083/api/runtime/threads
|
||
```
|
||
|
||
读取动态工作流事件：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18083/api/workflow/events
|
||
```
|
||
|
||
安装并构建前端：
|
||
|
||
```bash
|
||
cd web
|
||
pnpm install
|
||
pnpm build
|
||
```
|
||
|
||
启动 Phase 4 只读前端工作台：
|
||
|
||
```bash
|
||
cd web
|
||
pnpm dev
|
||
```
|
||
|
||
前端开发地址为 `http://127.0.0.1:13083/`。Phase 4 前端仅使用本地静态示例数据，页面文案会标明“示例数据”或“等待连接后端 API”；Phase 5 才接入真实只读 API。前端可保留 `local_sample`、`api_missing` 等内部 source kind，但用户界面必须显示中文来源和 `高 / 中 / 低` 置信度。
|
||
|
||
## Security Boundaries
|
||
|
||
- 不读取 `.codex/auth.json`。
|
||
- 不写入 Codex SQLite。
|
||
- SQLite 通过纯 Go `modernc.org/sqlite v1.35.0` 和 `mode=ro&immutable=1` 打开；缺失 SQLite 返回空列表和低置信度来源说明。
|
||
- 运行线程 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/projects` 只读解析 `.codex/config.toml` 中的 `[projects."..."]`，展示路径、显示名、信任等级和目录存在性。
|
||
- 当前 `/api/workflow/events` 从运行线程、spawn edges、goals 和计划文件证据生成事件流/交接边/阶段状态，不写死固定流程。
|
||
- Phase 4 前端不调用真实 API、不保存草稿、不写回 `.codex/agents/*.toml`；所有写回相关控件仅作为只读步骤展示。
|
||
|
||
## Known Risks
|
||
|
||
- Codex 内部 SQLite schema 可能变化。
|
||
- 运行状态由多来源推断，必须显示置信度。
|
||
- Phase 3 真实 SQLite 读取已覆盖临时测试库；如果真实 Codex schema 新增字段或缺少可选字段，应继续走 schema-aware 查询和来源证据，而不是让 API 500。
|
||
- Phase 4 只读工作台是静态壳；如果用户误以为它展示真实状态，应优先检查界面是否仍清楚显示来源、置信度和“等待连接 API”提示。
|