Add proposals for deferred root-cause refactors (B2/B4/C1/C2/C4/C7/M2/M5/M7-M12)

This commit is contained in:
ZacharyZhang-NY committed 2026-04-20 10:53:16 -04:00
1 parent 77076e7b29
commit 06d58d9fd6
15 files changed
+3660

No files matched your search

+252
View File
@@ -0,0 +1,252 @@
# Proposal M12: renderer 状态层审查(IPC 契约化后做)
> 来源:问题.md M12(行 290-294)、附录 D(行 403-408)
> 状态:proposed
> 提出:Roundtable 2026-04-20(Linus + Karpathy + Steve Jobs)
> Owner: TBD
> 估计工时:3-4 周
> Blocking dependencies:**M2(IPC 契约化)必须先完成**
## 问题陈述
104 个 IPC channel(见 M2)基本都在给 renderer 推状态:
- profile snapshot
- task list
- run events
- browser actions
- approvals
- messages
- …
renderer 如何 debounce、merge、避免 stale read,**本次 review 未深入**——但缺乏契约层的前提下几乎必然有一致性 bug。
典型问题猜测(需 M2 完成后验证):
1. **Race condition**:两个 IPC response 几乎同时到达,后到覆盖先到,但语义上应该合并
2. **Stale read**:renderer 发 request → main 返回 → 中间 main 已经又写了一次 → renderer 拿到 stale snapshot
3. **过度 refetch**:renderer 没有合适的 cache,每次切换页面都重 fetch(浪费 IPC round trip)
4. **Event dedup**:同一个 run event 被多个订阅路径接收,渲染时重复展示
5. **Optimistic update 回滚**:renderer 本地 optimistic 更新,但 main 拒绝后没有正确回滚
## 根因分析
当前未知——本 proposal 承认**review 没覆盖 renderer**。
Linus 视角推测:104 个 channel × N 种 payload shape × 若干订阅者 = 巨大的状态空间。没有类型契约(M2 未完成)时,renderer 层的一致性问题**无法静态证明也无法系统性测试**。M2 是前置条件——契约化后才能逐个 channel audit。
Karpathy 视角补充:renderer 的 UI state 错乱直接让用户看到 "agent 跑着但 UI 显示闲置" 或 "approval 已批但列表还在" 等典型 bug。这种 bug 很难用 unit test 捕捉,需要 e2e 验证 + state invariant checking。
## 设计方案
本 proposal 是**审查方案**而不是修复方案——具体修法要等审查结果。
### 审查范围
`src/renderer/` 全部代码,重点:
1. **状态管理库**:目前是 zustand(从 `package.json` 看到依赖)
2. **IPC 订阅点**:`useEffect` 里调 `window.api.invoke` / 订阅 event 的位置
3. **数据合并逻辑**:event 到达时如何 merge 到 store
4. **缓存策略**:哪些数据缓存、TTL 多少、如何失效
5. **Optimistic update**:哪些 action 先改 UI 再等 ack
### 审查 checklist
| 项 | 检查内容 |
|----|---------|
| 1 | 每个 zustand store 的 state shape 是否 type-safe(借助 M2 的 IpcOutput 类型) |
| 2 | 每个 IPC invoke 的 response 处理,是否考虑 race(后到请求覆盖先到请求) |
| 3 | 每个 event subscription,是否 dedup(同一 event 不同路径接收) |
| 4 | Optimistic update 的回滚逻辑完备性 |
| 5 | 组件 unmount 时 subscription cleanup |
| 6 | 跨 route 切换时 store 是否 reset(避免显示上一个 company 的数据) |
| 7 | 长列表的 virtualization(react-virtual 已在依赖里,实际使用覆盖度) |
| 8 | Loading / error / empty 三种边界态覆盖 |
### 预期产出
审查结束后产出 `docs/proposals/M12-renderer-findings.md`,按严重度列出发现的具体问题,每条给修复 proposal(可能演化为独立 proposal)。
### 审查方法
1. **静态**:
- grep `window.api.invoke` 找所有 call site
- grep `useEffect` + IPC 调用 找订阅点
- 对照 M2 的 IpcChannels 一一核对 shape
2. **动态**:
- 启动 app,开 React DevTools 看 zustand store 状态
- 触发典型场景(agent run、approval flow、task update),观察 state transition
- 故意制造 race(背景 run 发 event + 前景用户交互)
3. **e2e**:
- 用 Playwright(tests/e2e 已配置)写 invariant 检查脚本:
- 任何时刻 UI 显示的 "pending approvals" 数量 = main 进程 DB 查询结果
- 任何时刻 UI 显示的 "active runs" = DB runs where status=running
## Migration 计划(审查后)
审查阶段:
1. **Phase 1(1 周)**:静态扫描 + 形成 findings 列表
2. **Phase 2(1 周)**:动态测试 + Playwright invariant script
3. **Phase 3(1 周)**:按严重度归类,高严重度的 findings 进入后续 sprint 修复
4. **Phase 4(1-2 周)**:根据 findings 可能派生出新的 proposal(例如"renderer-state-race-fixes")
## 风险与回滚
| 风险 | 触发条件 | 回滚方法 |
|------|---------|---------|
| 审查范围失控 | 发现问题太多,sprint 无法覆盖 | 按严重度分批,每个 sprint 处理一类 |
| 修复引入新 bug | 动 renderer state 逻辑 | 每类修复独立 PR + e2e 验证 |
| M2 没完成就启动 | 契约化未完成导致审查无类型依据 | 不做,等 M2 |
## 验证标准(审查阶段)
1. **覆盖率**:grep 可见所有 `window.api.invoke` 都被审查
2. **Findings 数**:产出具体 finding 列表(预估 20-40 条)
3. **E2E invariant**:至少 5 条关键 invariant 被 playwright 脚本覆盖
4. **修复 backlog**:高优先 finding 进入下个 sprint
## 不在范围
- **不做 renderer 架构重写**:只是审查 + 针对性修复
- **不换状态管理库**:zustand 保留
- **不改 UI 设计**:只审数据流
- **不重构 route 层**:url routing 逻辑独立
- **不做 A/B 测试设施**:UI 实验独立 proposal
## 参考文件清单
- `src/renderer/`(全部,待审查)
- `src/preload/index.ts`(IPC bridge)
- `src/main/ipc-*.ts`(main 侧 handler)
- `tests/e2e/playwright.config.ts`(e2e 测试配置)
- M2 契约表(前置依赖)
## 附:为什么现在放一个"审查 proposal" 而不是修复 proposal
本次代码 review(2026-04-20)**明确跳过了 renderer 深入**——review report 也坦白了这点。列 M12 不是占位,是承认"这里有未知的坑"。
**第一性原理**:不能在没契约(M2)的前提下审 renderer 状态——审的结论无法落成 executable 测试。必须等 M2 完成后,renderer 层的问题才有具体形状。
M12 也是 IPC-related 所有 proposal 的收官——M2 完成 + M12 审查完 + 修复完,整个 main ↔ renderer 的契约面才算治理完整。
Karpathy 视角:Agent 的 UI 呈现错误("agent 跑完了但还在 spinner")直接伤害产品 perception——用户不会分辨是 LLM bug 还是 state bug,一律认为"这 agent 不可靠"。所以 renderer state 治理的优先级实际比列 M 级更高,但依赖链强迫它排在后面。
## 附:审查输出模板
审查结束后 `docs/proposals/M12-renderer-findings.md` 的结构:
```markdown
# M12 Findings (<date>)
## 🔴 Critical findings
### F-01: <具体问题>
- 文件:src/renderer/xxx.tsx:<行号>
- 重现:<最小重现步骤>
- 影响:<用户层面影响>
- 建议修复:<简短描述>
## 🟠 Major findings
...
## 🟡 Minor findings
...
## Covered e2e invariants
1. <invariant 1>
2. <invariant 2>
...
```
## 附:gating matrix
| Gate | 条件 | 放行判断人 |
|------|------|----------|
| G1 | M2 IPC 契约化完成 | Linus |
| G2 | 审查 checklist 8 项全覆盖 | Owner |
| G3 | Findings 列表产出并分类(≥20 条) | Linus |
| G4 | e2e invariant 脚本 ≥5 条可运行 | Karpathy |
| G5 | 高优先 findings 进入下 sprint 修复 | Owner |
## 附:关键 invariant 候选
e2e playwright 要覆盖的状态不变式:
1. UI "pending approvals" count = DB approvals where status = 'pending'
2. UI "active runs" = DB runs where status = 'running'
3. Task card 显示的 phase = DB tasks.phase(B2 完成后)
4. Agent message 未读数 = DB agent_message_reads 未读行数
5. 某 company 被切换后,UI 不应残留前一 company 数据
6. Approval 批准后,UI 应在 1s 内从 pending 列表消失
7. Task 从 todo → in_progress 时,spinner 应立即显示
8. Browser action 执行中,main 进程可见 subprocess status = running
## 附:为什么现在不做 proposal 只做审查
当前 review 团队(Linus + Karpathy + Jobs)**没有覆盖 renderer**——贸然给出修复 proposal 等于凭想象出方案。本 proposal 诚实承认这是"审查准备"阶段,具体修复待发现。
## 附:为什么不选其他方案
**方案 A(当前 proposal)**:先审查后修复,M2 做前置。
**方案 B(一次性 renderer 重写)**:风险极大——renderer 代码量不小,重写周期长,期间 UI 完全不可用。
**方案 C(按路由逐 page 重写)**:逻辑上可行,但 findings 可能跨 page(例如多个 page 用同一个 bug store),按 page 重写解决不了。
方案 A 是发现问题 → 针对性修复的稳妥路径。
## 附:常见 renderer state 反模式(待审查时排查)
审查重点观察以下 pattern:
1. **useEffect 里 invoke 没 AbortController**:组件 unmount 但 promise 仍 resolve,导致 "setState on unmounted component"
2. **event listener 没 cleanup**:`ipcRenderer.on("xxx", h)` 返回的 listener 没在 `useEffect` 清理
3. **派生 state 存 store**:本可以 derive 的数据写入 store,引入一致性问题
4. **Optimistic update 没 rollback**:`store.setState({ ... })` 后 invoke 失败,UI 保持错误态
5. **同一 data 多次 fetch**:切换 tab 每次重 fetch,没有 cache 或 cache 失效策略不当
6. **Route 切换 store 不 reset**:上一个 company 的数据残留到当前 company 视图
7. **Event dedup 缺失**:同一 run_event 被多个路径转发到 renderer,渲染时重复
8. **List 未 virtualize**:大列表渲染全量 DOM,滚动卡顿
审查时对每个 store 和每个大组件逐项核查。
## 附:playwright e2e invariant 脚本骨架
```ts
// tests/e2e/invariants.spec.ts(M12 产出)
test("pending approvals UI = DB", async ({ page, electronMain }) => {
await page.goto("/approvals");
const uiCount = await page.locator("[data-testid=pending-approval]").count();
const dbCount = await electronMain.evaluate(() =>
db.approvals.count({ status: "pending" })
);
expect(uiCount).toBe(dbCount);
});
test("active runs UI = DB", async ({ page, electronMain }) => {
await page.goto("/runs");
const uiRunning = await page.locator("[data-status=running]").count();
const dbRunning = await electronMain.evaluate(() =>
db.runs.count({ status: "running" })
);
expect(uiRunning).toBe(dbRunning);
});
// ... 至少 5 条 invariant
```
## 附:renderer store 梳理(待 M2 完成后形成清单)
M2 完成后,M12 审查第一步:把每个 zustand store 列出来 + 它订阅的 IPC channel 映射,形成:
| Store | 订阅 channel | 更新策略 | 发现的问题 |
|-------|------------|---------|----------|
| agentsStore | `agents/list` + `agents/updated` event | ? | 待审 |
| tasksStore | `tasks/list` + `tasks/updated` event | ? | 待审 |
| ... | ... | ... | ... |
## 附:e2e harness 运行频率
- PR 触发:快速 invariant(< 30s 跑完的子集)
- 夜间 build:全量 invariant + soak test(5 分钟持续交互)
- Release gate:全量 + manual QA pass
M12 审查结束后产出的 invariant 脚本会同时塞进这三层。