appbuilder-action-scaffolder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

App Builder Action Scaffolder

App Builder 动作脚手架生成工具

Full lifecycle skill for Adobe Runtime actions — scaffold, implement, deploy, and debug. Place action code at

src/<extension-dir>/actions/<action-name>/index.js

and register in

src/<extension-dir>/ext.config.yaml

Adobe Runtime动作全生命周期技能——脚手架生成、实施、部署和调试。将动作代码放置在

src/<extension-dir>/actions/<action-name>/index.js

，并在

src/<extension-dir>/ext.config.yaml

中注册。

Pattern Quick-Reference

模式速查

Pick the template that matches the user's intent. Default to

assets/action-boilerplate.js

for generic actions.

User wants	Template
Simple action / generic starting point	assets/action-boilerplate.js
Minimal prototype (bare-bones)	assets/action-scaffold-template.js
Database CRUD (durable records, indexes)	assets/database-action-template.js
Webhook receiver (I/O Events)	assets/event-webhook-template.js
Custom event provider	assets/event-provider-template.js
Journaling consumer (replayable events)	assets/journaling-consumer-template.js
Large payload response (>1 MB)	assets/large-payload-template.js
Action sequence pipeline	assets/action-sequence-template.js
Asset Compute worker (AEM renditions)	assets/asset-compute-worker-template.js
Debug Runtime action issues	references/debugging.md

选择与用户需求匹配的模板。通用动作默认使用

assets/action-boilerplate.js

。

用户需求	模板
简单动作/通用起点	assets/action-boilerplate.js
极简原型（基础结构）	assets/action-scaffold-template.js
数据库CRUD（持久化记录、索引）	assets/database-action-template.js
Webhook接收器（I/O Events）	assets/event-webhook-template.js
自定义事件提供者	assets/event-provider-template.js
日志记录消费者（可重放事件）	assets/journaling-consumer-template.js
大负载响应（>1 MB）	assets/large-payload-template.js
动作序列流水线	assets/action-sequence-template.js
Asset Compute工作器（AEM renditions）	assets/asset-compute-worker-template.js
调试Runtime动作问题	references/debugging.md

Fast Path (for clear requests)

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

When the user's request maps unambiguously to a single pattern above — they name a specific pattern, reference a template, or describe a use case that clearly matches one entry — skip straight to scaffolding. Use the matched template and proceed directly.

Examples of fast-path triggers:

"Add a webhook receiver action" →
```
assets/event-webhook-template.js
```
, scaffold directly
"Create an Asset Compute worker" →
```
assets/asset-compute-worker-template.js
```
, scaffold directly
"Add a database CRUD action" →
```
assets/database-action-template.js
```
, scaffold directly
"Add an action called process-order" (simple, no ambiguity) →
```
assets/action-boilerplate.js
```
, scaffold directly

If there is any ambiguity — multiple patterns could fit, constraints are unclear, or the user hasn't specified enough to pick a single approach — fall through to the full workflow below.

当用户的请求明确匹配上述单一模式时——他们指定了特定模式、引用了模板，或描述的用例清晰匹配某一项——直接跳至脚手架生成步骤。使用匹配的模板并直接执行。

快速路径触发示例：

"添加一个Webhook接收器动作" →
```
assets/event-webhook-template.js
```
，直接生成脚手架
"创建一个Asset Compute工作器" →
```
assets/asset-compute-worker-template.js
```
，直接生成脚手架
"添加一个数据库CRUD动作" →
```
assets/database-action-template.js
```
，直接生成脚手架
"添加一个名为process-order的动作"（简单无歧义） →
```
assets/action-boilerplate.js
```
，直接生成脚手架

若存在任何歧义——多个模式均适用、约束条件不明确，或用户未提供足够信息以选择单一方案——则进入下方完整工作流程。

Quick Reference

速查指南

