@gracker/smartperfetto 1.0.13

package/strategies/teaching.strategy.md

@@ -0,0 +1,176 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+---
+scene: teaching
+priority: 3
+effort: medium
+required_capabilities: []
+optional_capabilities: []
+keywords:
+  - 教学
+  - 是什么
+  - 什么意思
+  - 怎么工作
+  - 怎么运作
+  - explain
+  - how does
+  - what is
+  - thread role
+  - mechanism
+  - 原理
+  - 线程角色
+  - 关键slice
+  - mermaid
+  - 源码
+  - source code
+  - 这个slice
+compound_patterns:
+  - "这个.*是什么"
+  - ".*怎么.*工作"
+  - ".*是.*什么意思"
+  - "explain.*this"
+  - "what.*does.*this"
+  - ".*管线.*是"
+  - ".*pipeline.*is"
+
+plan_template:
+  mandatory_aspects:
+    - id: architecture_detection
+      match_keywords: ['detect_architecture', 'architecture', '架构', 'pipeline', '管线', '教学']
+      suggestion: '教学场景建议包含架构检测阶段 (detect_architecture)'
+    - id: pipeline_teaching
+      match_keywords: ['teach', 'explain', '说明', '解释', 'thread', '线程', 'slice', 'mermaid', 'invoke_skill']
+      suggestion: '教学场景建议包含管线教学内容获取阶段 (invoke_skill with pipeline skill)'
+---
+
+#### 教学/概念解释分析（用户提到 是什么、什么意思、怎么工作、explain、what is、pipeline、thread role）
+
+**核心目标：** 帮助用户理解 trace 中的组件、线程、Slice 和渲染管线的工作原理，先教后诊、分层递进。
+
+**Phase 1 — 识别用户关注对象：**
+
+根据用户输入判断教学方向：
+
+| 用户关注对象 | 判断方式 | 教学路径 |
+|------------|---------|---------|
+| 选中的 Slice | 用户提到"这个slice"、"这个是什么" + 有 selection context | 解释 Slice 含义 → 所属管线 → 正常范围 |
+| 特定线程 | 用户提到线程名（RenderThread、1.ui、CrRendererMain 等） | 解释线程角色 → 在渲染管线中的位置 |
+| 渲染架构/管线 | 用户提到"管线"、"pipeline"、"渲染架构" | 先检测架构 → 加载对应管线教学 |
+| 通用概念 | 用户提到"VSync"、"Choreographer"、"SurfaceFlinger" 等术语 | 概念解释 → 在管线中的位置 → 与 trace 的关联 |
+
+**Phase 2 — 架构检测与 observed-flow 教学：**
+```
+invoke_skill('rendering_pipeline_detection', { package: <package hint> })
+# 读取 pipeline_bundle: detection + teachingContent + pinInstructions + activeRenderingProcesses
+# 再基于 selection / visible window / package hint 查询 observedFlow.lanes/events
+# 对关键 rendering event 追加 bounded scheduler 事实：
+#   - thread_state.waker_id -> direct_wakeup / wakes_to
+#   - sched.thread_executing_span_with_slice._critical_path_stack -> critical_path_segment / critical_path_to
+```
+- 先展示当前 trace 中真实观测到的 lanes/events，再展示 Mermaid
+- `primary_pipeline_id` 只是入口，不是最终单选结论
+- 如果 candidates/features 暗示 WebView/Flutter/RN/GL/TextureView/SurfaceView 等混合出图，先分开展示 host HWUI 与 producer 链路
+- 如果 trace 具备 sched/thread_state 信号，展示 Critical task / Wakeup 关系；如果缺少 `sched_wakeup` 或官方 critical path 为空，明确标成采集缺口
+- 解释关键线程角色（main thread、RenderThread、producer、SurfaceFlinger、HWC/present）
+- 列出关键 Slice 及其含义，并标注哪些在当前 trace 中真实命中、哪些缺失
+- 如果用户有 selection context，优先关联选区；否则使用 visible window，再退回 package/process hint 或活跃渲染进程 fallback
+
+**Phase 3 — 上下文关联教学：**
+
+**3a. 异常关联（教 + 诊）：**
+- 如果用户选中的 Slice/线程存在明显异常 → 先解释正常行为，再指出偏差
+- 例如："DrawFrame 正常耗时 4-8ms，当前帧耗时 35ms，超出帧预算"
+
+**3b. 源码位置（按需）：**
+注意：AOSP 源码路径可能因 Android 版本不同而变化。如果引用源码位置，标注适用的 Android 版本范围（如 'Android 12+ (API 31+)'）。核心渲染路径在 android14-release 分支为最新参考。
+
+如果用户问到源码位置，提供 AOSP 源码路径 + 关键函数名：
+
+| Slice 名称 | AOSP 源码文件 | 关键函数 |
+|-----------|-------------|---------|
+| DrawFrame | android/view/ViewRootImpl.java | performTraversals() |
+| Choreographer#doFrame | android/view/Choreographer.java | doFrame() |
+| RenderThread::draw | libs/hwui/renderthread/RenderThread.cpp | draw() |
+| dequeueBuffer | frameworks/native/libs/gui/Surface.cpp | dequeueBuffer() |
+| onMessageReceived | frameworks/native/services/surfaceflinger/SurfaceFlinger.cpp | onMessageReceived() |
+| bindApplication | android/app/ActivityThread.java | handleBindApplication() |
+| performCreate | android/app/Instrumentation.java | callActivityOnCreate() |
+| inflate | android/view/LayoutInflater.java | inflate() |
+| measure / layout / draw | android/view/View.java | measure(), layout(), draw() |
+| Choreographer#doCallbacks | android/view/Choreographer.java | doCallbacks() |
+| eglSwapBuffers | frameworks/native/opengl/libs/EGL/eglApi.cpp | eglSwapBuffersWithDamageKHR() |
+| queueBuffer | frameworks/native/libs/gui/Surface.cpp | queueBuffer() |
+
+**3c. Perfetto 表/视图查询：**
+如果用户问到 Perfetto 的特定表或视图：
+```
+lookup_sql_schema("<table_or_view_name>")
+```
+返回表的 schema、列定义和用途说明。
+
+**Phase 4 — 教学输出格式：**
+
+### 输出结构必须遵循：
+
+1. **概念说明**：这个组件/Slice/线程是什么（1-2 句话，用中文通俗解释）
+   - 术语首次出现时给出中英文对照，如：VSync（垂直同步信号）
+
+2. **在渲染管线中的位置**：它在帧渲染流程中处于什么阶段（如有 Mermaid 图则展示）
+   - 标注当前关注对象在 Mermaid 图中的位置
+
+3. **关键线程角色**：
+   ```
+   | 线程名 | 职责 | 对应的 Trace 标签 |
+   |-------|------|----------------|
+   | main | UI 布局和绘制 | Choreographer#doFrame, measure, layout, draw |
+   | RenderThread | GPU 命令提交 | DrawFrame, syncFrameState, flush commands |
+   | SurfaceFlinger | 合成与显示 | onMessageReceived, INVALIDATE, REFRESH |
+   ```
+
+4. **关键 Slice 说明**：
+   ```
+   | Slice 名称 | 说明 | 正常耗时范围 |
+   |-----------|------|------------|
+   | Choreographer#doFrame | VSync 触发的帧回调入口 | 2-8ms |
+   | DrawFrame | RenderThread 绘制入口 | 2-6ms |
+   | dequeueBuffer | 从 BufferQueue 获取缓冲区 | <1ms |
+   ```
+
+5. **AOSP 源码位置**（仅在用户明确问到时提供）：
+   - 源码文件路径 + 关键函数名
+
+6. **与当前 Trace 的关联**：
+   - 必须区分“trace 中实际观测到的事实”和“文档/YAML 中的机制解释”
+   - 如果用户选中了特定内容，将教学与选区关联
+   - 没有 selection 时说明使用 visible window、package/process hint 还是 fallback
+   - 如有异常，指出偏差并简要说明可能原因
+   - 如果缺少 SurfaceFlinger/HWC/present/fence 等采集信号，明确说明不能伪造这一段链路
+
+7. **常见问题**：
+   - 该组件相关的常见性能问题（2-3 条）
+   - 每条包含：问题表现、典型原因、排查方向
+
+**Phase 5 — 时间线可视化（可选）：**
+
+当你完成管线教学内容后，如果已检测到管线类型并获取了关键 Slice 列表，调用以下 skill 将关键 Slice 高亮为 Perfetto 时间线 overlay，帮助用户对照理论管线图与实际 trace。这个 overlay 结果应进入 observed-flow 语义：命中的 slice 是事实，未命中的 slice 是 warning，不是静态模板事实。
+
+```
+invoke_skill('pipeline_key_slices_overlay', {
+  slice_names: "'Choreographer#doFrame','DrawFrame','syncFrameState',...",
+  package: <package hint>,
+  start_ts: <分析区间起始>,
+  end_ts: <分析区间结束>
+})
+```
+
+注意：`slice_names` 参数使用 SQL IN 列表格式，每个名称用单引号包裹、逗号分隔。从管线教学的 `key_slices` 列表中提取名称。
+
+**教学原则：**
+- **先教后诊**：先解释正常行为，再指出异常
+- **事实先于模板**：真实 slice/thread/process/layer/ts/dur/present 证据优先；Mermaid 和文档只解释已观测链路
+- **混合链路分开看**：HWUI host 与 WebView/Flutter/RN/GL/TextureView/SurfaceView producer 先分开展示，再在有 dependency/overlap 证据时合并
+- **分层教学**：第一轮给概览，用户追问再深入
+- **关联实践**：始终结合当前 trace 中的实际数据
+- **不假设知识**：首次使用技术术语时用中文解释含义
+- **鼓励探索**：在结尾建议用户可以进一步询问的方向

