Pipeline 编写指南

937 字约 3 分钟

节点结构

Pipeline 节点用 JSON 定义，每个节点描述一个识别 → 动作 → 跳转的完整步骤：

{
    "NodeName": {
        "recognition": "TemplateMatch",
        "roi": [
            100,
            200,
            80,
            50
        ],
        "template": "button.png",
        "threshold": 0.8,
        "action": {"type": "Click"},
        "next": ["NextNode"],
        "on_error": ["FallbackNode"]
    }
}

识别类型

类型	适用场景	说明
TemplateMatch	静态 UI 元素	OpenCV 模板匹配，图片放 `image/` 目录，threshold 默认 0.7
OCR	动态文本	PaddleOCR v5，`expected` 支持正则，`roi` 指定文字区域
DirectHit	路由分发	始终匹配成功，用于 `next` 分支控制
Custom	复杂逻辑	Python 自定义识别，通过 `@AgentServer.custom_recognition()` 注册
ColorMatch	颜色过滤	配合 OCR 的 `color_filter` 字段使用，过滤背景干扰

动作类型

类型	说明
Click	点击识别位置。`target: true` 点中心，`target: [x,y,w,h]` 偏移坐标
DoNothing	仅做识别路由，不执行操作
Swipe	滑动。`param.begin` / `param.end` / `param.duration`
Custom	Python 自定义动作，通过 `@AgentServer.custom_action()` 注册

常用字段

字段	说明
`pre_delay` / `post_delay`	动作前/后等待（毫秒），导航点击后建议 1000-2000ms
`post_wait_freezes`	等待画面静止不动（替代固定延迟，更智能）
`max_hit`	最大命中次数，超过后节点被跳过。用于循环出现的元素
`timeout`	识别超时（ms），默认 20000
`only_rec`	仅识别不动作（用于 TemplateMatch 时需注意 schema）
`focus`	命中/失败时显示日志通知
`color_filter`	OCR 预处理颜色过滤，值为 ColorMatch 节点名

节点命名约定

节点名称用点分隔层级，如 FarmResources.Start、ClaimRewards.CheckDaily
前缀用功能模块英文名：PVP.、BattlePass.、Common.
JumpBack 节点不加 next 字段

设计模式

线性流程

适合有明确先后顺序的操作（如启动游戏）：

"LaunchGame": {
    "recognition": "DirectHit",
    "action": {
        "type": "DoNothing",
        "param": { "package": "com.phxh.official.nld" }
    },
    "next": ["ClickToStart"]
},
"ClickToStart": {
    "recognition": "TemplateMatch",
    "template": "click_to_start.png",
    "action": { "type": "Click" },
    "post_delay": 2000,
    "next": ["DailyLoginReward", "CheckHomePage"]
}

DirectHit 路由枢纽

"HubNode": {
    "recognition": "DirectHit",
    "action": { "type": "DoNothing" },
    "next": ["BranchA", "BranchB"]
}

next 是 OR 逻辑：从上到下依次尝试，第一个识别成功的节点被执行。

[JumpBack] 中心枢纽

适合需要反复进入子模块的场景（如领取奖励循环）：

"ClaimRewards.MainHub": {
    "recognition": "DirectHit",
    "action": { "type": "DoNothing" },
    "next": [
        "[JumpBack]DispatchClaim.Start",
        "[JumpBack]ClaimRewards.Start",
        "[JumpBack]BattlePass.Start",
        "[JumpBack]Mailbox.Start"
    ]
}

[JumpBack] 节点命中后执行动作，然后跳回父节点重新尝试 next 列表。只有非 JumpBack 节点能退出循环。

JumpBack 节点不能有 next 字段——路由由父节点的 next 控制。

战斗循环

"BattleStage": {
    "recognition": "DirectHit",
    "action": { "type": "DoNothing" },
    "next": [
        "[JumpBack]ClickVictory",
        "[JumpBack]ClickItemDialog",
        "QuickBattle"
    ]
}

战斗胜利 → 点击 → 跳回检测 → 再次战斗 → 体力不足时退出。

任务选项覆盖

tasks/*.json 中用 pipeline_override 在运行时修改节点行为：

"pipeline_override": {
    "FarmResources.Start": {
        "next": ["FarmResources.ResourceCollect"]
    },
    "FarmResources.ClickStage": {
        "custom_recognition_param": "{\"stage_name\": \"1-1\", \"stage_index\": 1, \"resource_type\": \"特别军费行动\"}"
    }
}

可以修改 next、roi、threshold、custom_action_param 等任意字段。

max_hit 防循环

"ClaimButton": {
    "max_hit": 5,
    "recognition": "TemplateMatch",
    ...
}

最多命中 5 次后跳过，适合循环出现的领取按钮。max_hit 跨会话计数。

color_filter OCR 预处理

对于颜色鲜明的文本，可以用 ColorMatch 预先过滤背景，提升 OCR 准确率：

"GoldTextFilter": {
    "recognition": "ColorMatch",
    "method": 4,
    "lower": [[38, 31, 30]],
    "upper": [[50, 44, 44]],
    "count": 1000,
    "connected": true
}

在 OCR 节点中引用：

JOCR(roi=(x, y, w, h), color_filter="GoldTextFilter")

注意事项

等待时间要充足 — 导航点击后至少 1000ms，复杂界面建议 2000ms
OCR expected 是正则表达式 — ".*" 匹配任意，"^text$" 精确匹配
ROI 以 1280x720 为基准 — 坐标 [x, y, w, h]
on_error 兜底 — 重要的导航节点要加 on_error，避免卡死
next 顺序重要 — 优先匹配的放在前面，减少等待时间
截图不全时加 roi — 缩小识别范围提升速度和准确率
post_wait_freezes — 适合动画结束后再操作，比固定 post_delay 更可靠
清体力模式使用 RepeatCount — 通过 Custom Action 动态减少战斗次数