build-actions-generator

ODC 构建操作生成器

为通过 MABS 12+ 面向 Android 和 iOS 的 ODC 移动端库（Capacitor 和 Cordova 插件）及 ODC 应用生成 buildAction.json。

适用场景

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

• 为 ODC 移动端库（Capacitor 或 Cordova 插件）生成 buildAction.json 文件。
• 为需要原生构建配置的 ODC 应用生成 buildAction.json 文件。
• 为调整为适用于 ODC（基于 Capacitor）部署的 Cordova 插件生成构建操作。
• 配置 Android 的 AndroidManifest.xml、Gradle 文件或 XML 资源。
• 配置 iOS 的 Info.plist、entitlements 或显示名称。
• 定义输入变量（字符串、数字、布尔值）和条件逻辑。
• 根据插件的原生需求，为两个平台搭建构建操作。
• 使用插件路径参数调用，或在 Capacitor 或 Cordova 插件目录中调用。

❌ 请勿将此技能用于：

• 在 ODC Studio/Portal 中上传或引用 JSON（步骤 2–3 — 请参阅手动指南）。
• Cordova 可扩展性配置或 O11 可扩展性 JSON。
• Cordova 应用构建、O11 构建或早于 12 的 MABS 版本 — 构建操作仅适用于 ODC 上的 Capacitor 应用（MABS 12+）。
• 位于构建操作 JSON 之外的应用级构建配置。
• 发布或测试插件（步骤 4 — 由开发者负责）。

---

端到端流程

此技能仅处理步骤 1。步骤 2–4 需要手动完成。

步骤	负责人	内容
1. 生成 JSON	此技能	创建包含所有必需平台操作的 buildAction.json
2. 上传 JSON	开发者	将文件添加到 ODC Studio 中的插件/库 → Resources，然后在 Extensibility 选项卡中引用该文件，并为任何变量创建 Extensibility Settings。
3. 在 Portal 中关联	开发者	如果构建操作包含参数，请在 ODC Portal → Mobile Distribution 选项卡 → Extensibility settings 中提供参数值
4. 发布并测试	开发者	使用 MABS 12（Capacitor）或更高版本测试移动端构建

---

JSON 文件结构

输出位置： 在插件根目录的 build-actions/ 文件夹中写入两个文件：

• build-actions/buildAction.json — 构建操作配置
• build-actions/README.md — 便于阅读的文档（请参阅生成指南步骤 5）

始终在所提供目录的顶层（如果未提供路径参数，则在当前工作目录）创建 build-actions/。 即使扫描的源文件位于子目录中，也绝不要在 plugin/、android/ 或 ios/ 等子目录中创建该文件夹。如果插件仓库采用嵌套结构（例如 plugin/android/、plugin/ios/），输出仍应放在仓库根目录：build-actions/buildAction.json。

{
  "variables": { },       // optional — input parameters for the build action
  "platforms": {
    "android": { },       // optional — Android-specific actions
    "ios": { }            // optional — iOS-specific actions
  }
}

文件命名： 使用驼峰命名法，不含空格。

✅ buildAction.json、pushNotifications.json、cameraPlugin.json ❌ build action.json、Build_Action.json

platforms 下必须至少包含 android 或 ios 之一。

---

变量和条件

如果构建操作使用变量或条件，请阅读 references/variables-and-conditions.md，了解完整语法和示例。

• 变量（"variables" 键）——由插件开发者声明的类型化输入（string、number、boolean）；使用插件的应用通过可扩展性配置中的 parameters 块提供值。除非该值确实为必填项，否则始终提供 default；如果未提供默认值，且该变量未设置，构建就会失败。
• 平台特定变体——如果同一个逻辑值（例如 App ID、API 密钥）同时用于 Android 和 iOS，但通常因平台而异，请使用 _ANDROID 和 _IOS 后缀分别定义变量（例如 ADMOB_APP_ID_ANDROID、ADMOB_APP_ID_IOS）。不要将它们合并为一个共享变量——开发者必须能够分别为每个平台配置变量。
• 条件——在任一操作条目中添加 condition 字段，以便有条件地跳过该操作（displayName、productName 和 appName 除外）；有关语法和运算符，请参阅参考文件。

如果定义了变量，请阅读 references/extensibility-configuration.md，了解可扩展性配置中的 parameters 如何为 buildAction.json 中声明的变量提供值。如果库和使用该库的应用都定义了构建操作，则先运行库的构建操作。

---

Android 操作

如果目标平台是 Android，请阅读 references/android-build-actions.md，了解完整的操作架构和示例。

可用操作：

