appbuilder-project-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

App Builder Project Initialization

App Builder项目初始化

Maps user intent to the right Adobe App Builder template and runs non-interactive

aio app init

. Default:

@adobe/generator-app-excshell

(SPA + actions). For headless/bare projects, use

init-bare

将用户意图映射至合适的Adobe App Builder模板，并运行非交互式

aio app init

命令。默认模板为

@adobe/generator-app-excshell

（SPA + actions）。对于无头/极简项目，使用

init-bare

。

Fast Path (for clear requests)

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

When the user's intent maps unambiguously to a single template — for example, they name a template directly or describe an app that clearly matches exactly one entry below — skip straight to Initialize via Script below. Use the matched template and any project name the user provided (or a sensible default).

Examples of fast-path triggers:

"Create an App Builder app using
```
@adobe/generator-app-excshell
```
" → use that template, run init
"Set up an Asset Compute worker" → maps unambiguously to
```
@adobe/generator-app-asset-compute
```
, run init
"Create a new App Builder app" (no specifics) → defaults to
```
@adobe/generator-app-excshell
```
, run init
"Initialize a bare project" → use
```
init-bare
```
, run init

If there is any ambiguity — multiple templates could fit, or the user's constraints are unclear — use the full template decision table and workflow below.

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

快速路径触发示例：

“使用
```
@adobe/generator-app-excshell
```
创建一个App Builder应用” → 使用该模板，运行初始化
“设置Asset Compute工作器” → 明确映射至
```
@adobe/generator-app-asset-compute
```
，运行初始化
“创建一个新的App Builder应用”（无具体要求） → 默认使用
```
@adobe/generator-app-excshell
```
，运行初始化
“初始化一个极简项目” → 使用
```
init-bare
```
，运行初始化

若存在任何歧义——多个模板均适用，或用户的约束条件不明确——请使用下方完整的模板决策表与工作流程。

Template Decision Table

模板决策表

Pick the template that matches the user's intent. When unclear, default to

@adobe/generator-app-excshell

User wants	Template
SPA with actions + React UI	@adobe/generator-app-excshell
AEM Content Fragment Console extension	@adobe/aem-cf-admin-ui-ext-tpl
AEM React SPA (WKND-based)	@adobe/generator-app-aem-react
Adobe API Mesh (GraphQL)	@adobe/generator-app-api-mesh
Asset Compute custom worker	@adobe/generator-app-asset-compute
Remote server on App Builder	@adobe/generator-app-remote-mcp-server-generic
Bare / from-scratch project (no pre-scaffolded actions or UI)	init.sh init-bare

For a headless/backend-only request, prefer

init-bare

when possible. If the user still needs a template that generates UI files, plan a post-init cleanup so the final project has no

web-src

frontend directory or web manifest wiring.

选择与用户意图匹配的模板。若不明确，默认使用

@adobe/generator-app-excshell

。

用户需求	模板
带actions + React UI的SPA	@adobe/generator-app-excshell
AEM内容片段控制台扩展	@adobe/aem-cf-admin-ui-ext-tpl
基于WKND的AEM React SPA	@adobe/generator-app-aem-react
Adobe API Mesh（GraphQL）	@adobe/generator-app-api-mesh
Asset Compute自定义工作器	@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清单配置。

Initialize via Script

通过脚本初始化

All commands go through a single script:

scripts/init.sh

Note: The path to this skill's scripts may be
skills/
,
.augment/skills/
, or
.github/skills/
depending on your platform and repository layout. Adjust the prefix in the commands below accordingly.

With a template:

bash

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

Bare project (no template):

bash

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

Use

init-bare

only when the user explicitly wants to configure everything from scratch. In that case, "bare" means the generated project should stay minimal:

app.config.yaml

exists with an empty or minimal

application.runtimeManifest

```
package.json
```
exists with only the basic project dependencies
No pre-scaffolded
```
src/
```
,
```
web-src/
```
, or
```
actions/
```
directories

