SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场commercetools-custom-application

commercetools-custom-application

编程与开发

查看项目

更新于 10-27 20:03

技能介绍

用途

该技能旨在帮助用户从零开始创建一个 Merchant Center 自定义应用（Custom Application），并最终将其注册到用户的 Organization 中，安装到用户选择的 Organization（所有项目或按 Organization 设置允许列表）的指定项目，并显示在这些项目的主菜单中。

主要能力

  • 通过聊天收集用户输入（应用名称、区域、项目键、入口路径、菜单标签、联系邮箱、文件夹、语言、托管方式等）。
  • 在独立的 git 仓库中搭建应用（使用 create-mc-app），安装依赖并构建。
  • 将应用部署到静态托管（支持 Vercel、Netlify、Cloudflare Pages、Surge、Connect 等，具体取决于用户选择）。
  • 在 Merchant Center 中注册应用（Draft 状态），发送验证邮件，用户点击后完成注册（Ready 状态）。
  • 将应用安装到用户选择的 Organization 和项目，并使其出现在主导航中。
  • 提供文档检索脚本，确保基于最新验证的文档进行操作。
  • 支持无头模式（headless）运行，所有步骤通过脚本自动执行，支持中断后恢复。
  • 提供手动步骤（manual-steps.md）供无法运行命令或需要手动重做某一步时使用。
  • 包含验证脚本（verify.mjs）检查部署后的应用路径和深层路径是否返回 200。

使用方式

  1. 首先运行文档检索脚本（docs-search.mjs），获取最新验证的文档作为主要依据。
  2. 运行 Step 0：无头模式（headless.mjs）。这是唯一推荐路径，无论用户是否有终端。
    • 先询问用户应用名称，然后通过 intake.mjs 获取表单问题并询问用户。
    • 使用 intake.mjs check 验证答案。
    • 运行 headless.mjs，传入答案作为参数。脚本会检查工具并启动 Merchant Center 登录，打印登录 URL 并等待凭据文件。
    • 脚本可能退出码 4，返回 needs 对象列出 Organizations 和项目，此时询问用户选择哪些 Organizations 以及所有项目或允许列表，写入计划文件（installPlan），然后重新运行并传入 --install-plan。
    • 退出码 0 且 stage 为 "review" 时，打印审查信息（应用事实、安装目标、所有者 Organization、部署帮助设置），展示给用户并获取明确同意。
    • 获得同意后，重新运行并传入 --confirmed。脚本将执行创建应用、git init、安装依赖、构建、注册（Draft）、部署、主机检查、完成注册（Ready、安装）、打开浏览器等步骤。
    • 如果某步骤需要用户提供值（团队、令牌、生产 URL），脚本退出码 4 并返回 needs，询问用户后重新运行并传入相应参数。
  3. 部署帮助选项（--deploy-help on|off）需询问用户，不能默认。
  4. 如果指向现有应用目录（--app-dir），则跳过创建，从当前状态恢复。
  5. 所有命令输出记录到 <app-dir>/.mc-onboarding/session.log。
  6. 手动步骤：当需要手动重做某一步或无法运行命令时，参考 manual-steps.md 中的七个独立命令（输入、预检、搭建、安装目标与注册、部署、完成、验证）。

适用场景

  • 用户拥有 commercetools 项目，并且是某个 Organization 的 Administrators Team 成员。
  • 用户希望创建 Merchant Center 自定义应用并集成到主导航中。
  • 用户希望通过自动化脚本完成从创建到部署、注册、安装的全流程。
  • 用户可能没有终端，但可以通过聊天提供输入并运行无头模式。

限制

  • 用户必须拥有 commercetools 项目，否则应停止并告知。
  • 用户必须是目标 Organization 的 Administrators Team 成员，否则设置 API 会返回 FORBIDDEN。
  • 无头模式是唯一推荐路径，不提供 onboard.mjs。
  • 部署帮助默认不开启，必须询问用户。
  • 不能替用户回答表单、选择 Organizations、所有者或部署开关，也不能替用户回答 needs。
  • 注册过程中需要用户点击验证邮件，脚本会等待。
  • 如果应用安装后未出现在导航中，非管理员需要在其 Team 上授予应用的 View 权限。
  • 如果 register.mjs 报告 INSTALL_MISMATCH，表示应用以另一种模式安装，用户需在 Merchant Center 中切换模式或卸载后重新运行。
  • 如果 register.mjs 报告 "No progress"，表示操作执行但状态未变，需检查错误中指定的步骤状态，不要循环。
  • 主机必须将所有路径重写到 index.html，否则安装后页面空白。
  • 本地开发绕过注册，需检查 Ready 状态并使用 register.mjs 安装。
  • 配置更改（applicationId、url）必须提交，以便下次部署与注册匹配。

检查清单

  • 用户拥有项目且是所有者 Organization 的 Administrators Team 成员。
  • 所有输入均来自用户：没有猜测的 Organizations、所有者、项目键、托管或部署开关。
  • 无头运行以应用 Ready 结束（退出码 0 且包含 productionUrl 并打开），或手动步骤 1 到 6 以 register.mjs 返回 done: true 结束。
  • 应用文件夹是独立的 git 仓库（在该文件夹中运行了 git init -b main，文件夹包含 .git）。
  • scripts/verify.mjs 针对生产 URL 通过（应用路径和更深路径均返回 200）。
  • 在已部署项目的主导航中看到应用，或用户确认且报告称未看到导航。
  • 配置更改（applicationId、url）已提交，以便下次部署与注册匹配。