@gracker/smartperfetto 1.0.13

package/strategies/knowledge-thermal-throttling.template.md

@@ -0,0 +1,53 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+# Thermal Throttling
+
+## Mechanism
+
+Android devices contain multiple thermal sensors monitoring SoC junction temperature, battery temperature, and skin temperature. When any sensor exceeds a defined threshold, the **thermal governor** intervenes by reducing CPU and GPU frequency caps, limiting the maximum performance available to the system.
+
+### Throttle Chain
+
+```
+Sustained workload → heat generation → thermal zone exceeds threshold
+    → governor reduces frequency cap → CPU/GPU run slower
+    → frame rendering takes longer → frames miss VSync deadline → jank
+```
+
+### Hysteresis
+
+Thermal management uses hysteresis to prevent rapid oscillation. Once throttling activates at threshold T1 (e.g., 85C), it does not deactivate until temperature drops below a lower threshold T2 (e.g., 80C). This means:
+- Throttling onset can lag the actual hot workload by seconds
+- Recovery takes longer than expected -- temperature must drop significantly before full performance restores
+- Users experience prolonged jank even after the heavy workload ends
+
+### Sustained vs Burst Workloads
+
+- **Burst** (< 2s): Brief spikes rarely trigger throttling. The thermal mass of the SoC absorbs short bursts.
+- **Sustained** (> 5-10s): Continuous high load accumulates heat until throttle thresholds are reached.
+- Gaming, video recording, benchmarks, and scroll-through-large-lists scenarios are common sustained workload triggers.
+
+## Trace Signatures
+
+| What to Look For | Meaning |
+|-----------------|---------|
+| `android_dvfs_counters` | Frequency caps imposed by thermal governor |
+| `cpu_frequency_counters` | Actual operating frequency -- compare against max to detect capping |
+| `thermal_zone` counters | Raw temperature readings from SoC sensors |
+| Actual freq << max supported freq | Active thermal throttling |
+| Frequency dropping mid-trace | Throttle onset -- correlate with jank increase |
+| GPU frequency counters | GPU throttling (affects DrawFrame duration) |
+
+### Detection Pattern
+
+Compare the CPU frequency in the first 5 seconds of the trace (before thermal buildup) against the frequency during the janky period. A significant drop (e.g., big core going from 2.8GHz to 1.8GHz) confirms thermal throttling as a contributing factor.
+
+## Typical Solutions
+
+- **Reduce sustained CPU/GPU load**: Optimize shaders, reduce overdraw, simplify animations
+- **Implement frame pacing**: Deliver consistent work per frame instead of bursty patterns. Inconsistent frame times cause higher peak temperatures
+- **Offload to RenderThread**: Move draw work off the main thread to distribute heat across cores
+- **Avoid busy-wait patterns**: Spin loops generate maximum heat with no useful work
+- **Reduce background work during performance-critical paths**: Pause non-essential jobs during scrolling or animation
+- **Consider workload spreading**: Distribute computation across multiple cores rather than saturating one core

package/strategies/linux.strategy.md

