pipeline-debug

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：

1. tools/schema/pipeline.schema.json
2. tools/schema/interface_import.schema.json
3. tools/schema/interface.schema.json
4. tools/schema/custom.recognition.schema.json
5. tools/schema/custom.action.schema.json

如果项目缺少某个 schema，说明缺失项并继续基于 MaaFramework 通用协议分析。

2. 分析 Pipeline 片段

1. 解析 JSON，列出所有节点。
2. 提取关键字段：recognition、action、enabled、next、interrupt、sub、on_error、timeout、max_hit。
3. 构建节点图：父节点到子节点、反向引用、入口节点、终止节点。
4. 区分 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. 生成优化建议

建议按优先级输出：

1. 正确性问题：会导致执行失败、误点、卡死。
2. 可靠性问题：弹窗、加载、动画、网络波动下容易失败。
3. 性能问题：全屏识别、大模板、高频 OCR。
4. 可维护性问题：命名不清、过度拆分、重复节点、缺少 desc。

8. 提供修正方案

如发现问题，给出修正后的 JSON 片段，并说明每处改动原因。响应格式见 输出格式。

注意事项

• v1 简写和 v2 object 格式可能共存，应按项目现状判断，不要强行重写无关节点。
• 无 next 的节点可以是合法终止节点，但必须符合流程语义。
• enabled 默认为 true，只有显式 false 才默认关闭。
• interrupt / sub / on_error 的语义依项目使用习惯和 MaaFramework 版本而定，先查 schema 和现有模式。
• 模板路径通常相对 image/resource 图片目录，具体以当前项目约定为准。
• OCR expected 可能支持正则；是否自动 i18n 取决于当前项目工具链。
• 输出问题时优先给高置信度结论；不确定项标为“需要运行日志或截图验证”。

参考资料

• Pipeline 节点命名规范
• 调试规则
• 常见模式
• 输出格式
• MaaFramework Pipeline Protocol：https://github.com/MaaXYZ/MaaFramework/blob/main/docs/en_us/3.1-PipelineProtocol.md