如何在 Capacitor 应用开发中使用 AI Agents

要在 Capacitor 应用开发中使用 AI agents，就要给 agent 补上它默认缺少的两样东西：Capacitor 原生端的流程知识，来源是可安装的 skills以及实时工具，通过 MCP 服务器 以及它能运行的 CLI。凭借 Capgo 开源的 Capacitor 能力和 Capgo MCP servers，像 Claude Code、Codex 或 Cursor 这样的 Agent 可以通过正确的 native 配置添加插件、调试 iOS 和 Android builds、请求 cloud builds 并上传 Live Update。

本指南将解释为什么通用 Agent 会在 Capacitor 上出错，如何通过几条命令设置 skills 和 MCP，针对应用生命周期各阶段的 prompts，以及确保安全的防护机制。

为什么通用 Agent 在 Capacitor 方面表现不佳

Agent 在 Web code 方面表现出色。但 Capacitor 项目增加了另一半内容，且每年都在变化：

• 版本漂移。 Capacitor 8 更改了 Android SDK 级别，新的 iOS 项目默认使用 Swift Package Manager，并且 App Store uploads 需要 Xcode 26。训练数据中混杂了 Capacitor 3 到 8 的建议。
• 跨文件的 Native 配置。 单个插件可能需要 Info.plist keys、entitlements、 AndroidManifest.xml permissions、Gradle 变更以及 cap sync. Agent 通常只负责 JavaScript 部分。
• 插件选择。 许多社区插件已停止维护。Agent 会根据出现频率来选择，而不是根据 Capacitor 8 的兼容性来选择。
• 隐性故障。 错误隐藏在 Xcode、Logcat 或 CI 日志中，而不是编辑器里。

你可以通过让 Agent 按需加载上下文，并提供可调用的工具来解决这个问题，而不是让它盲目猜测。

工具集：技能、MCP 以及 CLI

安装技能

bunx skills add Cap-go/capgo-skills

安装程序会自动检测支持的 agent，并将技能放置在各 agent 的检索路径下。该套件涵盖了插件选择、最佳实践、Capacitor 应用与插件的大版本升级 (包括 v7 到 v8)、CocoaPods 迁移至 SPM、调试、iOS 和 Android logs、推送通知、Deep Links、Safe Areas、安全扫描、测试、CI/CD、App Store 预检、Cordova 与 Web App 迁移、Capgo Live Update 以及 Capgo Native Build。该 技能页面 列出所有技能。

在 Claude Code 中，你还可以使用插件市场：

claude plugin marketplace add Cap-go/capgo-skills
claude plugin install capgo-cloud@capgo-skills

连接 MCP 服务器

托管服务器无需安装。将其添加到 Claude Code，并在提示时通过 OAuth 登录：

claude mcp add --transport http capgo https://api.capgo.app/mcp

CLI 服务器通过 stdio 在本地运行，并使用你的 Capgo 登录信息，请先登录：

bunx @capgo/cli@latest login
claude mcp add capgo -- bunx @capgo/cli@latest mcp

对于使用 JSON 配置的编辑器（Cursor、Windsurf、Claude Desktop），对应的配置如下：

{
  "mcpServers": {
    "capgo": {
      "command": "bunx",
      "args": ["@capgo/cli@latest", "mcp"]
    }
  }
}

CLI MCP 提供了如下工具： capgo_upload_bundle, capgo_list_channels, capgo_update_channel, capgo_check_compatibility, capgo_request_build, capgo_doctor，以及 capgo_get_stats。完整列表请参阅 CLI MCP 参考文档，以及 MCP 页面 说明何时该用哪个服务器。

在 Capacitor 生命周期中使用 Agent

在 prompt 中写明技能名称。这样 Agent 会加载正确的流程，而不是临场发挥。

1. 将 Web 应用转换为 Capacitor 应用

Use the webapp-to-capacitor skill to add Capacitor 8 with iOS and Android
to this Vite + React app. Keep the existing build output folder.

Agent 会安装 @capacitor/core 以及 CLI，设置 webDir，添加平台并运行首次同步。对于现有的 Cordova 项目，请使用 cordova-to-capacitor。对于 Next.js、Nuxt 或类似框架，请使用 framework-to-capacitor，它会处理静态导出设置。

2. 用合适的插件添加原生功能

Use the capacitor-plugins skill to add biometric login.
Pick a plugin that supports Capacitor 8, configure iOS and Android,
and show me the usage code.

