commerce-app-migrate

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Migrate to App Management

迁移至App Management

Use this skill when the user wants to migrate an Adobe Commerce App Builder project from the Integration Starter Kit or Checkout Starter Kit to the new App Management approach using
@adobe/aio-commerce-lib-app
.
This skill orchestrates the full migration: detection → domain analysis → Q&A → config assembly → execution. It leaves the project fully migrated and ready to deploy.
当用户希望使用
@adobe/aio-commerce-lib-app
将Adobe Commerce App Builder项目从Integration Starter Kit或Checkout Starter Kit迁移至新的App Management方案时,可使用本技能。
本技能会编排完整的迁移流程:检测 → 领域分析 → 问答 → 配置组装 → 执行。迁移完成后,项目即可直接部署。

Confirmation protocol

确认协议

At each step marked [await]: end your turn immediately, output nothing further, and wait for the developer's reply before proceeding.
Autonomous mode: If invoked with
--auto
or
--yes
, or the context indicates an automated pipeline (no interactive terminal), skip all [await] points and proceed directly to the next step.
Doc-scan-only mode: If invoked with
--doc-scan-only
, skip all migration steps after the Analyzer. After Step 1 completes (Analyzer returns a
ProjectSnapshot
):
  • If
    alreadyMigrated === false
    , output:
    --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.
    Then stop.
  • If
    alreadyMigrated === true
    , apply any applicable Cross-cutting Warnings, then dispatch the Executor in doc-scan-only mode. No files are modified. Do not proceed to Steps 2–5.

在每个标记为**[await]**的步骤中:立即结束当前操作,不再输出任何内容,等待开发者回复后再继续。
自主模式: 如果调用时传入
--auto
--yes
,或上下文表明处于自动化流水线(无交互式终端),则跳过所有**[await]**节点,直接进入下一步。
仅文档扫描模式: 如果调用时传入
--doc-scan-only
,则在分析器完成后跳过所有迁移步骤。完成步骤1(分析器返回
ProjectSnapshot
)后:
  • 如果
    alreadyMigrated === false
    ,输出:
    --doc-scan-only要求项目已迁移至App Management方案。
    未找到app.commerce.config.ts(或.js)文件。
    
    请运行/commerce-app-migrate(不带--doc-scan-only参数)先执行迁移。
    然后停止操作。
  • 如果
    alreadyMigrated === true
    ,应用所有适用的跨领域警告,然后以仅文档扫描模式调用执行器。不会修改任何文件。 请勿继续执行步骤2–5。

Preflight Check

预检检查

Before doing anything else, verify the current directory looks like an App Builder project. Check that ALL of these exist:
  • app.config.yaml
  • package.json
  • At least one of:
    actions/
    directory OR
    src/
    directory OR
    actions-src/
    directory (some projects compile TypeScript from
    actions-src/
    to
    actions/
    ;
    actions/
    may be gitignored and absent in a fresh checkout)
If none of those pass, stop immediately and output:
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.
Do not proceed further if the preflight fails.

在执行任何操作前,先验证当前目录是否为App Builder项目。需确保以下所有文件/目录均存在:
  • app.config.yaml
  • package.json
  • 至少存在以下目录之一:
    actions/
    src/
    actions-src/
    (部分项目会将TypeScript代码从
    actions-src/
    编译到
    actions/
    actions/
    可能被git忽略,在全新检出的项目中可能不存在)
如果以上条件未全部满足,立即停止操作并输出:
此目录似乎不是Commerce App Builder项目。
预期应找到:app.config.yaml、package.json,以及actions/或src/目录。

请在App Builder项目的根目录下运行本技能。
如果预检失败,请勿继续执行后续操作。

Step 1: Run Analyzer Agent

步骤1:运行分析器Agent

Dispatch the Analyzer agent (defined in
${CLAUDE_SKILL_DIR}/agents/analyzer.md
) using the Agent tool. The Analyzer reads the current directory and returns a
ProjectSnapshot
JSON object (schema defined in
${CLAUDE_SKILL_DIR}/shared/schema.md
).
Before printing the summary, check these early-exit conditions:
If
alreadyMigrated === true
:
Output:
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
Then apply any applicable Cross-cutting Warnings (see subsection below).
Then dispatch the Executor agent (
${CLAUDE_SKILL_DIR}/agents/executor.md
) in doc-scan-only mode to produce documentation recommendations for the project:
  • Pass
    mode = "doc-scan-only"
    to the Executor
  • Pass the
    ProjectSnapshot
    JSON from the Analyzer
  • Pass
    assembled config = null
    (no new config to write)
