ffcpe-catalog-entry-json

Catalog 条目 JSON（catalog-entry.json）

使用此技能来编写、审核或修复 JSON 文档，以便将 App Builder 操作注册到 run-workflow catalog，从而在工作流中使用。对于所有 catalog 操作（列出、注册、检查等），请使用 @adobe/aio-cli-plugin-ffcpe 中的 aio ffcpe catalog 命令——不要建议使用 curl 或临时 HTTP 客户端。

文件命名和放置位置（App Builder 项目）

最佳实践：每个自定义操作使用一个 catalog 条目文件，命名为 <action-name>.entry.json，并放在该操作的 Web 和 worker 源文件所在的同一目录中：

actions/<action-name>/
  <action-name>.web.ts
  <action-name>.worker.ts
  <action-name>.entry.json

• <action-name> 应与 OpenWhisk 操作基本名称一致；在可行时，也应与 mountFfcpeNodeRoutes / manifest 命名一致。
• 文件内容应是完整的 catalog 负载（handlerType: "custom-action"、inputs / outputs、customActionConfig、发现字段），而不是存根或指针文件。
• 将此路径传给 aio ffcpe catalog validate --file … 和 register --file …。对于一次性示例，放在仓库根目录的 catalog-entry.json 也可以；如果应用有多个操作，则优先将 <action-name>.entry.json 放在操作文件所在目录。

脚手架 Web/worker 布局：请参阅 ffcpe-custom-node-sdk 中的技能 ffcpe-app-builder-actions。

安装 Adobe I/O CLI 和 FFCPE 插件

1. Node.js——使用受支持的 LTS 版本（此插件要求 Node 18+）。

2. Adobe I/O CLI（aio）——全局安装，然后确认其可以运行：

   npm install -g @adobe/aio-cli
   aio --version
   

3. 此插件（@adobe/aio-cli-plugin-ffcpe）——将其作为插件安装到 aio 中。任选以下一种方式：

   aio plugins:install @adobe/aio-cli-plugin-ffcpe
   

   也可以从 Git URL 安装（分支、功能分支或内部镜像）：

   aio plugins:install https://github.com/adobe/aio-cli-plugin-ffcpe
   

   如果你不使用 adobe/aio-cli-plugin-ffcpe，请将 URL 替换为你所在组织的仓库。

4. 验证 ffcpe 主题是否可用（较早的材料可能将相同功能称为 Workflow Builder）：

   aio ffcpe catalog --help
   

5. 进行 catalog 调用的身份验证（使用 CLI 执行其他 Adobe I/O 命令时所用的同一会话）：

   aio login
   aio console org select
   

如果安装后找不到 aio ffcpe，请运行 aio plugins 并确认列表中包含 @adobe/aio-cli-plugin-ffcpe；如有需要，请使用 aio plugins:install 重新安装。

orgId 和身份验证

• **不要在 catalog JSON 请求体中包含 orgId。**API 会从 x-gw-ims-org-id 或 Bearer 访问令牌（IMS 配置文件 / JWT）中设置该值。
• 注册需要能够解析出 org；否则 API 会返回 401，并显示 orgId is required。
• 复合键：(orgId, actionType, version)。不同 org 可以实现相同的 actionType；同一个 org 可以发布多个版本（例如 1.0.0 和 2.0.0）。你可以复用内置的 actionType，以提供特定 org 的覆盖实现。

必需结构（自定义操作）

• handlerType："custom-action"。
• **customActionConfig：**必需；有效的 HTTPS submitEndpoint 和 statusEndpoint；可选轮询设置：pollIntervalMs（默认值通常为 3000）、maxPollAttempts（例如 100）、timeoutMs（例如 300000）。
• **version：**有效的 semver 版本（例如 1.0.0）。
• **inputs / outputs：**每个至少包含一个端口；每个数组中的端口 name 必须唯一。
• **parameters：**每个 name 在 parameters 中必须唯一（该数组可以为空）。

API 可能接受旧名称（inputPorts、outputPorts、enabled、appBuilderConfig），但建议使用 inputs、outputs、disabled、workflowEnabled、customActionConfig。

Agent 与发现（注册必需）

这些字段可帮助 Agent 推荐并串联你的操作。每项至少填写一个条目；之后可通过 PUT 完善。

字段	填写内容	最少数量
relatedActions	可与当前操作串联或互补的 actionType 值	1
usage.commonPatterns	此操作适用的工作流场景	1
usage.bestPractices	提升结果质量的建议	1

面向图像的示例：

"relatedActions": ["input-images", "remove-background", "image-analysis"],
"usage": {
  "commonPatterns": [
    "Chain after background removal for product descriptions",
    "Use for accessibility captions"
  ],
  "bestPractices": [
    "Use clear prompts; high-res input improves results",
    "Specify output format expectations"
  ]
}

