@gracker/smartperfetto 1.0.13

package/strategies/anr.strategy.md

@@ -0,0 +1,200 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+---
+scene: anr
+priority: 1
+effort: medium
+required_capabilities:
+  - anr
+  - cpu_scheduling
+optional_capabilities:
+  - binder_ipc
+  - lock_contention
+  - gc_memory
+keywords:
+  - anr
+  - 无响应
+  - 应用无响应
+  - 主线程无响应
+  - deadlock
+  - not responding
+  - 死锁
+  - watchdog
+  - broadcast timeout
+  - input dispatching
+  - 冻屏
+  - freeze
+  - 卡死
+
+phase_hints:
+  - id: freeze_verdict
+    keywords: ['verdict', '判定', 'freeze', 'diagnosis', '诊断', '原因', 'anr_analysis', '系统', 'system']
+    constraints: 'freeze_verdict 是第一优先级门控。system freeze → 系统原因排查；app_specific → 进入 App 根因决策树（5 步子流程）。禁止在未确认 freeze_verdict 前直接分析 App 代码。'
+    critical_tools: ['anr_analysis']
+    critical: true
+
+plan_template:
+  mandatory_aspects:
+    - id: anr_root_cause
+      match_keywords: ['anr', 'deadlock', 'block', '死锁', '阻塞', 'not_responding', 'anr_analysis']
+      suggestion: 'ANR 场景建议包含 ANR 原因定位阶段 (anr_analysis)'
+---
+
+#### ANR 分析（用户提到 ANR、无响应、not responding、死锁、冻屏）
+
+**⚠️ 核心原则：**
+1. **先判系统还是应用**：`system_freeze_check` 的 `freeze_verdict` 是第一优先级判定。系统冻屏导致的 ANR 不是 App Bug
+2. **按 ANR 类型差异化分析**：INPUT_DISPATCHING / BROADCAST / SERVICE / CONTENT_PROVIDER 的分析路径不同
+3. **四象限 + blocked_functions 交叉定位根因**：与启动分析相同的诊断方法论
+4. **量化证据链**：每个根因判断必须有 blocked_function、线程状态占比、Binder 对端等具体证据
+
+### ANR 类型与超时阈值
+
+| ANR 类型 | 超时阈值 | 触发条件 |
+|----------|---------|---------|
+| INPUT_DISPATCHING_TIMEOUT | 5s | 输入事件分发无响应 |
+| BROADCAST_OF_INTENT | 10s (前台) / 60s (后台) | BroadcastReceiver.onReceive() 超时 |
+| EXECUTING_SERVICE | 20s (前台) / 200s (后台) | Service.onCreate()/onStartCommand() 超时 |
+| CONTENT_PROVIDER_NOT_RESPONDING | 10s | ContentProvider 发布超时 |
+| NO_FOCUSED_WINDOW | 5s | 无焦点窗口（通常是 Activity 启动异常） |
+
+#### ANR 场景关键 Stdlib 表
+
+写 execute_sql 时优先使用（完整列表见方法论模板）：`android_oom_adj_intervals`、`android_monitor_contention_chain`、`android_screen_state`、`sched_latency_for_running_interval`、`cpu_utilization_in_interval(ts, dur)`、`android_garbage_collection_events`
+
+**Phase 1 — ANR 检测 + 系统健康评估（1 次调用）：**
+```
+invoke_skill("anr_analysis")
+```
+- 如果知道包名，传入 `process_name` 或 `package` 参数
+- 返回结果包含以下关键 artifact：
+  - `detection`：ANR 检测（总数、受影响进程数、时间跨度）
+  - `cpu_health`：系统 CPU 负载（大核/小核利用率、是否过载）
+  - `memory_pressure`：ANR 窗口内的 LMK 事件
+  - `io_load`：各进程的 D-state（IO 阻塞）时长
+  - `lock_waits`：futex/mutex 锁等待分布（P95/max）
+  - **`system_freeze_check`**：**系统冻结判定（最关键）**
+  - `anr_overview`：ANR 分类统计
+  - 逐 ANR 的 `anr_detail` 迭代结果（四象限、阻塞原因、Binder、锁竞争、唤醒链等）
+
+**必须获取关键 artifact 的完整数据**：
+```
+fetch_artifact(artifactId, detail="rows", offset=0, limit=50)
+```
+优先获取：`system_freeze_check`、`anr_overview`、逐 ANR 的 `quadrant`（四象限）和 `blocking`（阻塞原因）
+
+**Phase 2 — 冻结判定分流（基于 freeze_verdict，第一优先级）：**
+
+### ⚠️ 必须首先检查 `system_freeze_check` 的 `freeze_verdict` 字段：
+
+| freeze_verdict | 含义 | 后续分析方向 |
+|---------------|------|-------------|
+| `system_server_freeze` | system_server 冻结（running_pct < 5%） | **系统级问题**：system_server watchdog、kernel panic、硬件故障。报告为系统问题，不是 App Bug |
+| `system_freeze` | 多数应用冻结（frozen_pct > 70%）但 system_server 未冻结 | **系统级问题**：可能是 CPU 饥饿（thermal throttling、后台负载）、内存压力（大量 LMK）、IO 风暴。交叉检查 `cpu_health` 和 `memory_pressure` |
+| `app_specific` | 仅目标应用受影响 | **应用级问题**：进入 Phase 3 详细分析主线程阻塞原因 |
+
+**当 `freeze_verdict = system_server_freeze` 或 `system_freeze` 时：**
+- 直接报告为系统级问题，不要深入分析 App 代码
+- 交叉检查：`cpu_health` 显示 `overloaded` → CPU 饥饿；`memory_pressure` 有大量 LMK → 内存压力；`io_load` 有高 IO wait → IO 风暴
+- 建议用户检查系统侧日志（logcat system_server、kernel dmesg）
+- **跳过 Phase 3，直接到 Phase 4 输出**
+
+**Phase 3 — App 级根因诊断决策树（当 freeze_verdict = app_specific）：**
+
+### 第一步：看四象限分布（来自 anr_detail 的 `quadrant`）
+
+| 四象限 | 占比 | 含义 | 下一步 |
+|--------|------|------|--------|
+| Q4 Sleeping 极高 | >80% | **主线程被阻塞**（ANR 最常见原因） | → 第二步：用 blocked_functions 定位 |
+| Q3 Runnable 高 | >30% | CPU 饥饿——可运行但得不到 CPU | → 检查 `sched_latency`、`cpu_health`、后台进程抢占 |
+| Q1+Q2 Running 高 | >70% | CPU-bound——主线程在执行重计算 | → 检查 `main_thread_slices`、热点函数 |
+| 混合 | 无明显主导 | 多因素共同导致 | → 依次排查 Q4→Q3→Q1 |
+
+### 第二步：当 Q4 占比高时 — 用 blocked_functions + 线程状态定位
+
+从 `blocking`（主线程状态分布）artifact 中读取 `blocked_function` 字段：
+
+| 线程状态 | blocked_functions 特征 | 根因类型 | 典型场景 |
+|---------|----------------------|---------|---------|
+| S (Sleeping) | `futex_wait_queue` / `futex_wait` | **锁等待** | art_lock_contention、monitor 竞争、synchronized 块 |
+| S (Sleeping) | `binder_wait_for_work` / `binder_ioctl` | **同步 Binder 阻塞** | 跨进程 IPC 等待 system_server/对端进程响应 |
+| S (Sleeping) | `do_epoll_wait` / `ep_poll` | **Looper 空闲/等待事件** | 正常空闲等待（非阻塞，排除性证据） |
+| S (Sleeping) | `pipe_wait` / `pipe_read` | **管道等待** | 等待子线程/进程通信 |
+| S (Sleeping) | `SyS_nanosleep` / `hrtimer_nanosleep` | **主动 sleep** | Thread.sleep() 在主线程 |
+| D (Disk Sleep) | `io_schedule` / `blkdev_issue_flush` | **磁盘 IO** | 大文件读写、SQLite 操作 |
+| D (Disk Sleep) | `SyS_fsync` / `do_fsync` | **fsync 刷盘** | SQLite WAL checkpoint、SharedPreferences commit |
+| D (Disk Sleep) | `filemap_fault` / `do_page_fault` | **页缺失** | 内存映射文件首次访问 |
+
+### 第三步：按 ANR 类型差异化分析
+
+当 blocked_functions 不足以确定根因时，结合 ANR 类型缩小范围：
+
+| ANR 类型 | 重点检查 | 关键 artifact |
+|----------|---------|-------------|
+| INPUT_DISPATCHING_TIMEOUT | 主线程在做什么？是否有长 Binder 调用或锁等待阻塞了 input 处理 | `blocking`、`binder_calls`、`main_sync_binder`、`lock_contention` |
+| BROADCAST_OF_INTENT | `onReceive()` 内是否有网络/IO/数据库操作在主线程执行 | `blocking`、`main_thread_slices`（查找 onReceive 相关 slice）、`io_load` |
+| EXECUTING_SERVICE | `onCreate()`/`onStartCommand()` 是否有耗时初始化 | `main_thread_slices`、`blocking` |
+| CONTENT_PROVIDER_NOT_RESPONDING | ContentProvider 发布阻塞 | `blocking`、`binder_calls` |
+| NO_FOCUSED_WINDOW | Activity 启动异常，可能是 ANR 前 Activity 未完成创建 | 检查是否有关联的启动事件 |
+
+### 第四步：进阶诊断工具（按需）
+
+| 工具 | 何时使用 | artifact |
+|------|---------|---------|
+| **唤醒链（wakeup_chain）** | Q4 高但 blocked_function 为空时 — 谁唤醒了主线程？ | `wakeup` |
+| **锁竞争（lock_contention）** | blocked_function 含 futex/monitor 时 — 谁持有锁？ | `lock_contention`（from `android_monitor_contention`） |
+| **App 冻结检测（app_freeze_check）** | 判断应用是否完全无活动（MainThread+RenderThread+Binder 全部无活动） | `freeze` |
+| **RenderThread 分析** | INPUT_DISPATCHING_TIMEOUT 中，检查是否 nSyncDraw/dequeueBuffer 阻塞 | `render_thread` |
+| **Binder 调用详情** | blocked_function 含 binder 时 — 对端进程是谁？ | `binder_calls`、`main_sync_binder` |
+| **调度延迟** | Q3 Runnable 高时 — 具体延迟分布 | `sched` |
+
+### 第五步：交叉验证系统上下文
+
+- **CPU 负载** (`cpu_health`)：大核 avg_util_pct > 90% → CPU 饥饿参与因素
+- **内存压力** (`memory_pressure`)：ANR 窗口内有 LMK → 可能是 GC 压力或进程被回收重启
+- **IO 负载** (`io_load`)：多进程 D-state 高 → 系统级 IO 瓶颈
+- **锁等待** (`lock_waits`)：futex P95 > 20ms → 严重锁竞争系统级问题
+
+**Phase 4 — 综合输出：**
+
+### 输出结构必须遵循：
+
+1. **ANR 概览**：
+   - ANR 事件数、受影响进程数、时间跨度
+   - 系统冻结判定结果（`freeze_verdict`）+ system_server 状态
+   - 如果是系统级问题，明确标注 **"⚠️ 系统级问题，非应用 Bug"**
+
+2. **系统健康摘要**：
+   - CPU 负载状态（正常/繁忙/过载）
+   - 内存压力（LMK 事件数）
+   - IO 负载（Top 进程 D-state）
+
+3. **逐 ANR 根因分析**（每个 ANR 事件）：
+   ```
+   ### ANR #N: [进程名] — [ANR 类型] ([超时阈值])
+   - **四象限**：Q1=XX% Q2=XX% Q3=XX% Q4=XX% → 状态判断: [blocked/cpu_starved/busy_running]
+   - **根因推理链**：
+     ① 四象限显示 Q4=NN%（主线程大量时间被阻塞）
+     ② 线程状态：S(Sleeping) = XXms，blocked_function = `futex_wait_queue` → 锁等待
+     ③ 锁持有者：[线程名] 在执行 [操作]（来自 lock_contention）
+     ④ 结论：[具体根因 + 证据]
+   - **App 冻结状态**：[正常/部分冻结/完全冻结]
+   - **Binder 影响**：[主线程同步 Binder 总时长、关键对端]
+   ```
+
+4. **优化建议**：
+   - 按影响面排序
+   - 区分系统侧 vs 应用侧建议
+   - 系统冻屏：建议检查 system_server watchdog、thermal、内存压力
+   - 应用锁等待：建议减少 synchronized 范围、使用异步 Binder
+   - 应用 IO 阻塞：建议将 IO 移到后台线程
+   - CPU 饥饿：建议检查后台进程、调整线程优先级
+
+⚠️ **禁止的做法：**
+- 不检查 `freeze_verdict` 就开始分析 App 代码（可能把系统冻屏误判为 App Bug）
+- 只说"主线程被阻塞"而不提供 blocked_function 和具体阻塞对象
+- 忽略 `wakeup_chain` 数据（这是定位间接依赖链的关键）
+- 把所有 ANR 统一用同一个决策路径分析，不区分 ANR 类型
+- 忽略 `app_freeze_check`（应用完全冻结 vs 部分响应是重要区分）
+- 不交叉检查 CPU/内存/IO 系统上下文就下结论

