Electron Memory Perf

Core Rule

Analyze the target business module, not the whole project by default. First understand the feature's real workflow and the memory-heavy capabilities it actually uses, then instrument only the user-approved scope.

Workflow

1. Ask the user which feature or module to analyze before adding logs.

   • Examples: full-screen protection, app window protection, screenshot editor, startup idle memory, one IPC flow, one worker, one renderer page.
   • Do not instrument the whole project unless the user explicitly asks.

2. Read code to build a business workflow.

   • Identify entry points, IPC handlers, BrowserWindow/WebContentsView usage, renderer pages, workers, child processes, native addons, capture loops, image/canvas flows, network/AI calls, and cleanup paths.
   • Summarize the workflow in business terms before editing when the scope is non-trivial.

3. Identify only the capabilities used by that business flow.

   • Examples: canvas, Image, DataURL, Blob, Buffer, native addon, worker_threads, child_process, BrowserWindow, desktopCapturer, WebContentsView, OffscreenCanvas, WebGL, WebRTC, AI/OCR requests, IPC large payloads.
   • Memory attribution must be limited to capabilities the target feature actually uses.

4. Find the log path.

   • Search for existing logging code first: electron-log, log.transports.file, app.log, userData, Documents, custom logger modules.
   • If the path cannot be determined confidently, stop and ask the user for the log path.

5. Add structured logs only in the approved module.

   • Every AI-added log must contain the short removable marker AI-PERF.
   • Include both English machine fields and Chinese human labels where useful.
   • Add nearby code comments with AI-PERF: only where they help future removal.
   • The user or a future agent must be able to find all added logs with rg "AI-PERF".

6. Provide the exact command for the user to run after reproducing the problem.

   • Prefer the bundled script:

node <skill>/scripts/electron-perf-report.cjs --log "C:\path\to\app.log" --out "C:\path\to\electron-perf-report.html"

7. Analyze the generated log and report using the business workflow.
   • Explain each important metric in Chinese.
   • Map process metrics back to business actions.
   • Avoid generic conclusions that ignore the feature's actual implementation.

AI-PERF Log Shape

Use one-line structured JSON logs. Prefer this shape and adapt to the project's logger:

log.info('[AI-PERF]', {
  ai_perf: true,
  module: 'fullscreen-protect',
  module_cn: '全画面保护',
  phase: 'capture_after',
  phase_cn: '截图完成',
  capability: 'native-capture',
  capability_cn: 'Native 截图',
  ts: Date.now(),
  duration_ms: 123,
  payload_mb: 7.91,
  main_memory: process.memoryUsage(),
  note_cn: '截图帧已生成，准备送入 AI 识别',
});

For renderer logs, include business and rendering facts:

console.info('[AI-PERF-RENDERER]', JSON.stringify({
  ai_perf: true,
  module: 'fullscreen-protect',
  module_cn: '全画面保护',
  phase: 'canvas_draw_done',
  phase_cn: '打码画布绘制完成',
  capability: 'canvas-image',
  capability_cn: '图片解码与 Canvas 绘制',
  duration_ms: drawMs,
  renderer_memory: performance.memory,
  canvas: {
    mosaic_backing_mb: canvas.width * canvas.height * 4 / 1024 / 1024,
  },
}));

What To Measure

Measure only what the selected business flow uses.

• Native capture or screenshots: capture cost, pixel size, BGRA/RGBA MB, native addon before/after memory.
• AI/OCR/network: request start/end, payload size, response size, predict cost, in-flight count.
• Image/DataURL/Blob: string length, estimated MB, decode cost, natural size, cleanup timing.
• Canvas/WebGL/OffscreenCanvas: backing store estimate, draw cost, clear/reset cost, texture-related steps.
• IPC: payload size, send cost, receive cost, clone/transfer strategy.
• Worker/child process: task cost, rss, external, arrayBuffers, queue length.
• BrowserWindow/WebContentsView: window creation/destruction, visibility, embed/detach, relevant process metrics.
• Idle/startup: timed memory snapshots, loaded windows, active timers, background loops.

Report Expectations

The HTML report must be readable by non-engineers.

• Show Chinese labels first and English fields second: GPU 工作集内存（gpu_working_set_mb）.
• Include a business workflow section derived from the target code/logs.
• Include a "business capabilities used" section.
• Explain memory attribution based on those capabilities.
• Keep raw data searchable for engineers.
• Highlight AI-generated log markers so they can be removed later.

Bundled Resources

• Use scripts/electron-perf-report.cjs to generate a standalone Chinese HTML report from a log file.
• Read references/instrumentation.md before adding logs.
• Read references/interpretation.md before writing the final diagnosis.