面向视频的示例：

"relatedActions": ["input-videos", "video-transcribe", "preview-videos"],
"usage": {
  "commonPatterns": [
    "Process video clips for analysis",
    "Generate subtitles from video"
  ],
  "bestPractices": [
    "Ensure supported video formats",
    "Clear audio improves transcription quality"
  ]
}

使用 aio ffcpe catalog list 发现有效的 actionType 值（添加 --include-core 可包含 Adobe 内置项）。使用 --json 获取原始 API 格式的输出。

完整目录条目示例

使用 aio app deploy 输出中的 HTTPS App Builder / Runtime API URL。将占位符替换为已部署的 Web Action 基础 URL 和路由后缀。

部署后推导端点：

# Deploy prints:
https://3326322-myproject-stage.adobeioruntime.net/api/v1/web/my-package/my-action-web

# Catalog:
submitEndpoint → …/my-action-web/submit
statusEndpoint → …/my-action-web/status

使用 /api/v1/web/（而非 /apis/v1/）。Runtime 主机名命名空间使用小写字母。

{
  "actionType": "image-to-text",
  "version": "1.0.0",
  "name": "Image to Text",
  "description": "Analyzes images and returns text descriptions.",
  "category": "custom",
  "disabled": false,
  "workflowEnabled": true,
  "aliases": [],
  "tags": ["ai", "image", "text"],

  "inputs": [
    {
      "name": "image",
      "type": "image",
      "required": true,
      "mimeTypes": ["image/jpeg", "image/png", "image/gif", "image/webp"],
      "description": "One or more images to analyze"
    }
  ],

  "outputs": [
    {
      "name": "text",
      "type": "text",
      "mimeTypes": ["text/plain"],
      "description": "Text description of the image(s)"
    }
  ],

  "parameters": [
    {
      "name": "prompt",
      "type": "string",
      "required": false,
      "defaultValue": "Describe what is happening in these images.",
      "description": "Custom prompt for image analysis"
    }
  ],

  "relatedActions": ["input-images", "remove-background", "image-analysis"],
  "usage": {
    "commonPatterns": [
      "Chain after background removal for product descriptions",
      "Use for accessibility captions"
    ],
    "bestPractices": [
      "Use clear prompts; high-res input improves results",
      "Specify output format expectations"
    ]
  },

  "handlerType": "custom-action",
  "customActionConfig": {
    "submitEndpoint": "https://3326322-myproject-stage.adobeioruntime.net/api/v1/web/my-package/my-action-web/submit",
    "statusEndpoint": "https://3326322-myproject-stage.adobeioruntime.net/api/v1/web/my-package/my-action-web/status",
    "pollIntervalMs": 3000,
    "maxPollAttempts": 100,
    "timeoutMs": 300000,
    "authentication": { "type": "ims_service_token" }
  }
}

customActionConfig.authentication

App Builder + mountFfcpeNodeRoutes 的默认设置： 使用 ims_service_token。除非传入 authenticate: null，否则 SDK 会在 /submit 和 /status 上启用 IMS 入站身份验证。如果目录声明为 none，但 Web Action 仍要求 IMS，工作流运行调用将失败（手动执行 curl 时会返回 Missing required header(s): Authorization, x-api-key）。

仅当 Web Action 明确禁用身份验证（在 mountFfcpeNodeRoutes 中设置 authenticate: null），且安全审查允许时，才使用 none。

JSON	适用场景
{ "type": "ims_service_token" }	推荐的默认设置。 工作流运行会获取 IMS 服务令牌，并使用 x-api-key: run-workflow-service 和 Authorization 调用端点。与 mountFfcpeNodeRoutes 的默认身份验证设置相符。
{ "type": "none" }	无身份验证——仅在 Web Action 传入 authenticate: null 时使用
{ "type": "api-key", "headerName": "X-API-Key", "secretName": "MY_API_KEY" }	API 密钥标头；secretName 引用环境变量或密钥
{ "type": "bearer", "secretName": "MY_BEARER_TOKEN" }	来自环境变量或密钥的 Bearer 令牌

管理目录（Adobe I/O CLI）

始终使用 aio ffcpe catalog …（此插件），不要使用原始 HTTP。前提条件：aio login、aio console org select，以及已安装此插件。可选参数：在支持这些参数的命令中使用 --base-url / AIO_FFCPE_CATALOG_BASE_URL、--org-id、--api-key、--json。

