AI导哈

Metal着色器开发工具

一个用于AI辅助的Metal着色器开发的完整系统，支持实时编写、修改和视觉迭代着色器。

  • by erichowens
  • Swift
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 erichowens/metal-shader-mcp

使用说明

金属着色器 MCP - 克劳德的着色器开发游乐场

一个完整的AI辅助金属着色器开发系统，其中Claude能够实时编写、修改着色器，并进行可视化迭代。

项目概述

新增：对导出的帧可选择进行Core ML后处理。配置详情请参阅下文。

注：旧的文件桥接方式（将命令写入 Resources/communication）正在被弃用，取而代之的是严格的 MCP 客户端。请参阅下面的弃用通知。 Metal Shader MCP 是一个 macOS 上的 SwiftUI + Metal 实验场，它提供了一个规范化的流程来迭代着色器、展示视觉效果并支持持续集成（CI）。计划中将添加一个 MCP 层，以便 AI 助手能够与应用程序进行交互（编译、预览、截图），但目前主要的入口还是这个 macOS 应用程序，您可以本地编译并运行它。

当前状态（截至2025年10月2日）

  • macOS 应用（使用 SwiftUI + Metal）可在本地和持续集成（CI）环境中构建和运行。
  • 使用简易渲染器和截图/导出辅助工具进行实时着色器编辑。
  • 会话浏览器（历史记录选项卡）捕获每个会话的快照（代码 + 图像 + 元数据）。
  • CI（持续集成）强制执行：构建、测试、视觉证据捕获、WARP工作流合规性检查、UI冒烟测试（标签选择/状态）、文档检查。
  • 分支保护与合并策略所有CI检查必须通过后才能合并到主分支。直接向主分支推送会被拒绝。更改必须通过带有绿色检查标记的PR（Pull Request）进行。覆盖检查需要用户明确的决定，且不建议这样做。
  • 单次提交PR策略：一次只能有一个活跃的（非草稿）核心PR；其他PR保持草稿状态，直至当前活跃的PR被合并。

路线图

  • MCP服务器集成，以便从工具中驱动macOS应用程序（编译/预览/快照）。
  • 在多种分辨率下进行基于基线的视觉回归测试。
  • 包含名称、描述和持久元数据的着色器库（参见WARP/元数据规则）。
  • 导出包含参数扫描和性能分析的管道（PNG/视频）。
  • 在CI（持续集成）中用于自动文件发现的Xcode项目或Swift包目标。

快速入门（macOS 应用）

  • 先决条件：需配备Xcode（最新稳定版）的macOS系统以及支持Metal的设备。
  • 本地构建并运行：
swiftc -o MetalShaderStudio \
  ShaderPlayground.swift AppShellView.swift HistoryTabView.swift SessionRecorder.swift \
  Sources/MetalShaderCore/MCPClient.swift \
  -framework SwiftUI -framework MetalKit -framework AppKit -framework UniformTypeIdentifiers \
  -parse-as-library

./MetalShaderStudio --tab history

特点/特性

  • 现场精选集实时编译Metal着色器并报告错误
  • 热重载文件更改时自动重新编译
  • **性能分析（或性能剖析）**测量帧率（FPS）、GPU/CPU时间以及内存使用情况
  • 预览引擎实时着色器预览，支持WebSocket更新
  • 着色器模板内置的着色器示例和效果
  • MCP集成与人工智能助手无缝集成

安装

  • macOS 应用（当前版本）：请参阅上方的快速入门指南。
  • MCP服务器（计划中）：现有的npm脚本是为未来的MCP服务器预留的占位符。它们目前并不需要运行macOS应用程序。
# Planned (MCP server), not required for the macOS app today
npm install
npm run build

无头渲染器（用于数据集和持续集成）

在不启动应用程序的情况下将着色器渲染为PNG格式：

swift run ShaderRenderCLI --shader-file shaders/plasma_fractal.metal --out data/sample.png --width 256 --height 256 --time 0.0

Core ML 后处理（可选）

  • 配置于 Resources/communication/coreml_config.json （提供模板）。
  • 提供一个模型于 Resources/models/YourModel.mlmodelc 或者 .mlmodel。
  • 当存在且有效时，导出数据将在保存前通过模型进行传递。

配置字段：

  • modelPath模型路径（例如。， Resources/models/StyleTransfer.mlmodelc）
  • inputName图像输入特征名称（例如。， image）
  • outputName输出图像特征名称（例如。， stylizedImage)
  • width， height模型输入维度

