如何在 Capacitor App 开发中使用 AI Agent

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

本指南会说明通用 Agent 为什么会在 Capacitor 上出错、如何用几条命令配好 skills 和 MCP、应用生命周期各阶段该用的 prompts，以及保障安全的防护措施。

为什么通用 Agent 搞不定 Capacitor

Agent 在 Web code 上很强。Capacitor 项目却多出另一半，而且每年都在变：

• 版本漂移。 Capacitor 8 更改了 Android SDK 级别，新的 iOS 项目默认使用 Swift Package Manager，并且 App Store 上传需要 Xcode 26。训练数据里混杂着 Capacitor 3 到 8 的各种建议。
• 跨文件的 Native 配置。 单个插件可能需要 Info.plist keys、entitlements、 AndroidManifest.xml 权限、Gradle 改动，以及一个 cap sync。Agent 通常只做 JavaScript 部分。
• 插件选择。 许多社区插件已无人维护。Agent 会挑它见得最多的，而不是在 Capacitor 8 上真正能用的。
• 隐形故障。 错误藏在 Xcode、Logcat 或 CI 日志里，而不是编辑器中。

解决方式是给 Agent 提供可按需加载的上下文，以及可调用而非靠猜的工具。

工具包：Skills、MCP 和 CLI

安装 skills

bunx skills add Cap-go/capgo-skills

安装程序会检测受支持的 agents，并把 skills 放到每个 agent 会查找的位置。这套 skills 涵盖插件选择、最佳实践、Capacitor 应用和插件的大版本升级（包括 v7 到 v8）、CocoaPods 到 SPM 迁移、调试、iOS 和 Android 日志、推送通知、deep link、安全区域、安全扫描、测试、CI/CD、App Store 预检、Cordova 和 Web 应用迁移、Capgo 实时更新以及 Capgo 原生构建。 skills 页面 列出所有技能。

在 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 生命周期中使用智能体

在 prompt 中指定技能名称。这能让智能体加载正确的流程，而不是随意发挥。

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.

智能体安装 @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 插件目录，因此代理会选择受维护的插件并添加 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.

日志技能为代理提供确切的 adb 和 Xcode 命令，用于流式传输和过滤设备日志，使其能够读取真实的堆栈跟踪，而不是从源代码中猜测。

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.

对于任何涉及 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 工作安全的护栏

• 做原生改动前，先制定计划。 以下改动都先要计划和 diff ios/ 以及 android/.
• 避免在对话中泄露密钥。 自行保存 build 凭据和 API 密钥，用 git 忽略凭据文件，切勿把密钥粘贴到 prompt 中。
• 把 channel 当作安全网。 让 agent 上传到 beta 或 internal channel，生产环境由你亲自 promote。
• 依赖 rollback。 Capgo 会在新 bundle 启动失败时，将设备回滚到上一个可正常运行的 bundle，从而降低一次有问题的上传造成的损害。
• 优先使用可审查的命令。 上述 CLI 命令在 agent 的日志中清晰易读。如果不确定某个 MCP 工具做了什么，可以让 agent 展示等效的 CLI 命令。
• 应用商店提交仍由人工负责。 agent 可以准备 build 和 metadata，但提交审核和回复审核人员仍应由人工负责。

故障排除

Agent 忽略了该 skill。 在 prompt 中明确指定它，并确认已为该 agent 安装（重新运行 bunx skills add Cap-go/capgo-skills).

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

Agent 建议了过时的 Capacitor API。 告知它你的 Capacitor 版本，并让它使用托管的 MCP 搜索文档 capgo_search_docs 工具。

云端构建在签名时失败。 凭据缺失，或描述文件与 Bundle ID 不匹配。请重新保存凭据并重新运行构建请求。

上传被拒绝，提示不兼容。 该 bundle 需要原生代码变更。请先发布商店构建版本，然后再发布 live update。

总结

AI agent 只有不再靠猜，才能真正对 Capacitor 有用。安装 Capacitor 技能，让它们遵循正确流程；连接用于文档的公共 Capgo MCP 和用于账户操作的 CLI MCP，并在原生变更、密钥和生产 channel 周围保留一些防护措施。想了解如何在应用内构建 AI 功能，请阅读 为什么 Capacitor 非常适合 AI 移动应用.