用 aio CLI 端到端初始化 Adobe App…

当需要创建 App Builder 应用、脚手架项目、运行 aio app init、搭建 Experience Cloud 扩展、添加 actions/web 资源，或从零创建 Developer Console 项目/工作区并订阅 API 时使用。

适用场景

解决思路

1. 首次机器准备：确认 Node 20（`node -v` 应为 v20.x）；有 nvm 则 `nvm install 20 && nvm use 20 && nvm alias default 20`；无 nvm 则先 `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash`，重开 shell 后再装 Node 20（也可 `brew install node@20` 或官方安装器）。
2. 安装并登录 aio CLI：在 Node 20 下执行 `npm install -g @adobe/aio-cli`，然后 `aio login`（`aio login -f` 强制重新登录），用 `aio where` 确认 IMS 组织/上下文，用 `aio console org list` 列出组织 ID，必要时 `aio console org select <id>`。
3. 切换 Stage 环境：`export AIO_CLI_ENV=stage && aio logout && aio login`；取消该变量或开新 shell 即回到 prod。
4. 无浏览器登录（CI）：在 Developer Console 工作区点 Download all 得到 `console.json`，用 `aio app init <app> --import path/to/console.json`；或在工作区添加 OAuth Server-to-Server 凭据供 CI 无人工认证（不要脚本化 SSO/MFA）。
5. Bootstrap 前置检查：`npm install -g @adobe/aio-cli` 并 `aio --version` 确保 CLI 最新；用 `aio console org list --json` 确认已选组织，否则 `aio console org select <orgId>` 或在每条命令上传 `--orgId`。
6. 按用户状态决定动作：从零则跑完整 bootstrap 链（project → workspace → APIs）再 `aio app init`；项目已存在仅缺工作区则跳过 project-create，直接 `aio console workspace create`；项目+工作区已存在仅需加 API 则 `aio console api list` 后 `aio console workspace api add`；全部就绪则直接初始化。
7. 创建前先用 `aio console project list --json` 和 `aio console workspace api list --projectName <p> --workspaceName <w> --json` 检查已存在资源（这些命令对已存在会报错，无幂等性）。
8. 创建 Console 项目：`aio console project create -n my-project --json`（可选 `-t "Title" -d "Description" -o <orgId>`）。
9. 创建workspace：`aio console workspace create --projectName my-project --name Stage --json`（可选 `--orgId <orgId> --title "Stage workspace"`）。
10. 发现并订阅 API：`aio console api list --json` 查看服务码及是否需要 product profile；免费服务用 `aio console workspace api add --projectName my-project --workspaceName Stage --service-code AdobeIOManagementAPISDK --json`；需要 product profile 的服务加 `--license-config AdobeAnalyticsSDK=AnalyticsProductionProfile`；`--service-code` 支持逗号分隔多服务，`--license-config` 可重复。
11. 处理 bootstrap 单步失败：project create 报 already exists 则从 `aio console project list --json` 复用现有项目名继续第 2 步；workspace create 报 already exists 则用 `aio console workspace list --projectName <p> --json` 继续第 3 步；api add 报 product profile required 则向用户/管理员索取 profile 名并用 `--license-config CODE=PROFILE` 重试；组织选择错误则显式传 `--orgId <id>` 或先 `aio console org select <id>`。
12. 将本地应用接入已 bootstrap 的状态：方式一在 init 时直接传 `--org <orgId> --project my-project`（连同 `-y --no-login --no-install` 一起透传给 `aio app init`）；方式二 init 后 `cd ./my-project && aio app use --no-input` 采用当前选中的项目/工作区。
13. Fast Path：当意图明确对应单一模板（如直接点名模板、Asset Compute worker、无特定要求默认 excshell、bare 项目）时，直接跳到脚本初始化，用匹配模板和用户提供的项目名（或合理默认）。
14. 按模板决策表选择模板：SPA+React UI 用 `@adobe/generator-app-excshell`；AEM Content Fragment Console 扩展用 `@adobe/aem-cf-admin-ui-ext-tpl`；AEM React SPA 用 `@adobe/generator-app-aem-react`；API Mesh 用 `@adobe/generator-app-api-mesh`；Asset Compute worker 用 `@adobe/generator-app-asset-compute`；远程服务器用 `@adobe/generator-app-remote-mcp-server-generic`；bare 项目用 `init.sh init-bare`；不明确时默认 excshell。
15. 通过脚本初始化：带模板 `skills/appbuilder-project-init/scripts/init.sh init "@adobe/generator-app-excshell" ./my-project`；带 org/project `... init "@adobe/generator-app-excshell" ./my-project --org <orgId> --project my-project`；bare 项目 `... init-bare ./my-project`；脚本输出 JSON 含 `success`/`path`/`output`，先检查 `success`。
16. bare 项目保持最小：`app.config.yaml` 仅有空或最小 `application.runtimeManifest`，`package.json` 仅基础依赖，无预生成的 `src/`、`web-src/`、`actions/` 目录。
17. 复杂/模糊请求先收集意图：应用类型、是否需要 UI、扩展点（dx/excshell/1、aem/cf-console-admin/1、dx/asset-compute/worker/1 或 N/A）、额外 actions、Console 状态、所需 API（含需 product profile 的）；Console 状态为从零或未知时先跑 Bootstrap 流程。
18. Post-init 定制：在项目目录运行 `npm install`（init 用 `--no-install` 以求快，但构建/测试前必须装依赖）。
19. API Mesh 项目：确认 `./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`，再用真实 source handlers 定制根 `mesh.json`（多后端场景至少配置两个 handler）。
20. bare 项目清理：init-bare 后检查生成项目，若出现 `actions/`、`src/`、`web-src/` 则删除，bare 项目不应保留自动生成的 action 代码或 web 资源。
21. headless 清理：若用户要无前端项目，init 后 `rm -rf web-src/` 或模板特定路径如 `rm -rf src/<extension>/web-src/`，并从 `app.config.yaml` 或 `ext.config.yaml` 移除 `web: web-src` 及 `operations.view`/`impl: index.html` 等前端配置。
22. 后续添加 action：`cd ./my-project && skills/appbuilder-project-init/scripts/init.sh add-action "my-action"`；后续添加 web 资源：`skills/appbuilder-project-init/scripts/init.sh add-web-assets`。
23. 直接编辑 `ext.config.yaml`：生产设 `runtime: nodejs:22`（Stage 工作区也接受 `runtime: nodejs:24`）；添加 `inputs:` 环境变量；需要 IMS token 时设 `annotations.require-adobe-auth: true`；按 HTTP 访问需求设 `web: 'yes'` 或 `web: 'raw'`。
24. 多扩展项目在 `app.config.yaml` 添加 `$include` 条目；生产级 action 代码用 `appbuilder-action-scaffolder` 技能的 boilerplate 模式（日志、输入校验、错误处理）。
25. 验证项目结构：`app.config.yaml` 存在且 YAML 合法；所有 `$include` 路径可解析；`ext.config.yaml`（若有）的 `runtimeManifest.packages` 至少含一个 action；所有声明的 `function:` 路径下 action JS 文件存在；`package.json` 含 `name`、`version` 及 Adobe SDK 依赖（`@adobe/aio-sdk` 或 `@adobe/aio-lib-core-logging`）；`app.config.yaml` 无根级 `runtimeManifest`。
26. 构建/测试/部署：`aio app build`、`aio app test`、`aio app deploy`、`aio app dev`（若 action 用 State SDK、Files SDK 或 sequences 则改用 `aio app run`）。
27. Manifest 护栏：扩展项目 action 定义在 `ext.config.yaml` 的 `runtimeManifest` 并经 `app.config.yaml` 的 `$include` 引用；独立应用 action 放在 `app.config.yaml` 的 `application.runtimeManifest`；不要把根级 `runtimeManifest` 直接放在 `app.config.yaml`（CLI 会忽略，不会部署）。
28. 排障：`aio` 未安装则停止初始化，请用户安装 CLI 并 `aio auth login` 后重试；`npm install` 失败则捕获首个包错误、确认 Node/npm 版本、在项目根重跑直到成功；模板选择模糊则问一个澄清问题（UI vs headless、扩展点、目标产品），无偏好则默认 excshell 并明确说明假设；项目目录已存在或非空则不要静默覆盖，询问换目录/清空/新路径。
29. 排障：`aio console …` 子命令或 flag 不识别通常是 CLI 陈旧，`npm install -g @adobe/aio-cli` 后重试；workspace api add 报 product profile required 则 `aio console api list --json` 确认后索取 profile 名并用 `--license-config CODE=PROFILE` 重试；无组织选中则 `aio console org list` 后 `aio console org select <orgId>` 或每条命令传 `--orgId`。
30. 排障：新脚手架但部分编辑的项目校验报错时，用 `--no-config-validation` 在单条命令上临时解锁（如 `aio app build --no-config-validation`），manifest 完整后立即去掉，不要写进脚本；模板列表在公司代理后挂起则升级 CLI 并确认同 shell 导出 `HTTPS_PROXY` 后重试。
31. 排障：`aio` 命令瞬间以 `ERR_REQUIRE_ESM`（exit 127）退出时，在全局包内固定插件：`cd "$(npm root -g)/@adobe/aio-cli" && npm install @adobe/aio-cli-plugin-certificate@2.1.0`，每次 `aio update` 后复查。
32. 排障：`aio console org list` 返回空 `[]` 通常是环境错误（内部开发在 stage，CLI 默认 prod），执行 `export AIO_CLI_ENV=stage && aio logout && aio login`；stage 也为空则是授权问题（需 App Builder 许可并在 Admin Console → Users → Developers 添加用户）。
33. 排障：`aio console project list` 报 `451 … accept developer terms` 时，打开 Developer Console（Stage `https://developer-stage.adobe.com/console`，Prod `https://developer.adobe.com/console`），确认右上角组织正确，接受提示后重跑命令。
34. 初始化后交接：`appbuilder-action-scaffolder`（action 脚手架、playbook、checklist、boilerplate、manifest 校验）与 `appbuilder-ui-scaffolder`（为 ExC Shell SPA 和 AEM 扩展构建 React Spectrum UI）。

适用边界 · 注意事项

• 未安装 aio CLI 或未完成登录时不要开始初始化——先安装 CLI 并 `aio auth login`。
• 用户明确要 bare 项目时不要保留预生成的 actions 或 web 资源，否则违背其意图。
• 不要把 `--no-config-validation` 固化进脚本，否则会掩盖本地配置与部署形态的漂移。