MaaPipelineEditor

主题

kqcoxn
1621
5.6m

流程级调试 ​

流程级调试功能允许在 MaaPipelineEditor 中实时运行 Pipeline 任务，观察节点执行过程，查看识别结果，并快速定位问题。

提示

此模块正在绝赞重构中，服务暂不可用。

前置条件 ​

在使用调试功能前，需要满足以下条件：

  1. 启动 LocalBridge 服务：确保本地服务正常运行
  2. 连接控制器：完成设备连接
  3. 配置资源路径：设置包含 Pipeline 资源的目录

使用流程 ​

1. 配置调试参数 ​

在调试面板中配置以下参数：

资源路径 ​

资源路径用于加载 Pipeline 定义、图像资源等文件。支持配置多个路径，后面的路径会覆盖前面的同名资源。

  • 自动填充：连接后端后，编辑器会自动尝试从后端配置中获取资源路径
  • 手动添加：点击"添加路径"按钮，输入资源目录的绝对路径，路径需要精确到 pipeline 文件夹的根目录，例如/resource或/base，而非 pipeline 文件夹本身

入口节点 ​

选择任务的起始节点。可以从以下方式选择：

  • 在画布中选中节点后，点击"设为入口"按钮
  • 在调试面板的入口节点下拉框中手动选择

Agent 连接（可选） ​

输入 Agent 标识符以连接 Agent 服务。Agent 用于提供 AI 辅助功能。

2. 启动调试 ​

点击"启动调试"按钮开始执行。系统会：

  1. 验证配置参数的完整性（资源路径、入口节点、控制器）
  2. 自动保存当前 Pipeline 文件（如果启用了"调试前保存"选项）
  3. 创建调试会话，加载资源并初始化 MaaFramework
  4. 从入口节点开始执行任务

3. 查看执行状态 ​

调试过程中，界面会实时更新以下状态信息：

状态标签 ​

  • 空闲（灰色）：未启动调试
  • 运行中（蓝色）：正在执行任务
  • 识别中（黄色）：当前节点正在识别 next 列表
  • 执行中（绿色）：当前节点正在执行动作
  • 已暂停（橙色）：任务已暂停
  • 已完成（青色）：任务执行完毕

实时信息 ​

  • 当前节点：显示正在执行的节点名称
  • 识别目标：识别阶段显示正在识别的目标节点
  • 执行时长：显示任务运行的总时长

4. 识别记录 ​

识别卡片列表 ​

识别记录面板以卡片形式展示每一轮识别的结果：

卡片结构：

  • 标题：当前执行的节点（发起识别的节点）
  • 时间戳：识别发生的时间
  • 识别项：next/on_error 列表中的所有候选节点

识别项状态：

  • 🟡 待识别（pending）：等待识别
  • 👀 识别中（running）：正在识别
  • ✅ 已命中（succeeded）：识别成功
  • ❌ 未命中（failed）：识别失败

操作：

  • 点击"查看"按钮可以查看该识别项的详细信息
  • 点击"清空"按钮清除所有识别记录

识别详情 ​

识别详情模态框展示单个识别项的完整信息：

  • 基础信息：节点名称、状态、时间戳、父节点、执行次数
  • 算法信息：使用的识别算法类型（OCR、TemplateMatch、ColorMatch 等）
  • 绘制图像：算法生成的调试图像（如 OCR 框选、模板匹配位置等）
  • 最佳结果：识别返回的详细数据（坐标、文本、置信度等）

5. 执行历史 ​

在节点字段面板的"识别记录"标签页中，可以查看与当前选中节点相关的执行历史：

时间线视图 ​

按时间顺序展示节点的执行过程：

  • 运行中：蓝色圆点，正在执行
  • 已完成：绿色对勾，执行成功
  • 失败：红色叉号，执行失败

每条记录包含：

  • 执行次数（如果节点被多次执行）
  • 开始时间
  • 执行耗时
  • 错误信息（如果失败）

识别记录标签页 ​

出发节点记录：显示从当前节点发起的所有识别记录（parentNode 等于当前节点）

目标节点记录：显示当前节点作为识别目标的所有记录（识别项中包含当前节点）

6. 停止调试 ​

点击"停止调试"按钮结束任务执行。系统会：

  1. 停止当前运行的任务
  2. 断开 Agent 连接（如果已连接）
  3. 销毁调试会话，释放资源
  4. 保留识别记录和执行历史供查看

高级功能 ​

调试前自动保存 ​

启用"调试前保存"选项后，每次启动调试前会自动保存当前的 Pipeline 文件，避免因未保存导致的不一致。

打开日志 ​

点击"打开日志"按钮可以在系统默认编辑器中打开 MaaFramework 的运行日志（maa.log），查看更详细的执行信息。

识别记录面板 ​

点击"显示识别记录"按钮可以展开全局识别记录面板，独立显示所有识别记录，方便全局查看和对比。

常见问题 ​

资源路径无法加载 ​

问题：启动调试时提示"加载资源失败"

解决方案：

  1. 确认资源路径正确，且包含 pipeline 子目录
  2. 检查路径权限，确保后端进程有读取权限
  3. 查看后端日志，确认具体的错误原因

控制器连接失败 ​

问题：提示"控制器不存在"或"控制器实例不可用"

解决方案：

  1. 在调试前确保已成功连接 ADB 设备或 Win32 窗口
  2. 检查 LocalBridge 服务状态
  3. 尝试重新连接控制器

识别结果不显示 ​

问题：调试过程中没有识别记录产生

解决方案：

  1. 确认 Pipeline 节点配置正确，包含识别算法和 next 列表
  2. 检查日志，确认识别过程是否正常执行
  3. 验证截图功能是否正常（调用截图工具测试）

Agent 连接失败 ​

问题：提示"Agent 连接失败"

解决方案：

  1. Agent 连接是可选功能，不影响基础调试功能
  2. 检查 Agent 服务是否启动
  3. 验证 Agent 标识符是否正确

最佳实践 ​

  1. 逐步调试：从简单节点开始，逐步扩展到复杂流程
  2. 查看识别详情：通过绘制图像和最佳结果快速定位识别问题
  3. 配合日志使用：遇到问题时查看详细日志，获取更多诊断信息