ios-agent-skill

iOS Agent Skill

为你的编码 Agent 提供构建和审查 iOS 应用所需的 Apple 参考资料、Swift 源代码和本地工具。

观看网站演示 · 浏览网站

用一句话描述应用，/ios-build Agent 就会规划应用、编写 SwiftUI 代码和 Xcode 项目，然后在模拟器中构建并运行应用（已验证的内容，网站上的示例应用）。对于现有项目，同一套软件包还能为你的编码 Agent 提供审查、本地 Apple 参考资料和模拟器工具，以检查其工作成果。

浏览网站 · 客户端设置指南 · npm · 发行说明

用一句话构建应用

/ios-build "<what you want>" 会让 Claude Code 规划 iOS 应用、编写 SwiftUI 代码和 Xcode 项目、应用功能模块（登录、存储、支付、地图等），然后在 iOS 模拟器中构建、运行并截图，最后报告哪些事项需要你的账号或资金。已发布的工具包含在 ios-agent-mcp 2.10.2 中（npm 于 2026 年 10 月 15 日验证），其中包括由规划驱动的设计令牌、示例数据、与调色板协调的资源、浅色／深色／XXL 截图证据、部署目标检查和 App Store 就绪情况报告。四款现有应用已在 Xcode 27.0 上构建并运行；请参阅 examples/agent 获取更新后的证据。

快速开始

安装已发布的服务和 Claude Code 命令：

claude mcp add ios-agent -- npx -y ios-agent-mcp@latest
npx -y ios-agent-mcp@latest install-command --global

然后，在 Mac 上启动任意 Claude Code 会话，且需安装 Xcode 16 或更高版本：

/ios-build "A habit tracker with a list, a detail screen, and settings with dark mode toggle"

发布（尚未发布的 GitHub 源代码）： ios-agent-mcp ship 会准备截图集和元数据，然后提供需单独批准的签名／归档和 TestFlight 上传步骤。设置与限制。尚未验证实时签名分发；npm 未有变更。

Windows／Linux 或云端客户端： GitHub 源代码现已包含 build --remote，可在 GitHub Actions 上进行未签名构建并截取模拟器截图。此功能需要目标仓库、GitHub CLI 身份验证以及固定版本的工具包／Xcode。请参阅远程 macOS 设置与计费。npm 发布已推迟。

XcodeGen 为可选工具：如果未安装，Agent 会自行编写文件夹同步的 Xcode 项目。相关步骤请参阅 docs/tooling/ios-build-agent.md。四个截图示例复用了现有应用文件夹；尚未在单次 Mac 会话中从规划到代码生成完整运行这条一句话快速开始流程。

示例

习惯追踪器	带搜索功能的笔记	三标签页信息流	外卖配送

计划、生成的源代码、运行报告，以及已测试和未测试的内容：examples/agent。

能力

每项能力都是 capabilities/ 中的一个文件夹，其中包含清单、配方、Swift 模板、应用钩子和验证钩子。目录列出了更广泛的能力范围，供规划和成本估算使用。以下数量由清单生成。

状态	能力
已在 Mac 上验证	7
模块已存在，尚未在 Mac 上验证	41
...其中 Swift 已在 Mac 上编译（组合编译检查）	41
已阻塞	0
仅列出以供规划	114

31 个类别中共有 162 个目录条目；由 capabilities/CATALOG.md 生成。

需要你的账户

Agent 无需账户即可在模拟器中构建并运行所有内容。需要使用服务的能力会在清单中声明所需密钥。客户端密钥（例如可发布密钥）应放在项目被 git 忽略的 .env 文件中，并通过生成的 xcconfig 传递给应用。在设置这些密钥之前，它们会是 REPLACE_ME 占位符，因此应用仍可构建并显示配置提示。服务器机密绝不会放入应用中。PLAN.md 会列出每次运行所需的内容，以及各项服务的成本模型。要在设备上运行、使用 TestFlight 或发布应用，需要加入 Apple Developer Program。

尚未完成

• design-system、firebase-auth、firebase-firestore、google-sign-in、stripe-payments、rive-animation 和 webview-animation 能力已通过独立的 Mac 编译验证。服务提供商账户和运行时交易仍未验证；组合编译检查不能替代各模块的验证运行（参见编译检查）。
• 对于这四个现有示例，Agent 的构建、模拟器启动和逐屏截图阶段已在 Mac 上运行。原始规划和代码生成会话是分开的，尚未在 Mac 上端到端运行全新的单句生成。
• Agent 自行截图时的点按和滚动，以及设备构建，均尚未完成。在外卖配送示例中，未测试 StoreKit 购买和 Live Activity。

