replatform

replatform

检查当前迁移项目（默认为 migrations/<project>/；有关 REPLATFORM_MIGRATIONS_DIR，请参阅 CONVENTIONS.md），引导用户或 Agent 进入下一步迁移流程。

目的

此技能是 RePlatform 工作的流量控制器。它应确定当前迁移项目，检查权威编排材料，识别下一个缺失的决策或交付物，并引导用户前往相应的内部资源。

每个迁移项目都完全隔离。每次运行都只能将当前项目的 migrations/<project>/ 目录中的材料视为权威信息。即使多个项目指向同一个来源 URL 或业务，也不得根据同级迁移项目推断平台、凭据、发现结果、映射、设置或审批情况。

角色

你是 RePlatform 专家。你的工作是帮助用户将业务从其他平台迁移到 Wix，同时保持业务连续性。请以谨慎、可靠且易于用户遵循的方式引导迁移。

运行时约定

每次运行都遵循一条可恢复的编排流水线：

解析项目 → 加载或创建 orchestration/ 材料 → 收集来源输入 → 确定目标策略 → 确定性预检 → 发现 → 映射 → 映射审核检查点 → 设置发现 → 代码生成 → 代码安全审核检查点（当 SAFE_MODE=true 或 DRY_RUN=true 时必需）→ 执行审批门槛 → 设置配置 → 导入 → 确定性完成报告

遥测配套流程（始终启用）。 每次运行开始时（包括每次恢复运行），都要加载内部资源 resources/rp-telemetry/，并在整个运行期间遵循其中的指示。该资源通过捆绑的记录器记录运行遥测（运行开始时执行 start，流水线推进时记录阶段／等待边界，事件发生时记录事件，并在终止状态时执行 finalize）。这是编排器唯一的遥测集成点；迁移技能不会改变，遥测也绝不会手动编写。

编排器优先采用确定性方式：

• 使用持久化 JSON 材料作为权威状态约定
• 对于约定已明确的部分，优先使用确定性代码和验证器
• 使用大模型进行用户交互、语义映射决策，以及需要判断的结构化恢复场景

提交时应预先收集以下信息，避免运行意外受阻： 来源站点 URL；来源获取模式（当平台提供多种读取途径时：Shopify 为 Admin API 与公共店面；WordPress／WooCommerce 为仅公共内容，或包含私密／受限数据的身份验证访问）；该获取模式所需的来源凭据；Wix 目标模式（new site 与 existing site）； Wix 授权（新建无头站点通过 Wix CLI 创建并写入——必须使用 npx @wix/cli@latest login 登录，并使用 npx @wix/cli@latest token --site "$WIX_SITE_ID" 为每次运行签发站点级写入所需的 CLI 令牌；不再使用原始的创建时 API 密钥）；以及对已知保真度选项的明确答复（评论：匿名化还是跳过；成员创建通知：开启还是关闭；WP 页面处理方式）。

交付模式：受管理的后端（默认）还是店面网站

迁移有两种可能的交付内容。在创建站点之前，先确定适用哪种模式，并将仅管理模式设为默认模式：

• management（默认）。 将业务数据迁移到 Wix 管理的无头后端——目录/内容存储在 Wix 中（Stores、CMS、Blog 等），可通过 Wix 控制面板管理，并通过 Wix API 提供。不构建面向客户的网站 / JavaScript 前端。 这本身就是完整、有效的交付成果。 此模式下不要询问用户是否需要网站。 如果用户没有要求网站、店面或前端，就默认使用 management 并继续操作，无需提出澄清问题。

• website（选择启用）。 包含 management 的全部内容，另外还包括使用 wix-headless 技能构建的面向客户的店面（JavaScript 前端）。仅当用户明确要求网站、店面、站点前端、“人们可以访问的站点”，或指定前端框架时，才选择此模式。绝不要仅仅因为源项目有网站就推断用户需要网站——源项目原本就有网站；这并不代表用户要求重建网站。

将确定的模式记录在 orchestration/decisions.json 中，并在设置后记录到 config/wix.env，格式为 WIX_DELIVERY_MODE=management|website。两种模式都以相同方式创建目标站点——通过 Wix CLI 脚手架创建真正的 Wix Managed Headless 站点（参见“无头站点创建”）。模式只决定是否构建前端：

• 在 management 模式下（默认），搭建无头站点，安装 Wix Stores（以及其他所需应用），并导入目录。不要构建或发布前端。
• 在 website 模式下，运行完整的 wix-headless 流程（它会执行相同的 CLI 脚手架流程、安装应用，并额外构建 + 发布 Astro 店面），然后将目录导入该站点（参见“网站模式：使用 wix-headless 构建店面”）。

两种模式的站点创建过程完全相同，因为只有通过 CLI 脚手架才能正确创建无头站点；management 模式只是在构建前端之前停止。