package/strategies/touch-tracking.strategy.md

@@ -0,0 +1,213 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+---
+scene: touch_tracking
+priority: 3
+effort: medium
+required_capabilities:
+  - input_latency
+  - frame_rendering
+  - surfaceflinger
+optional_capabilities:
+  - cpu_scheduling
+  - gpu
+keywords:
+  - 跟手度
+  - 跟手
+  - 跟随
+  - follow finger
+  - touch tracking
+  - 触控延迟
+  - 持续延迟
+  - 滑动跟随
+  - input to display
+  - 管线延迟
+  - pipeline latency
+  - 触摸跟踪
+  - touch latency
+  - 输入延迟持续
+compound_patterns:
+  - "跟手.*度"
+  - "跟手.*延迟"
+  - "滑动.*跟手"
+  - "滑动.*跟随"
+  - "touch.*tracking"
+  - "follow.*finger"
+  - "input.*display.*latency"
+  - "持续.*延迟"
+  - "每帧.*延迟"
+  - "per.*frame.*latency"
+
+plan_template:
+  mandatory_aspects:
+    - id: per_frame_latency_measurement
+      match_keywords: ['input', 'touch', '跟手', '延迟', 'latency', 'per_frame', 'tracking']
+      suggestion: '跟手度场景建议包含逐帧 Input-to-Display 延迟测量阶段'
+---
+
+#### 跟手度分析（用户提到 跟手度、跟手延迟、follow finger、touch tracking）
+
+**⚠️ 核心区分：跟手度 ≠ 首帧响应速度 ≠ 滑动流畅性**
+
+| 指标 | 定义 | 对应策略 |
+|------|------|---------|
+| **跟手度**（本策略） | 整个滑动过程中，每一个 MotionEvent 到它对应的帧 present 的**持续延迟** | touch_tracking |
+| **首帧响应速度** | ACTION_MOVE → 第一帧画面变化的**单次延迟** | scroll_response |
+| **滑动流畅性** | 帧间时间稳定性、掉帧率 | scrolling |
+
+跟手度差的典型表现：手指已经滑到位置 A，但屏幕内容还停留在 2-3 帧之前的位置。
+用户不会感到"卡顿"（帧率可能60fps），但会感到"不跟手"、"有黏滞感"。
+
+**Phase 1 — 逐帧 Input-to-Display 延迟测量：**
+
+```
+invoke_skill("input_to_frame_latency", { process_name: "<包名>" })
+```
+返回：每个 MOVE 事件的 5 维延迟分解（dispatch/handling/ack/e2e）+ 帧内分解（frame_dur/frame_to_present），以及统计指标（均值、P50、P90、P99、抖动）和 is_speculative 帧关联置信度。
+
+如果该 Skill 不可用（trace 缺少 `sendMessage(*)`/`receiveMessage(*)` slices），使用 SQL 回退：
+```sql
+-- 查找 MOVE 事件与消费帧的关联
+WITH input_events AS (
+  SELECT
+    ied.ts as input_ts,
+    ied.event_action,
+    ied.upid,
+    p.name as process_name
+  FROM android_input_event_dispatch ied
+  LEFT JOIN process p ON p.upid = ied.upid
+  WHERE (p.name GLOB '{process_name}*' OR '{process_name}' = '')
+    AND (ied.event_action = 'ACTION_MOVE' OR ied.event_action = '2')
+),
+frame_match AS (
+  SELECT
+    ie.input_ts,
+    ie.process_name,
+    (SELECT MIN(f.ts) FROM actual_frame_timeline_slice f
+     WHERE f.upid = ie.upid AND f.ts >= ie.input_ts) as frame_ts,
+    (SELECT MIN(f.ts + f.dur) FROM actual_frame_timeline_slice f
+     WHERE f.upid = ie.upid AND f.ts >= ie.input_ts) as frame_present_ts
+  FROM input_events ie
+)
+SELECT
+  printf('%d', input_ts) as input_ts,
+  process_name,
+  printf('%d', frame_ts) as frame_ts,
+  printf('%d', frame_present_ts) as frame_present_ts,
+  ROUND((frame_present_ts - input_ts) / 1e6, 2) as input_to_display_ms,
+  ROUND((frame_ts - input_ts) / 1e6, 2) as input_to_frame_start_ms
+FROM frame_match
+WHERE frame_present_ts IS NOT NULL
+ORDER BY input_ts
+```
+
+**评级标准（基于 P90 input-to-display 延迟）：**
+
+| P90 延迟 | 评级 | 说明 |
+|---------|------|------|
+| <32ms | 极佳 | 约 2 帧延迟（60Hz），用户感知完美跟手 |
+| 32-48ms | 良好 | 约 2-3 帧延迟（60Hz），轻微不跟手但可接受 |
+| 48-64ms | 一般 | 约 3-4 帧延迟，明显不跟手感 |
+| 64-96ms | 差 | 4-6 帧延迟，强烈黏滞感 |
+| >96ms | 极差 | 严重不跟手 |
+
+注意：120Hz 设备的评级标准更严格（×0.5），240Hz 更甚。需先检测 VSync 周期进行评级校准。
+
+**Phase 2 — VSync 相位分析：**
+
+跟手延迟的一个关键因素是 **input sampling 与 VSync 的相位关系**。
+
+```
+invoke_skill("vsync_phase_alignment", { process_name: "<包名>" })
+```
+
+该 Skill 测量：
+- Input event timestamp 与最近 VSync 信号的相位差
+- 相位差的统计分布
+- 是否存在系统性的相位偏移（worst case: input 刚好在 VSync 后到达，需要多等一帧）
+
+**Phase 3 — 延迟分解（根因定位）：**
+
+将每帧 input-to-display 延迟分解为 4 段：
+
+| 段 | 计算方法 | 正常范围 (60Hz) | 含义 |
+|----|---------|---------------|------|
+| **Input→VSync** | frame_ts - input_ts | 0-16ms | 输入事件等待下一个 VSync（取决于相位） |
+| **VSync→FrameEnd** | frame_dur | 8-16ms | App 处理帧（measure+layout+draw+RenderThread） |
+| **FrameEnd→Present** | present_ts - (frame_ts + frame_dur) | 0-16ms | SurfaceFlinger 合成+呈现 |
+| **总计** | present_ts - input_ts | 16-48ms | 端到端 |
+
+对于延迟偏高的帧，深钻瓶颈段：
+```sql
+-- 检查 Choreographer wait 是否过长
+SELECT
+  printf('%d', s.ts) AS ts,
+  ROUND(s.dur / 1e6, 2) AS dur_ms,
+  s.name
+FROM slice s
+JOIN thread_track tt ON s.track_id = tt.id
+JOIN thread t ON tt.utid = t.utid
+WHERE t.name = 'main' AND s.name = 'Choreographer#doFrame'
+  AND s.ts >= {frame_ts} - 20000000
+  AND s.ts <= {frame_ts} + 20000000
+ORDER BY s.ts
+LIMIT 5
+```
+
+**Phase 4 — 跟手度优化诊断树：**
+
+| 根因 | 判断条件 | 优化方向 |
+|------|---------|---------|
+| **VSync 相位不利** | Input→VSync 段持续 >12ms | 调整 input dispatch timing 或启用 input prediction |
+| **帧处理过慢** | VSync→FrameEnd 段 >16ms | 同滑动卡顿分析（四象限诊断） |
+| **SF 合成延迟** | FrameEnd→Present 段 >16ms | GPU composition 慢 / layer 数多 |
+| **管线深度过深** | 持续 3+ 帧延迟 | 检查 BufferQueue 模式（triple buffering → 固有 3 帧延迟） |
+| **低刷新率** | VSync 周期 >16ms | 设备未处于高刷模式（VRR 未激活） |
+| **输入采样率低** | input event 间隔 >12ms | 触控 IC 采样率低（120Hz touch sampling = 8.3ms interval） |
+
+**深钻决策：**
+
+| 条件 | 深钻动作 |
+|------|---------|
+| **VSync→FrameEnd 过长** | `invoke_skill("jank_frame_detail", ...)` 查看帧内瓶颈 |
+| **管线深度 ≥3** | 检查 BufferQueue 深度和 BLAST/Legacy 模式 |
+| **持续高延迟 + 低频率** | `invoke_skill("thermal_throttling")` 检查是否热降频 |
+| **VSync 周期异常** | `invoke_skill("vrr_detection")` 检查 VRR 状态 |
+
+### 输出结构必须遵循：
+
+1. **跟手度评级**：P50/P90/P99 input-to-display 延迟 + 评级（需标注设备刷新率）
+   ```
+   | 统计指标 | 值 | 说明 |
+   |---------|-----|------|
+   | 设备刷新率 | 120Hz (8.33ms/帧) | VSync 周期 |
+   | 触控采样率 | ~240Hz (~4.2ms) | Input event 间隔中位数 |
+   | P50 延迟 | 24ms | 约 3 帧延迟 |
+   | P90 延迟 | 38ms | 约 4.5 帧延迟 |
+   | P99 延迟 | 65ms | 约 8 帧延迟 |
+   | 抖动 (StdDev) | 8ms | 延迟稳定性 |
+   ```
+
+2. **延迟分布图**：按时间顺序展示每帧的 input-to-display 延迟
+   - 标注延迟飙升点（spike）
+   - 关联可能的系统事件（GC、Binder、频率变化）
+
+3. **延迟分段分解**：
+   ```
+   | 延迟段 | 均值 | P90 | 是否瓶颈 |
+   |-------|------|-----|---------|
+   | Input→VSync | 6ms | 12ms | |
+   | VSync→FrameEnd | 10ms | 22ms | ★ 瓶颈 |
+   | FrameEnd→Present | 8ms | 14ms | |
+   | **总计** | **24ms** | **38ms** | |
+   ```
+
+4. **根因分析**：基于延迟分段定位主要瓶颈
+   - 如果是 VSync 相位问题：说明 input sampling 与 VSync 的对齐情况
+   - 如果是帧处理慢：给出主线程/RenderThread 的热点
+   - 如果是管线深度：说明 BufferQueue 配置
+
+5. **优化建议**：
+   - 按根因类别给出可操作建议
+   - 标注预期收益（例如"优化后预计 P90 从 38ms 降至 24ms"）