store-asset-generator

# StoreKit — AI 驱动的应用商店资产生成器 一个开源的 [MCP 服务器](https://modelcontextprotocol.io)，适用于 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)，用于从您的移动应用项目中生成应用商店和 Play 商店资产。 **一个命令。所有商店资产。** ```bash cd my-ios-app claude > 生成此应用的商店资产 ``` --- ## 功能介绍 StoreKit 扫描您的移动项目，了解其屏幕，构建它，获取模拟器截图，设计独特的商店模版，编写 ASO 优化的文案，并以 Fastlane 准备好的格式导出所有内容 — 所有这些都通过 Claude Code 的 MCP 工具。 无需固定模板。无需 API 密钥。每个应用都根据其实际颜色、类别和内容获得独特的设计。 ### 真实示例 这些模版是由 StoreKit 从真实应用中生成的 — 每个应用都有一个根据其类别、颜色和内容量身定制的独特设计： #### Ingredio — AI 食品扫描仪和营养跟踪器   #### Qardly — 数字名片   > 相同的工具，完全不同的设计。StoreKit 分析每个应用的颜色、类别和屏幕 — 然后 Claude 设计一个独特的模版。没有固定模板，两个应用看起来不一样。 ### 流程 ``` 检测项目 → 扫描代码，找到屏幕，按商店重要性排序 ↓ 构建项目 → xcodebuild / gradle / flutter 构建 ↓ 模拟器控制 → 启动模拟器，安装应用 ↓ 截取截图 → 捕获每个屏幕（状态栏：9:41，电池满格） ↓ 生成模版 → 分析颜色/调色板，Claude 设计自定义 HTML ↓ 批量渲染 → Puppeteer 渲染到每个所需的商店尺寸 ↓ 生成元数据 → Claude 编写 ASO 描述，关键词，文案 ↓ 导出资产 → 打包成 Fastlane 准备好的目录 ``` 如果构建失败或您跳过模拟器，StoreKit 会自动退回到读取您的源代码并从中设计模版。 --- ## 安装 ### 步骤 1 — 安装 **从 npm（发布时）：** ```bash npm install -g store-asset-generator ``` **从源代码：** ```bash git clone https://github.com/ArzuOzsoySW/store-asset-generator.git cd store-asset-generator npm install npm run build ``` ### 步骤 2 — 注册 Claude Code **从 npm：** ```bash claude mcp add store-asset-generator --scope user -- npx -y store-asset-generator ``` **从源代码（本地）：** ```bash claude mcp add store-asset-generator --scope user -- node /path/to/store-asset-generator/dist/index.js ``` ### 步骤 3 — 验证 ```bash claude mcp list ``` 您应该看到： ``` store-asset-generator: ✓ 已连接 ``` 然后在 Claude Code 会话中： ``` /mcp ``` 应该列出 `store-asset-generator` 下的 9 个工具。 ### 要求 - **Node.js** >= 20 - **Claude Code** 具有 Pro 或 Max 订阅 - **用于 iOS 截图：** Xcode + iOS 模拟器（仅限 macOS） - **用于 Android 截图：** Android SDK + 模拟器 - **用于 Flutter：** Flutter SDK - **用于模版渲染：** Puppeteer Chrome — 运行一次： ```bash npx puppeteer browsers install chrome ``` - **可选：** [Facebook IDB](https://fbidb.io/) 以获得更好的 iOS 模拟器交互 并非所有这些都是必需的。如果您跳过模拟器（`skip_simulator: true`），您只需要 Node.js 和 Puppeteer。 --- ## 使用 ### 快速开始 ```bash cd /path/to/your-app claude ``` 然后输入： ``` 为此应用生成商店资产，top_n: 3 ``` 就是这样。StoreKit 检测您的项目，选择 3 个最值得商店的屏幕，构建并截图它们（或在构建失败时退回到源代码），设计独特的模版，编写商店文案，并导出所有内容。 ### 现实示例 #### 示例 1：SwiftUI 应用（Ingredio — 食谱/成分跟踪器） ``` > 生成所有路径：/Users/me/Projects/Ingredio，top_n: 3 [引导模式 — 在 Claude Code 中不提供采样] 阶段 1：detect_project ✓ → SwiftUI 应用，找到 14 个屏幕 → 前 3 名：TrackerView（重要性 9），WeightCoachView（8），RecipeDetailView（8） 阶段 2：select_screens_deterministic ✓ → 按重要性评分选择了 3 个屏幕中的 3 个 阶段 3：build_ios ✗ （当前分支上的 Swift 编译错误） → 自动回退：为 3 个屏幕收集源代码 阶段 4：analyze ✓ → 设计简介已生成，包含调色板，字体建议，密度 结果：工作订单返回，包含 3 个设计任务 + 元数据任务 Claude 代理然后： 1. 读取每个屏幕的 Swift 源代码 2. 设计一个独特的 HTML 模版（TrackerView 的暗玻璃拟态，WeightCoach 的干净渐变，RecipeDetail 的编辑布局） 3. 调用 generate_mockup(batch_render) → PNG 在所有商店尺寸 4. 在 EN + TR 中编写 App Store + Play Store 文案 5. 调用 export_assets → Fastlane 目录准备就绪 ``` 输出： ``` store-assets/ ├── mockups/ │ └── ios/ │ ├── tracker-view-6.7-inch.png │ ├── tracker-view-6.1-inch.png │ ├── tracker-view-5.5-inch.png │ ├── tracker-view-ipad-12.9-inch.png │ ├── weight-coach-view-6.7-inch.png │ ├── ... （4 大小 × 3 屏幕 = 12 个模版 PNG） ├── metadata/ │ └── copy.json （ASO 文案，英文和土耳其语） ├── fastlane/ │ ├── metadata/en-US/ │ ├── metadata/tr/ │ ├── screenshots/ │ └── Deliverfile └── config.json ``` #### 示例 2：具有工作构建的 Flutter 应用 ``` > 生成所有路径：/Users/me/Projects/my-flutter-app，top_n: 4 阶段 1：detect_project ✓ → Flutter，8 个屏幕 阶段 2：select_screens ✓ → HomeScreen，ProductDetail，CartScreen，ProfileScreen 阶段 3：build_ios ✓ → flutter build ios --debug --simulator 阶段 4：boot_ios ✓ → iPhone 16 Pro Max 模拟器 阶段 5-8：screenshot × 4 ✓ → 捕获原始 PNG（9:41，电池满格） 阶段 9-12：analyze × 4 ✓ → 提取调色板，设计简介准备就绪 阶段 13-16：design + render × 4 ✓ → 每个屏幕的独特模版 HTML 阶段 17：metadata ✓ → ASO 文案，英文 阶段 18：export ✓ → Fastlane 目录 → 16 个模版 PNG（4 个屏幕 × 4 个 iOS 尺寸） → store-assets/ 已准备好上传 ``` #### 示例 3：完全跳过模拟器 如果您没有设置 Xcode/模拟器，或者您的构建已损坏： ``` > 生成所有路径：/Users/me/Projects/my-app，skip_simulator: true，top_n: 3 ``` StoreKit 直接读取您的源代码，Claude 设计模版，想象每个屏幕的样子。不需要构建，模拟器或截图。模版不会像素完美，但足以用于商店列表草稿。 ### 分步（细粒度控制） 除了 `generate_all` 之外，您还可以调用单个工具： ``` > 检测此项目的类型并列出所有屏幕 > 为 iOS 模拟器构建 > 启动 iOS 模拟器并截取首页截图 > 分析截图 store-assets/.work/raw-home.png > （Claude 读取设计简介，编写自定义 HTML 模版） > 渲染此 HTML 为模版：[粘贴 HTML] > 编写 App Store 描述和英文和土耳其语关键词 > 以 Fastlane 格式导出所有内容 ``` ### 可视化编辑器（生成后） ```bash # 从终端（不在 Claude Code 内） npx store-asset-generator-preview ./store-assets # 或如果从源代码安装： node /path/to/store-asset-generator/dist/preview/cli.js ./store-assets ``` 在 `http://localhost:4321` 打开以下内容： - 左侧面板：模版缩略图列表 - 中心：所选模版以全尺寸显示 - 右侧面板：编辑标题，强调色，元数据（带有实时字符计数器） - 保存 + 重新生成按钮 --- ## 工作原理（两种模式） ### 引导模式（Claude Code CLI） Claude Code 不支持 MCP 采样，因此 `generate_all` 在 **引导模式** 下运行: 1. 运行所有机械/确定阶段（检测，构建，截图，分析） 2. 返回具有每个屏幕设计简介的结构化 **工作订单** 3. Claude（Claude Code 会话中的代理）读取工作订单 4. Claude 设计 HTML 模版，调用 `generate_mockup(render)`，填写元数据，调用 `export_assets` 您不需要执行任何特殊操作 — 此操作会自动发生。该工具检测到采样不可用并切换到引导模式。 ### 原子模式（支持采样的主机） 在支持采样的 MCP 主机（Claude Desktop，Cursor 等）上，`generate_all` 在单个原子调用中运行所有操作 — 包括 AI 设计步骤。无需代理循环。 --- ## MCP 工具（共 9 个） | 工具 | 描述 | |------|-------------| | **`generate_all`** | 端到端流程。从这里开始。自动检测引导模式还是原子模式。 | | `detect_project` | 扫描项目 → 平台，屏幕，重要性分数，构建配置 | | `build_project` | 为模拟器构建（flutter / xcodebuild / gradle） | | `simulator_control` | 启动，关闭，安装，启动模拟器 | | `navigate_and_interact` | 在运行的应用中点击，输入，滚动，滑动 | | `take_screenshot` | 捕获干净的状态栏（9:41，电池满格，信号满格） | | `generate_mockup` | 三种模式：`analyze`（调色板 + 简介），`render`（HTML→PNG），`batch_render`（所有尺寸） | | `generate_metadata` | 为 Claude 填写 ASO 数据结构 | | `export_assets` | 将所有内容打包成 Fastlane 准备好的格式 | ## 支持的平台 | 平台 | 检测 | 构建 | 模拟器 | 截图 | |----------|-----------|-------|-----------|------------| | **Flutter** | ✅ | ✅ | ✅ （通过 iOS/Android） | ✅ | | **SwiftUI** | ✅ | ✅ | ✅ | ✅ | | **UIKit** | ✅ | ✅ | ✅ | ✅ | | **Jetpack Compose** | ✅ | ✅ | ✅ | ✅ | | **React Native** | ✅ | ❌ （计划中） | ❌ | ❌ | | **Kotlin Multiplatform** | ✅ | 部分 | 部分 | 部分 | ## 输出结构 ``` store-assets/ ├── mockups/ │ ├── ios/ （每个屏幕 × 4 尺寸：6.7"，6.1"，5.5"，iPad 12.9"） │ └── android/ （每个屏幕 × 3 尺寸：手机，7" 平板电脑，10" 平板电脑） ├── metadata/ │ └── copy.json （ASO 文案，按本地化） ├── fastlane/ │ ├── metadata/ │ │ ├── en-US/ （name.txt，subtitle.txt，description.txt，keywords.txt，...） │ │ └── tr/ │ ├── screenshots/ │ └── Deliverfile └── config.json （可编辑 - 预览 UI 的源代码） ``` ### 商店截图尺寸 **iOS（应用商店）：** | 尺寸 | 设备 | 分辨率 | |------|--------|------------| | 6.7" | iPhone 16 Pro Max | 1290 × 2796 | | 6.1" | iPhone 16 | 1179 × 2556 | | 5.5" | iPhone 8 Plus | 1242 × 2208 | | 12.9" iPad | iPad Pro | 2048 × 2732 | **Android（Play 商店）：** | 尺寸 | 设备 | 分辨率 | |------|--------|------------| | 手机 | Pixel 9 | 1080 × 1920 | | 7" 平板电脑 | Nexus 7 | 1200 × 1920 | | 10" 平板电脑 | Pixel 平板电脑 | 1600 × 2560 | --- ## 上传到商店（Fastlane） StoreKit 生成一个与 Fastlane 兼容的目录。要实际上传到应用商店/Play 商店： ### 一次性设置 ```bash # 安装 Fastlane brew install fastlane # iOS - 使用 App Store Connect 认证 fastlane deliver init # Android - 使用 Google Play 控制台认证 fastlane supply init ``` ### 上传 StoreKit 生成的资产后 ```bash cd /path/to/your-app/store-assets # iOS → App Store Connect fastlane deliver \ --metadata_path ./fastlane/metadata \ --screenshots_path ./fastlane/screenshots \ --skip_binary_upload true \ --force true # Android → Google Play 控制台 fastlane supply \ --metadata_path ./fastlane/metadata \ --skip_upload_apk true \ --skip_upload_aab true ``` `--skip_binary_upload` / `--skip_upload_apk` 表示它只上传截图和元数据，而不是应用二进制文件本身。你可以通过 Xcode 或你的 CI 流水线处理二进制文件上传。 或者直接询问 Claude：``` 上传商店资产到 App Store Connect via fastlane ``` Claude 将为您运行命令（如果已配置 Fastlane）。 --- ## 故障排除 ### 采样时出现“方法未找到”错误 Claude Code CLI 中的正常行为。该工具自动切换到引导模式。无需采取任何操作。 ### 构建因架构不匹配而失败 已在 v0.1.0 中修复 - 使用 `generic/platform=iOS Simulator` 目的地，该目的地在 Intel 和 Apple Silicon Mac 上都有效。 ### 构建因 Swift/Kotlin 编译错误而失败 该工具捕获此错误并退回到源代码收集。Claude 设计模版源自源代码。如果您想要真实的模拟器截图，请修复编译错误。 ### “Puppeteer：chrome 未找到” 运行一次： ```bash npx puppeteer browsers install chrome ``` ### 模版看起来很通用 设计简介传递主导颜色 + 内容密度 + 类别特定字体到 Claude。如果输出是通用的，请提供更多上下文： ``` generate_all path: /my/app, top_n: 3 ``` 然后当 Claude 设计 HTML 时，提供反馈：“使其更高级”或“使用更深的颜色” - Claude 将重新设计。 ### MCP 未出现在 `/mcp` 您需要在添加 MCP 后重启 Claude Code。使用 `/exit` 或 Ctrl+D，然后启动新会话。 --- ## 开发 ```bash git clone https://github.com/ArzuOzsoySW/store-asset-generator.git cd store-asset-generator npm install npm run build # tsc + copy prompts and UI assets npm test # vitest - 3 files, 9 tests npm run dev # tsc --watch ``` ### 项目结构 ``` src/ ├── index.ts # MCP stdio 入口 ├── server.ts # 9 个工具定义 + 路由 ├── types.ts # 共享类型（ProjectInfo，DesignBrief，...） ├── tools/ │ ├── orchestrate.ts # generate_all（引导 + 原子模式） │ ├── detect.ts # 多平台项目检测 │ ├── build.ts # flutter/xcodebuild/gradle │ ├── simulator.ts # xcrun simctl / adb │ ├── navigate.ts # UI 交互（IDB，AppleScript，adb） │ ├── screenshot.ts # 状态栏掩码捕获 │ ├── mockup.ts # analyze / render / batch_render │ ├── metadata.ts # ASO 结构 │ └── export.ts # Fastlane 打包 ├── prompts/ # 采样提示（.md，人类可编辑） ├── utils/ │ ├── sampling.ts # MCP 采样包装器与探针 │ └── shell.ts # execa 包装器 ├── preview/ │ ├── server.ts # 本地 HTTP 编辑器 │ ├── ui.html # 单文件 UI（香草，无框架） │ └── cli.ts # store-asset-generator-preview bin └── renderer/ └── references/ # 旧的 12 个固定模板（仅供参考） ``` ## 贡献 欢迎 PRs！好的领域： - React Native / Kotlin Multiplatform 构建适配器 - 按类别的提示调优（`src/prompts/*.md`) - `src/renderer/references/` 下的新参考设计 - 预览 UI 改进 - 更多测试fixtures ## 许可证 MIT