MAA_Punish Pipeline 编写指南
文档索引
| 需求 |
优先看 |
| 速查表（本节下方） |
识别/动作/字段默认值/节点属性 |
| 完整语义与边界情况 |
仓库根目录 protocol-3.1-task-pipeline.md |
| 上游原文 |
3.1-PipelineProtocol |
| JSON Schema 校验 |
tools/schema/pipeline.schema.json、custom.*.schema.json |
| 自动战斗专项 |
docs/自动战斗框架开发指南.md |
| Python 自定义实现 |
agent/recognition/、agent/action/ |
Pipeline 速查表
v1 / v2 写法
- v1：
"recognition": "TemplateMatch"，参数字段与节点平级混写（老写法）。
- v2（推荐）：
"recognition": { "type": "TemplateMatch", "param": { ... } }，action 同理；除 recognition/action 外的字段（next、timeout、pre_delay 等）仍在节点根上，与协议一致。
roi / box / target（易混）
| 字段 |
含义 |
roi |
识别搜索区域 [x,y,w,h]，可与 roi_offset 叠加 |
box |
识别命中结果区域（运行时产生） |
target |
动作作用区域；默认 true 表示用当前识别结果的 box |
节点通用字段 · 默认值速查
以下为协议常见内置默认（节点未写时使用；实际可能被 assets/resource/**/default_pipeline.json 覆盖，见下节）。
| 字段 |
典型默认 |
说明 |
rate_limit |
1000 ms |
每轮识别间隔下限 |
timeout |
20000 ms |
本节点 next 整轮识别超时；-1 表示无限等 (v5.5) |
pre_delay / post_delay |
200 ms |
识别→动作前、动作→截下一帧前；易引入隐性等待，按需显式写 0 |
pre_wait_freezes / post_wait_freezes |
0 |
画面静止再前进；对象形式见协议「等待画面静止」 |
repeat |
1 |
动作重复次数 (v5.3) |
repeat_delay / repeat_wait_freezes |
0 |
重复间隔 (v5.3) |
inverse |
false |
反转识别结果 |
enabled |
true |
false 时其他节点 next 里会跳过该节点 |
max_hit |
无限制 |
命中次数上限 (v5.1) |
执行顺序（单节点内）
pre_wait_freezes → pre_delay → action（及 repeat 分支）→ post_wait_freezes → post_delay → 截图 → 识别 next。
next / on_error
| 机制 |
说明 |
next |
按顺序尝试子节点识别，第一个命中则执行其 action 并进入该子节点上下文 |
| 全未命中 |
循环等待直到 timeout（或无限），再进当前节点的 on_error |
| 动作失败 |
进命中子节点的 on_error（若写了） |
| 任务结束 |
next 为空且无需 JumpBack；或 StopTask；或外部 post_stop |
节点属性（next / on_error 列表里）
| 写法 |
作用 |
[JumpBack]节点名 或 { "name": "节点名", "jump_back": true } |
子链跑完后回到父节点，从父 next 头再扫；用于弹窗/加载。在 on_error 路径上不回跳 (v5.9) |
[Anchor]锚点名 |
解析为最后一次被赋值的锚点指向的节点；anchor 字段可在节点上设为字符串 / 数组 / 对象 (v5.7) |
识别算法速查表
recognition.type（v2）或 v1 的 recognition 字符串。
| 类型 |
用途提要 |
关键 param（节选） |
| DirectHit |
不识别，直接当命中 |
roi |
| TemplateMatch |
模板找图 |
template（image/ 相对路径）、roi、threshold（默认 0.7）、method（如 5 常用）、green_mask、index / order_by |
| FeatureMatch |
特征点匹配，透视/尺度变化 |
template、count、detector（如 SIFT） |
| ColorMatch |
找色 |
method（如 40=HSV）、lower、upper、count、connected |
| OCR |
文字 |
expected（可正则）、model、only_rec、color_filter（引用 ColorMatch 节点名）v5.8 |
| NeuralNetworkClassify |
固定区域分类 |
model（model/classify）、labels、expected（类下标） |
| NeuralNetworkDetect |
检测框 |
model（model/detect）、expected、threshold |
| And v5.3 |
逻辑与 |
all_of（节点名字符串 v5.7 或内联识别）、box_index |
| Or v5.3 |
逻辑或，首个命中即停 |
any_of |
| Custom |
自定义识别（本项目为 Python 注册） |
custom_recognition、custom_recognition_param、roi |
动作类型速查表
action.type（v2）或 v1 的 action 字符串。
| 类型 |
用途提要 |
关键 param（节选） |
| DoNothing |
无操作 |
— |
| Click |
点击 |
target（true / 节点名 / [Anchor]名 / 坐标 / 区域）、target_offset、contact、pressure v5.0 |
| LongPress |
长按 |
duration、target 等同 Click |
| Swipe |
滑动 |
begin、end（支持折线列表）、duration、only_hover |
| MultiSwipe |
多指滑动 |
swipes[]：begin/end/starting/… |
| TouchDown / TouchMove / TouchUp v5.0 |
细分触控 |
contact、target |
| Scroll v5.1 |
滚轮（Win/mac 等） |
target、dx、dy（建议 Win 下取 120 倍数） |
| ClickKey / LongPressKey |
按键 |
key（虚拟键码） |
| KeyDown / KeyUp v5.0 |
组合键时序 |
key |
| InputText |
文本 |
input_text |
| StartApp / StopApp |
启停应用 |
package |
| StopTask |
停止当前任务链 |
— |
| Command |
外部进程 |
exec、args（支持 {ENTRY} {NODE} {IMAGE} 等占位） |
| Shell v5.3 |
ADB shell |
cmd、shell_timeout（原 timeout v5.8 改名） |
| Screencap |
保存截图到 log 目录 |
filename、format、quality |
| Custom |
自定义动作（本项目 Python） |
custom_action、custom_action_param、target |
本项目约定
- 分辨率：ROI / 模板均以 1280×720 为基准（与 README 模拟器说明一致）。
- 资源路径：
assets/resource/**/pipeline/**/*.jsonc；图片相对各自 bundle 的 image/ 等目录。
- 默认值文件：例如
assets/resource/base/default_pipeline.json 会与框架 default_pipeline.json 机制合并；改全局默认时注意多 bundle 加载顺序（见协议「多 Bundle」）。
- 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。
核心原则（审查时自检）
- 状态驱动：识别 → 操作 → 再识别；少凭假设点击后的画面。
- 高命中率：
next 覆盖分支（含弹窗、加载、异常界面）。
- 慎用纯延迟：优先加识别节点与
*_wait_freezes；需要「无等待」时对默认敏感字段显式 0。
- Schema：提交前用仓库工具/IDE 校验
tools/schema/pipeline.schema.json。
- 勿照搬其他项目：Custom 名称以本仓库为准。
审查清单
参考（本仓库）
protocol-3.1-task-pipeline.md（权威细节）docs/自动战斗框架开发指南.mdtools/schema/pipeline.schema.json- 成熟范例：同目录其它
*.jsonc（如 Role_Selection.jsonc）
Source: overflow65537/MAA_Punish — distributed by TomeVault.
tomevault-io