| name | pipeline-debug |
| description | 调试和优化 MaaFramework Pipeline JSON。用于对照 schema 验证配置，检测缺失引用、循环依赖、孤立节点、命名与行为不匹配、ROI/阈值问题，并给出可靠性、性能和可维护性改进建议。触发词包括 debug pipeline、validate pipeline、optimize pipeline、pipeline error。 |
| license | MIT |
| compatibility | Designed for Claude Code |
| allowed-tools | Read Grep Glob |
MaaFramework Pipeline 调试
功能说明
- 对照
tools/schema/pipeline.schema.json 及相关 schema 验证 Pipeline JSON。
- 检测结构性问题：缺失引用、循环依赖、孤立节点、意外终止。
- 通过命名规范分析节点角色，从节点名推断其预期行为。
- 检测命名与代码不匹配，例如
Click 节点没有动作，Visible 节点却执行点击。
- 提供性能、可靠性和可维护性优化建议。
- 必要时生成修正后的 Pipeline 片段，可以增删节点以实现正确行为。
使用场景
- Pipeline JSON 运行不符合预期。
- 部署前验证 Pipeline 配置。
- 排查节点跳转、识别失败、重复点击、误点、卡死。
- 优化 ROI、阈值、流程结构或异常处理。
- 根据节点名理解流程语义，检查命名是否与实际识别/动作一致。
工作流程
1. 读取规范文件
优先读取当前项目中的 schema：
tools/schema/pipeline.schema.jsontools/schema/interface_import.schema.jsontools/schema/interface.schema.jsontools/schema/custom.recognition.schema.jsontools/schema/custom.action.schema.json
如果项目缺少某个 schema，说明缺失项并继续基于 MaaFramework 通用协议分析。
2. 分析 Pipeline 片段
- 解析 JSON，列出所有节点。
- 提取关键字段：
recognition、action、enabled、next、interrupt、sub、on_error、timeout、max_hit。
- 构建节点图：父节点到子节点、反向引用、入口节点、终止节点。
- 区分 v1 简写字段和 v2
{type, param} 字段。
3. 对照 schema 验证
逐节点检查：
- 必需字段是否齐全。
- 字段类型是否匹配。
- 枚举值、数值范围、字符串模式是否合法。
- 识别类型及参数是否正确。
- 动作类型及参数是否正确。
- Custom 节点名和参数是否可能与 agent 注册不一致。
4. 通过命名分析节点语义
使用 Pipeline 节点命名规范 理解节点角色：
<Domain>Main：入口节点。<Domain><Subtask>Flow：流程编排节点。<Domain>Enter<Page>：进入页面或功能。<Domain>On<Page>Page / <Domain><Object>Visible：页面或 UI 状态检测。<Domain>Click<Object> / Select / Claim / Purchase：动作节点。<Domain>Confirm<Object>：确认弹窗或确认操作。<Domain><Page>Entered：进入成功哨兵节点。<Domain>End / EndTask：终止节点。
重点检查命名与行为不匹配：
Click<Object> 但没有 action: Click 或等价动作。Visible / On<Page>Page 却执行点击。Flow 节点包含具体识别或动作。Enter<Page> 点击后没有成功哨兵或重试/异常处理。Detected 暴露底层识别实现，而 Visible / Available / Selected 更符合业务语义。
5. 分析节点关系
- 所有
next[]、interrupt[]、sub[]、on_error[] 目标都必须存在。
- 识别循环是否有退出条件、
max_hit、timeout 或明确终止节点。
- 找出无法从入口到达的孤立节点。
- 找出没有
next 且不像终止节点的死胡同。
- 检查
[JumpBack]、[Anchor] 等节点属性是否用于合适场景。
6. 识别常见问题
详见 调试规则参考。快速检查：
- 缺少识别或识别类型错误。
- TemplateMatch 缺模板、OCR 缺 expected、ColorMatch 缺 lower/upper。
- ROI 过大、阈值过低或过高。
- 点击后没有验证下一画面。
- 重复点击同一按钮，可能误点到下一页元素。
enabled 默认值与 Project Interface 选项语义不一致。
7. 生成优化建议
建议按优先级输出：
- 正确性问题：会导致执行失败、误点、卡死。
- 可靠性问题：弹窗、加载、动画、网络波动下容易失败。
- 性能问题：全屏识别、大模板、高频 OCR。
- 可维护性问题：命名不清、过度拆分、重复节点、缺少 desc。
8. 提供修正方案
如发现问题，给出修正后的 JSON 片段，并说明每处改动原因。响应格式见 输出格式。
注意事项
- v1 简写和 v2 object 格式可能共存，应按项目现状判断，不要强行重写无关节点。
- 无
next 的节点可以是合法终止节点，但必须符合流程语义。
enabled 默认为 true，只有显式 false 才默认关闭。interrupt / sub / on_error 的语义依项目使用习惯和 MaaFramework 版本而定，先查 schema 和现有模式。- 模板路径通常相对 image/resource 图片目录，具体以当前项目约定为准。
- OCR
expected 可能支持正则；是否自动 i18n 取决于当前项目工具链。
- 输出问题时优先给高置信度结论；不确定项标为“需要运行日志或截图验证”。
参考资料