package/strategies/arch-compose.template.md

@@ -0,0 +1,10 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+<!-- No template variables — static content -->
+### Jetpack Compose 分析注意事项
+- **Recomposition**：关注 `Recomposer:recompose` slice 频率和耗时，频繁重组是性能杀手
+- **LazyList**：`LazyColumn`/`LazyRow` 的 `prefetch` 和 `compose` 子 slice 影响滑动流畅度
+- **Hybrid View**：如果 isHybridView=true，传统 View 和 Compose 混合渲染，需关注 `choreographer#doFrame` 中的 Compose 耗时
+- **State 读取**：过多的 State 读取（尤其在 Layout 阶段）会触发不必要的重组
+- **线程模型**：与标准 Android 相同（MainThread + RenderThread），但 Compose 的 Layout/Composition 阶段在 MainThread

package/strategies/arch-flutter.template.md

@@ -0,0 +1,17 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+<!-- No template variables — static content -->
+### Flutter 分析注意事项
+- **线程模型**：Flutter 使用 `N.ui` (UI/Dart)  和 `N.raster` (GPU raster) 线程替代标准 Android MainThread/RenderThread
+- **帧渲染**：观察 `N.raster` 线程上的 `Rasterizer::DrawToSurfaces` slice，它是每帧 GPU 耗时的关键指标
+- **Engine 差异**：Skia 引擎看 `SkCanvas*` slice；Impeller 引擎看 `Impeller*` slice
+- **SurfaceView vs TextureView**：
+  - **SurfaceView（单出图）**：1.ui → 1.raster → BufferQueue → SurfaceFlinger。Jank 来源在 1.ui/1.raster，不涉及 RenderThread
+  - **TextureView（双出图）**：1.ui → 1.raster(光栅化) → JNISurfaceTexture(纹理桥接, trace 中显示为 `JNISurfaceTextu`) → RenderThread(updateTexImage + composite)。Jank 可能在 1.ui、1.raster 或 RenderThread updateTexImage，也需关注 JNISurfaceTexture 桥接开销
+- **Jank 判断**：需同时看 `N.ui` (Dart 逻辑耗时) 和 `N.raster` (GPU raster 耗时)，任一超帧预算都会导致掉帧
+
+### 结论必须包含的 Flutter 信息
+- **渲染管线类型**：必须在结论概览中明确标注 SurfaceView（单出图）或 TextureView（双出图），并描述对应的渲染管线路径
+- **Engine 类型**：标注 Impeller 或 Skia（如检测为 UNKNOWN，说明判断依据）
+- **线程对应关系**：说明 1.ui/1.raster 线程与哪个进程对应