Action entry point: Place action code at
```
src/<extension-dir>/actions/<action-name>/index.js
```
. This keeps paths aligned with the generated extension layout.
Manifest location: Register actions in
```
src/<extension-dir>/ext.config.yaml
```
. Do not put a root-level
```
runtimeManifest
```
in
```
app.config.yaml
```
; the CLI silently ignores it.
Extension directory name: The extension directory name varies by project template:
- ```
src/dx-excshell-1/
```
  — Experience Cloud Shell SPA (default)
- ```
src/aem-cf-console-admin-1/
```
  — AEM Content Fragment Console extension
- ```
src/dx-asset-compute-worker-1/
```
  — Asset Compute worker Use the actual directory name from your project's
```
app.config.yaml
```
```
$include
```
  entries.
Web action response shape: Return
```
{ statusCode, body }
```
for standard web actions; add
```
headers
```
only when needed.
Key CLI loop:
```
aio app dev
```
for local iteration (use
```
aio app run
```
if actions use State SDK, Files SDK, or sequences),
```
aio rt action invoke
```
for direct testing,
```
aio app deploy
```
for publishing.
State vs database: State for ephemeral job tracking; database for durable records, indexed queries, or document-style CRUD.
Events delivery choice: Webhook for push delivery, custom event provider to publish domain events, journaling consumer for replayability or back-pressure.
Large payload and sequence patterns: Large payload redirect when >1 MB response limit; action sequence for linear multi-action flows.
Asset Compute worker fit: Use for AEM rendition processing; different SDK and extension layout than standard Runtime actions.

动作入口点：将动作代码放置在
```
src/<extension-dir>/actions/<action-name>/index.js
```
。此路径与生成的扩展布局保持一致。
清单位置：在
```
src/<extension-dir>/ext.config.yaml
```
中注册动作。请勿在
```
app.config.yaml
```
中添加根层级的
```
runtimeManifest
```
；CLI会静默忽略该配置。
扩展目录名称：扩展目录名称因项目模板而异：
- ```
src/dx-excshell-1/
```
  —— Experience Cloud Shell SPA（默认）
- ```
src/aem-cf-console-admin-1/
```
  —— AEM内容片段控制台扩展
- ```
src/dx-asset-compute-worker-1/
```
  —— Asset Compute工作器请使用项目
```
app.config.yaml
```
  中
```
$include
```
  条目里的实际目录名称。
Web动作响应格式：标准Web动作返回
```
{ statusCode, body }
```
；仅在需要时添加
```
headers
```
。
核心CLI循环：
```
aio app dev
```
用于本地迭代（若动作使用State SDK、Files SDK或序列，则使用
```
aio app run
```
），
```
aio rt action invoke
```
用于直接测试，
```
aio app deploy
```
用于发布。
State与数据库对比：State用于临时作业跟踪；数据库用于持久化记录、索引查询或文档式CRUD。
事件交付选择：Webhook用于推送交付，自定义事件提供者用于发布领域事件，日志记录消费者用于可重放性或背压处理。
大负载与序列模式：响应超过1 MB限制时使用大负载重定向；动作序列用于线性多动作流程。
Asset Compute工作器适用场景：用于AEM renditions处理；与标准Runtime动作使用不同的SDK和扩展布局。

Full Workflow (for ambiguous or complex requests)

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

Confirm target outcome, constraints, and acceptance criteria.
Collect current implementation context from code, environment, and Adobe configuration.
Apply the detailed procedure in
```
references/playbook.md
```
for this capability.
Produce implementation artifacts and validation evidence.
Run through
```
references/checklist.md
```
before final handoff.
Summarize decisions, risks, and immediate next actions.

确认目标结果、约束条件和验收标准。
从代码、环境和Adobe配置中收集当前实施上下文。
应用
```
references/playbook.md
```
中针对此能力的详细流程。
生成实施工件和验证证据。
在最终交付前运行
```
references/checklist.md
```
中的检查项。
总结决策、风险和立即执行的下一步动作。

Example User Prompts

用户请求示例

