Maa Pipeline Generate

What it does

When your agent uses it

• OCR node generation
• Choosing TemplateMatch/OCR/ColorMatch/CustomRecognition
• Preserving target-file schema style
• Designing next/[JumpBack] links before merging generated nodes into pipeline JSON

Example prompts

• “/maa-pipeline-generate”

Requirements

• Python 3

Workflow steps

12 steps, taken from the first numbered list in SKILL.md.

1. 1ocr() 自动截图：MaaMCP 的 ocr() 工具会自行获取当前画面，调用前不要重复 screencap()；如果换了 MCP provider，先读该工具的参数说明确认截图语义。
2. 2ROI 不是越大越好：默认 expand=75 会失败（OCR 把"角色"拆成"电"+"色"）。多数节点 sweet spot 是 expand=20-30。
3. 3特殊节点需要小 ROI："城堡" expand≥20 全失败，只接受 0-15（上方有图标 M/3.9m/1077/👍 干扰）。
4. 4expected 必须匹配当前资源实际显示文本：在 MaaGumballs 中文资源里 ["角色"] 正确、["Role"] 找不到；跨语言项目要按目标资源/locale 写实际 OCR 文本或项目约定的 i18n 形式。
5. 5OCR 非确定性：同一 ROI 不同次结果可能不同，timeout: 2000 期间会重试。
6. 6OCR 失败不要立刻换 TemplateMatch：先看截图、扫 ROI、检查 expected 与颜色干扰；如果目标本质是稳定图标/按钮，TemplateMatch 本来就是正确选择，不必死守 OCR。
7. 7可滚动 UI 用大 ROI + 父级 orchestrator（重要）
8. 8run_pipeline 必须有手动超时意识：超过 ~10 秒不返回要主动停止，可能 ROI/expected 配错或 OCR 引擎卡住。
9. 9改完 pipeline 文件后调 load_pipeline(path) 即可：不需要重启 server。run_pipeline 每次都按 pipeline_path 从磁盘读最新内容，reload 后立即生效。
10. 10可滚动 UI 用统一大 ROI：当多个目标在同一个可滚动列表（如城堡建筑列表）时，所有节点共用同一 ROI [x, top_y, w, full_h]，覆盖整个滚动区域。避免每个节点各自 ROI 滚动后失效。前提：每个节点的 expected 文字是唯一的（OCR 按…
11. 11ROI 上边界 ≤ 元素最小 y：目标元素在 y=424 时，ROI y 起点必须 ≤ 424，否则切掉顶部导致 OCR 失败。例：原 ROI [100, 450, ...] 把"城堡管理"切掉 26px → 改为 [100, 400, ...] 通过。
12. 12卡住时截图查看：节点超时、OCR 找不到、行为异常时，调 screencap 看当前屏幕实际状态。可能界面已不在预期页、可能位置已被遮挡。

What it can do on your machine

Read from SKILL.md and the folder at commit e3ff401. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 2 files in scripts/ (Python), which the agent can run.

  Shell commands in SKILL.md call:

  • python

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Maa Pipeline Generate loads about 2.8k tokens when it runs. Until then it costs about 87 tokens; SKILL.md has 621 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~87

When it runs · the whole SKILL.md, loaded when a task matches

~2.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from duorua/narutomobile at commit e3ff401, republished under its AGPL-3.0 licence (© duorua). 621 words, ~2,843 tokens.

name

maa-pipeline-generate

description

Generate MaaFramework Pipeline nodes and recognition snippets from screenshots or observed UI state. Use for OCR node generation, ROI sweep, choosing TemplateMatch/OCR/ColorMatch/CustomRecognition, preserving target-file schema style, and designing `next`/`[JumpBack]` links before merging generated nodes into pipeline JSON.

# === Step 1: 连接设备 ===
from maa_mcp.adb import find_adb_device_list, connect_adb_device
controller_id = connect_adb_device(find_adb_device_list()[0])

# === Step 2: OCR 拿 box + 算 ROI ===
from maa_mcp.vision import ocr
from maa_mcp.download import check_and_download_ocr

ocr_results = ocr(controller_id)
if isinstance(ocr_results, str) and "OCR 模型文件不存在" in ocr_results:
    check_and_download_ocr()
    ocr_results = ocr(controller_id)

matched = [r for r in ocr_results if target_text in (r.text if hasattr(r, "text") else r["text"])]
best = max(matched, key=lambda r: r.score if hasattr(r, "score") else r["score"])
box = best.box if hasattr(best, "box") else best["box"]

