| name | maa-punish-pipeline-guide |
| description | MAA_Punish 任务流水线 JSON/JSONC 编写与审查指南。含 Pipeline 速查表（识别类型、动作类型、节点字段默认值、JumpBack/Anchor、Custom）。基于 MaaFramework 协议与本仓库 protocol-3.1-task-pipeline.md。在编写或审查 pipeline、排查超时/on_error、或使用 TemplateMatch/OCR/Custom 时使用。 |
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）