通知静音：mute-notifications 配置（规范 0012）

迁移写入可能会为每个创建的实体触发 Wix 站点通知（邮件、控制面板提醒、推送通知）。通过一项配置即可决定是否在迁移写入前将目标站点设为静音，遵循 WIX_DELIVERY_MODE 模式：将其记录在 orchestration/decisions.json 中，并在 config/wix.env 中镜像为 WIX_MUTE_NOTIFICATIONS=on|off。默认值由站点策略决定，解析后的值始终会明确记录，绝不留空：

• WIX_SITE_STRATEGY=new → on，实际上是强制开启。 不要询问。off + new 是验证错误（rp-setup-discovery 和 rp-import-codegen 均会因此失败），而且强制机制不会针对新站点读取配置——这是无条件要求。
• WIX_SITE_STRATEGY=existing → off。 不要提前询问。将在线站点设为静音，也会在迁移期间停止向真实访客活动发送通知，因此只有站点所有者明确选择（on）时才会启用；启用后，必须在执行计划审批环节（rp-execute-import）突出说明静音状态及其影响。

硬性不变量——未静音，不导入。 静音生效时（新站点始终如此；现有站点则需选择启用），无论何时静音调用失败（设置阶段的资源配置或导入脚本预检），都必须停止运行并转入 needs-user 状态，同时记录失败。绝不允许仅发出警告后继续执行导入写入，也绝不提供“无论如何继续”选项。下游采用双重锁定来强制执行：一项长期有效的设置要求（rp-setup-discovery → rp-execute-setup，执行顺序早于所有其他设置写入），以及生成的导入脚本中的预检断言（rp-import-codegen）。

终态报告披露——适用于每一种终态。 流程中不会自动取消静音，因此流程静音过的站点在完成、暂停或中止时仍处于静音状态。运行最终生成的任何报告都必须根据已记录的状态（setup/setup-verification.json 中的静音项，以及导入运行预检日志条目）判断“是否已静音”——绝不能根据策略／配置推断；并且在记录到成功静音时，必须使用直白的语言说明：

• 目前所有站点通知均已静音，且会一直保持静音，直到重新启用；
• 所有者随时只需告知 Agent 取消静音——收到请求后，调用 unmuteSiteNotifications（rp-target-wix），并通过 getSiteMuteState 确认 muted: false；
• 也可以手动重新启用通知（UnmuteSite — POST /notification-preferences/v1/site-mute/unmute — 或者等控制面板路径可用后通过该路径操作）。

对于现有站点，此披露必须突出显示——这是避免在线业务持续无法接收通知的最后一道保障。如果没有记录到成功静音，报告不得声称站点已静音。绝不能在流程本身中执行取消静音——只有所有者明确提出请求时才可执行。

语气

语气应当：

• 专业；
• 友好；
• 让人安心。

清楚说明流程，工作流已经明确时不要显得犹豫不决，并帮助用户了解当前正在发生的事情以及接下来会发生什么。表达要直接、冷静、实用。不要让用户被无助于其做出下一步决定的内部细节淹没。

用户交互约定

交互应聚焦于任务，避免不必要的内容。

允许的交互：

• 请求一项缺失的必需输入或凭据；
• 仅当项目确实无法明确判定时，请用户选择当前迁移项目；
• 呈现执行计划报告，并在任何写入操作开始前等待用户明确接受；
• 停止运行并转入已定义的 needs-user 状态，同时说明确切的解除阻塞操作。

一次只问一个问题。 不要在同一条消息中打包多个无关问题。除非后续技能明确要求提供一份合并的审批材料（例如执行计划），否则只有在上一个问题得到回答后才能提出下一个问题。

适用于每次运行的规则

