ffcpe-custom-node-sdk

App Builder 上的 FFCPE 自定义操作（@adobe/ffcpe-custom-node-core、@adobe/ffcpe-custom-node-app-builder）

适用对象

在协助使用 NPM 包的使用者时，请使用此技能：这些团队正在交付 App Builder 应用，并由 Workflow Builder 以 custom-action（异步提交 + 状态轮询）的方式调用该应用。

如需为 SDK 源代码仓库做出贡献（单体仓库、Turbo、发布），请参阅 README.md（“Monorepo (contributors)”）以及 SDK 源代码旁的 CONTRIBUTING.md（内部镜像或已发布的仓库检出）。

如需搭建 Web/worker 文件、webpack 和 ext.config.yaml，请使用 ffcpe-app-builder-actions。

如需编写 catalog-entry.json 和使用 aio ffcpe catalog（验证、注册、列出、更新），请安装来自 adobe/aio-cli-plugin-ffcpe 的技能：ffcpe-catalog-entry-json 和 aio-ffcpe-cli。

npx skills add adobe/aio-cli-plugin-ffcpe --all -y

端到端检查清单

0. 初始化 Console 项目（仅限新项目）——通过 aio console 创建项目和工作区，运行 aio app init --standalone-app，下载工作区配置，并通过 aio app use <config>.json --overwrite --no-input 配置。清理 web-src/、搭建生成的通用操作，以及 app.config.yaml 中的 web: web-src。将 webpack-config.js 替换为 esbuild-loader + commonjs2 结构。**Console 项目名称：**只能包含字母数字字符，最多 20 个字符（不能使用连字符）；名称可以不同于 YAML 中的 OpenWhisk 包名称。具体步骤请参阅 ffcpe-app-builder-actions →“从 init-bare 开始”。

1. 安装 SDK 包（npm 或 pnpm）并实现 Web + worker 操作。**最佳实践：**将 catalog 条目与 <action-name>.web.* 和 <action-name>.worker.* 放在同一目录，命名为 <action-name>.entry.json（请参阅 ffcpe-app-builder-actions）。

2. 部署 App Builder 应用；从部署输出中复制 Web 操作基础 URL；将 catalog 中的 submitEndpoint / statusEndpoint 设为 {base}/submit 和 {base}/status。

3. 编写 <action-name>.entry.json——端口必须与 worker 输入/输出名称匹配；端点使用部署所得的端点；使用默认的 mountFfcpeNodeRoutes 身份验证时，设置 authentication: { "type": "ims_service_token" }（除非路由上设置了 authenticate: null，否则不要设为 none）。

4. 使用 CLI 验证并注册——切勿直接使用 curl：

   aio ffcpe catalog validate --file ./actions/my-action/my-action.entry.json
   aio ffcpe catalog register --file ./actions/my-action/my-action.entry.json
   

安装包

使用 npm：

npm install @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder

或使用 pnpm——在应用的 .npmrc 中设置 auto-install-peers=true，然后运行：

pnpm add @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder

显式列出 peers——如果你希望在 package.json 中列出所有 peer，或者使用的工具不会自动安装 peer（例如 Yarn Classic）：

npm install @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder hono hono-openwhisk-adapter

pnpm add @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder hono hono-openwhisk-adapter

常见 peer（请根据模板和 Adobe 文档确认版本）：

• @adobe/aio-lib-core-logging、@adobe/aio-lib-state、@adobe/aio-lib-ims、openwhisk、hono、hono-openwhisk-adapter

链接本地 SDK 检出副本

当使用方应用应从附近的 SDK 单体仓库克隆副本加载 @adobe/ffcpe-custom-node-core / @adobe/ffcpe-custom-node-app-builder，而非从注册表加载时，请使用此方法。

1. 在 SDK 单体仓库中，为两个包安装依赖并构建 dist/：

   pnpm install && pnpm run build
   # or: npm install && npm run build
   

   为了快速迭代，请在 SDK 根目录运行 pnpm run dev（或 npm run dev），以便在更改时重新构建 dist/。

