baa-conductor

CODEX-TASK-PLANS-OPTIMIZATION.md

  1# Codex 任务：plans/ 文档优化
  2
  3## 上下文
  4
  5仓库：`/Users/george/code/baa-conductor`，分支 `main`
  6
  7`plans/discuss/` 下有两份审查文档，包含具体问题和建议：
  8- `DISCUSS-FIREFOX-BRIDGE-CONTROL.md`（9 个改进点）
  9- `DISCUSS-PLANS-DIRECTORY.md`（10 个改进点）
 10
 11请先完整阅读这两份 discuss 文档，然后按下面的任务清单执行。
 12
 13---
 14
 15## 任务清单
 16
 17### 第一批：结构优化（先做）
 18
 19**T-OPT-01：新建 plans/README.md**
 20
 21索引所有 plans/ 下的文档，标注活跃 vs 已完成，说明文档命名规范。内容简短，50 行以内。
 22
 23**T-OPT-02：新建 plans/GLOSSARY.md**
 24
 25统一定义两份需求文档共享的术语：
 26- 空壳页（Shell Page）：定义 URL 策略、cookie 携带方式、健康检查
 27- 凭证指纹（Credential Fingerprint）：输入字段、哈希算法（SHA-256）、生成侧（插件）、变更语义
 28- 状态三态：fresh / stale / lost 的定义和转换条件
 29- account：含义和唯一性范围
 30
 31**T-OPT-03：STATUS_SUMMARY.md 瘦身**
 32
 33- 更新基线为当前 HEAD（`79c932a`）
 34- 「当前新的主需求文档」加上 FIREFOX_BRIDGE_CONTROL_REQUIREMENTS.md
 35- 删除重复的「低优先级 TODO」章节（和「当前主 TODO」合并）
 36- 将 T-S001~T-S020 完成记录移到 `tasks/COMPLETED.md`（新建）
 37- 将「4318 依赖盘点与结论」移到 `plans/DECISIONS.md`（新建）
 38- 将「当前仍需关注」改为「已知风险」表格，每条带：风险 / 触发条件 / 缓解措施 / 关联任务
 39- 瘦身后 STATUS_SUMMARY 控制在 80 行以内
 40
 41### 第二批：需求文档补充
 42
 43**T-OPT-04：FIREFOX_BRIDGE_CONTROL_REQUIREMENTS.md 补充**
 44
 45根据 DISCUSS-FIREFOX-BRIDGE-CONTROL.md 的建议，在原文档中增加以下章节（不改动已有结构，只追加）：
 46
 471. **迁移策略**：现有 `/v1/browser/claude/*` 接口如何过渡到通用 `api_request` 模型。定义新接口路径命名、旧接口标记为 legacy、灰度切换方式
 482. **SSE 可靠性设计**：stream_event 带递增 seq、断连后的 partial_events 交付、超时阈值（默认 30s）、背压处理
 493. **空壳页实现方案**：引用 GLOSSARY.md 中的定义，补充 tab 健康检查周期
 504. **调度策略默认参数**：抖动（μ=2s σ=0.5s）、限流（10req/min/platform）、退避（base=1s max=60s）、熔断（连续 5 次失败触发，半开探测间隔 30s）。注明参数可通过配置调整
 515. **首版范围标注**：在多 client 相关段落标注「首版：单 client_id 调度」vs「扩展预留」
 526. **Tab 状态模型**：desired vs actual、自动调和策略、tab_restore 的精确语义
 537. **关联文档**：在文档开头增加对 PERSISTENCE 文档和 GLOSSARY 的引用
 54
 55**T-OPT-05：BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md 补充**
 56
 571. **凭证指纹规范**：引用 GLOSSARY.md
 582. **关联文档**：在文档开头增加对 CONTROL 文档和 GLOSSARY 的引用
 59
 60**T-OPT-06：新建 plans/TASK_SCHEDULER_REQUIREMENTS.md**
 61
 62从桌面 handoff（内容见下方附录）提炼正式需求文档，补充：
 63- scheduler 并发策略（首版：单 task 串行，step 串行）
 64- 失败重试策略（step 失败不重试，task 标记 failed，人工决定是否重跑）
 65- step 超时定义（默认 120s，可覆盖）
 66- task 优先级（首版：FIFO，预留 priority 字段）
 67- 执行链路选择原则：codexd = 代码任务（有文件系统）、browser = 对话任务（无文件系统），由 task step 的 executor 字段决定
 68
 69### 第三批：收尾
 70
 71**T-OPT-07：plans/README.md 最终更新**
 72
 73所有文档都到位后，更新 README 索引，确保引用准确。
 74
 75---
 76
 77## 约束
 78
 79- 只改 `plans/` 和 `tasks/` 目录下的 markdown 文件
 80- 不改任何 `.ts`、`.js`、`.json`、`.sql` 代码文件
 81- 不改 `apps/`、`packages/`、`ops/` 下的内容
 82- 新建文件用 UTF-8，行尾 LF
 83- commit message 格式：`docs: <简述>`
 84- 每个 T-OPT 可以单独 commit，也可以合并 commit，但不要跨批次合并
 85
 86---
 87
 88## 附录：Handoff Task Scheduler 方案摘要
 89
 90目标：conductor task 异步执行引擎
 91
 92当前架构缺口：
 93```
 94POST /v1/tasks          ← 未实现
 95      ↓
 96scheduler loop          ← hook 在 ConductorDaemon.runSchedulerPass，未接线
 97      ↓
 98codexd turn executor    ← 每个 step = 一次 codexd turn
 99      ↓
100result → 下一个 step
101```
102
103最小实现路径（4 步）：
1041. POST /v1/tasks — 接受 { repo, task_type, title, goal, steps[] }，写入 SQLite
1052. scheduler loop 接线 — 每 10s runSchedulerPass，扫 queued tasks
1063. codexd turn executor — 创建 session → 发 turn → 轮询 events.jsonl → 写结果
1074. 查询接口 — GET /v1/tasks、/v1/tasks/:id、/v1/tasks/:id/logs（已有）
108
109DB schema 已完整（ops/sql/schema.sql），db 方法已有（insertTask/insertTaskStep/insertTaskRun）。
110
111验收标准：提交含 1-2 个 codexd step 的 task → scheduler 自动拾取执行 → status 变 done → GET 可查结果。
112
113关键约束：
114- codex turn 走 nginx 会 502，走本地 100.71.210.78:4317
115- BUG-010 存在，回复从 events.jsonl 读
116- 先做最小可跑版本