MaaFW Custom Development

Use Custom to supplement logic that cannot be expressed by Pipeline: reading external state, cross-node data transfer, dynamic counting, complex judgments, and custom recognition algorithms. Do not write binding class signatures and context API from memory — always route to the bindings / native-api index of MaaLLMWiki (version locked, source-referenced; when the

maallmwiki

skill is installed, it will handle the complete routing process).

Hard Guardrails

Prefer pipeline over custom (default direction, determined by cost asymmetry rather than preference):
- Why prefer pipeline: The outer layer of custom nodes is still scheduled and observed by the engine — next candidate order (first hit first executed),
```
max_hit
```
  ,
```
on_error
```
  , focus, and option's pipeline_override still take effect as usual, and sub-processes started by
```
run_task
```
  are also executed by the engine. What loses automatic constraints is the inside of the callback — internal loops / waits / network IO are not expanded into a node graph, node
```
timeout
```
  cannot interrupt a blocked callback, and time consumption, cancellation, retries, and internal state are all managed by yourself, leaving only logs for the toolchain.
- Always use pipeline for visually determinable waits / clicks / swipes / text finding / loops / branches — loop = next ring + exit + max_hit (use
```
repeat
```
  /
```
repeat_delay
```
  /
```
repeat_wait_freezes
```
  for fixed number of repetitions, v5.3+), branch = next order + masking.
- Only use Custom for: reading runtime data outside the screen (files, network, process status, time) or control flow based on such data; judgments that cannot be expressed by recognition / action fields; external calls.
- Two hard boundaries of field expressiveness (these account for the majority of custom usage in empirical projects):
  - And / Or are boolean combinations — no numerical comparison, no cross-node arithmetic (numerical comparison and multi-node numerical expressions are the territory of custom); the only data flow during combination is box:
    box_index
    selects output,
    sub_name
    passes filtered box as ROI, Or takes the hit box;
  - max_hit
    only increments, and pipeline fields cannot read or clear the hit count — you can use
    get_hit_count
    /
    clear_hit_count
    in custom (scope: shared by the current task and its
    run_task
    subtasks); there is still no field channel for cross-node "data" —
    anchor
    is a node name variable (three states: write / clear / reference), not data storage.
- Reverse signals that it's time to switch to custom: when you start stacking cloned nodes to express a piece of logic, the node graph becomes bloated and hard to read, or you start needing to modify parameters or counts at runtime (override / state-type standard components appear frequently) — it's better to switch than to keep splitting.
- If you are unsure about the criteria, go back to
```
maafw-pipeline
```
  and try splitting the nodes first.
Fail explicitly, and distinguish three semantics:
- CustomRecognition returns miss = this candidate is not hit — polling continues to try subsequent candidates, and if all candidates miss in the entire round, it will trigger the host's on_error after the host node's
```
timeout
```
  (not triggered immediately);
- CustomAction returns failure = triggers the on_error of the node where the action is located; do not swallow implementation exceptions, return failure explicitly — silent false success is a troubleshooting nightmare;
- Empty return value semantics on the binding side must be checked before writing (example: Python action
```
run
```
  returning None is equivalent to success, recognition
```
analyze
```
  returning None is equivalent to miss — forgetting to write return on the action side is silent false success; subject to binding routing);
- Directly calling
```
context.run_recognition()
```
  only returns the recognition result, and the error branch is handled by the caller.
Registration names are character-by-character consistent: The registration name (the string in the decorator or registry) is exactly the same as the pipeline node reference, case-sensitive. Synchronize all registration points when renaming — decorator/registry, pipeline references (modify pipeline usage first, then registration), and include enum if there is Schema infrastructure; node name references in custom code (entries of
```
run_task
```
/
```
run_recognition
```
/
```
run_action
```
, targets of
```
override_next
```
) are also in the synchronization scope — calls will fail directly (you must check the return value), not silent disconnection; asset paths are also in the synchronization scope, but the framework will not report errors for you — custom code reading images must self-check the loading result (empty image means failure), and missing modifications mostly manifest as silent idling (see naming.md of maafw-pipeline for the full list of reference points).
Signature Routing: The parameter structure of
```
analyze
```
/
```
run
```
and context API evolve with the binding version, subject to the routing result. The examples in this article are only for illustration; do not rely on hooks that the framework does not promise (such as stop / interrupt callback — whether they exist and what they are called are subject to the routing result). The framework will not actively interrupt callbacks — for long loops, self-check stop conditions, set timeouts for external IO, and use language mechanisms such as finally / RAII for resource cleanup.
- Context Capabilities (what levers you have after using custom; names are subject to binding routing):
```
run_task
```
  /
```
run_recognition
```
  /
```
run_action
```
  (run by node, recognition and action are paired);