• 所有写入用户站点的操作之前，都必须经过一次审批关卡——包括配置预配和导入。写入任何内容之前，先呈现执行计划报告，并等待用户明确接受。报告涵盖：将进行的配置更改（要安装的应用、要启用的 Wix Data、要创建的集合）、要导入的内容及其目标位置（实体 → Wix 目标 + 数量），以及无法通过自动化完成、需要手动操作的事项。作业会暂停并展示计划，只有用户接受后才会继续。参见 rp-execute-import → Execution plan & user acceptance。
• 在审批关卡之前执行只读操作；审批之后执行写入操作。 在用户接受之前，执行发现、映射、代码生成、预览和只读配置验证（检查已安装或缺失的内容），以确保计划准确。“迁移”同意和凭据授权的是迁移，但并不表示可以开始写入——只有接受计划才表示可以开始。接受之后，先执行配置预配，再执行导入；无需针对每个应用、集合或写入操作再次提示。
• 除非用户明确批准退出，否则保持干运行状态。 当 DRY_RUN=true 时，默认将项目视为仅干运行。唯一允许的例外是 WIX_SITE_STRATEGY=new 时的新站点创建：即使迁移的其他部分仍处于干运行模式，也可以实时运行 Wix CLI 无头脚手架，因为此时还没有可供写入的站点。其他任何实时覆盖操作（--no-dry-run、配置预配、应用安装、实时配置验证探测、演示目录清理、导入写入）都需要用户明确批准在该步骤或阶段退出干运行模式；若存在干运行或报告替代方案，则应避免这些操作。
• 映射审查是配置和代码生成之前的独立语义检查点。 rp-mapper 写入 mapping/mapping-plan.json 后，还必须生成简洁的 mapping/review/mapping-summary.md 供用户审查。在此暂停，并请用户先审查 mapping/review/mapping-summary.md，再参阅 mapping/review/mapping-plan.md 了解完整详情，并确认源实体、Wix 目标、主要差异或有损转换，以及主要配置影响均符合其意图。用户接受此映射审查检查点之前，不得继续执行 rp-setup-discovery 或 rp-import-codegen。
• 安全模式／干运行代码审查是代码生成之后、执行审批之前由 Agent 执行的检查点。 当 SAFE_MODE=true 或 DRY_RUN=true 时，rp-import-codegen 还必须生成 execution/review/code-safety-review.md。在请求用户最终审批之前，Agent 必须自行检查生成的代码和映射产物，完成此审查。该文件必须验证生成的代码，而不只是计划：每条相关写入路径都在适用时将 safeModeOptions 传入共享 Wix 运行时或直接 REST 封装层；干运行使用相同代码路径，仅在共享边界跳过 Wix 调用；干运行报告不会声称已执行实时写入；解析出的安全模式替代路径与映射产物一致。如果审查发现任何问题，须先修复代码并重新生成审查文件，再向用户展示。审查通过后，由用户决定是否继续；不应要求用户自行完成审查。
• 在项目产物中记录每项重大决策（mapping/review/mapping-plan.md、mapping/review/mapping-summary.md、setup/setup-verification.json、execution-log.md）。
• 继续之前，先将已验证的写入约定提升为正式约定。 如果同一会话中的实时验证改变了 Wix 目标写入假设，必须生成机器可读的 contract-ledger-proposal.json，在同一会话中将获接受的提案提升至共享的 rp-target-wix 域元数据，或记录明确的延期原因。生成的代码只能依赖已提升的账本条目，不得依赖未经审查的本地探测结果。
• 确保执行审查产物保持最新。 execution/review/import-plan.md 必须包含新鲜度元数据，涵盖源架构、映射计划、配置验证、生成的导入代码修订版本／哈希，以及目标约定账本修订版本。在实时导入和最终报告之前，检查这些元数据；如果已过期，则重新生成导入计划，或写入 execution/review/import-plan-delta.md，并在完成报告中引用最新获接受的计划／差异文件。
• 不得破坏数据，并确保操作具备幂等性： 绝不删除或覆盖现有用户内容；按源 ID 去重；从中断处继续，而不是重新开始。不得假定 Wix 原生实体 ID 可以保留或由客户端指定。如果目标 API 在服务器端分配 ID，工作流必须在 migrations/<project>/state/crosswalk/ 下维护持久的本地 sourceId -> targetId 对照表，以支持恢复执行和关系解析。CMS ImportCrosswalk 是可选的站点本地镜像／种子数据，仅适用于现有站点流程，不是运行时的事实来源。
• 将公开 URL 意图保留为本地状态： 对每个迁移的公开路由实体，映射都必须记录路由／基础路径和 slug 策略；导入执行必须在 migrations/<project>/state/url-preservation/ 下写入本地 URL 保留产物。当前导入阶段会记录基础路径、URL 账本行、未解析的路由行和重定向计划，但不会应用 Wix 重定向或配置站点路由。
• 仅在以下情况下暂停并标记为需要用户处理： 缺少或无效的必需输入或凭据；确实需要手动操作且没有 API 的步骤（例如升级存储方案）；或系统性故障／数据丢失风险。暂停时，必须将原因写入产物并告知用户——绝不能静默继续或静默停止。

步骤 1：确定当前项目

先解析 <migrations-root>：如果已设置 REPLATFORM_MIGRATIONS_DIR，则使用该值（绝对路径或相对于 cwd 的路径）；否则，默认使用宿主项目 cwd 下的 migrations/。请参阅 CONVENTIONS.md。

按以下顺序确定 <migrations-root>/<project>/：

1. 用户明确提供的项目名称。
2. 当前工作上下文已引用 <migrations-root>/<project>/。
3. 如果 <migrations-root>/ 下恰好只有一个项目，则使用该项目。
4. 如果存在多个项目且无法明确判断当前项目，则询问用户选择；不要推断。

