commerce-app-migrate

迁移到 App Management

当用户希望将 Adobe Commerce App Builder 项目从 Integration Starter Kit 或 Checkout Starter Kit 迁移到新的 App Management 方案，并使用 @adobe/aio-commerce-lib-app 时，请使用此技能。

此技能负责协调完整的迁移流程：检测 → 领域分析 → 问答 → 配置组装 → 执行。迁移完成后，项目即可部署。

确认协议

每当步骤标记为 [await] 时：立即结束当前轮次，不再输出任何内容，并等待开发者回复后再继续。

自主模式： 如果调用时使用了 --auto 或 --yes，或者上下文表明这是自动化流水线（没有交互式终端），则跳过所有 [await] 步骤，直接继续下一步。

仅扫描文档模式： 如果调用时使用了 --doc-scan-only，则在分析器之后跳过所有迁移步骤。步骤 1 完成后（分析器返回 ProjectSnapshot）：

• 如果 alreadyMigrated === false，则输出：

  --doc-scan-only requires the project to already be migrated to App Management.
  No app.commerce.config.ts (or .js) was found.
  
  Run /commerce-app-migrate (without --doc-scan-only) to perform the migration first.
  

  然后停止。

• 如果 alreadyMigrated === true，则应用所有适用的跨领域警告，然后以仅扫描文档模式调度执行器。不会修改任何文件。 不要继续步骤 2–5。

---

预检

开始任何操作之前，请确认当前目录看起来是一个 App Builder 项目。检查以下文件和目录是否全部存在：

• app.config.yaml
• package.json
• 以下目录至少存在一个：actions/、src/ 或 actions-src/ （有些项目会将 TypeScript 从 actions-src/ 编译到 actions/；在全新检出时，actions/ 可能被 git 忽略而不存在）

如果以上条件均不满足，请立即停止并输出：

This directory does not appear to be a Commerce App Builder project.
Expected to find: app.config.yaml, package.json, and an actions/ or src/ directory.

Please run this skill from the root of your App Builder project.

如果预检失败，不要继续。

---

步骤 1：运行分析器 Agent

使用 Agent 工具调度分析器 Agent（定义于 ${CLAUDE_SKILL_DIR}/agents/analyzer.md）。 分析器会读取当前目录并返回一个 ProjectSnapshot JSON 对象 （其架构定义于 ${CLAUDE_SKILL_DIR}/shared/schema.md）。

输出摘要之前，请检查以下提前退出条件：

如果 alreadyMigrated === true： 输出：

This project appears to already be migrated to App Management.
Found: app.commerce.config.ts (or app.commerce.config.js with ESM defineConfig)

Re-running migration would overwrite your existing configuration.
If you want to re-generate specific sections, please specify which
section to update: metadata / eventing / installation / adminUi / businessConfig

然后应用所有适用的跨领域警告（见下方小节）。

随后以仅扫描文档模式调度执行器 Agent（${CLAUDE_SKILL_DIR}/agents/executor.md），为项目生成文档建议：

• 向执行器传递 mode = "doc-scan-only"
• 向执行器传递分析器返回的 ProjectSnapshot JSON
• 传递 assembled config = null（不写入新配置）

执行器会根据现有的 app.commerce.config.ts 扫描 README.md 和 env.dist，并打印“文档建议”报告，不会修改任何文件。

除非开发者明确要求更新特定部分，否则不要继续步骤 2–5（领域 Agent、问答、配置组装、完整执行）。

执行器打印文档建议后，立即停止。不要继续输出下方的“检测到的项目：”摘要块或迁移确认提示。

分析器返回后，输出一份易于理解的摘要： 检测到的项目： 类型： Starter Kit 身份验证模式： （<paas = "PaaS/OAuth1" | saas = "SaaS/IMS" | dual = "Both PaaS + SaaS" | unknown = "Unknown">） Action 包： （ 个包） 入门流程： <comma-separated list of script paths with purposes, or "none"> 包管理器：

迁移将包括：<confidence !== "none" 的域列表>

应用任何适用的跨领域警告（见下文小节）。

如果 hasMeshConfig === true，还需追加：

