wix-headless-kit

Wix Headless Kit

基于已交付并验证的代码构建 Wix Headless 网站，而不是自行编写集成。 每个垂直领域都会交付集成代码本身——类型化数据层、钩子、组件、页面和种子脚本，均已确保正确。在能够运行这些代码的技术栈上（Wix 管理的 Astro、任何 React 项目），代码可直接部署，Agent 的工作也就缩小为品牌、布局、文案和接线。 在无法运行这些代码的技术栈上（没有打包器的静态网站、使用其他语言的服务端渲染应用），同一份代码就是参考实现：它的 REST 对应版本用于部署浏览器端功能，而其中编码的规则就是 Agent 移植时要遵循的内容。无论哪种情况，决策都已体现在代码中；不要重新争论这些决策。

适用范围。 本工具针对 Wix 管理的 Astro 进行了优化，每个垂直领域只交付一种解决方案形式。如果需求没有与之冲突，就按原样使用。当需求要求的功能无法用该形式表达时，或网站建成后工作转为管理或扩展网站时，应使用 wix-docs 和 wix-manage，而不是在这里变通。

模型

• 已发布的代码就是实现。 每个垂直领域的实现都在仓库的 wix-headless-templates 技能中（skills/wix-headless-templates/<vertical>/），而不在本技能的 文件夹中。运行 node <SKILL_ROOT>/install/templates.mjs 可查看该技能的位置：如果它与本技能并排安装（冷启动 时会同时安装两者；插件可能不会），则位于相邻文件夹 <SKILL_ROOT>/../wix-headless-templates/；否则会一次性获取到 <SKILL_ROOT>/templates/（即克隆该技能 仓库，第二个仓库）；以下每个脚本都会以相同方式解析它。本文档中的每个 templates/... 路径都相对于 打印出的根目录——如果相邻目录存在，本技能中就没有 templates/ 文件夹。 该文件夹会随项目保留（只有组合后的 project/ 脚手架不会放入其仓库），因此后续会话读取的是项目构建时所用的版本。每个垂直领域包含：
  • app/ — 与框架无关的核心（TypeScript）：返回纯可序列化 DTO 的数据层（图片解析为 https URL，价格预先格式化）、React Hooks，以及不处理路由的无头组件。适用于 Astro islands、Vite SPA 和 Next。
  • app-astro/ — 精简的 Astro 覆盖层：通过核心获取数据并将 DTO 传递给 islands 的 SSR 页面，且已预先配置好由所有者编辑的商品页 SEO。
  • seed/ — 构建时 REST 种子脚本（输入纯数据计划，输出创建的内容）及其 SEED.md 合约。
  • INSTRUCTIONS.md — 该垂直领域的操作指南：文件地图、构建内容、硬性规则。
  • project/ — 将该垂直领域组合到 Wix CLI 的空白 Astro 脚手架中，并包含其锁文件：这是新站点通过 wix create 复制的内容，因此第一个垂直领域无需解析即可安装。