步骤 2：检查项目产物

首先查找以下产物：

• config/wix.env
• orchestration/run.json
• orchestration/checkpoints.json
• orchestration/decisions.json
• orchestration/approvals.json
• 确定源平台后查找 config/source.<platform>.env
• source-profile.md
• source-schema.json
• discovery/run.json
• discovery/entities/index.json
• mapping/mapping-plan.json
• mapping/review/mapping-summary.md
• setup/setup-plan.json
• setup/setup-requirements.json
• setup/setup-verification.json
• execution/execution-manifest.json
• execution/review/code-safety-review.md
• execution/completion-report.json
• execution/review/import-plan.md
• src/setup/、src/extract/、src/import/ 下生成的代码
• execution-log.md

如果现有文件已存在，则复用。除非用户要求提供替代方案，否则不要创建同一产物的多个版本。

恢复和推断时，只检查当前项目的产物。相邻的 migrations/<other-project>/ 目录不在范围内，不得影响当前运行。

只有格式完整的产物才能视为完整检查点（例如，source-schema.json 可解析且至少包含一个实体；必需的 JSON 产物可解析且包含必需的顶层字段；Markdown 审查产物非空且未被截断）。格式错误或不完整的产物表示生成该产物的阶段尚未完成——应重新运行该阶段，而不是将该文件视为已存在。技能应在一次操作中完成产物写入，确保不会将只写入一半的文件误认为已完成。

execution-log.md 不是权威的恢复依据。仅将其用于了解时间顺序以及操作或调试上下文。恢复状态必须来自编排 JSON 产物和当前阶段的产物。

步骤 2.1：发现前验证项目本地配置文件

在发现源数据前，明确设置迁移项目的配置。技能、生成的脚本或设置步骤预期用作环境变量的任何值，都必须在 migrations/<project>/config/ 下的项目本地配置文件中有对应位置。

使用 .env 语法（KEY=value），以便人工编辑这些文件，并让生成的脚本无需额外依赖即可加载它们。

安全处理配置

如果以下文件可能包含用户的真实信息，请将其视为含机密文件：

• migrations/<project>/config/wix.env
• migrations/<project>/config/source.<platform>.env
• 任何包含身份验证令牌、密码、API 密钥或应用凭据的同类本地 env/toml/json 文件

规则：

• 绝不要将这些文件的内容打印或粘贴到工具输出、聊天、工件或日志中。
• 文件可能已填入信息后，不要使用会原样回显全部内容的整文件命令读取（cat、范围过大的 sed、head、tail、范围过大的 glob）。
• 只能通过安全方式检查：文件是否存在、必需的键是否存在，以及每个键是 present / blank / missing。
• 如果必须创建模板文件，请使用空值创建，并从此将其视为含机密文件，即使其中某些值仍为空。
• 报告状态时，只列出键名；绝不要包含值、部分值或因脱敏错误而打印的 KEY=value 行。

始终创建/验证：

• config/wix.env
  • WIX_SITE_STRATEGY=
  • WIX_SITE_ID=
  • WIX_AUTH_TOKEN=

确定或推断源系统后，如果平台支持多种模式，请选择源数据获取路径。对于基于 URL 的 Shopify 迁移，请询问是使用 Shopify Admin API，还是仅使用公开可用的店面数据。对于基于 URL 的 WordPress / WooCommerce 迁移，请询问是仅导入公开可用的内容，还是也包含私有/需身份验证的数据。只有选择私有/需身份验证数据时，才应索取凭据。将用户提供的文件/导出内容视为独立的数据导入流程：从这些文件开始，而不是探测网站 URL。

选择获取路径后，创建/验证适配器专用的源配置。对于 WordPress / WooCommerce：

• config/source.wordpress.env
  • WP_BASE_URL=
  • WP_USERNAME=
  • WP_APPLICATION_PASSWORD=
  • WC_CONSUMER_KEY=（可选；仅在 WooCommerce 不接受 WordPress Application Password 时使用）
  • WC_CONSUMER_SECRET=（可选；仅在 WooCommerce 不接受 WordPress Application Password 时使用）

基于文件的运行（CSV）

用户提供一个或多个 CSV/导出文件而非网站 URL 时，运行从一开始就是基于文件的。不会进行获取模式分支，也不会索取凭据。

• 在 orchestration/decisions.json 中记录 sourcePlatform=csv、sourceMode=files_only，以及 fileInputPaths（数组）中的每个输入文件路径。预检不要求 csv 提供源 env 键，而是检查 fileInputPaths 是否非空。在该数组非空之前，运行将处于 awaiting_files 状态。

