baa-conductor

DISCUSS-PLANS-DIRECTORY.md

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