@gracker/smartperfetto 1.0.15 → 1.0.16

package/skills/atomic/process_slice_cpu_hotspots.skill.yaml

@@ -0,0 +1,321 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2024-2026 Gracker (Chris)
+# This file is part of SmartPerfetto. See LICENSE for details.
+
+# =============================================================================
+# 进程 Slice CPU 热点（原子 Skill）
+# =============================================================================
+# 按进程统计 named slice 的实际 Running CPU time。不同于 wall duration，
+# 这里把 slice 时间段和 thread_state=Running 区间求交，避免把睡眠、IO 等
+# 非执行时间误算成 CPU 消耗。
+
+name: process_slice_cpu_hotspots
+version: "1.0"
+type: atomic
+category: cpu
+tier: B
+
+meta:
+  display_name: "进程 Slice CPU 热点"
+  description: "按进程聚合 named slice 的实际 Running CPU 时间"
+  icon: "query_stats"
+  tags: [cpu, slice, thread_state, running, hotspot, atomic]
+
+triggers:
+  keywords:
+    zh: [slice CPU, 函数 CPU, 热点 slice, CPU 热点, Running 时间, named slice]
+    en: [slice cpu, function cpu, hot slices, cpu hotspots, running time, named slice]
+  patterns:
+    - ".*(slice|函数|方法).*(CPU|cpu|消耗|热点).*"
+    - ".*(CPU|cpu).*(slice|function|method|named).*"
+
+prerequisites:
+  modules:
+    - sched
+  required_tables:
+    - slice
+    - thread_track
+    - thread
+    - process
+    - thread_state
+
+identity:
+  policy: verify_if_present
+  scope: process
+  aliases: [package, process_name]
+  rewriteTo: recommended_process_name_param
+
+inputs:
+  - name: package
+    type: string
+    required: false
+    description: "目标应用包名或进程名前缀"
+  - name: process_name
+    type: string
+    required: false
+    description: "目标进程名；当 package 为空时使用"
+  - name: upid
+    type: integer
+    required: false
+    description: "可选 trace 内进程 ID；优先级高于 package/process_name"
+  - name: slice_name
+    type: string
+    required: false
+    description: "可选 slice 名称过滤；默认字面包含匹配，包含 % 时按 SQL LIKE 模式匹配"
+  - name: thread_scope
+    type: string
+    required: false
+    default: all
+    description: "线程范围：all/main/render/main_render"
+  - name: start_ts
+    type: timestamp
+    required: false
+    description: "分析起始时间戳(ns)，默认 trace_start()"
+  - name: end_ts
+    type: timestamp
+    required: false
+    description: "分析结束时间戳(ns)，默认 trace_end()"
+  - name: min_cpu_ns
+    type: integer
+    required: false
+    default: 0
+    description: "聚合后最小 CPU 时间阈值(ns)"
+  - name: top_k
+    type: integer
+    required: false
+    default: 10
+    description: "返回 TopK 条目"
+
+display:
+  level: detail
+  layer: list
+  title: "进程 Slice CPU 热点"
+  columns:
+    - name: process_name
+      label: "进程"
+      type: string
+      format: truncate
+    - name: slice_name
+      label: "Slice"
+      type: string
+      format: truncate
+    - name: count
+      label: "次数"
+      type: number
+      format: compact
+    - name: thread_count
+      label: "线程数"
+      type: number
+      format: compact
+    - name: sample_threads
+      label: "样例线程"
+      type: string
+      format: truncate
+    - name: total_cpu_ms
+      label: "CPU时间"
+      type: duration
+      format: duration_ms
+      unit: ms
+    - name: total_wall_ms
+      label: "Wall时间"
+      type: duration
+      format: duration_ms
+      unit: ms
+    - name: avg_cpu_ms
+      label: "平均CPU"
+      type: duration
+      format: duration_ms
+      unit: ms
+    - name: max_cpu_ms
+      label: "最大CPU"
+      type: duration
+      format: duration_ms
+      unit: ms
+    - name: cpu_efficiency_pct
+      label: "CPU/Wall"
+      type: percentage
+      format: percentage
+    - name: selected_cpu_share_pct
+      label: "所选CPU占比"
+      type: percentage
+      format: percentage
+    - name: first_ts
+      label: "首次出现"
+      type: timestamp
+    - name: last_ts
+      label: "最后出现"
+      type: timestamp
+
+sql: |
+  WITH
+  raw_input AS (
+    SELECT
+      COALESCE(${start_ts}, trace_start()) AS raw_start_ts,
+      COALESCE(${end_ts}, trace_end()) AS raw_end_ts,
+      ${upid} AS target_upid,
+      NULLIF(COALESCE(NULLIF('${process_name|}', ''), NULLIF('${package|}', '')), '') AS target_process,
+      NULLIF('${slice_name|}', '') AS target_slice,
+      CASE
+        WHEN '${thread_scope|all}' IN ('all', 'main', 'render', 'main_render') THEN '${thread_scope|all}'
+        ELSE 'all'
+      END AS thread_scope,
+      MAX(COALESCE(${min_cpu_ns|0}, 0), 0) AS min_cpu_ns,
+      MIN(MAX(COALESCE(${top_k|10}, 10), 1), 100) AS top_k
+  ),
+  input AS (
+    SELECT
+      MIN(raw_start_ts, raw_end_ts) AS start_ts,
+      MAX(raw_start_ts, raw_end_ts) AS end_ts,
+      target_upid,
+      target_process,
+      target_slice,
+      thread_scope,
+      min_cpu_ns,
+      top_k
+    FROM raw_input
+  ),
+  target_threads AS (
+    SELECT
+      p.upid,
+      p.pid,
+      p.name AS process_name,
+      t.utid,
+      t.tid,
+      COALESCE(t.name, '') AS thread_name
+    FROM process p
+    JOIN thread t ON t.upid = p.upid
+    CROSS JOIN input i
+    WHERE (
+        (
+          i.target_upid IS NOT NULL
+          AND p.upid = i.target_upid
+        )
+        OR (
+          i.target_upid IS NULL
+          AND (
+            i.target_process IS NULL
+            OR p.name GLOB i.target_process || '*'
+            OR p.name LIKE '%' || i.target_process || '%'
+          )
+        )
+      )
+      AND (
+        i.thread_scope = 'all'
+        OR (
+          i.thread_scope IN ('main', 'main_render')
+          AND (t.is_main_thread = 1 OR t.tid = p.pid)
+        )
+        OR (
+          i.thread_scope IN ('render', 'main_render')
+          AND (
+            t.name = 'RenderThread'
+            OR t.name = 'GPU completion'
+            OR t.name GLOB '[0-9]*.ui'
+            OR t.name GLOB '[0-9]*.raster'
+          )
+        )
+      )
+  ),
+  candidate_slices AS (
+    SELECT
+      s.id,
+      s.name AS slice_name,
+      s.ts,
+      s.dur,
+      tt.upid,
+      tt.process_name,
+      tt.utid,
+      tt.thread_name
+    FROM slice s
+    JOIN thread_track track ON s.track_id = track.id
+    JOIN target_threads tt ON track.utid = tt.utid
+    CROSS JOIN input i
+    WHERE s.dur > 0
+      AND s.ts < i.end_ts
+      AND s.ts + s.dur > i.start_ts
+      AND (
+        i.target_slice IS NULL
+        OR (
+          INSTR(i.target_slice, '%') > 0
+          AND s.name LIKE i.target_slice
+        )
+        OR (
+          INSTR(i.target_slice, '%') = 0
+          AND INSTR(s.name, i.target_slice) > 0
+        )
+      )
+  ),
+  per_slice_cpu AS (
+    SELECT
+      cs.id,
+      cs.process_name,
+      cs.slice_name,
+      cs.utid,
+      cs.thread_name,
+      MAX(cs.ts, i.start_ts) AS clipped_start_ts,
+      MIN(cs.ts + cs.dur, i.end_ts) AS clipped_end_ts,
+      MIN(cs.ts + cs.dur, i.end_ts) - MAX(cs.ts, i.start_ts) AS wall_ns,
+      COALESCE(SUM(
+        MIN(MIN(cs.ts + cs.dur, i.end_ts), ts.ts + ts.dur)
+        - MAX(MAX(cs.ts, i.start_ts), ts.ts)
+      ), 0) AS cpu_ns
+    FROM candidate_slices cs
+    CROSS JOIN input i
+    LEFT JOIN thread_state ts ON ts.utid = cs.utid
+      AND ts.state = 'Running'
+      AND ts.dur > 0
+      AND ts.ts < MIN(cs.ts + cs.dur, i.end_ts)
+      AND ts.ts + ts.dur > MAX(cs.ts, i.start_ts)
+    GROUP BY
+      cs.id,
+      cs.process_name,
+      cs.slice_name,
+      cs.utid,
+      cs.thread_name,
+      cs.ts,
+      cs.dur,
+      i.start_ts,
+      i.end_ts
+  ),
+  aggregate_cpu AS (
+    SELECT
+      process_name,
+      slice_name,
+      COUNT(*) AS count,
+      COUNT(DISTINCT utid) AS thread_count,
+      SUBSTR(GROUP_CONCAT(DISTINCT COALESCE(NULLIF(thread_name, ''), '<unnamed>')), 1, 240) AS sample_threads,
+      SUM(cpu_ns) AS total_cpu_ns,
+      SUM(wall_ns) AS total_wall_ns,
+      AVG(cpu_ns) AS avg_cpu_ns,
+      MAX(cpu_ns) AS max_cpu_ns,
+      MIN(clipped_start_ts) AS first_ts,
+      MAX(clipped_end_ts) AS last_ts
+    FROM per_slice_cpu
+    GROUP BY process_name, slice_name
+    HAVING SUM(cpu_ns) >= (SELECT min_cpu_ns FROM input)
+  ),
+  selected_total AS (
+    SELECT SUM(total_cpu_ns) AS total_cpu_ns
+    FROM aggregate_cpu
+  )
+  SELECT
+    process_name,
+    slice_name,
+    count,
+    thread_count,
+    sample_threads,
+    ROUND(total_cpu_ns / 1e6, 2) AS total_cpu_ms,
+    ROUND(total_wall_ns / 1e6, 2) AS total_wall_ms,
+    ROUND(avg_cpu_ns / 1e6, 2) AS avg_cpu_ms,
+    ROUND(max_cpu_ns / 1e6, 2) AS max_cpu_ms,
+    ROUND(100.0 * total_cpu_ns / NULLIF(total_wall_ns, 0), 1) AS cpu_efficiency_pct,
+    ROUND(100.0 * total_cpu_ns / NULLIF((SELECT total_cpu_ns FROM selected_total), 0), 1) AS selected_cpu_share_pct,
+    printf('%d', first_ts) AS first_ts,
+    printf('%d', last_ts) AS last_ts
+  FROM aggregate_cpu
+  WHERE total_cpu_ns > 0
+  ORDER BY total_cpu_ns DESC
+  LIMIT (SELECT top_k FROM input)
+
+output:
+  format: structured

