@gracker/smartperfetto 1.0.13

package/strategies/interaction.strategy.md

@@ -0,0 +1,149 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+---
+scene: interaction
+priority: 4
+effort: medium
+required_capabilities:
+  - input_latency
+  - frame_rendering
+optional_capabilities:
+  - cpu_scheduling
+  - binder_ipc
+  - surfaceflinger
+keywords:
+  - 点击
+  - 触摸
+  - 输入延迟
+  - 响应延迟
+  - 点击慢
+  - 响应慢
+  - 点击卡顿
+  - click
+  - tap
+  - touch
+  - input latency
+  - response time
+  - click delay
+  - input delay
+compound_patterns:
+  - "点击.*响应"
+  - "响应.*时间"
+  - "输入.*慢"
+---
+
+#### 点击/触摸响应分析（用户提到 点击、触摸、tap、click、input latency）
+
+**Phase 1 — 概览 + 慢事件列表（1 次调用）：**
+```
+invoke_skill("click_response_analysis", { enable_per_event_detail: false })
+```
+- 如果知道包名，传入 `package` 参数以精确过滤
+- 如果知道时间范围，传入 `start_ts` / `end_ts`
+- 返回结果包含以下 artifact：
+  - `latency_overview`：延迟概览（总事件数、平均延迟、P50/P90/P99）
+  - `slow_events`：慢输入事件列表（event_ts, event_end_ts, total_ms, dispatch_ms, handling_ms, event_type, event_action, process_name）
+  - `latency_by_type`：按事件类型分组的延迟统计
+  - `input_thread_state`：输入处理期间的主线程状态分布
+  - `input_binder`：输入处理期间的 Binder 调用
+  - `latency_distribution`：延迟分布直方图
+- **获取慢事件详细数据**：
+  `fetch_artifact(artifactId, detail="rows", offset=0, limit=20)` 获取 `slow_events` 的完整列表
+- **如果没有慢事件**（slow_events 为空或总平均延迟 < 100ms）：报告响应良好并停止，无需深钻
+
+**Phase 2 — 逐事件深钻（最多 5 个慢事件）：**
+
+从 `slow_events` 中选取延迟最大的 5 个事件，对每个事件调用：
+```
+invoke_skill("click_response_detail", {
+  event_ts: "<事件的 event_ts>",
+  event_end_ts: "<事件的 event_end_ts>",
+  total_ms: <总延迟ms>,
+  dispatch_ms: <分发延迟ms>,
+  handling_ms: <处理延迟ms>,
+  event_type: "<事件类型>",
+  event_action: "<事件动作>",
+  process_name: "<进程名>"
+})
+```
+返回每个事件的：
+- `quadrant`：四象限分析（Q1 大核运行 / Q2 小核运行 / Q3 Runnable / Q4 Sleeping）
+- `cpu_core`：CPU 大小核占比
+- `blocking`：主线程阻塞原因分析（thread_states + blocked_functions）
+- `binder_calls`：Binder 调用详情
+- `main_sync_binder`：主线程同步 Binder 阻塞
+- `sched_delay`：调度延迟
+- `main_file_io`：主线程文件 IO
+
+对大型 artifact 使用 `fetch_artifact` 获取完整行数据。
+
+**Phase 3 — 综合结论（基于根因决策树）：**
+
+### 第一步：瓶颈定位 — dispatch vs handling vs ack
+
+| 延迟阶段 | 含义 | 高占比（>50% 总延迟）时的根因方向 |
+|---------|------|-------------------------------|
+| dispatch_ms | 系统分发延迟（从内核到应用） | 系统侧问题：SurfaceFlinger 忙、system_server 负载高、输入管线积压 |
+| handling_ms | 应用处理延迟（应用收到事件到处理完成） | 应用侧问题：主线程阻塞、计算量大 → 用四象限分析定位 |
+| ack_ms | ACK 延迟（处理完成到帧上屏） | 渲染管线问题：帧绘制慢、SurfaceFlinger 合成延迟 |
+
+### 第二步：当 handling 是瓶颈时 — 用四象限分析定位
+
+| 四象限 | 占比 | 含义 | 下一步 |
+|--------|------|------|--------|
+| Q1 大核运行 高 | >50% | CPU-bound，处理逻辑重 | 分析主线程热点 slice，检查是否有不必要的同步计算 |
+| Q2 小核运行 高 | >15% | 被调度到性能不足的小核 | 检查进程优先级、EAS/uclamp 配置 |
+| Q3 Runnable 高 | >5% | CPU 资源争抢 | 看调度延迟、后台负载 |
+| Q4 Sleeping 高 | >25% | 主线程被阻塞 | **必须看 blocked_functions** → 第三步 |
+
+### 第三步：当 Q4 占比高时 — 用线程状态 + blocked_functions 定位
+
+| 线程状态 | blocked_functions 特征 | 根因类型 |
+|---------|----------------------|---------|
+| S (Sleeping) | `futex_wait_queue` / `futex_wait` | 锁等待（synchronized/ReentrantLock） |
+| S (Sleeping) | `binder_wait_for_work` / `binder_ioctl` | 同步 Binder 阻塞 |
+| S (Sleeping) | `SyS_nanosleep` / `hrtimer_nanosleep` | 主动 sleep() 调用 |
+| D (Disk Sleep) | `io_schedule` / `blkdev_issue_flush` | 磁盘 IO 阻塞 |
+| D (Disk Sleep) | `SyS_fsync` / `do_fsync` | fsync 刷盘（SQLite/SharedPreferences） |
+| D (Disk Sleep) | `filemap_fault` / `do_page_fault` | 页缺失 |
+
+### 第四步：多手势类型识别（次要 — 仅在用户明确提及时分析）
+
+以下手势类型属于进阶分析，仅在用户明确提到"长按"、"双击"等手势关键词时才进行分析：
+
+| 手势类型 | 识别方式 | 分析要点 |
+|---------|---------|---------|
+| **长按 (Long Press)** | ACTION_DOWN 到 ACTION_UP 之间持续时间 > 500ms，且无 MOVE 事件（或 MOVE < 3 次） | 长按响应由 ViewConfiguration.getLongPressTimeout() 控制（默认 500ms）。如果用户反馈长按响应慢，检查：① 主线程在 DOWN 后 500ms 内是否有阻塞导致 Looper 延迟处理 LongPress Runnable；② onLongClick 回调本身的执行耗时 |
+| **双击 (Double Tap)** | 两次 ACTION_DOWN 之间间隔 < 300ms（ViewConfiguration.getDoubleTapTimeout()） | 双击检测由 GestureDetector 处理。如果用户反馈双击不灵敏，检查：① 两次 tap 间隔是否接近 300ms 阈值；② 首次 tap 的 ACTION_UP 处理是否过慢导致第二次 DOWN 被错过 |
+
+**长按事件检测 SQL（仅在用户提及时使用）：**
+```
+execute_sql("WITH motion AS (SELECT read_time AS ts, event_action, process_name, SUM(CASE WHEN event_action='DOWN' THEN 1 ELSE 0 END) OVER (ORDER BY read_time) AS gid FROM android_input_events WHERE event_type='MOTION'), gestures AS (SELECT gid, MIN(ts) AS down_ts, MAX(CASE WHEN event_action='UP' THEN ts END) AS up_ts, COUNT(CASE WHEN event_action='MOVE' THEN 1 END) AS move_cnt FROM motion WHERE gid>0 GROUP BY gid) SELECT printf('%d', down_ts) AS ts, ROUND((up_ts - down_ts)/1e6, 1) AS hold_ms FROM gestures WHERE up_ts IS NOT NULL AND (up_ts - down_ts) > 500000000 AND move_cnt <= 2 ORDER BY down_ts LIMIT 20")
+```
+
+**双击事件检测 SQL（仅在用户提及时使用）：**
+```
+execute_sql("WITH downs AS (SELECT read_time AS ts, LAG(read_time) OVER (ORDER BY read_time) AS prev_ts FROM android_input_events WHERE event_type='MOTION' AND event_action='DOWN') SELECT printf('%d', ts) AS ts, ROUND((ts - prev_ts)/1e6, 1) AS gap_ms FROM downs WHERE prev_ts IS NOT NULL AND (ts - prev_ts) < 300000000 ORDER BY ts LIMIT 20")
+```
+
+### 输出结构必须遵循：
+
+1. **概览**：总事件数、慢事件数、平均/P90/P99 延迟、总体评级
+   - 如果无慢事件：报告"输入响应良好"并给出关键指标
+
+2. **瓶颈分布**：
+   - dispatch-heavy 事件 N 个（系统侧）
+   - handling-heavy 事件 N 个（应用侧）
+   - ack-heavy 事件 N 个（渲染管线）
+
+3. **逐事件根因**（每个慢事件）：
+   ```
+   ### 事件 #N: [event_type] [event_action] — 总延迟 XXms
+   - 瓶颈阶段：handling (XXms, YY%)
+   - 四象限：Q1=XX% Q2=XX% Q3=XX% Q4=XX%
+   - 根因：[具体根因 + blocked_functions 证据]
+   - 建议：[可操作的优化建议]
+   ```
+
+4. **优化建议**：按影响面排序，区分系统侧 vs 应用侧建议