2. 在使用方 App Builder 项目中，先链接 core，再链接 app-builder：

   pnpm：

   pnpm link /path/to/ffcpe-custom-node-sdk/packages/core
   pnpm link /path/to/ffcpe-custom-node-sdk/packages/app-builder
   

   npm：

   npm link /path/to/ffcpe-custom-node-sdk/packages/core
   npm link /path/to/ffcpe-custom-node-sdk/packages/app-builder
   

3. 要恢复使用注册表中的包：

   pnpm unlink @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder && pnpm install
   # or: npm unlink @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder && npm install
   

**可选的全局链接（pnpm）：**分别在 packages/core 和 packages/app-builder 中使用 pnpm link --global 注册每个包，然后在使用方项目中运行 pnpm link --global @adobe/ffcpe-custom-node-core 和 pnpm link --global @adobe/ffcpe-custom-node-app-builder。如果 app-builder 的 workspace:* 无法解析，请继续使用目录链接，或添加使用方的 pnpm.overrides，将 @adobe/ffcpe-custom-node-core 固定到 packages/core 路径。

完整说明见 SDK 的 README.md（“使用本地 SDK 检出副本”）。

安装 Agent 技能

技能位于 SDK 仓库的 skills/ 下，通过 open agent skills CLI 安装。每个 Agent（Claude Code、Cursor 等）都会链接到同一个规范副本，以确保指导内容一致。

从 GitHub 安装（使用方仓库）

# List available skills
npx skills add adobe/ffcpe-custom-node-sdk --list

# Install all FFCPE skills (project-local)
npx skills add adobe/ffcpe-custom-node-sdk --all -y

# Install only this skill
npx skills add adobe/ffcpe-custom-node-sdk --skill ffcpe-custom-node-sdk -y

# Claude Code + Cursor
npx skills add adobe/ffcpe-custom-node-sdk --all -a claude-code -a cursor -y

# Global (all projects on this machine)
npx skills add adobe/ffcpe-custom-node-sdk --all -g -y

从本地 SDK 检出副本安装

npx skills add /path/to/ffcpe-custom-node-sdk/skills --all -y

有关更新/移除命令和技能目录结构，请参阅此仓库中的 skills/README.md。

CLI 插件技能（独立仓库）：

npx skills add adobe/aio-cli-plugin-ffcpe --all -y

在每个 SKILL.md 的 frontmatter 中通过 name 引用技能：ffcpe-custom-node-sdk、ffcpe-app-builder-actions、aio-ffcpe-cli、ffcpe-catalog-entry-json。

Catalog CLI（@adobe/aio-cli-plugin-ffcpe）

部署后，安装 Adobe I/O CLI 插件以执行目录操作：

npm install -g @adobe/aio-cli
aio plugins:install @adobe/aio-cli-plugin-ffcpe
aio login
aio console org select

命令	用途
aio ffcpe catalog validate -f ./actions/<action-name>/<action-name>.entry.json	本地 JSON 验证（不调用 API）
aio ffcpe catalog register -f ./actions/<action-name>/<action-name>.entry.json	注册新的自定义操作
aio ffcpe catalog inspect ACTIONTYPE	获取单个条目
aio ffcpe catalog list	列出自定义操作（添加 --include-core 可包含 Adobe 内置项）
aio ffcpe catalog update ACTIONTYPE -f …	完整 PUT 替换
aio ffcpe catalog disable / enable / delete	生命周期管理

在 register/update 上使用 --strict，可在验证出现警告时使操作失败。使用 AIO_FFCPE_CATALOG_BASE_URL 或 --base-url 覆盖 API 主机。优先使用 aio ffcpe catalog，而不是手写 HTTP 请求——身份验证使用与 aio login 相同的 IMS 会话。

确保目录 JSON 中的 customActionConfig.submitEndpoint / statusEndpoint 与已部署的 Web 操作 URL 以及 mountFfcpeNodeRoutes 中的路由路径一致。目录 inputs / outputs 中的 name 值必须与工作进程通过 getTextInput、getImageInput 等读取的值一致。

两个 OpenWhisk 操作（推荐形态）