package/strategies/arch-standard.template.md

@@ -0,0 +1,31 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+<!-- No template variables — static content -->
+### 标准 Android HWUI 渲染架构指南
+
+**线程模型：**
+- **主线程 (main)**: View 树遍历 (measure → layout → draw)，生成 DisplayList/RenderNode
+- **RenderThread**: 执行 DisplayList → GPU 绘制命令 → swap buffers (通过 EGL)
+- **SurfaceFlinger**: 接收 app 提交的 Buffer → HWC/GPU 合成 → 送显
+
+**帧渲染流水线 (BLAST, Android 12+):**
+1. Choreographer 在 VSync 信号触发 doFrame 回调
+2. 主线程执行 traversal: measure → layout → draw → buildDisplayList
+3. 主线程通过 syncFrameState 将 DisplayList 传给 RenderThread
+4. RenderThread 执行 DrawFrame: 发出 GPU 命令 → EGL swap → BLASTBufferQueue
+5. SurfaceFlinger 通过 acquireBuffer 获取帧 → HWC 合成 → Present Fence → 上屏
+
+**分析要点：**
+- FrameTimeline 表可用：`actual_frame_timeline_slice` + `expected_frame_timeline_slice`
+- 卡顿检测依赖 FrameTimeline 的 jank_type 字段 (app_deadline_missed, sf_deadline_missed 等)
+- 主线程 → RenderThread 的 syncFrameState 是关键分界点：如果主线程的 draw 阶段慢，RenderThread 开始就晚
+- 关注 `DrawFrame` slice 在 RenderThread 上的耗时：正常 <8ms
+- 关注 `dequeueBuffer` / `queueBuffer` 延迟：如果 SurfaceFlinger 消费慢，producer 端 dequeueBuffer 会被阻塞
+- GPU 完成时间由 Fence 信号反映，关注 `waiting for GPU completion` 或 `Fence` 相关 slice
+
+**常见瓶颈模式：**
+- 主线程 measure/layout 过重 → draw 延迟 → RenderThread 开始晚 → 整帧超时
+- RenderThread GPU 命令过多 → DrawFrame 耗时 → swap 延迟
+- SurfaceFlinger 合成慢 (GPU composition 多 layer) → 下一帧 dequeueBuffer 阻塞
+- VSync 偏移不当 → app 和 SF 的 VSync 相位冲突