• appName — 设置 Android 应用名称（字符串，不支持条件）
• manifest — 修改 AndroidManifest.xml（设置属性、合并或注入 XML）
• gradle — 修补 Gradle 构建文件（在目标 DSL 路径插入或替换）
• res — 在 res/ 文件夹下创建资源文件
• json — 修改 JSON 文件（set 或 merge）
• xml — 修改任意 XML 资源文件
• copy — 将文件、目录或 URL 复制到项目中
• code — 添加或修补原生 Android（Java/Kotlin）源文件（source+targetDir、file+target+replace，或 file+patchFile）
• tar — 对项目文件应用 tar 操作

---

iOS 操作

如果目标平台是 iOS，请阅读 references/ios-build-actions.md，了解完整的操作架构和示例。

可用操作：

• displayName — 设置显示在主屏幕上的应用显示名称（不支持条件）
• productName — 设置显示在 App Store 中的产品名称（不支持条件）
• buildSettings — 以键值对形式设置 Xcode 构建设置
• buildPhases — 添加或替换自定义 shell 脚本构建阶段
• plist — 修改 Info.plist 或其他 plist 文件（替换或合并条目）
• xcprivacy — 更新 PrivacyInfo.xcprivacy
• entitlements — 添加或修改 entitlements（对象，不是数组）
• frameworks — 将系统或自定义框架添加到 Xcode 项目
• json — 修改 JSON 文件（set 或 merge）
• xml — 修改任意 XML 文件
• copy — 将文件、目录或 URL 复制到项目中
• strings — 更新 .strings 本地化文件
• xcconfig — 更新 .xcconfig 构建配置文件
• code — 添加或修补原生 iOS（Swift/Objective-C）源文件（source+compilerFlags、file+target+replace，或 file+patchFile）
• tar — 对项目文件应用 tar 操作

---

生成指南

1. 读取插件输入信号

如果提供了路径参数，则插件根目录为该路径；否则为当前目录。在向开发者提问之前，先检查插件中是否存在相关信号：

• 如果插件根目录下存在 input-contract.yaml，请根据完整的 capacitor-plugin-generator/references/input-contract.md 架构读取，并提取以下相关部分：
  • migration.hooks（tier_1 / tier_2 / tier_3）——用于推导构建操作的钩子分类。
  • dependencies.android.gradle 和 dependencies.ios.{cocoapods,spm,system_frameworks}——基于依赖的操作（Gradle 补丁、框架条目）。
  • permissions.android 和 permissions.ios——权限操作（清单 <uses-permission>、plist 使用说明）。
  • plugin.name——用于 README 标题。
  • 所有其他字段（api.methods、api.types、api.events 等）均无关——直接忽略。
• 始终也要直接扫描插件源代码，即使存在契约也不例外。契约仅作为起点；扫描源代码可以发现契约可能未涵盖或已过时的信号：
  • **Cordova 插件：**解析 plugin.xml——阅读 references/cordova-plugin-scanning.md，了解完整的元素到操作映射和钩子分类指南。
  • **Capacitor 插件：**扫描插件文档、package.json 和原生源文件（Java/Kotlin 和 Swift/Objective-C）——阅读 references/capacitor-plugin-scanning.md，了解完整的扫描指南。
• 作为 cordova-plugin-migrator ODC 流程（Phase 11a）的一部分调用时，输出（build-actions/）会写入 Capacitor 插件目录，而不是 Cordova 源代码树。cordova-plugin-migrator 会将 Capacitor 插件路径作为工作目录或参数提供。

2. 收集需求

询问开发者（或根据上下文推断）：

• 插件需要哪些原生功能？（相机、位置、推送、蓝牙等）
• 目标平台有哪些：仅 Android、仅 iOS，还是两者都支持？
• 开发者需要控制运行时配置值吗？（→ 变量）
• 是否有操作取决于这些值？

3. 将需求映射到操作

原生需求	Android 操作	iOS 操作
运行时权限	manifest 注入 <uses-permission>	plist 使用说明键
自定义 URL 方案	manifest 合并 intent-filter	plist CFBundleURLTypes
自定义应用属性	manifest 属性	—
原生依赖	gradle 替换	—
推送通知	manifest 合并 + gradle	entitlements aps-environment
App 组	—	entitlements com.apple.security.application-groups
自定义显示名称	—	displayName
自定义原生代码	code 注入/替换	code 注入/替换

如果某个钩子或元素无法明确映射到上述任何操作，请阅读 references/common-scenarios.md，了解那些看似无法映射、但有对应构建操作的模式。

4. 生成 JSON

