appbuilder-project-init

App Builder 项目初始化

将用户意图映射到合适的 Adobe App Builder 模板，并以非交互方式运行 aio app init。默认模板：@adobe/generator-app-excshell（SPA + actions）。对于无头／精简项目，请使用 init-bare。

如果 Developer Console 项目／工作区／API 订阅尚不存在，此技能会引导 Agent 直接调用 aio console …，以非交互方式创建这些资源——请参阅 Bootstrap 部分和 references/bootstrap.md。最新版 @adobe/aio-cli 套件支持以非交互方式运行 aio console project create / workspace create / api list / workspace api add（对于需要产品配置文件的服务，可使用 --license-config），以及 aio app init --org/--project/--template-options。这些命令共同移除了 Agent 设置流程中所有阻碍操作的“打开 Developer Console UI 并点击”步骤。只需安装最新版 CLI（npm install -g @adobe/aio-cli）并使用这些命令。

机器设置（首次）

在初始化项目之前，每台机器只需执行一次——每个环境还需登录一次。如果已安装 CLI 且已登录，请跳到下方的 Bootstrap。

1. Node 20

App Builder 需要 Node 20（npm 随其一同安装）。检查当前启用的版本：node -v → 应为 v20.x。

• 已安装 nvm？ 执行 nvm install 20 && nvm use 20 && nvm alias default 20，以便新终端持续使用该版本。如果安装了多个 Node 版本，当前启用的版本必须是 20。
• 没有 Node／nvm？ 安装 nvm，然后安装 Node 20：

  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
  # reopen the shell, then:
  nvm install 20 && nvm use 20 && nvm alias default 20
  

  （其他方式：brew install node@20，或使用 nodejs.org 上的官方安装程序。）

Adobe 的旧文档提到 Node 18——请使用 20。全局安装的 aio 属于运行 npm i -g 时启用的 Node 版本；如果切换 Node 版本，旧的 aio 就不会出现在 PATH 中。版本不匹配的表现：aio 因 SyntaxError: Unexpected token '??=' 而退出（Node 20 之前的版本无法解析适用于 Node 20 的 aio）——请执行 nvm use 20 并在该版本下重新安装 aio。

2. 安装 aio CLI 并登录

npm install -g @adobe/aio-cli      # on Node 20
aio login                          # opens a browser; `aio login -f` forces a fresh prompt
aio where                          # confirm the correct IMS org/context
aio console org list               # list orgs and their IDs (then `aio console org select <id>` if needed)

CLI 会自动存储令牌；一次普通的 aio login 可持续数小时／数天——每个会话登录一次，而非每条命令都登录。确认使用的是正确的 IMS 组织——选错组织是最常见的设置错误。

3. Stage 与 prod

默认环境为 prod。若要使用 stage，请设置环境变量并重新进行身份验证：

export AIO_CLI_ENV=stage
aio logout && aio login

取消设置该变量（或打开新终端）即可返回 prod。stage CLI 会连接 stage Console（developer-stage）。

无浏览器登录（CI／无人操作）

• **导入凭据：**在 Developer Console 中打开工作区 → Download all → console.json，然后运行 aio app init <app> --import path/to/console.json（会填充 .env／.aio——请将 console.json 视为机密文件，并将其加入 gitignore）。
• **CI／流水线：**向工作区添加 OAuth Server-to-Server 凭据；aio 和 Runtime 可使用客户端 ID／密钥进行身份验证，无需人工操作。不要在无头环境中编写 SSO／MFA 脚本。

引导设置 Developer Console（项目、工作区、API）

如果用户从零开始——尚无 Developer Console 项目，或者现有项目缺少工作区或 API 订阅——请在运行 aio app init 之前完成引导设置。否则，aio app init／aio app use／aio app deploy 将无法将本地应用关联到任何资源。

完整的引导设置只需使用 aio 命令；请直接调用命令，不要通过包装脚本调用。新版插件已支持以非交互方式运行这些命令；逐步调用还能让你根据“已存在”或“需要产品配置文件”等响应作出处理，而不必把这些判断写进 bash。

预检

确保 CLI 已更新——非交互式 Console 和应用初始化命令由此提供：

npm install -g @adobe/aio-cli
aio --version

不要尝试指定特定的插件版本；直接使用最新版本。如果此后某个 console 或 app 子命令被拒绝，并提示“command not found”或“unknown flag”，说明 CLI 安装确实失败了（PATH 问题、权限问题或注册表镜像问题）——请修复安装，而不是尝试绕过问题。

确认已选择组织（或在以下每条命令中传入 --orgId）：