package/strategies/arch-webview.template.md

@@ -0,0 +1,9 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+<!-- No template variables — static content -->
+### WebView 分析注意事项
+- **渲染线程**：GL Functor 模式下 WebView 的 DrawGL 在 App RenderThread 中执行（是帧耗时的重要组成部分）；SurfaceControl 模式下有独立的 Viz Compositor 线程，不经过 RenderThread
+- **Surface 类型**：GLFunctor (传统) vs SurfaceControl (现代)，后者性能更好
+- **JS 执行**：观察 V8 相关 slice（`v8.run`, `v8.compile`）来定位 JS 瓶颈
+- **帧渲染**：WebView 帧不走 Choreographer 路径，需通过 SurfaceFlinger 消费端判断掉帧

package/strategies/comparison-conclusion.template.md

@@ -0,0 +1,36 @@
+You are generating the AI conclusion for a persisted SmartPerfetto multi-trace analysis-result comparison.
+
+Use only the structured comparison matrix, deterministic facts, and warnings in the input. Do not invent metrics, trace events, root causes, or recommendations that are not supported by the matrix.
+
+Return JSON only, with this exact shape:
+
+{
+  "verifiedFacts": ["fact from numeric matrix and evidence"],
+  "inferences": ["careful interpretation that follows from the verified facts"],
+  "recommendations": ["next action grounded in the compared metrics"],
+  "uncertainty": ["known limitation, missing metric, or comparability concern"]
+}
+
+Requirements:
+
+- Keep every numeric claim tied to a metric already present in the matrix.
+- Separate verified numeric facts from interpretation.
+- Mention missing metrics, scene mismatch, or metadata comparability risks in uncertainty.
+- Prefer concise bullet-like strings. Do not return Markdown outside the JSON.
+- Output language: {{outputLanguage}}.
+
+User request:
+
+{{query}}
+
+Comparison matrix JSON:
+
+{{matrixJson}}
+
+Deterministic verified facts:
+
+{{deterministicFacts}}
+
+Existing uncertainty:
+
+{{uncertainty}}

