Flutter 工具面板 nikitafedorov008/dsh-flutter-tools

dsh-flutter-tools

给 DeepSeek Harness 侧边栏用的 Flutter 面板：不用离开对话，就能运行、检查、分析 Flutter 应用。

设备与启动

设备来自常驻的 flutter daemon，启动走 flutter run --machine，VM Service URI 会自动接上，其余功能都通过运行中应用自己的 VM Service 和 flutter-devtools-mcp 完成。

已连接的应用

功能

- 设备 —— 常驻的 flutter daemon（推事件，不轮询）：手机一插上就自己出现。这一栏显示当前选中的设备，带 OS 图标（Apple、Android、Windows、Linux，Web 目标则是浏览器）和一个小类型图标；点一下展开列表切换，选择按项目记住。模拟器也来自同一个 daemon。
- 启动 —— 设备、模式（debug / profile / release）、flavor 和 --dart-define 键值对，然后一个按钮，按状态决定运行还是停止。面板读取 app.debugPort 并自己连上；应用日志落在面板里。
- Flavor 与 defines —— flavor 从项目里推断（Android 的 productFlavors、非默认的 Xcode scheme）；defines 是键值编辑器。两者都按项目记住，进命令行之前先校验。
- 控制 —— 热重载、热重启、截图（内联）、widget 树、debug paint。
- 调试开关 —— 应用实际注册的服务扩展：debugPaint、showPerformanceOverlay、repaintRainbow、debugPaintBaselinesEnabled、timeDilation、inspector.show。
- 面板内嵌 DevTools —— daemon 托管 DevTools 服务器，面板把它嵌进来（inspector、performance、cpu-profiler、memory、network、logging），还有一个按钮把同一页面挪到侧边栏浏览器标签页。
- 应用信息与内存 —— VM 版本、平台、pid 和 isolate 组成键值块；实时堆读数、GC 按钮、已保存的内存快照，以及最近两次快照的对比。
- 抓取与分析 —— 重建跟踪和 HTTP 抓取各一个开关，profiling 会话，collect_performance_session 自动填好工作区根目录。
- 项目命令 —— pub get、pub outdated、flutter doctor，输出带渲染：pub outdated 变成表格，可升级的行高亮；flutter doctor 变成清单。
- 分离与 Web —— 让应用继续跑，面板不再跟踪它；或者把 Web 构建打开到侧边栏浏览器标签页。
- SDK —— 工作区自己的锁定版本（先 .fvm/flutter_sdk，再 .fvmrc）优先于 PATH 上的任何版本。

安装

DeepSeek Harness → Settings → Add plugin，然后粘贴本仓库地址。这个字段接受插件包名、GitHub 仓库地址或本地目录。命令行接受同样的写法（dsh plugin add …）；注意，桌面应用管理的配置档会拒绝命令行改动，所以插件管理器才是常规途径。

要求：

- Flutter SDK（优先用工作区锁定的版本，PATH 里的作为兜底）；
- PATH 里有 npx —— flutter-devtools-mcp 首次使用时拉取；
- 侧边栏标签页需要 dsh-better-sidebar；
- Flutter 应用跑在 debug（重建跟踪）或 profile（指标）模式下。

组成结构

| 文件 | 所属半边 | 作用 |
| index.js | 宿主（Cordis） | 注册 /flutter 路由，持有 flutter daemon、flutter run 子进程和 flutter-devtools-mcp 子进程，提供 panel.html |
| panel.html | 被提供的页面 | 整个 UI，纯 HTML/CSS/JS —— 无需构建步骤 |
| client.js | 客户端 bundle | 注册侧边栏标签页，其主体是指向 /flutter 的 iframe |
| icon.svg | 清单资源 | 插件管理器显示的图标，在 package.json 里声明为 icon |
| cordis.patch.yml | bundle 补丁 | 挂载行；其 name 必须等于包名，这样客户端 bundle 才会在 /plugins/dsh-flutter-tools/client.js 提供 |
| dev-server.mjs | 开发 | 在 DSH 之外跑同样的路由，方便迭代 UI |
| docs/ | 开发 | 上面的截图 |

端点

全部位于 /flutter 下，仅限回环 Host。

| 路由 | 用途 |
| GET /flutter | 面板页面（?cwd=&sessionId=） |
| GET /flutter/config | 工作区 cwd、fvm 锁定版本、解析出的 Flutter、开关标签 |
| GET /flutter/devices | 实时设备列表（daemon） |
| GET /flutter/emulators | 来自 daemon 的模拟器 |
| GET /flutter/flavors | 项目里找到的 flavor（Android blocks + Xcode schemes） |
| GET /flutter/run | 启动状态：running、appId、mode、flavor、defines、VM Service URI、日志尾部 |
| POST /flutter/run | 在设备上启动：{ deviceId, mode, flavor, defines } |
| POST /flutter/run/stop | 停止已启动的应用 |
| POST /flutter/run/detach | 让应用继续运行，停止跟踪它 |
| POST /flutter/emulator/launch | 启动模拟器：{ emulatorId } |
| GET /flutter/devtools | DevTools 页面 URL：?page=…&uri= |
| GET /flutter/extensions | 已注册的调试扩展及其当前状态 |
| POST /flutter/extension | 切换某个扩展：{ name, value }（仅限允许列表） |
| GET /flutter/heap | 主 isolate 的堆用量（?uri=） |
| POST /flutter/gc | 回收垃圾，然后报告堆用量 |
| POST /flutter/command | 一次性命令行：pub_get \| pub_outdated \| doctor |
| POST /flutter/call | flutter-devtools-mcp 工具调用：{ tool, arguments }（仅限允许列表） |

构建时的笔记

这些地方花过时间，记下来免得别人再付一遍。

- flutter daemon --machine 不是合法参数：它会以退出码 2 退出，且没有任何输出。不带它时，daemon 说的是同一套协议。
- flutter emulators --machine 也不存在。
- 故意不传 --show-web-server-device：实测下来，它只改变一件事——列表里多出那个合成的 web-server 设备——而这里没有任何东西依赖它。
- flutter run、flutter daemon 和 npx 都是包装器：真正的进程是孙进程（dartvm），所以直接 child.kill() 杀不掉它。子进程以 detached 方式启动，再按进程组杀掉——但 app.detach 之后例外，此时按进程组杀会把已分离的应用一起带走，所以改成按 pid 杀工具进程。
- 实测：app.detach 之后工具不会自行退出（20 s 后仍然活着），而它启动的应用能独立存活。
- VM Service 的 getMemoryUsage 需要 isolateId，而且没有 collectAllGarbage RPC——那正是 getAllocationProfile(gc: true) 的用途。
- ext.flutter.brightnessOverride 不做成开关：它上报的是平台的实际亮度，所以在深色系统上「关」依然读作深色，开关会说谎。
- --dart-define 是编译期的：改过的 define 在下次启动时生效，热重启不生效。
- 命令输出从头截断：pub outdated 的列标题留在顶部，而从尾部截断会让面板剩下一些解析不了的行。
- 插件图标是 data URL，由 harness 根据 package.json 顶层的 icon 生成；它没有 HTTP 路由，路径必须留在 manifest 目录内。

License

MIT — see LICENSE.

Development

node dev-server.mjs 9100 /path/to/flutter/project # the panel, outside DSH

docs/ 里的截图取自那个 dev server，Chrome 深色模式，device scale 2。

Attribution

标签页图标和插件图标都是 Flutter 的标志，取自 simple-icons（CC0）。Flutter 是 Google 的商标；这里用这个标志只是为了标注 Flutter 工具链。