@gracker/smartperfetto 1.0.20 → 1.0.22

package/strategies/selection-area.template.md

@@ -7,28 +7,40 @@
   {{durationMs}}  - Duration in ms, e.g. "19.30"
   {{trackCount}}  - Number of selected tracks (number or "未知")
   {{trackSummary}} - Pre-formatted track list grouped by process (string, may be empty)
+  {{sourceLabel}} - Selection source label, e.g. Perfetto area/time-range selection or current visible timeline window
 -->
 ## 用户选区上下文
 
-用户在 Perfetto UI 中选择了一段时间区间（按 M 键标记）：
+用户当前问题带有一个明确的时间范围 scope（来源: {{sourceLabel}}）：
 - **起始时间:** {{startNs}} ns
 - **结束时间:** {{endNs}} ns
 - **持续时间:** {{durationMs}} ms
 - **选中 Track 数:** {{trackCount}}{{trackSummary}}
 
 **分析约束:**
-- 你的 SQL 查询必须使用 `WHERE ts >= {{startNs}} AND ts <= {{endNs}}` 来限制时间范围
+- 选区/窗口只定义时间和可选 track scope；用户真正要看的指标由用户问题决定，不要用固定 pattern 代替意图判断
+- SQL 查询必须限制在上述时间范围。对 `slice` / `thread_state` / `sched_slice` 这类带持续时间的表，优先使用 overlap clipping：`ts < {{endNs}} AND ts + dur > {{startNs}}`，并用 `MIN(ts + dur, {{endNs}}) - MAX(ts, {{startNs}})` 计算区间内贡献
 - 上述时间戳是 trace_processor 原始时间戳（ns），可直接用于 slice/thread_state/sched 等所有表的 ts 列
 - 分析结论应聚焦于用户选择的这段区间
 - 如果需要全局上下文（如整体 VSync 周期）来做对比，可以额外查询，但核心分析范围是选区内
-- 当用户提到"选中的区间"/"这一段"/"选择的范围"/"marked area"等，指的就是上述时间窗口
+- 当用户提到"选中的区间"/"这一段"/"选择的范围"/"marked area"/"current window"等，指的就是上述时间窗口
+- 如果前端请求附带了 `traceContext` datasets，优先复用其中已经预取的选区数据；缺少用户所问的指标时，再调用工具补齐
 
-**选区内常用 SQL 查询模板:**
+**快速路径建议:**
+- 对 CPU 摆核、task/core placement、各核平均频率、频率分布、Running task/process 排名、Running 四象限这类选区问题，优先调用：
+  `invoke_skill(skillId="selection_range_cpu_sched_summary", params={start_ts: {{startNs}}, end_ts: {{endNs}}})`
+- 如果用户限定某个进程或线程，把它作为 `package` 或 `thread_name` 参数传给该 Skill；没有限定时保持未过滤，让结果按数据排序
+- 如果用户只问一个 Skill 未覆盖的小指标，可以直接 `execute_sql`，但仍必须使用上述时间范围和 overlap clipping
+
+**选区内常用 SQL 查询模板（需要自定义 SQL 时使用）:**
 ```sql
 -- 1) 选区内某线程的调度状态分布（大小核、Running/Sleeping/Runnable）
-SELECT cpu, state, SUM(dur)/1e6 AS total_ms, COUNT(*) AS count
+SELECT cpu, state,
+       SUM(MIN(ts + dur, {{endNs}}) - MAX(ts, {{startNs}}))/1e6 AS total_ms,
+       COUNT(*) AS count
 FROM thread_state
-WHERE utid = <UTID> AND ts >= {{startNs}} AND ts <= {{endNs}}
+WHERE utid = <UTID>
+  AND ts < {{endNs}} AND ts + dur > {{startNs}}
 GROUP BY cpu, state ORDER BY total_ms DESC;
 
 -- 2) 选区内 CPU 频率变化（使用 counter + cpu_counter_track，不要用 cpu_frequency_counters）
@@ -38,9 +50,12 @@ WHERE ct.name = 'cpufreq' AND c.ts >= {{startNs}} AND c.ts <= {{endNs}}
 ORDER BY ct.cpu, c.ts;
 
 -- 3) 选区内某线程的 Slice 热点（通过 thread_track 关联）
-SELECT s.name, s.dur/1e6 AS dur_ms, s.ts, s.depth
+SELECT s.name,
+       (MIN(s.ts + s.dur, {{endNs}}) - MAX(s.ts, {{startNs}}))/1e6 AS dur_ms,
+       s.ts, s.depth
 FROM slice s JOIN thread_track tt ON s.track_id = tt.id
-WHERE tt.utid = <UTID> AND s.ts >= {{startNs}} AND s.ts <= {{endNs}}
+WHERE tt.utid = <UTID>
+  AND s.ts < {{endNs}} AND s.ts + s.dur > {{startNs}}
 ORDER BY s.dur DESC LIMIT 20;
 ```