package/strategies/anr.strategy.md

@@ -108,7 +108,7 @@ fetch_artifact(artifactId, detail="rows", offset=0, limit=50)
 |--------|------|------|--------|
 | Q4 Sleeping 极高 | >80% | **主线程被阻塞**（ANR 最常见原因） | → 第二步：用 blocked_functions 定位 |
 | Q3 Runnable 高 | >30% | CPU 饥饿——可运行但得不到 CPU | → 检查 `sched_latency`、`cpu_health`、后台进程抢占 |
-| Q1+Q2 Running 高 | >70% | CPU-bound——主线程在执行重计算 | → 检查 `main_thread_slices`、热点函数 |
+| Q1+Q2 Running 高 | >70% | CPU-bound——主线程在执行重计算 | → 检查 `main_thread_slices`，并调用 `invoke_skill("process_slice_cpu_hotspots", { process_name, start_ts, end_ts, thread_scope: "main" })` 定位主线程热点函数/slice 的 Running CPU time |
 | 混合 | 无明显主导 | 多因素共同导致 | → 依次排查 Q4→Q3→Q1 |
 
 ### 第二步：当 Q4 占比高时 — 用 blocked_functions + 线程状态定位
@@ -197,4 +197,4 @@ fetch_artifact(artifactId, detail="rows", offset=0, limit=50)
 - 忽略 `wakeup_chain` 数据（这是定位间接依赖链的关键）
 - 把所有 ANR 统一用同一个决策路径分析，不区分 ANR 类型
 - 忽略 `app_freeze_check`（应用完全冻结 vs 部分响应是重要区分）