@@ -0,0 +1,86 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+---
+scene: linux
+priority: 7
+effort: medium
+required_capabilities:
+  - cpu_scheduling
+optional_capabilities:
+  - cpu_freq_idle
+  - perf_samples
+keywords:
+  - linux
+  - kernel
+  - sched
+  - runqueue
+  - runnable
+  - pmu
+  - perf
+  - cache miss
+  - branch miss
+  - rss
+  - swap
+  - 内核
+  - 调度
+  - 调度延迟
+  - 缓存未命中
+  - 分支预测
+compound_patterns:
+  - "(linux|kernel|内核).*(调度|runqueue|PMU|perf|内存)"
+  - "(sched|runqueue|pmu|perf).*(latency|counter|miss|压力)"
+
+phase_hints:
+  - id: sched_latency
+    keywords: ['sched', 'runnable', 'runqueue', '调度', '延迟', '等待']
+    constraints: '调度问题优先调用 linux_sched_latency_distribution 和 linux_runqueue_depth_timeline；如果用户给定时间窗必须传 start_ts/end_ts。'
+    critical_tools: ['linux_sched_latency_distribution', 'linux_runqueue_depth_timeline']
+    critical: true
+  - id: pmu_perf
+    keywords: ['PMU', 'perf', 'cache miss', 'branch miss', '缓存未命中', '分支预测']
+    constraints: 'PMU 问题调用 linux_perf_counter_hotspots。无 perf sample/counter 数据时必须说明 trace 未启用 PMU，不能给 cache/branch 结论。'
+    critical_tools: ['linux_perf_counter_hotspots']
+    critical: false
+  - id: linux_memory
+    keywords: ['RSS', 'swap', '内存', 'resident', 'process memory']
+    constraints: 'Linux 进程内存问题调用 linux_process_rss_swap_timeline；page fault/reclaim 仍用 page_fault_in_range 做窗口级阻塞证据。'
+    critical_tools: ['linux_process_rss_swap_timeline', 'page_fault_in_range']
+    critical: false
+
+plan_template:
+  mandatory_aspects:
+    - id: sched_or_linux_signal
+      match_keywords: ['linux_sched_latency_distribution', 'linux_runqueue_depth_timeline', 'sched', 'runqueue', '调度']
+      suggestion: 'Linux 调度问题需要包含 sched latency 或 runqueue 深度分析'
+---
+
+#### Linux 内核 / 调度 / PMU 分析
+
+Linux 场景必须先判断 trace 是否包含对应数据源：sched 基础数据通常存在，PMU/perf counter 需要额外 trace_config，RSS/swap 需要内存 counters。
+
+**Phase 1 — 调度延迟与 runqueue：**
+
+```
+invoke_skill("linux_sched_latency_distribution", { package: "<包名>", start_ts: "<start>", end_ts: "<end>" })
+invoke_skill("linux_runqueue_depth_timeline", { start_ts: "<start>", end_ts: "<end>" })
+```
+
+用于判断 Runnable→Running 等待是否构成瓶颈，以及系统级 runnable thread count 是否持续高压。
+
+**Phase 2 — PMU / perf counter（仅数据可用时）：**
+
+```
+invoke_skill("linux_perf_counter_hotspots", { package: "<包名>", start_ts: "<start>", end_ts: "<end>" })
+```
+
+无 perf samples/counters 时，结论必须是"当前 trace 不支持 PMU 判断"。
+
+**Phase 3 — 进程内存 / page fault：**
+
+```
+invoke_skill("linux_process_rss_swap_timeline", { package: "<包名>", start_ts: "<start>", end_ts: "<end>" })
+invoke_skill("page_fault_in_range", { package: "<包名>", start_ts: "<start>", end_ts: "<end>" })
+```
+
+RSS/swap 是容量证据，page fault/reclaim 是阻塞证据，不能互相替代。

package/strategies/media.strategy.md