1. Web 操作 — FFCPE 的 HTTP 入口：POST /submit、GET /status。构建 Hono 应用，调用 mountFfcpeNodeRoutes，并使用 hono-openwhisk-adapter 中的 ToOpenWhiskAction 导出 main。
2. Worker 操作 — 长时间运行的作业：通过 createFfcpeNodeWorker(handler, options) 导出 main。

使用 ext.config.yaml（或等效文件），确保 web 操作使用 web: "raw" 和 annotations.require-adobe-auth: false（参见 README.md 中的清单示例）。worker / web 的包名和操作名称必须与传给 mountFfcpeNodeRoutes 的值一致。

Web 路由接线（mountFfcpeNodeRoutes）

• 传入 worker: { package, name } — 提交后异步调用 OpenWhisk 的目标。
• 传入 web: { package, name } — 必填；用于构建返回给 Workflow Builder 的 statusUrl。若省略或使用空字符串，挂载时会抛出异常。
• 可选的 routes — 默认值为 /submit 和 /status；应与目录中的 submitEndpoint / statusEndpoint 路径一致。
• 可选的 authenticate — 默认通过 createImsInboundAuth 使用 IMS bearer 和 x-api-key。传入 null 可禁用这些路由的身份验证（仅在产品和安全策略允许时使用）。
• 可选的 jobStore、loggerName、jobMetadata(submit) — 高级选项；默认存储由 aio-lib-state 提供支持。

Worker 处理程序（createFfcpeNodeWorker）

• 实现 FfcpeNodeWorkerHandler：异步函数 ({ jobId, inputs, params, logger, authContext, args }) — inputs 是已验证的 FFCPE input[]；params 是来自 run-workflow 的工作流参数（提交的 parameters）；args 是完整的 worker 调用对象（OpenWhisk main(args)）。
• 返回 { status: "completed", outputs?: ActionOutput[] } 或 { status: "failed", error: string }。
• 在选项中使用 requiredInputNames，以便在提交负载缺少指定输入时快速失败。
• 仅当有意将失败映射为 SDK 的失败作业行为时，才抛出 FfcpeJobFailedError（适配器已会映射处理程序返回的 failed 结果）。

优先使用 @adobe/ffcpe-custom-node-core 中的 findInputByName、getTextInput 等函数，并使用 TextInput、ImageInput、VideoInput、JsonInput 缩窄类型。使用 createTextOutput、createImageOutput、createVideoOutput、createJsonOutput（及相关辅助函数）构建输出。

HTTP 契约（Workflow Builder 的预期行为）

Workflow Builder 会向 submitEndpoint 发送 POST 请求，负载为 { inputs, parameters }，并轮询状态，直到状态变为 completed 或 failed。提交响应应包含 jobId、status，并最好包含用于轮询的 statusUrl。

有关请求头规则、响应字段和轮询语义，请参阅 SDK 文档包或源代码树中的 docs/custom-action-requests.md（供维护者使用的相同材料也与仓库 README 一同提供）。

安全性与健壮性（自定义操作作者须知）

• 将 inputs 和 parameters 视为不可信数据；在获取或处理资源前，验证其类型、大小和 URL。
• 切勿记录令牌、API 密钥或原始 Authorization 请求头；尽量精简 Logger 输出。
• 尽可能使用 HTTPS 资源 URL；如果在 SDK 之外实现自定义获取逻辑，应对可疑协议或重定向采取默认拒绝策略。
• 除非有明确且经过审核的理由使用 authenticate: null，否则应在提交和状态路由上启用身份验证。

高级选项 / 备用方案

• 仅使用 Core 处理 HTTP — 不使用 Hono 时，可使用 handleFfcpeSubmit、handleFfcpeStatus 或 runWorkerJob（仍需要 JobStore、JobOrchestrator、InboundAuth 和状态 URL 构建器）。
• 自定义编排或存储 — 实现 Core 接口（JobStore、JobOrchestrator），并参照上游 README 中“为其他 Cloud Functions Provider 实现”的检查清单（分叉适配器行为时同样适用）。

快速查阅

有关导入速查表、pnpm link 和故障排查（状态 URL、Web 清单），请参阅 references/quick-reference.md。