wix-replatform

wix-replatform

wix-replatform 是用于可恢复源站到 Wix 迁移的精简协调器。 它会为当前阶段选择一个内部模块；不会把每个阶段的流程都放进自身上下文。

始终生效的约定

• 在检查或创建任何内容之前，先在 migrations/<project>/（或 REPLATFORM_MIGRATIONS_DIR）下解析当前项目。只有该项目的产物具有权威性。
• 每次运行开始时启动或恢复 resources/rp-telemetry/，并在到达终止状态时完成收尾。绝不手动编写遥测事件。
• 使用编排 JSON 和经过验证的阶段产物作为恢复依据。日志和聊天记录仅作为诊断上下文。
• 保护用户数据：以幂等方式写入，按源标识去重，恢复而不是重新开始，且绝不为一次迁移创建第二个目标站点。
• 绝不打印机密、包含机密的配置内容、令牌或凭据。仅报告键名及其状态（存在／空白／缺失）。
• 不得仅凭文字说明或单个产物就宣布迁移完成。终止完成状态由确定性路由器和聚合完成产物决定。

流水线

intake → destination → source inputs → preflight → (standard: discovery → mapping → codegen;
quick: adapter preflight → quick plan) → setup discovery → website handoff
→ safety review/approval → setup → import
→ storefront continuation (website only) → aggregate finalization

交付模式包括 management（仅后端）、website（仅前端）和 management_and_website（上述集成流程）。接受用户输入 both，并将其转换为 management_and_website，然后持久化规范值。

对于 deliveryMode=management，聚合收尾需要有效的后端导入记录。对于 deliveryMode=management_and_website，还需要当前的 website/completion.json，其中应包含已完成的截图审查、没有尚未解决的严重／高风险问题，以及发布证据。execution/completion-report.json 是后端记录，单独不能代表网站迁移已完成。

执行操作前先路由

每次新对话或恢复对话时：

1. 解析项目并初始化／加载其编排产物。
2. 运行 node skills/wix-replatform/scripts/orchestration-route.js <projectDir>。
3. 仅加载路由返回的 nextResource，然后遵循该资源的要求，直到其写入所需输出或遇到持久性阻塞。
4. 每次阶段边界之后重新路由。绝不凭记忆决定下一阶段。

如果产物格式错误、不完整、过时或未通过验证器，则将其生成阶段视为未完成，并路由到生成该产物的阶段。不要创建并行的替代产物。

按需加载的模块映射

路由器情况	加载
项目、交付模式、源模式或分组接收信息尚未确定	resources/rp-project-intake/
目标站点不存在、存在冲突，或需要创建／采用	resources/rp-destination/
需要源 URL／文件／配置／获取模式／凭据	resources/rp-source-inputs/
缺少确定性预检或预检受阻	resources/rp-preflight/
快速模式需要解析平台、端点预检、计划、提取或导入	选定的 resources/rp-quick-<platform>/
缺少源架构	resources/rp-discovery/ 及选定的源适配器
缺少映射或需要审查映射	resources/rp-mapper/
缺少 Wix 要求	resources/rp-setup-discovery/
缺少导入代码／审查，或内容已过时	resources/rp-import-codegen/
缺少设置验证	resources/rp-execute-setup/
缺少后端完成报告	resources/rp-execute-import/
仅前端工作，或集成式网站交接／构建／问题修复循环／发布回执未完成	resources/rp-website-continuation/
缺少聚合完成产物	resources/rp-execution-policy/

路由指定的资源就是该阶段的完整约定。对于无关阶段，不要加载源文件、机密、脚手架或店面流程。

交互策略

常规模式仅针对缺失的必填输入、确实存在歧义的当前项目，或强制要求的写入批准提问。除非某个模块另有规定，否则一次只问一个问题。

写入前，必须保留强制执行计划批准关卡。只读发现、映射、设置验证、代码生成和审查都应在此之前完成。