• 统一的认证接缝。 所有已发布代码都通过 src/wix/sdk.ts 调用 Wix：在 Wix 托管的 Astro 上，认证是隐式提供的（无需客户端，也无需 id）；在任何其他 React 配置中，同一文件会使用 src/wix/config.ts 中的公开客户端 id 运行手动访客客户端。部署步骤会完成配置——无需手动接线。
• 数据保持原样；呈现由你负责。 数据层、Hooks 和购物车界面按原样接好——绝不要改写其内部实现、通过 API 路由重新路由，或重新推导请求格式。如果需求涉及它们未表达的内容，请阅读负责该内容的已发布文件，并通过 wix-docs 确认合约；绝不要根据生成的 SDK 类型、包文件或 node_modules 推断。普通调用者有权执行的操作应放在新的数据层函数中。特权操作应放在经过验证的服务端端点中——参见 templates/shared/CUSTOM_OPERATIONS.md。不会随附呈现层：垂直领域的 INSTRUCTIONS 会列出你要基于已发布 Hooks 自行设计和实现的界面，并为每个界面提供带有其合约的骨架（对于 storefront：shop 和 PDP 页面及其 islands，还有主页）。
• 绝不要依据训练数据或记忆编写 Wix API。 无论是 URL、路径、版本、标头、字段名、筛选键还是请求体，都不例外。你要编写或调用的每个 Wix 请求——无论在前端、种子脚本还是构建时读取站点数据——都必须来自此处安装的官方 Wix 技能、它们首先部署的代码，或者在它们未涵盖该调用时，来自通过 wix-docs 查阅的官方 Wix 文档。先在那里阅读，再编写调用。 **每次请求前的检验：**本会话中你运行的文件读取或文档搜索的输出里必须包含确切的路径和请求体，并且要从该输出中复制。其他任何内容都是记忆：输出在调用出现前就被截断的文件、你记得早先读过的来源，或在已找到的调用基础上改动部分内容后构造的调用。猜测的调用若返回 400 或空结果，并不代表接近答案；这正是本规则要防止的失败。接着尝试其他变体仍然是在猜测，而对未通过检验的失败调用得到空回复或错误回复，只能说明调用本身有问题，不能说明站点的情况。调用尚未确认时，要让错误保持可见：不要使用 2>/dev/null，也不要使用 | echo。已发布代码经过真实站点测试；看起来相似的请求体可能什么也返回不了，而且 API 很少会解释原因。
• 绝不模拟；出错时明确失败；通过 Wix 完成购买。 使用实时数据或如实展示空状态；显示错误，不要吞掉错误；结账和购买始终通过 Wix 重定向会话完成。
• 根据计划部署可选能力。 垂直领域可以选择启用共享能力，而无需复制敏感代码。对于普通文件上传，在计划中添加一个命名的 capabilities.mediaUpload.policies 条目；Fast 会一次性提供客户端辅助函数、Astro 端点、依赖项和生成的策略模块。选择前请阅读 templates/shared/CUSTOM_OPERATIONS.md。Agent 会将辅助函数接入商品 UI；绝不会编写或扩大端点的权限范围。对于全站搜索（带建议的页眉搜索框，以及一个涵盖已部署垂直领域中的商品、服务、帖子和活动的 /search?q= 页面），添加一个 capabilities.siteSearch 条目；Fast 会一次性提供其数据层、stores、Hooks、组件和搜索页面。启用该能力意味着种子步骤会在站点上安装 Wix Site Search 应用（install: true；运行内容种子之后执行该能力的 seed/install.mjs）——安装后约半分钟内索引就会填充。操作指南：templates/shared/capabilities/site-search/INSTRUCTIONS.md。

运行流程

全程需要：Node ≥ 22.12（Astro 7；只有 Wix CLI 可在 20.11 上运行）、git、已登录的 Wix CLI（npx @wix/cli@latest whoami； npx @wix/cli@latest login 是设备代码流程：向用户显示 URL 和代码，绝不要将令牌读入上下文），以及与此技能一同安装的两个配套技能 wix-docs 和 wix-manage。node <SKILL_ROOT>/install/bootstrap.mjs 会检查 CLI，并在尚未登录时运行登录流程；冷启动页面 https://www.wix.com/skills/headless-cold-start/headless-kit.md 会让一台不具备上述任何条件（包括这些技能）的机器完成这些准备。在已有 wix.config.json 的文件夹中，先运行 node <SKILL_ROOT>/install/context.mjs：若缺少 .env.local，它会运行 wix env pull，并打印文件夹的结构（folder.shape，即第 3 步中的各个情况及其对应的 next），以及项目具备的两个身份——部署站点（来自配置，wix release 的目标）和内容站点（来自环境，SDK 客户端以该站点的身份运行，其应用的控制面板用于管理业务）。除迁移预览（guides/migration.md）外，它们是同一个站点；在迁移预览中，环境变量指向正在迁移的站点。此处的每个脚本都会读取该上下文；绝不会仅根据配置猜测调用的目标站点。接着，获取一次随附代码：node <SKILL_ROOT>/install/templates.mjs。它会打印文件夹路径；下方的 templates/… 路径都是相对于该文件夹，而非默认相对于 <SKILL_ROOT>。 node <SKILL_ROOT>/install/check.mjs 会说明技能或其模板是否有更新版本，并打印更新命令；它不会更改任何内容。