Why this matters: if the user asked for a bare project, pre-generated actions or web assets contradict that intent and remove the clean starting point they requested.

The script outputs JSON with

success

path

, and

output

fields. Check

success

before proceeding.

所有命令均通过单个脚本执行：

scripts/init.sh

注意： 此技能脚本的路径可能为
skills/
、
.augment/skills/
或
.github/skills/
，具体取决于您的平台与仓库结构。请相应调整下方命令中的前缀。

使用模板：

bash

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

极简项目（无模板）：

bash

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

状态。

Full Workflow (for ambiguous or complex requests)

完整工作流程（适用于模糊或复杂请求）

Step 1 — Gather intent

步骤1 — 收集意图

Ask the user (or infer from conversation context):

Question	Examples
What type of app?	SPA shell, headless API, AEM extension, Asset Compute worker, API Mesh, remote server
Needs a UI?	Yes (React Spectrum in ExC Shell), No (actions only)
Extension point?	dx/excshell/1, aem/cf-console-admin/1, dx/asset-compute/worker/1, or N/A
Additional actions?	Names and purposes of custom actions beyond the default

If the user simply says "create an App Builder app" with no specifics, default to

@adobe/generator-app-excshell

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

问题	示例
应用类型？	SPA外壳、无头API、AEM扩展、Asset Compute工作器、API Mesh、远程服务器
是否需要UI？	是（ExC Shell中的React Spectrum）、否（仅actions）
扩展点？	dx/excshell/1、aem/cf-console-admin/1、dx/asset-compute/worker/1，或无
额外actions？	除默认之外的自定义actions的名称与用途

若用户仅说“创建一个App Builder应用”且无具体要求，默认使用

@adobe/generator-app-excshell

。

Step 2 — Select template

步骤2 — 选择模板

Consult the Template Decision Table above and references/templates.md to map the user's intent to a template.

参考上方的模板决策表与references/templates.md，将用户意图映射至对应模板。

Step 3 — Initialize, customize, validate

步骤3 — 初始化、定制、验证

Follow the Initialize via Script, Post-init customization, and Validate sections below.

遵循下方的通过脚本初始化、初始化后定制与验证部分。

Post-init Customization

初始化后定制

Consult references/templates.md for template-specific post-init guidance. Common tasks:

Install dependencies — Run
```
npm install
```
in the project directory. The init script uses
```
--no-install
```
to keep initialization fast, but dependencies are required before building or testing.
For API Mesh projects, verify mesh.json
is at the project root — After
```
aio app init
```
with
```
@adobe/generator-app-api-mesh
```
, confirm
```
./mesh.json
```
exists before treating the scaffold as ready. If the file only exists at
```
node_modules/@adobe/generator-app-api-mesh/templates/mesh.json
```
, copy it into place with
```
cp node_modules/@adobe/generator-app-api-mesh/templates/mesh.json ./mesh.json
```
. The file under
```
node_modules/
```
is the generator's template source, not the project's active API Mesh configuration. Then customize the root
```
mesh.json
```
with the user's real source handlers; for multi-backend scenarios, configure at least two handlers.
Clean up bare-project scaffolding if needed — After
```
init-bare
```
, inspect the generated project. If the initializer created
```
actions/
```
,
```
src/
```
, or
```
web-src/
```
, remove those directories before continuing. A bare project should not keep auto-generated action code or web assets.
Headless cleanup after template init — If the user wants a headless project with no frontend, delete any generated UI directory after
```
aio app init
```
:
```
rm -rf web-src/
```
or the template-specific path such as
```
rm -rf src/<extension>/web-src/
```
. Then remove matching
```
web-src
```
config from
```
app.config.yaml
```
or
```
ext.config.yaml
```
if present, especially
```
web: web-src
```
and
```
operations.view
```
/
```
impl: index.html
```
entries. This avoids unnecessary frontend build artifacts and stale manifest wiring in a backend-only project.