⚠ 检测到 API Mesh 配置（mesh.json）。
无法自动迁移 Mesh 配置，必须手动保留。

然后询问：

这样看起来正确吗？（yes / no — 如果不正确，请描述问题所在）
按 Enter 或输入 "yes" 自动继续。

[await]

处理更正：

• 如果开发者更正了 starterKitType，请在继续之前更新 ProjectSnapshot 中的值
• 如果开发者更正了 authMode，请更新该值
• 重新打印更正后的摘要并再次询问，直到得到确认

处理未知的 starterKitType： 如果 starterKitType === "unknown"，请检查 extensionPointsInUse：

• 如果存在 "commerce/backend-ui/1" → 这是 Admin UI SDK v1 扩展。继续操作， 保持 starterKitType = "unknown" — admin-ui-sdk 域 Agent 将把它迁移到 v2。 打印提示：“检测到 Admin UI SDK v1 (commerce/backend-ui/1)。正在迁移到 v2 (commerce/backend-ui/2)。”

• 如果所有 confidence 值都是 "none" 且 extensionPointsInUse 为空： 输出：

  此项目似乎并非基于 Integration Starter Kit
  或 Checkout Starter Kit。未检测到事件消费者、webhook 或 Admin UI SDK
  模式。
  
  迁移仍可生成仅包含元数据的最简 app.commerce.config.ts。
  是否继续？（yes / no）
  

  如果开发者回答 no，则停止。如果回答 yes，则继续并使用空域结果。

• 否则，询问开发者：

  我无法确定此项目基于哪个 Starter Kit。
  这是 Integration Starter Kit 还是 Checkout Starter Kit？
  选项：[integration / checkout / adminUiSdk / custom]
  
  不确定？请参阅文档：
    • Integration Starter Kit：https://developer.adobe.com/commerce/extensibility/starter-kit/integration/
    • Checkout Starter Kit：    https://developer.adobe.com/commerce/extensibility/starter-kit/checkout/
  

  继续之前，请使用开发者的回答更新 ProjectSnapshot。

跨领域警告

只要 ProjectSnapshot 中设置了相应字段，就应用这些警告，无论迁移状态如何。将每个匹配的内容块追加到当前正在构建的输出中。

如果 openWhiskTriggers 非空，追加：

⚠ 检测到 OpenWhisk 触发器（无法自动迁移）：
  <逐项列出每个触发器的描述>
这些定时触发器在 App Management 中没有直接对应项。

读取 ${CLAUDE_SKILL_DIR}/shared/migration-warnings.md（OpenWhisk Triggers 部分）， 并向开发者提供替代方案。

如果 hasApiGateway === true，追加：

⚠ 检测到 OpenWhisk API Gateway 路由（runtime manifest 中的 apis: 块）。
这些 HTTP 路由在 App Management 中没有直接对应项。

读取 ${CLAUDE_SKILL_DIR}/shared/migration-warnings.md（API Gateway 部分）， 并向开发者提供迁移选项。

如果 hasSequences === true，追加：

⚠ 检测到 OpenWhisk 序列。
Action 序列在 App Management 中没有对应项。

读取 ${CLAUDE_SKILL_DIR}/shared/migration-warnings.md（Sequences 部分）， 并向开发者提供重构指导。

---

步骤 2：并行调度领域 Agent

对于每个 confidence !== "none" 的领域，使用 Agent 工具同时调度相应的 Agent（在一次并行调用中完成）：

confidence 字段	Agent 文件
confidence.events !== "none"	${CLAUDE_SKILL_DIR}/agents/events.md
confidence.webhooks !== "none"	${CLAUDE_SKILL_DIR}/agents/webhooks.md
confidence.adminUiSdk !== "none"	${CLAUDE_SKILL_DIR}/agents/admin-ui-sdk.md
confidence.businessConfig !== "none"	${CLAUDE_SKILL_DIR}/agents/business-config.md

每个 Agent 都会收到：

• ProjectSnapshot JSON
• 指示其使用自己的 Read 工具读取当前目录中相关文件的说明

收集所有返回的 DomainResult 对象。每个对象都包含 domain、configFragment 和 unresolvedQuestions 字段（架构见 ${CLAUDE_SKILL_DIR}/shared/schema.md）。