The Executor will scan
README.md
and
env.dist
against the existing
app.commerce.config.ts
and print the "Documentation recommendations" report without modifying any files.
Do not proceed to Steps 2–5 (domain agents, Q&A, config assembly, full execution) unless the developer explicitly requests a specific section update.
After the Executor prints the documentation recommendations, stop. Do not continue to the "Detected project:" summary block or the migration confirmation prompt below.
After the Analyzer returns, print a human-readable summary:
Detected project:
  Type:             <starterKitType> Starter Kit
  Auth mode:        <authMode> (<paas = "PaaS/OAuth1" | saas = "SaaS/IMS" | dual = "Both PaaS + SaaS" | unknown = "Unknown">)
  Action packages:  <comma-separated list of package names> (<count> packages)
  Onboarding:       <comma-separated list of script paths with purposes, or "none">
  Package manager:  <packageManager>

Migration will include: <list domains where confidence !== "none">
Apply any applicable Cross-cutting Warnings (see subsection below).
If
hasMeshConfig === true
, also append:
⚠ API Mesh configuration detected (mesh.json).
Mesh configuration cannot be migrated automatically and must be preserved manually.
Then ask:
Does this look correct? (yes / no — if no, describe what's wrong)
Press Enter or type "yes" to proceed automatically.
[await]
Handle corrections:
  • If developer corrects
    starterKitType
    , update it in the ProjectSnapshot before proceeding
  • If developer corrects
    authMode
    , update it
  • Re-print summary with corrections and ask again until confirmed
Handle unknown starterKitType: If
starterKitType === "unknown"
, check
extensionPointsInUse
:
  • If
    "commerce/backend-ui/1"
    is present → this is an Admin UI SDK v1 extension. Proceed with
    starterKitType = "unknown"
    — the admin-ui-sdk domain agent will migrate it to v2. Print a note: "Detected Admin UI SDK v1 (commerce/backend-ui/1). Migrating to v2 (commerce/backend-ui/2)."
  • If all confidence values are
    "none"
    AND
    extensionPointsInUse
    is empty: Output:
    This project does not appear to be based on the Integration Starter Kit
    or Checkout Starter Kit. No event consumers, webhooks, or Admin UI SDK
    patterns were detected.
    
    Migration can still generate a minimal app.commerce.config.ts with metadata
    only. Continue? (yes / no)
    If developer says no, stop. If yes, proceed with empty domain results.
  • Otherwise, ask the developer:
    I couldn't determine which starter kit this project is based on.
    Is this an Integration Starter Kit or a Checkout Starter Kit?
    Options: [integration / checkout / adminUiSdk / custom]
    
    Not sure? See the documentation:
      • Integration Starter Kit: https://developer.adobe.com/commerce/extensibility/starter-kit/integration/
      • Checkout Starter Kit:     https://developer.adobe.com/commerce/extensibility/starter-kit/checkout/
    Update the ProjectSnapshot with their answer before proceeding.
使用Agent工具调用分析器Agent(定义于
${CLAUDE_SKILL_DIR}/agents/analyzer.md
)。 分析器会读取当前目录并返回
ProjectSnapshot
JSON对象(schema定义于
${CLAUDE_SKILL_DIR}/shared/schema.md
)。
在打印汇总前,检查以下提前退出条件:
如果
alreadyMigrated === true
输出:
该项目似乎已迁移至App Management方案。
已找到:app.commerce.config.ts(或使用ESM defineConfig的app.commerce.config.js)

重新运行迁移会覆盖现有配置。
如果希望重新生成特定部分,请指定需更新的部分: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、问答、配置组装、完整执行)。
执行器打印文档建议后,停止操作。请勿继续输出“检测到的项目:”汇总块或下方的迁移确认提示。
分析器返回结果后,打印易读的汇总信息:
检测到的项目:
  类型:             <starterKitType> Starter Kit
  认证模式:        <authMode> (<paas = "PaaS/OAuth1" | saas = "SaaS/IMS" | dual = "PaaS + SaaS双模式" | unknown = "未知">)
  动作包:          <逗号分隔的包名列表>(共<count>个包)
  引导流程:       <逗号分隔的带用途的脚本路径列表,或“无”>
  包管理器:        <packageManager>