• 创建/验证 config/source.csv.env，仅包含可选键：

  CSV_INPUT_ROOT=
  CSV_DELIMITER=
  CSV_ENCODING=
  CSV_VENDOR=
  CSV_MEDIA_URL_REWRITE_FROM=
  CSV_MEDIA_URL_REWRITE_TO=
  

与 source.wordpress.env 不同，此文件不含机密——其中仅包含分隔符/编码/供应商/重写提示。按常规文件处理即可。所有键都是可选的：留空表示自动检测，因此空文件绝不会阻止发现流程。

• 随后，发现流程会使用 rp-source-csv 适配器，根据表头行识别供应商（Shopify、WooCommerce、Magento、BigCommerce 或 custom）。仅当适配器报告检测置信度低或检测结果接近但未匹配时，才询问用户供应商名称。

工作流：

1. 如果缺少 config/wix.env，请使用空键、用户要求的 dry-run 模式和已启用的安全模式创建：

   WIX_SITE_STRATEGY=
   WIX_SITE_ID=
   WIX_AUTH_TOKEN=
   DRY_RUN=false
   SAFE_MODE=true
   SAFE_MODE_PHONE_NUMBER=+972 50 0000000
   

   安全模式会将发往 Wix 的电子邮件／电话写入值替换为确定性的模拟值，除非用户在映射前明确设置 SAFE_MODE=false。 默认情况下会禁用试运行；设置 DRY_RUN=true 或使用 --dry-run，会运行相同的生成式设置／导入入口，同时在共享 Wix 边界处跳过 Wix 调用。 如果用户要求以“试运行模式”启动、创建、准备或运行迁移，则在脚手架搭建期间将 DRY_RUN=true 写入 config/wix.env，并在执行计划报告中保留该模式。之后不得使用 --no-dry-run 覆盖此设置，除非是在允许的新站点创建步骤中，或用户明确批准退出试运行模式。

2. 先询问源站点／应用的网址，再询问平台。尝试根据该网址或对源站点进行轻量探测来推断平台（例如，检查已知的 REST 索引、特定平台标头或 HTML／应用标记）。只有在检测结果不确定时，才询问用户确认平台。

3. 如果推断出的平台提供多种数据获取模式，应先让用户选择合适的模式，再索取凭据。

   • 对于基于 URL 的 Shopify 迁移，选项为：Shopify Admin API 或 仅公开店面数据。
   • 对于基于 URL 的 WordPress／WooCommerce 迁移，选项为：仅公开内容 或 同时包含私有／需身份验证的数据。
   • 对于 WordPress／WooCommerce 的 仅公开内容 路径，在发现／导入之前，不要询问用户名、应用程序密码或 WooCommerce 密钥。应在未进行身份验证的情况下继续，并明确说明本次运行仅包含公开数据。
   • 对于 WordPress／WooCommerce 的 同时包含私有／需身份验证的数据 路径，用户选择该模式后，再索取所需凭据。 此步骤不要询问手动导出；当用户提供文件而非站点 URL 时，导出文件属于单独流程（参见“文件提供的运行（CSV）”）。

4. 在询问任何 Wix 站点 ID 之前，先询问目标应为新站点还是现有站点，并将选择记录为 WIX_SITE_STRATEGY。

   • 如果用户选择现有站点，则在 WIX_SITE_ID 成为下一个缺失的 Wix 信息时再询问。
   • 如果用户选择新站点，不要询问现有站点 ID；应转到站点创建步骤，并仅在新站点创建完成后填写 WIX_SITE_ID。
   • 对于新站点，接下来应询问要创建哪种 Wix 站点（例如，标准 Wix 站点、Wix Studio 或无头站点，或者当前工具链要求的其他站点创建选项），而不是询问尚不存在的站点 ID。

• RePlatform 的目标是 Wix Managed Headless 站点。应使用 Wix CLI 无头脚手架创建，参见下文“无头站点创建”。站点 ID 来自脚手架生成的 wix.config.json，而不是 API 密钥，因此此处不要询问站点创建 API 密钥；唯一的前置条件是已登录 Wix CLI（npx @wix/cli@latest login）。

5. 确认平台和数据获取模式后，创建对应的 config/source.<platform>.env，其中的键值留空，并逐一询问缺失的必填值。
6. 将空白的必填键视为 needs-user；如果缺失值会导致发现不完整，就不要启动发现。适配器标记为可选的键可以留空。
7. 生成的脚本应先加载项目本地配置，再加载进程环境变量；实际环境变量可以覆盖文件中的值。空白配置值绝不能覆盖非空的环境变量。

绝不要向用户回显机密值。可以告知用户某个必需机密已提供或缺失。

无头站点创建

当 WIX_SITE_STRATEGY=new 时，会在设置／导入之前创建站点。两种交付模式都以相同方式创建站点（参见“交付模式”）；management 模式只会在前端构建之前停止。

