maa-punish-pipeline-guide

MAA_Punish Pipeline 编写指南

文档索引

---

Pipeline 速查表

v1 / v2 写法

• v1："recognition": "TemplateMatch"，参数字段与节点平级混写（老写法）。
• v2（推荐）："recognition": { "type": "TemplateMatch", "param": { ... } }，action 同理；除 recognition/action 外的字段（next、timeout、pre_delay 等）仍在节点根上，与协议一致。

roi / box / target（易混）

节点通用字段 · 默认值速查

以下为协议常见内置默认（节点未写时使用；实际可能被 assets/resource/**/default_pipeline.json 覆盖，见下节）。

执行顺序（单节点内）

pre_wait_freezes → pre_delay → action（及 repeat 分支）→ post_wait_freezes → post_delay → 截图 → 识别 next。

next / on_error

节点属性（next / on_error 列表里）

---

识别算法速查表

recognition.type（v2）或 v1 的 recognition 字符串。

---

动作类型速查表

action.type（v2）或 v1 的 action 字符串。

---

本项目约定

1. 分辨率：ROI / 模板均以 1280×720 为基准（与 README 模拟器说明一致）。
2. 资源路径：assets/resource/**/pipeline/**/*.jsonc；图片相对各自 bundle 的 image/ 等目录。
3. 默认值文件：例如 assets/resource/base/default_pipeline.json 会与框架 default_pipeline.json 机制合并；改全局默认时注意多 bundle 加载顺序（见协议「多 Bundle」）。
4. Python Custom（v2 示例骨架）

"MyStep": {
    "recognition": {
        "type": "Custom",
        "param": {
            "custom_recognition": "YourRecoName",
            "custom_recognition_param": {},
            "roi": [0, 0, 1280, 720]
        }
    },
    "action": {
        "type": "Custom",
        "param": {
            "custom_action": "YourActionName",
            "custom_action_param": {},
            "target": true
        }
    },
    "next": ["NextNode"]
}

注册名必须与 assets/agent 内实现一致；调试看 custom.log 或 debug/custom_*.log。

---

核心原则（审查时自检）

1. 状态驱动：识别 → 操作 → 再识别；少凭假设点击后的画面。
2. 高命中率：next 覆盖分支（含弹窗、加载、异常界面）。
3. 慎用纯延迟：优先加识别节点与 *_wait_freezes；需要「无等待」时对默认敏感字段显式 0。
4. Schema：提交前用仓库工具/IDE 校验 tools/schema/pipeline.schema.json。
5. 勿照搬其他项目：Custom 名称以本仓库为准。

---

审查清单

• 字段符合 schema；Custom 与 Python 注册名一致
• next / on_error 覆盖主要分支；JumpBack 用于可恢复中断
• ROI / 模板基于 720p
• 任务入口与 assets/interface.json、assets/tasks 一致
• 需要文案展示时对照 interface / 任务定义

---

参考（本仓库）

• protocol-3.1-task-pipeline.md（权威细节）
• docs/自动战斗框架开发指南.md
• tools/schema/pipeline.schema.json
• 成熟范例：同目录其它 *.jsonc（如 Role_Selection.jsonc）