flutter-devtools-mcp 0.3.1 → 0.3.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Dragan Bajic
+Copyright (c) 2026 treexi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -15,7 +15,8 @@ Connect AI agents to running Flutter apps for runtime inspection, profiling, and
 
 - Auto-discover and connect to running Flutter apps
 - Inspect widget tree and locate rebuild hotspots with source references
-- Run session-based performance collection (frames, CPU, memory, network)
+- Run session-based performance collection (frames, jank@16.67ms, rebuilds, hot functions Self>20ms, GC Top5, scroll FPS, image decode, isolate, network, memory)
+- Generate rule-engine `.ai.md` reports (runtime summary → findings → P0/P1/P2)
 - Save and compare memory snapshots
 - Execute debug actions (hot reload/restart, evaluate expression, screenshot)
 
@@ -24,27 +25,26 @@ Connect AI agents to running Flutter apps for runtime inspection, profiling, and
 ### Prerequisites
 
 - Node.js >= 18
-- A Flutter app running in `debug` or `profile` mode (recommended: `profile`)
+- A Flutter app running in `debug` or `profile` mode (recommended: `profile` for metrics; use `debug` when you need rebuild tracking)
 
-### Install and build
+### Install via npm (recommended)
+
+No local clone required:
 
 ```bash
-git clone https://github.com/draganbajic/flutter-devtools-mcp.git
-cd flutter-devtools-mcp
-npm install
-npm run build
+npx -y flutter-devtools-mcp
 ```
 
-### MCP config examples
+### MCP config (npx)
 
-#### Cursor (`.cursor/mcp.json`)
+#### Cursor (`.cursor/mcp.json` or Settings → MCP)
 
 ```json
 {
   "mcpServers": {
     "flutter-devtools": {
-      "command": "node",
-      "args": ["/path/to/flutter-devtools-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "flutter-devtools-mcp"]
     }
   }
 }
@@ -56,8 +56,8 @@ npm run build
 {
   "mcpServers": {
     "flutter-devtools": {
-      "command": "node",
-      "args": ["/path/to/flutter-devtools-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "flutter-devtools-mcp"]
     }
   }
 }
@@ -69,8 +69,8 @@ npm run build
 {
   "servers": {
     "flutter-devtools": {
-      "command": "node",
-      "args": ["/path/to/flutter-devtools-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "flutter-devtools-mcp"]
     }
   }
 }
@@ -78,12 +78,34 @@ npm run build
 
 #### CodeBuddy (`.codebuddy/mcp.json`)
 
+```json
+{
+  "mcpServers": {
+    "flutter-devtools": {
+      "command": "npx",
+      "args": ["-y", "flutter-devtools-mcp"]
+    }
+  }
+}
+```
+
+### Local build (optional)
+
+```bash
+git clone https://github.com/treexi/flutter-devtools-ext.git
+cd flutter-devtools-ext/flutter-devtools-mcp
+npm install
+npm run build
+```
+
+Then point MCP at the built entry:
+
 ```json
 {
   "mcpServers": {
     "flutter-devtools": {
       "command": "node",
-      "args": ["/path/to/flutter-devtools-mcp/dist/index.js"]
+      "args": ["/absolute/path/to/flutter-devtools-mcp/dist/index.js"]
     }
   }
 }
@@ -95,6 +117,7 @@ Start your app:
 
 ```bash
 flutter run --profile
+# or: flutter run --debug   # needed for rebuild tracking
 ```
 
 Then ask your AI assistant:
@@ -103,7 +126,7 @@ Then ask your AI assistant:
 Connect Flutter app, collect performance data for 30s (scenario: home feed scroll), and provide optimization suggestions based on code.
 ```
 
-The AI calls `collect_performance_session` (blocking for 30s), then reads `filesToInspect` and returns P0/P1/P2 suggestions.
+The AI calls `collect_performance_session` (blocking for ~30s), then reads `filesToInspect` and returns P0/P1/P2 suggestions.
 
 Design docs:
 
@@ -112,25 +135,12 @@ Design docs:
 - Doc index: [`docs/README.md`](docs/README.md)
 - Image URL sample: [`examples/app_network_image_README.md`](examples/app_network_image_README.md)
 
-## 4) Regression Commands
-
-```bash
-# Android debug regression
-npm run test:regression:android
-
-# Android profile regression (default duration)
-npm run test:regression:android:profile
-
-# Android profile regression (30s)
-npm run test:regression:android:profile:30s
-```
-
-## 5) Tool List (22)
+## 4) Tool List (22)
 
 ### Performance Session
 | Tool | Description |
 |------|-------------|
-| `collect_performance_session` | Block for N seconds (default 30), return JSON with frames/rebuilds/CPU/memory/network |
+| `collect_performance_session` | Block for N seconds (default 30), return JSON + `.ai.md`: frames/jank, rebuilds (debug), hot functions (Self>20ms), GC Top5, scroll FPS, image decode, isolate, memory, network |
 
 ### Discovery & Connection
 | Tool | Description |
@@ -181,14 +191,35 @@ npm run test:regression:android:profile:30s
 | `toggle_debug_paint` | Toggle debug paint |
 | `evaluate_expression` | Evaluate Dart expression |
 
-## 6) Recommendations and Limitations
+## 5) Recommendations and Limitations
 
 - Prefer `profile` mode for accurate performance metrics: `flutter run --profile`
-- `debug` mode adds overhead; use it for trend checks only
+- `debug` mode adds overhead; use it for trend checks and **rebuild tracking**
 - Rebuild tracking extension is unavailable in `profile` mode (auto-degraded)
-- Network capture depends on `dart:io` `HttpClient` timeline events
-- `projectTopFunctions` tracks app `lib/` methods; hit rate can be low on Android profile. Use 30~60s collection and active interactions
-- To attribute image decode to a **URL**, use the shared loader sample: [`examples/app_network_image.dart`](./examples/app_network_image.dart) (see [`examples/app_network_image_README.md`](./examples/app_network_image_README.md))
+- Network capture depends on `dart:io` `HttpClient` timeline events (and HttpProfile when available)
+- Hot functions (`projectTopFunctions`) track app `lib/` methods; on Android profile hit rate can be low — use 30~60s and keep interacting
+- Jank budget is fixed at **16.67ms** (60 FPS)
+- To attribute image decode to a **URL + ms**, use the shared loader sample: [`examples/app_network_image.dart`](./examples/app_network_image.dart) (writes `args.ms`)
+
+## 6) Publish (GitHub Actions → npm)
+
+1. Repo Settings → Secrets → Actions: create **`NPM_TOKEN`**
+   - [npm Access Tokens](https://www.npmjs.com/settings/~/tokens) → **Granular Access Token**
+   - Packages: Read and write
+   - Enable **Bypass two-factor authentication** (required for CI)
+   - Prefer enabling 2FA on the npm account first
+2. Bump & tag:
+
+```bash
+cd flutter-devtools-mcp
+npm version patch
+git push origin main --tags
+```
+
+3. GitHub → Releases → publish the tag (e.g. `v0.3.1`), or run workflow **Publish npm** manually.  
+   Workflow: [`.github/workflows/publish-npm.yml`](../.github/workflows/publish-npm.yml)
+
+Tag version (without `v`) must match `package.json` `version`.
 
 ## 7) Roadmap
 
@@ -197,12 +228,13 @@ npm run test:regression:android:profile:30s
 - [x] Network traffic inspection
 - [x] Before/after snapshot comparison
 - [x] Session-based performance collection (`collect_performance_session`)
-- [ ] Continuous monitoring mode (real-time jank watcher)
+- [x] npm publish for `npx flutter-devtools-mcp`
+- [ ] Continuous monitoring mode
 - [ ] Integration test runner with performance baselines
 - [ ] Shader compilation jank detection
-- [ ] npm publish for `npx flutter-devtools-mcp`
 
 ## 8) License
 
 MIT
 
+Flutter and Dart are trademarks of Google LLC. This project is an independent, unofficial tool that talks to apps over the Dart VM Service; it is not affiliated with, endorsed by, or part of Google or the official Flutter DevTools.

package/README.zh-CN.md

@@ -15,97 +15,101 @@
 
 - 自动发现并连接 Flutter 进程（无需手抄 VM URI）
 - 查看 Widget 树、定位重建热点（含源码位置）
-- 采集性能会话（帧、CPU、内存、网络）并输出结构化结果
+- 采集性能会话（帧、jank@16.67ms、重建、耗时函数 Self>20ms、GC Top5、滚动 FPS、图片解码、Isolate、网络、内存）
+- 生成规则引擎 `.ai.md` 报告（运行时摘要 → 问题清单 → P0/P1/P2）
 - 做快照对比（内存前后变化）
 - 执行调试动作（hot reload/restart、表达式求值、截图等）
 
-
-
 ## 2. 快速开始
 
-
-
 ### 2.1 前置条件
 
 - Node.js >= 18
-- Flutter App 运行在 `debug` 或 `profile` 模式（建议 `profile`）
-
+- Flutter App 运行在 `debug` 或 `profile` 模式（指标建议 `profile`；需要重建追踪用 `debug`）
 
+### 2.2 用 npm 安装（推荐）
 
-### 2.2 安装与构建
+无需本地 clone / build：
 
 ```bash