aio console org list --json   # if needed, then:
aio console org select <orgId>

决策规则

用户状态	下一步操作
“从头创建项目 + 工作区 + 添加 API”	运行引导链（项目 → 工作区 → API），然后运行 aio app init。
项目已存在，工作区缺失	跳过创建项目。运行 aio console workspace create，然后按需运行 aio console workspace api add。
项目 + 工作区已存在，只需添加 API	运行 aio console api list 查找服务代码，然后运行 aio console workspace api add。
所有内容都已配置	跳过引导。直接执行通过脚本初始化。

创建前，务必使用 aio console project list --json 和 aio console workspace api list --projectName <p> --workspaceName <w> --json 检查现有内容——如果对象“已存在”，这些命令会明确报错，而且没有内置的幂等机制。

引导链（原始命令）

步骤 1 — 创建 Console 项目：

aio console project create -n my-project --json
# optional: -t "Title" -d "Description" -o <orgId>

步骤 2 — 在项目中创建工作区（Stage 是首个非 Production 工作区的惯用名称；在长期共享的项目中，请选择描述性更强的名称）：

aio console workspace create \
  --projectName my-project \
  --name Stage \
  --json
# optional: --orgId <orgId> --title "Stage workspace"

步骤 3 — 查找并订阅应用所需的 API：

aio console api list --json   # see all service codes available to the org
                              # entries flagged for whether they need a product profile

# Free-tier service:
aio console workspace api add \
  --projectName my-project \
  --workspaceName Stage \
  --service-code AdobeIOManagementAPISDK \
  --json

# Service that requires a product profile:
aio console workspace api add \
  --projectName my-project \
  --workspaceName Stage \
  --service-code AdobeAnalyticsSDK \
  --license-config AdobeAnalyticsSDK=AnalyticsProductionProfile \
  --json

--service-code 支持以逗号分隔的列表，可在一次调用中订阅多项免费服务。需要同时添加多项绑定配置文件的服务时，可以重复使用 --license-config。

从各步骤失败中恢复

失败情况	处理方式
project create 因“已存在”而失败	查看 aio console project list --json，复用现有项目的名称，然后从步骤 2 继续。
workspace create 因“已存在”而失败	使用 aio console workspace list --projectName <p> --json 列出工作区，然后从步骤 3 继续。
workspace api add 返回“需要产品配置文件”	此服务代码需要 --license-config。向用户（或组织管理员）询问配置文件名称，然后使用 --license-config CODE=PROFILE 重试。
任意步骤返回组织选择错误	显式传入 --orgId <id>，或在重试前运行一次 aio console org select <id>。

将本地应用连接到已引导创建的资源

有两种等效方式，可让全新的 aio app init 指向刚创建的项目/工作区：

1. 将它们作为标志传给 init 本身（最简洁）：

   skills/appbuilder-project-init/scripts/init.sh init \
     "@adobe/generator-app-excshell" ./my-project \
     --org <orgId> --project my-project
   

   该封装程序会将 --org / --project / --template-options 原样传递给 aio app init，并保留现有的 -y --no-login --no-install 标志。

2. 初始化后运行 aio app use（适用于任何插件版本）：

   cd ./my-project
   aio app use --no-input   # adopts the currently selected project/workspace, no prompts
   

无论选择哪种方式，最后本地 .aio 和 .env 都会指向刚引导创建的工作区，因此 aio app deploy 会发布到正确的命名空间。

快速路径（适用于明确的请求）

当用户的意图明确对应单个模板时（例如，用户直接指定模板，或描述的应用与下方某个条目完全匹配），请直接跳转到下方的 通过脚本初始化。使用匹配的模板以及用户提供的项目名称（或合理的默认名称）。

快速路径触发示例：

• “使用 @adobe/generator-app-excshell 创建一个 App Builder 应用” → 使用该模板，运行初始化
• “设置一个 Asset Compute worker” → 明确对应 @adobe/generator-app-asset-compute，运行初始化
• “创建一个新的 App Builder 应用”（没有具体要求）→ 默认使用 @adobe/generator-app-excshell，运行初始化
• “初始化一个空白项目” → 使用 init-bare，运行初始化

如果存在任何歧义——可能适用多个模板，或用户的约束不明确——请使用下方的完整模板决策表和工作流。

模板决策表

选择符合用户意图的模板。如果不明确，则默认使用 @adobe/generator-app-excshell。