注：用户界面保持不变；此更改仅影响导出的帧和会话快照。

使用方法

启动MCP服务器

npm start

开发模式

npm run dev

可用的MCP工具

  1. 编译着色器编译Metal着色器代码

    • 支持AIR、metallib和SPIRV目标
    • 优化选项
    • 错误和警告报告

  2. 预览着色器生成预览图像

    • 实时渲染
    • 可定制分辨率
    • 触控交互支持

  3. 更新制服更新着色器参数

    • 时间、触摸位置、分辨率
    • 自定义统一值

  4. **性能配置文件（或性能概况）**性能指标

    • FPS测量
    • GPU/CPU时间追踪
    • 内存使用监控

  5. 热重载文件监视

    • 自动重新编译
    • WebSocket 通知
    • 开发仪表板

  6. 验证着色器语法验证

    • 错误检测
    • 性能优化建议
    • 代码分析

着色器开发

示例：万花筒效果

#include <metal_stdlib>
using namespace metal;

fragment float4 kaleidoscopeFragment(
    VertexOut in [[stage_in]],
    texture2d<float> texture [[texture(0)]],
    constant Uniforms& uniforms [[buffer(0)]]
) {
    // Kaleidoscope transformation
    float2 uv = kaleidoscope(in.texCoord, 6, uniforms.time);
    
    // Generate RGBY color blocks
    float4 color = generateColorBlock(uv, uniforms.blockSize);
    
    return color;
}

性能要求

  • 目标在现代设备上达到60帧每秒
  • 记忆高效内存使用
  • 汇编<500毫秒

着色器元数据约定

着色器应在顶部包含一个文档字符串，声明名称和描述。这将被解析 ShaderMetadata.from(code:path:) 并支持图书馆搜索、缩略图视图和元数据视图。

示例：

/**
 * Kaleidoscope Blocks
 * Geometric color blocks with animation controls.
 */
#include <metal_stdlib>
using namespace metal;
fragment float4 fragmentShader() { return float4(0,0,0,1); }
  • 第一个非空文档行 → name
  • 跟随非空行（直到遇到空行）→ description
  • 当来源信息可用时，记录源路径

“库”选项卡和缩略图

  • 库条目的标题/描述来源于着色器的文档字符串。
  • 缩略图可以来源于会话快照，或者通过无头渲染器生成以确保一致性。
  • 随着图书馆用户体验的扩展，预计将会实现按标签搜索/过滤以及快速比较覆盖功能。

文件桥接通信协议（过渡期）

在严格的MCP客户端正在集成的同时，该应用程序使用了一个简单的文件桥接方式 Resources/communication/:

  • commands.json （输入，本地工作流中可选）：排队中的操作（例如，设置着色器、导出帧）
  • status.json （输出）：最后操作状态和诊断信息
  • current_shader_meta.json活动着色器的解析名称/描述/路径
  • library_index.json索引库元数据
  • uniforms.json当前的统一值
  • compilation_errors.json最后一次编译诊断信息

随着MCP运输系统取代桥梁，密钥和精确形状将趋于稳定，但这些文件目前是本地工具集成的权威来源。

建筑学

metal-shader-mcp/
├── src/
│   ├── index.ts         # MCP server
│   ├── compiler.ts      # Metal compilation
│   ├── preview.ts       # Preview engine
│   ├── hotReload.ts     # File watching
│   ├── profiler.ts      # Performance profiling
│   └── parameters.ts    # Uniform management
├── shaders/
│   └── kaleidoscope.metal  # Example shader
└── dist/                # Compiled output

热重载仪表板

访问开发仪表板，请前往：

http://localhost:3000/dashboard

特点：

  • 实时编译状态
  • 错误和警告显示
  • 性能指标
  • 文件监视状态

着色器示例

随附的万花筒着色器展示了：

  • 实时几何变换
  • Perlin噪声生成
  • 色彩块效果
  • 交互式动画
  • 性能优化技术

性能优化

分析仪测量：

  • 平均帧时间
  • 每秒帧数
  • GPU处理时间
  • CPU开销
  • 内存使用量
  • 功耗估算

发展

重要提示：路径稳定，不受启动目录影响