-git clone https://github.com/draganbajic/flutter-devtools-mcp.git
-cd flutter-devtools-mcp
-npm install
-npm run build
+npx -y flutter-devtools-mcp
 ```
 
+### 2.3 MCP 配置（npx）
 
-
-### 2.3 MCP 配置
-
-
-
-#### Cursor (`.cursor/mcp.json`)
+#### Cursor（`.cursor/mcp.json` 或 Settings → MCP）
 
 ```json
 {
   "mcpServers": {
     "flutter-devtools": {
-      "command": "node",
-      "args": ["/path/to/flutter-devtools-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "flutter-devtools-mcp"]
     }
   }
 }
 ```
 
-
-
 #### Claude Desktop (`claude_desktop_config.json`)
 
 ```json
 {
   "mcpServers": {
     "flutter-devtools": {
-      "command": "node",
-      "args": ["/path/to/flutter-devtools-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "flutter-devtools-mcp"]
     }
   }
 }
 ```
 
-
-
 #### VS Code / Copilot (`.vscode/mcp.json`)
 
 ```json
 {
   "servers": {
     "flutter-devtools": {
-      "command": "node",
-      "args": ["/path/to/flutter-devtools-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "flutter-devtools-mcp"]
     }
   }
 }
 ```
 
-
-
 #### CodeBuddy (`.codebuddy/mcp.json`)
 
 ```json
 {
   "mcpServers": {
     "flutter-devtools": {
-      "command": "node",
-      "args": ["/path/to/flutter-devtools-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "flutter-devtools-mcp"]
     }
   }
 }
 ```
 
+### 2.4 本地构建（可选）
 
+```bash
+git clone https://github.com/treexi/flutter-devtools-ext.git
+cd flutter-devtools-ext/flutter-devtools-mcp
+npm install
+npm run build
+```
+
+然后 MCP 指向：
+
+```json
+{
+  "mcpServers": {
+    "flutter-devtools": {
+      "command": "node",
+      "args": ["/absolute/path/to/flutter-devtools-mcp/dist/index.js"]
+    }
+  }
+}
+```
 
 ## 3. 推荐主流程：30s 性能会话
 
@@ -113,6 +117,7 @@ npm run build
 
 ```bash
 flutter run --profile
+# 或：flutter run --debug   # 需要重建追踪时
 ```
 
 然后在 AI 中直接说：
@@ -121,140 +126,99 @@ flutter run --profile
 连接 Flutter App，开始采集性能数据 30s，场景：首页滚动，结合代码给优化方案
 ```
 
-AI 会调用 `collect_performance_session`（阻塞 30s）并返回结构化结果，随后结合 `filesToInspect` 源码给出 P0/P1/P2 优化建议。
+AI 会调用 `collect_performance_session`（阻塞约 30s）并返回结构化结果，随后结合 `filesToInspect` 源码给出 P0/P1/P2 优化建议。
 
 **文档：**
 
-- 指标怎么读（GC / 重建 / 图片解码等）：`[docs/performance-metrics-guide.md](docs/performance-metrics-guide.md)`
-- 产品与数据结构：`[docs/performance-session-simple-design.md](docs/performance-session-simple-design.md)`
-- 文档索引：`[docs/README.md](docs/README.md)`
-- 图片 URL 埋点样板：`[examples/app_network_image_README.md](examples/app_network_image_README.md)`
-
+- 指标怎么读：[`docs/performance-metrics-guide.md`](docs/performance-metrics-guide.md)
+- 产品与数据结构：[`docs/performance-session-simple-design.md`](docs/performance-session-simple-design.md)
+- 文档索引：[`docs/README.md`](docs/README.md)
+- 图片 URL 埋点样板：[`examples/app_network_image_README.md`](examples/app_network_image_README.md)
 
+## 4. Demo App
 
-## 4. 回归命令
+仓库内 [`../flutter-simple`](../flutter-simple) 是带故意性能问题的 Demo（高频 setState、网络图、后台 isolate）。
 
 ```bash
-# Android debug 回归
-npm run test:regression:android
-
-# Android profile 回归（默认时长）
-npm run test:regression:android:profile
-
-# Android profile 回归（30s）
-npm run test:regression:android:profile:30s
+cd ../flutter-simple
+flutter run --debug -d <device>
 ```
 
-
+然后用 MCP `collect_performance_session` 采集即可。
 
 ## 5. 工具清单（22）
 
-
-
 ### Performance Session
 
-
-| Tool                          | Description                                                                                                   |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `collect_performance_session` | 阻塞采集 N 秒（默认 30），返回 JSON：帧/jank、耗时函数（Self>20ms 异常）、重建（debug）、GC、滚动FPS、图片解码、Isolate、内存、网络；并生成带「开发者结论」的 `.ai.md` |
-
-
-
+| Tool | Description |
+|------|-------------|
+| `collect_performance_session` | 阻塞采集 N 秒（默认 30），返回 JSON + `.ai.md`：帧/jank、重建（debug）、耗时函数（Self>20ms）、GC Top5、滚动 FPS、图片解码、Isolate、内存、网络 |
 
 ### Discovery & Connection
 
-
-| Tool            | Description                 |
-| --------------- | --------------------------- |
-| `discover_apps` | 自动发现并连接运行中的 Flutter App     |
-| `connect`       | 通过 VM Service URI 手动连接      |
-| `disconnect`    | 断开连接                        |
-| `get_app_info`  | 获取 VM / isolate / 平台信息与扩展能力 |
-
-
-
+| Tool | Description |
+|------|-------------|
+| `discover_apps` | 自动发现并连接运行中的 Flutter App |
+| `connect` | 通过 VM Service URI 手动连接 |
+| `disconnect` | 断开连接 |
+| `get_app_info` | 获取 VM / isolate / 平台信息与扩展能力 |
 
 ### Widget Inspection
 
-
-| Tool              | Description                 |
-| ----------------- | --------------------------- |
-| `get_widget_tree` | 获取 Widget 层级（含源码位置与项目过滤）    |
-| `inspect_widget`  | 深度查看 widget 属性/约束/render 信息 |
-
-
-
+| Tool | Description |
+|------|-------------|
+| `get_widget_tree` | 获取 Widget 层级（含源码位置与项目过滤） |
+| `inspect_widget` | 深度查看 widget 属性/约束/render 信息 |
 
 ### Rebuild Tracking
 
-
-| Tool                      | Description        |
-| ------------------------- | ------------------ |
-| `start_tracking_rebuilds` | 开始追踪重建             |
-| `stop_tracking_rebuilds`  | 输出重建报告（次数、源码位置、建议） |
-
-
-
+| Tool | Description |
+|------|-------------|
+| `start_tracking_rebuilds` | 开始追踪重建 |
+| `stop_tracking_rebuilds` | 输出重建报告（次数、源码位置、建议） |
 
 ### Performance Profiling
 
-
-| Tool              | Description                            |
-| ----------------- | -------------------------------------- |
-| `start_profiling` | 开始 timeline profiling                  |
-| `stop_profiling`  | 输出帧、jank、hotspot、build/layout/paint 分析 |
-
-
-
+| Tool | Description |
+|------|-------------|
+| `start_profiling` | 开始 timeline profiling |
+| `stop_profiling` | 输出帧、jank、hotspot、build/layout/paint 分析 |
 
 ### Memory Analysis
 
-
-| Tool                  | Description      |
-| --------------------- | ---------------- |
+| Tool | Description |
+|------|-------------|
 | `get_memory_snapshot` | 获取堆快照（含类分布、疑似异常） |
-| `save_snapshot`       | 保存命名快照           |
-| `compare_snapshots`   | 对比两个快照差异         |
-| `list_snapshots`      | 列出所有快照           |
-
-
-
+| `save_snapshot` | 保存命名快照 |
+| `compare_snapshots` | 对比两个快照差异 |
+| `list_snapshots` | 列出所有快照 |
 
 ### Network
 
-
-| Tool                    | Description            |
-| ----------------------- | ---------------------- |
-| `start_network_capture` | 开始抓取 HTTP 流量           |
-| `stop_network_capture`  | 输出 URL、状态码、耗时、体积、错误等统计 |
-
-
-
+| Tool | Description |
+|------|-------------|
+| `start_network_capture` | 开始抓取 HTTP 流量 |
+| `stop_network_capture` | 输出 URL、状态码、耗时、体积、错误等统计 |
 
 ### Debug Actions
 
-
-| Tool                  | Description    |
-| --------------------- | -------------- |
-| `hot_reload`          | 触发 Hot Reload  |
-| `hot_restart`         | 触发 Hot Restart |
-| `take_screenshot`     | 截图             |
-| `toggle_debug_paint`  | 切换 Debug Paint |
-| `evaluate_expression` | 执行 Dart 表达式    |
-
-
-
+| Tool | Description |
+|------|-------------|
+| `hot_reload` | 触发 Hot Reload |
+| `hot_restart` | 触发 Hot Restart |
+| `take_screenshot` | 截图 |
+| `toggle_debug_paint` | 切换 Debug Paint |
+| `evaluate_expression` | 执行 Dart 表达式 |
 
 ## 6. 使用建议与限制
 
 - 推荐在 `profile` 模式采集性能数据：`flutter run --profile`
-- `debug` 有额外检查开销，性能数据仅供趋势参考
+- `debug` 有额外检查开销；需要 **重建追踪** 时用 debug
 - `profile` 下不支持 Widget 重建追踪扩展（会自动降级）
-- 网络采集基于 `dart:io` `HttpClient` timeline 事件，部分第三方实现可能无法完整采集
-- `projectTopFunctions` 为业务 `lib/` 方法列表，Android profile 下命中率可能偏低，建议 30~60s 并持续业务交互
-- 图片解码若要带 **URL/尺寸**，请业务侧使用统一入口样板：`[examples/app_network_image.dart](./examples/app_network_image.dart)`（说明见 `[examples/app_network_image_README.md](./examples/app_network_image_README.md)`）
-
-
+- 网络采集基于 `dart:io` `HttpClient` / HttpProfile，部分封装可能不完整
+- 耗时函数（`projectTopFunctions`）为业务 `lib/` 方法；Android profile 下命中率可能偏低，建议 30~60s 并持续操作
+- 掉帧预算固定 **16.67ms**（60FPS）
+- 图片解码若要带 **URL + ms**，请用统一入口样板：[`examples/app_network_image.dart`](./examples/app_network_image.dart)（写入 `args.ms`）
 
 ## 7. 路线图
 
@@ -263,30 +227,34 @@ npm run test:regression:android:profile:30s
 - [x] 支持网络流量检查
 - [x] 支持前后快照对比
 - [x] 支持会话式性能采集（`collect_performance_session`）
+- [x] 发布到 npm（支持 `npx flutter-devtools-mcp`）
 - [ ] 持续监控模式（实时卡顿监视）
 - [ ] 集成测试运行器（含性能基线对比）
 - [ ] Shader 编译卡顿检测
-- [x] 发布到 npm（支持 `npx flutter-devtools-mcp`）
-
-
 
 ## 8. 发版（GitHub Actions → npm）
 
-1. 仓库 Settings → Secrets and variables → Actions，新增 **`NPM_TOKEN`**（[npm Access Tokens](https://www.npmjs.com/settings/~/tokens) 选 Automation）
+1. 仓库 Settings → Secrets and variables → Actions，新增 **`NPM_TOKEN`**
+   - 打开 [npm Access Tokens](https://www.npmjs.com/settings/~/tokens)
+   - 账号建议先开 [2FA](https://www.npmjs.com/settings/~/account/security)（Authorization and writing）
+   - 创建 **Granular Access Token**：Packages **Read and write**，勾选 **Bypass two-factor authentication**（CI 必须）
+   - Secret 名必须是 `NPM_TOKEN`
 2. 改版本并提交：
    ```bash
    cd flutter-devtools-mcp
-   npm version patch   # 0.3.0 → 0.3.1，会改 package.json 并打 git tag
+   npm version patch   # 例如 0.3.1 → 0.3.2
    git push origin main --tags
    ```
-3. GitHub → **Releases** → Draft a new release，Tag 选刚推的 `v0.3.1` → Publish  
-   → 自动跑 [`.github/workflows/publish-npm.yml`](../.github/workflows/publish-npm.yml) 发布到 npmjs.com  
-   也可在 Actions 里对 **Publish npm** 点 Run workflow 手动触发。
-
-> Tag 版本（去掉前缀 `v`）必须与 `package.json` 的 `version` 一致。
-
+3. GitHub → **Releases** → 用对应 tag（如 `v0.3.2`）发布  
+   → 自动跑 [`.github/workflows/publish-npm.yml`](../.github/workflows/publish-npm.yml)  
+   或在 Actions 里对 **Publish npm** 手动 Run workflow
 
+> `ENEEDAUTH`：未配置 / 空的 `NPM_TOKEN`  
+> `403 … bypass 2fa`：请按上面重建 **Granular + Bypass 2FA** token  
+> Tag（去掉 `v`）必须与 `package.json` 的 `version` 一致
 
 ## 9. License
 
-MIT
+MIT
+
+Flutter / Dart 为 Google LLC 商标。本项目为独立的非官方工具，通过 Dart VM Service 连接运行中的 App，与 Google 或官方 Flutter DevTools **无隶属或背书关系**。

package/docs/README.md

@@ -6,4 +6,4 @@
 | [performance-session-simple-design.md](./performance-session-simple-design.md) | 产品 / 实现 | `collect_performance_session` 交互、参数、数据结构 |
 | [performance-audit-requirements.md](./performance-audit-requirements.md) | 规划 | 重型 MD/HTML 审计（P2，非当前主路径） |
 | [../examples/app_network_image_README.md](../examples/app_network_image_README.md) | 业务接入 | 统一图片入口，解码带 URL |
-| [../README.zh-CN.md](../README.zh-CN.md) | 全员 | 安装、快速开始、工具表、回归命令 |
+| [../README.zh-CN.md](../README.zh-CN.md) | 全员 | 安装（npx）、快速开始、工具表、发版 |

package/docs/performance-metrics-guide.md

@@ -9,7 +9,7 @@
 ## 1. 推荐用法（两分钟）
 
 ```bash
-# 1) 性能主采（帧 / 业务CPU / GC / 图片解码更准）
+# 1) 性能主采（帧 / 耗时函数 / GC / 图片解码更准）
 flutter run --profile
 
 # 2) AI 对话
@@ -56,7 +56,7 @@ flutter run --profile
 | **滚动段 FPS / 段 jank** | 2s 窗口分段 | 滑动 <50FPS 或段 jank 高 | 列表滑动卡顿 |
 | **Build / Layout / Paint max** | Timeline 阶段 | 单阶段经常 >8～16ms | 卡在 build / 布局 / 绘制哪一段 |
 
-**限制**：Android profile 下 Timeline 帧事件偶发偏少 → 摘要可能 ⚪无数据，此时以 **业务CPU / 图片解码** 为准。
+**限制**：Android profile 下 Timeline 帧事件偶发偏少 → 摘要可能 ⚪无数据，此时以 **耗时函数 / 图片解码** 为准。
 
 ### 3.2 归因：卡在哪
 
@@ -64,7 +64,7 @@ flutter run --profile
 |------|------|------------|------|
 | **耗时函数 Top（lib/）** | VM `getCpuSamples` + 路径过滤；**Self >20ms → 🔴异常** | 哪个业务方法占时间 | 比框架 `drawFrame` 有用；框架热点不进开发者结论 |
 | **Widget 重建 Top** | inspector 扩展 | 哪个组件重建过多、文件:行号 | **仅 debug**；profile 固定 ⚪无数据 |
-| **filesToInspect** | 重建 + 业务CPU 文件 | 该打开哪些源码 | AI/人工优先读这些文件 |
+| **filesToInspect** | 重建 + 耗时函数 文件 | 该打开哪些源码 | AI/人工优先读这些文件 |
 
 ### 3.3 尖刺：偶发卡一下
 
@@ -102,7 +102,7 @@ flutter run --profile
 **能发现：**
 
 1. **卡顿尖刺来自 GC**：最长经常 >16～32ms，或 >8ms 很多次  
-2. **分配偏勤（间接）**：次数极高 → 短命对象多（临时 List、字符串、闭包、解码缓冲）；需结合业务CPU/重建  
+2. **分配偏勤（间接）**：次数极高 → 短命对象多（临时 List、字符串、闭包、解码缓冲）；需结合耗时函数/重建  
 3. **交叉验证**：与 setState / 热循环 / 大图同时出现时，GC 高往往是副作用  
 
 **发现不了：**
@@ -131,7 +131,8 @@ flutter run --profile
 **推荐**：全站网络图走统一入口 [`AppNetworkImage`](../examples/app_network_image.dart)：
 
 - Timeline 事件名：`app.imageDecode`
-- arguments：`url`（必填），`width` / `height` / `bytes`（可选）
+- arguments：`url`（必填），**`ms`（必填，Stopwatch 耗时）**，`width` / `height` / `bytes`（可选）
+- 跨 `await` 时 B/E 常丢时长，样板用 instant + `args.ms`；MCP 优先读该字段
 
 报告示例：
 
@@ -162,11 +163,12 @@ flutter run --profile
 
 ---
 
-## 7. 业务 CPU 为什么曾为空 / 怎么读
+## 7. 耗时函数为什么曾为空 / 怎么读
 
 - 过滤规则：业务 `lib/` / `package:<app>/`，排除 Flutter SDK、`dart:ui` 等误归一路径  
 - Android profile 下 Self 时间常落在框架叶子；业务方法靠采样 + 路径/符号命中  
 - Demo 可用 `Timeline` / `@pragma('vm:never-inline')` 提高命中率  
+- **Self >20ms → 报告标 🔴异常**  
 - **看 `projectTopFunctions`，不要看框架 `topFunctions` 当根因**
 
 ---
@@ -176,7 +178,7 @@ flutter run --profile
 ```text
 1. 开发者结论里的 P0
 2. 🔴 行：图片解码（带 URL）/ 高 jank / 滚动最差段
-3. 业务CPU Top → 打开 filesToInspect
+3. 耗时函数 Top → 打开 filesToInspect
 4. 🟡 GC / 内存 → 当旁证，回到分配与重建
 5. debug 补采重建（若怀疑 setState 风暴）
 ```
@@ -190,18 +192,6 @@ flutter run --profile
 | [performance-session-simple-design.md](./performance-session-simple-design.md) | 产品形态、工具参数、数据结构、AI 话术 |
 | [performance-audit-requirements.md](./performance-audit-requirements.md) | 重型 MD/HTML 审计（P2 规划，非当前主路径） |
 | [../examples/app_network_image_README.md](../examples/app_network_image_README.md) | 图片统一入口接入 |
-| [../README.zh-CN.md](../README.zh-CN.md) | 安装、回归命令、工具清单 |
-
----
-
-## 10. 回归
-
-```bash
-cd flutter-devtools-mcp
-npm run build
-npm run test:regression:android:profile
-# 或 30s：
-npm run test:regression:android:profile:30s
-```
+| [../README.zh-CN.md](../README.zh-CN.md) | 安装、MCP 配置（npx）、工具清单、发版 |
 
 报告默认落在 Flutter 工程下：`performance-sessions/*.json` + `*.ai.md`。

package/docs/performance-session-simple-design.md

@@ -1,6 +1,6 @@
-# Flutter 性能采集会话 — 方案设计（两轮对话）
+# Flutter 性能采集会话 — 方案设计
 
-> **产品形态**：用户用两句话完成一次采集；MCP 负责采数据；AI 负责结合代码出优化方案。  
+> **产品形态**：用户一句话完成一次采集；MCP 负责采数据；AI 负责结合代码出优化方案。  
 > **优先级**：本方案为 P0；[`performance-audit-requirements.md`](./performance-audit-requirements.md) 中的重型报告降为 P2 可选。  
 > **指标怎么读（开发者）**：见 [`performance-metrics-guide.md`](./performance-metrics-guide.md)。
 
@@ -61,9 +61,9 @@ sequenceDiagram
 
 | 角色 | 职责 | 不做 |
 |------|------|------|
-| **你** | `flutter run --profile`；两轮对话；App 内操作 30s | 不调 MCP 工具名 |
-| **MCP** | 连接 VM；并行采集；`stop` 时输出结构化 JSON | 不调 LLM；不读源码 |
-| **AI** | 解析人话 → 调工具；`stop` 后读代码 → 写优化方案 | 不代替你在 App 里操作 |
+| **你** | `flutter run`；一句话触发采集；App 内操作约 30s | 不调 MCP 工具名 |
+| **MCP** | 连接 VM；并行采集；时长到后输出结构化 JSON + `.ai.md` | 不调 LLM；不读源码 |
+| **AI** | 解析人话 → 调工具；返回后读代码 → 写优化方案 | 不代替你在 App 里操作 |
 
 ---
 
@@ -84,7 +84,7 @@ AI **必须依次**：
 
 ## 5. MCP 工具设计
 
-### 5.1 沿用现有（第一轮会用到）
+### 5.1 连接类（采集前）
 
 | 工具 | 用途 |
 |------|------|
@@ -337,10 +337,11 @@ interface PerformanceSessionResult {
 ## 9. 前置条件
 
 ```bash
-# 终端 1：启动 App（推荐 profile）
+# 终端：启动 App（推荐 profile；需要重建追踪用 debug）
 flutter run --profile
 
-# Cursor：配置 MCP 指向 dist/index.js
+# Cursor / Claude：MCP 用 npx（见 README.zh-CN §2.3）
+# command: npx , args: ["-y", "flutter-devtools-mcp"]
 # 工作区：打开 Flutter 项目根目录（AI 才能读 lib/）
 ```
 
@@ -351,37 +352,18 @@ flutter run --profile
 | 情况 | AI 回复要点 |
 |------|-------------|
 | 未发现 App | 提示先 `flutter run`，或粘贴 VM URI |
-| 重复 start | 先说「已在采集中」，或先 stop 再 start |
-| 未 start 就 stop | 提示先执行第一轮话术 |
-| 采集 < 5s | 警告数据可能不足，建议重新采 30s |
+| 采集时长过短 | 警告数据可能不足，建议重新采 30s |
 | 网络为空 | 说明可能未走 dart:io，其他维度仍给方案 |
+| profile 无重建 | 说明平台限制，需要时 debug 补采 |
 
 ---
 
 ## 11. 验收标准
 
-1. 第一轮话术后，MCP 返回「已开始采集」
-2. 操作 30s 后第二轮话术，`stop` 返回合法 JSON
-3. JSON 含 `topRebuilds[].line`、`topFunctions[].file`、`hintsForAnalysis`
-4. AI 能根据 `filesToInspect` 打开对应 dart 文件并输出 P0/P1 方案
-5. 原有 21 个工具行为不变
-
----
-
-## 13. 回归命令（当前）
-
-```bash
-# Android debug 回归
-npm run test:regression:android
-
-# Android profile 回归（默认时长）
-npm run test:regression:android:profile
-
-# Android profile 回归（30s）
-npm run test:regression:android:profile:30s
-```
-
-> 说明：profile 模式不支持 Widget 重建追踪；帧数偶发偏低时，以 `vm-samples` + 网络 + AI 规则分析为准。
+1. 一句话术后，`collect_performance_session` 阻塞约 30s 并返回合法 JSON + `.ai.md`
+2. JSON 含运行时摘要字段、`filesToInspect`、`projectTopFunctions`（耗时函数）等
+3. AI 能根据 `filesToInspect` 打开对应 dart 文件并输出 P0/P1 方案
+4. 原有独立工具行为不变（加上会话工具共 22 个）
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "flutter-devtools-mcp",
-  "version": "0.3.1",
-  "description": "MCP server that connects AI agents to Flutter DevTools for runtime inspection, profiling, and debugging of Flutter applications",
+  "version": "0.3.2",
+  "description": "MCP server that connects AI agents to running Flutter apps via the Dart VM Service for runtime inspection, profiling, and debugging",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -20,12 +20,6 @@
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
     "prepublishOnly": "npm run build",
-    "test:regression": "node scripts/regression-performance-session.mjs",
-    "test:regression:spawn": "node scripts/regression-performance-session.mjs --spawn",
-    "test:regression:android": "FLUTTER_DEVICE=android node scripts/regression-performance-session.mjs --spawn",
-    "test:regression:android:profile": "FLUTTER_DEVICE=android FLUTTER_RUN_MODE=profile node scripts/regression-performance-session.mjs --spawn",
-    "test:regression:android:profile:30s": "FLUTTER_DEVICE=android FLUTTER_RUN_MODE=profile REGRESSION_DURATION_SEC=30 node scripts/regression-performance-session.mjs --spawn",
-    "test:regression:ios": "FLUTTER_DEVICE=ios node scripts/regression-performance-session.mjs --spawn",
     "prepare": "npm run build"
   },
   "keywords": [