调试边界与初始定位
配置和资源问题应先用 validate、expand、explain 与 lock 工具定位，不需要启动后端。运行问题再区分 Application 生命周期、Plugin binding、UniRoboSim 能力和具体 Provider 行为，避免直接把所有异常归因于物理引擎。
运行时检查应在完整 tick 边界进行。Pause 保留世界，用于检查 scene、frame、geometry、control target、插件状态和输出；single-step 只推进一个受控边界，不等同于直接调用后端 step()。
Application visualization API 发布点、线、frame、文本、metric 与 event 等稳定描述。Provider 可以原生绘制，Server 可以远程传输，记录系统可以保存；发布者不依赖具体 UI。
截图和视频只用于记录可见行为，应与结构化 run ID、plan digest、generation、tick、插件状态和错误日志一起保存。图片本身无法证明使用了哪份配置或资源。
| 现象 | 最先检查 |
|---|---|
| Run 无法编译 | 配置诊断、Project、Registry 与资源 digest |
| 能编译但无法 prepare | Provider/插件发现与能力要求 |
| reset 后出现旧命令 | generation、Operation 与订阅清理 |
| UI 有内容但控制失败 | control targets、binding 与 authority |
| 输出不完整 | 插件终结、staging 校验与发布状态 |
公共可视化门面见Application SDK，远程表面见Server REST API。
分层排查流程
编译层。 先运行 validate、expand、explain 和 Lock verify。记录输入路径、结构化错误、组件 release、资源摘要与 plan digest。这里失败时不要启动后端，也不要修改 Provider 来容忍无效 Plan。
构造与生命周期层。 Plan 成功后，分别观察 open/prepare/start 的 Application snapshot、Provider identity、插件 status 与 failure records。确认错误发生在 Core 服务建立、某个插件 hook 还是 Provider world creation。
稳定服务层。 检查 scene catalog、frame、geometry、state、capabilities 与 control targets 是否在相同 generation/revision 上一致。若公共服务已经错误，再把最小输入交给对应服务/Provider；若输出正确，则继续检查消费插件或接口。
控制与数据层。 对控制保存 request、authority、targets、Operation ID/终态与 applied frame；对录制保存通道准入、队列 gap、finalizer、validation/commit receipt。不要只看“机器人动了”或“目录里有文件”。
展示层。 最后检查 TUI、Web、MCP、Visualizer 或视频。若结构化状态正确而显示错误，才属于界面投影；不要因为前端没有刷新就修改 Runtime generation。
最小复现与运行时观察
保留同一 Run/Lock 与资源摘要，逐步移除不相关插件、实体和通道，但不要更换导致问题消失的核心输入。明确记录最小复现仍需要的 Provider、launch profile、GPU/GUI 和外部服务。
若问题只在某后端出现，用相同稳定组件语义对比其他 Provider，并保存两侧 catalog/targets，而不是用两个不同机器人资产得出后端结论。
暂停与单步。 Pause 应发生在完整 tick 边界并保留世界；single-step 推进一个受控物理边界。每次操作前后保存 snapshot、generation、tick、state/target revision 与关键实体值。直接在调试器里调用后端 step() 会绕过插件、控制和记录，因此不能作为 FastSim 行为证据。
Visualization primitive。 点、线、frame、文本、metric 与 event 适合解释规划目标、碰撞几何、坐标变换和控制误差。发布者写稳定描述，Provider 可原生绘制，Server 可传输，记录系统可保存。可视化失败不应改变算法或物理状态。
证据包与问题归属
- Run 与 Lock、Core/插件/Provider 版本和 plan digest；
- 复现命令、退出码、结构化日志和时间范围；
- Application/Plugin snapshot、run/generation/tick；
- 实体 catalog、frame/geometry/targets 与 Operation；
- 输出 validation/commit receipt；
- 说明性截图或视频，以及它对应的结构化时间点；
- 未运行的 GPU、GUI、硬件或其他 Provider 门禁，明确标记未验证。
常见误判包括：画面卡住可能是 Runtime paused、媒体订阅停止或渲染阻塞，三者修复位置不同；控制请求超时可能仍在执行；文件存在不等于已原子提交；截图显示某机器人不等于使用了预期组件 release；同样的异常文本也可能来自上游无效输入或下游消费失败。
完成分层定位后，将修复交给最早违反合同的层，并添加该层单元测试与一条跨边界集成验证。