流程级调试
流程级调试用于在 MaaPipelineEditor 中直接运行当前 Pipeline 图，观察节点执行路径、识别结果、动作详情、截图产物和运行诊断。调试能力由 LocalBridge 调用 MaaFramework 提供，编辑器负责把运行事件映射回画布节点。
调试入口集中在 调试工作台 中。它不是一个需要开启或关闭的“调试模式”，也不提供断点、暂停、继续、单步等传统调试器语义；需要定位某个节点时，可以从指定节点重新发起一次新的运行。
前置条件
使用调试前，请确认：
- 已启动并连接 LocalBridge。
- 已初始化 MaaFramework，并连接 ADB 或 Win32 控制器。
- 已配置可加载 Pipeline、image 等资源的资源路径。
- 当前图中存在可映射到运行时名称的 Pipeline 节点。
提示
纯 Web 端无法访问本地 MaaFramework runtime，因此不提供流程级调试。Web + LocalBridge 和本地一体包均可使用。
打开调试工作台
点击全局工具区的调试按钮即可打开调试工作台。工作台左侧按使用频率组织：
- 总览：启动、停止和查看当前会话状态。
- 运行配置：集中管理接口（Interface）、资源（Resource）、控制器（Controller）、代理（Agent）和产物策略（Artifact Policy）。
- 节点：选择入口节点，发起节点级运行，并查看当前会话内与节点相关的事件。
- 时间线：查看追踪事件（Trace Event），并在当前会话内临时回放。
- 图像：查看截图、识别图、绘制图，选择固定图输入，发起批量固定图识别。
- 诊断 / 性能 / 日志：查看启动前检查、运行摘要、任务事件和错误信息。
LocalBridge 未连接时也可以打开工作台；连接后会读取调试能力清单（Capability Manifest），界面会按真实后端能力启用按钮。
运行配置
资源路径
资源路径用于加载 Pipeline、image 和其他运行资源。可以手动输入，也可以使用 LocalBridge 扫描到的资源包（Resource Bundle）。
路径通常应指向包含 pipeline、image 等子目录的资源根目录。多个路径会按顺序加载，后加载的同名资源覆盖先加载的资源。
控制器与截图
此功能一般无需配置或使用，仅做排查时使用
实时运行会使用当前已连接的 MaaFramework 控制器（Controller）。调试工作台可以手动截图，也可以开启实时截图推流，便于确认当前设备画面。
固定图识别不依赖实时控制器，会使用指定图片创建临时图像控制器。
MFW Agent
Agent 为可选能力。可以配置手动连接的外部 Agent，也可以使用托管模式让 LocalBridge 启动子进程。运行时会把 custom recognition/action 等诊断写入追踪和性能摘要。
产物策略
产物（Artifact）是运行过程中按需读取的大对象，包括：
- 原始图（Raw Image）
- 绘制图（Draw Image）
- 动作详情（Action Detail）
- 截图（Screenshot）
- 性能摘要（Performance Summary）
- 批量识别摘要（Batch Recognition Summary）
普通追踪事件只保存产物引用，以避免把大图直接塞进事件流造成卡顿或 OOM。
运行方式
完整运行
从配置档入口（Profile Entry）启动完整 Pipeline。适合验证整条流程是否能按预期执行。
从选中节点运行
以当前选中节点作为入口，继续沿 next / on_error 执行后续节点。适合复查某个中段节点之后的流程。
单节点运行
只对选中节点执行一次识别与动作组合，不继续运行后续节点。适合快速验证单个节点的完整配置。
仅识别
只测试选中节点的识别逻辑，不执行动作。适合调试 OCR、模板匹配、颜色匹配等识别参数。
仅动作
跳过识别，直接执行选中节点的动作（Action）。此模式会弹出确认，因为它可能直接点击、滑动或输入。
固定图识别
使用资源 image 目录下的图片或项目内指定图片测试选中节点的识别逻辑。适合复现截图、离线调参和批量验证模板。
追踪与产物
调试运行会生成追加式追踪（Trace）。每个事件包含序号、时间、来源、事件类型、阶段、状态、节点映射和产物引用。
时间线面板可以查看当前会话内的事件，并临时回放追踪。回放只用于当前工作台展示，不会生成长期调试记录。
图像面板用于加载产物。点击“查看”后，工作台才会向 LocalBridge 请求对应的图片或 JSON 详情。
Pipeline Override（运行时覆盖）
Pipeline Override 允许您在调试运行时临时覆盖节点的配置，无需修改原始 Pipeline 文件。适合快速验证参数调整、测试不同识别策略或跳过特定节点。
使用方式
在调试工作台的总览面板中，展开 Pipeline Override 编辑区，输入覆盖配置 JSON。
格式说明
覆盖配置以节点的运行时名称（RuntimeName）为键，值为需要覆盖的字段：
{
"节点名称": {
"recognition": "OCR",
"action": "Click",
"roi": [100, 200, 300, 400]
},
"另一个节点": {
"next": ["跳转目标"]
}
}支持的覆盖类型
- OverridePipeline：覆盖节点的完整配置（识别、动作、参数等）
- OverrideNext：覆盖节点的后继节点列表
- OverrideImage：覆盖节点使用的图像数据
使用场景
- 临时修改识别参数（如 ROI、阈值）进行快速调参
- 跳过某些节点（覆盖 next 指向后续节点）
- 测试不同的动作配置而不修改源文件
- 调试时强制使用特定图片进行识别
提示
Override 配置仅在当前调试会话中生效，不会修改原始 Pipeline 文件。支持 v1 和 v2 协议格式，系统会自动进行版本适配。
辅助面板
AI 摘要面板
AI 摘要面板可以自动生成调试运行的分析报告，帮助您快速理解执行结果和定位问题。
功能特点：
- 完整报告：对整次调试运行生成综合分析报告
- 失败分析：仅针对失败的节点生成诊断报告
- 节点解释：选择特定节点执行记录，AI 解释其行为和结果
- 自动生成：可开启自动生成开关，每次运行结束后自动生成报告
- Markdown 渲染：报告以 Markdown 格式展示，支持复制
提示
AI 摘要面板需要配置 AI API。报告质量取决于所选模型的能力。
资源健康检查面板
资源健康检查面板在调试运行前自动检测资源配置的完整性和正确性，提前发现潜在问题。
检查内容：
- 资源路径数量与加载状态
- 已加载文件数量
- 节点映射与边映射完整性
- 加载失败线索
- 检查耗时
诊断级别：
- Error：严重问题，可能导致运行失败
- Warning：潜在风险，建议修复
- Info：提示信息，供参考
功能特点：
- 按类别分组展示诊断结果
- 提供修复建议
- 支持从诊断结果快速跳转到相关文件或节点
性能面板
性能面板展示调试运行的性能指标和统计数据。
展示内容：
- 运行 ID 与状态
- 总运行时长
- 事件总数
- 节点执行数
- 识别执行数
- 动作执行数
- 截图次数
产物查看：
- 性能摘要产物（JSON 格式）
- 选中产物的详细预览
停止与日志
点击“停止”会请求 LocalBridge 停止当前任务，并释放运行时资源。停止后，当前会话内已经收到的追踪、诊断和产物引用仍可查看。
长期排查请以 MaaFramework 自动生成的 maa.log 为准。MPE 不维护独立的长期调试历史库。
常见问题
提示缺少资源路径
请在运行配置中选择资源包，或手动添加包含 pipeline / image 的资源根目录。也可以刷新 LocalBridge 的资源包列表后再试。
提示控制器不可用
请先在本地服务中连接 ADB 设备或 Win32 窗口，再回到调试工作台启动运行。固定图识别不需要实时控制器。
识别图或详情没有显示
确认产物策略中启用了对应类型，例如绘制图（Draw Image）或动作详情（Action Detail）。普通追踪事件只显示引用，需要在图像或节点详情中点击加载。
回放 / 录制控制器不可用
当前 MaaFramework Go 绑定尚未提供可维护的 Replay / Record controller 创建能力。MPE 会在能力清单中将其标记为不可用，而不是显示不可执行的假按钮。
使用建议
- 先用“仅识别”确认识别参数，再用“单节点运行”验证识别与动作组合。
- 中段流程问题优先使用“从选中节点运行”，避免重复跑完整流程。
- 复杂识别问题优先保存截图，再用固定图识别复现。
- 遇到运行失败时，同时查看诊断、时间线、产物详情和
maa.log。