选择哪种工作流

你的目标	使用	备注
根据描述构建新应用	在 Claude Code 中使用 /ios-build "<description>"，或使用 ios-agent-mcp build	进行规划、编写、构建、运行和截图；参见上文。npm 2.10.2 和 GitHub main 中可用。
让现有项目通过你自己的验收测试	ios-agent-mcp loop	运行你编写的检查，并请 Claude 修复失败项；参见应用构建循环和 Reading List 演示。
只获取可编辑的起始模板	ios-agent-mcp new MyApp	提供起始模板和简要说明，并非完整应用。
审查或扩展你已有的代码	下方的 MCP 工具	按文件定位的审查、本地参考资料、资源和模拟器检查。

从一个连接开始

对于 Claude Code：

claude mcp add ios-agent -- npx -y ios-agent-mcp@latest

设置 ChatGPT/Codex、Gemini CLI 或 Muse。一个 npm 包包含代码评审、本地参考资料、应用脚手架和模拟器工具。需要 Node.js 20+；本地 iOS 构建需要 macOS 和 Xcode；GitHub 源码远程通道会在 Actions 上运行这些步骤。

然后提出以下要求：

构建一个 SwiftUI 阅读清单，包含本地持久化、搜索，以及易于访问的空状态和错误状态。复用本地源代码库。构建应用、运行测试并捕获模拟器证据。说明任何失败的检查。

对于现有应用，请提供其项目的绝对路径，并在进行更改前要求进行有针对性的评审。

它能帮助你完成哪些工作

功能	你将获得
根据一句话构建应用	ios-build agent 会规划屏幕、数据和功能，编写 SwiftUI 和 Xcode 项目，然后在模拟器中构建、运行应用并截图。ios-agent-mcp 2.10.0 起提供。
创建应用	可编辑的 Swift 入门模板、实现说明，以及可选的 XcodeGen 规范。
复用 Apple 知识	在本地 Swift 源代码和指南中按限定范围搜索，并查阅按日期整理的 Apple 技术和发行说明目录。
评审 Swift 代码	针对并发、架构、SwiftUI、可用性、安全性、性能和 App Intents 的问题，并标注所在文件。
生成设计素材	生成命名的浅色／深色／高对比度颜色，以及使用可编辑 SVG 图层在本地渲染的不透明 1024px 应用图标。
评审应用配色系统	生成语义调色板，并检查浅色、深色和高对比度配色证据。
评审后端集成	确认支持的服务，并在本地评审凭证、身份验证、策略和网络证据。
在模拟器上验证	通过 Xcode 构建、测试、安装、启动应用并捕获屏幕截图。
评审启动屏幕	针对目标谨慎检查启动配置、故事板和素材引用。
准备本地发行草稿	检查所选目标的信息、未解决的问题，以及带哈希且可恢复的本地包，全程无需连接 Apple。
App Store 截图工作室（GitHub 源码）	将截图转换为本地化截图集，包含可复用布局、中性边框、预览图库和经过验证的 PNG 导出文件。
Apple 系统集成（GitHub 源码）	预览和评审日历、提醒事项、通讯录、照片、相机、地图、文件、共享、快捷指令和通知，并提供权限和功能证据。

素材生成 · 评审工具 · 模拟器设置 · Apple 发行状态

直接创建入门模板：

npx -y ios-agent-mcp@latest new MyApp --brief "A reading list with local storage" --xcodegen

入门模板不是完整应用：--xcodegen 会写入一个 project.yml，由 XcodeGen 将其转换为项目。要根据描述构建完整应用，请使用 /ios-build。生成应用的所有权和品牌归用户所有。

查看证据

Reading List 演示包含持久化、搜索、模拟器验收测试和捕获的屏幕截图。/ios-build Agent 规划并编写的四个应用，以及它们的计划、运行报告和模拟器截图，位于 examples/agent。

已发布的 npm 2.10.2 软件包包含构建 Agent 工具、部署目标检查和 App Store 就绪情况报告。其中包括七个 Apple 系统集成工具和九个 Screenshot Studio 工具。静态审查采用启发式规则，并非编译器诊断。Apple 目录是参考索引，不是 Apple 专有框架的源代码，也不能证明有 405 项可用集成。尚未对 Token 节省情况进行基准测试。构建循环验证的局限性。

为什么要与 Xcode 搭配使用？