"Add a new action to my App Builder project that calls the AEM Assets API."
"My runtime action is timing out after 60 seconds. How do I increase the limit without breaking the app?"
"Set up a cron action that runs every 5 minutes to sync data from an external API."
"Create a web action that accepts file uploads and stores them using the Files SDK."
"Store customer preferences in the App Builder Database."
"Set up a webhook to receive I/O Events for asset changes."
"My action response is too large — how do I handle payloads over 1MB?"

"向我的App Builder项目添加一个调用AEM Assets API的新动作。"
"我的Runtime动作在60秒后超时。如何在不破坏应用的情况下延长限制？"
"设置一个每5分钟运行一次的cron动作，从外部API同步数据。"
"创建一个接受文件上传并使用Files SDK存储文件的Web动作。"
"将客户偏好存储在App Builder数据库中。"
"设置一个Webhook以接收资产变更的I/O Events。"
"我的动作响应过大——如何处理超过1MB的负载？"

Inputs To Request

需要请求的输入信息

Current repository path and module boundaries
Target Adobe organization, project, and workspace
Non-functional constraints: latency, cost, compliance, and support model
Definition of done with measurable acceptance criteria

当前仓库路径和模块边界
目标Adobe组织、项目和工作区
非功能性约束：延迟、成本、合规性和支持模式
包含可衡量验收标准的完成定义

Deliverables

交付物

Implementation updates for the requested capability
Validation evidence: tests, checks, or reproducible verification steps
Handoff summary with explicit tradeoffs and follow-up actions

针对请求功能的实施更新
验证证据：测试、检查或可复现的验证步骤
包含明确权衡和后续动作的交付总结

Quality Bar

质量标准

Keep decisions explicit and traceable to project constraints
Prefer deterministic automation for repeatable steps
Fail safely with actionable diagnostics
Document tradeoffs and next-step risks in handoff notes

保持决策明确且可追溯至项目约束
优先使用确定性自动化处理可重复步骤
安全失败并提供可操作的诊断信息
在交付说明中记录权衡和下一步风险

References

参考资料

Use
```
references/playbook.md
```
for detailed execution guidance.
Use
```
references/checklist.md
```
for pre-handoff validation.
Use
```
references/prompt-pack.md
```
for ready-to-use execution prompts.
Use
```
references/runtime-reference.md
```
for action structure, params, response formats, SDK usage, and CLI operations.
Use
```
references/aem-apis.md
```
for AEM Content Fragment API surfaces — decision table, Delivery OpenAPI, Management OpenAPI, GraphQL persisted queries, and the deprecated Assets HTTP API — with auth patterns and action code for each.
Use
```
references/action-patterns.md
```
for common action patterns, including CRUD API, cron, multi-step processing, database CRUD, webhook intake, custom event providers, journaling consumers, large payload redirects, action sequence composition, and Asset Compute workers.

Use

assets/database-action-template.js

assets/event-webhook-template.js

assets/event-provider-template.js

assets/journaling-consumer-template.js

assets/large-payload-template.js

assets/action-sequence-template.js

, and

assets/asset-compute-worker-template.js

when the user request maps directly to one of the newer boilerplate patterns.

Use

../_shared/categories/architecture-runtime.md

for Adobe service-specific guidance.

使用
```
references/playbook.md
```
获取详细执行指南。
使用
```
references/checklist.md
```
进行交付前验证。
使用
```
references/prompt-pack.md
```
获取现成的执行提示。
使用
```
references/runtime-reference.md
```
获取动作结构、参数、响应格式、SDK使用和CLI操作相关信息。
使用
```
references/aem-apis.md
```
获取AEM内容片段API相关信息——决策表、Delivery OpenAPI、Management OpenAPI、GraphQL持久化查询以及已弃用的Assets HTTP API——包含每个API的认证模式和动作代码。
使用
```
references/action-patterns.md
```
获取常见动作模式，包括CRUD API、cron、多步骤处理、数据库CRUD、Webhook接收、自定义事件提供者、日志记录消费者、大负载重定向、动作序列组合以及Asset Compute工作器。

当用户请求直接匹配某一新样板模式时，使用

assets/database-action-template.js

、