---

步骤 3：分组问答

收集所有 DomainResult 中的 unresolvedQuestions。 如果所有领域都没有未解决的问题，则跳到步骤 4。

在一次分组会话中提出所有问题（格式见 ${CLAUDE_SKILL_DIR}/shared/questions.md）：

• 按领域分组
• 对于带有 default 值的问题，以确认形式显示：“（建议：X）”
• 在各领域之间按顺序为问题编号

[await]

对于收到的每个回答：

• 将其应用到对应 DomainResult 的 configFragment
• 使用问题的 id 定位需要更新的确切字段

如果开发者接受建议值（按 Enter 键／回答“是”），则使用 default。

特殊情况——默认跳过的问题（其中 default 为 "no"）： 这类问题询问是否要包含一个可选部分；由于缺少必需数据，该部分已从 configFragment 中省略（例如，没有已部署操作包的提供方方向）。按以下方式解读开发者的回复：

• "no"（或按 Enter 键）→ 将该部分保留在 configFragment 之外；不做任何操作
• "yes" 或任何操作字符串 → 将该部分加回；如果回复中尚未指定运行时操作名称，则提示输入，然后将其应用到 configFragment

自主模式——自动接受默认值摘要：

在 --auto 模式下，应用所有问题的默认值后，打印：

── 自动接受的默认值 ────────────────────────────────────────
  以下问题已在 --auto 模式下自动回答：
  [  <domain> : <question id> = "<default value>"  ]
     ← 每个具有明确默认值的问题占一行；如果没有此类问题，则省略整个部分 →

如果所有领域都没有未解决的问题，则完全省略此部分。

---

步骤 4：组装 app.commerce.config.ts

从当前目录读取 package.json，提取元数据。

合并所有 configFragment 对象，组装完整配置内容：

import { defineConfig } from "@adobe/aio-commerce-lib-app/config";

export default defineConfig({
  metadata: {
    id: "<derived from package.json name>",
    displayName: "<derived from package.json name>",
    version: "<from package.json version or 1.0.0>",
    description:
      "<from package.json description or 'Commerce App Builder application'>",
    upgradeMode: "auto",
  },
  // eventing: { ... }          ← from events DomainResult, if present
  // installation: { ... }      ← from webhooks DomainResult, if present
  // adminUi: { ... }           ← from admin-ui-sdk DomainResult (migrated from v1), if present
  // businessConfig: { ... }    ← from business-config DomainResult, if present
});

元数据推导规则：

• id：先检查 extension-manifest.json——如果其中有 id 字段，且它与软件包名称样板不同，则使用该字段（应用相同的规范化规则：转为小写，将非字母数字字符替换为 -，去除首尾空格，最多 50 个字符）。 否则，使用 package.json 中的 name。去掉 npm 作用域（@scope/）。将所有非字母数字字符（- 除外）替换为 -。将整个字符串转为小写。 去除首尾的连字符。最多 50 个字符。 以下已知 ISK 样板名称应优先使用 extension-manifest.json 中的名称： commerce-integration-starter-kit、starter-kit、commerce-checkout-starter-kit、 aio-app-builder-template。
• displayName：先检查 extension-manifest.json——如果其中有 displayName 字段，则使用该字段（截断至 50 个字符）。否则，将 id 转为标题格式（将 - 替换为空格）。 最多 50 个字符。
• version：使用 package.json 中的 version。默认值："1.0.0"。
• upgradeMode：使用 "manual"（目前为默认值，升级执行流程仍在稳定中），除非开发者明确要求自动执行。"auto" 仍处于实验阶段：生成的部署后钩子会调用期望状态的 POST /installation 端点并启动计划升级，然后等待其生命周期结果。在 "manual" 模式下，同一端点会创建或复用计划并返回，但不会启动执行。
• description：如果 package.json 中有 description，则使用该值。 如果描述超过 255 个字符，不要在句子中间截断。应改写描述：阅读完整描述，并撰写一段不超过 255 个字符的简短描述，同时保留核心含义——应用的用途、连接的系统及其主要功能。尽量使用完整句子；优先删去次要细节（部署说明、详尽的功能列表），而不是核心用途。结尾绝不能是 "..."——改写后的描述应读起来自然完整，而非被截断。 改写后的值仅用于配置：Executor 会在 init 前记录原始的 package.json 描述，并在之后恢复（init 会将配置值写回 package.json）。 如果该字段不存在或为空，则检查 extension-manifest.json 中的 description 字段（应用相同的改写规则）。 如果两者都没有描述，则使用："Commerce App Builder application"。

