用途：面向从 OpenGL 等迁移到 Metal 时出现的渲染与性能问题，提供系统化诊断流程。适用症状包括移植后黑屏、着色器编译失败、颜色或坐标错误、性能不如原实现、渲染伪影、GPU 工作期间崩溃。
主要能力：按症状给出决策树与常见修复，例如黑屏时检查渲染通道描述符、drawable、管线状态、绘制调用、资源绑定、顶点数据、NDC 坐标范围与清屏色；着色器错误时对照 GLSL 与 MSL 差异（如 texture 采样、mod 与 fmod、atan 与 atan2、inversesqrt 与 rsqrt、类型映射与显式转换）；颜色坐标异常时处理 Y 轴翻转、镜像、像素格式、sRGB、Z 范围与混合状态；性能回退时排查验证开销、每帧创建资源或管线、绘制调用过多、CPU-GPU 同步停顿、存储模式与三重缓冲；崩溃时排查资源生命周期、GPU 超时、越界访问与验证信息。
使用方式：第一步在 Xcode 的 Edit Scheme → Run → Diagnostics 中启用 Metal API Validation、Metal Shader Validation 与 GPU Frame Capture。随后按症状查决策树，配合 GPU Frame Capture（Cmd+Opt+Shift+G）、Instruments 的 Metal System Trace 与着色器调试器定位问题。文中给出的代码片段与命令保持原样，可直接参考。
适用场景：iOS 12+、macOS 10.14+、tvOS 12+ 上的 Metal 移植调试。
限制：资料未提供安装命令、收费方式与具体平台支持范围之外的细节；部分修复需结合项目实际验证。