assets/event-webhook-template.js

、

assets/event-provider-template.js

、

assets/journaling-consumer-template.js

、

assets/large-payload-template.js

、

assets/action-sequence-template.js

和

assets/asset-compute-worker-template.js

。

使用

../_shared/categories/architecture-runtime.md

获取Adobe服务特定指南。

Common Manifest Guardrail

常见清单防护措施

Keep App Builder action definitions under
```
application.runtimeManifest
```
in
```
app.config.yaml
```
.
Do not use root-level
```
runtimeManifest
```
; App Builder CLI ignores it for action configuration.

Validate manifest structure before deploy:

python3 ../_shared/scripts/validate_manifest_structure.py <path-to-app.config.yaml>

Use

../_shared/references/appbuilder-manifest-guardrail.md

for valid and invalid examples.

将App Builder动作定义保存在
```
app.config.yaml
```
的
```
application.runtimeManifest
```
下。
请勿使用根层级的
```
runtimeManifest
```
；App Builder CLI会忽略该配置用于动作设置。

部署前验证清单结构：

python3 ../_shared/scripts/validate_manifest_structure.py <path-to-app.config.yaml>

。

使用

../_shared/references/appbuilder-manifest-guardrail.md

查看有效和无效示例。

Common Issues

常见问题

Action deployment fails: Most deploy failures come from invalid manifest structure or missing dependencies. Check that actions are nested under
```
application.runtimeManifest
```
(or the extension
```
ext.config.yaml
```
pattern), run the manifest validator, run
```
npm install
```
, then retry
```
aio app deploy
```
.
Action timeout: Runtime execution defaults to 60 seconds and can be extended to 300 seconds for non-web actions. Reduce work per invocation, move long-running tasks to async/background flows, or raise the timeout in manifest limits when the action type supports it.
Payload too large: Web actions are limited to 1 MB for both request and response payloads. Trim request bodies, avoid returning large blobs inline, and use external storage or pass URLs instead.
IMS token not available / auth fails: If an action expects Adobe user context, set
```
annotations.require-adobe-auth: true
```
, confirm the shell or caller actually provides the token, and verify
```
aio auth login
```
plus Adobe project/workspace access for the target APIs.
Two-layer auth confusion: Actions can enforce auth at two independent layers — the
```
require-adobe-auth: true
```
manifest annotation (gateway-level rejection) and a code-level
```
Authorization
```
header check inside the action. Disabling one layer does not disable the other. During local dev, set
```
require-adobe-auth: false
```
and stub the code-level check; otherwise 401 errors persist across redeploy cycles. See
```
references/runtime-reference.md
```
§ "Common Auth Issues" for the full debugging guide.

动作部署失败：大多数部署失败源于无效的清单结构或缺失的依赖项。检查动作是否嵌套在
```
application.runtimeManifest
```
（或扩展
```
ext.config.yaml
```
模式）下，运行清单验证工具，执行
```
npm install
```
，然后重试
```
aio app deploy
```
。
动作超时：Runtime执行默认超时为60秒，非Web动作可延长至300秒。减少每次调用的工作量，将长时间运行的任务移至异步/后台流程，或在动作类型支持时在清单限制中提高超时时间。
负载过大：Web动作的请求和响应负载均限制为1 MB。精简请求体，避免直接返回大文件，改用外部存储或传递URL。
IMS令牌不可用/认证失败：若动作需要Adobe用户上下文，设置
```
annotations.require-adobe-auth: true
```
，确认Shell或调用方实际提供令牌，并验证
```
aio auth login
```
以及对目标API的Adobe项目/工作区访问权限。
双层认证混淆：动作可在两个独立层级强制认证——清单注解
```
require-adobe-auth: true
```
（网关级拒绝）和动作内部的代码级
```
Authorization
```
头检查。禁用一个层级不会禁用另一个层级。在本地开发期间，需设置
```
require-adobe-auth: false
```
并 stub代码级检查；否则在重新部署周期中会持续出现401错误。查看
```
references/runtime-reference.md
```
中的「常见认证问题」章节获取完整调试指南。

