@gracker/smartperfetto 1.0.13

package/skills/atomic/consumer_jank_detection.skill.yaml

@@ -0,0 +1,556 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2024-2026 Gracker (Chris)
+# This file is part of SmartPerfetto. See LICENSE for details.
+
+# =============================================================================
+# 消费端掉帧检测 (Consumer-Side Jank Detection)
+# =============================================================================
+# 从 SurfaceFlinger 消费端角度检测真正的掉帧
+#
+# 核心原理：
+# - 使用同 layer 的“实际呈现时间间隔”判断是否错过 VSync
+# - display_frame_token 仅作为帧标识，不再直接用 token gap 判定卡顿
+# - 通过动态 VSync 周期 + 会话断点过滤，避免长空窗/跨会话误判
+#
+# 与传统 jank_type 的区别：
+# - jank_type 反映框架标记，不一定等同用户可见掉帧
+# - 这里的 consumer_jank 以“实际呈现是否跨过多个 VSync”为准
+
+name: consumer_jank_detection
+version: "1.0"
+type: atomic
+category: rendering
+tier: A
+
+meta:
+  display_name: "Consumer Jank 检测"
+  description: "检测 Consumer (SurfaceFlinger) 侧的卡顿"
+  icon: "warning"
+  tags: [jank, consumer, surfaceflinger, atomic]
+  # ----- Phase F: pipeline-aware 接口 -----
+  pipeline_aware: true
+  pipeline_aware_note: |
+    本 skill 已暴露 pipeline_id 可选输入。
+    当前实现按 layer_name 过滤通用判断（pipeline-agnostic），未来可按 pipeline_id 切换 SQL：
+    - Flutter: 1.ui jank（Animator::BeginFrame 超 budget）vs 1.raster jank（Rasterizer 超 budget）分开计
+    - Camera: 多路输出 back-pressure 归因（preview/analysis/record）
+    - Video: codec underflow（releaseOutputBuffer pool 耗尽）vs HWC overlay degradation
+    - Game: 三线程 lag 归因（GameThread/RenderThread/RHIThread）
+
+triggers:
+  keywords:
+    zh: [消费端卡顿, present interval, SurfaceFlinger, 显示端卡顿, 帧呈现]
+    en: [consumer jank, present interval, surfaceflinger, display jank]
+  patterns:
+    - ".*(消费端|显示端).*(卡顿|掉帧).*"
+    - ".*(consumer|present|display).*jank.*"
+
+prerequisites:
+  required_tables:
+    - actual_frame_timeline_slice
+  modules:
+    - android.frames.timeline
+
+inputs:
+  - name: package
+    type: string
+    required: false
+    description: "应用包名"
+  - name: layer_name
+    type: string
+    required: false
+    description: "Layer 名称（可选，用于精确匹配）"
+  - name: start_ts
+    type: timestamp
+    required: false
+  - name: end_ts
+    type: timestamp
+    required: false
+  - name: pipeline_id
+    type: string
+    required: false
+    description: "Pipeline ID (Phase F: pipeline-aware optional input; 当前实现 pipeline-agnostic, 未来按 pipeline 切换 SQL)"
+
+steps:
+  # Step 1: 检测 VSync 周期
+  - id: vsync_config
+    type: atomic
+    name: "VSync 配置"
+    sql: |
+      WITH
+      sf_vsync_intervals AS (
+        SELECT
+          c.ts - LAG(c.ts) OVER (ORDER BY c.ts) as interval_ns
+        FROM counter c
+        JOIN counter_track t ON c.track_id = t.id
+        WHERE t.name = 'VSYNC-sf'
+          AND (${start_ts} IS NULL OR c.ts >= ${start_ts})
+          AND (${end_ts} IS NULL OR c.ts < ${end_ts})
+      ),
+      vsync_median AS (
+        SELECT CASE
+          WHEN raw_ns BETWEEN 5500000 AND 6500000 THEN 6060606
+          WHEN raw_ns BETWEEN 6500001 AND 7500000 THEN 6944444
+          WHEN raw_ns BETWEEN 7500001 AND 9500000 THEN 8333333
+          WHEN raw_ns BETWEEN 9500001 AND 12500000 THEN 11111111
+          WHEN raw_ns BETWEEN 12500001 AND 20000000 THEN 16666667
+          WHEN raw_ns BETWEEN 20000001 AND 35000000 THEN 33333333
+          ELSE raw_ns
+        END AS vsync_period_ns
+        FROM (
+          SELECT CAST(COALESCE(
+            (SELECT PERCENTILE(interval_ns, 0.5)
+             FROM sf_vsync_intervals
+             WHERE interval_ns > 5500000 AND interval_ns < 50000000),
+            (SELECT CAST(PERCENTILE(dur, 0.5) AS INTEGER)
+             FROM expected_frame_timeline_slice
+             WHERE dur > 5000000 AND dur < 50000000
+               AND (${start_ts} IS NULL OR ts >= ${start_ts})
+               AND (${end_ts} IS NULL OR ts < ${end_ts})),
+            16666667
+          ) AS INTEGER) AS raw_ns
+        )
+      )
+      SELECT
+        vsync_period_ns,
+        CAST(ROUND(1e9 / vsync_period_ns) AS INTEGER) as refresh_rate_hz
+      FROM vsync_median
+    save_as: vsync_config
+
+  # Step 2: 检测真正的掉帧（基于实际呈现间隔）
+  - id: consumer_jank_frames
+    type: atomic
+    name: "消费端掉帧检测"
+    display:
+      level: detail
+      title: "真正的掉帧帧（SF 消费端视角）"
+      columns:
+        - name: frame_id
+          label: "帧ID"
+          type: string
+        - name: layer_name
+          label: "图层"
+          type: string
+        - name: ts_str
+          label: "时间"
+          type: timestamp
+          unit: ns
+          clickAction: navigate_timeline
+        - name: ts_sec
+          label: "时间(s)"
+          type: number
+        - name: dur_ms
+          label: "帧耗时"
+          type: duration
+          format: duration_ms
+          unit: ms
+        - name: token_gap
+          label: "Token跳跃"
+          type: number
+        - name: vsync_missed
+          label: "跳帧数"
+          type: number
+        - name: interval_ms
+          label: "间隔"
+          type: duration
+          format: duration_ms
+          unit: ms
+        - name: app_jank_type
+          label: "App标记"
+          type: string
+        - name: jank_severity
+          label: "严重程度"
+          type: string
+        - name: delay_source
+          label: "延迟来源"
+          type: string
+          description: "app_late=应用渲染超时, sf_late=SF/显示延迟, buffer_stuffing=缓冲区满"
+    sql: |
+      WITH
+      vsync_ticks AS (
+        SELECT
+          c.ts - LAG(c.ts) OVER (ORDER BY c.ts) as interval_ns
+        FROM counter c
+        JOIN counter_track t ON c.track_id = t.id
+        WHERE t.name = 'VSYNC-sf'
+          AND (${start_ts} IS NULL OR c.ts >= ${start_ts})
+          AND (${end_ts} IS NULL OR c.ts < ${end_ts})
+      ),
+      vsync_period AS (
+        SELECT CAST(COALESCE(
+          (SELECT PERCENTILE(interval_ns, 0.5)
+           FROM vsync_ticks
+           WHERE interval_ns > 5500000 AND interval_ns < 50000000),
+          (SELECT CAST(PERCENTILE(dur, 0.5) AS INTEGER)
+           FROM expected_frame_timeline_slice
+           WHERE dur > 5000000 AND dur < 50000000
+             AND (${start_ts} IS NULL OR ts >= ${start_ts})
+             AND (${end_ts} IS NULL OR ts < ${end_ts})),
+          16666667
+        ) AS INTEGER) as vsync_period_ns
+      ),
+      raw_frames AS (
+        SELECT
+          COALESCE(a.display_frame_token, a.surface_frame_token) as frame_id,
+          a.display_frame_token,
+          a.surface_frame_token,
+          a.ts,
+          a.dur,
+          a.layer_name,
+          a.jank_type,
+          a.present_type,
+          a.upid,
+          ROW_NUMBER() OVER (
+            PARTITION BY a.upid, COALESCE(a.display_frame_token, a.surface_frame_token)
+            ORDER BY a.ts, a.layer_name
+          ) as row_rank
+        FROM actual_frame_timeline_slice a
+        LEFT JOIN process p ON a.upid = p.upid
+        WHERE COALESCE(a.display_frame_token, a.surface_frame_token) IS NOT NULL
+          AND (
+            a.layer_name LIKE 'TX - ${package}%'
+            OR a.layer_name = '${layer_name}'
+            OR ('${package}' = '' AND '${layer_name}' = '')
+          )
+          AND ('${start_ts}' = '' OR a.ts >= CAST('${start_ts}' AS INTEGER))
+          AND ('${end_ts}' = '' OR a.ts <= CAST('${end_ts}' AS INTEGER))
+      ),
+      -- 同一 display frame token 在多 layer 会重复，先去重再做间隔分析
+      app_frames AS (
+        SELECT
+          frame_id,
+          display_frame_token,
+          surface_frame_token,
+          ts,
+          dur,
+          layer_name,
+          jank_type,
+          present_type,
+          upid,
+          ts + CASE WHEN dur > 0 THEN dur ELSE 0 END as present_ts,
+          LAG(ts + CASE WHEN dur > 0 THEN dur ELSE 0 END)
+            OVER (PARTITION BY upid ORDER BY ts, frame_id) as prev_present_ts
+        FROM raw_frames
+        WHERE row_rank = 1
+      ),
+      interval_analysis AS (
+        SELECT
+          frame_id,
+          display_frame_token,
+          surface_frame_token,
+          ts,
+          dur,
+          layer_name,
+          jank_type as app_jank_type,
+          present_type,
+          present_ts - prev_present_ts as interval_ns,
+          CASE
+            WHEN prev_present_ts IS NULL THEN 1
+            WHEN present_ts - prev_present_ts > (SELECT vsync_period_ns * 6 FROM vsync_period) THEN 1
+            ELSE 0
+          END as is_session_break,
+          MAX(CAST(ROUND((present_ts - prev_present_ts) * 1.0 / (SELECT vsync_period_ns FROM vsync_period) - 1, 0) AS INTEGER), 0) as vsync_missed,
+          MAX(CAST(ROUND((present_ts - prev_present_ts) * 1.0 / (SELECT vsync_period_ns FROM vsync_period), 0) AS INTEGER), 1) as token_gap,
+          CASE
+            WHEN prev_present_ts IS NULL THEN 0
+            WHEN present_ts - prev_present_ts > (SELECT vsync_period_ns * 6 FROM vsync_period) THEN 0
+            WHEN present_ts - prev_present_ts > (SELECT vsync_period_ns FROM vsync_period) * 1.5 THEN 1
+            ELSE 0
+          END as is_consumer_jank,
+          CASE
+            WHEN MAX(CAST(ROUND((present_ts - prev_present_ts) * 1.0 / (SELECT vsync_period_ns FROM vsync_period) - 1, 0) AS INTEGER), 0) = 0 THEN 'SMOOTH'
+            WHEN MAX(CAST(ROUND((present_ts - prev_present_ts) * 1.0 / (SELECT vsync_period_ns FROM vsync_period) - 1, 0) AS INTEGER), 0) = 1 THEN 'MINOR_JANK'
+            WHEN MAX(CAST(ROUND((present_ts - prev_present_ts) * 1.0 / (SELECT vsync_period_ns FROM vsync_period) - 1, 0) AS INTEGER), 0) <= 3 THEN 'JANK'
+            WHEN MAX(CAST(ROUND((present_ts - prev_present_ts) * 1.0 / (SELECT vsync_period_ns FROM vsync_period) - 1, 0) AS INTEGER), 0) <= 7 THEN 'SEVERE_JANK'
+            ELSE 'FROZEN'
+          END as jank_severity
+        FROM app_frames
+        WHERE prev_present_ts IS NOT NULL
+      )
+      SELECT
+        printf('%d', frame_id) as frame_id,
+        layer_name,
+        printf('%d', ts) as ts_str,
+        ROUND(ts / 1e9, 3) as ts_sec,
+        ROUND(CASE WHEN dur > 0 THEN dur ELSE 0 END / 1e6, 2) as dur_ms,
+        token_gap,
+        vsync_missed,
+        ROUND(interval_ns / 1e6, 2) as interval_ms,
+        app_jank_type,
+        present_type,
+        jank_severity,
+        is_consumer_jank,
+        -- P0-3: Decompose delay source using framework jank classification (ground truth)
+        -- Note: dur from actual_frame_timeline_slice spans app→display, includes SF time,
+        -- so we rely on app_jank_type from the framework instead of dur comparison.
+        -- app_late = framework detected app missed its deadline
+        -- sf_late = app was on time (None) or SF was the bottleneck
+        -- buffer_stuffing = buffer queue full (triple-buffering backpressure)
+        CASE
+          WHEN app_jank_type = 'None' THEN 'sf_late'
+          WHEN app_jank_type GLOB '*SurfaceFlinger*' THEN 'sf_late'
+          WHEN app_jank_type GLOB '*Buffer*' THEN 'buffer_stuffing'
+          ELSE 'app_late'
+        END as delay_source
+      FROM interval_analysis
+      WHERE is_session_break = 0
+        AND is_consumer_jank = 1
+      ORDER BY ts
+    save_as: consumer_jank_frames
+
+  # Step 3: 消费端掉帧统计汇总
+  - id: consumer_jank_summary
+    type: atomic
+    name: "消费端掉帧汇总"
+    display:
+      level: summary
+      title: "消费端掉帧统计"
+      columns:
+        - name: total_frames
+          label: "总帧数"
+          type: number
+          format: compact
+        - name: consumer_jank_frames
+          label: "掉帧数"
+          type: number
+          format: compact
+        - name: smooth_frames
+          label: "流畅帧"
+          type: number
+          format: compact
+        - name: consumer_jank_rate
+          label: "掉帧率"
+          type: percentage
+          format: percentage
+        - name: max_vsync_missed
+          label: "最大跳帧"
+          type: number
+        - name: rating
+          label: "评级"
+          type: string
+    sql: |
+      WITH
+      vsync_ticks AS (
+        SELECT
+          c.ts - LAG(c.ts) OVER (ORDER BY c.ts) as interval_ns
+        FROM counter c
+        JOIN counter_track t ON c.track_id = t.id
+        WHERE t.name = 'VSYNC-sf'
+          AND (${start_ts} IS NULL OR c.ts >= ${start_ts})
+          AND (${end_ts} IS NULL OR c.ts < ${end_ts})
+      ),
+      vsync_period AS (
+        SELECT CAST(COALESCE(
+          (SELECT PERCENTILE(interval_ns, 0.5)
+           FROM vsync_ticks
+           WHERE interval_ns > 5500000 AND interval_ns < 50000000),
+          (SELECT CAST(PERCENTILE(dur, 0.5) AS INTEGER)
+           FROM expected_frame_timeline_slice
+           WHERE dur > 5000000 AND dur < 50000000
+             AND (${start_ts} IS NULL OR ts >= ${start_ts})
+             AND (${end_ts} IS NULL OR ts < ${end_ts})),
+          16666667
+        ) AS INTEGER) as vsync_period_ns
+      ),
+      vsync_events AS (
+        SELECT
+          c.ts as vsync_ts,
+          c.ts - LAG(c.ts) OVER (ORDER BY c.ts) as interval_ns
+        FROM counter c
+        JOIN counter_track t ON c.track_id = t.id
+        WHERE t.name = 'VSYNC-sf'
+          AND (${start_ts} IS NULL OR c.ts >= ${start_ts})
+          AND (${end_ts} IS NULL OR c.ts < ${end_ts})
+      ),
+      buffer_events AS (
+        SELECT c.ts, c.value as buffer_count
+        FROM counter c
+        JOIN counter_track t ON c.track_id = t.id
+        WHERE t.name LIKE '%BufferTX%'
+          AND (t.name LIKE '%${package}%' OR '${package}' = '')
+          AND ('${end_ts}' = '' OR c.ts <= CAST('${end_ts}' AS INTEGER))
+      ),
+      vsync_with_buffer AS (
+        SELECT
+          v.vsync_ts,
+          v.interval_ns,
+          (SELECT b.buffer_count
+           FROM buffer_events b
+           WHERE b.ts <= v.vsync_ts
+           ORDER BY b.ts DESC
+           LIMIT 1
+          ) as buffer_at_vsync
+        FROM vsync_events v
+        WHERE v.interval_ns IS NOT NULL
+      ),
+      jank_events AS (
+        SELECT
+          vsync_ts,
+          interval_ns,
+          MAX(CAST(ROUND(interval_ns * 1.0 / (SELECT vsync_period_ns FROM vsync_period) - 1, 0) AS INTEGER), 0) as vsync_missed
+        FROM vsync_with_buffer
+        WHERE buffer_at_vsync IS NOT NULL
+          AND interval_ns > (SELECT vsync_period_ns FROM vsync_period) * 1.5
+      ),
+      vsync_stats AS (
+        SELECT
+          COUNT(*) as total_frames,
+          (SELECT COUNT(*) FROM jank_events) as consumer_jank_frames,
+          COALESCE((SELECT MAX(vsync_missed) FROM jank_events), 0) as max_vsync_missed,
+          COALESCE((SELECT AVG(vsync_missed + 1.0) FROM (
+            SELECT MAX(CAST(ROUND(interval_ns * 1.0 / (SELECT vsync_period_ns FROM vsync_period), 0) AS INTEGER), 1) as vsync_missed
+            FROM vsync_with_buffer
+            WHERE buffer_at_vsync IS NOT NULL
+          )), 1.0) as avg_token_gap
+        FROM vsync_with_buffer
+        WHERE buffer_at_vsync IS NOT NULL
+      ),
+      app_stats AS (
+        SELECT
+          COUNT(*) as app_total_frames,
+          SUM(CASE WHEN COALESCE(a.jank_type, 'None') != 'None' THEN 1 ELSE 0 END) as app_reported_jank
+        FROM actual_frame_timeline_slice a
+        LEFT JOIN process p ON a.upid = p.upid
+        WHERE COALESCE(a.display_frame_token, a.surface_frame_token) IS NOT NULL
+          AND (
+            a.layer_name LIKE 'TX - ${package}%'
+            OR a.layer_name = '${layer_name}'
+            OR ('${package}' = '' AND '${layer_name}' = '')
+          )
+          AND ('${start_ts}' = '' OR a.ts >= CAST('${start_ts}' AS INTEGER))
+          AND ('${end_ts}' = '' OR a.ts <= CAST('${end_ts}' AS INTEGER))
+      )
+      SELECT
+        (SELECT total_frames FROM vsync_stats) as vsync_total_frames,
+        COALESCE((SELECT app_total_frames FROM app_stats), 0) as app_total_frames,
+        (SELECT consumer_jank_frames FROM vsync_stats) as consumer_jank_frames,
+        (SELECT total_frames FROM vsync_stats) - (SELECT consumer_jank_frames FROM vsync_stats) as smooth_frames,
+        ROUND(100.0 * (SELECT consumer_jank_frames FROM vsync_stats) / NULLIF((SELECT total_frames FROM vsync_stats), 0), 2) as consumer_jank_rate,
+        COALESCE((SELECT app_reported_jank FROM app_stats), 0) as old_logic_jank_count,
+        ROUND(100.0 * COALESCE((SELECT app_reported_jank FROM app_stats), 0) / NULLIF(COALESCE((SELECT app_total_frames FROM app_stats), 0), 0), 2) as old_logic_jank_rate,
+        MAX(COALESCE((SELECT app_reported_jank FROM app_stats), 0) - (SELECT consumer_jank_frames FROM vsync_stats), 0) as false_positives,
+        MAX((SELECT consumer_jank_frames FROM vsync_stats) - COALESCE((SELECT app_reported_jank FROM app_stats), 0), 0) as false_negatives,
+        (SELECT max_vsync_missed FROM vsync_stats) as max_vsync_missed,
+        ROUND((SELECT avg_token_gap FROM vsync_stats), 2) as avg_token_gap,
+        CASE
+          WHEN 100.0 * (SELECT consumer_jank_frames FROM vsync_stats) / NULLIF((SELECT total_frames FROM vsync_stats), 0) < 1 THEN '优秀'
+          WHEN 100.0 * (SELECT consumer_jank_frames FROM vsync_stats) / NULLIF((SELECT total_frames FROM vsync_stats), 0) < 5 THEN '良好'
+          WHEN 100.0 * (SELECT consumer_jank_frames FROM vsync_stats) / NULLIF((SELECT total_frames FROM vsync_stats), 0) < 15 THEN '一般'
+          ELSE '较差'
+        END as rating
+      LIMIT 1
+    save_as: consumer_jank_summary
+
+  # Step 4: 严重程度分布
+  - id: jank_severity_distribution
+    type: atomic
+    name: "掉帧严重程度分布"
+    display:
+      level: detail
+      title: "掉帧严重程度分布"
+      columns:
+        - name: severity
+          label: "严重程度"
+          type: string
+        - name: count
+          label: "帧数"
+          type: number
+          format: compact
+        - name: percentage
+          label: "占比"
+          type: percentage
+          format: percentage
+    sql: |
+      WITH
+      vsync_ticks AS (
+        SELECT
+          c.ts - LAG(c.ts) OVER (ORDER BY c.ts) as interval_ns
+        FROM counter c
+        JOIN counter_track t ON c.track_id = t.id
+        WHERE t.name = 'VSYNC-sf'
+          AND (${start_ts} IS NULL OR c.ts >= ${start_ts})
+          AND (${end_ts} IS NULL OR c.ts < ${end_ts})
+      ),
+      vsync_period AS (
+        SELECT CAST(COALESCE(
+          (SELECT PERCENTILE(interval_ns, 0.5)
+           FROM vsync_ticks
+           WHERE interval_ns > 5500000 AND interval_ns < 50000000),
+          (SELECT CAST(PERCENTILE(dur, 0.5) AS INTEGER)
+           FROM expected_frame_timeline_slice
+           WHERE dur > 5000000 AND dur < 50000000
+             AND (${start_ts} IS NULL OR ts >= ${start_ts})
+             AND (${end_ts} IS NULL OR ts < ${end_ts})),
+          16666667
+        ) AS INTEGER) as vsync_period_ns
+      ),
+      vsync_events AS (
+        SELECT
+          c.ts as vsync_ts,
+          c.ts - LAG(c.ts) OVER (ORDER BY c.ts) as interval_ns
+        FROM counter c
+        JOIN counter_track t ON c.track_id = t.id
+        WHERE t.name = 'VSYNC-sf'
+          AND (${start_ts} IS NULL OR c.ts >= ${start_ts})
+          AND (${end_ts} IS NULL OR c.ts < ${end_ts})
+      ),
+      buffer_events AS (
+        SELECT
+          c.ts,
+          c.value as buffer_count
+        FROM counter c
+        JOIN counter_track t ON c.track_id = t.id
+        WHERE t.name LIKE '%BufferTX%'
+          AND (t.name LIKE '%${package}%' OR '${package}' = '')
+          AND ('${end_ts}' = '' OR c.ts <= CAST('${end_ts}' AS INTEGER))
+      ),
+      vsync_with_buffer AS (
+        SELECT
+          v.interval_ns,
+          (SELECT b.buffer_count
+           FROM buffer_events b
+           WHERE b.ts <= v.vsync_ts
+           ORDER BY b.ts DESC
+           LIMIT 1
+          ) as buffer_at_vsync
+        FROM vsync_events v
+        WHERE v.interval_ns IS NOT NULL
+      ),
+      gap_analysis AS (
+        SELECT
+          MAX(CAST(ROUND(interval_ns * 1.0 / (SELECT vsync_period_ns FROM vsync_period) - 1, 0) AS INTEGER), 0) as vsync_missed,
+          CASE
+            WHEN MAX(CAST(ROUND(interval_ns * 1.0 / (SELECT vsync_period_ns FROM vsync_period) - 1, 0) AS INTEGER), 0) = 0 THEN 'SMOOTH (gap=1)'
+            WHEN MAX(CAST(ROUND(interval_ns * 1.0 / (SELECT vsync_period_ns FROM vsync_period) - 1, 0) AS INTEGER), 0) = 1 THEN 'MINOR_JANK (gap=2, 跳1帧)'
+            WHEN MAX(CAST(ROUND(interval_ns * 1.0 / (SELECT vsync_period_ns FROM vsync_period) - 1, 0) AS INTEGER), 0) <= 3 THEN 'JANK (gap=3-4, 跳2-3帧)'
+            WHEN MAX(CAST(ROUND(interval_ns * 1.0 / (SELECT vsync_period_ns FROM vsync_period) - 1, 0) AS INTEGER), 0) <= 7 THEN 'SEVERE_JANK (gap=5-8, 跳4-7帧)'
+            ELSE 'FROZEN (gap>8, 跳8+帧)'
+          END as severity
+        FROM vsync_with_buffer
+        WHERE buffer_at_vsync IS NOT NULL
+      )
+      SELECT
+        severity,
+        COUNT(*) as count,
+        ROUND(100.0 * COUNT(*) / NULLIF(SUM(COUNT(*)) OVER (), 0), 2) as percentage
+      FROM gap_analysis
+      GROUP BY severity
+      ORDER BY
+        CASE severity
+          WHEN 'SMOOTH (gap=1)' THEN 1
+          WHEN 'MINOR_JANK (gap=2, 跳1帧)' THEN 2
+          WHEN 'JANK (gap=3-4, 跳2-3帧)' THEN 3
+          WHEN 'SEVERE_JANK (gap=5-8, 跳4-7帧)' THEN 4
+          ELSE 5
+        END
+    save_as: jank_severity_distribution
+
+output:
+  format: structured
+  fields:
+    - name: consumer_jank_frames
+      description: "真正的掉帧帧列表"
+    - name: consumer_jank_summary
+      description: "消费端掉帧统计汇总"
+    - name: jank_severity_distribution
+      description: "掉帧严重程度分布"