@@ -0,0 +1,75 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+---
+scene: media
+priority: 6
+effort: medium
+required_capabilities:
+  - cpu_scheduling
+optional_capabilities:
+  - frame_rendering
+  - gpu
+  - gpu_work_period
+  - power_rails
+keywords:
+  - 视频
+  - 音频
+  - 解码
+  - 编码
+  - media
+  - codec
+  - video
+  - audio
+  - decoder
+  - encoder
+  - mediacodec
+  - codec2
+  - omx
+compound_patterns:
+  - "(视频|音频|解码|编码).*(卡顿|耗电|延迟|掉帧)"
+  - "(media|video|audio|codec|decoder).*(jank|power|latency|stutter)"
+
+phase_hints:
+  - id: codec_activity
+    keywords: ['MediaCodec', 'Codec2', 'OMX', 'decoder', 'encoder', '解码', '编码', '视频卡顿']
+    constraints: '优先调用 media_codec_activity 检查 codec/buffer 事件。该 skill 基于 slice 信号；缺 codec trace 时必须标注数据不足。'
+    critical_tools: ['media_codec_activity']
+    critical: true
+  - id: media_rendering_power
+    keywords: ['frame', 'gpu', 'power', '掉帧', '功耗', 'work period']
+    constraints: '视频/媒体卡顿需要结合 frame/GL/GPU/power 证据：必要时调用 scrolling_analysis、gl_standalone_swap_jank、android_gpu_work_period_track、power_consumption_overview。'
+    critical_tools: ['media_codec_activity', 'gl_standalone_swap_jank', 'android_gpu_work_period_track', 'power_consumption_overview']
+    critical: false
+
+plan_template:
+  mandatory_aspects:
+    - id: codec_activity
+      match_keywords: ['media_codec_activity', 'MediaCodec', 'Codec2', 'OMX', '解码', '编码']
+      suggestion: '媒体场景必须检查 codec/buffer 活动或明确说明 trace 缺少媒体信号'
+    - id: render_or_power_context
+      match_keywords: ['gl_standalone_swap_jank', 'android_gpu_work_period_track', 'power_consumption_overview', 'frame', 'gpu', '功耗']
+      suggestion: '媒体卡顿/耗电问题需要补充渲染、GPU 或功耗上下文'
+---
+
+#### 媒体 / Codec 分析
+
+当前公开 stdlib index 没有稳定的 Android codec 专用表，因此媒体基础分析先基于 `slice` / `thread` 信号识别 MediaCodec、Codec2、OMX、CCodec 和 buffer API。
+
+**Phase 1 — Codec 活动与慢事件：**
+
+```
+invoke_skill("media_codec_activity", { package: "<包名>", start_ts: "<start>", end_ts: "<end>" })
+```
+
+重点看 `dequeueInputBuffer` / `queueInputBuffer` / `dequeueOutputBuffer` / `releaseOutputBuffer` 是否出现长耗时，以及 codec 线程是否集中在某个窗口。
+
+**Phase 2 — 渲染/GPU/功耗上下文：**
+
+| 问题 | 调用 |
+|---|---|
+| 视频掉帧但 codec 正常 | `invoke_skill("gl_standalone_swap_jank")` 或按场景切回 scrolling strategy |
+| GPU active region 连续或异常 | `invoke_skill("android_gpu_work_period_track")` |
+| 媒体播放耗电 | `invoke_skill("power_consumption_overview")` |
+
+输出时必须标注媒体 trace 信号来源。如果 codec slices 不存在，只能说明当前 trace 不支持媒体归因，并给出采集建议。

package/strategies/memory.strategy.md

