Sections marked TODO areempirical samples pending supplementation(incremental content, does not affect usability); for triage status see ../README.md。
Scope:real-time debugging and acceptance in development state with device online(cold start / reconnection / disconnection recovery during acceptance is performed by the developer actively creating offline and reconnection windows; this is an acceptance method rather than leaving the development state):
- Protocol semantics routing: precise field semantics (field names, parameters, default values, version support) and debug commands are all routed to MaaLLMWiki the version-locked protocol source text (
2.4-控制方式说明、3.1-任务流水线协议、3.3-ProjectInterfaceV2协议）； - Runtime tool routing：the runtime tool's commands and result fieldsare routed to the selected runtime tool's own documentation (Agent defaults autonomously to maafw-live, see references/tooling.md) — the protocol source text does not contain tool commands;protocol source text and tool documentationif either is unreachable, mark as "unverified";
- Post-hoc diagnosis boundary: post-hoc log and evidence diagnosis (user logs, Sentry, historical records) belongs to MaaEvidenceKit 's
maa-evidence, not this skill.
Hard guardrails
- Evidence first: every diagnostic conclusion must have real-time observational evidence — current frame, recognition hit/miss and score, logs, box and click-point comparison; "possibly" must be turned into a verifiable hypothesis and then tested; no concluding by guesswork (same origin as maafw-pipeline's exploration-first principle).
- One variable at a time: change only one of threshold / ROI / template / parameter at a time, retest immediately after the change and keep a record; if multiple things are changed at once, the resulting change cannot be attributed — the first discipline of the debugging state.
- Follow the framework pipeline: diagnostic screenshots and clicks must go through the framework screenshot pipeline (observation base / framework screenshot API / runtime tool), not external screenshot tools — resolution and image space must be consistent with the recognition input (the pixel-space consistency principle inherits maafw-pipeline's SKILL.md asset standard).
- Locate only, do not fix: this skill produces "localization conclusion + evidence". Boundary:to verify a hypothesis, temporary changes may be made and retested immediately(hard guardrail 2 "one variable at a time" is exactly this usage), but the deliverable is still conclusion + evidence,fixes are persisted via handoff(recognition/pipeline → maafw-pipeline, wiring/options → maafw-interface, custom → maafw-custom; the modification track already includes small fixes like ROI fine-tuning) — do not make structural changes while localizing.
- Verdict grading: distinguishcall success(whether the command completed execution),task success(task-level result + actual recognition hit),business acceptance success(functional behavior meets expectations) — the three layers do not substitute for one another; call-layer signals (outer ok / exit code) cannot be used as task or acceptance conclusions; the specific verdict fields and exit code semantics depend on the tool (for maafw-live see references/tooling.md Judgment points). Running through once ≠ stable—acceptance must be repeated, including cold start and reconnection.
- Preserve debugging scenes promptly：Key frames during debugging should be promptly promoted into the key frame library (preserved in the observation foundation); once the scene is gone, it's gone; offline post-mortem analysis turns to
maa-evidence。
Workflow
0. Triage (layer first, then act)
Locate by symptom to one of the five layers, then enter the corresponding layer process; for cross-layer symptoms, investigate from the outermost layer first:
| Symptom | Layer |
|---|---|
| Device can't connect / task won't start / fails immediately on startup / options don't take effect | Configuration layer |
| A node doesn't hit / hits the wrong thing | Recognition layer |
| Recognition hits but click doesn't land / swipe doesn't move / landing point is offset | Action layer |
| Stuck / infinite loop / goes to nodes it shouldn't / terminates early | Flow layer |
| Runs through but functional behavior is wrong / pre-delivery check | Acceptance layer |
For the troubleshooting tree (symptom → check items → common root causes), see references/diagnosis-tree.md; for the evidence-gathering methods and tools for checks at each layer, see references/tooling.md—hard requirements do not change with tools; tools are replaceable.
Before entering a layer, first decideExecution tool（references/tooling.md"Working mode"): Agent autonomous default is maafw-live; before acting, version / env / probe self-check; if not installed or unavailable, select a replacement according to the "Tool Replacement Judgment" and explicitly state in the localization conclusion which capability is missing—tool selection precedes any in-layer action.
1. Configuration layer (device and startup chain)
Static first, then dynamic: for projects with dev-tools, first pnpm check clear structural errors, then discuss runtime behavior. For "options don't take effect", first check option applicability filtering (the number one cause, empirical value; for the mechanism see maafw-interface's options.md), then check wiring. For check items such as device connectivity, task entry, subprocess dual logs, protocol field verification, and common root causes, see references/diagnosis-tree.md configuration layer details.
2. Recognition layer (single-node verification)
Single-node verification + screenshot + hits/box expectations—for commands, check the selected tool's documentation (default maafw-live:reco recognition unit test,--act real-device action half;run starting from entry will continue through next / on_error, not single-node verification—for isolation and side-effect boundaries see references/tooling.md default execution path), for node field semantics check the "Task Pipeline Protocol". The first question is alwaysIs the target in the frame, then discuss ROI / threshold / template; one variable at a time (hard guardrail 2). For criteria, empirical values, and recognition type adaptation see references/diagnosis-tree.md recognition layer details.
3. Action layer (successful recognition ≠ click takes effect)
The first question is always "where did it click": compare the recognition box vs the actual landing point pixel by pixel, then discuss target / offset. For target semantics, the inverse trap, treatments for the two pitfalls, and retry gating see references/diagnosis-tree.md action layer details.
4. Flow layer (stuck attribution)
Use the execution model for attribution (for the full execution model see maafw-pipeline's SKILL.md, this is the only map for attribution). The most common attribution error: wanting to adjust the wait duration for a node to be recognized, but changing itsprevious node's timeout / on_error. For the three checks for infinite loops, early termination, and the list of rename-disconnection surfaces see references/diagnosis-tree.md flow layer details.
5. Acceptance layer (end-to-end)
The four completeness questions (especially "behavior when not in the target scenario is explicitly defined") + grading of verdicts (hard guardrail 5) + repeated runs (including cold start / reconnect / disconnection recovery); acceptance has two tiers — Pipeline business-process acceptance (can be undertaken by running tools, and the conclusion must record preconditions and Agent state) and target Client integration acceptance (actually going through the Client's pretask, assembly, Agent startup, and task entry; a tool running successfully cannot substitute for it — for boundaries see references/tooling.md). For override effectiveness verification and test accumulation see references/diagnosis-tree.md acceptance layer details.
6. Handoff
The localization conclusion must include:symptom → layer → root-cause hypothesis → evidence (frames/logs/scores/comparison) → recommended fix direction → handoff target skill. Fixes go to maafw-pipeline / maafw-interface / maafw-custom; offline evidence analysis goes to maa-evidence.
In-depth reading (as needed)
- references/diagnosis-tree.md — troubleshooting tree: symptom → check items → common root causes (configuration-layer details, list of silent disconnection surfaces, threshold and ROI empirical values)
- references/tooling.md — evidence-collection methods and tool matrix: working modes, maafw-live default execution path and key verdict points, mapping of alternative tool capabilities, key check points for each layer and tool-replacement decisions
TODO (to be supplemented through practice — incremental empirical-sample category, the sole list)
- Log-interpretation details for each branch of the troubleshooting tree (interpretation samples from log fragments → conclusions)
- Troubleshooting branch for slow recognition (performance); debugging key points for ColorMatch / And / Or / self-trained model nodes
- Minimum reproduction standard procedure and evidence snapshot list for each layer (including the "minimum evidence-collection sequence" template for the process layer)
- Acceptance record template (verification object, scope, actual results, evidence, implementation fingerprint — aligned with state-plan's tested semantics, pending its schema freeze)
Inline TODOs in the troubleshooting tree / tool documentation are only position markers; this section is the sole list and completion criterion.