迁移将包含:<confidence !== "none"的领域列表>
应用所有适用的跨领域警告(见下方小节)。
如果
hasMeshConfig === true
,额外追加:
⚠ 检测到API Mesh配置(mesh.json)。
Mesh配置无法自动迁移,需手动保留。
然后询问:
以上信息是否正确?(是/否——若否,请描述问题)
按回车键或输入“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
    相关模式。
    
    迁移仍可生成仅包含metadata的最小化app.commerce.config.ts。是否继续?(是/否)
    如果开发者选择否,停止操作。如果选择是,继续执行,领域结果为空。
  • 否则,询问开发者:
    无法确定该项目基于哪个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后再继续。

Cross-cutting Warnings

跨领域警告

Apply these whenever the corresponding field is set in the ProjectSnapshot, regardless of migration state. Append each matching block to whatever output is currently being built.
If
openWhiskTriggers
is non-empty
, append:
⚠ OpenWhisk triggers detected (cannot be auto-migrated):
  <list each trigger description>
These scheduled triggers have no direct equivalent in App Management.
Read
${CLAUDE_SKILL_DIR}/shared/migration-warnings.md
(OpenWhisk Triggers section) and present the replacement options to the developer.
If
hasApiGateway === true
, append:
⚠ OpenWhisk API Gateway routes detected (apis: blocks in runtime manifest).
These HTTP routes have no direct equivalent in App Management.
Read
${CLAUDE_SKILL_DIR}/shared/migration-warnings.md
(API Gateway section) and present the migration options to the developer.
If
hasSequences === true
, append:
⚠ OpenWhisk sequences detected.
Action sequences have no equivalent in App Management.
Read
${CLAUDE_SKILL_DIR}/shared/migration-warnings.md
(Sequences section) and present the refactoring guidance to the developer.

无论迁移状态如何,只要ProjectSnapshot中存在对应字段,就应用以下警告。将每个匹配的警告块追加到当前输出内容中。
如果
openWhiskTriggers
非空
,追加:
⚠ 检测到OpenWhisk触发器(无法自动迁移):
  <列出每个触发器的描述>
这些定时触发器在App Management方案中没有直接对应的替代方案。
阅读
${CLAUDE_SKILL_DIR}/shared/migration-warnings.md
(OpenWhisk Triggers章节),并向开发者展示替代方案。
如果
hasApiGateway === true
,追加:
⚠ 检测到OpenWhisk API Gateway路由(运行时清单中的apis:块)。
这些HTTP路由在App Management方案中没有直接对应的替代方案。
阅读
${CLAUDE_SKILL_DIR}/shared/migration-warnings.md
(API Gateway章节),并向开发者展示迁移选项。
如果
hasSequences === true
,追加:
⚠ 检测到OpenWhisk序列。
动作序列在App Management方案中没有对应的替代方案。
阅读
${CLAUDE_SKILL_DIR}/shared/migration-warnings.md
(Sequences章节),并向开发者展示重构指导。

Step 2: Dispatch Domain Agents in Parallel

步骤2:并行调用领域Agent

For each domain where
confidence !== "none"
, dispatch the corresponding agent at the same time using the Agent tool (all in one parallel call):
confidence fieldAgent file
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
Each agent receives:
  • The
    ProjectSnapshot
    JSON
  • Instruction to read the relevant files in the current directory using their own Read tools
Collect all returned
DomainResult
objects. Each has
domain
,
configFragment
, and
unresolvedQuestions
fields (schema in
${CLAUDE_SKILL_DIR}/shared/schema.md
).

对于每个
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
字段(schema定义于
${CLAUDE_SKILL_DIR}/shared/schema.md
)。

Step 3: Grouped Q&A

步骤3:分组问答

Collect all
unresolvedQuestions
from every
DomainResult
. If there are no unresolved questions across all domains, skip to Step 4.
Present all questions in a single grouped session (format defined in
${CLAUDE_SKILL_DIR}/shared/questions.md
):
  • Group by domain
  • For questions with
    default
    values, show as confirmations: "(suggested: X)"
  • Number questions sequentially across domains
[await]
For each answer received:
  • Apply it to the
    configFragment
    of the corresponding
    DomainResult
  • Use the question
    id
    to locate the exact field to update