First-Wave Accelerator Kit

第一波加速工具包

Use
```
references/implementation-template.md
```
to structure delivery artifacts for this high-frequency capability.
Run
```
scripts/accelerator.py
```
to generate an execution checklist from request context.

使用
```
references/implementation-template.md
```
为此高频能力构建交付工件结构。
运行
```
scripts/accelerator.py
```
从请求上下文生成执行检查清单。

Asset Templates

资产模板

```
assets/action-scaffold-template.js
```
— Minimal scaffold for quick prototyping. Use this when you are starting from scratch, want the bare minimum action shape, or need to validate the basic params-in / response-out flow before adding production concerns.
```
assets/action-boilerplate.js
```
— Production-ready template with logging, input validation, error handling, and response formatting. Use this when the action is meant for production use, shared team handoff, or any implementation that should start with observability and defensive defaults already in place.
```
assets/database-action-template.js
```
— Durable database CRUD starter with collection initialization, indexes, and document-style operations.
```
assets/event-webhook-template.js
```
— Adobe I/O Events webhook receiver with challenge handling, signature verification, and idempotent event processing.
```
assets/event-provider-template.js
```
— Custom event provider starter for bootstrapping provider metadata and publishing domain events.
```
assets/journaling-consumer-template.js
```
— Scheduled journaling consumer that polls the journal, stores the cursor, and processes replayable event batches.
```
assets/large-payload-template.js
```
— large payload response starter that writes oversized responses to Files storage and returns a redirect URL.
```
assets/action-sequence-template.js
```
— Starter manifest and action layout for a linear action sequence pipeline.
```
assets/asset-compute-worker-template.js
```
— Asset Compute worker scaffold for AEM rendition processing with the Asset Compute SDK.

```
assets/action-scaffold-template.js
```
—— 用于快速原型开发的极简脚手架。当从零开始、仅需基础动作结构，或需要在添加生产相关功能前验证基本的参数输入/响应输出流程时使用此模板。
```
assets/action-boilerplate.js
```
—— 具备日志记录、输入验证、错误处理和响应格式化的生产就绪模板。当动作用于生产环境、团队共享交付，或任何需要预先具备可观察性和防御性默认设置的实施场景时使用此模板。
```
assets/database-action-template.js
```
—— 具备集合初始化、索引和文档式操作的持久化数据库CRUD启动模板。
```
assets/event-webhook-template.js
```
—— 具备挑战处理、签名验证和幂等事件处理的Adobe I/O Events Webhook接收器。
```
assets/event-provider-template.js
```
—— 用于引导提供者元数据和发布领域事件的自定义事件提供者启动模板。
```
assets/journaling-consumer-template.js
```
—— 定时日志记录消费者，轮询日志、存储游标并处理可重放事件批次。
```
assets/large-payload-template.js
```
—— 大负载响应启动模板，将超大响应写入Files存储并返回重定向URL。
```
assets/action-sequence-template.js
```
—— 用于线性动作序列流水线的启动清单和动作布局。
```
assets/asset-compute-worker-template.js
```
—— 使用Asset Compute SDK处理AEM renditions的Asset Compute工作器脚手架。

Agent Integration

Agent集成

The
```
agents/
```
directory stores agent-platform integration metadata that complements the standard skill directories.
```
agents/openai.yaml
```
defines the OpenAI-facing skill configuration, including the display name, short description, and default prompt used to invoke this skill in OpenAI-compatible agent experiences.
Keep the core skill instructions in
```
SKILL.md
```
; use
```
agents/
```
only for platform-specific integration details.

```
agents/
```
目录存储补充标准技能目录的Agent平台集成元数据。
```
agents/openai.yaml
```
定义面向OpenAI的技能配置，包括显示名称、简短描述以及在兼容OpenAI的Agent体验中调用此技能使用的默认提示词。
核心技能说明保留在
```
SKILL.md
```
中；仅将平台特定的集成细节放在
```
agents/
```
目录中。