package/strategies/knowledge-binder-ipc.template.md

@@ -0,0 +1,59 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+# Android Binder IPC
+
+## Mechanism
+
+Binder is Android's primary inter-process communication mechanism. A synchronous binder call works as follows:
+
+1. **Client thread** issues a `binder transaction` and **sleeps** (blocked in kernel)
+2. **Kernel** transfers the call data to the target (server) process
+3. **Server thread** wakes up, executes the requested method, and produces a result
+4. **Kernel** copies the result back to the client
+5. **Client thread** wakes up and continues execution
+
+During the entire round-trip, the client thread cannot do anything else. When this happens on the main thread, it cannot process input events, run animations, or draw frames.
+
+## Why It Blocks the UI
+
+The main thread is single-threaded for UI work. A synchronous binder call on the main thread means:
+- No Choreographer callbacks fire (frame deadlines missed)
+- Input events queue up (touch latency increases)
+- Animations freeze
+
+The blocking duration depends entirely on the server side -- the client has no control over how long the server takes to respond.
+
+## Common Slow Servers
+
+| Server Process | Service | Why It's Slow |
+|---------------|---------|---------------|
+| system_server | ActivityManagerService (AMS) | Lock contention, process lookup |
+| system_server | PackageManagerService (PMS) | Package resolution, permission checks |
+| system_server | WindowManagerService (WMS) | Window state transitions |
+| surfaceflinger | SurfaceComposer | Buffer management, layer updates |
+| mediaserver | MediaCodec/AudioFlinger | Codec allocation, audio routing |
+
+## Trace Signatures
+
+| What to Look For | Meaning |
+|-----------------|---------|
+| `binder transaction` slice on client thread | Client-side blocking duration |
+| `binder reply` slice on server thread | Server-side execution time |
+| blocked_function = `binder_wait_for_work` | Thread idle waiting for incoming binder work |
+| `android_binder_client_server_breakdown` | Detailed server-side blame breakdown |
+
+Server-side blame reasons from `android_binder_client_server_breakdown`:
+- **monitor_contention** -- server thread waiting on a Java monitor lock
+- **io** -- server performing disk or network I/O while handling the call
+- **memory_reclaim** -- kernel reclaiming memory during the call
+- **art_lock_contention** -- ART runtime internal lock contention
+
+## Typical Solutions
+
+- Switch to async binder (`oneway`) where result is not needed immediately
+- Batch multiple IPC calls into a single transaction
+- Defer non-critical IPC to a background thread
+- Cache results of frequent queries (e.g., PackageManager info)
+- Use `ContentResolver.query()` with a projection to minimize data transfer
+- Pre-fetch data during idle time rather than on-demand during frame rendering