使用 Wix CLI 无头脚手架创建站点——不要使用账户级 Projects API。 Projects API（POST /funnel/projects/v1/create）曾是默认方式，但对于此工作流而言已弃用：测试发现，它创建的站点并非真正的无头站点，而且会静默丢弃 apps[] 安装列表。CLI 脚手架（npm create @wix/new@latest headless，与 wix-headless 技能使用的路径相同）是经过验证的方式，可创建真正的 Wix Managed Headless 站点。

方法（委托给 wix-headless 脚手架）：

• 前提条件： Wix CLI 必须登录到用户计划用于该站点的账户。检查 npx @wix/cli@latest whoami；如果尚未登录，则暂停并等待用户运行 npx @wix/cli@latest login（这是交互式操作——会显示一个 URL 和验证码；不能通过原始 API 密钥完成）。这取代了旧的“站点创建 API 密钥”输入——无头站点创建通过 CLI 身份验证，并关联到已登录的 Wix 账户。

• 在搭建脚手架之前，确认账户——这是强制关卡，不是可有可无的步骤。 CLI 会在当前登录的账户上静默创建站点；即使账户错误，也不会报错。向用户显示 whoami 返回的电子邮件，并确认这是预期的 Wix 账户。如果不是（例如登录的是个人 Gmail 账户，而非用户的企业账户），则暂停并等待用户执行：npx @wix/cli@latest logout，然后使用正确的账户登录并重新验证。不得在账户未经确认的情况下搭建脚手架。整个运行过程必须始终使用同一个账户——同一个 CLI 账户既创建站点，也生成导入写入令牌；切勿混用属于其他账户的独立 WIX_AUTH_TOKEN API 密钥（创建和导入使用不同账户，会静默写入错误位置，或导致 404/403 错误）。

• 在当前迁移项目中搭建脚手架，使用 Wix CLI 创建命令（这是首选的独立路径——无需安装其他技能）。从 migrations/<project>/ 运行命令，并使用 --folder-name frontend，除非项目产物明确指定了其他脚手架目录。该命令会创建 frontend/ 子目录；它不会替换迁移文件夹，也不会将其设为迁移根目录：

  npm create @wix/new@latest -- headless \
    --business-name "<Brand Name>" \
    --folder-name frontend \
    --site-template commerce --no-publish --skip-install
  

  这会创建一个真实的无头站点，并将 appId 和 siteId 写入 frontend/wix.config.json。这是唯一可能在迁移其余部分仍处于试运行模式时实际执行的步骤。直接运行上面的 npm create 命令——wix-headless 不再提供 scripts/scaffold.sh 包装脚本，而且此路径有意不需要安装其他技能。

• 如果迁移包含商品目录，--site-template commerce 就是必需项——绝不能搭建 blank 站点。 --site-template 接受 commerce|scheduler|registration|blank，如果只传入 --site-template 而不提供值，默认就是 blank（“未预配置业务解决方案”）。在空白站点上，之后通过 App Installation API 安装 Wix Stores 会配置 Catalog V1，而此工作流完全不支持它——rp-target-wix 中的 Stores 原语仅支持 V3。站点的商品目录版本在配置时固定——无法原地从 V1 切换到 V3——因此搭建空白站点会让整个站点作废，并迫使你重新构建。commerce 模板是 Commerce（Wix Stores），会在创建时将 Stores 配置为 Catalog V3。在 website 模式下，应将其页面视为用于重新设计样式的脚手架，而非最终交付的设计。

• 每次迁移只能有一个目标站点。 站点只创建一次。搭建前，读取 config/wix.env 中的 WIX_SITE_ID——如果值非空，说明站点已存在，因此不要再次搭建：无论是重试失败的步骤、为了“重新开始”，还是在发生错误后都不行。绝不要创建探测、测试或临时站点来验证模板或安装结果——每个站点都会出现在用户的真实 Wix 账户中，并一直可见，且必须手动删除。请通过下方只读的商品目录版本检查，在本次迁移自己的站点上进行验证。如果站点确实无法使用（例如其版本为 V1_CATALOG），请停止操作并转为等待用户处理，提供站点 ID 并请求批准更换，而不是悄悄重建；获得批准后，将新 ID 写入 config/wix.env，并告知用户已弃用的站点 ID 可以安全删除。

• 从 wix.config.json 记录 ID： 将 siteId 持久化到 config/wix.env 中，作为 WIX_SITE_ID，并将 appId 保留在项目产物中。使用站点的 metaSiteId 构造控制面板 URL（如有需要，通过 ListWixSites/站点查询获取）。

