pipeline-guide

# MaaFramework Pipeline 编写指南 ## 核心原则 1. **状态驱动**：遵循“识别 → 操作 → 识别”循环。每次操作必须基于识别结果，禁止假设操作后画面状态。 2. **覆盖可能画面**：扩充 `next` 列表，覆盖操作后可能出现的页面、弹窗、加载态和异常态。 3. **少用硬延迟**：尽量不用 `pre_delay` / `post_delay` / `timeout` 解决稳定性问题，优先通过中间识别节点和 `pre_wait_freezes` / `post_wait_freezes` 等待画面稳定。 4. **720p 基准**：坐标、ROI、模板裁剪和截图判断统一以 1280×720 为基准，除非当前项目另有明确约定。 5. **格式一致**：遵循项目现有 JSON 格式化规则；常见 MaaFramework 项目使用 4 空格缩进和数组元素换行。 ## 节点命名 - 节点名使用 PascalCase，推荐基础格式为 `<Domain><SemanticPart><Role>`。 - 不要在全项目无脑统一为“动宾”或“宾动”；先判断节点角色，再决定语序。 - 动作节点使用动宾：命中后会执行点击、选择、领取、购买、确认、关闭等动作时，使用 `<Domain><Verb><Object><OptionalRole>`，例如 `CommonConfirmReward`、`DailyTaskClaimMissionReward`、`ShopPurchaseGem`、`BattleClosePage`。 - 状态 / 对象 / 纯检测节点使用宾 + 状态或角色后缀：例如 `ShopGemVisible`、`BattleStartButtonBlocked`、`DailyRewardsRewardClaimed`；不要为了动宾写成 `VisibleGem`、`BlockedStartButton`。 - 按钮、弹窗、文本模板看语义：`ConfirmButton` 可以表示“确认按钮”这个对象；但执行“确认购买/确认奖励”动作的节点应命名为 `ConfirmBuy` / `ConfirmReward`。 - 入口节点常用 `<Domain>Main`；只编排流程、不直接识别或动作的节点常用 `<Domain><Subtask>Flow`，若流程目标本身是动作，也可用动宾目标，例如 `DailyRewardsClaimRewardFlow`。 - 页面或 UI 状态节点使用 `On<Page>Page`、`Visible`、`Available`、`Selected`、`Completed`、`Exhausted` 等能表达业务语义的后缀。 - 不要使用 `_Start`、`Node1`、`clickReward`、`shop_enter`、`FlagInX`、`RewardConfirm`、`RewardClaim`、`GemPurchase`、`PageClose` 这类不稳定、语序不一致或不表达职责的名称。 ## Pipeline v2 推荐格式 ```jsonc { "MyNode": { "recognition": { "type": "TemplateMatch", "param": { "template": "MyTask/button.png", "roi": [100, 200, 300, 100], "threshold": 0.7, }, }, "action": { "type": "Click", }, "next": ["NextNode"], }, } ``` ## 常用识别算法 ### TemplateMatch ```jsonc "recognition": { "type": "TemplateMatch", "param": { "template": "path/to/image.png", "roi": [x, y, w, h], "threshold": 0.7 } } ``` - 模板路径通常相对项目 image/resource 图片目录，按当前项目约定为准。 - 尽量缩小 ROI，避免全屏匹配造成性能和误识别问题。 - `green_mask: true` 可遮蔽不参与匹配的区域。 ### OCR ```jsonc "recognition": { "type": "OCR", "param": { "roi": [x, y, w, h], "expected": ["完整文本"] } } ``` - `expected` 优先写完整文本。 - 多语言项目中，确认当前项目是否有 i18n 工具自动处理 OCR 文案。 - 需要片段或正则时，按项目约定标注跳过 i18n。 ### ColorMatch ```jsonc "recognition": { "type": "ColorMatch", "param": { "roi": [x, y, w, h], "method": 40, "lower": [h_low, s_low, v_low], "upper": [h_high, s_high, v_high], "count": 100 } } ``` - 优先使用 HSV 或灰度空间，避免直接 RGB 匹配带来的设备差异。 ### And / Or ```jsonc "recognition": { "type": "And", "param": { "all_of": ["NodeA", "NodeB"], "box_index": 0 } } ``` ```jsonc "recognition": { "type": "Or", "param": { "any_of": ["NodeA", "NodeB"] } } ``` - 只有组合条件会被多个节点复用，或确实需要组合识别时，才拆出独立子节点。 - 不要为了“看起来清楚”把单次使用的 `Visible` 节点过度拆分。 ### Custom ```jsonc "recognition": { "type": "Custom", "param": { "custom_recognition": "MyRecognition", "custom_recognition_param": {} } } ``` - `custom_recognition` / `custom_action` 名称必须与 Agent 注册名一致。 - 参数结构应和 Go/C++/Python 扩展代码中的解析结构一致。 ## 常用动作类型 | 动作 | 用途 | 关键字段 | | ---------------------- | -------------- | -------------------------------------- | | `Click` | 点击 | `target`, `target_offset` | | `LongPress` | 长按 | `target`, `duration` | | `Swipe` | 滑动 | `begin`, `end`, `duration` | | `Scroll` | 滚轮 | `target`, `dx`, `dy` | | `ClickKey` | 按键 | `key` | | `InputText` | 输入文本 | `input_text` | | `StartApp` / `StopApp` | 启停应用 | `package` | | `StopTask` | 停止当前任务链 | 无 | | `Custom` | 自定义动作 | `custom_action`, `custom_action_param` | | `DoNothing` | 不执行动作 | 无 | `target` 常见形式：`true`、节点名字符串、`[x, y]`、`[x, y, w, h]`。 ## 流程控制 - `next`：按序识别，首个命中节点执行其 action 后成为当前节点；全部超时或为空则流程结束。 - `on_error`：识别超时或动作失败后的兜底节点。 - `[JumpBack]`：执行完子链后返回父节点继续识别，适合弹窗、加载、奖励确认等中断处理。 - `[Anchor]`：动态引用锚点，按 MaaFramework 当前协议使用。 - `max_hit`：限制节点最大命中次数，适合避免重复领取或循环点击。 ## 典型模式 ### 带弹窗处理的任务入口 ```jsonc { "MyTaskMain": { "next": [ "MyTaskStep", "[JumpBack]CommonConfirmDialog", "[JumpBack]CommonWaitLoadingExit", "[JumpBack]NavigationReturnHome", ], }, } ``` ### 点击后验证画面变化 ```jsonc { "ClickConfirm": { "recognition": {"type": "TemplateMatch", "param": {"template": "confirm.png", "roi": [100, 100, 200, 80]}}, "action": {"type": "Click"}, "post_wait_freezes": {"time": 200, "target": [0, 0, 0, 0]}, "next": ["VerifyNextScreen", "[JumpBack]ClickConfirm"], }, } ``` ## 审查清单 - [ ] 字段名、类型、枚举值符合 Pipeline 协议或项目 schema。 - [ ] `next` / `on_error` / `sub` / `interrupt` 引用的节点都存在。 - [ ] 每次点击后有识别验证，不假设操作后状态。 - [ ] ROI / target 坐标基于 1280×720 或项目约定分辨率。 - [ ] 没有不必要的硬延迟；必须等待时优先使用 freeze wait。 - [ ] OCR 文本和 locale/i18n 规则符合当前项目约定。 - [ ] Custom 节点注册名和参数结构与 Agent 代码一致。 - [ ] 未过度拆分只使用一次且无复用价值的中转检测节点。 ## 参考 - 字段速查：[field-reference.md](field-reference.md) - MaaFramework Pipeline Protocol：<https://github.com/MaaXYZ/MaaFramework/blob/main/docs/en_us/3.1-PipelineProtocol.md>