pipeline-testing
Skill65 starsChanged 4 months agoMITView on GitHub
测试 MaaFramework Pipeline JSON 中的 node,验证识别和操作是否正常工作。 Click 节点会让页面跳转,破坏后续测试初始状态。必须用 BackButton_500ms 返回: **BackButton_500ms** 在 main_ui.json 里,DirectHit 识别返回箭头,定位精确可靠。 OCR 失败时不要换 TemplateMatch!先用 sweep 找 sweet spot。 操作流程: 1. 生成测试 pipeline — 同一节点,多个 expand 变体 2. 关键:expected 必须是中文(["角色"]),不是英文 key(["Role"]) 3. run_pipeline 逐个跑,记录 score 4. 选 score ≥ 0.99 且 ROI 不重叠相邻元素的 expand 5. 用 generate_node.py --expand X --overwrite 正式写入 实战矩阵(5 节点实测): 观察: - OCR 引擎*非确定性*:同一 ROI 不同次测试结果可能不同 - timeout: 2000 期间 OCR 会重试多次,所以单次失败不一定是真失败 - 特殊节点(如"城堡")需小 ROI,因为大 ROI 包含邻近 UI 元素会干扰 OCR 测试时*绝对不要*点击这些按钮(消耗资源): - 升级建筑、神殿升级 -…
In this repository3 other files it gives its agents.
- pipeline-generateSkill
- pipeline-guideSkill
- pipeline-optionSkill
The file
Files
Pipeline Testing Skill
概述
测试 MaaFramework Pipeline JSON 中的 node,验证识别和操作是否正常工作。
核心流程
# 1. 连接设备
find_adb_device_list()
controller_id = connect_adb_device(device_name="xxx")
# 或
controller_id = connect_window(window_name="xxx")
# 2. 加载 pipeline
load_pipeline(pipeline_path="<pipeline_json>")
RESOURCE_PATH = "<resource_base_path>"
# 3. 逐个测试
for node_name in pipeline_nodes:
result = run_pipeline(
controller_id=controller_id,
pipeline_path=pipeline_path,
entry=node_name,
resource_path=RESOURCE_PATH
)
# succeeded + all_results 有内容 = 识别成功
# 详见下方"结果判断"小节结果判断
| status | all_results | 含义 |
succeeded | 有内容 | ✅ 识别成功 |
succeeded | 空 | ❌ 识别失败 |
failed | — | ❌ 节点未触发 / 识别超时 |
返回结构:
{
"status": "succeeded",
"nodes": [{
"name": "node_name",
"recognition": {
"all_results": [{"box": [x, y, w, h], "score": 0.99, "text": "..."}]
}
}]
}跨测试导航 ⚠️
Click 节点会让页面跳转,破坏后续测试初始状态。必须用 BackButton_500ms 返回:
# 测试节点
run_pipeline(..., entry="NodeA", ...)
# 必须返回!不要 click_key(4) 模拟 ESC(可能进错页面)
run_pipeline(..., entry="BackButton_500ms", ...)
# 测下一个
run_pipeline(..., entry="NodeB", ...)BackButton_500ms 在 main_ui.json 里,DirectHit 识别返回箭头,定位精确可靠。
ROI Sweep 测试方法
OCR 失败时不要换 TemplateMatch!先用 sweep 找 sweet spot。
操作流程:
- 生成测试 pipeline — 同一节点,多个 expand 变体
- 关键:
expected必须是中文(["角色"]),不是英文 key(["Role"]) run_pipeline逐个跑,记录 score- 选 score ≥ 0.99 且 ROI 不重叠相邻元素的 expand
- 用
generate_node.py --expand X --overwrite正式写入
实战矩阵(5 节点实测):
| 节点 | e0 | e20 | e50 | 最佳 |
| 角色 | ✅ | ✅ 0.9997 | ✅ | e20 |
| 编队 | ✅ | ✅ 0.998 | ✅ | e20 |
| 城堡 | ✅ | ❌ | — | e3(仅 0-15) |
| 佣兵团 | ❌ | ✅ | ✅ | e20 |
| 前往群岛 | ✅ | ✅ | ✅ | e20 |
观察:
- OCR 引擎非确定性:同一 ROI 不同次测试结果可能不同
timeout: 2000期间 OCR 会重试多次,所以单次失败不一定是真失败- 特殊节点(如"城堡")需小 ROI,因为大 ROI 包含邻近 UI 元素会干扰 OCR
资源保护 ⚠️
测试时绝对不要点击这些按钮(消耗资源):
- 升级建筑、神殿升级
- 供奉、祭拜先祖
- 购买物品、商城购买
- 确认战斗开始
- 任何有资源消耗的确认按钮
误入后处理:尝试 BackButton_500ms 或 ESC → 切换 tab 刷新。
常见问题
| 现象 | 排查 |
| 节点超时失败 | 截屏看实际界面 → 调整 expected 文本或 roi |
| OCR 拆分多字(如"角色"→"电"+"色") | 缩小 ROI 避开干扰 |
| 误识别相邻文字 | 缩小 ROI 限制范围 |
| 点击位置不准 | 实际点击取 box 中心点:x + w/2, y + h/2 |
| 可滚动 UI 单视图测不全 | 一个截图里只能看到 5-6 个元素,需要 swipe 多次分别测;详见下方 |
| Click + BackButton 跳错页面 | Click 子页后按 BackButton 可能回到大地图/外层 UI,不是预期父页面;需主动 navigate 回来 |
| 部分可见元素识别 | 边界处只露 25px 也能 OCR 找到(score 偏低 0.8x),用大 ROI 覆盖即可 |
可滚动 UI 多视图测试
单次截图只能测当前可见的 5-6 个元素。要测全列表(如城堡 10 个建筑)必须多次 swipe:
1. 进入目标页(如城堡顶部)
2. run_pipeline 测当前可见的 N 个节点
3. 每个 click 后 BackButton 返回
4. swipe 滚动一屏
5. 再 run_pipeline 测新可见的节点
6. 重复直到列表测完典型案例:城堡建筑(10 节点)
- 顶部:城堡管理/市场/铁匠铺/炼金工坊/训练所
- 中段:城堡主厅/神殿/家族
- 底部:藏馆/庄园
关键:所有节点共用同一大 ROI [x, top_y, w, full_h],不要给每个节点算不同 ROI(滚动后位置变了,原 ROI 失效)。
卡住时截图查看
症状:节点超时、OCR 找不到、行为异常、识别 score 突然下降
解决:调 screencap(controller_id) 看实际屏幕状态:
- 当前在哪个页面?(是否已跳到其他页面)
- 目标文字是否被遮挡/弹窗挡住?
- 屏幕是否在加载/转圈?
- 滚动位置对吗?
配合 ocr() 看识别结果交叉验证。不要盲调 ROI/expected,先看实际屏幕。
跨测试导航 ⚠️(Click 节点路径风险)
Click 节点会让页面跳转,破坏后续测试初始状态。必须用 BackButton_500ms 返回:
# 测试节点
run_pipeline(..., entry="NodeA", ...)
# 必须返回!不要 click_key(4) 模拟 ESC(可能进错页面)
run_pipeline(..., entry="BackButton_500ms", ...)注意:BackButton 不一定回到你期望的父页面!
- 例:城堡管理 → BackButton → 实际回到 大地图(不是城堡)
- 例:训练所 → BackButton → 回到城堡(正常)
测试前先确认 BackButton 路径,或者用 ocr() 检查当前页面状态再继续。
测试模板
## <文件名> 测试记录
日期: 2026-06-05
设备: xxx
controller_id: xxx
### Node 列表
- [ ] node_name_1
- [ ] node_name_2
### 测试进度
| Node | 结果 | 备注 |
|------|------|------|
| xxx | ✅ | score=0.999 |
| xxx | ❌ | 原因xxx |Reference(详见 pipeline-guide)
- ROI / box / target 概念
- 识别类型:DirectHit / OCR / TemplateMatch / FeatureMatch / ColorMatch / And / Or
- 动作类型:Click / LongPress / Swipe / Scroll / InputText / ClickKey
- 节点生命周期:pre_wait_freezes → pre_delay → action → post_wait_freezes → post_delay → 截图识别 next
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