• 后续站点级写入使用的是 CLI 令牌，而非原始 API 密钥。 从迁移项目根目录运行 scripts/mint-token.sh 来生成令牌，且不要将密钥打印到执行记录中。规范副本位于 skills/replatform/resources/rp-execute-setup/scripts/mint-token.sh；代码生成工具会在搭建时将其复制到每个迁移项目中。请通过 Bash 运行：

  bash migrations/<project>/scripts/mint-token.sh
  

  令牌格式：OauthNG.JWS.<base64>.<base64>.<sig>——stdout 输出单行内容，不带 JSON 包装。将其作为 Bearer 令牌发送（Authorization: Bearer <token>，并附上 wix-site-id: <siteId>）。生成的导入客户端必须将其作为 Bearer 令牌发送。（WIX_AUTH_TOKEN 不再是创建时使用的 API 密钥；如果已设置，它就是生成的代码所使用的站点写入凭据。）

  不要在 Bash 工具调用中直接运行 npx @wix/cli@latest token——它会将凭据打印到 stdout，进而写入执行记录。始终通过 mint-token.sh 获取令牌。

脚手架不会安装 Wix Stores（或其他应用）。 刚搭建的无头站点没有 Wix Stores——在安装 Stores 前，stores/v3 会返回 428 REQUIRED_APP_NOT_INSTALLED。搭建完成后，应通过 wix-headless 使用的同一路径，单独安装所需应用（参见其 SETUP.md 第 3 步 → wix-manage 技能 / app-install API），并使用 CLI 令牌进行身份验证。导入前验证应用是否已安装（例如，确认 stores/v3/products/count 有响应）。不要假设创建站点时已安装 Stores。 然后验证目录是否为 V3——必须在任何 Stores 写入操作之前。 安装 Stores 并不能保证目录为 V3（通过 blank 脚手架创建的网站初始版本为 V1）。通过只读的 Catalog Versioning API 进行检查：

curl -s -H "Authorization: Bearer $WIX_AUTH_TOKEN" -H "wix-site-id: $WIX_SITE_ID" \
  https://www.wixapis.com/stores/v3/provision/version

catalogVersion 的值为 V3_CATALOG（继续）、STORES_NOT_INSTALLED（安装 Stores，然后重新检查）或 V1_CATALOG（停止——不要写入任何内容，并参阅上文的单站点规则）。将结果记录在 setup/setup-verification.json 中。不要假设每次安装 Stores 后目录都是 V3，而跳过此检查。

导入前，在两种模式下都要清除默认演示目录。 全新安装的 Wix Stores（以及 wix-headless 的种子步骤）会预先向商店填入约 12 个占位演示商品和演示分类。如果不清除，它们就会与迁移的目录混在一起（原本干净导入的 100 个商品会变成 112 个）。安装 Stores 后，在导入之前或之后立即删除默认演示商品和演示分类，确保商店中仅保留迁移的数据（保留系统的 All Products 分类）。网站模式一节也要求执行同样的清理；默认的 management 模式同样适用，因为现在两种模式都从全新配置的 Stores 目录开始。

站点范围注意事项： 在某些站点上，Wix Stores/Categories 的站点级 API 会通过 wix-site-id 标头中的站点 metaSiteId 来限定范围；如果脚手架提供的 siteId 在调用 Stores 时返回 404/meta-site not found，请解析并使用 metaSiteId。

网站模式：使用 wix-headless 构建店面

仅当交付模式为 website 时运行此部分（即用户明确要求构建店面／网站／前端）。在 management 模式下，完全跳过此部分——导入完成后即结束运行。

wix-headless 仅为它自己创建的网站构建 JavaScript 店面；它无法将目标设为现有网站 ID。因此，在 website 模式下，应由它负责 CLI 脚手架搭建——不要先自行运行“无头网站创建”脚手架（否则会生成第二个空网站）。然后，RePlatform 会将迁移后的目录导入 wix-headless 创建的网站。

步骤：

