capacitor-plugin-generator

Capacitor 插件生成器

根据自然语言意图或结构化 YAML 契约，生成一个可供审查的 Capacitor 插件候选版本。输出应遵循官方 Capacitor 插件架构，但这只是初稿，发布前需要人工审查。

何时使用此技能

✅ 在以下情况下使用此技能：

• 从头开始创建新的 Capacitor 插件。
• 为 Capacitor 应用添加原生功能（相机、传感器、存储等）。
• 设计插件架构和 API 契约。
• 为 iOS（Swift）或 Android（Kotlin/Java）实现原生代码。
• 将原生 API 桥接到 JavaScript/TypeScript。
• 配置插件及其构建系统。
• 根据 cordova-capacitor-plugin-migration 技能移交的结构化 YAML 契约生成插件。

❌ 请勿在以下情况下使用此技能：

• 构建标准 Capacitor 应用（请改用 Capacitor 文档）。
• 实现无需原生桥接的纯 Web 功能。
• 修改现有的 Capacitor 核心插件。
• 分析 Cordova 插件结构（请先使用 cordova-capacitor-plugin-migration；该技能会生成此技能所需的输入契约）。
• 将现有插件升级到较新的 Capacitor 版本。
• 未经人工审查就发布可用于生产环境的代码。

先决条件

要求	用途
Node.js LTS 和 npm	运行 Capacitor 插件生成器和包脚本。
Xcode	目标平台为 iOS 时，构建并验证 iOS 输出。
Android Studio 和 Android SDK	目标平台为 Android 时，构建并验证 Android 输出。
CocoaPods 和 Gradle	在生成的代码需要时解析原生依赖项。
Capacitor 插件知识	发布前审查生成的原生桥接代码。

Agent 行为

• 判断用户提供的是对话式意图还是结构化 YAML。
• 在对话模式下，只询问缺失的插件标识、方法、平台、事件、权限、配置和原生依赖项。
• 在结构化模式下，解析 references/input-contract.md，跳过需求收集；如果可选的迁移部分包含阻碍项或三级钩子，则停止。
• 仅将迁移元数据作为实现上下文。不要检查或分析 Cordova 源码；这属于迁移技能的职责。
• 优先使用官方 Capacitor 插件生成器，然后编辑生成的脚手架以实现所需 API。
• 保持生成的代码以契约为先：TypeScript 定义决定 Web、iOS、Android、文档和示例应用的行为。
• 仅使用已安装的 @capacitor/core、@capacitor/android 和 @capacitor/ios 包中存在的 Capacitor 类。不要臆造辅助类、实用程序或导入路径。如果不确定某个 API 是否存在，请阅读包源码，而不要根据名称推断。
• 当生成的 TypeScript 契约对应于现有公共 API（Capacitor core/community、Capawesome、内部库，或用户正在替换的有文档记录的 JavaScript API）时，查明实际在线路上传输的字符串字面值。不要根据便于理解的名称推导这些值。结构化模式的 YAML 会明确指定这些值；对话模式的生成必须查阅源码。
• 保持桥接文件精简。如果某个方法会因此变成职责混杂的大型代码块，就将原生逻辑拆分到实现、管理器、权限、配置和映射辅助模块中。
• 根据预期产品行为选择原生 API，而不是为了演示方便。如果所需行为需要权限、特殊应用设置或手动应用配置，则生成合适的 checkPermissions() / requestPermissions() 流程，并记录手动设置步骤。
• 清楚说明已运行哪些验证命令，以及哪些命令需要在本地由人工或设备验证。
• 绝不要通过此技能正式发布。仅运行发布检查和 npm publish --access public --dry-run。

流程

阶段 1：确定任务和输入模式

阅读 references/input-contract.md。如果输入是包含 plugin、 platforms 和 api 的 YAML，则将其解析为结构化模式，并跳过提问。如果 输入是对话式的，则询问创建相同契约结构所需的最少缺失字段。

阶段 2：搭建脚手架

阅读 references/scaffolding.md。尽可能使用非交互式标志运行官方 Capacitor 插件生成器。确保名称一致： registerPlugin() 的 JavaScript 名称等于 iOS jsName，也等于 Android 的 @CapacitorPlugin(name)。

阶段 3：设计 TypeScript API

阅读 references/api-design.md。在实现原生代码之前定义 src/definitions.ts。每个方法使用选项和结果接口，使用字符串联合类型而非枚举，为事件使用监听器签名，并在所有 JSDoc 中添加 @since。

阶段 4：实现 Web 层

阅读 references/web-guide.md。扩展 WebPlugin，在使用浏览器 API 前进行特性检测；如果 API 存在但当前浏览器无法使用，则抛出 unavailable()；如果没有对应的 Web 实现，则抛出 unimplemented()。通过动态导入注册 Web 层。

