// MaaEnd Pipeline JSON 编写指南。基于 MaaFramework Pipeline 协议，提供节点命名、识别算法、动作类型、流程控制、可复用节点等编码规范与模式参考。在编写、修改或审查 Pipeline JSON、设计节点流程、使用 TemplateMatch/OCR/Custom 识别或 Click/Swipe 动作时使用。
MaaEnd MapTracker 相关组件编写指南。为 agent/go-service/maptracker 下的 Go 代码提供说明，并提供 MapTracker 的开发文档指引。在参与开发 MapTracker 的 Go 代码实现时，或需要了解 MapTracker 详细工作原理时使用。
向 routes.json 添加环境监测（EnvironmentMonitoring）新观察点条目。使用时：新增 zmdmap / kite_station_i18n 观察点路线配置、适配新版本的环境监测任务、补全缺失的 EnterMap、MapPath 或 MapTarget 数据。会自动检测缺失任务，逐字段询问路线数据后写入 routes.json。
分析 Windows 崩溃转储文件（.dmp），诊断 MaaEnd 及其依赖项（MaaFramework、MXU）的崩溃。自动从 GitHub Releases 下载对应版本 PDB 符号，使用 minidump-stackwalk 解析堆栈轨迹并定位崩溃根因。当 issue 日志包或附件中发现 .dmp 文件，或用户要求分析 DMP/崩溃转储时使用。
分析 MaaEnd 上游仓库公开 Issue（`https://github.com/MaaEnd/MaaEnd/issues/...` 或 `#1234`）。自动抓取 issue 正文和评论中的 `MaaEnd-logs-*.zip` 附件，下载解压后从 `maafw.log`、`maafw.bak.*.log`、`go-service.log`、`mxu-tauri.log`、`mxu-web-*.log`、`mxu-agent*.log`、`config/*`、`on_error/` 中筛选关键证据，并结合 MaaEnd、MaaFramework、MXU 的代码和文档判断根因、给出修复方案，供用户在让你分析 MaaEnd issue、日志包、识别失败、任务卡死、控制器差异、Pipeline/Agent/MXU 问题时使用。
分析 MaaEnd `CreditShoppingMain` 的日志。用于还原信用购物任务中实际购买了什么商品、每件商品的折扣力度、是否触发过刷新（或刷新次数已用尽）、稳健刷新是否触发、以及信用点的消耗状况。货架槽位必须以日志中的 `CreditIcon`（TemplateMatcher）为锚，有无 `BuyFirstOCR`/`Priority2OCR` 不影响槽位级货架的还原与呈现。适用于用户询问信用点交易、信用购物买了什么、折扣情况、刷新配置、`CreditShoppingMain` 任务行为等场景。
仅分析 `AutoStockStapleMain` 的 MaaEnd 日志。用于还原该任务实际购买了什么、购买所对应的证据、逐步剩余账单（券/账单）数值时间线，以及在 pipeline 或 go-service 中应当加日志/埋点的位置。适用于用户询问 `AutoStockStapleMain`、`AutoStockStaple`、武陵/四号谷地的稳定需求物资购买，或该任务内账单数值变化原因等场景。
| name | pipeline-guide |
| description | MaaEnd Pipeline JSON 编写指南。基于 MaaFramework Pipeline 协议，提供节点命名、识别算法、动作类型、流程控制、可复用节点等编码规范与模式参考。在编写、修改或审查 Pipeline JSON、设计节点流程、使用 TemplateMatch/OCR/Custom 识别或 Click/Swipe 动作时使用。 |
next 列表，覆盖当前操作后所有可能画面，力争一次截图命中。pre_delay / post_delay / timeout，优先通过增加中间识别节点解决；只在必须等画面稳定时才用 pre_wait_freezes / post_wait_freezes。当确实不需要延迟时，要在节点上显式将 rate_limit / pre_delay / post_delay 设为 0（协议默认 rate_limit=1000ms、pre_delay/post_delay=200ms，省略字段会引入隐式等待；仓库的 tools/add_node_defaults.py 会为 Common 节点补齐这些 0 值字段）。.prettierrc（4 空格缩进，数组元素换行）。__ 开头（如 __ScenePrivateXXX），不对外暴露。ResellMain、DailyProtocolPassInMenu、RealTimeAutoFightEntry。MaaEnd 使用 v2 格式，recognition 和 action 放入二级字典：
{
"MyNode": {
"recognition": {
"type": "TemplateMatch",
"param": {
"template": "MyTask/button.png",
"roi": [100, 200, 300, 100],
"threshold": 0.7,
},
},
"action": {
"type": "Click",
},
"next": ["NextNode"],
},
}
"recognition": {
"type": "TemplateMatch",
"param": {
"template": "path/to/image.png", // 相对 image 文件夹
"roi": [x, y, w, h], // 720p 坐标，缩小搜索范围
"threshold": 0.7 // 默认 0.7，按需调整
}
}
green_mask: true 可遮蔽不参与匹配的区域（用 RGB(0,255,0) 涂色）。"recognition": {
"type": "OCR",
"param": {
"roi": [x, y, w, h],
"expected": ["完整文本"]
}
}
expected 写完整文本，不要写片段。tools/i18n 会自动处理。expected 数组中加 // @i18n-skip 注释。"recognition": {
"type": "ColorMatch",
"param": {
"roi": [x, y, w, h],
"method": 40, // HSV 空间（推荐）
"lower": [h_low, s_low, v_low],
"upper": [h_high, s_high, v_high],
"count": 100
}
}
// And：全部子识别都成功才算命中
"recognition": {
"type": "And",
"param": {
"all_of": ["NodeA", "NodeB"], // 可引用节点名或内联 object
"box_index": 0
}
}
// Or：任一子识别成功即命中
"recognition": {
"type": "Or",
"param": {
"any_of": ["NodeA", "NodeB"]
}
}
调用 go-service 注册的自定义识别器：
"recognition": {
"type": "Custom",
"param": {
"custom_recognition": "ExpressionRecognition",
"custom_recognition_param": {
"expression": "{CreditOCR}<300"
}
}
}
| 动作 | 用途 | 关键字段 |
|---|---|---|
Click | 点击 | target, target_offset |
LongPress | 长按 | target, duration |
Swipe | 滑动 | begin, end, duration |
Scroll | 滚轮（仅Win32） | 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]。
按序识别，首个命中的节点执行其 action 后成为当前节点。next 为空或全部超时则任务结束。
识别超时或动作失败时执行的节点列表。
[JumpBack]：命中后执行完该节点链，自动返回父节点继续识别 next。适用于处理弹窗、加载等中断场景。
"next": [
"BusinessNode",
"[JumpBack]HandlePopup",
"[JumpBack]WaitLoading"
]
[Anchor]：动态引用锚点，运行时解析为最后设置该锚点的节点。
只在必须时使用 pre_wait_freezes / post_wait_freezes 等待画面静止，不要为了执行稳定而使用延迟：
"post_wait_freezes": {
"time": 200,
"target": [0, 0, 0, 0] // 全屏
}
避免对同一按钮重复点击——第二次点击可能作用于下一界面的其他元素。
限制节点最大命中次数，超过后自动跳过：
"max_hit": 3
编写前先检查是否已有可复用节点，避免重复造轮子。
Common/Button/）| 节点 | 说明 |
|---|---|
WhiteConfirmButtonType1 | 白底圆环确认 |
WhiteConfirmButtonType2 | 白底对号确认 |
YellowConfirmButtonType1 | 黄底圆环确认 |
YellowConfirmButtonType2 | 黄底对号确认 |
CancelButton | 白底 X 取消 |
CloseButtonType1 | 右上角 X（不兼容 ESC 菜单） |
CloseButtonType2 | 右上角 X（兼容 ESC 菜单，推荐） |
TeleportButton | 右下角传送按钮 |
CloseRewardsButton | 奖励界面对号关闭 |
从任意界面自动导航到目标场景。仅使用 Interface/ 下的接口节点，禁止引用 __ScenePrivate* 内部节点。
"next": [
"MyBusinessNode",
"[JumpBack]SceneAnyEnterWorld"
]
常用接口：SceneAnyEnterWorld、SceneEnterMapAny、SceneEnterWorldFactory、SceneDialogConfirm、SceneWaitLoadingExit 等。详见 docs/zh_cn/developers/scene-manager.md。
SubTask：顺序执行子任务列表。ClearHitCount：清除节点命中计数。ExpressionRecognition：计算布尔表达式。docs/zh_cn/developers/custom.md。{
"MyTaskEntry": {
"next": [
"MyTaskMainStep",
"[JumpBack]SceneDialogConfirm",
"[JumpBack]SceneWaitLoadingExit",
"[JumpBack]SceneAnyEnterWorld",
],
},
}
{
"ClickConfirm": {
"recognition": { "type": "TemplateMatch", "param": { "template": "confirm.png", "roi": [...] } },
"action": { "type": "Click" },
"post_wait_freezes": { "time": 200, "target": [0, 0, 0, 0] },
"next": ["VerifyNextScreen", "[JumpBack]ClickConfirm"]
}
}
{
"MyButton": {
"recognition": {
"type": "And",
"param": {
"all_of": ["ButtonBackground", "ButtonIcon"],
"box_index": 0,
},
},
"action": {"type": "Click"},
},
}
pre_delay / post_delay / timeoutnext 列表覆盖所有可能画面，含弹窗/加载/异常.prettierrclocales/ 已添加新增任务的多语言文本expected 写完整文本post_wait_freezes__ScenePrivate* 内部节点docs/zh_cn/developers/common-buttons.mddocs/zh_cn/developers/scene-manager.mddocs/zh_cn/developers/custom.mddocs/zh_cn/developers/README.mddocs/zh_cn/developers/node-testing.md