appbuilder-action-scaffolder

App Builder 操作脚手架

适用于 Adobe Runtime 操作的完整生命周期技能——搭建脚手架、实现、部署和调试。将操作代码放在 src/<extension-dir>/actions/<action-name>/index.js，并在 src/<extension-dir>/ext.config.yaml 中注册。

正在构建 Workfront 扩展？Workfront 专属操作层——{ data, error } 响应约定、从 SPA 传递 IMS 令牌，以及 Workfront 自有的 Public API v21——位于 workfront-actions 中。通用操作模式、模板和 App Builder SDK 请使用此技能。

模式快速参考

选择与用户意图相符的模板。通用操作默认使用 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 衍生版本）	assets/asset-compute-worker-template.js
调试 Runtime 操作问题	references/debugging.md

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

如果用户的请求明确对应上方的某一种模式——用户点名特定模式、引用某个模板，或描述的用例明确匹配某一项——则跳过完整流程，直接搭建脚手架。使用匹配的模板并直接开始。

快速路径触发示例：

• “添加一个 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，直接搭建脚手架

如果存在任何歧义——可能适用多种模式、约束不明确，或用户未提供足够信息来选择单一方案——则转入下方的完整工作流。

快速参考

• 操作入口点： 将操作代码放在 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 Content Fragment Console 扩展
  • 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 衍生版本处理；其 SDK 和扩展布局与标准 Runtime 操作不同。

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

1. 确认目标结果、约束和验收标准。
2. 从代码、环境和 Adobe 配置中收集当前实现的上下文。
3. 按照 references/playbook.md 中针对该功能的详细流程执行。
4. 生成实现产物和验证证据。
5. 在最终交接前，逐项检查 references/checklist.md。
6. 总结决策、风险和接下来的行动。

用户提示词示例

• “在我的 App Builder 项目中添加一个调用 AEM Assets API 的新操作。”
• “我的运行时操作在 60 秒后超时。如何提高时限而不影响应用？”
• “设置一个每 5 分钟运行一次的 cron 操作，用于从外部 API 同步数据。”
• “创建一个接收文件上传并使用 Files SDK 存储文件的 Web 操作。”
• “在 App Builder Database 中存储客户偏好设置。”
• “设置一个 webhook，用于接收资产变更的 I/O Events。”
• “我的操作响应太大了——如何处理超过 1MB 的负载？”

需请求的信息

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

交付物

• 针对所请求功能的实现更新
• 验证证据：测试、检查或可复现的验证步骤
• 交接摘要，明确说明权衡和后续行动

质量标准

• 明确决策，并说明其与项目约束的关联
• 对可重复的步骤优先采用确定性自动化
• 安全地处理失败，并提供可执行的诊断信息
• 在交接说明中记录权衡和后续步骤的风险

参考资料

• 使用 references/playbook.md 获取详细的执行指南。
• 使用 references/checklist.md 进行交接前验证。
• 使用 references/prompt-pack.md 获取可直接使用的执行提示词。
• 使用 references/runtime-reference.md 了解操作结构、参数、响应格式、SDK 用法和 CLI 操作。
• 使用 references/aem-apis.md 了解 AEM Content Fragment API 的接口，包括决策表、Delivery OpenAPI、Management OpenAPI、GraphQL 持久化查询以及已弃用的 Assets HTTP 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 服务专属指南。

常见清单防护要求

• 在 app.config.yaml 的 application.runtimeManifest 下定义 App Builder 操作。
• 不要使用根级 runtimeManifest；App Builder CLI 会忽略其中的操作配置。
• 部署前验证清单结构：python3 ../_shared/scripts/validate_manifest_structure.py <path-to-app.config.yaml>。
• 使用 ../_shared/references/appbuilder-manifest-guardrail.md 查看有效和无效示例。

常见问题

• 操作部署失败： 大多数部署失败都是由清单结构无效或缺少依赖项导致的。请检查操作是否嵌套在 application.runtimeManifest 下（或采用扩展的 ext.config.yaml 模式），运行清单验证器，执行 npm install，然后重试 aio app deploy。
• 操作超时： 运行时执行默认超时时间为 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 并替换代码级检查；否则，在重新部署周期中仍会持续出现 401 错误。完整调试指南请参阅 references/runtime-reference.md §“常见身份验证问题”。

第一波加速套件

• 使用 references/implementation-template.md 为此高频功能整理交付材料。
• 运行 scripts/accelerator.py，根据请求上下文生成执行清单。

资产模板

• 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 — 用于 AEM 衍生内容处理的 Asset Compute 工作器脚手架，基于 Asset Compute SDK。

Agent 集成

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