用户需求	模板
带有 actions 和 React UI 的 SPA	@adobe/generator-app-excshell
Content Hub 扩展（资产详情面板、卡片操作、批量操作）	不使用生成器——从示例应用搭建脚手架，参见 references/templates.md
AEM Content Fragment Console 扩展	@adobe/aem-cf-admin-ui-ext-tpl
AEM React SPA（基于 WKND）	@adobe/generator-app-aem-react
Adobe API Mesh（GraphQL）	@adobe/generator-app-api-mesh
Asset Compute 自定义 worker	@adobe/generator-app-asset-compute
App Builder 上的远程服务	@adobe/generator-app-remote-mcp-server-generic
空白／从头开始的项目（没有预先搭建脚手架的 actions 或 UI）	init.sh init-bare

对于无头／仅后端的请求，尽可能优先使用 init-bare。如果用户仍然需要会生成 UI 文件的模板，请规划初始化后的清理步骤，确保最终项目没有 web-src 前端目录或 web 清单配置。

通过脚本初始化

aio app * 封装命令均通过同一个脚本运行：scripts/init.sh。（Console 引导命令会直接调用——原因请参见上方的 引导 部分。）

注意： 根据平台和仓库布局，此技能脚本的路径可能是 skills/、.augment/skills/ 或 .github/skills/。请相应调整下方命令中的前缀。

使用模板：

skills/appbuilder-project-init/scripts/init.sh init "@adobe/generator-app-excshell" ./my-project

使用模板，并完整配置到特定的 Console 组织／项目（无需在初始化后运行 aio app use）：

skills/appbuilder-project-init/scripts/init.sh init \
  "@adobe/generator-app-excshell" ./my-project \
  --org <orgId> --project my-project

--org、--project、--template-options（经 Base64 编码的 JSON）和 --no-config-validation 会直接传递给 aio app init。请使用最新版本的 @adobe/aio-cli，以确保这些参数都能被识别；对于极少数暂时不应要求部分脚手架通过架构验证的情况，可以使用 --no-config-validation 作为变通方式。

空白项目（不使用模板）：

skills/appbuilder-project-init/scripts/init.sh init-bare ./my-project

仅当用户明确要求从头配置所有内容时，才使用 init-bare。在这种情况下，“空白”意味着生成的项目应保持精简：

• app.config.yaml 存在，且包含空的或精简的 application.runtimeManifest
• package.json 存在，且仅包含项目的基本依赖项
• 不包含预先搭建脚手架的 src/、web-src/ 或 actions/ 目录

原因：如果用户要求空白项目，预先生成的 actions 或 Web 资源就与其意图相矛盾，也会破坏他们所要求的干净起点。

脚本会输出包含 success、path 和 output 字段的 JSON。请先检查 success，再继续。

完整工作流（适用于有歧义或复杂的请求）

步骤 1 — 收集需求

询问用户（或根据对话上下文推断）：

问题	示例
应用类型是什么？	SPA 外壳、无头 API、AEM 扩展、Asset Compute 工作器、API Mesh、远程服务
是否需要 UI？	需要（ExC Shell 中的 React Spectrum）、不需要（仅操作）
扩展点是什么？	dx/excshell/1、aem/cf-console-admin/1、dx/asset-compute/worker/1，或 N/A
是否需要其他操作？	除默认操作外的自定义操作名称和用途
Console 状态如何？	是否已有项目和工作区？还是需要创建它们并先订阅 API？
需要哪些 API？	例如 Adobe I/O Management、Analytics、Target，包括任何需要产品配置文件的 API

如果用户只说“创建一个 App Builder 应用”，没有提供具体信息，则默认使用 @adobe/generator-app-excshell。

如果 Console 状态为“从头开始”或未知，请在继续选择模板前运行 Bootstrap the Developer Console 流程。完整的 Agent 引导操作指南请参阅 references/bootstrap.md。

步骤 2 — 选择模板

参阅上方的模板决策表和 references/templates.md，将用户的需求映射到相应模板。

步骤 3 — 初始化、自定义、验证

遵循下方的 Initialize via Script、Post-init customization 和 Validate 部分。

初始化后的自定义

请参阅 references/templates.md，了解特定模板的初始化后指导。常见任务：