package/strategies/knowledge-cpu-scheduler.template.md

@@ -0,0 +1,67 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->
+
+# Linux CPU Scheduling on Android
+
+## Mechanism
+
+Android uses **EAS (Energy Aware Scheduling)**, which places tasks on the most energy-efficient CPU core that can meet the task's performance requirements. The scheduler balances performance against power consumption.
+
+### Core Topology
+
+Modern Android SoCs use heterogeneous CPU clusters:
+
+| Cluster | Cores | Characteristics |
+|---------|-------|----------------|
+| **Little** (efficiency) | 4 | Low frequency, low power, high efficiency |
+| **Medium** (balanced) | 2-3 | Mid frequency, moderate power |
+| **Big** (performance) | 1-2 | High frequency, high power |
+| **Prime** (peak) | 1 | Highest frequency, highest power |
+
+Higher-capacity cores run at higher frequencies and complete work faster, but consume more power and generate more heat.
+
+### Why Small-Core Placement Hurts
+
+When a latency-sensitive task (main thread, RenderThread) runs on a little core, it executes at a lower frequency. Work that takes 8ms on a big core might take 20ms on a little core, missing the frame deadline entirely. The scheduler may initially place the task on a little core because its load average appears low.
+
+### Frequency Governor Latency
+
+The CPU frequency governor adjusts core frequency based on load, but with a **2-10ms ramp-up delay** (depending on `rate_limit_us` and util history). A sudden burst of work (e.g., Choreographer#doFrame starting) runs at the previous low frequency for the first few milliseconds before the governor ramps up. This initial slow period can push the frame past its budget.
+
+### uclamp (Utilization Clamping)
+
+Android uses `uclamp.min` to hint the scheduler that certain threads need minimum performance. RenderThread and main thread typically get high uclamp values, requesting placement on faster cores. When uclamp is misconfigured or the system is under thermal constraints, these hints may be ignored.
+
+### uclamp.max
+
+`uclamp.max` 被 thermal governor / power_hal 用来**动态限制线程的最大频率**（不是全局限频）。当频率被限但 thermal_zone 温度不高时，可能是 uclamp.max 被调低了。这是 Android 12+ thermal mitigation 的关键机制。
+
+## Trace Signatures
+
+| What to Look For | Meaning |
+|-----------------|---------|
+| `sched_slice` table | Which CPU core ran each thread and for how long |
+| `cpu_frequency_counters` | Actual CPU frequency over time |
+| CPU ID in Q1/Q2 range (0-3 typically little) | Task running on efficiency cores |
+| Scheduling latency (Runnable duration) | Time between Runnable and Running state |
+
+**Scheduling latency thresholds**:
+- < 2ms: Normal
+- 2-5ms: Elevated (acceptable under load)
+- 5-15ms: Concerning -- CPU contention or priority issue
+- \> 15ms: Critical -- severe CPU starvation, likely thermal throttle or runaway process
+
+## Typical Solutions
+
+- Set appropriate thread priority: `SCHED_FIFO` or high nice value for critical rendering threads
+- Reduce background thread count to avoid CPU contention
+- Check thermal state: throttling forces tasks onto slower cores at lower frequencies
+- Use `Process.setThreadPriority()` for worker threads to yield to UI threads
+- Audit background services and jobs running during performance-critical operations
+- Verify uclamp settings for RenderThread and main thread via `thread_state` table
+
+### WALT vs PELT
+
+- **PELT (AOSP upstream)**: 指数加权移动平均，half-life ~32ms。util_avg 从 0 到 90% 稳态需 ~100ms。
+- **WALT (高通/MTK 定制)**: 基于窗口的 MAX 取值（通常 20ms 窗口），对突发负载响应更快（~10ms），但可能过度调度到大核。
+- **schedutil ramp-up**: 实际升频延迟约 2-10ms（取决于 rate_limit_us 和 util 历史），而非早期文献常引用的 10-30ms（那是旧版 interactive governor）。