If the developer accepts a suggested value (presses Enter / says "yes"), use the
default
.
Special case — skip-by-default questions (where
default
is
"no"
): These questions ask whether to include an optional section that was omitted from the
configFragment
because required data was missing (e.g. a provider direction with no deployed action package). Interpret the developer's reply as:
  • "no"
    (or pressing Enter) → leave the section out of the
    configFragment
    ; do nothing
  • "yes"
    or any action string → add the section back; prompt for the runtime action name if not already specified in the reply, then apply it to the
    configFragment
Autonomous mode — auto-accepted defaults summary:
In
--auto
mode, after applying all question defaults, print:
── Auto-accepted defaults ────────────────────────────────────────
  The following questions were answered automatically (--auto mode):
  [  <domain> : <question id> = "<default value>"  ]
     ← one line per question that had an explicit default; omit entire section if no questions existed →
Omit this section entirely if there were no unresolved questions across all domains.

收集所有
DomainResult
中的
unresolvedQuestions
。 如果所有领域均未存在未解决的问题,跳过步骤4。
将所有问题以单个分组会话的形式呈现(格式定义于
${CLAUDE_SKILL_DIR}/shared/questions.md
):
  • 按领域分组
  • 对于带有
    default
    值的问题,以确认形式展示:“(建议:X)”
  • 跨领域按顺序为问题编号
[await]
针对收到的每个回答:
  • 将其应用到对应
    DomainResult
    configFragment
  • 使用问题的
    id
    定位需更新的具体字段
如果开发者接受建议值(按回车键/输入“yes”),则使用
default
值。
特殊情况——默认跳过的问题
default
"no"
): 这些问题询问是否要添加一个可选部分,由于缺少必要数据(例如,无已部署动作包的提供者方向),该部分已从
configFragment
中省略。开发者的回复按以下规则解读:
  • "no"
    (或按回车键)→ 不将该部分加入
    configFragment
    ;不执行任何操作
  • "yes"
    或任何操作字符串 → 将该部分重新加入;如果回复中未指定运行时动作名称,则提示用户输入,然后将其应用到
    configFragment
自主模式——自动接受默认值汇总:
--auto
模式下,应用所有问题的默认值后,打印:
── 自动接受默认值 ────────────────────────────────────────
  以下问题已自动回答(--auto模式):
  [  <领域> : <问题id> = "<默认值>"  ]
     ← 每个带有明确默认值的问题占一行;若无问题则省略整个区块 →
如果所有领域均未存在未解决的问题,则完全省略该区块。

Step 4: Assemble app.commerce.config.ts

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

Read
package.json
from the current directory to extract metadata.
Assemble the full config content by merging all
configFragment
objects:
typescript
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'>",
  },
  // 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
});
Metadata derivation rules:
  • id
    : Check
    extension-manifest.json
    first — if it has an
    id
    field and it is not the same as the package name boilerplate, use it (apply same normalization: lowercase, replace non-alphanumeric with
    -
    , trim, max 50 chars). Otherwise take
    name
    from
    package.json
    . Strip npm scope (
    @scope/
    ). Replace any non-alphanumeric characters (except
    -
    ) with
    -
    . Lowercase the entire string. Trim leading/trailing dashes. Max 50 chars. Known ISK boilerplate names to skip in favor of extension-manifest.json:
    commerce-integration-starter-kit
    ,
    starter-kit
    ,
    commerce-checkout-starter-kit
    ,
    aio-app-builder-template
    .
  • displayName
    : Check
    extension-manifest.json
    first — if it has a
    displayName
    field, use it (truncated to 50 chars). Otherwise title-case the
    id
    (replace
    -
    with spaces). Max 50 chars.
  • version
    : Use
    package.json
    version
    . Default:
    "1.0.0"
    .
  • description
    : Use
    package.json
    description
    if present. If the description exceeds 255 characters, do NOT truncate it mid-sentence. Instead, rewrite it: read the full description and compose a shorter one that fits in 255 characters while preserving the essential meaning — what the app does, which systems it connects, and its key capabilities. Prefer complete sentences; drop secondary detail (deployment notes, exhaustive feature lists) before core purpose. Never end with
    "..."
    — the rewritten description must read as intentional, not cut off. The rewritten value applies only to the config: the Executor records the original
    package.json
    description before init and restores it afterwards (init writes the config value back into
    package.json
    ). If absent or empty, check
    extension-manifest.json
    description
    field (apply the same rewrite rule). If neither has a description:
    "Commerce App Builder application"
    .