@@ -0,0 +1,94 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+---
+scene: memory
+priority: 4
+effort: medium
+required_capabilities:
+  - gc_memory
+  - memory_pressure
+optional_capabilities:
+  - cpu_scheduling
+  - binder_ipc
+  - battery_counters
+keywords:
+  - 内存
+  - memory
+  - oom
+  - 泄漏
+  - leak
+  - lmk
+  - 内存压力
+  - 内存不足
+  - low memory
+  - out of memory
+  - dmabuf
+  - 内存占用
+compound_patterns:
+  - "内存.*泄漏"
+  - "内存.*压力"
+  - "内存.*不足"
+  - "memory.*leak"
+  - "memory.*pressure"
+
+plan_template:
+  mandatory_aspects:
+    - id: memory_trend_and_gc
+      match_keywords: ['memory', 'oom', 'gc', '内存', 'heap', 'lmk', 'memory_analysis']
+      suggestion: '内存场景建议包含内存使用趋势和 GC 分析阶段 (memory_analysis)'
+---
+
+#### 内存分析（用户提到 内存、memory、OOM、泄漏、LMK）
+
+#### 内存场景关键 Stdlib 表
+
+写 execute_sql 时优先使用（完整列表见方法论模板）：`android_garbage_collection_events`、`android_oom_adj_intervals`、`android_screen_state`
+
+**Phase 1 — 内存概览（1 次调用）：**
+```
+invoke_skill("memory_analysis")
+```
+返回：内存使用趋势、RSS/PSS 分布、内存分类统计。
+
+**Phase 2 — LMK 分析（如果有 LMK 事件）：**
+```
+invoke_skill("lmk_analysis")
+```
+返回：LMK 事件列表、被杀进程、OOM-adj 分布、重启循环检测。
+
+如果需要更轻量的事件/分数视图，或 `lmk_analysis` 结果为空但用户明确问 OOM/adj：
+```
+invoke_skill("lmk_kill_attribution")
+invoke_skill("oom_adjuster_score_timeline")
+invoke_skill("memory_rss_high_watermark")
+```
+- `lmk_kill_attribution`：LMK 事件、被杀进程、adj、oom_score_adj
+- `oom_adjuster_score_timeline`：进程 OOM adj 分数时间线
+- `memory_rss_high_watermark`：RSS high watermark，辅助识别增长型内存压力
+
+**Phase 3 — 深度分析（按需选择）：**
+
+| 信号 | 工具 | 何时使用 |
+|------|------|---------|
+| GPU 内存 / DMA-BUF | `invoke_skill("dmabuf_analysis")` | 图形密集应用的 GPU 内存分析 |
+| Java Heap Graph | `invoke_skill("android_heap_graph_summary")` | trace 含 Java heap dump 时，先确认 sample/process，再按 retained/cumulative size 找主要 class retainer |
+| Bitmap 内存 | `invoke_skill("android_bitmap_memory_per_process")` | 图片/纹理密集应用的 Bitmap footprint；有 heap graph 时同时看 width/height/density/storage/source attribution |
+| GC 压力 | `invoke_skill("gc_analysis")` | Java 堆内存问题、频繁 GC |
+| 页缺失 | `execute_sql` 查询 `page_fault` | 内存映射文件访问延迟 |
+| 系统内存压力 | `invoke_skill("memory_pressure_in_range", { start_ts, end_ts })` | 特定时间段的内存压力事件 |
+
+**Phase 4 — 交叉分析：**
+- 内存压力 + LMK → 检查是否有进程被反复杀死重启（thrashing）
+- GC 频繁 + 内存增长 → 可能存在 Java 对象泄漏
+- Heap graph 可用 + retained class 集中 → 按 `android_heap_graph_summary` 的 top retainer 继续查 dominator/reference path；不要只按 raw object id 下结论
+- DMA-BUF 增长 → GPU 内存泄漏（纹理/Buffer 未释放）
+- 内存压力 + ANR → 系统内存不足导致的 ANR（非 App 代码 Bug）
+
+**输出结构：**
+
+1. **内存概览**：总内存、已用内存、可用内存、趋势（增长/稳定/下降）
+2. **LMK 事件**（如有）：被杀次数、受影响进程、OOM-adj 分布
+3. **内存热点**：内存占用最大的进程/组件
+4. **根因分析**：泄漏证据、压力来源
+5. **优化建议**：按内存类型（Java 堆/Native/GPU/文件映射）分类

package/strategies/multi-trace-result-comparison.strategy.md

