SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsmaafw-pipeline

maafw-pipeline

General & other

View repository

Updated 10-16 04:57

About this skill

MaaFW Pipeline Development

Writing the full workflow follows two tracks; before starting, first choose the track:

  • New-build track: create a flow from scratch (task or subflow)—requirements → breakdown and state list (including exploratory evidence gathering) → file structure and naming → asset preparation → node authoring → flow composition → self-check and handoff. Large tasks are broken down level by level into nested subflow compositions, and each level follows the same steps.
  • Modification track: make changes, refactor, and review on an existing project—survey → search references → modify → self-check (see below); do not force it into the new-build order.

Exact field semantics (field names, parameters, default values, version support)are not copied in this document, and are always routed to MaaLLMWiki 's 3.1-任务流水线协议: version locking, tracing references back to source, and marking "unverified" when unreachable (when the maallmwiki skill is installed, it carries the complete routing process). The execution model is the basis for all reasoning below, and a minimal version is given here:

Execution model (minimal mental model)

A node has three stages:recognition → action → next. The engine operates between nodes as follows:

  1. Startup: the task is started by the entry node name (post_task); the engine initializes to "current node = entry node, polling list = [entry node]"—the entry is recognized as the only candidate (usually DirectHit always matches); if recognition times out, useits own timeout, and if it does not match, it also followsits own on_error。
  2. Polling: after the current node's action completes, its next list is polled and recognized in order: each round tries each candidate in sequence; if none match in this round, wait rate_limit and then take a new screenshot and retry (when all candidates in this round are DirectHit, screenshots are skipped, with zero screen overhead).
  3. Transition：the first matching candidate wins immediately(subsequent candidates are no longer checked),enter that node, and execute its action—if the action succeeds, poll its next list (return to step 2); if the action fails, follow its on_error.
  4. Timeout attribution: polling exceedsthe current node's timeout(default 20s) and still has no match → followthe current node's on_error—to adjust a nodebeing recognized's wait duration or timeout destination, changeits previous node's timeout / on_error, not its own.
  5. Abnormal state：
    • entry (three kinds): action failure; polling timeout; no existing and enabled node in the polled list (do not wait for timeout and immediately miss—nonexistent references cannot pass load validation, and those that reach this step are mostly enabled:false nodes or unset anchors).
    • After entry: The on_error list takes over the next list and is polled the same way—when on_error is empty, next is immediately empty and the loop terminates directly, and the task ends in failure.
    • Clearance: Cleared only by a recognition hit; if the action fails after the hit, it immediately re-enters—so in terms of results, exiting the abnormal state = hit and action succeeded.
    • Tighten during abnormal state: Another miss (on_error polling times out, or the list has no existing and enabled nodes at all—e.g., a recovery node name is misspelled, fail immediately without waiting for the timeout)Do not enter on_error, and the task fails directly; if the execution chain runs empty while still in an abnormal state, the already registered [JumpBack] back-jump does not take effect, and the task terminates in failure.
  6. Termination and success/failure：
    • The loop terminates when next is empty or on external stop / StopTask;task success/failure = whether it is in an abnormal state at termination(running empty in a normal state means success).
    • The only exception is [JumpBack](normal state only): a sub-chain running empty does not terminate;re-poll the parent node's next list(recognize in order from the beginning; the parent node does not recover to the current node through recognition, the timeout and on_error ownership return to the parent node, and the action is not re-run). For example A.next=["B","[JumpBack]C"]、C.next=["D"]、D.next=[], after C hits and finishes D, re-poll A.next。

on_error ownership: A candidate being recognized does not count as entering the node;it counts as entering only after a hit; after entering, the execution action and polling of the next list both occur within this node—an action failure follows the on_error of the node where the action is located, and a next-list polling timeout follows the on_error of the node to which the next list belongs.