阶段 5：定义方法签名

阅读 references/api-design.md。为每个方法选择一种桥接返回类型：值、void 或回调。仅对流或长期运行的监听器使用回调返回类型。确保 TypeScript、Web、iOS 和 Android 中的事件名称完全一致。

阶段 6：实现 iOS

阅读 references/architecture-patterns.md 和 references/ios-implementation.md。默认使用 Bridge 模式：精简的 Capacitor 插件类委托给实现类。仅当插件较复杂，包含多个原生子系统、权限流程或生命周期问题时，才使用 Facade。

阶段 7：实现 Android

阅读 references/architecture-patterns.md 和 references/android-implementation.md。默认使用 Bridge 模式：精简的 Plugin 类委托给实现类。仅当插件较复杂，包含多个管理器、权限流程、服务、Activity 或生命周期钩子时，才使用 Facade。

阶段 8：生成示例应用

阅读 references/sample-app.md。创建或更新示例应用，以覆盖插件的整个公开 API，包括成功路径、预期错误、权限、配置和监听器。

阶段 9：生成文档并验证

阅读 references/testing-strategies.md 和 references/publishing.md。 使用 npm run docgen 根据 JSDoc 生成 API 文档；不要手动编写 API 文档。 运行目标平台对应的验证命令，并记录受环境限制而无法完成的检查。

阶段 10：发布检查

阅读 references/publishing.md。运行发布前检查清单和试运行： npm publish --access public --dry-run。未经明确的人工审核，不要发布生成的插件；该审核不属于此技能的范围。

最佳实践

应做

• ✅ 使用 npm init @capacitor/plugin 的命令行标志，让脚手架以非交互方式运行。
• ✅ 在提问前检测入口模式（对话式还是结构化 YAML）。在结构化模式下完全跳过信息收集。
• ✅ 先设计 TypeScript API（契约优先），再根据该契约实现 Web、iOS 和 Android。
• ✅ 实现 Web 层，以便在没有设备的情况下进行测试，即使大多数方法都会抛出 unimplemented() 也一样。
• ✅ 镜像现有 API 时，检查官方插件的原生依赖；声明相同的 SDK，并编写精简的适配器，而不是重新实现。
• ✅ 使用 JSDoc 和 @since 为每个公共符号编写文档。
• ✅ 提交前运行 npm run fmt，报告完成前运行 npm run verify。
• ✅ 在 iOS 和 Android 上使用双类模式（桥接类 + 实现类），以便测试。
• ✅ 镜像现有 API 时，精确匹配线格式字符串值和数字值。查阅官方 definitions.ts，不要根据易懂的名称猜测。
• ✅ 确保 TypeScript / Web / iOS / Android 中的事件名称完全一致。

不应做

• ❌ 混合不同关注点——让插件专注于单一功能。
• ❌ 跳过错误处理。使用规范的 4 种错误代码（UNAVAILABLE、PERMISSION_DENIED、INVALID_PARAMETER、OPERATION_FAILED）拒绝请求。
• ❌ 在 TypeScript 接口中使用回调，而不是 Promise。
• ❌ 忘记 Web 实现，即使功能仅适用于 iOS/Android 也一样。
• ❌ 对应该可配置的值进行硬编码。使用 references/configuration.md 中的运行时插件配置。
• ❌ 臆造 Capacitor 类、辅助工具或导入路径。请对照已安装的 @capacitor/core、@capacitor/android 和 @capacitor/ios 软件包进行验证。
• ❌ 从 Plugin 子类之外调用 notifyListeners(...)——请参阅 references/architecture-patterns.md 中的“Event Dispatch Locality”。
• ❌ 使用此技能发布。仅运行试运行：npm publish --access public --dry-run。
• ❌ 检查或分析 Cordova 源码——这属于配套迁移技能的范畴。

错误处理