package/strategies/comparison-methodology.template.md

@@ -0,0 +1,41 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+## 对比分析方法论
+
+当两个 Trace 同时可用时，遵循以下结构化对比流程：
+
+### Phase 1: 对齐确认
+1. 调用 `get_comparison_context()` 获取两个 Trace 的元数据
+2. 确认包名对齐（相同应用 → 直接对比；不同应用 → 在结论中标注差异）
+3. 确认能力交集（`commonCapabilities`）— 后续对比仅限交集范围
+
+### Phase 2: 结构化数据收集
+1. 对当前 Trace 使用 `invoke_skill` 获取核心分析数据
+2. 对参考 Trace 使用 `execute_sql_on('reference', ...)` 获取同类数据
+3. 重点收集可量化对比的指标：
+   - 帧耗时分布（P50/P90/P99）
+   - Jank 帧数量和类型分布
+   - 关键线程 CPU 占用
+   - 启动各阶段耗时
+
+### Phase 3: 差异深钻
+对 Phase 2 中差异显著的指标（>10% 变化），使用 `execute_sql_on` 深入分析：
+- 差异的具体分布（哪些帧/阶段贡献了差异）
+- 系统上下文差异（CPU 频率、温控、内存压力）
+- 根因推断（为什么参考 Trace 更好/更差）
+
+### Phase 4: 结构化结论
+输出格式：
+
+1. **Delta 表格**（必须）：
+| 指标 | 当前 Trace | 参考 Trace | 变化 | 评估 |
+|------|-----------|-----------|------|------|
+
+2. **根因分析**：解释主要差异的根本原因
+3. **建议**：基于对比结果的优化建议
+
+### 约束
+- 所有数值必须标注归一化方式（绝对值 / 百分比变化 / 占总时长比例）
+- 不要对比单侧缺失的数据 — 在 delta 表中标注 "N/A"
+- 每个数据引用必须标注来源：`[当前 Trace]` 或 `[参考 Trace]`