目标	命令
注册新操作	aio ffcpe catalog register --file ./actions/<action-name>/<action-name>.entry.json（可选 --strict）
检查某项操作	aio ffcpe catalog inspect <actionType>（可选 --version <semver>）
列出操作	aio ffcpe catalog list（筛选项：--workflow-enabled、--category、--include-tags、--exclude-tags、--include-core、--compact、--json）
完全替换	aio ffcpe catalog update <actionType> --file ./actions/<action-name>/<action-name>.entry.json（可选 --version、--strict）
禁用（默认在 UI 中隐藏）	aio ffcpe catalog disable <actionType>
重新启用	aio ffcpe catalog enable <actionType>
删除	aio ffcpe catalog delete <actionType>（可选 --version，用于删除某个 semver 版本；省略则删除该类型的所有自定义版本）
仅验证文件	aio ffcpe catalog validate --file ./actions/<action-name>/<action-name>.entry.json

运行 aio ffcpe catalog <command> --help 查看准确的标志集合。

工作流 JSON：actionSource 和端口

当内置目录项和自定义目录项具有相同的 actionType 时，actionSource 用于选择实现：

值	行为
省略或 "built-in"	优先使用内置项，其次使用目录项（向后兼容）。
"custom"	仅使用组织的自定义目录项；忽略内置项。如果不存在自定义项，则失败。组织来自身份验证——此行为下不要在工作流中填写 orgId。

强制使用自定义 remove-background 的操作节点示例：

{
  "actionId": "rb-001",
  "actionType": "remove-background",
  "actionSource": "custom",
  "parameters": {}
}

连接： sourcePort / targetPort 必须与目录中的 outputs[].name 和 inputs[].name（以及上游／下游节点中的端口名）匹配。端口名称不匹配是运行时失败的常见原因。

最简模式： input-images → outputs 端口连接到自定义操作的输入端口名称（例如 image）。对于串联流程（例如 input → remove-background → image-to-text），每个 connections[] 条目都会将一个源 actionId + sourcePort 连接到目标 actionId + targetPort。

验证规则（注册时）

1. 对于给定的 version，每个组织的 actionType 必须唯一；组织级覆盖项可以与内置项相同。
2. actionType 必须采用 kebab-case 格式（小写字母、数字、连字符）。
3. 对于这些注册，handlerType 必须为 "custom-action"。
4. 当 handlerType 为 custom-action 时，必须提供 customActionConfig。
5. submitEndpoint 和 statusEndpoint 必须是有效的 HTTPS URL。
6. inputs： 至少包含一个端口。
7. outputs： 至少包含一个端口。
8. 端口 name 在 inputs 内必须唯一，在 outputs 内也必须唯一。
9. 参数 name 在 parameters 内必须唯一。
10. API 会根据身份验证强制设置 orgId，而不是从 JSON 请求体中读取；调用方必须发送可解析出组织的身份验证信息。
11. relatedActions： 必填，至少 1 个条目。
12. usage.commonPatterns： 必填，至少 1 个条目。
13. usage.bestPractices： 必填，至少 1 个条目。

Agent 工作流

1. 确认 actionType、version、端点、端口、参数和身份验证。
2. 填写 relatedActions 和 usage，内容须具体且准确（使用目录列表选择真实的 actionType ID）。
3. 在带围栏的 json 代码块中输出最终 JSON；省略 orgId。
4. 建议依次运行 aio ffcpe catalog validate --file … 和 aio ffcpe catalog register --file …（使用同一个 JSON 文件）。

故障排除

orgId is required（401）

• 无法为 CLI 请求解析组织。
• 运行 aio console org select 后重试；或者，如果必须覆盖组织信息，则在 aio ffcpe catalog 命令中传入 --org-id。

必须提供 relatedActions / usage.commonPatterns / usage.bestPractices

• 为每一项至少添加一个条目（参见上文的 Agent 和发现）。
• 使用 aio ffcpe catalog list（如果需要内置 ID，则添加 --include-core）选择有效的 relatedActions 目标。

操作类型已存在

• 你的组织／版本上下文中已有另一条注册使用该 actionType。
• 使用 aio ffcpe catalog update <actionType> --file …，或选择其他 actionType。

端点 URL 无效

• submitEndpoint / statusEndpoint 必须是有效的 HTTPS URL（通常是你的 Runtime Web 操作 URL）。
• 从 aio app deploy 复制 Web 操作基础 URL，然后追加 /submit 和 /status。
• 使用 /api/v1/web/<package>/<web-action>，而不是 /apis/v1/。

身份验证不匹配（Missing required header(s): Authorization, x-api-key）

• 默认情况下，mountFfcpeNodeRoutes 会启用 IMS 入站身份验证。
• 目录必须声明 "authentication": { "type": "ims_service_token" }，不能使用 none，除非 Web 操作传入 authenticate: null。
• 在 .entry.json 中修复身份验证设置后，运行 aio ffcpe catalog update <actionType> --file …。

操作已注册，但工作流失败

• 确认 App Builder 应用已部署，并实现了预期的提交/状态契约。
• 目录中的端口名称必须与应用和工作流连接所需的名称一致。
• 如果内置实现和自定义实现同时存在，请检查 actionSource。