整个运行过程中，每一步都要确保站点正常运行，让用户能在站点逐步完善时随时试用。只有站点所有者才能完成的步骤，绝不能阻碍流程：草拟的内容会直接上线；任何涉及收款的功能都会先进入 Wix 的结账流程，之后才会连接支付功能。将所有者需要完成的步骤及其链接放在收尾部分，作为用户可以自行完成或请求协助的后续步骤。

整个运行过程中：如果用户要求向 Wix 发送反馈、表达不满或感到沮丧，或者运行过程中遇到任何阻碍——包括任何本不该花这么多轮才能解决的问题，无论最后是否报错（令人困惑的错误、文档缺失、必须重新运行的种子数据、随附文件未能满足需求、需要阅读源代码才能理解的操作手册条目、需要通过试错才能弄清的调用、必须自行想出的变通办法、缓慢或不稳定的步骤、平台限制）——都应根据 <SKILL_ROOT>/guides/feedback.md 提出代为向 Wix 反馈。默认主动提出，而不是等用户要求；只有得到明确同意后才能发送，绝不自动发送。第 5 步以相同的自检结束。

1. 确定技术栈。 默认使用 Wix 管理的 Astro——除非用户指定其他框架，或目录中已有框架，否则就采用它。然后根据已提供代码可在哪种技术栈中运行来决定：

   • React（Vite、Next 等）可以运行所有已提供代码——数据层、钩子和组件：--stack react。Agent 自己的文件可以使用 JS；已提供的文件是 TypeScript，在 JS 项目中无需改动即可构建——切勿手动移除这些文件；如果需求要求任何地方都不能使用 TypeScript，请说明已提供的代码无法满足要求，并在继续前征求确认。 指定的框架要先使用其自身命令搭建脚手架 （npm create vite@latest 等），然后在该文件夹中执行第 3 步。
   • 其他打包型 JS 框架（Vue、Svelte、Solid、纯 Vite）：数据层和与框架无关的存储可以运行（src/wix/ 中不含 React），React 钩子和组件则不适用：--stack lib。Agent 将绑定这些存储，并根据相同的契约编写该框架的组件。
   • 没有打包器，或使用其他语言——静态网站（纯 HTML/CSS/JS）、服务端渲染应用（Flask、Laravel、Rails 等）：参考模式（见下文对应章节和 <SKILL_ROOT>/guides/reference-mode.md）。app/ 中的内容都不会部署；REST 层会为浏览器端部署，服务端则为其读取操作移植该层。

   Wix 托管的方式，以及各技术栈要在此处发布所需的条件。 wix release 会上传 wix.config.json 中指定的文件夹（site.outputDirectory），并将其作为文件提供服务——没有 SPA 回退、目录索引或重写规则：/ 和真实文件可以解析，直接加载或分享干净的客户端路由时则会返回 404。服务端代码只能以 Cloudflare Workers 构建的形式运行，并通过 outputDirectory: { client, server } 声明。

   • 托管式 Astro 是 Wix CLI 搭建脚手架时使用的技术栈：Wix Astro 集成（@wix/astro，环境认证）、托管适配器（@wix/astro-wix-hosting-adapter，Workers 构建）、用于已提供组件的 React 18 及 astro.config.mjs 中的 integrations: [wix(), react()]、adapter: wixHostingAdapter()、output: "server"、security: { checkOrigin: false }，以及包含 static.wixstatic.com 的 image.domains。未通过 CLI 创建的 Astro 项目不具备这些配置；部署前请添加，否则网站将无法为所有路由提供服务。当前主版本的集成（@wix/astro 3，与本技能中的模板一致）要求使用 Astro 7：较早主版本的项目必须先升级到 7，或作为 React 宿主接入。
   • React 和其他打包器会将自身构建产物作为文件发布。因此路由要么使用哈希路由，要么为每条路由生成一个 HTML 文件，并通过文件名链接——必须在编写第一条路由前确定；传给 Wix 作为返回目标的任何 URL，都必须是托管端能够提供服务的 URL。请直接加载深层 URL 进行验证，不要从 / 开始导航。
   • 构建产物为服务端的框架（Next、Nuxt、Remix、SvelteKit 等）只能通过静态导出（文件形式，适用上文规则）或通过 outputDirectory: { client, server } 进行 Workers 构建来发布；否则就采用可自托管方式，并在结账流程能够返回之前，将其域名添加到 OAuth 应用的允许域名中。
   • 静态网站（无构建）：outputDirectory 指向页面所在文件夹；路由由页面和查询字符串 slug 组成（参考模式）。