1. 安装依赖项 — 在项目目录中运行 npm install。初始化脚本使用 --no-install 以加快初始化速度，但在构建或测试之前必须安装依赖项。
2. 对于 API Mesh 项目，确认 mesh.json 位于项目根目录 — 使用 @adobe/generator-app-api-mesh 执行 aio app init 后，确认 ./mesh.json 存在，再将脚手架项目视为已就绪。如果该文件仅存在于 node_modules/@adobe/generator-app-api-mesh/templates/mesh.json，请使用 cp node_modules/@adobe/generator-app-api-mesh/templates/mesh.json ./mesh.json 将其复制到正确位置。node_modules/ 下的文件是生成器的模板源文件，并非项目当前使用的 API Mesh 配置。然后使用用户的真实源处理程序自定义根目录下的 mesh.json；对于多后端场景，至少配置两个处理程序。
3. 根据需要清理空项目脚手架 — 执行 init-bare 后，检查生成的项目。如果初始化程序创建了 actions/、src/ 或 web-src/，请在继续之前删除这些目录。空项目不应保留自动生成的操作代码或 Web 资源。
4. 模板初始化后的无头模式清理 — 如果用户需要没有前端的无头项目，请在执行 aio app init 后删除生成的 UI 目录：rm -rf web-src/，或使用模板特定路径，例如 rm -rf src/<extension>/web-src/。然后，从 app.config.yaml 或 ext.config.yaml 中移除匹配的 web-src 配置（如果存在），尤其是 web: web-src 和 operations.view / impl: index.html 条目。这样可以避免仅含后端的项目产生不必要的前端构建产物和过时的清单配置。
5. 添加操作 — 如果用户之后需要自定义操作，请运行 cd ./my-project && skills/appbuilder-project-init/scripts/init.sh add-action "my-action"。
6. 添加 Web 资源 — 仅当用户之后决定空项目需要 UI 时，才运行 skills/appbuilder-project-init/scripts/init.sh add-web-assets。
7. 直接编辑 ext.config.yaml — 自定义操作定义：

• 将 runtime: nodejs:22 用于生产环境。Stage 工作区也接受 runtime: nodejs:24。
• 为操作所需的环境变量添加 inputs:
• 如果操作需要 IMS 令牌，请设置 annotations.require-adobe-auth: true
• 根据 HTTP 访问需求设置 web: 'yes' 或 web: 'raw'

8. 编辑 app.config.yaml — 对于多扩展项目，添加 $include 条目。
9. 应用操作样板代码 — 使用 appbuilder-action-scaffolder 技能的样板模式，编写包含日志记录、输入验证和错误处理的生产就绪操作代码。

验证

直接检查以下项目以验证项目结构：

1. app.config.yaml** 存在**且包含有效的 YAML
2. 所有 $include 路径都能解析为实际文件
3. ext.config.yaml（如果存在）包含至少一个操作的 runtimeManifest.packages
4. 所有声明的 function: 路径均存在对应的操作 JS 文件
5. package.json** 存在**，且包含 name、version 和 Adobe SDK 依赖项（@adobe/aio-sdk 或 @adobe/aio-lib-core-logging）
6. **app.config.yaml 中没有根级 **runtimeManifest（请参阅下文的清单防护措施）

读取相关文件并逐项验证。继续之前请修复所有问题。

构建、测试、部署（可选）

如果用户希望继续进行脚手架搭建以外的工作：

aio app build       # Build
aio app test        # Run tests
aio app deploy      # Deploy to Adobe I/O Runtime
aio app dev         # Run locally for development (use `aio app run` instead if actions use State SDK, Files SDK, or sequences)

清单防护措施

**扩展项目：**操作定义在 ext.config.yaml 的 runtimeManifest 下，并通过 app.config.yaml 中的 $include 引用。

**独立应用：**操作应放在 app.config.yaml 的 application.runtimeManifest 下。

不要在 app.config.yaml 中直接放置根级 runtimeManifest：CLI 会忽略这些操作，因此它们不会被部署。如果发现这种结构，请将其移至 application.runtimeManifest 下或移至 ext.config.yaml 中。

Troubleshooting & Edge Cases

