profile-dart-code

用途

本技能用于对 Dart 命令行应用进行 CPU 性能分析（Dart CPU Profiling），通过 VM Service 协议采集 CPU 采样样本并识别性能瓶颈，帮助智能体自动化 Dart 脚本或 CLI 工具的 CPU 剖析流程。

适合在以下情况使用：

被要求分析、优化或基准测试 Dart 脚本或 CLI 工具的 CPU 执行情况。
排查热点循环、繁重函数调用或意外的执行开销。

不适用的情况（弃用护栏）

以下情况不要使用本技能进行性能分析：

纯 I/O 瓶颈：性能瓶颈来自网络延迟、数据库查询或磁盘 I/O 等待，而非 CPU 执行。
Flutter UI 应用：目标为需要帧分析、光栅线程检查或组件重建跟踪的 Flutter 应用（应改用 Flutter DevTools 或 widget_inspector）。
短时微基准测试：仅运行数毫秒的微基准测试，VM 预热和采样开销会扭曲结果（应改用 package:benchmark_harness 或 package:bench_press）。
目标无法正常执行：若目标脚本无法编译或启动即崩溃，应先修复功能性缺陷再进行 CPU 性能分析。

工作流程

确保编译正常：确认目标 Dart 脚本能正常运行（dart run <script.dart>）。
运行分析脚本：使用本技能目录中的自动化分析辅助脚本，在启用 VM Service 可观测性的情况下启动目标应用，采集 CPU 样本，并输出消耗最高的函数。
分析并优化：查看工具报告的 self 与 total 采样百分比，定位瓶颈（例如过多的对象分配、开销高的哈希计算、虚方法分发开销）。

运行分析辅助脚本

该仓库包含一个零依赖（仅使用官方 vm_service）的性能分析脚本，可启动任意 Dart 文件、连接到 VM Service、等待执行完成（--pause-isolates-on-exit）、获取 CPU 样本，并打印简洁摘要，同时导出完整 JSON 性能档案。

可在任意工作目录下运行：

dart run <dash_skills_repo>/skills/profile-dart-code/scripts/bin/profile.dart --out=cpu_profile.json -- <path_to_target.dart> [target_arguments...]

脚本参数

-o, --out=<file>：保存原始 JSON CPU 档案的输出文件路径（默认：cpu_profile.json）。
-p, --period=<micros>：采样间隔，单位为微秒（默认：1000µs = 1ms）。最小 50µs。
-- <target.dart> [args...]：要分析的 Dart 脚本，以及传递给 main() 的任意参数。

[!WARNING] 潜在挂起风险：使用 VM service 对 Dart 目标进行性能分析或调试时，目标异常或连接问题可能导致进程无限期挂起。请确保目标脚本处理超时，并监控进程输出。

示例输出

Connecting to VM service at ws://127.0.0.1:8181/ws...
Target execution paused at exit. Retrieving CPU profile samples...

=== Top CPU Functions (Self Samples) ===
 1. _PuzzleSmart._shiftSlice (self: 34.2%, total: 41.0%)
 2. _countInversions (self: 18.5%, total: 18.5%)
 3. shortestPaths (self: 12.1%, total: 98.4%)

Saved complete JSON profile to: cpu_profile.json

解读性能档案的最佳实践

重点关注 Self % 与 Total %：高 self % 表示 CPU 时间直接消耗在函数自身主体内部（数学运算、循环分支、数组索引）。高 total % 而低 self % 表示该函数是调度器或外层编排循环。
留意隐藏开销：注意紧凑循环中的隐式对象分配（_copyData、迭代器包装器、闭包创建）。
以实证验证优化效果：在应用优化前后，始终记录基线采样数与执行时长（time -v）。