症状	修复方法
npm init @capacitor/plugin 失败，并显示 Refusing to prompt in non-TTY environment	以非交互方式传入所有必需标志：npm init @capacitor/plugin <folder> -- --name "<npm-name>" --package-id "<reverse-dns>" --class-name "<PascalCase>" --description "<one-line>" --author "<name <email>>" --license "<SPDX>" --repo "<url>" --android-lang "<kotlin|java>"。请参阅 references/scaffolding.md。
npm init @capacitor/plugin 失败，并显示 invalid option: --android-lang undefined: Must be either 'kotlin' or 'java'	以非交互方式运行时，必须指定 --android-lang 标志。请在命令中添加 --android-lang "kotlin"（新插件推荐）或 --android-lang "java"。
插件加载失败，但没有任何提示	确保 registerPlugin() 的名称与 iOS jsName 和 Android @CapacitorPlugin(name) 一致。
JS 未收到事件	确保 TypeScript、Web、iOS 和 Android 中的事件名称字符串完全相同。
JS 无法调用 iOS 方法	确保该方法标记为 @objc，并列在 pluginMethods 中。
JS 无法调用 Android 方法	确保该方法是公开的，并使用 @PluginMethod() 标注。
npm run verify:ios 失败	运行 pod install --repo-update，然后重新运行 iOS 验证命令。
npm run verify:android 失败	同步 Gradle，并检查 Android SDK、compile SDK 和依赖项版本。
Android 编译错误：class X is public, should be declared in a file named X.java	Java 要求公有类必须放在与其同名的文件中。为每个插件生成多个 Java 类时，请将每个公有类放在单独的文件中。Kotlin 没有此限制。
Android 编译错误：notifyListeners(...) has protected access in Plugin	Plugin 中的 notifyListeners() 是 protected。只能在继承 Plugin 的类内部调用。如果其他类需要发送事件，请将数据返回给插件并在那里分发，或在插件上公开一个内部调用 notifyListeners() 的包装方法。
Android 编译错误：com.getcapacitor.* 导入的 class … 符号无法解析	已安装的 @capacitor/android 中不存在此导入。生成前请根据软件包源代码核实导入；不要根据名称推断 Capacitor 类。
Android 编译错误：<method> in <Subclass> cannot override <method> in Plugin; attempting to assign weaker access privileges; was public	Plugin 子类中的辅助方法与 com.getcapacitor.Plugin 已定义的 public 方法冲突（例如 hasPermission、getPermissionState、notifyListeners）。请重命名辅助方法，或将其可见性设为与父类的 public 一致。
TypeScript 构建错误：Cannot find type definition file for '<name>' 或 Invalid module name in augmentation, module '<name>' cannot be found	被扩充的模块尚未安装。请将其添加到 devDependencies（如果使用了三斜线引用，还需添加到 tsconfig.json 的 compilerOptions.types 中）。这适用于任何模块扩充，不仅限于 @capacitor/cli。
TypeScript 构建错误：Interface 'X' incorrectly extends interface 'Y'. Property 'Z' is optional in type 'X' but required in type 'Y'（或相反的错误）	不要重新声明内置 lib 类型已提供的成员。请直接使用 lib 类型，或仅通过 declare global { interface Y { newMember?: ... } } 扩充真正新增的成员。使用 'name' in target 运行时检查能力。
npm run docgen 生成的输出为空	在 src/definitions.ts 中添加 JSDoc；docgen 会读取 TypeScript 契约。
目标浏览器中没有 Web API	如果该 API 存在但当前环境不支持，请使用 unavailable()；如果没有对应的 Web 实现，请使用 unimplemented()。
结构化 YAML 被拒绝	根据 references/input-contract.md 进行验证；确保必需的基础字段齐全，且阻塞项为空。
生成的输出范围过广	将无关功能拆分为独立插件，并缩小 API 范围后重新生成。
生成的原生代码重新实现了官方插件委托给原生 SDK 的逻辑	检查官方插件的 .podspec / Package.swift / android/build.gradle 中是否依赖原生 SDK。如果存在，请声明相同的 SDK 并编写轻量适配器——请参阅 references/api-design.md 中的 “Native Dependency Detection”。

相关技能

• cordova-capacitor-plugin-migration：分析 Cordova 插件，并为此生成器制定结构化迁移计划。

参考资料

• references/input-contract.md：生成器输入的结构化 YAML 契约。
• references/scaffolding.md：生成器调用、名称一致性和脚手架验证。
• references/api-design.md：TypeScript API 设计、JSDoc、事件签名和方法返回类型。
• references/web-guide.md：WebPlugin 模式、动态导入、功能检测和错误。
• references/architecture-patterns.md：Bridge 和 Facade 模式，以及事件一致性。
• references/ios-implementation.md：iOS Bridge、实现类、权限、依赖项和 Podspec。
• references/android-implementation.md：Android Bridge、实现类、权限、依赖项和 Gradle。
• references/configuration.md：plugins.<PluginJSName> 下的 Capacitor 配置键。
• references/testing-strategies.md：本地链接、验证命令、钩子和审查工作流。
• references/publishing.md：软件包字段、docgen、检查清单和发布试运行。
• references/sample-app.md：演练完整 API 的示例应用要求。
• references/permission-patterns.md：深入讲解权限流程——iOS 上的多权限 DispatchGroup、位置代理、使用前检查／即时／延迟使用方模式，以及打开系统设置。
• references/typescript-implementation.md：深入讲解 TypeScript 层——单例插件模式、类型化错误类、完整的事件监听器句柄记录、辅助工具和 Jest 脚手架。