-- 不交叉检查 CPU/内存/IO 系统上下文就下结论
+- 不交叉检查 CPU/内存/IO 系统上下文就下结论

package/strategies/game.strategy.md

@@ -100,7 +100,7 @@ invoke_skill("mali_gpu_power_state")
 | 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 |
+| 线程/进程 CPU 利用率 | `invoke_skill("cpu_thread_utilization_period")` / `invoke_skill("cpu_process_utilization_period")`；需要函数/slice 级热点时补 `invoke_skill("process_slice_cpu_hotspots", { process_name, start_ts, end_ts })` | 判断 UnityMain/GameThread/RenderThread 是否 CPU-bound，并用 Running CPU time 定位 named slice 热点 |
 | 功耗归因 | `invoke_skill("wattson_thread_power_attribution")` | 仅在 power_rails + cpu_freq_idle 可用时做线程能耗归因 |
 | 独立 GL swap 间隔 | `invoke_skill("gl_standalone_swap_jank")` | NativeActivity/GLSurfaceView 或引擎自管 swap 时检查生产端 present 节奏 |
 

package/strategies/general.strategy.md

@@ -19,7 +19,7 @@ keywords: []
 
 | 用户关注方向 | 推荐路径 | 说明 |
 |-------------|---------|------|
-| **CPU / 调度 / 线程** | `invoke_skill("cpu_analysis")` → 如果发现 throttling → `invoke_skill("thermal_throttling")` | 交叉检查热节流和 CPU 频率 |
+| **CPU / 调度 / 线程** | `invoke_skill("cpu_analysis")` → 需要函数/slice CPU 热点时 `invoke_skill("process_slice_cpu_hotspots", { process_name: "<包名或进程名>" })` → 如果发现 throttling → `invoke_skill("thermal_throttling")` | 用 Running CPU time 区分真实计算热点和 wall-time 阻塞，再交叉检查热节流和 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 等待 |

