flutter-devtools-mcp 0.3.1

package/examples/app_network_image.dart

@@ -0,0 +1,242 @@
+import 'dart:async';
+import 'dart:developer' as developer;
+import 'dart:io';
+import 'dart:typed_data';
+import 'dart:ui' as ui;
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+
+/// 业务侧「一处侵入」样板：统一网络图入口，供 flutter-devtools-mcp 采集
+/// `imageDecode` 时带上 url / 尺寸 / 字节数。
+///
+/// ## 接入步骤
+/// 1. 复制本文件到业务工程（如 `lib/widgets/app_network_image.dart`）
+/// 2. 全站网络图改用 [AppNetworkImage]，禁止业务直接 `Image.network`
+/// 3. 大图预加载/强制解码走 [AppImageLoader.loadAndDecode]
+///
+/// ## Timeline 约定（MCP 已识别）
+/// - 事件名：`app.imageDecode`
+/// - arguments：`url`（必填）、`ms`（必填，Stopwatch 耗时）、`width`/`height`/`bytes`（可选）
+///
+/// 复制到业务后可按需换成 Dio / cached_network_image，只要保留 Timeline 字段即可。
+class AppImageLoader {
+  AppImageLoader._();
+
+  static const String timelineEvent = 'app.imageDecode';
+
+  /// 下载并解码；耗时与元数据写入 Timeline，便于性能报告点名 URL。
+  ///
+  /// 注意：跨 await 时 Timeline B/E 时常采不到时长，因此用 Stopwatch
+  /// 在结束 instant 里写入 `ms`，供 MCP 解析。
+  static Future<ui.Image> loadAndDecode(
+    String url, {
+    int? cacheWidth,
+    int? cacheHeight,
+  }) async {
+    final sw = Stopwatch()..start();
+    try {
+      final bytes = await _downloadBytes(url);
+      final codec = await ui.instantiateImageCodec(
+        bytes,
+        targetWidth: cacheWidth,
+        targetHeight: cacheHeight,
+      );
+      final frame = await codec.getNextFrame();
+      return frame.image;
+    } finally {
+      sw.stop();
+      developer.Timeline.instantSync(
+        timelineEvent,
+        arguments: <Object, Object>{
+          'url': url,
+          'ms': sw.elapsedMilliseconds,
+          if (cacheWidth != null) 'width': cacheWidth,
+          if (cacheHeight != null) 'height': cacheHeight,
+        },
+      );
+    }
+  }
+
+  static Future<Uint8List> _downloadBytes(String url) async {
+    final client = HttpClient();
+    try {
+      final req = await client.getUrl(Uri.parse(url));
+      final res = await req.close();
+      if (res.statusCode < 200 || res.statusCode >= 300) {
+        throw HttpException('HTTP ${res.statusCode}', uri: Uri.parse(url));
+      }
+      final builder = BytesBuilder(copy: false);
+      await for (final chunk in res) {
+        builder.add(chunk);
+      }
+      return builder.takeBytes();
+    } finally {
+      client.close(force: true);
+    }
+  }
+}
+
+/// 带 Timeline 埋点的 [ImageProvider]，供 [AppNetworkImage] 使用。
+class AppNetworkImageProvider extends ImageProvider<AppNetworkImageProvider> {
+  const AppNetworkImageProvider(
+    this.url, {
+    this.cacheWidth,
+    this.cacheHeight,
+    this.scale = 1.0,
+  });
+
+  final String url;
+  final int? cacheWidth;
+  final int? cacheHeight;
+  final double scale;
+
+  @override
+  Future<AppNetworkImageProvider> obtainKey(ImageConfiguration configuration) {
+    return SynchronousFuture<AppNetworkImageProvider>(this);
+  }
+
+  @override
+  ImageStreamCompleter loadImage(
+    AppNetworkImageProvider key,
+    ImageDecoderCallback decode,
+  ) {
+    final chunkEvents = StreamController<ImageChunkEvent>();
+    return MultiFrameImageStreamCompleter(
+      codec: _loadAsync(key, chunkEvents, decode),
+      scale: key.scale,
+      chunkEvents: chunkEvents.stream,
+      informationCollector: () => <DiagnosticsNode>[
+        DiagnosticsProperty<ImageProvider>('Image provider', this),
+        DiagnosticsProperty<String>('URL', url),
+      ],
+    );
+  }
+
+  Future<ui.Codec> _loadAsync(
+    AppNetworkImageProvider key,
+    StreamController<ImageChunkEvent> chunkEvents,
+    ImageDecoderCallback decode,
+  ) async {
+    final sw = Stopwatch()..start();
+    try {
+      final bytes = await AppImageLoader._downloadBytes(key.url);
+      chunkEvents.add(
+        ImageChunkEvent(
+          cumulativeBytesLoaded: bytes.length,
+          expectedTotalBytes: bytes.length,
+        ),
+      );
+      final buffer = await ui.ImmutableBuffer.fromUint8List(bytes);
+      return decode(
+        buffer,
+        getTargetSize: (intrinsicWidth, intrinsicHeight) {
+          return ui.TargetImageSize(
+            width: key.cacheWidth,
+            height: key.cacheHeight,
+          );
+        },
+      );
+    } catch (e, st) {
+      scheduleMicrotask(() {
+        chunkEvents.addError(e, st);
+      });
+      rethrow;
+    } finally {
+      sw.stop();
+      developer.Timeline.instantSync(
+        AppImageLoader.timelineEvent,
+        arguments: <Object, Object>{
+          'url': key.url,
+          'ms': sw.elapsedMilliseconds,
+          if (key.cacheWidth != null) 'width': key.cacheWidth!,
+          if (key.cacheHeight != null) 'height': key.cacheHeight!,
+        },
+      );
+      await chunkEvents.close();
+    }
+  }
+
+  @override
+  bool operator ==(Object other) {
+    if (other.runtimeType != runtimeType) return false;
+    return other is AppNetworkImageProvider &&
+        other.url == url &&
+        other.cacheWidth == cacheWidth &&
+        other.cacheHeight == cacheHeight &&
+        other.scale == scale;
+  }
+
+  @override
+  int get hashCode => Object.hash(url, cacheWidth, cacheHeight, scale);
+
+  @override
+  String toString() =>
+      '${objectRuntimeType(this, 'AppNetworkImageProvider')}("$url")';
+}
+
+/// 业务推荐使用的网络图组件（替代裸 [Image.network]）。
+class AppNetworkImage extends StatelessWidget {
+  const AppNetworkImage({
+    super.key,
+    required this.url,
+    this.width,
+    this.height,
+    this.fit = BoxFit.cover,
+    this.cacheWidth,
+    this.cacheHeight,
+    this.errorBuilder,
+    this.placeholder,
+  });
+
+  final String url;
+  final double? width;
+  final double? height;
+  final BoxFit fit;
+
+  /// 解码目标宽高（逻辑像素×devicePixelRatio 由调用方换算，或直接传展示像素）
+  final int? cacheWidth;
+  final int? cacheHeight;
+
+  final ImageErrorWidgetBuilder? errorBuilder;
+  final Widget? placeholder;
+
+  @override
+  Widget build(BuildContext context) {
+    final dpr = MediaQuery.devicePixelRatioOf(context);
+    final tw = cacheWidth ??
+        (width != null ? (width! * dpr).round() : null);
+    final th = cacheHeight ??
+        (height != null ? (height! * dpr).round() : null);
+
+    return Image(
+      image: AppNetworkImageProvider(url, cacheWidth: tw, cacheHeight: th),
+      width: width,
+      height: height,
+      fit: fit,
+      gaplessPlayback: true,
+      errorBuilder: errorBuilder ??
+          (context, error, stackTrace) => SizedBox(
+            width: width,
+            height: height,
+            child: placeholder ??
+                const Center(child: Icon(Icons.broken_image, size: 20)),
+          ),
+      frameBuilder: (context, child, frame, wasSynchronouslyLoaded) {
+        if (wasSynchronouslyLoaded || frame != null) return child;
+        return SizedBox(
+          width: width,
+          height: height,
+          child: placeholder ??
+              const Center(
+                child: SizedBox(
+                  width: 16,
+                  height: 16,
+                  child: CircularProgressIndicator(strokeWidth: 2),
+                ),
+              ),
+        );
+      },
+    );
+  }
+}

