# GoodBuddy 性能原则

## 文档信息

- **适用范围：** Desktop（Electron Main、Preload、Renderer）及其后台进程和线程。
- **用途：** 新功能设计和代码评审的约束。多个 agent 并行修改代码时，以本文为统一标准。
- **关联文档：** `docs/roadmap/product-performance-experience-improvement-plan.md`（测量记录与实施进度）。
- **参照：** VS Code 的进程分工和渲染做法。我们没有在同一台机器上实测过 VS Code，下面的预算按常见的流畅标准设定。

## 1. 性能预算

“流畅”用下面的数字判断，不靠感觉。“标准机”指不降速运行 `npm run perf:app`，“低端机”指加上 `GB_PERF_CPU_THROTTLE=4`。

| 指标 | 标准机 | 低端机 |
| --- | --- | --- |
| 按键到下一帧，p95 | ≤ 16 ms | ≤ 50 ms |
| 点击到界面响应（切换会话、打开面板），p95 | ≤ 100 ms | ≤ 300 ms |
| 稳定交互期间（打字、滚动、流式输出）超过 50 ms 的长任务 | 0 | 尽量为 0，总时长不超过场景时长的 5% |
| 流式输出、滚动时的帧间隔，p95 | ≤ 17 ms | ≤ 33 ms |
| Main 事件循环单次阻塞 | ≤ 16 ms | — |
| Main 事件循环延迟，p99 | ≤ 30 ms | — |
| DOM 节点数 | 不随会话数、消息数增长 | 同左 |

标准机的阈值由 `npm run perf:check` 检查。低端机的数值目前只做记录，等结果稳定后再加进阈值检查。

## 2. 原则

### P1 Main 只做调度

Main 负责窗口、生命周期、权限和消息转发。数据库查询、文档解析、哈希、向量计算、批量文件读写，都放到 worker 线程或 `utilityProcess` 里执行。

- 新代码不能在 Main 里使用 `DatabaseSync` 和同步文件 API。lint 已有白名单，名单只能减少。
- 暂时必须留在 Main 的同步操作，单次耗时要能证明在 16 ms 以内，并在代码里注明理由。
- 耗时可能超过 16 ms 的操作，必须支持取消和进度上报，不能一直占着 Main。

### P2 界面状态局部订阅

状态按领域放进外部 store，组件通过 selector 只订阅自己用到的那一部分。

- 不再往 `App.tsx` 里加 `useState`、`useEffect` 或领域逻辑。`App.tsx` 有行数上限，只能往下调。
- IPC 订阅放在 store 模块里，组件不直接调用 `window.goodbuddy.*.on*`。
- 一个按键、一个流式片段，只能让显示它的那一小块界面重新渲染。
- 传给 memo 组件的回调和 context 值，引用必须稳定。

### P3 高频数据走专门通道，按帧合并

流式文本、终端输出、进度、滚动这类高频数据，不进全局状态。

- 多条更新合并后，每帧最多提交一次；同步到全局状态的频率要更低，目前是 250 ms。
- 高频路径上不能读取布局（`getBoundingClientRect`、`scrollHeight` 等），布局读取要集中到每帧一次。
- 合并更新不能丢失、重复或打乱顺序。每条数据带序号，并有测试覆盖。

### P4 数据只有一份来源，只传变化部分

- 每类数据只有一个权威来源，由数据所在进程负责持久化。界面不把整份数据写回。
- 跨进程的通知直接带上变化的内容，接收方不再“收到通知后重新查全量”。
- 写入合并成批次和事务，不按每个事件单独开一个事务。

### P5 工作量和可见内容成正比

- 长列表只渲染可见部分，包括消息、会话、笔记、文件树和知识库列表。
- 解析和渲染的结果要缓存，比如 Markdown 语法树。内容没变，就不重新计算。
- 增量处理：只解析变化的部分。没有把握时，退回到慢但正确的完整处理，并记录在测试里。

### P6 启动只做首屏需要的工作

- 首屏之前只做显示应用壳和恢复上次界面所需的工作。
- 其他初始化（Provider、Runtime、知识库、通知渠道等）按需执行，或等首屏显示后再空闲执行。
- 后台模块在第一次使用时才加载。

### P7 先测量，再修改

- 先跑测量，拿到数据再改代码；每项改动都要有前后对比，基线用临时 worktree 构建。
- 每个版本至少跑 3 轮，交替运行；结果差异小于同一版本多次运行之间的波动时，不能说成“有提升”。
- 测量用隔离的用户目录和本地假模型，不发出外部模型请求，结果里不含用户内容。