快速管理导入模式

当 managementImportMode=quick 时，只有在确定性来源探测识别出兼容平台后，才能选择平台适配器。快速模式是一种范围有限的公开数据导入：适配器的版本化 quick-mode.json 定义其来源路由、实体图、字段矩阵和排除项。快速后端分支不得运行 Agent 式发现、映射或项目专属代码生成。仍需执行目标端设置、应用安装、Catalog-V3 和通知安全检查、执行批准、共享写入运行时、交叉映射和完成情况核算。如果没有符合条件的适配器，应持久化记录不支持此模式的结果，并要求用户选择标准模式；绝不能静默回退。

只有在缺少/无效的必填输入、没有 API 的手动操作，或存在系统性故障/数据丢失风险时才暂停。暂停时必须持久化记录代码、证据、负责人和准确的解除阻塞操作；绝不能静默停止。

一键模式

用户明确提出要求时，记录 automationMode=one_click，并设置 source=user，然后应用以下规则。模式缺失，或记录为 deterministic_inference/prior_artifact 的 one_click 值，都属于常规交互模式，不得跳过任何检查点：

• 在一次分组请求中收集所有仍缺失的受理信息；之后不再因常规批准而暂停；
• 将映射和执行批准记录为 approved，并设置 decidedBy=agent；跳过暂停却未记录状态属于无效操作；
• 对于仅使用 CSV/文件的运行，由 Agent 验证并接受所需的样本预览；若用户未明确指定一键模式，则暂停以进行常规映射审查、样本预览验证和执行批准；
• 默认使用新的隔离站点，除非明确提供或已固定现有目标；根据发现的路由系列确定性地选择网站范围；
• 遇到 PATH/工具解析故障时，在操作员兼容的交互式登录 Shell 下重试；请求所需的浏览器/网络沙箱权限提升，并在认定受阻前重试；
• 停止前先尝试显而易见的恢复操作：PATH/工具故障时先使用匹配的 Shell，然后对受沙箱限制的浏览器或网络/API 故障进行所需的权限提升并重试；
• 持续执行所选交付内容直至完成。在 management_and_website 模式下，这包括前端构建、构建后差距分析、有限次数的修复循环和发布回执；如果用户在受理时选择了改版，还包括单独的克隆后改版审查；
• 交付前，重新进行路由。一键运行只有在生成 completion/migration-completion.json 时才算 completed，或在存在带类型的持久化阻塞项时才算 blocked。

从 PATH 或工具解析故障中恢复时，使用操作员兼容的本地 Node/Yarn Shell。特定于机器的 Shell 路径只能写入本地且已从 Git 排除的 Agent 说明中。

仓库本地交互式 Shell 约定： 首次尝试出现 PATH/工具解析故障，可能意味着命令是在一个普通的非交互式 Shell 下运行的，该 Shell 从未加载操作员的 Node/Yarn 配置文件。根据本地环境或已从 Git 排除的 Agent 说明，找到操作员兼容的登录 Shell，验证它可执行，然后通过该 Shell 以交互式登录模式重试完全相同的命令，以加载能够解析 node/yarn/npx 的配置文件。不要在此公开技能中硬编码特定于机器的 Shell 路径。只有兼容 Shell 重试本身失败时，才升级为持久化阻塞项。

防护措施

• 切勿绕过验证器、审批状态更新、已验证的通知静音设置或 Catalog-V3 门槛，来让某个阶段看起来已完成。
• website 仅指前端；management_and_website 指集成式后端和前端迁移。切勿将集成迁移目标交给前端技能，也不要在该模式下创建第二个前端站点。
• 如果 wix-headless-replatform 不可用，切勿手动实现店面；请记录阻塞事项，并注明所需的确切运行时能力。
• 在管理模式下，完成设置发现后仍须生成 website/handoff.*，以便后续店面可以启动，而无需重复进行后端发现。