package/examples/app_network_image_README.md

@@ -0,0 +1,51 @@
+# AppNetworkImage — 业务接入样板
+
+复制 `flutter-simple/lib/perf/app_network_image.dart` 到业务工程，用于让性能采集能拿到 **图片 URL / 尺寸 / 字节数**。
+
+## 为什么要这一处侵入
+
+| 方式 | 有无 URL | 说明 |
+|------|----------|------|
+| 纯 Timeline 引擎事件 | 通常无 | 只能告警「有慢解码」 |
+| **统一 `AppNetworkImage`** | 有 | 报告可点名具体图 |
+
+## 接入
+
+1. 复制文件到例如 `lib/widgets/app_network_image.dart`
+2. 列表/头像/封面改为：
+
+```dart
+AppNetworkImage(
+  url: item.coverUrl,
+  width: 56,
+  height: 56,
+  fit: BoxFit.cover,
+)
+```
+
+3. 预加载 / 强制解码：
+
+```dart
+final image = await AppImageLoader.loadAndDecode(
+  url,
+  cacheWidth: 800,
+  cacheHeight: 600,
+);
+```
+
+4. （可选）lint / Code Review：禁止业务直接 `Image.network`
+
+## Timeline 约定
+
+- 事件名：`app.imageDecode`
+- arguments：`url`（必填），`ms`（必填，Stopwatch 耗时），`width` / `height` / `bytes`（可选）
+
+跨 `await` 时 Timeline 的 B/E 时常采不到时长，样板用 **Stopwatch + instantSync 写入 `ms`**，MCP 优先读该字段。
+
+`flutter-devtools-mcp` 的 `imageDecode` 指标会解析这些字段，并在报告「慢解码」中展示链接。
+
+指标解读见：[../docs/performance-metrics-guide.md](../docs/performance-metrics-guide.md) §5。
+
+## 与 cached_network_image
+
+可在现有缓存库外包一层，在真正 decode 结束后用 Stopwatch 打同样的 `Timeline.instantSync(app.imageDecode, arguments: {url, ms, ...})` 即可，不必换掉缓存策略。

package/package.json

@@ -0,0 +1,69 @@
+{
+  "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",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "flutter-devtools-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE",
+    "docs",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "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": [
+    "flutter",
+    "devtools",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "debugging",
+    "profiling",
+    "dart",
+    "vm-service",
+    "cursor",
+    "claude"
+  ],
+  "author": "treexi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/treexi/flutter-devtools-ext.git",
+    "directory": "flutter-devtools-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/treexi/flutter-devtools-ext/issues"
+  },
+  "homepage": "https://github.com/treexi/flutter-devtools-ext/tree/main/flutter-devtools-mcp#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ws": "^8.18.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.9",
+    "@types/ws": "^8.18.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}