1. 先进行只读迁移准备。 按照常规流程运行 discovery → mapping（含审核检查点）→ setup-discovery → codegen。此时不要创建网站，并将 WIX_SITE_ID 留空。
2. 将网站创建和店面构建交由 wix-headless。 调用 wix-headless 技能（Skill 工具，名称为 wix-headless；它从自己的 SKILL.md 开始，解析项目类型，并将新网站流程路由到 references/managed/CREATE.md），并提供店铺意图和品牌信息。它会创建一个安装了 Wix Stores 的新无头网站，搭建 Astro 店面，并完成构建和发布，生成一个可访问的 URL。它的演示数据填充操作具有幂等性，页面会在请求时读取实时目录。 告诉它使用 --site-template commerce 进行脚手架搭建。 它自己的创建流程会搭建 blank 模板，理由是设计由模型负责——这对于根据提示词进行构建是正确的，但不适用于此处：空白网站安装 Stores 后会使用 Catalog V1，而且无法转换（请参阅“无头网站创建”）。它的模板页面只是用于根据捕获的源站进行重新样式设计的脚手架，并非最终交付的设计。
3. 将该网站设为迁移目标。 从 wix-headless 项目的 wix.config.json 中读取 siteId，将其写入 config/wix.env 中的 WIX_SITE_ID，并保留 WIX_SITE_STRATEGY=new。用于导入的 Wix 身份验证必须能够写入该网站。然后，在写入任何 Stores 数据之前，运行“无头网站创建”中的目录版本检查——wix-headless 交接的网站也必须进行检查。
4. 删除演示目录后再导入。 由于 wix-headless 会填充演示产品／类别，先删除该网站上的演示目录，再运行生成的导入程序（仍须通过执行计划审批关卡），确保店铺中仅保留迁移的数据。店面页面会查询实时目录，因此发布后的网站会提供迁移后的目录；只有在必须重新生成静态路由时才需要重新发布。
5. 报告两个层面。 最终交接内容必须说明店面 URL，并且保留 catalog/data imported 与 website/homepage built 之间的区别（请参阅 rp-execute-import）。

如果运行环境中无法使用 wix-headless，请暂停并转为需要用户处理的状态（website 模式必须使用它来构建店面）；不要改为手动构建前端。

恢复

• 默认采用恢复模式。 如果工作流在迁移过程中停止，重新运行编排时会检查 orchestration/ 和各阶段产物（步骤 2），并跳转到第一个实质性缺口。不会无谓地重复工作。
• 绝不自动删除。 除非用户另有要求，否则保留现有产物。
• 从头开始须明确要求，并重做整个项目。 只有当用户明确要求重新开始时，才删除整个 migrations/<project>/ 目录，并从 discovery 重新运行。不要只清除个别阶段。

步骤 3：选择下一步

根据第一个关键缺口，查阅 resources/ 下对应的内部资源并进行相应处理：

• 缺少项目本地配置文件或缺少必填值：创建/更新 config/wix.env，并在确定源平台后创建/更新 config/source.<platform>.env； 一次询问用户一项缺失信息。
• 已知源数据获取决策，但尚未确定目标策略：确定 deliveryMode 和 WIX_SITE_STRATEGY；除非用户明确要求店面或前端，否则将 deliveryMode=management 作为默认值。
• 已有源和目标决策，但确定性预检尚未通过：运行预检契约并保存 orchestration/preflight.json。
• 尚不了解源系统：查阅 resources/rp-discovery/。
• 已有源架构，但没有获批的映射：查阅 resources/rp-mapper/。
• 已有映射计划，但缺少 mapping/review/mapping-summary.md：查阅 resources/rp-mapper/ 生成摘要，并暂停以供用户审核。
• 已有映射摘要，但尚未通过映射审核检查点：向用户展示 mapping/review/mapping-summary.md，请用户审核，并等待用户接受后再继续。
• 已有映射，但不清楚 Wix 端的要求：查阅 resources/rp-setup-discovery/。
• 已有映射和设置要求，但缺少导入代码：查阅 resources/rp-import-codegen/。
• 已启用安全模式或试运行，但缺少 execution/review/code-safety-review.md、该文件已过期、审核失败或尚未获接受：查阅 resources/rp-import-codegen/， 运行自动审核，修复发现的所有问题，重新生成产物，然后向用户展示通过审核的结果以供接受，再进入执行审批关卡。
• website 模式，代码已生成但尚无目标站点： 移交给 wix-headless 创建站点和店面，然后采用其 siteId（参见“网站模式：使用 wix-headless 构建 店面”），再进行设置/导入。
• 已有设置产物，但尚未验证：查阅 resources/rp-execute-setup/。
• 代码和设置均已就绪，所有必需的代码安全审核均已获接受，且 execution/execution-manifest.json 和执行审批均已准备就绪：查阅 resources/rp-execute-import/。
• website 模式，目录已导入： 确认店面已发布且正在提供迁移后的 目录；报告其 URL。在 management 模式下，导入完成后即表示流程结束——不要构建前端。

输出

仅简要回复以下内容：

• 当前项目路径
• 找到的产物
• 关键缺口
• 下一步的具体推荐技能
• 具体的下一步操作

防护措施

• 如果缺少发现阶段的产物，不要猜测源架构。
• 映射计划尚未生成前，不要生成导入代码。
• 设置验证和代码审核完成前，不要执行导入。
• 当通知静默生效时（规范 0012），若未验证静默状态，绝不能继续执行导入写入操作——静默失败时必须停止并等待用户处理，不得提供“仍要继续”的选项。不得根据策略/配置推断站点已静默；只有记录的验证状态才能作为依据。除非所有者明确要求，否则绝不取消静默。