@@ -0,0 +1,96 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+---
+scene: multi_trace_result_comparison
+priority: 0
+effort: medium
+required_capabilities: []
+optional_capabilities: []
+keywords:
+  - 分析结果对比
+  - 结果对比
+  - 多 Trace 对比
+  - 多 trace 对比
+  - 多个 Trace 对比
+  - 两个 Trace 对比
+  - 另一个 Trace
+  - 另外一个 Trace
+  - analysis result comparison
+  - result comparison
+  - multi trace comparison
+  - compare snapshots
+  - compare analysis results
+compound_patterns:
+  - "对比.*(分析结果|结果|snapshot|另一个\\s*Trace|另外一个\\s*Trace|两个\\s*Trace|多个\\s*Trace|多\\s*Trace)"
+  - "(分析结果|结果|snapshot|snapshots).*(对比|compare)"
+  - "compare.*(analysis results|snapshots|multi trace|another trace)"
+
+phase_hints:
+  - id: result_snapshot_selection
+    keywords: ['snapshot', '结果', '候选', 'baseline', 'current result', 'analysis result']
+    constraints: '必须先确认要对比的是 AnalysisResultSnapshot，而不是旧的 referenceTraceId raw trace 对比。候选不唯一时必须让用户选择 baseline 和 candidates。'
+    critical_tools: []
+    critical: true
+  - id: matrix_first
+    keywords: ['matrix', 'delta', 'metric', 'fps', 'jank', 'startup', '启动', '帧率']
+    constraints: '定量结论只能来自 ComparisonMatrix 的 normalized metrics。缺失 metric 要标注 missing reason；只有允许回填时才请求 trace backfill。'
+    critical_tools: []
+    critical: true
+
+plan_template:
+  mandatory_aspects:
+    - id: snapshot_scope
+      match_keywords: ['snapshot', 'analysis result', '结果', 'baseline', 'candidate']
+      suggestion: '分析结果对比必须先确认 snapshot 范围、baseline 和 candidates'
+    - id: comparison_matrix
+      match_keywords: ['matrix', 'metric', 'delta', 'fps', 'jank', 'startup', '启动', '帧率']
+      suggestion: '分析结果对比必须构造 ComparisonMatrix，并基于结构化 metric 输出 delta'
+---
+
+#### 分析结果对比（用户提到多个 Trace 的已有分析结果、snapshot、另一个 Trace 结果）
+
+这是新的多窗口/多用户结果快照对比，不是旧的单窗口 `referenceTraceId` 双 Trace raw data 对比。
+
+**核心原则：**
+1. 先对比 `AnalysisResultSnapshot`，不默认唤醒原 TraceProcessor。
+2. 定量结论只来自 `ComparisonMatrix` 中的 normalized metrics。
+3. 不同 scene、设备、包名或采集配置不一致时，结论必须降级并明确说明。
+4. 每个关键数值必须能追溯到 snapshot、metric key 和 evidence refs。
+5. AI 只能解释差异，不允许从自然语言报告里重新抽取或发明指标。
+
+**Phase 1 — Snapshot 范围确认：**
+
+- 当前窗口已有 latest snapshot 时，把它作为默认 baseline 候选。
+- 通过结果目录或候选选择器确认其他可读 snapshot。
+- 候选唯一时可以直接发起 comparison；候选不唯一时必须让用户确认。
+- baseline 必须明确；不要把“当前 Trace”隐式当成所有场景的 baseline。
+
+**Phase 2 — 构造 ComparisonMatrix：**
+
+- 使用 `multi_trace_result_comparison` Skill contract 描述输入输出边界。
+- 构造输入：`snapshot_ids`, `baseline_snapshot_id`, 可选 `metric_keys`, 原始 `query`。
+- 默认 metric 范围：`startup.total_ms`, `scrolling.avg_fps`, `scrolling.jank_rate_pct`。
+- 用户显式要求某个 metric key 时，优先加入 matrix；缺失时进入缺失矩阵。
+
+**Phase 3 — 缺失与回填：**
+
+- snapshot 已有 metric 时优先使用快照值。
+- snapshot 缺少标准 metric，且用户或策略允许回填时，才能回查原 Trace。
+- 回填失败时 comparison 仍完成，并把失败原因写入 missing matrix / uncertainty。
+- 自定义 metric 没有定义 extractor 时不要硬算，返回不支持或缺失原因。
+
+**Phase 4 — 结论输出：**
+
+输出必须包含：
+
+1. `ComparisonMatrix` delta 表，包含 baseline、candidate 值、delta、deltaPct 和 trend。
+2. 显著变化列表，只列出有结构化证据的变化。
+3. 不可比/缺失/回填失败说明。
+4. AI 解释分为“已验证事实”和“推断”，推断必须基于 matrix 中的事实。
+
+禁止：
+
+- 使用旧 `execute_sql_on("reference")` 路线替代结果快照对比。
+- 对单侧缺失 metric 给出百分比变化。
+- 用报告正文里的描述覆盖 normalized metric。