2. 播种计划。 播种内容由需求说明决定；本次运行创建的网站打开时始终会有内容：

   简述	方案
   以任何形式提供内容：CSV、JSON 或电子表格、提示词中的列表、PDF 价目表、包含照片和文本文件的文件夹、当前目录的链接，或任何列出内容的资料	这就是方案：按照 templates/shared/SUPPLIED-CONTENT.md 和该垂直领域的 SEED.md（“Supplied content”），将内容映射到 plan.json；每个条目、名称和价格都必须原样保留，使用其图片，不添加其他图片
   描述内容但不列出具体项目（“一家售卖手工浇注蜡烛的商店，共四款”“按三个类别分组的十二个常见问题”）	按照该垂直领域的 SEED.md 根据描述起草方案（仅为此读取该文件；将 INSTRUCTIONS.md 留到步骤 4）
   没有提及内容（“帮我建一家商店”）	对于本次运行创建的网站（新建、接管、仅配置），按照该垂直领域的 SEED.md 起草方案，让网站打开时已有内容——由 Agent 自行决定演示内容，无需询问；并在结束消息中说明这些是占位内容，以及所有者在哪里编辑。对于本次运行前已存在的网站：不添加种子内容；其内容由网站自行管理

   现有网站没有自己的方案：当简述中通过 id 指定网站，或文件夹的配置中指定网站时，网站已保存内容；前端会读取现有内容（步骤 3 的关联路径），只会添加简述中提供或描述的内容。