# 扩大 ROI（720p 硬编码 + 4 边裁剪）
SCREEN_W, SCREEN_H = 720, 1280
x, y, w, h = box
E = expand_offset
roi = [
    max(0, x - E),
    max(0, y - E),
    min(SCREEN_W - max(0, x - E), w + 2 * E),
    min(SCREEN_H - max(0, y - E), h + 2 * E),
]

# === Step 3: 合并到目标 pipeline ===
from maa_mcp.pipeline_tools import load_pipeline, save_pipeline
from pathlib import Path

PROJECT_ROOT = Path(__file__).resolve().parents[3]
pipeline_path = Path(pipeline_file)
if not pipeline_path.is_absolute():
    pipeline_path = PROJECT_ROOT / "assets" / "resource" / "base" / "pipeline" / pipeline_file

existing = load_pipeline(str(pipeline_path)) or {}
if node_name in existing and not overwrite:
    raise RuntimeError(f"节点 '{node_name}' 已存在")
existing[node_name] = {
    "recognition": "OCR",
    "expected": [target_text],
    "roi": roi,
    "action": action_type,
    "post_delay": post_delay,
    "timeout": timeout,
}
save_pipeline(
    pipeline_json=json.dumps(existing, ensure_ascii=False, indent=4),
    output_path=str(pipeline_path),
    overwrite=True,
)

原始 box:     ┌────┐
              │ 文字│
              └────┘
扩大后 roi:   ┌──────────┐
              │  ┌────┐  │
              │  │文字│  │
              │  └────┘  │
              └──────────┘

# 生成多个 expand 变体的测试 pipeline
python "<skill-dir>/scripts/generate_sweep.py" "角色" "46,1248,50,30" 0,5,10,15,20,25,30

python "<skill-dir>/scripts/generate_node.py" "角色" UI_RoleListPage main_ui.json --expand 20 --overwrite

"AutoSky_GreenCheck": {
    "recognition": "ColorMatch",
    "roi": [558, 802, 157, 45],
    "method": 4,
    "lower": [22, 123, 57],      // RGB 下界(暗绿)
    "upper": [55, 215, 102],     // RGB 上界(亮绿)
    "action": "DoNothing",
    "post_delay": 200,
    "timeout": 2000
},

"AutoSky_CheckEnergyZero": {
    "recognition": "OCR",
    "expected": ["0/\\d+"],
    "roi": [850, 1280, 220, 50],
    "color_filter": "AutoSky_GreenCheck",  // ← 只在绿色区域 OCR
    "action": "DoNothing"
}

{
    "MyActivity_Start": {
        "next": [
            "MyActivity_TeamReady",                      // 已在队伍配置页 → 点击"进入战斗"
            "[JumpBack]MyActivity_Difficulty_Select",     // 在难度选择页 → 选难度
            "[JumpBack]MyActivity_Enter"                 // 在大地图 → 找入口
        ],
        "timeout": 10000
    },

    "MyActivity_Enter": {
        "next": [
            "MyActivity_Enter_Click",                    // 找到图标 → 点击
            "[JumpBack]BigMap_Activity_Resident",         // 切"常驻"tab
            "[JumpBack]BigMap_Activity"                  // 打开活动页
        ],
        "timeout": 10000
    },

    "MyActivity_EnterBattle": {
        "recognition": "OCR",
        "expected": ["进入战斗"],
        "action": "Click",
        "next": [
            "MyActivity_FightStart",                       // 战斗开始
            "[JumpBack]MyActivity_TravelSelect_Boat",      // 乘船
            "[JumpBack]MyActivity_TravelSelect_Walk"       // 步行 fallback
        ]
    },

    "MyActivity_TravelSelect_Boat": {
        "recognition": "OCR",
        "expected": ["确定"],
        "roi": [490, 740, 100, 80],                     // 窄 ROI 限定乘船行
        "action": "Click"
    },

    "MyActivity_TravelSelect_Walk": {
        "recognition": "OCR",
        "expected": ["确定"],
        "roi": [490, 590, 100, 80],                     // 窄 ROI 限定步行行
        "action": "Click"
    }
}

© duorua, AGPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (scripts) in .agents/skills/maa-pipeline-generate of duorua/narutomobile.

• SKILL.md
• agents/openai.yaml
• scripts/generate_node.py
• scripts/generate_sweep.py

Open the folder on GitHubat commit e3ff401