baa-conductor

commit

0f218b9

parent

79c932a

author

codex@macbookpro

date

2026-03-26 17:12:43 +0800 CST

docs: add planning discussion notes

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

  1@@ -0,0 +1,228 @@
  2+# DISCUSS: plans/ 目录整体核对与改进建议
  3+
  4+日期：2026-03-26
  5+来源：Claude 审查 plans/ 全部文档 + git log + 在线 describe + handoff
  6+
  7+---
  8+
  9+## 0. 紧急：mini 与 Mac 代码不同步
 10+
 11+### 现状
 12+
 13+| 节点 | HEAD | 位置 |
 14+|---|---|---|
 15+| mini | `2ce8d18` | `/Users/george/code/baa-conductor` |
 16+| Mac | `79c932a` | `/Users/george/code/baa-conductor`（刚 clone） |
 17+| gogs | `79c932a` | origin |
 18+
 19+Mac（从 gogs 刚 clone）比 mini 多 4 个 commit：
 20+
 21+```
 22+79c932a docs: refine firefox bridge planning
 23+a29ea3c feat: persist browser bridge metadata
 24+81fa64c docs: add browser bridge persistence tasks
 25+12310df docs: prioritize browser bridge persistence
 26+```
 27+
 28+这意味着 mini 上正在运行的代码**不是最新的**。浏览器桥接持久化的代码（migration 0002、T-S017~T-S020）在 gogs 上但 mini 没拉。
 29+
 30+### 行动
 31+
 32+- mini 执行 `cd /Users/george/code/baa-conductor && git pull`
 33+- 拉完后检查是否需要重新 build 和重启 conductor-daemon
 34+- 确认 migration 0002 是否已在 mini 的 SQLite 里执行过（可能是在 mini 上先开发再 push 的，需要核实）
 35+
 36+---
 37+
 38+## 1. STATUS_SUMMARY.md 基线过期
 39+
 40+### 问题
 41+
 42+`STATUS_SUMMARY.md` 写的基线是 `main@4796db4`，但实际 HEAD 已到 `79c932a`，差了 5 个 commit。
 43+
 44+文档说「T-S001 到 T-S020 已经完成」，这部分是准确的，但以下字段过期：
 45+
 46+- 「当前代码基线」应更新为 `79c932a`
 47+- 「当前新的主需求文档」只列了 BROWSER_BRIDGE_PERSISTENCE，没提 FIREFOX_BRIDGE_CONTROL
 48+- 「当前主 TODO」说已清空，但 handoff 定义了下一个大目标：task scheduler
 49+
 50+### 建议
 51+
 52+每次有新 commit 进 main 时，STATUS_SUMMARY 的基线字段应同步更新。可以考虑在 CI 或 commit hook 中自动检测差异。
 53+
 54+---
 55+
 56+## 2. STATUS_SUMMARY.md 职责过载
 57+
 58+### 问题
 59+
 60+STATUS_SUMMARY 目前同时承担了 5 个角色：
 61+
 62+1. **changelog**（T-S001~T-S020 完成详情）
 63+2. **状态仪表盘**（运行中的服务、在线面）
 64+3. **TODO tracker**（主 TODO、低优先级 TODO）
 65+4. **架构清单**（保留内容、依赖盘点）
 66+5. **决策日志**（4318 兼容层结论）
 67+
 68+结果是文档有 200+ 行，维护成本高，容易局部过期。
 69+
 70+### 建议
 71+
 72+拆分为：
 73+
 74+| 文件 | 职责 |
 75+|---|---|
 76+| `STATUS_SUMMARY.md` | 只保留当前基线、运行状态、活跃需求文档索引、当前 TODO |
 77+| `CHANGELOG.md` 或 `tasks/COMPLETED.md` | T-S001~T-S020 完成记录归档 |
 78+| `ARCHITECTURE.md` | 组件清单、端口分配、在线面、依赖关系 |
 79+| `DECISIONS.md` | status-api 兼容层等架构决策记录 |
 80+
 81+STATUS_SUMMARY 瘦身到 50 行以内，一屏能看完。
 82+
 83+---
 84+
 85+## 3. 低优先级 TODO 重复
 86+
 87+STATUS_SUMMARY 里「当前主 TODO」和「低优先级 TODO」两个章节内容完全一样（清理 4318 依赖 + 提共享模块）。删除其中一个。
 88+
 89+---
 90+
 91+## 4. Handoff 文档不在仓库里
 92+
 93+### 问题
 94+
 95+`HANDOFF-2026-03-24.md` 在 mini 桌面上，不在 git 仓库里。handoff 里定义了 task scheduler 的详细实现路径和验收标准，是关键的规划文档。
 96+
 97+### 建议
 98+
 99+将 handoff 移入仓库：