### P8 正确性优先于速度

- 事件顺序、持久化、取消、崩溃恢复和显示结果都不能因为性能而改变。
- 异步改造要先确认“先写入、后读取”的顺序，没有测试覆盖就不合并。
- 风险高、收益小，或者会改变现有功能的优化先不做，在计划文档里记录理由。

### P10 体验不倒退

性能优化只能让体验变好，不能用体验换速度。“行为不变”不仅指数据和结果，也包括用户能感知到的交互：

- **动画和过渡保持原样。** 平滑滚动（如“到底部”按钮）、展开收起、悬停、淡入淡出都不能因为优化而消失。任何瞬间写入 `scrollTop`/`scrollTo` 的代码都会打断正在进行的平滑滚动，必须在平滑滚动期间暂停。
- **只渲染可见部分（P5）时，用户状态不能丢。** 行被卸载后，它的局部状态也会消失。以下行必须保持挂载，或者把状态存到行外：有焦点的行、用户展开过 `<details>` 或输入过内容的行、选中文本的两端、待回答的问题和待审批项、打开菜单或正在重命名的行。
- **只渲染可见部分时，基本操作要和完整列表一致：** 跨行选择和复制、滚动位置不因上方插入或删除而跳动（关闭原生 `overflow-anchor` 时要自己做锚定）、快速拖动滚动条时没有空白帧、渲染结果缓存让重新挂载的行不出现“加载中”。
- **合并和批处理不能增加交互延迟。** 第一条数据立即处理（leading edge），只合并之后同一帧内的数据。打字回显、终端回显不能多等一帧。
- **低频同步不能让用户看到旧数据。** 复制、导出、保存这类读取全局状态的操作，要先把待同步的数据刷进去。
- **体验要有测试。** 涉及动画、滚动、焦点的改动，需要真实 Electron 测试（逐帧采样）或单元测试，并确认测试在旧代码上会失败。

### P9 用工具守住规则

- lint 规则和性能阈值是合并前的硬性条件，不靠人工记得。
- 规则只能收紧，白名单和上限只能往下调。
- 每个 agent 只提交自己改的文件和片段，不把别人未提交的改动带进自己的提交。

## 3. 评审清单

提交性能相关改动，或者会影响热点路径的功能改动时，逐项确认：

1. Main 里有没有新增同步数据库调用、同步文件 IO，或者耗时可能超过 16 ms 的计算？
2. 有没有往 `App.tsx` 里加状态？一次按键或一个流式片段，会让多大范围的界面重新渲染？
3. 高频路径上有没有读取布局，有没有每次事件都提交状态？
4. 有没有整份数据回写，或者“收到通知后重新查全量”？
5. 列表的 DOM 数量会不会随数据量增长？
6. 有没有在启动阶段新增同步初始化？
7. 是否附上了 `perf:app`、`perf:main` 或 `perf:knowledge` 的前后对比？
8. 顺序、取消、持久化和恢复，有没有测试覆盖？
9. 动画、平滑滚动、过渡还在吗？有没有新增会打断平滑滚动的瞬间滚动写入？
10. 只渲染可见部分的列表，滚走再滚回来，展开状态、输入内容、选区、焦点还在吗？
11. 合并或延迟处理后，第一次响应（打字回显、点击反馈）有没有变慢？复制、导出读到的是不是屏幕上的最新内容？

## 4. 当前差距

截至 2026-10-03，按原则对照的主要差距：

| 原则 | 差距 |
| --- | --- |
| P1 | 写入和大量同步数据库调用仍在 Main；没有独立数据进程。文档解析、分块和大文件哈希已移到 worker |
| P2 | `App.tsx` 约 9,600 行，当前会话更新时 App 仍会整体重新渲染 |
| P3 | 已基本满足：流式输出和终端输出都已按帧合并 |
| P4 | 界面仍发送整份活动记录；部分 `*Changed` 通知之后还会重新查全量 |
| P5 | 已基本满足：消息、会话、笔记、文件树、知识库文档表格都只渲染可见部分 |
| P6 | 已有基线（`npm run perf:startup`）：启动到输入框可用约 1.0 秒，Main 模块加载约 415 ms、本地工具环境初始化约 155 ms，还没有优化 |
| P9 | 性能阈值还没有接入 CI，也没有真实低端机的基线 |