pipeline-guide

name	pipeline-guide
description	MaaFramework Pipeline JSON 编写指南。用于编写、修改或审查 Pipeline JSON，设计节点流程，使用 TemplateMatch/OCR/ColorMatch/Custom 识别或 Click/Swipe/Custom 动作，并检查 MaaFramework 项目的通用 Pipeline 可靠性。

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 推荐格式

{
    "MyNode": {
        "recognition": {
            "type": "TemplateMatch",
            "param": {
                "template": "MyTask/button.png",
                "roi": [100, 200, 300, 100],
                "threshold": 0.7,
            },
        },
        "action": {
            "type": "Click",
        },
        "next": ["NextNode"],
    },
}

常用识别算法

TemplateMatch

"recognition": {
    "type": "TemplateMatch",
    "param": {
        "template": "path/to/image.png",
        "roi": [x, y, w, h],
        "threshold": 0.7
    }
}

• 模板路径通常相对项目 image/resource 图片目录，按当前项目约定为准。
• 尽量缩小 ROI，避免全屏匹配造成性能和误识别问题。
• green_mask: true 可遮蔽不参与匹配的区域。

OCR

"recognition": {
    "type": "OCR",
    "param": {
        "roi": [x, y, w, h],
        "expected": ["完整文本"]
    }
}

• expected 优先写完整文本。
• 多语言项目中，确认当前项目是否有 i18n 工具自动处理 OCR 文案。
• 需要片段或正则时，按项目约定标注跳过 i18n。

ColorMatch

"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

"recognition": {
    "type": "And",
    "param": {
        "all_of": ["NodeA", "NodeB"],
        "box_index": 0
    }
}

"recognition": {
    "type": "Or",
    "param": {
        "any_of": ["NodeA", "NodeB"]
    }
}

• 只有组合条件会被多个节点复用，或确实需要组合识别时，才拆出独立子节点。
• 不要为了“看起来清楚”把单次使用的 Visible 节点过度拆分。

Custom

"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：限制节点最大命中次数，适合避免重复领取或循环点击。

典型模式

带弹窗处理的任务入口

{
    "MyTaskMain": {
        "next": [
            "MyTaskStep",
            "[JumpBack]CommonConfirmDialog",
            "[JumpBack]CommonWaitLoadingExit",
            "[JumpBack]NavigationReturnHome",
        ],
    },
}

点击后验证画面变化

{
    "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
• MaaFramework Pipeline Protocol：https://github.com/MaaXYZ/MaaFramework/blob/main/docs/en_us/3.1-PipelineProtocol.md