3. 在项目文件夹中设置项目——无论文件夹为空还是磁盘上已有项目，都进行一次确定性调用；具体操作由文件夹中的若干文件信息决定：wix.config.json、其 site.outputDirectory、.env.local 中的迁移变量、package.json、index.html（位于根目录或 public/ 中）、src/pages/。node <SKILL_ROOT>/install/context.mjs 会打印它读取的结构以及相应的 next。简述就是指令：它要求启用的功能会安装到文件夹指定的网站上，无需再次询问。只有在操作会为已有网站的文件夹新建第二个网站，或似乎需要清理时，才询问。

   node <SKILL_ROOT>/install/setup.mjs --vertical <vertical>[,<vertical>…] [--plan plan.json] [--business-name "<Brand>"] [--stack <stack>]
   

   在这一次调用中列出简述需要的所有垂直领域（带会员账户的商店为 storefront,members）：第一个垂直领域的模板会搭建项目；其他垂直领域会在同一次调用中部署，因此一次安装即可涵盖全部垂直领域。安装开始后再添加垂直领域，则需要进行第二次安装。

   文件夹内容	类型	设置操作	设置时是否播种
   空文件夹，或零散文件（CSV、简介）	empty → 创建	在此使用该垂直领域组合模板执行 wix create；--business-name 用于命名网站	是，使用 --plan
   有前端，但没有配置（根目录下有 package.json 或 index.html：某人创建的 Astro、Vite、Next、纯 HTML 项目）	project → 接入	在原位置运行 init，为其创建一个新的空网站，然后部署；必须指定第 1 步中的 --stack；在 Wix 托管环境中，按该技术栈的要求准备项目（第 1 步），可在此之前或之后完成	是，使用 --plan
   有配置，其 .env.local 声明了正在进行的编辑器迁移（EDITOR_MIGRATION_STATUS=ACTIVE），无论是否附带下载包中的空白 Astro 入门模板	migration → 迁移	将随附代码迁入入门模板（或围绕纯配置使用组合模板），部署时将迁移后网站的应用用作客户端，然后开始安装；ready_for_brand_layer 会将 mode: "migrate"、父级 siteId 和子级 deploySiteId 列出（guides/migration.md）	永不播种
   有配置，没有前端	config-only → 拒绝	网站已存在，但还没有前端：下方的 attach.mjs 会从配置中获取网站，复用其托管环境，搭建脚手架并部署。该配置是 init 留下的，而 init 总会创建一个网站：这个网站是为本次运行创建的，且为空	是：像创建网站一样起草计划，然后运行 attach.mjs --plan
   有配置和前端（有 package.json，或文件夹中有 site.outputDirectory 指定的 index.html）	wix-project → 拒绝	迭代：绝不搭建脚手架、运行 init 或重新播种。deploy.mjs <vertical…> --stack <stack> 会添加解决方案（客户端 ID 来自 .env.local，配置作为后备），然后安装一次：运行 node <SKILL_ROOT>/install/install.mjs（如果 node_modules 已满足锁定文件要求，则无需操作）；更改通过编辑文件完成；然后发布	否
   有配置、package.json、public/index.html，且没有 src/pages/（通过拖放流程发布、位于 Wix Dev Machine 上的网站）	static-in-astro → 拒绝	页面保留为 public/ 中的纯文件：deploy.mjs <vertical…> --stack static --out public 会将 REST 层放入 public/js/wix/，并在原处接入页面（引用模式），不会添加 Astro 页面；运行 build 再运行 release 即可发布，URL 保持不变	否
   有配置和 CLI 的空白 Astro 入门模板，且没有自有内容（wix-astro-blank，仅含空白模板的依赖包：Dev Machine 上从未发布的网站、纯 wix create）	blank-starter → 拒绝	对配置中的网站运行 attach.mjs --business-name <brand> --vertical <v…> [--plan plan.json]：该垂直领域的组合模板会替换入门模板（包括其锁定文件），安装和播种会在后台启动；运行期间构建品牌层	是，使用 --plan：该网站是为本次运行创建的，且为空，除非 read-site.mjs 显示其中有内容
   有配置、根目录下有 index.html，没有 package.json（通过拖放流程发布并下载的网站）	published-static	使用配置中的网站，不运行 init：site/ 成为上传内容，REST 层部署到 site/js/wix/；next 会提示迁移页面、样式和资源；发布后 URL 保持不变	否

   未被任何行列出内容的文件夹属于 wix-project：仅填充路径——绝不搭建脚手架、运行 init、重新播种或删除；部署、编辑、发布。错误判断只会让运行变慢，绝不会损害用户的工作。 由谁决定是否填充种子数据：取决于网站的来源，而不是需求说明的措辞。 本次运行创建的网站按构造就是空的，因此总会填充种子数据——如果需求说明提供或描述了任何内容，就使用其中的内容；否则，Agent 会按照该垂直领域的 SEED.md 编写演示内容，无需等待用户要求，让网站打开时就有内容可看。本次运行创建的网站是指：由 setup 创建的网站（create、adopt），或文件夹中只有 wix.config.json、没有前端的情况（仅配置——init 留下的就是配置，而且 init 总会创建网站；attach 会报告 siteOrigin: "init"）。运行开始前就已存在的网站——需求说明中按 id 指定的网站、通过 --site 指定的网站、已关联到该网站的项目，或迁移的父网站（attach 会报告 siteOrigin: "given"）——包含的内容并非本次运行创建：只填充需求说明提供或要求添加的内容（attach.mjs --plan plan.json，或从项目根目录运行垂直领域的种子模块：node <templates>/<vertical>/seed/seed-<vertical>.mjs plan.json，其中 <templates> 是 install/templates.mjs 打印的文件夹），绝不为其编造内容。“为我的玩具店开一家新店”描述的是业务，而不是要添加的内容：不会填充任何数据。无论哪种情况，都要先读取现有网站（seed/read-site.mjs）。种子数据按名称追加且具有幂等性；绝不会删除或覆盖网站上的任何内容，结果中的 preexisting[] 会列出已存在的内容名称。

   • 需求说明按 id 指定了网站 → 不要调用此命令：读取 <SKILL_ROOT>/guides/existing-site.md 并遵循其中的说明（先读取网站，再运行 attach.mjs；它会针对指定的网站执行 setup 的操作，且只有通过 --plan 才会填充种子数据；该指南说明，只有当需求说明提供或要求添加内容时才传入此参数；其中也介绍了自托管和已在磁盘上的项目）。

   --vertical 为必需参数，用于选择要部署的随附代码以及要运行的种子模块。ready_for_brand_layer 事件会给出 mode（create、adopt、migrate、published-static）、shape、技术栈，以及该技术栈对应的 next，包括发布方式。

   setup 使用 --skip-git 搭建脚手架：它会自行组合各个步骤，并将版本控制留给你或外层仓库，因此不会创建脚手架通常会生成的 git 仓库和初始提交（否则，如果项目位于某个仓库内，就会成为嵌套仓库 gitlink）。

   项目会创建在当前目录中——入口流程要求你在此目录中操作，该目录已包含安装好的 skills——因此项目自包含，之后在其中打开的新会话也能找到所有内容。如果文件夹中已有脚手架要写入的文件，它会拒绝执行。对于必须保持当前文件夹原样的情况，--subfolder 会在一个以业务命名的新文件夹中创建项目；此时 skills 位于项目上一级目录。

   它每行输出一个 JSON 事件，并在约 35 秒内返回：从垂直领域组合模板搭建项目（wix create 会复制该模板：代码及其锁文件会随脚手架一起到位），部署文件夹中仍缺少的内容（在 package.json 中补齐代码导入的所有依赖），然后启动两个分离的后台任务——安装依赖（install/install.mjs：如果 node_modules 已满足锁文件要求，则不执行任何操作；如果目录已存在，则运行 npm install --ignore-scripts；否则运行 npm ci --ignore-scripts || npm install --ignore-scripts）和填充种子数据——其日志和完成标记都包含在事件中。最终的 ready_for_brand_layer 事件会包含项目目录、siteId、已准备好的仪表板链接，以及两个标记。转发重要事件。遇到 error 事件时，按照下文的手动操作流程仅恢复该步骤，然后继续。 恢复某个步骤，或稍后补充解决方案：这些部分都能从项目根目录独立运行 — node <SKILL_ROOT>/install/deploy.mjs <vertical…> --stack <stack>（客户端 ID 从 wix.config.json 中读取），运行一次 node <SKILL_ROOT>/install/install.mjs（绝不可同时运行第二个 npm install：两个 npm 在同一个 node_modules 中会发生竞争，并互相重复对方的工作；setup 已经启动了一个 — 等待其标记文件），以及按照对应 vertical 的 seed/SEED.md 运行种子模块。 现有项目的代码更改，只有在发布（步骤 5）且线上 URL 显示更改后才算完成 — 不是开发服务器或本地构建显示更改时。管理更改（针对网站的 recipe）无需发布；前端会实时读取。