package/strategies/network.strategy.md

@@ -0,0 +1,80 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+---
+scene: network
+priority: 6
+effort: medium
+required_capabilities:
+  - cpu_scheduling
+optional_capabilities:
+  - network_packets
+  - power_rails
+  - battery_counters
+keywords:
+  - 网络
+  - 流量
+  - 数据包
+  - network
+  - traffic
+  - packet
+  - wifi
+  - cellular
+  - 4g
+  - 5g
+  - tcp
+  - udp
+compound_patterns:
+  - "网络.*(流量|耗电|唤醒|请求|包)"
+  - "network.*(traffic|power|wakeup|packet)"
+
+phase_hints:
+  - id: network_packets
+    keywords: ['network', 'traffic', 'packet', '网络', '流量', '数据包', 'tcp', 'udp']
+    constraints: '优先调用 network_analysis。若 android_network_packets 不存在或为空，必须标注 trace 未启用 network_packets，不能解释为没有网络活动。'
+    critical_tools: ['network_analysis']
+    critical: true
+  - id: network_power
+    keywords: ['battery', 'power', 'wakeup', '耗电', '唤醒', '掉电']
+    constraints: '网络耗电问题需要把 network_analysis 与 battery_drain_attribution / power_consumption_overview 组合，区分网络事件链和 rail 级功耗归因。'
+    critical_tools: ['network_analysis', 'battery_drain_attribution', 'power_consumption_overview']
+    critical: false
+
+plan_template:
+  mandatory_aspects:
+    - id: network_data
+      match_keywords: ['network_analysis', 'network', '网络', '流量', 'packet']
+      suggestion: '网络场景必须先调用 network_analysis 或明确说明 network_packets 数据缺失'
+    - id: network_power_context
+      match_keywords: ['battery_drain_attribution', 'power_consumption_overview', '耗电', '唤醒', 'power']
+      suggestion: '网络耗电/唤醒问题需要补充功耗或唤醒上下文'
+---
+
+#### 网络活动分析
+
+网络场景先判断 trace 是否真的采集了 `android.network_packets`。如果没有该数据源，只能给采集建议，不能把空结果解释为"没有网络问题"。
+
+**Phase 1 — 网络流量/协议/接口总览：**
+
+```
+invoke_skill("network_analysis", { package: "<包名>" })
+```
+
+重点看接口分布、方向、协议、socket tag、活跃周期。如果用户关心具体时间段，必须传入 `start_ts` / `end_ts`。
+
+**Phase 2 — 网络耗电/唤醒链路：**
+
+```
+invoke_skill("battery_drain_attribution", { package: "<包名>", start_ts: "<start>", end_ts: "<end>" })
+```
+
+如果 power_rails 可用，再补：
+
+```
+invoke_skill("power_consumption_overview", { package: "<包名>", start_ts: "<start>", end_ts: "<end>" })
+```
+
+输出时明确区分：
+1. 网络包/活跃周期证据
+2. wakelock / suspend-wakeup / job 事件链
+3. rail 级能耗归因是否可用

package/strategies/overview.strategy.md