productDependencies comment: If
ProjectSnapshot.productDependencies
is non-null (has
minVersion
and/or
maxVersion
): Insert this comment block in the assembled TypeScript, immediately AFTER the copyright header and BEFORE the
import { defineConfig }
line:
typescript
// Product version constraints (no App Management equivalent — for reference only):
// Adobe Commerce compatibility: >= <minVersion>, < <maxVersion>
// Contact Adobe Commerce Marketplace for guidance on version enforcement.
Omit the
< <maxVersion>
part if
maxVersion
is null. Omit the
>= <minVersion>
part if
minVersion
is null. If both are null or
productDependencies
is null, omit the comment entirely.
Print the assembled TypeScript content to the terminal:
Here is the app.commerce.config.ts that will be created:

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

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

Does this look correct? (yes / no — if no, which section needs updating?)
Press Enter or type "yes" to proceed automatically.
[await]
Handle rejection: If the developer says no, ask: "Which section needs updating? (metadata / eventing / installation / adminUi / businessConfig)"
Then ask the specific corrective question for that section, update the assembled config accordingly, re-print, and ask for confirmation again.
Repeat until the developer confirms. Do NOT restart the entire flow — only re-enter the Q&A for the specific section being corrected.

读取当前目录下的
package.json
以提取元数据。
通过合并所有
configFragment
对象组装完整的配置内容:
typescript
import { defineConfig } from "@adobe/aio-commerce-lib-app/config";

export default defineConfig({
  metadata: {
    id: "<从package.json name派生>",
    displayName: "<从package.json name派生>",
    version: "<来自package.json version或1.0.0>",
    description:
      "<来自package.json description或'Commerce App Builder application'>",
  },
  // eventing: { ... }          ← 来自events领域的DomainResult(若存在)
  // installation: { ... }      ← 来自webhooks领域的DomainResult(若存在)
  // adminUi: { ... }           ← 来自admin-ui-sdk领域的DomainResult(从v1迁移而来,若存在)
  // businessConfig: { ... }    ← 来自business-config领域的DomainResult(若存在)
});
元数据派生规则:
  • id
    :首先检查
    extension-manifest.json
    ——如果存在
    id
    字段且其值与包名模板不同,则使用该值(应用相同的规范化规则:小写,将非字母数字字符替换为
    -
    ,修剪前后空格,最大长度50字符)。 否则从
    package.json
    中获取
    name
    。去除npm作用域(
    @scope/
    )。将任何非字母数字字符(除
    -
    外)替换为
    -
    。将整个字符串转为小写。 修剪前后的
    -
    。最大长度50字符。 已知需优先使用extension-manifest.json的ISK模板名称:
    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"
  • description
    :如果
    package.json
    中存在
    description
    则使用。 如果描述超过255字符,请勿在句子中间截断。 而是重写描述:读取完整描述,撰写一个更简短的版本,既能容纳在255字符内,又能保留核心含义——应用的功能、连接的系统及其关键能力。优先使用完整句子;在保留核心目的之前,删除次要细节(部署说明、详尽的功能列表)。 切勿以
    "..."
    结尾——重写后的描述必须看起来是有意为之,而非被截断。 重写后的值仅适用于配置:执行器会在初始化前记录原始的
    package.json
    描述,并在之后恢复(初始化会将配置值写回
    package.json
    )。 如果
    package.json
    中无描述或描述为空,检查
    extension-manifest.json
    description
    字段(应用相同的重写规则)。 如果两者均无描述:使用
    "Commerce App Builder application"
productDependencies注释: 如果
ProjectSnapshot.productDependencies
非空(包含
minVersion
和/或
maxVersion
): 在组装的TypeScript中插入以下注释块,位于版权头之后、
import { defineConfig }
行之前:
typescript
// 产品版本约束(App Management方案无对应功能——仅作参考):
// Adobe Commerce兼容性:>= <minVersion>, < <maxVersion>
// 如需版本实施指导,请联系Adobe Commerce Marketplace。
如果
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({
  ...组装后的内容...
})
─────────────────────────────────────────────────────────

以上内容是否正确?(是/否——若否,哪个部分需要更新?)
按回车键或输入“yes”可自动继续。
[await]
处理拒绝: 如果开发者选择否,询问:“哪个部分需要更新?(metadata / eventing / installation / adminUi / businessConfig)”
然后针对该部分询问具体的修正问题,相应地更新组装后的配置,重新打印并再次请求确认。
重复此过程直至开发者确认。请勿重启整个流程——仅针对需修正的部分重新进入问答环节。