4. 在安装完成的同时设计并构建页面——在 ready_for_brand_layer 事件提供的项目目录中，按照该垂直领域的 INSTRUCTIONS.md 操作：设置 @theme 令牌，为界面外层应用品牌样式，并基于已提供的钩子自行实现该垂直领域的创意页面——对于店面，包括产品卡片和网格、商店页面、PDP 页面和首页——设计应符合需求说明，而不是照搬参考组件。现在（而非更早）阅读 INSTRUCTIONS 和共享基础规范——templates/shared/DESIGN.md + templates/shared/CONTENT.md；这些规范仅从这一步开始适用。钩子和 DTO 契约已内嵌其中，因此不要打开已提供的文件本身。 对于已有前端，只做最低限度的修改。 如果本次运行接入的是之前就已存在的页面（例如交付的 mock、采用的现有网站或已发布的静态网站），只做让它们正常工作所需的最少修改：将页面显示的每个控件连接到已提供的代码，并且只添加控件正常工作所必需的内容。只有当需求说明提出要求时，才添加该垂直领域提供的其他功能；并在结束消息中列出这些功能。 如果需求说明需要已提供代码不支持的核心操作，请在编写之前阅读 templates/shared/CUSTOM_OPERATIONS.md。选择一种文档记载的实现路径并予以实现；不要逆向分析 SDK 内部实现。