```
run_recognition_direct
```
  /
```
run_action_direct
```
  (use engine algorithms directly without creating nodes);
```
wait_freezes
```
  (engine waits for the screen to freeze, takes screenshots internally);
```
override_pipeline
```
  /
```
override_next
```
  /
```
override_image
```
  (three patch tools);
```
get_node_data
```
  (read current valid node definition, including patches);
```
set_anchor
```
  /
```
get_anchor
```
  (anchor read/write);
```
get_hit_count
```
  /
```
clear_hit_count
```
  (count read/clear);
```
get_tasker
```
  (get controller / resource — prerequisite for screenshot chain);
```
clone
```
  (fork context).
State Minimization: Try to be stateless in custom; if cross-call memory is really needed (such as a "first execution only" sentinel), indicate the lifecycle — class state is shared across tasks during the lifetime of the agent process, and task re-entry will carry the last value.

Workflow

Determine host and registration path (prior to all implementation decisions): Whether in-process registration is possible is determined by who owns the main program — see references/agent-mode.md for details, agent segment wiring and architecture.
Type Determination:
- Custom recognition algorithm →
```
CustomRecognition
```
  (
```
analyze
```
  returns hit box);
- External calls / complex actions →
```
CustomAction
```
  (
```
run
```
  returns success or failure);
- Cross-cutting hooks (global checks, failure guidance) → sink channel instead of scattered into actions (see "Event Listening" in patterns.md for details).
Special cases are not included in the above categories: Non-standard device control uses
```
CustomController
```
— it is accessed as a controller rather than registered (subclass + factory constructed and then bound to Tasker), and is only feasible when you control the host process; the framework does not provide controller creation in the agent child process (see agent capabilities in agent-mode.md).
Minimum Registration Closed Loop: First connect the minimum node (DoNothing + logs) to get through the "registration → pipeline reference → being called" flow, then fill in the implementation.
File Creation and Implementation:
- Split files by business capability, aligned with the module directory of resource (file form follows language idioms, see "Module Boundaries" in references/patterns.md for criteria);
- Common reusable components go into the shared component directory; register at a single registration point (decorator or centralized registry);
- Parameters enter from pipeline's
```
custom_action_param
```
  /
```
custom_recognition_param
```
  (JSON), and are used after being processed for type / required / default values and runtime validation by parsing utility functions, do not take fields directly; the implementation comes with behavior contract documentation (docstring / comments and other language conventions) — clearly write expected behavior and parameter semantics.
Reuse instead of Rewrite:
- When recognition / action is needed in custom, prioritize referencing existing pipeline nodes —
```
context.run_recognition("<node_name>", image)
```
  directly runs the recognition of a node;
- Image source depends on usage: use
```
argv.image
```
  for the current screen in recognition callback; for a new screen after an action, actively take a screenshot through the existing controller and get the image after it is completed (example form
```
context.tasker.controller.post_screencap().wait().get()
```
  , name is subject to binding routing);
```
cached_image
```
  belongs to the controller, is the cache of the latest completed screenshot, and will not refresh by itself — use only when timeliness is acceptable;
- The recognize → operate → re-recognize rule also applies in custom (see flow-patterns of maafw-pipeline).
Failure, Cancellation and State Scope: See Hard Guardrail 2 for the three failure semantics; see Hard Guardrail 4 for cancellation strategies for long loops and external IO; indicate the lifecycle of cross-call state (Hard Guardrail 5); specify the target, scope and lifecycle of override patches (see "State and Scope" in patterns.md).
Validation: Logs include node name + input parameter summary + result summary (this is the only clue for troubleshooting); after unit validation, proceed to
```
maafw-debug
```
for single-node flow and end-to-end testing.

Review Checklist

Criteria: Can this logic really not be expressed by pipeline? Is process control hidden in custom (the inside of the callback is not expanded into a node graph)?
Naming is self-explanatory: registration names are aligned with pipeline node naming style (conventionally PascalCase), unified within the project.
Parameter baseline: entry runtime validation — clear type / required / default value / error behavior; projects with Schema infrastructure synchronize enum and registration names, and confirm that the validation entry is really covered (creating a file itself does not generate validation).
Failure path: distinguish the three failure semantics; no bare
```
except: pass
```
; binding semantics of empty return values have been checked.
Blocking and cancellation: long loops have stop checks, external IO has timeouts, cleanup has mechanisms such as finally / RAII.
Registration points: when renaming, modifying or deleting, synchronize all: pipeline usage → registration points → (include enum if there is Schema) → node name references and asset paths in custom code.

maafw-custom

NPX Install

Tags

SKILL.md Content (Chinese)

MaaFW Custom Development

Hard Guardrails

Workflow

Review Checklist

Further Reading (On Demand)