Step 5: Execute Migration

步骤5:执行迁移

Dispatch the Executor agent (
${CLAUDE_SKILL_DIR}/agents/executor.md
) with:
  1. The assembled
    app.commerce.config.ts
    TypeScript content as a string
  2. The final
    ProjectSnapshot
    JSON
The Executor performs all file writes and CLI commands and prints the migration summary.
If the Executor reports an error, relay the error message and the step that failed. Do not attempt to roll back changes — the git branch created by the Executor provides a rollback point (
git checkout main
to abandon the migration).

调用执行器Agent(
${CLAUDE_SKILL_DIR}/agents/executor.md
),传入:
  1. 组装好的
    app.commerce.config.ts
    TypeScript字符串内容
  2. 最终的
    ProjectSnapshot
    JSON
执行器会执行所有文件写入和CLI命令,并打印迁移汇总。
如果执行器报告错误,转发错误信息和失败步骤。 请勿尝试回滚更改——执行器创建的git分支提供了回滚点(
git checkout main
可放弃迁移)。

Notes

注意事项

  • Domain agents (Step 2) run in parallel — dispatch all eligible agents in one Agent tool call
  • Analyzer (Step 1) and Executor (Step 5) are sequential — Analyzer first, Executor last
  • This skill runs in the developer's project directory, not the migration skill repository
  • Documentation recommendations are produced by the Executor and cover:
    • README.md sections flagged by 5 patterns: ISK onboarding commands, old env var references, outdated architecture diagrams, credential-family semantic matching (IMS/SaaS, PaaS/OAuth1, workspace), and env setup boilerplate (
      cp env.dist .env
      )
    • env.dist entries grouped into three buckets: safe-to-remove (managed by App Management), review-manually (referenced in action source files, grouped by file), and onboarding-only (used only in onboarding scripts)
    • Rule 9 catches unreferenced env.dist variables not matched by any other rule and flags them for manual review
    • Category C (README) requires ≥ 5 flagged sections to emit the recommendations block
  • --auto
    mode
    prints a summary of all Q&A questions answered automatically with their defaults (omitted if no questions existed)
  • productDependencies
    version constraints from
    extension-manifest.json
    are auto-inserted as a comment block immediately before the
    import { defineConfig }
    line in the generated
    app.commerce.config.ts
  • Internal metadata fields (
    _directionWarning
    ,
    _source
    ) may be added by domain agents to
    configFragment
    objects — the Executor strips these before writing files so they never appear in the output TypeScript
  • 领域Agent(步骤2)并行运行——一次Agent工具调用完成所有符合条件的Agent调用
  • 分析器(步骤1)和执行器(步骤5)是顺序执行的——先运行分析器,最后运行执行器
  • 本技能在开发者的项目目录中运行,而非迁移技能仓库
  • 文档建议由执行器生成,涵盖:
    • README.md中被5种模式标记的章节:ISK引导命令、旧环境变量引用、过时的架构图、凭证族语义匹配(IMS/SaaS、PaaS/OAuth1、工作区)、环境设置模板(
      cp env.dist .env
    • env.dist条目分为三类:可安全移除(由App Management管理)、需手动检查(在动作源文件中被引用,按文件分组)、仅用于引导流程(仅在引导脚本中使用)
    • 规则9会捕获未被其他规则匹配的未引用env.dist变量,并标记为需手动检查
    • C类(README)需至少5个被标记的章节才会输出建议块
  • --auto
    模式
    会打印所有自动回答的问答汇总(若无问题则省略)
  • **
    productDependencies
    **来自
    extension-manifest.json
    的版本约束会自动作为注释块插入到生成的
    app.commerce.config.ts
    import { defineConfig }
    行的紧上方
  • 内部元数据字段
    _directionWarning
    _source
    )可能由领域Agent添加到
    configFragment
    对象中——执行器会在写入文件前移除这些字段,因此它们不会出现在输出的TypeScript中

Supporting Files

支持文件

Agent files dispatched by this skill:
  • Analyzer
  • Events
  • Webhooks
  • Admin UI SDK
  • Business Config
  • Executor
Shared reference files:
  • Schema
  • Questions format
  • Migration warnings
  • External references
本技能调用的Agent文件:
  • 分析器
  • 事件
  • Webhook
  • Admin UI SDK
  • 业务配置
  • 执行器
共享参考文件:
  • Schema
  • 问题格式
  • 迁移警告
  • 外部参考