• 文件名：使用 camelCase，不含空格（例如：buildAction.json）
• 仅包含实际有操作的平台
• 对开发者控制的值使用 $VAR_NAME 替换
• 除非确实必须提供变量值，否则为变量添加 default——如果没有默认值，且插件库或使用该插件的应用都未在扩展配置 parameters 中提供变量值，构建就会失败
• 仅在操作应有条件地跳过时添加 condition
• 在 manifest 中优先使用 merge 而非 inject，以避免重复条目
• 输出有效且格式规范的 JSON
• code 操作有特定于平台的文件路径约定——iOS 使用 Swift/Objective-C 文件（例如 App/AppDelegate.swift）；Android 使用 Java/Kotlin 文件（例如 app/src/main/java/com/example/App.java）。不要混用不同平台的约定。
• 优先使用配置级操作，而非 code——manifest、gradle、plist、xml 和 entitlements 可满足大多数原生需求，无需修改源文件。只有在不存在配置级替代方案时，才生成 code 操作。如果需要生成，请使用 file+target+replace；切勿使用 patchFile——它在 ODC 构建中不可靠。如果无法通过简单的字符串替换实现更改，请简要告知用户此方法在 ODC 中不可靠，并建议改用 Capacitor hook（超出此技能的范围）。不要解释 ODC 内部机制。
• 如果源文件是在运行时由用户提供的，请避免使用 tar 和 copy——只有在源文件位于插件包内的硬编码路径中，或来自外部 URL 时，这些操作才可靠。如果用例需要用户提供文件，请简要建议用户考虑改用 Capacitor hook。不要解释 ODC 内部机制。

写入 JSON 文件后，在继续之前验证其语法：

1. 告诉用户："正在验证 JSON 语法..."
2. 尝试运行 python3 -m json.tool build-actions/buildAction.json > /dev/null——如果有 python3，请使用此命令。
3. 如果没有 python3，尝试运行 jq empty build-actions/buildAction.json。
4. 如果这两个工具都不可用，请仔细检查文件：确认大括号和方括号成对、没有尾随逗号，并且字符串值中的转义正确（尤其注意 manifest/plist 条目中的 XML 内容，其中的引号必须转义为 \"）。
5. 如果工具或自检发现错误，请修复文件，并从第 2 步重新开始，直到 JSON 有效。
6. 只有验证通过后，才继续执行生成指南第 5 项（README）。

5. 生成 README 并完成

在 JSON 文件旁生成 build-actions/README.md。它是该插件的源代码管理文档，也是开发者设置 ODC 的主要参考。阅读 references/readme-template.md 了解必需的结构，然后遵循以下编写规则。

README 编写规则：

• 如果某个平台没有操作，则省略 ### Android 或 ### iOS 部分。
• 如果所有输入信号都已映射到构建操作，则完全省略 ## What requires additional setup。仅当发现无法映射的钩子或元素时才包含此部分。
• 如果没有变量，则完全省略 ## Variables 部分。
• 如果插件没有变量，则省略 ## ODC Setup 中第 2 步 JSON 块下方的可扩展性设置说明——此时不存在 parameters 键，因此这些说明没有适用背景。
• 在 ## Variables 表格中，如果没有默认值，则将 Required 设为 yes；如果存在默认值，则设为 no。当 Required 为 yes 时，Default 填写 —。
• ## ODC Setup 中的可扩展性 JSON 应使用生成的 JSON 中的实际变量名称，而不是占位符 VAR_NAME。
• 在 ## What requires additional setup 中，将 Recommended approach 设为：
  • 脚本类型钩子使用 Capacitor hook——具体说明钩子必须执行的操作
  • 用户提供的文件使用 ODC resource——告知开发者在 ODC Studio 中将文件添加为 ODC 资源（Deploy Action：Deploy to Target Directory）
  • 阻碍项使用 Not supported in ODC——ODC 开发者无法访问原生项目，因此没有手动替代方案；简要说明需要重新设计的原因
• 可扩展性配置权限替代方案：仅当 (a) 开发者明确询问了可扩展性配置，或 (b) 每个生成的构建操作都仅为 manifest <uses-permission> 条目和/或 plist iOS 使用说明条目时，才在 README 中提及 pluginConfigurations.permissions——这意味着整个 buildAction.json 都可以由库可扩展性配置中的 permissions 块替代。其他情况下均不要提及；参考文档见 references/extensibility-configuration.md。

生成两个文件后的终端输出：

• 不要输出 buildAction.json 的内容——写入文件时已显示这些内容。
• 不要在终端显示分析表、扫描结论或逐项元素推理。内部推理应保留在内部；无法明确映射的重要决定应写入 README，而不是终端。
• 只输出一条简短提示：“构建操作已写入 build-actions/。这是候选配置——使用前请检查 build-actions/buildAction.json，然后通过 MABS 12+ 构建以及针对真实移动应用的功能测试进行验证。有关此配置的内容摘要和 ODC 设置说明，请参阅 build-actions/README.md。”
• 如果 README 中写入了 ## What requires additional setup，再添加一行：“部分钩子或元素无法映射到构建操作——详情请参阅 build-actions/README.md。”
• 如果开发者未明确说明目标平台为 ODC，则添加一句说明：构建操作仅在 ODC 构建中生效，不适用于独立的 Capacitor 应用。
• 不要在终端重复 ODC 设置步骤。