@@ -0,0 +1,139 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+---
+scene: overview
+priority: 5
+effort: high
+required_capabilities:
+  - cpu_scheduling
+  - device_state
+optional_capabilities:
+  - frame_rendering
+  - startup
+  - binder_ipc
+  - gc_memory
+  - thermal_throttling
+  - power_rails
+  - battery_counters
+keywords:
+  - 发生了什么
+  - 有什么问题
+  - 概览
+  - 整体分析
+  - 场景还原
+  - 场景分析
+  - what happened
+  - overview
+  - analyze the trace
+  - scene reconstruction
+  - 全局分析
+compound_patterns:
+  - "整体.*分析"
+  - "分析.*整体"
+  - "trace.*中.*什么"
+  - "what.*in.*trace"
+
+plan_template:
+  mandatory_aspects:
+    - id: scene_detection_and_drill
+      match_keywords: ['scene', 'overview', '场景', '概览', 'detect', '检测', 'timeline']
+      suggestion: '概览场景建议包含场景检测和问题场景深钻阶段'
+---
+
+#### 概览 / 场景还原分析（用户提到 发生了什么、概览、overview、场景还原）
+
+本策略将 trace 当作一段用户操作的"故事"来解读：先检测发生了哪些场景，再对有问题的场景做针对性深钻。
+
+**Phase 1 — 场景检测（1 次调用）：**
+```
+invoke_skill("scene_reconstruction")
+```
+返回结果包含以下 artifact：
+- `time_range`：trace 时间范围和总时长
+- `screen_events`：屏幕状态变化（亮屏/灭屏/解锁）
+- `app_switches`：前台应用切换列表
+- `gestures`：用户手势（scroll/tap/long_press/swipe）
+- `scroll_starts`：滑动会话起始点
+- `inertial_scrolls`：惯性滑动事件
+- `idle_periods`：空闲时段
+- `launches`：应用启动事件（cold/warm/hot）
+- `sys_events`：系统事件（thermal/low_memory/broadcast）
+- `janks`：卡顿事件
+- `timeline`：合并时间线
+
+**必须获取关键 artifact 的完整数据**：
+```
+fetch_artifact(artifactId, detail="rows", offset=0, limit=50)
+```
+优先获取：`launches`、`gestures`、`inertial_scrolls`、`janks`、`timeline`
+
+**Phase 2 — 问题分级（基于阈值判断）：**
+
+对检测到的每个场景，按以下阈值判断是否存在性能问题：
+
+| 场景类型 | 问题阈值 | 数据来源 |
+|---------|---------|---------|
+| cold_start | duration > 1000ms | launches artifact |
+| warm_start | duration > 600ms | launches artifact |
+| hot_start | duration > 200ms | launches artifact |
+| scroll / inertial_scroll | jank_frames > 0 | janks artifact |
+| tap | total latency > 200ms | gestures artifact |
+| long_press | duration > 500ms | gestures artifact |
+| power / wakelock | wakelock/Doze/battery 状态异常 | Trace 数据完整度 + power/battery skills |
+
+按严重程度排序，选取 **top 3** 问题场景进入深钻。
+如果所有场景都在阈值内，报告"trace 中未检测到明显性能问题"并给出各场景的关键指标。
+
+**Phase 3 — 针对性深钻（路由表）：**
+
+对每个问题场景，调用对应的 Skill 进行深钻：
+
+如果深钻需要 `process_name`，系统会在进程级 Skill 执行前自动做身份准入和参数重写。若准入返回 ambiguous/blocked，调用 `process_identity_resolver` 查看候选进程；后续 Skill 的 `process_name` 使用 `recommended_process_name_param`，报告中的应用身份使用 `canonical_package_name`。
+
+| 场景类型 | 调用的 Skill | 关键参数 |
+|---------|------------|---------|
+| cold_start / warm_start / hot_start | `startup_analysis` | （自动检测启动事件） |
+| scroll / inertial_scroll | `scrolling_analysis` | start_ts, end_ts, process_name |
+| tap | `click_response_analysis` | start_ts, end_ts, package, enable_per_event_detail=false |
+| 有 jank 的时间区间 | `scrolling_analysis` | start_ts, end_ts, process_name |
+| 耗电/唤醒/待机异常 | `battery_charge_timeline` / `android_kernel_wakelock_summary` / `suspend_wakeup_analysis` | start_ts, end_ts |
+
+**不需要深钻的场景类型**（仅在时间线中描述即可）：
+- idle：空闲时段（信息性）
+- app_switch：前台切换（信息性）
+- screen_on / screen_off：屏幕状态变化（信息性）
+
+每个深钻只取概览级别结果（fetch summary artifact），不做逐帧/逐事件详细分析——本策略的目标是全局视角，用户可以对感兴趣的场景发起后续查询做深入分析。
+
+**Phase 4 — 综合输出（叙事式时间线）：**
+
+### 输出结构必须遵循：
+
+1. **Trace 概览**：
+   - 时间范围、总时长、前台应用、设备状态
+   - 一句话总结：这段 trace 记录了什么操作
+
+2. **时间线叙事**（按时间顺序描述用户操作场景）：
+   ```
+   [0.0s - 1.2s] 冷启动 com.example.app — 耗时 1200ms (超过 1000ms 阈值)
+   [1.2s - 3.5s] 空闲等待
+   [3.5s - 8.2s] 列表滑动 — 检测到 12 帧卡顿 (P90 掉帧 2 VSync)
+   [8.2s - 8.8s] 点击操作 — 响应延迟 350ms (超过 200ms 阈值)
+   [8.8s - 10.0s] 空闲
+   ```
+
+3. **问题场景诊断**（每个深钻的场景）：
+   ```
+   ### [严重程度] 场景: [场景类型] — [关键指标]
+   - 时间范围：[start_ts] — [end_ts]
+   - 关键发现：[来自深钻 Skill 的概览级结论]
+   - 初步根因：[基于深钻数据的根因方向]
+   ```
+
+4. **Top 3 建议**：按影响面排序的优化建议
+
+5. **建议后续分析**：
+   - 如果启动慢："可以问'分析启动性能'获取详细根因"
+   - 如果滑动卡顿："可以问'分析滑动卡顿'获取逐帧分析"
+   - 如果点击慢："可以问'分析点击响应'获取逐事件分析"

