关于 axiom-ios-graphics
面向 iOS GPU 渲染、图形编程、3D 显示和渲染性能工作的路由技能。它将任务分派到专门的 Metal、显示性能或 RealityKit 技能，涵盖迁移、API 参考与诊断。
主要功能
- 01路由 Metal 迁移与着色器任务
- 02引导 GPU 渲染问题诊断
- 03涵盖显示与帧率调优
- 04路由 RealityKit 和 SwiftUI 3D 工作
- 05区分架构、参考与故障排查
适用场景
- 01规划 OpenGL 或 DirectX 到 Metal 的移植
- 02查找移植后黑屏问题的指导
- 03排查帧率或 ProMotion 问题
- 04选择 SwiftUI 3D 内容的实现路径
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/axiom-ios-graphics确认已加载。
详细介绍
iOS 图形路由器
对于任何 GPU 渲染、图形编程、3D 内容显示或显示性能相关工作，必须使用此技能。
适用场景
在以下情况下使用此路由器：
- 将 OpenGL/OpenGL ES 代码移植到 Metal
- 将 DirectX 代码移植到 Metal
- 将 GLSL/HLSL 着色器转换为 Metal Shading Language
- 设置 MTKView 或 CAMetalLayer
- 调试 GPU 渲染问题（黑屏、颜色错误、崩溃）
- 评估转换层（MetalANGLE、MoltenVK）
- 优化 GPU 性能或解决热降频问题
- App 在 ProMotion 设备上卡在 60fps
- 配置 CADisplayLink 或渲染循环
- 可变刷新率显示问题
- 在非游戏类 SwiftUI App 中显示 3D 内容
- 使用 RealityKit 构建 AR 体验
- 在 SwiftUI 中使用 RealityView 或 Model3D
- 空间计算或 visionOS 3D 内容
路由逻辑
Metal 迁移
策略决策 → /skill axiom-metal-migration
- 转换层与原生重写之间的选择
- 项目评估与迁移规划
- 反模式与常见错误
- 应对截止期限压力的方案
API 参考与转换 → /skill axiom-metal-migration-ref
- GLSL → MSL 着色器转换表
- HLSL → MSL 着色器转换表
- GL/D3D API → Metal API 对照
- MTKView 设置、渲染管线、计算着色器
- 完整的 WWDC 代码示例
诊断 → /skill axiom-metal-migration-diag
- 移植后出现黑屏
- 着色器编译错误
- 颜色或坐标系错误
- 性能退化
- 各诊断路径的时间成本分析
显示性能
帧率与渲染循环 → /skill axiom-display-performance
- App 在 ProMotion（120Hz）设备上卡在 60fps
- MTKView 或 CADisplayLink 配置
- 可变刷新率优化
- 系统限制（低电量模式、限制帧速率、热限制、自适应电源）
- 帧预算计算（120Hz 下为 8.33ms）
- 测量实际帧率与报告帧率
RealityKit（非游戏类 3D 内容）
对于非游戏类 SwiftUI App 中的 3D 内容、AR 体验和空间计算，请使用 RealityKit 技能。对于游戏专用的 RealityKit 模式，请改用 ios-games 路由器。
架构、ECS 与最佳实践 → /skill axiom-realitykit
- Entity-Component-System 架构
- SwiftUI 集成：RealityView、Model3D、附件
- iOS 上的 AR：AnchorEntity 类型、SpatialTrackingSession
- 材质、物理、交互
- 性能优化
API 参考 → /skill axiom-realitykit-ref
- 完整的组件目录
- RealityView 和 Model3D API
- 材质系统（PBR、Unlit、Occlusion、Custom）
- RealityRenderer（Metal 集成）
故障排除 → /skill axiom-realitykit-diag
- 实体不可见、锚点无法跟踪
- 手势无响应、性能问题
- 材质问题、物理问题
决策树
- 选择转换层还是原生重写？→ metal-migration
- 将代码移植或转换为 Metal？→ metal-migration
- 需要 API 参考或着色器转换表？→ metal-migration-ref
- 设置 MTKView 或渲染管线？→ metal-migration-ref
- 移植后出现问题（黑屏、颜色错误）？→ metal-migration-diag
- 在 ProMotion 设备上卡在 60fps？→ display-performance
- CADisplayLink 或可变刷新率？→ display-performance
- 帧率不符合预期？→ display-performance
- 在 SwiftUI 中显示 3D 模型？→ axiom-realitykit
- 构建 AR 体验？→ axiom-realitykit
- 设置 RealityView 或 Model3D？→ axiom-realitykit-ref
- 3D 内容不可见或无法跟踪？→ axiom-realitykit-diag
- 对 RealityKit 内容进行自定义 Metal 渲染？→ axiom-realitykit-ref（RealityRenderer）
- 构建 3D 游戏？→ 改用 ios-games 路由器
避免自我合理化
| 想法 | 现实 |
|---|---|
| “我只要逐行翻译着色器就行了” | GLSL→MSL 在类型、坐标和精度方面存在差异。metal-migration-ref 提供了转换表。 |
| “MetalANGLE 会处理好所有事情” | 转换层在生产环境中有明显局限。metal-migration 会评估其中的权衡。 |
| “只是黑屏而已，可能是个简单的 bug” | 黑屏有 6 种不同原因。metal-migration-diag 可在 5 分钟内诊断，相比之下，盲目排查需要 30 分钟以上。 |
| “我的应用能以 60fps 运行，够用了” | ProMotion 设备支持 120Hz。display-performance 可配置正确的帧率。 |
| “我直接用 SceneKit 显示 3D 模型就行了” | SceneKit 已基本弃用。RealityView 和 Model3D 才是现代方案。axiom-realitykit 涵盖了 SwiftUI 集成。 |
| “只有一个 3D 模型，不需要 ECS” | Model3D 展示了无需 ECS 即可显示单个模型。RealityView 可扩展到复杂场景。axiom-realitykit 展示了这两种方案。 |
关键模式
metal-migration：
- 使用转换层（MetalANGLE）快速制作演示
- 在生产环境中改用原生 Metal 重写
- 状态管理差异（GL 有状态 → Metal 显式管理状态）
- 坐标系注意事项（Y 轴翻转、NDC 差异）
metal-migration-ref：
- 完整的着色器类型映射
- API 等效项对照表
- MTKView 与 CAMetalLayer 的选择
- 渲染管线设置模式
metal-migration-diag：
- GPU Frame Capture 工作流（2–5 分钟，相比之下盲目排查需要 30 分钟以上）
- 用于检查变量的着色器调试器
- 用于检测 API 误用的 Metal 验证层
- 性能回退诊断
display-performance：
- MTKView 默认使用 60fps（必须设置 preferredFramesPerSecond = 120）
- 使用 CADisplayLink preferredFrameRateRange 显式控制帧率
- 系统限制：低电量模式、限制帧速率、温度、Adaptive Power（iOS 26）
- 120Hz 的帧预算为 8.33ms
- UIScreen.maximumFramesPerSecond 不准确；CADisplayLink 才能反映真实情况
axiom-realitykit（非游戏 3D）：
- RealityView make/update 闭包模式
- 使用 Model3D 简单显示模型
- 使用 AnchorEntity 进行 AR 锚定
- 材质选择（SimpleMaterial、PBR、Occlusion）
axiom-realitykit-ref（API）：
- 使用 RealityRenderer 对 RealityKit 内容进行自定义 Metal 渲染
- 完整的材质属性参考
- RealityView 手势集成
示例调用
用户：“我应该使用 MetalANGLE，还是用原生 Metal 重写？”
→ 调用：/skill axiom-metal-migration
用户：“我正在将 projectM 从 OpenGL ES 移植到 iOS”
→ 调用：/skill axiom-metal-migration
用户：“如何将这个 GLSL 着色器转换为 Metal？”
→ 调用：/skill axiom-metal-migration-ref
用户：“第一次设置 MTKView”
→ 调用：/skill axiom-metal-migration-ref
用户：“移植后的应用显示黑屏”
→ 调用：/skill axiom-metal-migration-diag
用户：“移植到 Metal 后性能变差了”
→ 调用：/skill axiom-metal-migration-diag
用户：“我的应用在 iPhone Pro 上卡在 60fps”
→ 调用：/skill axiom-display-performance
用户：“如何将 CADisplayLink 配置为 120Hz？”
→ 调用：/skill axiom-display-performance
用户：“我的 Metal 应用中的 ProMotion 无法正常工作”
→ 调用：/skill axiom-display-performance
用户：“如何在我的 SwiftUI 应用中显示 3D 模型？”
→ 调用：/skill axiom-realitykit
用户：“我需要显示 USDZ 模型”
→ 调用：/skill axiom-realitykit
用户：“如何设置 RealityView？”
→ 调用：/skill axiom-realitykit-ref
用户：“我的 3D 模型没有显示在 RealityView 中”
→ 调用：/skill axiom-realitykit-diag
用户：“如何将 RealityRenderer 与 Metal 搭配使用？”
→ 调用：/skill axiom-realitykit-ref
用户：“我需要在应用中加入 AR”
→ 调用：/skill axiom-realitykit