SuperAPI AI 工具集

maui-devflow-onboard

编程与开发

查看项目

更新于 10-16 08:15

技能介绍

用途

MAUI DevFlow Onboard 用于在 maui devflow init 已安装 DevFlow 技能之后,把 MAUI DevFlow 接入到 .NET MAUI 项目中。它面向的是项目尚未引用任何 Microsoft.Maui.DevFlow.* 包、用户询问如何接入、初始化、安装、集成或设置 DevFlow 的场景。

何时使用

  • 项目还没有 Microsoft.Maui.DevFlow.* 包引用。
  • 用户询问如何接入、初始化、安装、集成或设置 DevFlow。
  • 需要在标准、Blazor、GTK 或 GTK + Blazor DevFlow 包之间做选择。
  • 仓库使用中央包管理,包编辑需要正确拆分。
  • maui devflow init 已安装技能,用户询问下一步的项目编辑。

何时转向其他技能

  • 如果包引用和 AddMauiDevFlowAgent() 已存在,但 CLI 无法连接,使用 maui-devflow-debug。
  • 如果 agent 可访问,且用户想要检查、点击、截图或调试 UI,使用 maui-devflow-debug。

工作流程

  1. 可选:在编辑前运行 maui devflow skills check 并更新捆绑技能,如果它报告 update-available-from-current-cli。
  2. 在工作区中查找 MAUI 应用项目。优先选择带有 UseMaui、平台 TFM(如 net*-android/net*-ios/net*-maccatalyst/net*-windows)或 GTK MAUI 包引用的应用项目。
  3. 判断每个目标项目是标准 MAUI、MAUI + Blazor WebView、GTK,还是 GTK + Blazor。
  4. 添加正确的 DevFlow 包引用。如果存在 Directory.Packages.props,需遵守中央包管理。
  5. 在 MauiProgram.cs 的 #if DEBUG 中注册 DevFlow。
  6. 构建并运行应用。
  7. 使用以下命令验证:
    • maui devflow diagnose
    • maui devflow wait
    • maui devflow ui tree --depth 1
  8. 如果集成后验证失败,切换到 maui-devflow-debug 进行连接恢复。

停止信号

  • 如果存在多个 MAUI 应用项目且用户未指明要接入哪一个,在编辑前停止。
  • 在 Debug 构建之外启用 DevFlow 之前,停止并询问。
  • 在包/注册编辑完成后停止,并在进行运行时调试前先通过构建验证。

关键反模式

  • 当 Directory.Packages.props 管理包版本时,不要给项目 PackageReference 项添加版本。
  • 除非应用使用 Blazor WebView,否则不要添加 Blazor DevFlow 包。
  • 除非用户明确要求,否则不要在 #if DEBUG 之外注册 DevFlow。
  • 不要使用旧的 builder.Services.AddMauiDevFlowAgent() 模式;应使用 builder.AddMauiDevFlowAgent()。

包选择

项目类型 所需包
标准 MAUI Microsoft.Maui.DevFlow.Agent
MAUI + Blazor WebView Microsoft.Maui.DevFlow.Agent、Microsoft.Maui.DevFlow.Blazor
GTK MAUI Microsoft.Maui.DevFlow.Agent.Gtk
GTK MAUI + Blazor WebView Microsoft.Maui.DevFlow.Agent.Gtk、Microsoft.Maui.DevFlow.Blazor.Gtk

Blazor WebView 的指示包括 Microsoft.AspNetCore.Components.WebView.Maui 包引用或 MauiProgram.cs 中的 AddMauiBlazorWebView()。

GTK 的指示包括 Microsoft.Maui.Platforms.Linux.Gtk4 或 Microsoft.Maui.Platforms.Linux.Gtk4.BlazorWebView。在添加当前 GTK DevFlow 包之前,先迁移已被取代的 Platform.Maui.Linux.Gtk4* 引用;不要混用两种后端。

中央包管理

如果仓库使用 Directory.Packages.props,把版本放在那里,并让项目 PackageReference 条目不带版本。

<!-- Directory.Packages.props -->
<PackageVersion Include="Microsoft.Maui.DevFlow.Agent" Version="<current-version>" />

<!-- App.csproj -->
<PackageReference Include="Microsoft.Maui.DevFlow.Agent" />

如果仓库不使用中央包管理,把版本放在 PackageReference 上。

MauiProgram.cs 注册

标准 MAUI:

using Microsoft.Maui.DevFlow.Agent;

// inside CreateMauiApp(), before return builder.Build();
#if DEBUG
builder.AddMauiDevFlowAgent();
#endif

MAUI + Blazor WebView:

using Microsoft.Maui.DevFlow.Agent;
using Microsoft.Maui.DevFlow.Blazor;

// inside CreateMauiApp(), before return builder.Build();
#if DEBUG
builder.AddMauiDevFlowAgent();
builder.AddMauiBlazorDevFlowTools();
#endif

GTK:使用 .Gtk 命名空间和包。当 GtkMauiApplication 创建第一个窗口时,AddMauiDevFlowAgent() 会自动启动。在 GtkMauiApplication.OnStarted() 重写中也可以使用显式的 this.StartDevFlowAgent() 钩子;仍然需要 builder 注册。

Mac Catalyst:确保 Debug 权限允许应用内 HTTP 服务器:

<key>com.apple.security.network.server</key>
<true/>

验证清单

  • MauiProgram.cs 仅在 Debug 构建中注册 DevFlow。
  • 应用项目引用的包类型与目标平台匹配。
  • 仅当应用使用 Blazor WebView 时才添加 Blazor DevFlow 工具。
  • GTK 应用使用当前后端,并在第一个窗口创建后自动启动 DevFlow agent。
  • Mac Catalyst Debug 权限包含 com.apple.security.network.server。
  • dotnet build 成功。
  • 运行中的应用出现在 maui devflow list 中。
  • maui devflow ui tree --depth 1 返回可视化树。

参考

  • 包/类型细节见 references/package-selection.md。
  • 注册模式见 references/mauiprogram-registration.md。