diagnose-renderer-oom
诊断 renderer OOM(内存耗尽崩溃)。当用户交来 renderer OOM 诊断包(zip 或 logs 目录)、报告编辑器窗口变黑/自动关闭、或提到 renderer OOM / Automatic resume is paused / oom-lo-space-size / 切 tab 后内存冲到数 GB 时使用。
SKILL.md.claude/skills/diagnose-renderer-oom/SKILL.md
GitHub诊断 renderer OOM(内存耗尽崩溃)
renderer OOM 是「堆在被压垮之前没有观测」的那类事故:renderer 自己来不及上报,所以证据全在 main 侧落盘的文件里。诊断包由命令 workbench.action.exportDiagnostics 导出(组成见 docs/development/error-diagnostics.md)。核心套路:先用三件套判定「这是不是 OOM、哪一类增长」,再按族去查元凶,最后核对结论能否被计数器解释。
⚠️ 第一原则:诊断包里的三件套先读全,再谈元凶。历史上三次 OOM(claude 回放、codex 回放、会话改动 tracker)在只看单份日志时都被误判过;三件套齐读能把「崩没崩、崩在哪、崩的时候还有谁在跑」一次锁死。机制/阈值/releaser 表的单一真相是
docs/development/memory-pressure.md,本 skill 只讲读法。
诊断三件套(先读这三份)
processMetrics.log的 renderer 内存曲线。两条线分开读:main 每 30s(有进程超 2GB 时 10s)写pid=… type=Tab mem=…MB cpu=…%(app.getAppMetrics()的 OS 工作集,看不到 V8 堆膨胀)+ renderer 自报的renderer-heap window=… used=…MB limit=…MB usedPct=… level=… holders=…(apps/editor/src/renderer/services/memory/rendererHeapReporter.ts)。判据优先于数值:used涨而holders不涨 = 元凶不在已知持有者里(unexplained=就是那个差值);level=critical在线上方停了多久 = releaser 是否有效。诊断包里memory.txt另存曲线尾部 32 条——日志尾部有 512KiB 截断,会恰好丢掉慢速爬升最早的那几条。acpSessionRestore.log的skipping auto-restore of session <id>: recent OOM crash in this window(apps/editor/src/renderer/services/acp/session/acpSessionRestoreCoordinator.ts:250,通道 idacpSessionRestore在同文件:151)。这行是判决书:出现即本窗口刚发生过被判定为 OOM 的崩溃,且自动恢复已被保护性跳过——别把「重启后会话没回来」再当独立 bug 查。processes.txt里同一 session 的多个--resume命令行(如 3 个claude.exe --resume=<同一 session>)。renderer 崩溃后旧 agent 进程无人回收,crash reload 又 spawn 一个新的:这些孤儿还在后台读扫,放大下一轮压力。修法(AcpHostMainService/ExtensionHostMainService的stopAllForWindow)与计数器口径见docs/development/memory-pressure.md「崩溃恢复链路」。
旁证:sessionWatchedChanges.log(通道 id sessionWatchedChanges,apps/editor/src/renderer/contributions/SessionWatchedChangesContribution.ts:105)的 watched-change storm = 大规模工具活动正在发生,用于解释「为什么这个会话在长」;它本身不是死因。
交叉还原(三件套之外还能看什么)
acpProtocol.log只留尾部 512KB(各日志统一,apps/editor/src/main/services/diagnostics/diagnosticsMainService.ts的LOG_TAIL_BYTES),崩溃前原文常已滚出窗口 → 改用三份交叉还原:processMetrics的曲线形状 +tabSwitchPerf.log里ipc.decode相位的连发(形如ipc.decode (response fileSearch.findFiles #42, 18.4MB),见docs/development/memory-pressure.md§一)+sessionWatchedChanges.log的 storm。ipc-frames.txt:main 侧的帧 ring 记录。renderer 自己那份在 OOM 时来不及落盘,所以「同一份内容被反复读回来」这一维度只有 main 侧这份是权威答案。memory.txt/sysinfo.md:main 堆 + 系统提交内存 + 托管进程树内存 +[memory] …水位行。
判定流程
- 确认是 OOM 而不是别的:
acpSessionRestore的skipping行或errors.jsonl的renderProcessGone(source=renderer:<id>)命中即 OOM 家族;oom-lo-space-size=<n>MB字样直接给出崩溃时的堆量级。都没有则先查error-diagnostics.md的异常退出取证。 - 看曲线形状定「族」(决定后面查哪里):分钟级暴涨(回放期)/ 数小时慢爬(某条常驻路径没有预算)/ 受压线上方长期滞留(释放无效或削的是无关内容)/ 周期性尖峰(另有未修项,见
memory-pressure.md「已知取舍与后续项」)。 - 按族对照预算清单:回放期 → 回放预算窗口与源头 cap(
apps/editor/src/renderer/services/acp/session/cases-memory-budget.md);live 期 →LIVE_INGESTION_BUDGET与 children 递归修剪(同文件);慢爬 → 「每条常驻路径是否都被某个度量覆盖」,重点怀疑_observables/ 缓存类常驻结构。 - 核对结论:结论必须能对上
holders=/counts=/unexplained=与flow=/gauge=两组读数(memory-pressure.md第五、六类缺口)。零修剪告警却在爬升 = 增长完全在记账之外,这才是要报的结论。 - 沉淀:新形态追加到
references/cases.md(信号行必填),并在下方「案例索引」补一行。
案例索引(按三件套信号速查)
skipping auto-restore出现 + 0.5GB→5.5GB / 40s + 会话含子 agent 大量 Read/Grep → 案例 1(回放绕过预算窗口)- 同一 session 多个
--resume孤儿 + 三个独立缺口叠加(live / 回放 / 孤儿) → 案例 2 - 切 tab 后 20s 内冲 4.4GB、
acpProtocol.log尾部窗口不足以还原 → 案例 3(codex 回放无源头 cap) - 0.7GB 慢爬到 5.4GB、
holders与used缺口巨大且修剪告警零命中 → 案例 4(observable 双份全文)
关键参考路径
docs/development/memory-pressure.md—— 机制/阈值/releaser 表/诊断包文件/已知取舍(先读它)docs/development/error-diagnostics.md—— 诊断包组成、errors.jsonl、崩溃闭环、脱敏apps/editor/src/renderer/services/memory/——memoryPressureService.ts(分级与释放)、rendererHeapReporter.ts(曲线出站)、boundedCache.tsapps/editor/src/renderer/services/acp/session/cases-memory-budget.md—— 会话/持久化预算族(含 tracker 活行)apps/editor/src/main/services/diagnostics/—— zip 组装、LOG_TAIL_BYTES、受控堆快照apps/editor/cases-interaction-perf.md+ skillanalyze-interaction-performance—— 渲染节奏 / 切 tab 面
其它
- 后续用本 skill,发现新经验按「判定流程」第 5 步同步更新
references/cases.md与上面的索引。 - 本 skill 只做读法与定性;修完之后的验证走
pnpm check与对应 e2e(如smoke.memoryPressure.spec.ts)。