• aio** 未安装 CLI：** 如果 aio --version 返回 command not found 或执行失败，请在初始化前停止。请用户安装 Adobe I/O CLI，完成 aio auth login，并仅在 CLI 可用后重试。
• npm install** 在初始化后失败：** 由于初始化使用 --no-install 运行，脚手架仍可创建，但在依赖项成功安装前，构建和测试都会失败。记录第一个软件包错误，确认 Node/npm 版本兼容，从项目根目录重新运行 npm install，并仅在成功后继续。
• 模板选择不明确： 如果请求可能对应多个模板，请针对 UI 还是无头模式、扩展点或目标 Adobe 产品提出一个澄清问题。如果用户没有偏好，默认使用 @adobe/generator-app-excshell，并明确说明这一假设。
• 项目目录已存在或不为空： 不要静默覆盖。询问用户是使用其他目录、清空现有文件夹，还是初始化到新路径。
• aio console …** 子命令或标志无法识别：** 这几乎总是因为 CLI 套件过时。运行 npm install -g @adobe/aio-cli 并重试——这是刷新所有插件（console、app、runtime、ims-oauth、telemetry）的受支持方式。只有在全新安装后同一命令仍然失败时，才深入排查。
• 添加 Workspace API 失败，提示“product profile required”： 服务代码需要产品配置文件。重新运行 aio console api list --json 进行确认，向用户（或组织管理员）询问配置文件名称，然后使用 --license-config CODE=PROFILE 重试。
• 未选择组织： Console 引导命令会因组织选择错误而失败。先运行 aio console org list，然后运行 aio console org select <orgId>（或向每个命令传入 --orgId），再重试。
• 新建脚手架但经过部分编辑的项目出现验证错误： 最近版本的 aio app * 默认会根据与 OpenWhisk 对齐的架构验证 app.config.yaml。每个读取或写入清单的 aio app * 命令都会运行验证，具体包括：aio app init、aio app add (action|web-assets|extension|event|service)、aio app delete (action|web-assets|extension|event|service)、aio app build、aio app deploy、aio app undeploy、aio app run、aio app dev、aio app use 和 aio app info。这些命令使用相同的绕过标志：--no-config-validation。只在需要解除阻塞的单个命令上使用它（例如，在重构尚未完成时运行 aio app build --no-config-validation），清单完整后立即移除。不要将它写入脚本——本地配置与部署形态之间的静默偏差正是添加验证器要捕获的问题。
• 公司代理后模板列表卡住： 较旧的 CLI 套件在模板注册表 SSL 握手期间不会遵循 HTTP_PROXY / HTTPS_PROXY。运行 npm install -g @adobe/aio-cli 以获取代理修复，确认已在同一 shell 中导出 HTTPS_PROXY，然后重试。
• aio** 命令因 ERR_REQUIRE_ESM 立即退出（退出码 127）：** 全新安装可能会将 @adobe/aio-cli-plugin-certificate 解析为 2.2.0（以 ESM 形式发布），而内置的 CommonJS console 库无法对其使用 require()——每个 aio where / login / console 命令都会以 [ERR_REQUIRE_ESM] 退出，退出码为 127（但 aio -v 仍会显示版本号，容易造成误导）。在全局软件包内部将插件固定到最后一个 CommonJS 2.x 版本：cd "$(npm root -g)/@adobe/aio-cli" && npm install @adobe/[email protected]。每次执行 aio update 后都要重新检查。
• aio console org list** 没有返回内容 / 返回 []：** 登录成功，但组织列表为空——这几乎总是因为环境错误（Adobe/App Builder 内部开发环境使用 stage，但 CLI 默认使用 prod）。切换环境：export AIO_CLI_ENV=stage && aio logout && aio login。如果 stage 中也没有内容，则问题在于授权，而非环境（需要 App Builder 许可证，并且用户需添加到 Admin Console → Users → Developers）。
• aio console project list** → 451 … accept developer terms：** 该组织尚未接受 Adobe Developer Terms of Use——这是每个组织仅需接受一次的条款，CLI 无法替你完成。打开 Developer Console（Stage https://developer-stage.adobe.com/console，Prod https://developer.adobe.com/console），确认组织正确（右上角），接受提示，然后重新运行命令。

与其他技能串联

初始化后，交接给：

• appbuilder-action-scaffolder — 使用 playbook、检查清单、样板模板和清单验证来搭建操作
• appbuilder-ui-scaffolder — 为 ExC Shell SPA 和 AEM 扩展构建 React Spectrum UI

模式速查

任务	参考	命令
引导 Console 项目 + 工作区 + API	references/bootstrap.md	aio console project create → aio console workspace create → aio console workspace api add
发现组织可用的 API	references/bootstrap.md	aio console api list --json
为现有工作区订阅 API	references/bootstrap.md	aio console workspace api add --service-code … [--license-config …]
根据模板初始化 App Builder 项目	references/templates.md	scripts/init.sh init
初始化后将本地应用连接到 Console 工作区	references/bootstrap.md	scripts/init.sh init … --org … --project … 或 aio app use --no-input
调试项目初始化问题	references/debugging.md	—

参考资料

• references/bootstrap.md — 通过最新的 @adobe/aio-cli 中的原始 aio console … 命令，引导 Agentic Developer Console（项目、工作区、API 订阅）
• references/templates.md — 模板目录，包含意图映射和各模板的初始化后指引（包括 Content Hub 扩展）
• references/debugging.md — 故障排除指南，涵盖初始化失败、Node/npm 问题、登录问题和首次运行错误