Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.
MaaFW 调试与验收
标注 TODO 的节为实践待补的经验样本（增量内容，不影响可用性）；分诊状态见 skills/README.md。
定位：开发态、设备在线的实时调试与验收（验收环节的冷启动 / 重连 / 断线恢复由开发者主动制造离线与重连窗口，属验收手段而非离开开发态）。字段精确语义（字段名、参数、默认值、版本支持）与调试命令一律路由 MaaLLMWiki 版本锁定的协议原文（2.4-控制方式说明、3.1-任务流水线协议、3.3-ProjectInterfaceV2）；运行工具的命令与结果字段路由所选运行工具自身文档（Agent 自主默认 maafw-live，见 references/tooling.md）——协议原文不含工具命令。两类来源不可达时标记"未验证"。事后日志与证据诊断（用户日志、Sentry、历史记录）归 MaaEvidenceKit 的 maa-evidence，不是本 skill。
硬护栏
- 证据优先：每个诊断结论必须有实时观测证据——当前帧、识别命中/未命中与得分、日志、box 与落点比对；「可能是」必须转成可验证假设再测，不许凭猜下结论（与 maafw-pipeline 的探索优先同源）。
- 一次一个变量：阈值 / ROI / 模板 / 参数每次只改一个，改完立即复测并留记录；多处同时改后结果变化无法归因——调试态第一纪律。
- 走框架链路：诊断用截图与点击必须走框架截图链路（观测底座 / 框架截图 API / 运行工具），不用外部截图工具——分辨率与图像空间必须与识别输入一致（像素空间一致原则继承 maafw-pipeline 素材标准）。
- 只定位不修复：本 skill 产出「定位结论 + 证据」。边界：为验证假设可临时改并立即复测（硬护栏 2「一次一个变量」正是此用法），但交付物仍是结论 + 证据，修复落盘走交接（识别/流程 → maafw-pipeline，接线/选项 → maafw-interface，custom → maafw-custom；修改轨已含 ROI 微调这类小修）——不边定位边做结构性改动。
- 判定分级：区分调用成功（命令是否执行完）、任务成功（任务级结果 + 实际识别命中）、业务验收成功（功能行为符合预期）——三层互不顶替，调用层信号（外层 ok / 退出码）不能当任务或验收结论；具体判定字段与退出码语义随工具（maafw-live 见 tooling.md 判定要点）。一次跑通 ≠ 稳定——验收要重复、含冷启动与重连。
- 调试现场及时留存：调试过程中的关键帧及时升格进关键帧库（观测底座留存），现场过了就过了；脱机的事后分析转
maa-evidence。
工作流
0. 分诊（先分层再动手）
按症状定位到五层之一再进对应层流程；跨层症状按最外层先排查：
| 症状 | 层 |
|---|---|
| 设备连不上 / 任务起不来 / 启动即失败 / 选项没生效 | 配置层 |
| 某节点不命中 / 命中错 | 识别层 |
| 识别命中但点击没落地 / 滑动没动 / 落点偏移 | 动作层 |
| 卡死 / 死循环 / 走到不该走的节点 / 提前终止 | 流程层 |
| 跑通了但功能行为不对 / 交付前检查 | 验收层 |
排障树（症状 → 检查项 → 常见根因）见 references/diagnosis-tree.md；各层检查的取证手段与工具见 references/tooling.md——硬要求不随工具变，工具可替换。
进层之前先定执行工具（tooling.md「工作模式」）：Agent 自主默认 maafw-live，动手前 version / env / probe 自检；未安装或不可用时按「工具替换判定」选定替代、并在定位结论里明说缺哪项能力——工具选择先于任何层内动作。
1. 配置层（设备与启动链路）
先静态后动态：有 dev-tools 的项目先 pnpm check 清结构错误，再谈运行时行为。「选项没生效」先查 option 适用性过滤（头号原因，经验值；机制见 maafw-interface），再查接线。设备连通、任务入口、子进程双日志等检查项、协议字段核对与常见根因见排障树配置层细节。
2. 识别层（单节点验证）
单节点验证 + 截图 + hits/box 期望——命令查所选工具文档（默认 maafw-live：reco 识别单测、--act 真机执行动作半；run 从 entry 起跑会继续走 next / on_error、不是单节点验证——隔离与副作用边界见 tooling.md 默认执行路径），节点字段语义查 3.1 协议。第一问永远是目标在不在帧里，再谈 ROI / 阈值 / 模板；一次一个变量（硬护栏 2）。判据、经验值与识别类型适配见排障树识别层细节。
3. 动作层（识别成功 ≠ 点击生效）
第一问永远是「点到哪了」：识别 box vs 实际落点逐像素比对，再谈 target / offset。target 语义、inverse 陷阱、两坑治法与重试门控见排障树动作层细节。
4. 流程层（卡死归因）
用执行模型归因（执行模型全文见 maafw-pipeline SKILL.md，这是归因的唯一地图）。最常见归因错误：想调某节点被识别的等待时长，改的是它上一节点的 timeout / on_error。死循环三查、提前终止与改名失联面清单见排障树流程层细节。
5. 验收层（端到端）
完备性四问（尤其「不在目标场景时的行为已显式定义」）+ 判定分级（硬护栏 5）+ 重复跑（含冷启动 / 重连 / 断线恢复）；验收分两档——Pipeline 业务流程验收（运行工具可承担，结论须记录前置条件与 Agent 状态）与目标 Client 集成验收（实际经 Client 的 pretask、装配、Agent 启动与任务入口，工具跑通不能替代——边界见 tooling.md）。override 生效验证与测试沉淀见排障树验收层细节。
6. 交接
定位结论必须包含：症状 → 层 → 根因假设 → 证据（帧/日志/得分/比对）→ 建议修复方向 → 交接目标 skill。修复转 maafw-pipeline / maafw-interface / maafw-custom；离线证据分析转 maa-evidence。
深入阅读（按需）
- references/diagnosis-tree.md — 排障树：症状 → 检查项 → 常见根因（配置层细节、静默失联面清单、阈值与 ROI 经验值）
- references/tooling.md — 取证手段与工具矩阵：工作模式、maafw-live 默认执行路径与判定要点、替代工具能力对应、各层检查要点与工具替换判定
TODO（实践待补——经验样本类增量，唯一清单）
- 排障树各分支的日志判读细则（日志片段 → 结论的判读样本）
- 识别慢（性能）排查分支；ColorMatch / And / Or / 自训模型节点的调试要点
- 各层最小复现标准流程与取证快照清单（含流程层「最小取证序列」模板）
- 验收记录模板（验证对象、范围、实际结果、证据、实现指纹——对齐 state-plan 的 tested 语义，待其 schema 冻结）
排障树 / 工具文档中的内联 TODO 仅为位置标记，以本节为唯一清单与完成判据。