Hard guardrails (in effect throughout)

  1. Exploration first: Every state to be written must have real observational evidence (screenshots, OCR text, color values, boxes, etc.); states inferred from documentation, node names, or memory are all treated as guessed,guessed states must not be written down。
    • Advance by transition: Whichever interface is explored (based on the current device screen), observe that interface's recognition markers and click targets; after clicking, if the next interface's marker is actually observed to appear (i.e., the next exit candidate), this transition can be written down. Popup nodes are likewise written only after that popup has been seen; write as far as you have observed, and there is no need to finish exploring the whole flow before writing; full-flow continuity and re-entrancy are not within the writing threshold—leave that for self-check and end-to-end acceptance to run.
    • Minimize click side effects: Do not click unnecessary submit/claim-type buttons; do not actively trigger states that can be confirmed via keyframes.
    • Non-reproducible states(one-time rewards, first-clear guides, interfaces after irreversible operations): useretained keyframesinstead—important change frames temporarily stored by the tool also count as observational evidence; check frame by frame before writing; those without even keyframes are still handled as gaps.
    • Reuse and boundaries: When reusing existing nodes, their entry prerequisites must likewise be confirmed by observation; if exploration is impossible (no device/no authorization/side effects forbidden), stop and report the gap; millisecond-level reactions such as flash sales and QTEs exceed the polling model—state directly that they cannot be done.
  2. Coordinate hygiene: Click targets are derived from recognition results (see details in references/anti-patterns.md）：
    • target default true(Inherits the box recognized by this node), most nodes do not need to write it; for offsets use target_offset and state the basis;
    • Alternatively refer to the target preferentially via a string reference (preceding node name / [Anchor]锚点名, an empty reference result means the action fails); a fixed coordinate array is treated as hardcoding, to be used only in special scenarios (such as negative coordinates calculated from the edge) with the reason stated—strictly forbidden DirectHit + hardcoded target coordinates。
  3. Do not fabricate fields: if unsure about field names, parameters, or version support, route instead; prefer writing less and using default values;$ root fields at the beginning are not parsed,. files/folders at the beginning are not read.
    • Comment conventions: pipeline is parsed by jsonc , pure explanations prefer // comments; for structured comments use desc / _desc, for placeholder hints use code / _code(such as template_code），doc / _doc try not to use—all are non-protocol-agreed fields (the engine silently ignores unknown keys).
  4. Baseline resolution neutral: the runtime baseline is obtained dynamically from the project controller configuration (default 720 short side, compatible with landscape and portrait); screenshots for measuring ROI must go through the framework screenshot pipeline, not external images.
  5. Loops must have a termination argument: for any construct whose execution can return to the candidate list of already-executed nodes ([JumpBack] jump-back, next forming a cycle), choose one of the three termination arguments and explain it in a comment:
    • Limited count：max_hit / timeout + on_error report;
    • Recognition gating: candidates carry real recognition, the action aims to eliminate that recognition, and when the action may fail a fallback count limit is still configured;
    • Idle intent: an explicitly declared infinite production loop, exited via external stop or a condition node, with real progress each round in the loop, and counter resets must be explicit;
    • Timeout and the DirectHit iron rule：timeout only handles "the target interface never appeared", and cannot handle "it keeps hitting and won't stop";DirectHit is forbidden in loops(always hits with no gating, and an all-DirectHit list skips screenshots and cannot observe screen changes).

New track

Steps 1–5 proceed bysegmentin a rolling manner: each extracted sub-flow goes through 1→5 on its own, explore one segment and write one segment; there is no need to finish exploring the entire task before starting to write; after all segments are complete and self-checked, proceed to step 6.

Rolling progress must be accompanied by aprogress file(cross-session working memory, externalized as a file, placed outside the resource package where it will not be loaded by the framework): record the requirements and decomposition conclusions (sub-flow list), the implementation status of each segment (planned / written / tested), the evidence frame number for each observed state, and the current breakpoint (which interface the device is on).Keyframes are archived bound to states—it is simultaneously the observed evidence, the material for re-testing recognition (node test mode: screenshot + hits/box expectations), and the source for template cropping.

1. Requirements → decomposition and state list (including exploration evidence)

  • Decompose before flipping (rolling decomposition): first decompose a large task into sub-flows with clear entry/exit (agreed Start/End suffix), and reusable ones across tasks go into the resource package's pipeline/general.json(File ownership expresses reuse boundaries, not relying on node name prefixes, see references/project-structure.md); the split boundary isan interface segment/business segment that can be independently observed and independently verified. First define the overall sub-flow framework; on-screen states and pop-ups are added incrementally as work progresses.
  • On-screen flow (same screen first, exit later): after entering the interface, first write and immediately test the same-screen exception handling nodes (without leaving the current screen, test immediately after writing); exit nodes are written last, and after writing and testing, proceed directly to the next interface.
  • State translation: translate the flow into states (initial state, intermediate state/pop-up, success state, failure state), and each state specifies two items (for selection details see references/flow-patterns.md step one):
    • Recognition selection: fixed image TemplateMatch, text OCR, color block ColorMatch, no visual change DirectHit, scaled target FeatureMatch, complex target NeuralNetworkClassify/NeuralNetworkDetect, multi-condition combination And/Or, complex logic to maafw-custom；
    • Evidence state: annotate observed or guessed（observed before writing,guessed explore first).