package/strategies/phase_hint_templates/misdiagnosis_vsync_vrr.template.yaml

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Phase-hint template for failureCategory `misdiagnosis_vsync_vrr`.
+#
+# The strategy patcher (proposeStrategyPatch.ts) renders one of these for
+# every active failure-category. The rendered YAML is appended to the
+# scene's `.strategy.md` frontmatter under `phase_hints` — the LLM never
+# writes YAML directly.
+#
+# Substitution variables (filled by the renderer):
+#   {{categoryId}}             — kebab-case form of failureCategoryEnum
+#   {{patchFingerprint}}       — sha256-truncated stable id
+#   {{appliedAt}}              — unix ms timestamp
+#   {{evidenceSummary}}        — one paragraph from the review agent
+#   {{candidateKeywords}}      — string[] of keyword tokens
+#   {{candidateConstraints}}   — single-paragraph constraint text
+#   {{candidateCriticalTools}} — string[] of tool/skill IDs
+#
+# Renderer rules:
+#   1. Keywords are sorted ascending so cosmetic reordering doesn't change
+#      the patch fingerprint.
+#   2. critical_tools items are validated against the active tool/skill
+#      registry — unknown IDs cause the renderer to refuse the patch.
+#   3. critical: defaults to false. Auto-generated patches never override
+#      a hand-written critical hint.
+#   4. The whole entry is tagged `auto_generated: true` so a human review
+#      can find auto patches in the file.
+
+id: "auto_{{categoryId}}_{{patchFingerprint}}"
+keywords: {{candidateKeywords}}
+constraints: |
+  {{candidateConstraints}}
+critical_tools: {{candidateCriticalTools}}
+critical: false
+auto_generated: true
+applied_at: {{appliedAt}}
+evidence: |
+  {{evidenceSummary}}