productDependencies 注释： 如果 ProjectSnapshot.productDependencies 非空（有 minVersion 和/或 maxVersion）： 在组装后的 TypeScript 中，将此注释块插入版权声明之后、import { defineConfig } 行之前：

// Product version constraints (no App Management equivalent — for reference only):
// Adobe Commerce compatibility: >= <minVersion>, < <maxVersion>
// Contact Adobe Commerce Marketplace for guidance on version enforcement.

如果 maxVersion 为 null，则省略 < <maxVersion> 部分。如果 minVersion 为 null，则省略 >= <minVersion> 部分。如果两者都为 null，或 productDependencies 为 null，则完全省略该注释。

将组装后的 TypeScript 内容输出到终端：

以下是将要创建的 app.commerce.config.ts：

─────────────────────────────────────────────────────────
import { defineConfig } from '@adobe/aio-commerce-lib-app/config'

export default defineConfig({
  ...assembled content...
})
─────────────────────────────────────────────────────────

看起来正确吗？（yes / no — 如果不正确，要更新哪个部分？）
按 Enter 或输入 "yes" 自动继续。

[await]

处理拒绝： 如果开发者回答 no，询问：“Which section needs updating? (metadata / eventing / installation / adminUi / businessConfig)”

然后针对该部分提出具体的修正问题，相应更新组装后的配置，重新打印并再次请求确认。

重复此流程，直到开发者确认。不要重新开始整个流程——只需重新进入正在修正的特定部分的问答环节。

---

第 5 步：执行迁移

向 Executor Agent（${CLAUDE_SKILL_DIR}/agents/executor.md）派发以下内容：

1. 作为字符串的完整 app.commerce.config.ts TypeScript 内容
2. 最终的 ProjectSnapshot JSON

Executor 会执行所有文件写入和 CLI 命令，并打印迁移摘要。

如果 Executor 报告错误，请转达错误消息和失败的步骤。 不要尝试回滚更改——Executor 创建的 git 分支提供了回滚点（使用 git checkout main 放弃迁移）。

---

注意事项

• 领域 Agent（第 2 步）会并行运行——在一次 Agent 工具调用中派发所有符合条件的 Agent
• Analyzer（第 1 步）和 Executor（第 5 步）按顺序运行——先运行 Analyzer，最后运行 Executor
• 此技能在开发者的项目目录中运行，而不是在迁移技能仓库中
• Executor 会提供文档建议，内容包括：
  • 由 5 种模式标记的 README.md 章节：ISK 入门命令、旧环境变量引用、过时的架构图、凭证系列语义匹配（IMS/SaaS、PaaS/OAuth1、工作区）以及环境设置样板代码（cp env.dist .env）
  • 将 env.dist 条目分为三个类别：可安全移除（由 App Management 管理）、手动审查（在 action 源文件中引用，按文件分组）以及仅用于入门流程（仅在入门脚本中使用）
  • 规则 9 会捕获其他规则未匹配的未引用 env.dist 变量，并将其标记为需手动审查
  • C 类（README）要求至少标记 ≥ 5 个章节，才会生成建议区块
• --auto 模式会打印所有自动使用默认值回答的问答问题摘要（如果没有问题，则省略）
• extension-manifest.json 中的 productDependencies 版本约束会自动作为注释块插入生成的 app.commerce.config.ts 中，紧邻 import { defineConfig } 行之前
• 领域 Agent 可能会向 configFragment 对象添加内部元数据字段（_directionWarning、_source）——Executor 会在写入文件前将其移除，因此它们不会出现在输出 TypeScript 中

支持文件

此技能派发的 Agent 文件：

• Analyzer
• Events
• Webhooks
• Admin UI SDK
• Business Config
• Executor

共享参考文件：

• Schema
• Questions format
• Migration warnings
• External references