100+
101+```
102+plans/HANDOFF-2026-03-24.md      # 或 plans/handoffs/
103+```
104+
105+并在 STATUS_SUMMARY 中引用。
106+
107+---
108+
109+## 5. Task Scheduler 需求缺正式文档
110+
111+### 问题
112+
113+Handoff 中「下一步要做的事」描述了 task scheduler 的完整方案（4 步实现路径 + 验收标准），但这属于规划级内容，应该有一份正式的 plans/ 需求文档，就像 BROWSER_BRIDGE_PERSISTENCE 和 FIREFOX_BRIDGE_CONTROL 一样。
114+
115+### 建议
116+
117+新建 `plans/TASK_SCHEDULER_REQUIREMENTS.md`，将 handoff 中的实现路径正式化，补充：
118+
119+- scheduler 的并发策略（同时跑几个 task？单 task 单 step 串行？）
120+- 失败重试策略（step 失败后重试几次？整个 task 标记 failed？）
121+- step 超时定义（codexd turn 超时 vs scheduler 级超时）
122+- task 优先级（当前先不做，但预留字段）
123+
124+---
125+
126+## 6. plans/ 缺少 README 索引
127+
128+### 问题
129+
130+plans/ 里有 3 个需求文档 + 1 个状态汇总 + 1 个 discuss 子目录，但没有 README 说明：
131+
132+- 哪些文档是活跃的 vs 已完成的
133+- 文档之间的依赖/先后关系
134+- 新需求文档应该怎么命名和放置
135+
136+### 建议
137+
138+新建 `plans/README.md`：
139+
140+```markdown
141+# plans/
142+
143+## 活跃需求
144+- BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md — 浏览器登录态持久化
145+- FIREFOX_BRIDGE_CONTROL_REQUIREMENTS.md — 浏览器控制与代发
146+- (待建) TASK_SCHEDULER_REQUIREMENTS.md — 异步任务执行引擎
147+
148+## 状态
149+- STATUS_SUMMARY.md — 全局状态快照
150+
151+## 讨论
152+- discuss/ — 审查意见和改进建议
153+```
154+
155+---
156+
157+## 7. 两份需求文档缺共享术语表
158+
159+### 问题
160+
161+（与 DISCUSS-FIREFOX-BRIDGE-CONTROL.md 第 9 点相同）
162+
163+两份需求文档多处使用相同概念但各自定义：
164+
165+| 术语 | 持久化文档 | 控制文档 |
166+|---|---|---|
167+| 空壳页 | 提到但未定义 URL/实现 | 提到但未定义 URL/实现 |
168+| 凭证指纹 | 定义了要存但没定义生成规范 | 提到不存原始值 |
169+| fresh/stale/lost | 出现在 DB schema | 出现在需求文本 |
170+| account | 提到持久化 | 提到按 account 选择代发目标 |
171+
172+### 建议
173+
174+在 plans/ 下新建 `GLOSSARY.md`，统一定义这些共享概念，两份文档引用而不是各自重复。
175+
176+---
177+
178+## 8. coordination/ 目录缺失
179+
180+### 问题
181+
182+Handoff 文档说「桌面 bugs/ 和 browser-control tasks 移入 coordination/bugs/ 和 coordination/tasks/browser-control/，桌面已清空（commit 41a4dc3）」。但：
183+
184+- mini 仓库 HEAD 是 `2ce8d18`，没有 `41a4dc3` 这个 commit
185+- Mac 仓库 HEAD 是 `79c932a`，也没有 `41a4dc3`
186+- 两边都不存在 `coordination/` 目录
187+
188+这说明 handoff 中关于 coordination 的描述要么是在一个未 push 的分支/worktree 上，要么是还没做。
189+
190+### 行动
191+
192+- 核实 mini 上是否有未 push 的 worktree 或分支包含 coordination/ 变更
193+- 如果 handoff 写的是计划而非已完成，应修正 handoff 措辞
194+- 建议先不建 coordination/，bug 和 task 继续用现有的 tasks/ + plans/ 结构
195+
196+---
197+
198+## 9. 「当前仍需关注」章节缺乏可操作性
199+
200+STATUS_SUMMARY 的「当前仍需关注」是一堆警告和注意事项，但：
201+
202+- 没有 owner（谁负责跟进？）
203+- 没有触发条件（什么时候需要重新评估？）
204+- 部分内容已过时（如 BUG-009 在 T-S004 中标记已修复，但这里还在提 listener 泄漏风险）
205+
206+### 建议
207+
208+改为「已知风险」清单，每条带：
209+
210+| 风险 | 触发条件 | 缓解措施 | 关联任务 |
211+|---|---|---|---|
212+| listener 泄漏 | 新测试绕开 withRuntimeFixture | Code review 检查 | T-S004 |
213+
214+---
215+
216+## 总结：建议改进优先级
217+
218+| # | 问题 | 严重度 | 行动 |
219+|---|---|---|---|
220+| 0 | mini 代码落后 gogs 4 个 commit | **Urgent** | mini git pull + rebuild |
221+| 1 | STATUS_SUMMARY 基线过期 | High | 更新基线和活跃需求引用 |
222+| 4 | Handoff 不在仓库 | High | 移入 plans/ |
223+| 5 | Task Scheduler 缺正式需求文档 | High | 从 handoff 提炼建 plans/ 文档 |
224+| 2 | STATUS_SUMMARY 职责过载 | Medium | 拆分为 4 个文件 |
225+| 6 | plans/ 缺 README | Medium | 新建索引 |
226+| 7 | 共享术语无统一定义 | Medium | 新建 GLOSSARY.md |
227+| 8 | coordination/ 目录声称存在但不存在 | Medium | 核实 handoff 准确性 |
228+| 3 | 低优先级 TODO 重复 | Low | 删一个 |
229+| 9 | 「当前仍需关注」不可操作 | Low | 改为风险清单 |