5. 两个后台任务都已完成时——安装任务的标记文件 .install-exit（内容为 0）和种子任务的标记文件 .seed-exit 均已存在——验证种子任务成功（.seed-exit 内容为 0；seed-result.json 中包含供摘要使用的创建数量；如果非零，请阅读 seed.log 并手动重新运行种子模块）。只有在设置阶段启动了种子任务时，这两个种子文件才会存在（attach 运行不会启动种子任务，只等待安装标记）。如果你自行运行了 seed-store.mjs（adopt、iterate 和 published-static 运行，以及 reference 模式），则无需等待标记文件：进程的退出代码就是结果，其标准输出是 JSON；等待进程完成（以前台方式运行，或对其 pid 执行 wait），而不是等待文件。然后构建并发布一次（托管模式），具体按 ready_for_brand_layer 事件中所述的 next 步骤，依据技术栈执行：Astro → npx @wix/cli@latest build，然后 npx @wix/cli@latest release；React 或其他打包器 → 使用项目自己的构建命令，然后通过 npx @wix/cli@latest release 发布 wix.config.json 中指定的构建目录（深层 URL 必须能直接返回 200，见步骤 1）；静态网站 → 仅执行 release。如果安装失败，再运行一次，然后构建。不要在流程中途构建并发布；后端内容会在运行时获取，因此重新发布不会“刷新”已填充的种子数据。只有网站发布成功后，本次运行才算完成——结束时提供线上 URL 和控制面板链接 https://manage.wix.com/dashboard/<siteId>（使用 ready_for_brand_layer 事件中的 siteId：迁移预览中，该链接指向已迁移网站的控制面板，发布 URL 指向预览网站，原网站保持不变；用户批准后，下一步是在 Wix CLI 中完成迁移——这三点都要说明）。根据 wix-manage 配方 references/domains/domain-search-purchase-and-connect.md（与此技能一起安装；否则使用 https://www.wix.com/skills/wix-manage/references/domains/domain-search-purchase-and-connect.md），告诉用户如何为网站绑定自己的域名：可以通过 Wix 购买，也可以使用已有域名。如果网站通过托管结账收款（购物车、付费预约或租赁、门票、套餐、捐赠），且没有信息表明已设置付款方式，则说明在设置完成前，访客结账时会看到什么：“我们无法接受在线付款。如需获取订单帮助，请联系我们。”——并提供两个用于解决此问题的链接：接受付款 https://manage.wix.com/dashboard/<siteId>/wix-cashier/payments（连接付款方式；免费及到店付款流程只需启用“手动付款”）和升级套餐 https://www.wix.com/upgrade/website?metaSiteId=<siteId>（在线付款需要高级套餐）。这两项都由网站所有者操作，并非网站缺陷。如果本次运行从网站所有者自己的页面开始，请指出这些页面承诺但发布后的网站无法提供的功能。直接从 wix release 输出中原样复制线上 URL——绝不要凭记忆重新输入（子域名输错会让用户遇到 404）。完成之前，按照 guides/feedback.md 对整个会话进行反馈自检：凡是本可以减少交互轮次的情况——包括你悄悄自行恢复的问题——都可作为反馈信号；如果有符合条件的情况，在交付链接时主动提出转达，并且只有在对方明确同意后才发送。