该技能了解官方 @capacitor/* 软件包以及 Capgo 插件目录，这样 Agent 就能选择一个维护中的插件并添加 Info.plist 使用字符串、Android 权限和同步步骤。像对待 Pull Request 一样检查 Diff。

3. 使用真实日志进行调试

Use the ios-android-logs skill to capture Logcat while I reproduce the crash
on the connected Android device, then use debugging-capacitor to find the cause.

Logs 能力让 Agent 能够获取精确的 adb 以及 Xcode 命令来流式传输并过滤设备日志，从而通过真实的堆栈跟踪（stack trace）进行分析，而不是靠猜源码。

4. 升级 Capacitor 并迁移至 SPM

Use the capacitor-app-upgrade-v7-to-v8 skill to upgrade this app.
Stop and show me the plan before changing native files.

如果你的 iOS 项目仍在使用 CocoaPods：

Use the cocoapods-to-spm skill to move the iOS project to Swift Package Manager.

Asking for a plan first is a good habit for any change that touches ios/ 或 android/如需了解该操作的手动版本，请参阅我们的 Capacitor 8 升级指南 以及 SPM 迁移指南.

5. 检查安全性和商店准备情况

Use the capacitor-security skill to scan this project and fix high severity issues.
Then run the capacitor-apple-review-preflight skill before I submit.

预检中常见的拒绝原因：缺少使用说明字符串、隐私清单缺失、Sign in with Apple 要求以及元数据问题。

6. 在云端构建 iOS 和 Android

请自行保存签名凭据，不要通过 Agent 进行：

bunx @capgo/cli@latest build credentials save --platform ios \
  --certificate ./cert.p12 --p12-password "..." \
  --ios-provisioning-profile ./profile.mobileprovision \
  --apple-key ./AuthKey.p8 --apple-key-id "KEY_ID" \
  --apple-issuer-id "ISSUER_ID" --apple-team-id "TEAM_ID"

凭据本地存储于 ~/.capgo-credentials/credentials.json (或 .capgo-credentials.json 带 --local（应将其加入 git-ignore），构建时会发送至云端，并在 Capgo 构建完成后删除。之后 Agent 即可自主运行：

Use the capgo-native-builds skill to request an iOS release build from the
current working directory, then read the logs and fix any build error.

这对应于：

bunx @capgo/cli@latest build request com.example.app --platform ios --path .

因为 --path . 上传工作树，Agent 即可在 Windows 或 Linux 上针对 iOS 构建错误进行迭代，而无需提交尝试性的修复代码。了解更多： Capgo 构建。如果你需要先配置证书， iOS 证书生成器 可以提供帮助。

7. 通过 live update 发布热修复

Use the capgo-live-updates skill to build the web app and upload it to the
beta channel. Check native compatibility first.

Agent 运行构建，然后：

bunx @capgo/cli@latest bundle upload --channel=beta

兼容性检查会将原生依赖项与设备上安装的内容进行对比，从而确保 Agent 不会推送需要商店构建版本中缺失的原生插件的 bundle。在 Beta 环境测试通过后再发布到生产环境。参见 Capgo live updates 的工作原理.

保障 Agent 工作安全的防护栏

• 在进行原生变更前先进行规划。 针对任何变更，请要求 Agent 提供方案和 diff。 ios/ 和 android/.
• 避免在对话中泄露密钥。 自行保存 build 凭据和 API 密钥，将凭据文件加入 git-ignore，切勿将密钥粘贴到 prompt 中。
• 利用 Channel 作为安全网。 让 Agent 将内容 upload 到 beta 或 internal channel，由你亲自执行生产环境的 Promote。
• 依赖 Rollback 机制。 Capgo 会在新的 bundle 启动失败时将设备回滚至上一个可用的版本，从而降低 bad upload 带来的影响。
• 优先使用可审计的命令。 上述 CLI 命令在 Agent 的 log 中清晰易读。如果你不确定某个 MCP tool 做了什么，可以让 Agent 展示对应的 CLI 命令。
• 应用商店提交由人工把控。 Agent 可以准备 build 和元数据，但提交审核以及回复审核人员的工作应由人工完成。

故障排除

Agent 忽略了该技能。 在 prompt 中明确指出名称，并检查该 agent 是否已安装（重新运行 bunx skills add Cap-go/capgo-skills).

缺少 MCP tools。 对于 CLI 服务器，请确认 bunx @capgo/cli@latest login 在 agent 运行的相同环境中执行成功。添加服务器后请重启 agent。

Agent 建议了过时的 Capacitor API。 告知其你的 Capacitor 版本，并让其通过托管的 MCP capgo_search_docs tool 进行文档检索。

Cloud build 签名失败。 凭据缺失或 provisioning profile 与 bundle ID 不匹配。请重新保存凭据并重新发起 build 请求。

Upload 被拒绝，版本不兼容。 Bundle 需要 native 变更。请先发布 Store build，然后再发布 live update。

总结

一旦 AI agents 不再“瞎猜”，它们对 Capacitor 就会变得非常有用。安装 Capacitor 技能以确保它们遵循正确的流程，连接用于文档的公共 Capgo MCP 以及用于账户操作的 CLI MCP，并针对原生变更、密钥和生产环境 channel 设置一些防护栏。欲了解更多关于在应用本身构建 AI 功能的内容，请阅读 为什么 Capacitor 非常适合 AI 移动应用.