package/skills/atomic/cpu_cluster_load_in_range.skill.yaml

@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2024-2026 Gracker (Chris)
+# This file is part of SmartPerfetto. See LICENSE for details.
+
+# =============================================================================
+# CPU 簇负载分析 (Composite Skill)
+# =============================================================================
+# 计算指定时间范围内各 CPU 簇（大核/小核）的整体负载
+# 负载 = Running 时间 / (时间范围 × 簇内核心数)
+# 100% 表示该簇所有核心完全跑满
+#
+# v2.0: 重构为 composite skill，复用 _cpu_topology 视图
+#   - 调用 cpu_topology_view 创建共享拓扑视图
+#   - 主 SQL 通过 JOIN _cpu_topology 获取核心分类
+#   - 支持 prime/big/medium/little 四级分类
+
+name: cpu_cluster_load_in_range
+version: "2.0"
+type: composite
+category: cpu
+tier: B
+
+meta:
+  display_name: "CPU 簇负载分析"
+  description: "计算大核簇和小核簇的整体 CPU 负载百分比（动态拓扑检测）"
+  icon: "memory"
+  tags: [cpu, cluster, load, atomic]
+
+inputs:
+  - name: start_ts
+    type: timestamp
+    required: true
+    description: "分析起始时间戳(ns)"
+  - name: end_ts
+    type: timestamp
+    required: true
+    description: "分析结束时间戳(ns)"
+
+steps:
+  # ========== 初始化 CPU 拓扑视图（供后续步骤 JOIN）==========
+  - id: init_cpu_topology
+    type: skill
+    name: "初始化 CPU 拓扑"
+    skill: cpu_topology_view
+    display:
+      level: hidden
+    optional: true
+
+  # ========== 簇负载计算 ==========
+  - id: cluster_load
+    type: atomic
+    name: "CPU 簇负载计算"
+    optional: true
+    display:
+      level: detail
+      layer: deep
+      title: "CPU 簇负载"
+      columns:
+        - name: cluster
+          label: "CPU 簇"
+          type: string
+        - name: core_count
+          label: "核心数"
+          type: number
+        - name: running_ms
+          label: "Running 时间"
+          type: duration
+          format: duration_ms
+          unit: ms
+        - name: total_capacity_ms
+          label: "总容量"
+          type: duration
+          format: duration_ms
+          unit: ms
+        - name: load_pct
+          label: "负载"
+          type: percentage
+          format: percentage
+        - name: idle_pct
+          label: "空闲"
+          type: percentage
+          format: percentage
+        - name: max_single_core_pct
+          label: "最忙核心"
+          type: percentage
+          format: percentage
+    sql: |
+      WITH
+      -- 获取每个 CPU 上的 Running 状态时间
+      cpu_running AS (
+        SELECT
+          ts.cpu,
+          ct.core_type as cluster_type,
+          -- 裁剪 slice 到时间范围内
+          MIN(ts.ts + ts.dur, ${end_ts}) - MAX(ts.ts, ${start_ts}) as clipped_dur
+        FROM thread_state ts
+        JOIN _cpu_topology ct ON ts.cpu = ct.cpu_id
+        WHERE ts.ts < ${end_ts}
+          AND ts.ts + ts.dur > ${start_ts}
+          AND ts.state = 'Running'
+          AND ts.cpu IS NOT NULL
+      ),
+      -- 按 CPU 聚合
+      per_cpu_stats AS (
+        SELECT
+          cpu,
+          cluster_type,
+          SUM(CASE WHEN clipped_dur > 0 THEN clipped_dur ELSE 0 END) as running_ns
+        FROM cpu_running
+        GROUP BY cpu, cluster_type
+      ),
+      -- 按簇聚合
+      cluster_stats AS (
+        SELECT
+          cluster_type,
+          COUNT(DISTINCT cpu) as core_count,
+          SUM(running_ns) as total_running_ns,
+          MAX(running_ns) as max_core_running_ns
+        FROM per_cpu_stats
+        GROUP BY cluster_type
+      )
+      SELECT
+        CASE
+          WHEN cluster_type = 'big' THEN '大核簇'
+          ELSE '小核簇'
+        END as cluster,
+        core_count,
+        ROUND(total_running_ns / 1e6, 2) as running_ms,
+        ROUND((${end_ts} - ${start_ts}) * core_count / 1e6, 2) as total_capacity_ms,
+        ROUND(100.0 * total_running_ns / NULLIF((${end_ts} - ${start_ts}) * core_count, 0), 1) as load_pct,
+        ROUND(100.0 - 100.0 * total_running_ns / NULLIF((${end_ts} - ${start_ts}) * core_count, 0), 1) as idle_pct,
+        ROUND(100.0 * max_core_running_ns / NULLIF(${end_ts} - ${start_ts}, 0), 1) as max_single_core_pct
+      FROM cluster_stats
+      ORDER BY cluster_type DESC
+    save_as: cluster_load
+
+output:
+  format: structured