参考模式——静态站点，或使用其他语言的服务端渲染应用

已发布的数据层还以 REST 层的形式通过 fetch 实现了一遍，供无法运行 app/ 的技术栈使用：没有打包器的静态站点，或使用其他语言的服务端渲染应用（Flask、Laravel、Rails）。REST 层用于部署浏览器端；服务端则移植其读取逻辑。若步骤 1 确定使用上述某种技术栈，请在步骤 3 之前阅读 <SKILL_ROOT>/guides/reference-mode.md：其中介绍了相关机制（site/ 的布局及 setup 在其中的作用、浏览器端与服务端分别运行的内容、可自托管来源的 OAuth 允许列表、预渲染输出），以及如何结束此类运行。对于公共站点，使用托管的 Astro 仍是更好的选择；结束时请说明这一点。

如果完全没有可用的机器，或者你所在的环境阻止了安装、CLI 或登录，请阅读 <SKILL_ROOT>/guides/api-run.md：该文档逐步介绍了同一运行过程，内容对应脚本发出的 Wix API 调用，以及此技能旁边用于定义契约的文件。

垂直领域

速查表。根据第一列判断需求；如果其中提到了此处未列出的 Wix 产品或功能、可能符合两行，或者听起来像是此技能未提供的功能（会议、礼品卡、忠诚度、群组），请阅读 <SKILL_ROOT>/guides/capabilities.md：其中介绍了每种 Wix 产品、涵盖的内容、此处由哪个垂直领域提供，以及未提供的功能。

用户想要……	垂直领域	操作指南
在线商店：商品、分类、变体、购物车、结账	storefront	templates/storefront/INSTRUCTIONS.md
预约／课程：服务、时段、员工、预订、结账	bookings	templates/bookings/INSTRUCTIONS.md
租赁：按小时或天租用的房间、车辆、装备，由客户选择租期并结账	rentals	templates/rentals/INSTRUCTIONS.md
博客：文章动态、分类／标签、富内容文章页面	blog	templates/blog/INSTRUCTIONS.md
结构化内容集合（目录、菜谱、列表），页面根据架构设计	cms	templates/cms/INSTRUCTIONS.md
任何可由访客填写的表单：联系／咨询、注册、申请、问卷——根据实时架构呈现	forms	templates/forms/INSTRUCTIONS.md
活动：活动列表、活动页面、免费 RSVP、通过托管结账售票	events	templates/events/INSTRUCTIONS.md
会员账户：应用内自定义登录／注册、受限页面、账户页面	members	templates/members/INSTRUCTIONS.md
作品集／展示：项目集合、带媒体画廊的项目页面	portfolio	templates/portfolio/INSTRUCTIONS.md
会员／订阅方案：定价页面、方案详情、托管购买	pricing-plans	templates/pricing-plans/INSTRUCTIONS.md
餐厅：带照片的菜单、在线点餐、餐桌预订	restaurants	templates/restaurants/INSTRUCTIONS.md
常见问题：按类别分组的问题、搜索、可展开的答案、每个问题对应一个链接	faq	templates/faq/INSTRUCTIONS.md
捐款：活动页面、目标进度、通过托管结账进行一次性和定期捐款	donations	templates/donations/INSTRUCTIONS.md

垂直领域可以组合：跨越多个领域的需求（例如带博客的餐厅、带会员账户的商店）应在设置调用中列出所有领域（--vertical restaurants,blog），这样一次安装即可覆盖；每个垂直领域的种子数据都会按各自的方案运行。对于已构建的项目，在项目根目录运行 node <SKILL_ROOT>/install/deploy.mjs <vertical…> 添加一个垂直领域，然后运行一次 npm install，再运行其种子数据。与任何已提供的垂直领域都不匹配的需求没有现成代码：用一行说明这一点，然后通过 wix-docs 根据 Wix API 参考构建（先搜索，再查看方法页面），遵循其他所有调用相同的规则，并使用同一项目和技术栈；如果有最接近的已提供垂直领域，则从它开始（guides/capabilities.md 会说明是哪一个）。