Add actions — If the user later wants custom actions, run

cd ./my-project && skills/appbuilder-project-init/scripts/init.sh add-action "my-action"

Add web assets — Only if the user later decides the bare project needs a UI, run
```
skills/appbuilder-project-init/scripts/init.sh add-web-assets
```
.
Edit ext.config.yaml directly — Customize action definitions:

Set
```
runtime: nodejs:22
```
(latest supported)
Add
```
inputs:
```
for environment variables the action needs
Set
```
annotations.require-adobe-auth: true
```
if the action needs IMS tokens
Set
```
web: 'yes'
```
or
```
web: 'raw'
```
depending on HTTP access needs

Edit app.config.yaml — For multi-extension projects, add
```
$include
```
entries.
Apply action boilerplate — Use the
```
appbuilder-action-scaffolder
```
skill's boilerplate pattern for production-ready action code with logging, input validation, and error handling.

参考references/templates.md获取模板专属的初始化后指导。常见任务：

安装依赖 — 在项目目录中运行
```
npm install
```
。初始化脚本使用
```
--no-install
```
以加快初始化速度，但构建或测试前需安装依赖。
对于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
```
；对于多后端场景，请配置至少两个处理器。
必要时清理极简项目脚手架 — 执行
```
init-bare
```
后，检查生成的项目。若初始化器创建了
```
actions/
```
、
```
src/
```
或
```
web-src/
```
，请在继续操作前删除这些目录。极简项目不应保留自动生成的action代码或Web资源。
模板初始化后的无头清理 — 若用户需要无前端的无头项目，执行
```
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
```
条目。这可避免在仅后端项目中产生不必要的前端构建产物与过时的清单配置。

添加actions — 若用户后续需要自定义actions，运行

cd ./my-project && skills/appbuilder-project-init/scripts/init.sh add-action "my-action"

。

添加Web资源 — 仅当用户后续决定极简项目需要UI时，运行
```
skills/appbuilder-project-init/scripts/init.sh add-web-assets
```
。
直接编辑ext.config.yaml — 定制action定义：

设置
```
runtime: nodejs:22
```
（最新支持版本）
添加
```
inputs:
```
以配置action所需的环境变量
若action需要IMS令牌，设置
```
annotations.require-adobe-auth: true
```
根据HTTP访问需求设置
```
web: 'yes'
```
或
```
web: 'raw'
```

编辑app.config.yaml — 对于多扩展项目，添加
```
$include
```
条目。
应用action模板 — 使用
```
appbuilder-action-scaffolder
```
技能的模板模式，生成包含日志、输入验证与错误处理的生产级action代码。

Validate

验证

Verify the project structure by checking these items directly:

```
app.config.yaml
```
** exists** and contains valid YAML
All $include
paths resolve to real files
```
ext.config.yaml
```
(if present) has
```
runtimeManifest.packages
```
with at least one action
Action JS files exist at all declared
```
function:
```
paths

package.json

** exists** with

name

version

, and an Adobe SDK dependency (

@adobe/aio-sdk

@adobe/aio-lib-core-logging

)

**No root-level **
```
runtimeManifest
```
in
```
app.config.yaml
```
(see Manifest guardrail below)

Read the relevant files and verify each check. Fix any issues before proceeding.

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

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
（见下方清单防护规则）

读取相关文件并验证每一项。继续操作前修复所有问题。

Build, Test, Deploy (optional)

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

If the user wants to go beyond scaffolding:

bash

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)

若用户希望超出脚手架搭建范围：

bash

aio app build       # 构建
aio app test        # 运行测试
aio app deploy      # 部署至Adobe I/O Runtime
aio app dev         # 本地运行进行开发（若actions使用State SDK、Files SDK或序列，请改用`aio app run`）

Manifest guardrail

清单防护规则

Extension projects: Actions are defined under

runtimeManifest

ext.config.yaml

, referenced via

$include

from

app.config.yaml

Standalone apps: Actions go under

application.runtimeManifest

app.config.yaml

Do not place a root-level

runtimeManifest

directly in

app.config.yaml

: the CLI ignores those actions, so they will not deploy. If you see this shape, move it under

application.runtimeManifest

or into

ext.config.yaml

扩展项目： Actions定义于

ext.config.yaml

的

runtimeManifest

下，通过

app.config.yaml

中的

$include

引用。

独立应用： Actions置于

app.config.yaml

的

application.runtimeManifest

下。

请勿在

app.config.yaml

中直接放置根级

runtimeManifest

：CLI会忽略这些actions，导致它们无法部署。若发现此结构，请将其移至

application.runtimeManifest

下或

ext.config.yaml

中。

Troubleshooting & Edge Cases

故障排查与边缘情况

```
aio
```
** CLI not installed:** If
```
aio --version
```
returns
```
command not found
```
or fails, stop before initialization. Ask the user to install Adobe I/O CLI, complete
```
aio auth login
```
, and retry only after the CLI is available.
```
npm install
```
** fails after init:** The scaffold can still be created because init runs with
```
--no-install
```
, but builds/tests will fail until dependencies install cleanly. Capture the first package error, confirm the Node/npm version is compatible, rerun
```
npm install
```
from the project root, and only continue once it succeeds.
Template choice is ambiguous: If the request could map to multiple templates, ask one clarifying question about UI vs headless, extension point, or target Adobe product. If the user has no preference, default to
```
@adobe/generator-app-excshell
```
and state that assumption explicitly.
Project directory already exists or is not empty: Do not overwrite it silently. Ask whether to use a different directory, clear the existing folder, or initialize into a new path.

aio
CLI未安装：若
```
aio --version
```
返回
```
command not found
```
或执行失败，请在初始化前停止操作。请用户安装Adobe I/O CLI，完成
```
aio auth login
```
，仅当CLI可用后重试。
初始化后
npm install
失败：由于初始化使用
```
--no-install
```
，脚手架仍可创建，但构建/测试会失败，直至依赖安装完成。捕获首个包错误，确认Node/npm版本兼容，从项目根目录重新运行
```
npm install
```
，仅当安装成功后继续。
模板选择存在歧义： 若请求可映射至多个模板，请询问一个澄清问题，例如关于UI vs 无头、扩展点或目标Adobe产品。若用户无偏好，默认使用
```
@adobe/generator-app-excshell
```
并明确说明此假设。
项目目录已存在或非空： 请勿静默覆盖。询问用户是否使用其他目录、清空现有文件夹或初始化至新路径。

Chaining with other skills

与其他技能联动

After initialization, hand off to:

```
appbuilder-action-scaffolder
```
— For scaffolding actions with playbook, checklist, boilerplate templates, and manifest validation
```
appbuilder-ui-scaffolder
```
— Build React Spectrum UI for ExC Shell SPAs and AEM extensions

初始化完成后，可转交至：

```
appbuilder-action-scaffolder
```
— 用于搭建包含操作手册、检查清单、模板与清单验证的actions
```
appbuilder-ui-scaffolder
```
— 为ExC Shell SPA与AEM扩展构建React Spectrum UI

Pattern Quick-Reference

模式速查

Task	Reference	Script
Debug project init issues	references/debugging.md	—

任务	参考	脚本
调试项目初始化问题	references/debugging.md	—

References

参考资料

references/templates.md — Template catalog with intent mapping and per-template post-init guidance
references/debugging.md — Troubleshooting guide for init failures, Node/npm issues, login problems, and first-run errors

references/templates.md — 模板目录，包含意图映射与各模板的初始化后指导
references/debugging.md — 初始化失败、Node/npm问题、登录问题与首次运行错误的故障排查指南