Xcode 已自带 Agent 专业能力以及构建和测试工具。满足需求时，请使用这些工具。本仓库为这四类客户端提供共享指南、可检查的审查规则、本地源码检索和可重复的资源工作流。目前尚无证据表明它能让 AI 的表现超越 Xcode 的技能，或减少 Token 用量。

指南的来源、证据和未完成的工作。配对基准测试工具包含 20 个 Swift 微任务；结果尚未发布，目前也还无法测量完整的应用构建。

帮助改进工具

失败反馈应留在你的编码会话中：观察到的错误、建议的修复方案以及实际验证结果。源服务器会在返回的工具错误中添加故障排除指南；Agent 指令也涵盖编译器和测试失败。这些消息不会出现在你正在构建的应用中。

prepare_issue_report 可在 iOS Agent 工具失败时让 AI 准备一份本地报告。它仅接受固定类别，提供预览和重复问题搜索链接，并由你决定是否公开提交。不会收集应用源码或日志。报告工作流。

作为 2.7.1 中的实验性工具推出：可选的 private_feedback 会在 AI 聊天中征得批准，并通过配置好的 HTTPS 接收器将固定类别发送到私人收件箱。目前未配置托管服务，因此私人提交功能尚未启用。它绝不会在未提示的情况下提交，也不会改为提交公开问题。

四类客户端，一个项目

客户端	配置与验证情况
Claude	本地 MCP 和源代码 skill；Claude 客户端提供编码 Agent。
ChatGPT / Codex	Codex 本地 MCP；ChatGPT skills 包，或单独配置的 HTTPS／专用隧道 MCP 连接。可用性取决于账户／工作区策略。
Gemini CLI	扩展配置和本地 MCP 连接已验证。
Muse Code	skill 发现、MCP 发现（36 工具的 2.7.0 服务）和 Stop hook 已验证；模型会话和观察器行为尚未验证。

项目专注于这四类客户端。如需支持其他客户端，请提交客户端支持请求，或为现有请求点 👍。投票会与可行性和测试结果一起影响优先级，但不保证一定交付。现有实验性适配器不再积极维护。

install.sh 是可选的：它会为选定的本地客户端安装源代码指导，而不是安装 MCP 服务或浏览器插件。克隆后运行 bash install.sh --help。大多数用户应使用上方的客户端配置指南。

参考覆盖情况

Apple 目录跟踪：99 项技术。已覆盖：99。计划中：0。已跳过：0。已弃用：0。覆盖率：100.0%。

权威数据源：frameworks.json。人工维护的索引：docs/apple-framework-index.md。

覆盖数量描述的是文档，而非已编译的集成。下载量每日更新，且不代表独立用户数。

贡献指南 · 开发 · 安全 · 路线图 · MIT 许可证

后端集成指南：选择服务并审查身份验证、数据和安全边界。

可选的提供商命令

使用 ios-agent-mcp environment 检查实际的 Xcode／SDK／模拟器清单。 ios-agent-mcp ai models 和 ai doctor 用于检查带日期的目录以及账户／本地可用性。 文本生成默认使用设备端 Apple 模型；使用云提供商和回退机制需要显式配置。 提供商配置、交接、模拟器 CLI 和限制。这些命令不能替代编码客户端，也不声称能自主完成应用开发。

本地 Apple 文档

在 Xcode → Settings → Components → Developer Documentation 中安装归档。通过 Window → Developer Documentation 阅读（使用标准键绑定时按 Shift–Command–0）。此集成使用 xcrun mcpbridge；归档由 Xcode 管理。

使用 xcode-mcp tools 查看已发现的 Xcode 架构，并使用 doctor xcode 诊断配置问题。

使用 ios-agent-mcp docs status 和 ios-agent-mcp docs symbol SwiftUI.NavigationStack 获取与版本对应的文档依据。适配器优先使用 Xcode MCP DocumentationSearch，其次使用范围受限的 SDK 证据。不会打包 Apple 的归档。需要桥接授权；检索不会自动验证代码。配置、工具和限制。

实验性原生源代码导入

功能分支中的 App IR 原型可将范围有限的本地 HTML 屏幕导入经过验证且带有源映射的表示形式，并生成原生 SwiftUI。它会重复使用现有的 Xcode 和模拟器工具。不支持的标记会被报告，并阻止生成。这并非通用框架转换，且未包含在 npm 2.10.2 中。请参阅架构与路线图和真实原生原型证据。

实验性原生转换工作（包括静态 React 子集和已保存证据的审查）记录在通用应用引擎架构中。这些原型并不能证明具备通用 React/Next.js 兼容性，也不能证明视觉保真度已达到可接受水平。