在 Adobe App Builder 项目中创建…

当需要为 App Builder 项目新增/实现/部署/调试 Adobe Runtime action（含 webhook、事件提供者、journaling、大负载、action sequence、Asset Compute worker 等模式）时使用。

适用场景

解决思路

1. 将 action 代码放在 src/<extension-dir>/actions/<action-name>/index.js，并在 src/<extension-dir>/ext.config.yaml 中注册，保持路径与生成的扩展布局一致。
2. 根据用户意图选择模板：通用起点用 assets/action-boilerplate.js；最小原型用 assets/action-scaffold-template.js；数据库 CRUD 用 assets/database-action-template.js；webhook 接收器用 assets/event-webhook-template.js；自定义事件提供者用 assets/event-provider-template.js；journaling 消费者用 assets/journaling-consumer-template.js；大负载响应用 assets/large-payload-template.js；action sequence 流水线用 assets/action-sequence-template.js；Asset Compute worker 用 assets/asset-compute-worker-template.js；调试 Runtime action 问题参考 references/debugging.md。
3. 当请求明确匹配单一模式（用户点名模式、引用模板或描述清晰匹配某一项）时走 Fast Path，直接使用匹配模板进行脚手架，不再走完整工作流。
4. 若存在歧义（多个模式都可能、约束不清、信息不足），则走完整工作流：1) 确认目标结果、约束与验收标准；2) 从代码、环境和 Adobe 配置收集当前实现上下文；3) 按 references/playbook.md 执行详细流程；4) 产出实现工件与验证证据；5) 交付前过一遍 references/checklist.md；6) 总结决策、风险与下一步行动。
5. 扩展目录名随项目模板不同：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 worker）；以项目 app.config.yaml 的 $include 条目中的实际目录名为准。
6. Web action 响应返回 { statusCode, body }，仅在需要时加 headers。
7. CLI 循环：本地迭代用 aio app dev（若 action 使用 State SDK、Files SDK 或 sequence 则用 aio app run），直接测试用 aio rt action invoke，发布用 aio app deploy。
8. State 用于临时任务跟踪；database 用于持久记录、带索引查询或文档式 CRUD。
9. 事件投递选择：webhook 用于推送投递，custom event provider 用于发布领域事件，journaling consumer 用于可重放或背压场景。
10. 响应超过 1 MB 限制时使用 large payload redirect；线性多 action 流程使用 action sequence。
11. AEM rendition 处理使用 Asset Compute worker，其 SDK 与扩展布局与标准 Runtime action 不同。
12. 将 action 定义放在 app.config.yaml 的 application.runtimeManifest 下；不要使用根级 runtimeManifest，App Builder CLI 会忽略它。
13. 部署前校验 manifest 结构：python3 ../_shared/scripts/validate_manifest_structure.py <path-to-app.config.yaml>；有效/无效示例见 ../_shared/references/appbuilder-manifest-guardrail.md。
14. 部署失败时：检查 action 是否嵌套在 application.runtimeManifest（或扩展 ext.config.yaml 模式）下，运行 manifest 校验器，执行 npm install，然后重试 aio app deploy。
15. Action 超时时：Runtime 默认 60 秒，非 web action 可延长至 300 秒；减少单次调用工作量、把长任务移到异步/后台流程，或在 manifest limits 中提高超时（当 action 类型支持时）。
16. 负载过大时：web action 请求和响应均限 1 MB；裁剪请求体、避免内联返回大 blob，改用外部存储或传 URL。
17. IMS token 不可用/认证失败时：若 action 需要 Adobe 用户上下文，设置 annotations.require-adobe-auth: true，确认 shell 或调用方确实提供 token，并验证 aio auth login 及目标 API 的 Adobe 项目/工作区访问权限。
18. 区分两层认证：manifest 注解 require-adobe-auth: true（网关层拒绝）与 action 内代码级 Authorization 头检查相互独立，禁用一层不会禁用另一层；本地开发时需同时设置 require-adobe-auth: false 并在代码中 stub 掉检查，否则 401 会在反复重新部署中持续出现（完整调试指南见 references/runtime-reference.md 的 Common Auth Issues）。
19. 使用 references/implementation-template.md 组织交付工件；运行 scripts/accelerator.py 根据请求上下文生成执行清单。
20. 参考文档：references/playbook.md（详细执行指导）、references/checklist.md（交付前校验）、references/prompt-pack.md（现成执行提示）、references/runtime-reference.md（action 结构、参数、响应格式、SDK 用法与 CLI 操作）、references/aem-apis.md（AEM Content Fragment API 决策表、Delivery/Management OpenAPI、GraphQL 持久查询、已弃用的 Assets HTTP API 及各自认证模式与 action 代码）、references/action-patterns.md（CRUD API、cron、多步处理、数据库 CRUD、webhook 接入、自定义事件提供者、journaling 消费者、大负载重定向、action sequence 组合、Asset Compute worker 等常见模式）、../_shared/categories/architecture-runtime.md（Adobe 服务特定指导）。
21. 构建 Workfront 扩展时改用 workfront-actions 技能（含 { data, error } 响应契约、SPA 传来的 IMS token 透传、Workfront Public API v21）；本技能用于通用 action 模式、模板与 App Builder SDK。
22. agents/ 目录存放 agent 平台集成元数据：agents/openai.yaml 定义 OpenAI 侧技能配置（显示名、简短描述、默认调用提示）；核心技能指令保留在 SKILL.md，agents/ 仅放平台特定集成细节。

适用边界 · 注意事项

• 构建 Workfront 扩展时应使用 workfront-actions 技能，而非本技能的通用 action 模式。
• 请求存在歧义（多个模式都可能、约束不清或信息不足）时不要走 Fast Path，应走完整工作流。
• 不要使用根级 runtimeManifest 配置 action，App Builder CLI 会忽略它。