---

name: pipeline-development description: "Guides MaaNTE Pipeline JSON, task option JSON, i18n, SceneManager, controller restrictions, and registry changes." disable-model-invocation: true metadata: disco-role: operating license: AGPL 3.0

Pipeline Development

Use This When

Use this sub-skill when the task involves assets/resource/base/pipeline/**/*.json, assets/resource/tasks/*.json, assets/interface.json, UI i18n files, SceneManager public interfaces, or Pipeline recognition/action flow design.

Typical prompts:

• Add a new MaaNTE task or task option.
• Modify a Pipeline node, ROI, recognition threshold, action, next, on_error, or pipeline_override.
• Debug why a task option does not affect a node.
• Register a task in the interface import list.
• Update labels/descriptions across five locale files.
• Add a scene-navigation interface or avoid direct private SceneManager usage.

Read First

1. references/pipeline-patterns.md for Pipeline JSON style, recognition/action patterns, flow control, delays, and SceneManager rules.
2. references/task-config-and-i18n.md for task JSON, options, pipeline_override, interface imports, and locale requirements.
3. references/troubleshooting.md for missing nodes, OCR/template mismatch, controller problems, and SceneManager misroutes.
4. ../../references/maa-framework-patterns.md for verified MaaFramework binding and Pipeline semantics used across the repo.
5. Run scripts/validate_pipeline_json.py when you need a quick node-structure check, or ../../scripts/inspect_task_catalog.py when checking task registry or option coverage.

Operating Rules

• Coordinates, click targets, image templates, and ROI rectangles are based on 1280×720.

• Prefer nested v2 shape for new nodes:

  "recognition": {"type": "OCR", "param": {"roi": [0, 0, 100, 40], "expected": ["完整文本"]}},
  "action": {"type": "Click"}
  

• Preserve existing local shorthand style when making a narrow edit in an old node, but do not mix incompatible forms inside the same field.

• Every action should follow recognition. A DirectHit is acceptable only after another node has proven state or for explicit config/entry placeholders.

• Do not solve missed states by adding broad loops or max_hit blindly. Add a state node, popup/loading handler, or clearer next branch.

• If a node truly needs no default wait, set rate_limit, pre_delay, and post_delay explicitly to 0.

• Use [JumpBack] for popups, loading, scene transitions, and shared handlers that should return to the parent node.

• Use public SceneManager interface nodes from Interface/Scene/; do not route task pipelines directly to private __ScenePrivate* nodes.

• OCR expected values should use complete text; if a partial/regex string must skip i18n sync, mark that in source comments according to repo convention.

New Task Checklist

1. Create or update assets/resource/base/pipeline/<TaskFamily>.json with a clear entry node.
2. Create or update assets/resource/tasks/<TaskName>.json with task, entry, option, and optional controller fields.
3. Add the task file to assets/interface.json imports.
4. Add or update five interface locale files when labels/descriptions use $key.
5. If Python is needed, coordinate with ../custom-actions/SKILL.md for custom action registration.
6. Run safe checks: task catalog inspection, JSON formatting, git diff --check, and targeted Pipeline node/manual tests when a live environment exists.

Common Review Questions

• Does the entry node exist and route from all realistic starting states?
• Does every next list cover success, loading, popup, wrong-scene, and completion states relevant to the task?
• Are controller restrictions accurate for the required input/screenshot mode?
• Are option names, input names, and pipeline_override target nodes exact?
• Are new OCR strings synchronized or intentionally skipped?
• Does the task avoid blind multi-click sequences and hidden implicit delays?