-> 注意: 不要猜测表名。如果不确定表是否存在，先用 `lookup_sql_schema` 工具查询。
+> 注意: 不要猜测表名。如果不确定表是否存在，先用 `lookup_sql_schema` 工具查询。

package/strategies/smart.strategy.md

@@ -0,0 +1,53 @@
+<!--
+SPDX-License-Identifier: AGPL-3.0-or-later
+Copyright (C) 2024-2026 Gracker (Chris)
+This file is part of SmartPerfetto. See LICENSE for details.
+-->
+---
+scene: smart
+strategy_kind: contract_only
+priority: 5
+effort: high
+keywords:
+  - smart
+  - 智能
+  - mixed trace
+  - 场景混合
+required_capabilities: []
+optional_capabilities: []
+final_report_contract:
+  required_sections:
+    - id: scene_timeline
+      label: 场景时间线
+      description: 按时间顺序列出 trace 中检测到的关键用户操作和设备状态场景。
+      pattern_groups:
+        - ["场景时间线", "timeline", "时间线"]
+        - ["冷启动", "热启动", "滑动", "点击", "返回", "Home", "亮屏", "熄屏", "ANR"]
+    - id: per_scene_summary
+      label: 分场景摘要
+      description: 对每个被深度分析的场景给出关键指标、结论和证据引用。
+      pattern_groups:
+        - ["分场景", "逐场景", "per-scene"]
+        - ["证据", "指标", "耗时", "延迟", "帧"]
+    - id: cross_scene_narrative
+      label: 跨场景叙事
+      description: 总结多个场景之间的关联、共同瓶颈或前后影响。
+      pattern_groups:
+        - ["跨场景", "整体", "关联", "链路"]
+        - ["原因", "影响", "共同", "瓶颈"]
+    - id: bottleneck_ranking
+      label: 瓶颈排序
+      description: 按影响范围、严重度和可行动性给出优化优先级。
+      pattern_groups:
+        - ["瓶颈排序", "优先级", "ranking"]
+        - ["P0", "P1", "优先", "建议"]
+---
+
+# Smart Analysis Contract
+
+This strategy is intentionally contract-only. It must not be injected as a
+normal scene strategy and must not participate in scene classification.
+
+Smart Analysis Mode combines Scene Story detection with profile-specific
+deep-dive routes, then projects the resulting scene report into a readable chat
+summary and the standard HTML report chain.

package/skills/atomic/device_state_snapshot.skill.yaml

