# 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 脚本会同时塞进这三层。