#性能与内存

# 发现采集和分析 skill；这里只节选相关条目。
agent-lynx skills list

<available_skills>
  <skill>
    <name>lynx-trace-analysis</name>
    <description>Specializes in analyzing Lynx trace data to diagnose performance issues and provide actionable optimization strategies.
Key Scenarios:
  - Loading Performance: Diagnosing slow startup metrics (FCP, FMP, TTI) and white screen issues.
  - Smoothness Analysis: Investigating root causes for scroll jank, frame drops, and interaction lag.
  - Regression Detection: Comparing traces to identify performance degradation or verify optimization gains between versions.
  - Pipeline Deep Dive: Pinpointing bottlenecks in specific rendering stages like Layout, Paint, JS execution, and background threads.
  - Native Module Analysis: Investigating performance issues related to native module calls.
  - Memory Analysis: Diagnosing high PSS, page lifecycle leaks, shared BTS context growth, VM pool waste, and JS heap snapshots.</description>
    <location>/tmp/agent-lynx-perf-docs-20261030/node_modules/@lynx-js/skill-lynx-trace-analysis/SKILL.md</location>
  </skill>
  <skill>
    <name>lynx-trace-record</name>
    <description>This guide provides step-by-step instructions for recording Lynx performance traces. Use this guide when the user asks how to record a trace.</description>
    <location>/tmp/agent-lynx-perf-docs-20261030/node_modules/@lynx-js/skill-lynx-trace-record/SKILL.md</location>
  </skill>
</available_skills>

# 节选先录制后打开页面的规则，以及内存与 GC 选项；执行入口使用当前 CLI 的 trace 命令。
agent-lynx skills get lynx-trace-record

### Step 2. Start recording:
Execute the start command **BEFORE** building or opening the page on your device. This ensures you capture the entire first frame of the page. Use the `--client` parameter with the client ID from Step 1.

…

| Enable memory data collection | `--enable-memory-trace` | `enableMemoryTrace` | `false` |
| Disable automatic Garbage Collection | `--no-force-gc` | `forceGC` | `true` |

Skill directory: /tmp/agent-lynx-perf-docs-20261030/node_modules/@lynx-js/skill-lynx-trace-record

# 打开本地构建的 Settings bundle；从响应中提取页面列表。
agent-lynx open 'http://127.0.0.1:33227/main.lynx.bundle?fullscreen=true' --client "$CLIENT_ID" | jq '.data.data'

[
  {
    "session_id": 1,
    "type": "",
    "url": "http://127.0.0.1:33227/main.lynx.bundle?fullscreen=true"
  }
]

# 确认目标页面已经显示，再结束本次加载采集。
agent-lynx wait --text Settings --client "$CLIENT_ID" --session 1

Matched text "Settings" after 296ms. A fresh snapshot was cached.

# 使用同一 client 停止采集，保留下载句柄，并检查是否丢失数据。
agent-lynx trace end --client "$CLIENT_ID"

{
  "success": true,
  "message": "Tracing completed successfully. Download the stream with `agent-lynx trace read-data`.",
  "stream": "1",
  "dataLossOccurred": false
}

# 把刚返回的 stream 1 保存到本地；下载完成后即可脱离设备分析。
agent-lynx trace read-data --client "$CLIENT_ID" --stream 1 -o ./settings-memory.pftrace

{
  "success": true,
  "message": "Trace data saved successfully.",
  "filePath": "/tmp/agent-lynx-perf-docs-20261030/settings-memory.pftrace",
  "bytesWritten": 154691
}

# 解析本地文件；用 jq 隐去完整事件清单，保留计数和文件标识。
agent-lynx trace event-summary ./settings-memory.pftrace --json | jq 'del(.events)'

{
  "success": true,
  "parseSucceeded": true,
  "trace": {
    "path": "/tmp/agent-lynx-perf-docs-20261030/settings-memory.pftrace",
    "bytes": 154691,
    "sha256": "383b14aaf6e08522eb13969c859a6154c2e0fbebcafeaeca5d6247523edee2e7"
  },
  "eventSource": "slice.name",
  "totalEvents": 8257,
  "uniqueEventNames": 889
}

# 节选分析指南目录；根据问题选择 memory-analysis。
agent-lynx skills get lynx-trace-analysis

### KNOWLEDGE BASE

*These are the "Guidebooks" you must load to know **what** to query.*
- [metrics-analysis](./references/metrics-analysis.md): Guide for: Startup phases, FCP/TTI, Navigation timing, White screen causes.
- [timing-flag](./references/timing-flag.md): Guide for Diagnosing missing performance callbacks, invalid timing flags, and abnormal ActualFMP/FMP durations.
- [jank-analysis](./references/jank-analysis.md): Guide for: Scroll smoothness, Input latency, Long Tasks (>16ms), Frame drops.
- [diff-analysis](./references/diff-analysis.md): Guide for: Comparing two traces, identifying regressions in specific phases.
- [nativemodule-analysis](./references/nativemodule-analysis.md): Guide for: Bridge communication, Native method latency, Serialization costs.
- [render-pipeline](./references/render-pipeline.md): Guide for: Understanding Lynx rendering pipeline, identifying slow stages, and analyzing gaps between metrics.
- [event-analysis](./references/event-analysis.md): Guide for: Diagnosing missing touch/custom/global events, tracing event dispatch to the real business handler, and distinguishing event delivery delay from handler cost.
- [memory-analysis](./references/memory-analysis.md): Guide for: High memory, page load/exit memory changes, memory leaks, shared BTS contexts, scrolling trends, VM pools, and JS heap snapshots.
- [sql-guide](./references/sql-guide.md): Guide for writing raw SQL queries to query trace data.
- [sourcemap-remapping](./references/sourcemap-remapping.md): Guide for remapping line and column numbers from Lynx trace event arguments back to original source positions.

