@gracker/smartperfetto 1.0.14 → 1.0.16

package/skills/atomic/process_identity_resolver.skill.yaml

@@ -144,6 +144,22 @@ display:
       label: "关键线程"
       type: string
       format: truncate
+    - name: thread_utid
+      label: "命中线程 UTID"
+      type: number
+    - name: thread_tid
+      label: "命中线程 TID"
+      type: number
+    - name: thread_name
+      label: "命中线程"
+      type: string
+      format: truncate
+    - name: thread_role
+      label: "线程角色"
+      type: string
+    - name: thread_target_matched
+      label: "命中目标线程"
+      type: boolean
     - name: layer_packages
       label: "Layer 包名"
       type: string
@@ -233,6 +249,17 @@ sql: |
       MAX(CASE
         WHEN input.target_thread IS NOT NULL
           AND COALESCE(t.name, '') GLOB '*' || input.target_thread || '*'
+        THEN 1
+        WHEN LOWER(COALESCE(input.target_thread, '')) IN ('main', 'ui', 'app_main')
+          AND (t.is_main_thread = 1 OR t.tid = p.pid)
+        THEN 1
+        WHEN LOWER(COALESCE(input.target_thread, '')) IN ('renderthread', 'render_thread', 'render')
+          AND (
+            t.name IN ('RenderThread', 'GPU completion', 'hwuiTask0', 'hwuiTask1')
+            OR t.name GLOB '[0-9]*.ui'
+            OR t.name GLOB '[0-9]*.raster'
+            OR t.name GLOB 'Cr*Main'
+          )
         THEN 1 ELSE 0 END) AS target_thread_match,
       GROUP_CONCAT(DISTINCT CASE
         WHEN t.is_main_thread = 1 OR t.tid = p.pid
@@ -247,6 +274,96 @@ sql: |
     CROSS JOIN input
     GROUP BY t.upid
   ),