package/strategies/comparison-result-methodology.template.md

@@ -0,0 +1,35 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+## 分析结果对比方法论
+
+该方法论只适用于持久化 `AnalysisResultSnapshot` 的对比。它与旧的双 Trace raw-data 对比不同：默认比较已完成分析的结构化结果，只有在明确允许且资源预算允许时才回查原 Trace。
+
+### 输入确认
+
+1. 明确 `baseline_snapshot_id` 和候选 `snapshot_ids`。
+2. 确认所有 snapshot 在同一 workspace 内可读。
+3. 检查 scene、包名、设备、采集配置是否可比；不一致时降低结论强度。
+4. 用户没有明确选择且候选不唯一时，必须请求选择，不要自动猜。
+
+### Matrix First
+
+1. 先构造 `ComparisonMatrix`，再生成解释。
+2. 定量结论只引用 normalized metric：metric key、value、unit、source、confidence、evidence refs。
+3. delta 只在 baseline 与 candidate 双方都有值时计算。
+4. 缺失值必须保留在 missing matrix 中，不要用 0 或空字符串代替。
+
+### 回填边界
+
+1. snapshot 已有值时不要重新查询 Trace。
+2. 标准 metric 缺失且 `allowTraceBackfill=true` 时，可以用 TraceProcessorLease 回填。
+3. 回填失败不应中断 comparison run；把失败原因写入 uncertainty。
+4. 自定义 metric 只有在有 extractor 或已存在 snapshot metric 时才可定量比较。
+
+### 输出要求
+
+- 先给 delta 表，再给显著变化。
+- 每个关键结论拆成“已验证事实”和“推断”。
+- 对不同 scene、不同设备、不同采集配置明确标注不可比风险。
+- 每个优化建议必须指向一个已验证事实或显著变化。
+- 不从旧报告正文或聊天记录中重新抽取数值。

package/strategies/game.strategy.md