…

Skill directory: /tmp/agent-lynx-perf-docs-20261030/node_modules/@lynx-js/skill-lynx-trace-analysis

// 读取 skill 返回目录中的内存指南；这里节选分析入口和报告命令。
Read $TRACE_SKILL_DIR/references/memory-analysis.md

## First Action

Classify the request, then perform exactly one first action:

| Request | First action |
|---|---|
| Broad memory analysis, high memory, leak check, page load/exit memory | Run `memory-analysis` with the trace path |
| Specific page URL | Run `memory-analysis --url "<substring>"` |
| Specific `instance_id` | Run `memory-analysis --instance-id <id>` |
| Scrolling/sliding trend | Ensure page URL or `instance_id` and an absolute trace time range are known, then run `memory-analysis --scenario scroll --start <ms> --end <ms>` |
| Specific VM snapshot numbers | Run `memory-analysis` first to obtain the VM's 1-based snapshot list |

Do not ask follow-up questions for a broad memory request. The default analysis covers every page created
after trace recording starts.

## Main Analysis Command

```bash
node <path_to_the_skill>/scripts/trace_query.bundle.cjs memory-analysis \
  --path "<trace_path_or_url>" \
  --output "<report_path>.html"
```

# 节选全局内存与 JS 堆快照操作；全局统计和页面 VM 使用不同的 session 范围。
agent-lynx skills get lynx-devtool

#### 15. Take Heap Snapshot

Capture a QuickJS heap snapshot from the current Lynx session and save it as a `.heapsnapshot` file.

```bash
agent-lynx take-heap-snapshot [options]
```

- `-c, --client <clientId>`: (Optional) Client ID.
- `-s, --session <sessionId>`: (Optional) Session ID.
- `--thread <thread>`: (Optional) Target VM thread, `background` or `main`. Defaults to `background`.
- `-o, --output <path>`: (Optional) Output file path. Defaults to the OS temp directory.

#### 16. Query Global Memory Usage

Query Lynx global memory usage through the global `Memory.*` CDP domain. Use the generic `cdp` command and send the request to the global DevTool handler with session ID `-1`.

```bash
# Get global Lynx memory usage across live instances
agent-lynx cdp -s -1 -m Memory.getAllMemoryUsage
agent-lynx cdp -s -1 -m Memory.getAllMemoryUsage '{"timeoutMs":50000}'
```

- `-c, --client <clientId>`: (Optional) Client ID.
- `-s, --session <sessionId>`: CDP session ID. Use `-1` for the global DevTool handler unless you have a platform-specific reason to override it.
- `params.timeoutMs` (Optional): Non-negative timeout in milliseconds. Maximum value is `300000`.

The command prints the raw `Memory.getAllMemoryUsage` JSON. Do not expect the CLI output to contain derived `summary`, `topMemoryItems`, or `topInstances` wrapper fields.

When the DevTool MCP server is available, prefer the `Memory_getAllMemoryUsage` MCP tool for the same raw payload instead of shelling out to the CLI.

…

Skill directory: /tmp/agent-lynx-perf-docs-20261030/node_modules/@lynx-js/skill-lynx-devtool

// 读取支持的 CDP 方法说明，确认全局 session -1 和 timeoutMs 参数。
Read $DEVTOOL_SKILL_DIR/references/cdp/memory/Memory.getAllMemoryUsage.md

# Memory.getAllMemoryUsage

Scope: This is a Lynx global CDP extension. Send it to the global DevTool handler with session ID `-1` unless you have a platform-specific reason to override the session.

- `Memory.getAllMemoryUsage` - Get global Lynx memory usage across live registered Lynx instances.
- Input:
  - `timeoutMs` (integer, optional): Non-negative timeout in milliseconds. `0` or omission lets the platform choose its default wait policy. Maximum accepted value is `300000`; fractional values are rejected.

# 保存后台 VM 的 JS 对象图，供后续检查对象类型和引用链。
agent-lynx take-heap-snapshot --client "$CLIENT_ID" --session 2 --thread background -o ./settings-background.heapsnapshot

Heap snapshot saved to ./settings-background.heapsnapshot

# 另存主线程 VM 快照；两个文件对应同一页面的不同运行时。
agent-lynx take-heap-snapshot --client "$CLIENT_ID" --session 2 --thread main -o ./settings-main.heapsnapshot

Heap snapshot saved to ./settings-main.heapsnapshot