package/strategies/scrolling.strategy.md

@@ -224,6 +224,7 @@ invoke_skill("scrolling_analysis", { start_ts: "<trace_start>", end_ts: "<trace_
 | UI thread 时间分解 | `invoke_skill("frame_ui_time_breakdown")` | 看 UI thread 在每帧的耗时分布 |
 | 每帧阻塞调用 | `invoke_skill("frame_blocking_calls")` | 将掉帧帧与 Binder/GC/锁竞争/futex/文件 IO 阻塞区间做重叠匹配 |
 | CPU process/thread 周期利用率 | `invoke_skill("cpu_process_utilization_period")` / `invoke_skill("cpu_thread_utilization_period")` | 用于 workload_heavy、后台抢占、线程归因 |
+| 进程 slice CPU 热点 | `invoke_skill("process_slice_cpu_hotspots", { process_name, start_ts, end_ts })` | 用 `thread_state=Running` 求交，确认掉帧窗口内真正消耗 CPU 的 named slice |
 | CPU cluster 拓扑 | `invoke_skill("cpu_cluster_mapping_view")` | 解释大小核分布，辅助 small_core_placement |
 | GPU work period | `invoke_skill("android_gpu_work_period_track")` | 只有 `gpu_work_period` capability 可用时才做 GPU active region 判断 |
 | Mali power state | `invoke_skill("mali_gpu_power_state")` | Mali 设备专用；无数据时标注设备/trace 不支持 |