@@ -0,0 +1,121 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+---
+scene: game
+priority: 4
+effort: medium
+required_capabilities:
+  - cpu_scheduling
+optional_capabilities:
+  - gpu
+  - thermal_throttling
+  - surfaceflinger
+  - gpu_work_period
+  - power_rails
+  - cpu_freq_idle
+keywords:
+  - 游戏
+  - game
+  - 帧率
+  - 游戏卡顿
+  - 游戏掉帧
+  - unity
+  - unreal
+  - 游戏性能
+  - game fps
+  - game performance
+  - godot
+  - cocos
+compound_patterns:
+  - "游戏.*卡"
+  - "游戏.*帧"
+  - "game.*jank"
+  - "game.*fps"
+
+phase_hints:
+  - id: game_loop_jank
+    keywords: ['game', 'Unity', 'Unreal', 'Cocos', 'Godot', '主循环', 'Tick', 'PlayerLoop', 'GameThread', '帧率', '卡顿']
+    constraints: '游戏/引擎场景必须先用 game_fps_analysis 看整体帧率，再用 game_main_loop_jank 检查引擎主循环/Tick 超预算切片。不要把缺 FrameTimeline 误判成没有掉帧。'
+    critical_tools: ['game_fps_analysis', 'game_main_loop_jank']
+    critical: true
+  - id: game_gpu_power
+    keywords: ['gpu', 'work period', 'mali', 'thermal', '功耗', '发热', '降频']
+    constraints: 'GPU/功耗/发热问题按数据完整度补充 android_gpu_work_period_track、mali_gpu_power_state、thermal_throttling、wattson_thread_power_attribution；缺 capability 时标注证据等级。'
+    critical_tools: ['android_gpu_work_period_track', 'mali_gpu_power_state', 'thermal_throttling', 'wattson_thread_power_attribution']
+    critical: false
+
+plan_template:
+  mandatory_aspects:
+    - id: fps_and_gpu
+      match_keywords: ['game', 'fps', '游戏', 'gpu', 'frame', '帧率']
+      suggestion: '游戏场景建议包含帧率分析和 GPU 状态检查阶段'
+    - id: engine_loop_jank
+      match_keywords: ['Unity', 'Unreal', 'Cocos', 'Godot', 'GameThread', 'PlayerLoop', 'Tick', '主循环']
+      suggestion: '游戏引擎场景建议包含 game_main_loop_jank 阶段，检查引擎自管帧循环'
+---
+
+#### 游戏性能分析（用户提到 游戏、game、帧率、游戏卡顿）
+
+游戏渲染管线与标准 Android View 不同：没有 FrameTimeline，不使用 Choreographer/RenderThread 流程。
+需要使用 `game_fps_analysis`（非 `scrolling_analysis`）作为入口。
+
+#### 游戏场景关键 Stdlib 表
+
+写 execute_sql 时优先使用（完整列表见方法论模板）：`android_gpu_frequency`、`cpu_utilization_per_second`、`cpu_frequency_counters`、`android_dvfs_counters`、`android_screen_state`
+
+**Phase 1 — 游戏帧率分析（1 次调用）：**
+```
+invoke_skill("game_fps_analysis", { process_name: "<游戏进程名>" })
+```
+返回：帧率统计、帧间隔分布、卡顿帧列表。
+
+**Phase 1.5 — 引擎主循环 / Tick 深钻：**
+
+```
+invoke_skill("game_main_loop_jank", { process_name: "<游戏进程名>", start_ts: "<trace_start>", end_ts: "<trace_end>" })
+```
+
+检查 Unity `PlayerLoop` / `Camera.Render` / `Gfx.WaitForPresent`、Unreal `FrameGameThread` / `GameThread` / `RHIThread`、Cocos `Director::mainLoop`、Godot `Main::iteration` 等切片是否超过目标帧预算。该阶段补的是应用生产端节奏，不能用 FrameTimeline 缺失来证明游戏无卡顿。
+
+**Phase 2 — GPU 深度分析（推荐）：**
+
+游戏通常是 GPU-bound。调用 GPU 相关分析：
+```
+invoke_skill("gpu_analysis")
+```
+检查 GPU 频率/利用率、Fence 等待时间。
+
+如果 Trace 数据完整度显示 `gpu_work_period` 可用，再补充：
+```
+invoke_skill("android_gpu_work_period_track")
+invoke_skill("mali_gpu_power_state")
+```
+用于判断 GPU active region 是否连续、Mali power state 是否异常。无 `gpu_work_period` 时只能做 GPU 频率/帧间隔定性分析。
+
+**Phase 3 — 系统级交叉分析：**
+
+| 信号 | 检查工具 | 说明 |
+|------|---------|------|
+| CPU 频率下降 | `invoke_skill("thermal_throttling")` | 游戏长时间运行容易触发热节流 |
+| 内存压力 | `invoke_skill("memory_analysis")` | 游戏内存占用大，可能触发 LMK |
+| CPU 调度 | `invoke_skill("cpu_analysis")` | 游戏线程调度到小核会造成帧率波动 |
+| 线程/进程 CPU 利用率 | `invoke_skill("cpu_thread_utilization_period")` / `invoke_skill("cpu_process_utilization_period")` | 判断 UnityMain/GameThread/RenderThread 是否 CPU-bound |
+| 功耗归因 | `invoke_skill("wattson_thread_power_attribution")` | 仅在 power_rails + cpu_freq_idle 可用时做线程能耗归因 |
+| 独立 GL swap 间隔 | `invoke_skill("gl_standalone_swap_jank")` | NativeActivity/GLSurfaceView 或引擎自管 swap 时检查生产端 present 节奏 |
+
+**Phase 4 — 引擎特定分析：**
+
+| 引擎 | 关键线程 | 关键 Slice |
+|------|---------|-----------|
+| Unity | UnityMain, UnityGfx | `PlayerLoop`, `Gfx.WaitForPresent`, `Camera.Render` |
+| Unreal | GameThread, RHIThread, RenderThread | `FrameGameThread`, `RHIThread`, `RenderingThread` |
+| Godot | GodotMain | `Main::iteration`, `physics_process` |
+
+**输出结构：**
+
+1. **帧率概览**：平均/P50/P90/P99 帧间隔、稳定性评级
+2. **卡顿帧分析**：卡顿帧时间分布、帧间隔直方图
+3. **GPU 状态**：频率、利用率、Fence 等待
+4. **热节流影响**：CPU/GPU 频率是否被限制
+5. **优化建议**：按 GPU-bound / CPU-bound / Thermal 分类

package/strategies/general.strategy.md

