MaaFW Debugging and Acceptance
Sections marked with TODO are experience samples to be supplemented through practice (incremental content that does not affect usability); for triage status, see skills/README.md.
Scope:
Real-time debugging and acceptance for MaaFW applications in development state with online devices (cold start / reconnection / disconnection recovery during acceptance are actively created by developers as acceptance methods, and do not mean leaving the development state). The precise semantics of fields (field names, parameters, default values, version support) and debugging commands are all routed to the version-locked protocol originals in
MaaLLMWiki (2.4-Control Method Description, 3.1-Task Pipeline Protocol, 3.3-ProjectInterfaceV2);
commands and result fields of runtime tools are routed to the documentation of the selected runtime tool itself (Agent defaults to maafw-live autonomously, see
references/tooling.md) — the protocol originals do not include tool commands. If both sources are unreachable, mark as "unverified". Post-hoc log and evidence diagnosis (user logs, Sentry, historical records) belongs to
in
MaaEvidenceKit, not this skill.
Hard Guardrails
- Evidence First: Every diagnostic conclusion must be supported by real-time observation evidence — current frame, recognition hit/miss and score, logs, comparison between box and click position; "maybe" must be converted into a verifiable hypothesis before testing, and conclusions based on guessing are prohibited (aligned with the exploration-first principle of maafw-pipeline).
- One Variable at a Time: Only one of threshold / ROI / template / parameter is changed at a time, and retest immediately after the change with records kept; result changes from simultaneous multiple changes cannot be attributed — this is the top discipline in debugging mode.
- Use Framework Pipeline: Screenshots and clicks for diagnosis must go through the framework's screenshot pipeline (observation base / framework screenshot API / runtime tool), external screenshot tools are not allowed — resolution and image space must be consistent with recognition input (the pixel space consistency principle inherits from maafw-pipeline asset standards).
- Position Only, Do Not Fix: This skill produces "root cause conclusion + evidence". Boundary: temporary changes for hypothesis verification followed by immediate retest are allowed (Hard Guardrail 2 "One Variable at a Time" is exactly for this purpose), but the deliverable is still conclusion + evidence. Fix implementation goes through handover (recognition/flow → maafw-pipeline, integration/options → maafw-interface, custom → maafw-custom; minor adjustments like ROI fine-tuning are already included in the modification track) — no structural changes while positioning.
- Judgment Hierarchy: Distinguish between call success (whether the command finishes execution), task success (task-level result + actual recognition hit), and business acceptance success (functional behavior meets expectations) — the three layers cannot replace each other, and call-layer signals (outer ok / exit code) cannot be used as task or acceptance conclusions; specific judgment fields and exit code semantics depend on the tool (for maafw-live, see judgment points in tooling.md). A single successful run ≠ stability — acceptance requires repeated runs, including cold start and reconnection scenarios.
- Preserve Debugging Scenes Promptly: Key frames during debugging should be promptly promoted to the key frame library (preserved by the observation base), as the scene cannot be reproduced once passed; offline post-hoc analysis is transferred to .
Workflow
0. Triage (Stratify Before Taking Action)
Locate the symptom to one of the five layers before entering the corresponding layer's process; for cross-layer symptoms, troubleshoot from the outermost layer first:
| Symptom | Layer |
|---|
| Device cannot connect / task cannot start / fails immediately at startup / options do not take effect | Configuration Layer |
| A node does not hit / hits the wrong target | Recognition Layer |
| Recognition hits but click does not land / swipe does not move / click position is offset | Action Layer |
| Stuck / infinite loop / goes to an unexpected node / terminates early | Flow Layer |
| Runs through but functional behavior is incorrect / pre-delivery check | Acceptance Layer |
The troubleshooting tree (symptom → check items → common root causes) can be found in references/diagnosis-tree.md; for evidence collection methods and tools for each layer's checks, see references/tooling.md — hard requirements do not change with tools, and tools are replaceable.
Before entering a layer, first determine the
execution tool (see "Working Modes" in tooling.md): Agent defaults to maafw-live autonomously, and perform self-checks with
/
/
before starting; if the tool is not installed or unavailable, select an alternative according to "Tool Replacement Judgment", and clearly state which capability is missing in the positioning conclusion — tool selection precedes any in-layer actions.
1. Configuration Layer (Device and Startup Pipeline)
Static first, then dynamic: For projects with dev-tools, first run
to clear structural errors before discussing runtime behavior. For "options not taking effect", first check option applicability filtering (the top cause based on experience; mechanism see maafw-interface), then check integration. For check items such as device connectivity, task entry, and dual logs of child processes, protocol field verification, and common root causes, see the configuration layer details in the troubleshooting tree.
2. Recognition Layer (Single-Node Verification)
Single-node verification + screenshot + hits/box expectations — for commands, refer to the selected tool's documentation (default maafw-live:
for recognition unit test,
for half-action execution on real device;
starts from entry and continues to next / on_error, which is not single-node verification — for isolation and side effect boundaries, see the default execution path in tooling.md). For node field semantics, refer to protocol 3.1. The first question is always
whether the target is in the frame, before discussing ROI / threshold / template; one variable at a time (Hard Guardrail 2). For criteria, empirical values, and recognition type adaptation, see the recognition layer details in the troubleshooting tree.
3. Action Layer (Recognition Success ≠ Effective Click)
The first question is always "where did it click": compare the recognition box with the actual click position pixel by pixel, before discussing target / offset. For target semantics, inverse traps, solutions to two common pitfalls, and retry gating, see the action layer details in the troubleshooting tree.
4. Flow Layer (Stuck Cause Attribution)
Use the execution model for attribution (the full execution model can be found in maafw-pipeline SKILL.md, which is the only map for attribution). The most common attribution error: when you want to adjust the waiting time for a node to be recognized, you modify the
/
of its
previous node. For three checks for infinite loops, early termination, and renamed disconnection surface list, see the flow layer details in the troubleshooting tree.
5. Acceptance Layer (End-to-End)
Four completeness questions (especially "behavior when not in the target scenario is explicitly defined") + judgment hierarchy (Hard Guardrail 5) + repeated runs (including cold start / reconnection / disconnection recovery); acceptance is divided into two levels — Pipeline business process acceptance (can be undertaken by runtime tools, conclusions must record preconditions and Agent status) and target Client integration acceptance (actually goes through the Client's pretask, assembly, Agent startup, and task entry, tool run-through cannot replace it — boundary see tooling.md). For override effect verification and test precipitation, see the acceptance layer details in the troubleshooting tree.
6. Handover
The positioning conclusion must include: symptom → layer → root cause hypothesis → evidence (frame/log/score/comparison) → suggested fix direction → target skill for handover. Fixes are transferred to maafw-pipeline / maafw-interface / maafw-custom; offline evidence analysis is transferred to maa-evidence.
Further Reading (On Demand)
- references/diagnosis-tree.md — Troubleshooting Tree: symptom → check items → common root causes (configuration layer details, silent disconnection surface list, threshold and ROI empirical values)
- references/tooling.md — Evidence Collection Methods and Tool Matrix: working modes, maafw-live default execution path and judgment points, alternative tool capability mapping, check points for each layer and tool replacement judgment
TODO (To Be Supplemented Through Practice — Incremental Experience Samples, Sole Checklist)
- Log interpretation rules for each branch of the troubleshooting tree (log snippet → conclusion interpretation samples)
- Recognition slowdown (performance) troubleshooting branch; debugging points for ColorMatch / And / Or / self-trained model nodes
- Standard minimum reproduction process and evidence snapshot checklist for each layer (including the "minimum evidence sequence" template for the flow layer)
- Acceptance record template (verification object, scope, actual result, evidence, implementation fingerprint — aligned with the tested semantics of state-plan, pending its schema freeze)
Inline TODOs in the troubleshooting tree / tool documentation are only position markers, and this section is the sole checklist and completion criterion.