@@ -1,171 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-or-later
-# Copyright (C) 2024-2026 Gracker (Chris)
-# This file is part of SmartPerfetto. See LICENSE for details.
-
-# =============================================================================
-# 设备环境状态快照（原子 Skill）
-# =============================================================================
-# 采集 trace 期间的设备环境信息：屏幕状态、电量、温度、CPU 频率、内存压力等。
-
-name: device_state_snapshot
-version: "1.0"
-type: atomic
-category: system_context
-tier: B
-
-meta:
-  display_name: "设备环境状态快照"
-  description: "采集 trace 期间的设备环境信息（屏幕、电量、温度、CPU、内存等）"
-  icon: "devices"
-  tags: [device, state, environment, context, atomic]
-
-prerequisites:
-  required_tables:
-    - counter
-    - counter_track
-
-inputs:
-  - name: start_ts
-    type: timestamp
-    required: false
-    description: "分析起始时间戳(ns)"
-  - name: end_ts
-    type: timestamp
-    required: false
-    description: "分析结束时间戳(ns)"
-
-display:
-  level: summary
-  layer: overview
-  title: "设备环境状态"
-  columns:
-    - name: metric
-      label: "指标"
-      type: string
-    - name: value
-      label: "值"
-      type: string
-    - name: ts
-      label: "时间戳"
-      type: timestamp
-      unit: ns
-      clickAction: navigate_timeline
-
-sql: |
-  WITH trace_bounds AS (
-    SELECT
-      COALESCE(${start_ts}, (SELECT MIN(ts) FROM slice)) as t_start,
-      COALESCE(${end_ts}, (SELECT MAX(ts + dur) FROM slice)) as t_end
-  ),
-  screen_state AS (
-    SELECT
-      'screen_state' as metric,
-      CASE WHEN c.value > 0 THEN 'ON' ELSE 'OFF' END as value,
-      c.ts as ts
-    FROM counter c
-    JOIN counter_track ct ON c.track_id = ct.id
-    WHERE ct.name GLOB '*ScreenState*' OR ct.name GLOB '*screen_state*'
-    ORDER BY c.ts DESC
-    LIMIT 1
-  ),
-  battery_info AS (
-    SELECT
-      'battery_level' as metric,
-      CAST(c.value AS TEXT) as value,
-      c.ts as ts
-    FROM counter c
-    JOIN counter_track ct ON c.track_id = ct.id
-    WHERE ct.name GLOB '*battery_level*' OR ct.name GLOB '*BatteryLevel*'
-    ORDER BY c.ts DESC
-    LIMIT 1
-  ),
-  charging_info AS (
-    SELECT
-      'charging_state' as metric,
-      CASE WHEN c.value > 0 THEN 'CHARGING' ELSE 'NOT_CHARGING' END as value,
-      c.ts as ts
-    FROM counter c
-    JOIN counter_track ct ON c.track_id = ct.id
-    WHERE ct.name GLOB '*battery_status*' OR ct.name GLOB '*charging*' OR ct.name GLOB '*BatteryStatus*'
-    ORDER BY c.ts DESC
-    LIMIT 1
-  ),
-  thermal_info AS (
-    SELECT
-      'thermal_zone' as metric,
-      ct.name || ': ' || CAST(ROUND(MAX(c.value) / 1000.0, 1) AS TEXT) || '°C' as value,
-      MAX(c.ts) as ts
-    FROM counter c
-    JOIN counter_track ct ON c.track_id = ct.id
-    CROSS JOIN trace_bounds tb
-    WHERE (ct.name GLOB '*thermal_zone*' OR ct.name GLOB '*Temperature*')
-      AND c.ts >= tb.t_start AND c.ts <= tb.t_end
-    GROUP BY ct.name
-    ORDER BY MAX(c.value) DESC
-    LIMIT 5
-  ),
-  cpu_freq_summary AS (
-    SELECT
-      'cpu_max_freq' as metric,
-      'CPU' || ct.name || ': ' || CAST(ROUND(MAX(c.value) / 1e6, 2) AS TEXT) || 'GHz' as value,
-      MAX(c.ts) as ts
-    FROM counter c
-    JOIN cpu_counter_track ct ON c.track_id = ct.id
-    CROSS JOIN trace_bounds tb
-    WHERE ct.name = 'cpufreq'
-      AND c.ts >= tb.t_start AND c.ts <= tb.t_end
-    GROUP BY ct.cpu
-    ORDER BY ct.cpu
-  ),
-  memory_info AS (
-    SELECT
-      'memory_pressure' as metric,
-      CAST(ROUND(MAX(c.value), 0) AS TEXT) as value,
-      MAX(c.ts) as ts
-    FROM counter c
-    JOIN counter_track ct ON c.track_id = ct.id
-    CROSS JOIN trace_bounds tb
-    WHERE (ct.name GLOB '*mem.*pressure*' OR ct.name GLOB '*MemFree*' OR ct.name GLOB '*MemAvailable*')
-      AND c.ts >= tb.t_start AND c.ts <= tb.t_end
-  ),
-  process_count AS (
-    SELECT
-      'active_processes' as metric,
-      CAST(COUNT(DISTINCT p.upid) AS TEXT) as value,
-      NULL as ts
-    FROM process p
-    JOIN thread t ON t.upid = p.upid
-    JOIN thread_state ts_tbl ON ts_tbl.utid = t.utid
-    CROSS JOIN trace_bounds tb
-    WHERE ts_tbl.ts >= tb.t_start AND ts_tbl.ts <= tb.t_end
-      AND ts_tbl.state = 'Running'
-  ),
-  oom_adj AS (
-    SELECT
-      'foreground_apps' as metric,
-      GROUP_CONCAT(p.name, ', ') as value,
-      NULL as ts
-    FROM (
-      SELECT DISTINCT p.name, p.upid
-      FROM counter c
-      JOIN process_counter_track pct ON c.track_id = pct.id
-      JOIN process p ON p.upid = pct.upid
-      CROSS JOIN trace_bounds tb
-      WHERE pct.name = 'oom_score_adj'
-        AND c.value <= 0
-        AND c.ts >= tb.t_start AND c.ts <= tb.t_end
-        AND p.name IS NOT NULL AND p.name != ''
-      LIMIT 10
-    ) p
-  )
-  SELECT metric, value, printf('%d', ts) as ts FROM screen_state
-  UNION ALL SELECT metric, value, printf('%d', ts) as ts FROM battery_info
-  UNION ALL SELECT metric, value, printf('%d', ts) as ts FROM charging_info
-  UNION ALL SELECT metric, value, printf('%d', ts) as ts FROM thermal_info
-  UNION ALL SELECT metric, value, printf('%d', ts) as ts FROM cpu_freq_summary
-  UNION ALL SELECT metric, value, printf('%d', ts) as ts FROM memory_info
-  UNION ALL SELECT metric, value, printf('%d', ts) as ts FROM process_count
-  UNION ALL SELECT metric, value, printf('%d', ts) as ts FROM oom_adj
-
-output:
-  format: structured