2. File structure and naming

  • File organization: new defaultmodule-prefix style + PascalCase file names（AutoCollect/AutoCollectRoute1.json), existing flat projects remain as before (incremental new modules may create directories); files shared across tasks are fixed to use general.json(lowercase convention). For details see references/naming.md and references/project-structure.md。
  • JSON version: new default Pipeline v2 nested syntax（recognition / action converges to {type, param}，MaaFW v4.4.0+, isolated namespaces prevent silently invalid mismatched fields); existing projects follow the existing mainstream style, unified within the project (see references/flow-patterns.md example note).
  • Node and asset naming: node names are resolved globally across files, case-sensitive, and duplicate names in the same package are an error; do not start with $ , do not use [ ]; organize by the word-position formula 任务_界面_对象_角色_变体 (for details see references/naming.md）。image/ organize by module into directories; folder names under the resource directory must not start with _ (Android packaging restriction).

3. Asset preparation

  • Consistent pixel space: templates are cropped from framework screenshots at the baseline resolution (after lossless scaling); emulator built-in screenshots are usable only when the resolution matches the baseline and there is no notification bar/watermark/lossy compression contamination; camera re-photography or mismatched aspect ratios are unusable. Cropping should avoid dynamic numbers/animations.
  • Tool selection: Agent autonomous workflows prioritize the real-time observation foundation (such as maafw-live 's crop / color / annotate / crop --from-kf, and the flow reads its built-in maafw-live skill), or write your own script to use the framework screenshot pipeline; when a human is present, the official toolchain can be used (VSCode Maa Pipeline Support (maa-support / MSE) / MFA Toolbox / MPE).
  • Post-crop self-match review: the new template must hit at the source position in the source frame (correct position takes priority over score); verify immediately after cropping.

4. Node authoring

  • Recognition and action: one node per state, recognize first then act;roi Tighten to the target appearance region (the starting point is the recognition box expanded by about 20px (empirical value); when unstable, scan several levels); check the action selection and parameter routing against the "Task Pipeline Protocol", and the click landing point must follow coordinate hygiene (Hard Guardrail 2).
  • Node notification (focus）: configure when runtime logs/prompts/popups need to be displayed focus(supports {name} placeholders and $ i18n，display channel selection,trace requires interface.json configure telemetry to take effect; routing per "Task Pipeline Protocol" and "ProjectInterface V2").
  • Parameter starting point: TemplateMatch's threshold starts from the target position's measured score minus about 0.1 (empirical value) and must be higher than the highest mismatched score on the same screen—if the two sides are too close, it is a template / roi problem, and tuning the threshold cannot save it (OCR / ColorMatch have different semantics, FeatureMatch relies on count / ratio control); prefer using *_wait_freezes instead of a hard delay.
  • Write discipline: useincremental insertionpreserve JSONC // comments, with indentation and field order aligned to the project's existing conventions; coordinates must always be measured values in the framework's scaled coordinate system.

5. Flow composition

For the full five-step breakdown, code examples, and stability rules, see references/flow-patterns.md. The core principles are as follows:

  • Main trunk: arrange the shortest successful path into a linear next chain; express interface switching with a "wait for target to appear" node, and keep delays and node timeout at their defaults; when using *_wait_freezes , its internal timeout defaults to 20s; when the waiting region has continuous animation, often configure a small fallback value of 1~2s (empirical value).
  • Branches: next order is priority;occlusion constraints take priority(special-case candidates that hit simultaneously must be placed before wildcard candidates to prevent reverse-order infinite loops), the rest are arranged bydescending hit frequency; mutually exclusive branches rely on order, sorting relies on order_by, and same-screen combinations rely on And/Or。
  • loops and interrupts: put the loop body and exit in the same list and configure max_hit(Hard Guardrail 5); make random popups/loading into independent nodes and attach them to key waiting points with [JumpBack] (only fulfilled in the normal state); use anchorfor dynamic convergence across branches (silently skipped if unset, and all preceding paths must cover it; for details see references/flow-patterns.md）。
  • Layered waiting and retrying: express waiting with parameters, do not write self-referential structures; add retries only after a measured failure rate, preferring a single-node self-reference + max_hit; only when an independent budget or strategy escalation is truly needed should you create Retry / Fallback cloned nodes and note the difference surfaces (for details see references/flow-patterns.md）。
  • Failure path: configure every next list with timeout + a stable, hittable on_error fallback (no secondary fallback if the abnormal state fails again);on_error should only perform exception recovery, not normal branching; blind repeated clicks without recognition gating are forbidden; action errors should converge rather than self-referentially forcing through.

6. Self-check and handover

  • Four completeness questions and reachability: no isolated nodes, no anchor chain breaks, no unresolved references; confirm the main line can run, popups can be handled, loading can be waited through, andthe behavior when not in the target scenario is explicitly defined(skip or error). For projects with tests/ infrastructure, add recognition regression cases.
  • Cross-stage handover: Single-node validation and end-to-end acceptance → maafw-debug; task entry points and option wiring → maafw-interface; logic that JSON cannot express → maafw-custom。

Modification track (entry point for existing projects)

  1. Reconnaissance(scale to the size of the change, use indexes instead of reading everything): for minor edits, directly locate the target node and its upstream/downstream; for structural changes, first look at the directory tree and interface.json task list → script to extract a node-name index (listing root keys) → search by token keywords; for shared artifacts, first check general.json; before starting, define the change boundary.
  2. Search references: before changing a node name or asset path, search the entire repository—the consequences of missed changes fall into four tiers by reference location (load-time error / runtime failure / failure on call without rollback / silent disconnection or drift); the reference surfaces covered by each tier and cross-language get_anchor details are in references/naming.md 's reference verification table.
  3. Modify: incrementally modify to the same standard as steps 2–5 of the creation track.
  4. Self-check: reachability check + item-by-item verification against the anti-pattern checklist (see references/anti-patterns.md）。

In-depth reading (as needed)