@@ -0,0 +1,48 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+---
+scene: general
+priority: 99
+effort: high
+required_capabilities:
+  - cpu_scheduling
+optional_capabilities: []
+keywords: []
+---
+
+#### 通用分析
+
+当前查询未匹配到特定场景策略。请根据用户关注的方向，使用以下决策树选择合适的分析路径。
+
+**决策树 — 按用户关注方向路由：**
+
+| 用户关注方向 | 推荐路径 | 说明 |
+|-------------|---------|------|
+| **CPU / 调度 / 线程** | `invoke_skill("cpu_analysis")` → 如果发现 throttling → `invoke_skill("thermal_throttling")` | 交叉检查热节流和 CPU 频率 |
+| **内存 / OOM / 泄漏** | `invoke_skill("memory_analysis")` → 如果有 heap dump → `invoke_skill("android_heap_graph_summary")` → 如果有 LMK → `invoke_skill("lmk_analysis")` → 如果涉及 GPU 内存 → `invoke_skill("dmabuf_analysis")` | 层层深入内存问题；heap graph 用 retained/cumulative size 定位 retainer |
+| **IO / 磁盘 / 存储** | `invoke_skill("block_io_analysis")` 或 `invoke_skill("io_pressure")` | 磁盘 IO 和系统 IO 压力 |
+| **GPU / 渲染** | `invoke_skill("gpu_analysis")` | GPU 频率、利用率、Fence 等待 |
+| **Binder / IPC** | `invoke_skill("binder_analysis")` → 特定事务 → `invoke_skill("binder_detail")` | Binder 通信分析 |
+| **锁竞争 / 死锁** | `invoke_skill("lock_contention_analysis")` | Monitor 竞争、锁链分析 |
+| **电源 / 功耗 / 唤醒** | 优先切到 power 策略；或 `invoke_skill("wattson_rails_power_breakdown")` / `invoke_skill("suspend_wakeup_analysis")` | 先看 power_rails/battery_counters/cpu_freq_idle/gpu_work_period 数据完整度；缺 Wattson 数据时退化为 wakelock/Doze/唤醒链 |
+| **SurfaceFlinger / 合成** | `invoke_skill("surfaceflinger_analysis")` | SF 合成延迟、GPU/HWC 分析 |
+| **非标准/混合渲染架构卡顿** | 先 `detect_architecture`；始终保留 HWUI host 分析（`scrolling_analysis` / `jank_frame_detail`），再按候选链路补：Flutter → `flutter_scrolling_analysis`，TextureView → `textureview_producer_frame_timing`，WebView GL Functor → `webview_drawfunctor_jank_chain`，RN old/new → `rn_bridge_to_frame_jank` / `rn_fabric_render_jank`，GLSurfaceView/NativeActivity → `gl_standalone_swap_jank` | 混合出图要先分开看 host 与 producer，再合并看依赖；避免只看 FrameTimeline 漏掉生产端 jank |
+| **网络** | `invoke_skill("network_analysis")` | 网络活动分析 |
+| **特定时间段** | `invoke_skill("system_load_in_range", { start_ts, end_ts })` | 任意时间段的系统负载 |
+| **不确定方向** | `invoke_skill("scene_reconstruction")` → 按场景路由 | 先做全局场景还原，再针对性深钻 |
+
+**场景专用快速路由**（如果用户的问题明确匹配以下场景，直接使用对应策略）：
+- **滑动/卡顿**: scrolling_analysis → jank_frame_detail (逐帧深钻)
+- **启动**: startup_analysis → startup_detail
+- **ANR**: anr_analysis → anr_detail
+- **点击/触摸**: click_response_analysis → click_response_detail (逐事件深钻)
+- **TextureView/WebView/Flutter/RN/GL 混合架构卡顿**: detect_architecture → HWUI host skill + architecture-specific producer skill → 合并依赖判断
+- **概览/场景还原**: scene_reconstruction → 按场景路由到对应 Skill
+- **功耗/耗电**: wattson_rails_power_breakdown → wattson_thread_power_attribution；数据缺失时 battery_charge_timeline / android_kernel_wakelock_summary / suspend_wakeup_analysis fallback
+
+也可以使用 `list_skills` 发现更多可用技能，或使用 `execute_sql` 做自定义查询。
+
+#### 通用场景关键 Stdlib 表
+
+写 execute_sql 时优先使用（完整列表见方法论模板）：`slice_self_dur`、`cpu_utilization_in_interval(ts, dur)`、`cpu_frequency_counters`、`android_garbage_collection_events`、`android_oom_adj_intervals`、`android_screen_state`、`android_dvfs_counters`、`wattson_rails_aggregation`、`android_battery_charge`