此项目之前使用当前工作目录来解析资源路径，这导致从不同文件夹启动MCP时出现行为不一致的情况（例如，动画可以正常工作但库/历史记录不行，或者相反）。现在，路径是相对于项目根目录解析的，检测方式如下：

  1. 如果设置了 METAL_SHADER_MCP_ROOT，则使用该目录（预期存在一个名为 Resources 的子文件夹）
  2. 否则，我们就从MCP源代码位置开始往上找，直到找到一个Resources目录
  3. 回退方案：process.cwd()（仅在上述方法失败时使用）

如果您需要覆盖设置，请在启动前设置环境变量：

  • macOS/zsh 导出 METAL_SHADER_MCP_ROOT 环境变量为 "/Users/erichowens/coding/metal-shader-mcp"

这确保了无论您在哪里运行CLI（命令行界面），MCP（可能是指某种管理控制面板或客户端程序）和应用程序都能读写相同的资源/通信文件夹以及资源/截图文件夹。

服务密钥/机密

此存储库无需外部服务密钥即可运行核心ShaderPlayground + MCP流程。如果您添加了需要密钥的集成，请按以下优先顺序之一进行存储：

  • 本地开发：.env.local（已添加到git忽略文件中）
  • 在同一台机器上共享开发环境：.env（已添加到git忽略文件中）
  • CI：在CI提供商的加密密钥存储中配置密钥
  • 生产环境：使用您的部署平台的密钥管理器（例如，GitHub Actions 密钥、1Password、AWS/GCP 密钥管理器）

永远不要将机密信息提交到代码仓库中。在代码中使用环境变量（例如，process.env.MY_KEY），并将所有需要的变量在此处记录下来。

事后行动要求

每一次重要的发展行动都必须完成以下步骤：

  1. 更新 BUGS.md 文件 - 记录发现的任何问题
  2. 更新 CHANGELOG.md 文件 - 记录所完成的工作
  3. 捕捉视觉证据 - 用户界面/着色器更改的截图
  4. 运行测试 - 确保没有引入任何退步（或：确保没有出现任何倒退）
  5. Git 操作 - 提交时附上描述性信息

见 WARP.md 用于详细的工作流程文档。

视觉测试

这个项目包含一个带有着色器固定装置和基准图像的视觉回归测试框架。

# Capture screenshots of current state (optional manual evidence)
./scripts/screenshot_app.sh "feature_description"

# Run visual tests
swift test --filter VisualRegressionTests

# If you intentionally changed visuals, regenerate goldens
make regen-goldens
  • 在失败的情况下，工件会被保存到 Resources/screenshots/tests/ （例如。， actual_*.png， diff_*.png以及一个摘要JSON。
  • 金毛寻回犬生活在 Tests/MetalShaderTests/Fixtures/ 并通过SPM资源进行打包。

文档文件

  • WARP.md（文件名，可理解为“WARP的Markdown文件”或保持原样，根据上下文具体解释） - 代理工作流程要求
  • CLAUDE.md（文件名，可翻译为“克劳德文档”或保持原样，具体根据上下文决定是否需要翻译文件名） - 创意愿景与人工智能交互模式
  • `VISUAL_TESTING.md` 翻译成中文为：“视觉测试说明文件”或“视觉测试指南”。（注：`md`通常表示Markdown格式的文件，但在此处直接翻译时，我们更关注文件名的含义，因此未直接译出`.md`，而是融入了整体意思中。） - 可视化测试框架
  • BUGS.md（文件名，可译为“错误报告.md”或保持原样，因为文件名通常不翻译） - 当前问题及解决方案
  • CHANGELOG.md 翻译为中文是：“变更日志文件（Markdown 格式）” - 项目演进历史

弃用通知（file-bridge）

  • 文件桥接（commands.json轮询）是过渡方案，一旦严格的MCP客户端（MCPLiveClient）通过MCPBridge集成到Swift应用中，该文件桥接将被移除。
  • 目标：用合适的MCP传输方式（stdio/websocket）替换桥接，移除轮询，增加健壮的错误处理。
  • 时间线：一旦PR #29合并，我们将继续处理PR #32以完成此次迁移。

做出贡献

欢迎投稿！请遵循工作流程要求 WARP.md：

  1. 从主分支创建特性分支
  2. 以视觉证据为依据实施变更
  3. 更新相关文件
  4. 运行视觉回归测试
  5. 提交包含截图的拉取请求

许可证

麻省理工学院（MIT）

相关 MCP