+  thread_identity_candidates AS (
+    SELECT
+      t.upid,
+      t.utid,
+      t.tid,
+      COALESCE(t.name, '<unnamed>') AS thread_name,
+      CASE
+        WHEN t.is_main_thread = 1 OR t.tid = p.pid THEN 'app_main'
+        WHEN t.name IN ('RenderThread', 'GPU completion', 'hwuiTask0', 'hwuiTask1')
+          OR t.name GLOB '[0-9]*.ui'
+          OR t.name GLOB '[0-9]*.raster'
+          OR t.name GLOB 'Cr*Main'
+        THEN 'render_thread'
+        ELSE 'unknown'
+      END AS thread_role,
+      CASE
+        WHEN input.target_thread IS NOT NULL
+          AND COALESCE(t.name, '') GLOB '*' || input.target_thread || '*'
+        THEN 1
+        WHEN LOWER(COALESCE(input.target_thread, '')) IN ('main', 'ui', 'app_main')
+          AND (t.is_main_thread = 1 OR t.tid = p.pid)
+        THEN 1
+        WHEN LOWER(COALESCE(input.target_thread, '')) IN ('renderthread', 'render_thread', 'render')
+          AND (
+            t.name IN ('RenderThread', 'GPU completion', 'hwuiTask0', 'hwuiTask1')
+            OR t.name GLOB '[0-9]*.ui'
+            OR t.name GLOB '[0-9]*.raster'
+            OR t.name GLOB 'Cr*Main'
+          )
+        THEN 1 ELSE 0
+      END AS thread_target_matched,
+      ROW_NUMBER() OVER (
+        PARTITION BY t.upid
+        ORDER BY
+          CASE
+            WHEN input.target_thread IS NOT NULL
+              AND COALESCE(t.name, '') GLOB '*' || input.target_thread || '*'
+            THEN 0
+            WHEN LOWER(COALESCE(input.target_thread, '')) IN ('main', 'ui', 'app_main')
+              AND (t.is_main_thread = 1 OR t.tid = p.pid)
+            THEN 0
+            WHEN LOWER(COALESCE(input.target_thread, '')) IN ('renderthread', 'render_thread', 'render')
+              AND (
+                t.name IN ('RenderThread', 'GPU completion', 'hwuiTask0', 'hwuiTask1')
+                OR t.name GLOB '[0-9]*.ui'
+                OR t.name GLOB '[0-9]*.raster'
+                OR t.name GLOB 'Cr*Main'
+              )
+            THEN 0 ELSE 1
+          END,
+          CASE WHEN t.is_main_thread = 1 OR t.tid = p.pid THEN 0 ELSE 1 END,
+          CASE
+            WHEN t.name IN ('RenderThread', 'GPU completion', 'hwuiTask0', 'hwuiTask1')
+              OR t.name GLOB '[0-9]*.ui'
+              OR t.name GLOB '[0-9]*.raster'
+              OR t.name GLOB 'Cr*Main'
+            THEN 0 ELSE 1
+          END,
+          t.utid
+      ) AS thread_rank
+    FROM thread t
+    JOIN process p USING (upid)
+    CROSS JOIN input
+    WHERE
+      (input.target_thread IS NOT NULL AND COALESCE(t.name, '') GLOB '*' || input.target_thread || '*')
+      OR (LOWER(COALESCE(input.target_thread, '')) IN ('main', 'ui', 'app_main') AND (t.is_main_thread = 1 OR t.tid = p.pid))
+      OR (LOWER(COALESCE(input.target_thread, '')) IN ('renderthread', 'render_thread', 'render') AND (
+        t.name IN ('RenderThread', 'GPU completion', 'hwuiTask0', 'hwuiTask1')
+        OR t.name GLOB '[0-9]*.ui'
+        OR t.name GLOB '[0-9]*.raster'
+        OR t.name GLOB 'Cr*Main'
+      ))
+      OR t.is_main_thread = 1
+      OR t.tid = p.pid
+      OR t.name IN ('RenderThread', 'GPU completion', 'hwuiTask0', 'hwuiTask1')
+      OR t.name GLOB '[0-9]*.ui'
+      OR t.name GLOB '[0-9]*.raster'
+      OR t.name GLOB 'Cr*Main'
+  ),
+  thread_identity AS (
+    SELECT
+      upid,
+      utid AS thread_utid,
+      tid AS thread_tid,
+      thread_name,
+      thread_role,
+      thread_target_matched
+    FROM thread_identity_candidates
+    WHERE thread_rank = 1
+  ),
   frame_rows AS (
     SELECT
       a.upid,
@@ -326,6 +443,11 @@ sql: |
       COALESCE(ts.has_rendering_thread, 0) AS has_rendering_thread,
       COALESCE(ts.target_thread_match, 0) AS target_thread_match,
       ts.key_thread_names,
+      ti.thread_utid,
+      ti.thread_tid,
+      ti.thread_name,
+      ti.thread_role,
+      COALESCE(ti.thread_target_matched, 0) AS thread_target_matched,
       COALESCE(fs.frame_rows, 0) AS frame_rows,
       COALESCE(fs.jank_rows, 0) AS jank_rows,
       COALESCE(fs.layer_target_match, 0) AS layer_target_match,
@@ -342,6 +464,7 @@ sql: |
     FROM process_base pb
     CROSS JOIN input
     LEFT JOIN thread_summary ts USING (upid)
+    LEFT JOIN thread_identity ti USING (upid)
     LEFT JOIN frame_summary fs USING (upid)
     LEFT JOIN oom_summary os USING (upid)
     LEFT JOIN battery_top bt
@@ -367,7 +490,8 @@ sql: |
         CASE WHEN target_name IS NOT NULL AND COALESCE(process_name, '') GLOB target_name || '*' THEN 20 ELSE 0 END +
         CASE WHEN target_name IS NOT NULL AND COALESCE(cmdline, '') GLOB target_name || '*' THEN 20 ELSE 0 END +
         CASE WHEN target_name IS NOT NULL AND layer_target_match = 1 AND is_system_like_process = 0 THEN 15 ELSE 0 END +
-        CASE WHEN target_thread IS NOT NULL AND target_thread_match = 1 THEN 20 ELSE 0 END
+        CASE WHEN target_thread IS NOT NULL AND target_thread_match = 1 THEN 20 ELSE 0 END +
+        CASE WHEN target_name IS NULL AND target_upid IS NULL AND target_pid IS NULL AND target_thread IS NOT NULL AND target_thread_match = 1 THEN 35 ELSE 0 END
       ) AS identity_score,
       (
         CASE WHEN frame_rows > 0 THEN 15 ELSE 0 END +
@@ -469,6 +593,11 @@ sql: |
     ROUND(battery_top_ns / 1e6, 2) AS battery_top_ms,
     thread_count,
     key_thread_names,
+    thread_utid,
+    thread_tid,
+    thread_name,
+    thread_role,
+    thread_target_matched,
     layer_packages,
     CASE
       WHEN package_name IS NOT NULL

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/skills/composite/code_pinpoint.skill.yaml

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2024-2026 Gracker (Chris)
+# This file is part of SmartPerfetto. See LICENSE for details.
+
+name: code_pinpoint
+version: "1.0"
+type: composite
+tier: S
+
+meta:
+  display_name: "代码定位线索"
+  description: "从 trace 中提取可用于 codebase-aware resolve_symbol / lookup_source 的线程、slice、module 和 symbol 线索"
+  icon: "code"
+  tags: [codebase, symbol, source, root_cause]
+
+triggers:
+  keywords:
+    zh: [代码, 源码, 函数, 符号, patch, 修复建议, file line]
+    en: [code, source, symbol, function, patch, file line]
+
+prerequisites:
+  modules:
+    - slices.with_context
+    - android.process_metadata
+
+inputs:
+  - name: package
+    type: string
+    required: false
+    description: "应用包名或进程名（可选）"
+  - name: start_ts
+    type: timestamp
+    required: false
+    description: "分析起始时间戳（纳秒，可选）"
+  - name: end_ts
+    type: timestamp
+    required: false
+    description: "分析结束时间戳（纳秒，可选）"
+
+identity:
+  policy: verify_if_present
+  scope: process
+  aliases: [package, process_name]
+  rewriteTo: recommended_process_name_param
+
+steps:
+  - id: hot_slices
+    type: atomic
+    name: "代码定位候选 slice"
+    display:
+      level: detail
+      layer: list
+      title: "Code Pinpoint Candidates"
+      columns:
+        - name: process_name
+          label: "Process"
+          type: string
+        - name: thread_name
+          label: "Thread"
+          type: string
+        - name: slice_name
+          label: "Slice"
+          type: string
+        - name: dur_ms
+          label: "Duration"
+          type: duration
+          unit: ms
+    sql: |
+      INCLUDE PERFETTO MODULE slices.with_context;
+
+      SELECT
+        process_name,
+        thread_name,
+        name AS slice_name,
+        ROUND(dur / 1e6, 3) AS dur_ms
+      FROM thread_slice
+      WHERE dur > 0
+        AND (${package} IS NULL OR process_name GLOB ${package} || '*')
+        AND (${start_ts} IS NULL OR ts >= ${start_ts})
+        AND (${end_ts} IS NULL OR ts + dur <= ${end_ts})
+      ORDER BY dur DESC
+      LIMIT 30;
+
+  - id: native_modules
+    type: atomic
+    name: "Native module / build-id 线索"
+    display:
+      level: debug
+      layer: deep
+      title: "Native Module Hints"
+      columns:
+        - name: module_name
+          label: "Module"
+          type: string
+        - name: build_id
+          label: "Build ID"
+          type: string
+        - name: frame_count
+          label: "Frames"
+          type: number
+    optional: true
+    sql: |
+      SELECT
+        COALESCE(m.name, '(unknown)') AS module_name,
+        COALESCE(m.build_id, '') AS build_id,
+        COUNT(*) AS frame_count
+      FROM stack_profile_frame f
+      JOIN stack_profile_mapping m ON f.mapping = m.id
+      GROUP BY module_name, build_id
+      ORDER BY frame_count DESC
+      LIMIT 30;

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/code-aware.template.md

@@ -0,0 +1,37 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+## Codebase-Aware Analysis
+
+本 session 已启用代码库感知分析：
+
+- `codeAwareMode`: `{{codeAwareMode}}`
+- whitelisted `codebaseIds`: `{{codebaseIds}}`
+
+### 工具顺序
+
+1. 先用 trace/Skill/SQL 找到性能现象和可疑线程、阶段、slice、symbol。
+2. 如果 trace 证据指向 App 代码，调用 `resolve_symbol(kind="app")`，再调用 `lookup_app_source`。
+3. 如果 trace 证据指向 AOSP/native，调用 `resolve_symbol(kind="native")`，再调用 `lookup_aosp_source`。
+4. 如果 trace 证据指向 kernel/vendor fork，调用 `resolve_symbol(kind="kernel")`，再调用 `lookup_kernel_source`，必须带 `vendor` 或明确 `codebase_id`。
+5. 只有在已有 successful lookup 的 `chunkId` 后，才可调用 `propose_patch`。
+
+### 输出纪律
+
+- 最终回答、阶段总结、报告和 export 中只能写 `chunkId`、相对 `filePath`、`lineRange`、`symbol`、`patchProposalId`。
+- 不要在自然语言中复述源码正文、secret、rootPath 或 absolute path。
+- `metadata_only` / `provider_send_disabled_for_session` 结果只能作为定位引用，不能引用源码内容。
+- `symbol_only_low_confidence` 或 `build_id_missing_cannot_pin_codebase` 时，必须说明无法可靠定位 file:line，不能生成 patch。
+
+### Patch 纪律
+
+- `patchStatus="verified"`：可以引用结构化 diff block 或 patch id。
+- `patchStatus="sketch"`：只能输出 rationale + patchSketch，不能输出 unified diff，也不能暗示可直接复制。
+- `patchStatus="unverified"`：只输出拒绝原因和下一步取证建议。
+- `multi_codebase_not_supported_phase1`：把 App/AOSP/kernel 修复拆成多个 proposal，不要合成跨库 diff。
+
+### Plan 44/54/55 边界
+
+- `recall_project_memory` / `recall_similar_case` / legacy `lookup_blog_knowledge` 可作为背景知识，不等同于用户代码证据。
+- 代码级根因必须来自 codebase registry chunk 或明确的 AOSP/OEM source chunk。
+

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/prompt-methodology.template.md

@@ -31,6 +31,8 @@ successCriteria: "确定掉帧根因并提供可操作的优化建议"
 3. **execute_sql** — 仅在没有匹配 Skill 或需要自定义查询时使用。**写 SQL 前务必先 lookup_sql_schema**
 4. **list_skills** — 不确定用哪个 Skill 时，先列出可用选项
 5. **detect_architecture** — 分析开始时调用，了解渲染管线类型
+6. **resolve_symbol / lookup_app_source / lookup_aosp_source / lookup_kernel_source** — 只有当 session 启用 codebase-aware 且 trace 证据已经指向具体代码域时使用；先定位 symbol，再查源码，最终只引用 CodeRef
+7. **propose_patch** — 只有在已有 successful code lookup 的 chunkId 后使用；未 verified 的 patch 只能作为 sketch，不能输出 copyable diff
 
 ### 参数说明
 - 调用 invoke_skill 时使用 `process_name` 参数（系统会自动映射为 YAML skill 中的 `package`）