wix-headless

Wix Headless

此技能将 Wix 业务服务连接到 Wix Headless 前端。它的核心任务是配置 Wix 后端：推断所需功能、安装 Wix 应用、为后端填充初始内容，并生成 SDK 集成指南，说明如何从前端调用 Wix。

前端相关工作取决于项目类型和操作：

• 仅后端（自我管理、stripe，或由托管模式执行的“仅设置后端”）——该技能会将 SDK 指南作为最终输出；前端、构建和托管由宿主负责。
• 托管式创建 / 连接——该技能也负责前端：搭建新项目（创建），或将 Wix 接入现有项目（连接）；使用同一份指南将其连接到后端，完成构建并发布到 Wix。（没有 Designer 或模板库——前端会根据意图临时构建。）

在仅后端运行中，该技能不负责项目搭建。 如果工作需要前端，请根据用户意图搭建前端——框架和结构由提示词决定；该技能负责 Wix 后端以及生成 SDK 指南，说明如何从现有前端调用 Wix，而不是选择或生成应用。stripe 运行通常就是如此：通过 Stripe Projects 配置项目（凭据写入 .env——参见 stripe/AUTHENTICATION.md），该技能配置后端并生成指南，之后根据 stripe/DEPLOYMENT.md 完成线上网站的最终部署；而前端则由宿主根据意图搭建并接入。

项目类型

除身份验证和部署外，该技能在所有项目类型中的行为都相同；身份验证和部署配置分别位于 references/ 下按类型划分的文件夹中：

项目类型	托管方式	身份验证和部署配置位置
managed	Wix 基础设施（由 Wix 维护）	references/managed/
self-managed	用户自己的主机（待定）	references/self-managed/
stripe	用户自己的主机，通过 Stripe Projects 配置	references/stripe/

其他所有内容——Discovery、Setup、Seed 和 SDK 交接——均与项目类型无关，并使用“提供的身份验证机制”这一说法，而不指代任何特定方法。

确定项目类型

在 Discovery 之前确定类型，按以下顺序判断——遇到第一个可以确定类型的条件后即停止：

1. 调用方提供。 如果宿主 / 调用方传入了项目类型（managed | self-managed | stripe），则使用该类型。显式指定的值始终优先。
2. 根据项目标记检测（磁盘上）。 只读检查工作目录：
   • stripe——.env 中包含 WIX_WIX_CLIENT_ID / WIX_WIX_CLIENT_SECRET / WIX_WIX_METASITE_ID（或纯 WIX_* 回退值）。这是 Stripe-Projects 的特征。
   • managed——Wix CLI 项目：存在 wix.config.json 或 .wix/ 目录，或 package.json 中包含 @wix/cli / @wix/astro。
   • self-managed——磁盘上存在前端项目（例如包含打包器 / 框架的 package.json），但既没有 Stripe .env 特征，也没有上述 Wix-CLI 标记。
3. 根据用户意图检测。 如果无法从磁盘确定，则阅读提示词：
   • managed——“managed”、“host on Wix”、“Wix-hosted”、“deploy to Wix”、“wix release”。
   • stripe——“stripe projects”、“I added Wix via Stripe”，Stripe-Projects 上下文。
   • self-managed——“self-hosted”、“my own host”，指定非 Wix 主机，或“I'll deploy it myself”。
4. 询问。 如果没有相关标记或标记相互冲突，请询问用户适用哪种类型——不要猜测。

将确定的类型暂存；它用于选择 <TYPE_DIR>（参见路径解析）。请注意，self-managed 仍待定——一旦确定为该类型，身份验证步骤就会停止，并显示明确的“尚未接入”错误。

确定操作（仅限 managed）

create/connect/iterate 仅限 managed。对于 managed，先按意图、再按目录确定操作——绝不能让空目录覆盖用户的请求。先检查 iterate（它由明确的磁盘信号决定）：

• iterate → references/managed/CONNECT.md。项目已经连接到 Wix——已存在 wix.config.json（或 .wix/）——且所有者希望添加或更改功能。流程与 connect 相同，但 §1 跳过 init，并沿用现有的 wix.config.json；绝不要对已连接的项目重新运行 init。
• connect → references/managed/CONNECT.md。用户提供了一个尚未连接到 Wix、希望接入的设计：磁盘上的前端项目没有 wix.config.json，或导入/获取的设计（解压或读取的 .zip/文件夹/文件、设计文件 URL、Claude-Design/v0/Lovable 导出），或类似“连接这个 / 实现这个设计（……连接到 Wix）/ 在 Wix 上托管这个 / 将这个部署到 Wix / 为这个项目添加 Wix Headless”的表述。导入或获取的设计即使当前目录为空，也属于 connect——设计来自其他位置（zip/fetch/URL），因此触发时目录为空并不代表 create。(CONNECT.md 第 1 步会将导入的设计放入 CWD，然后运行 init。)
• create → references/managed/CREATE.md。用户希望仅根据提示词构建一个新网站，且没有导入任何内容——例如“给我建一个网站 / 商店 / 博客……”，没有设计文件，也没有磁盘上的项目。
• backend-only — 用户只希望配置后端（不涉及前端工作）。→ 使用共享主干流程 + 输出 SDK 交接内容。

对于 self-managed 和 stripe，操作始终是仅后端（前端由托管方负责）。只有在确实没有导入的设计，且没有连接相关表述时，才根据目录是否为空来决定：空目录 → create；磁盘上已有前端 → connect。

前置条件（由宿主提供——我们只读取，绝不创建）

1. 项目类型 — managed | self-managed | stripe — 由调用方提供，否则根据项目特征 / 用户意图检测（参见“项目类型”§“确定项目类型”），再不然就询问。它决定 <TYPE_DIR>（参见“路径解析”）。
2. Wix metasite 和 headless OAuth 应用均已存在，且凭据可用 — 通过项目类型对应的 AUTHENTICATION.md 获取。此技能需要经授权访问该 metasite 的 bearer token，以及 metasite id。
3. 用户意图 — 描述 Wix 应提供哪些能力的自由文本（例如“添加商店”“博客 + 联系表单”“持久化我应用的数据”）。
4. （可选） 磁盘上的项目 — 只读，用于更准确地推断品牌 / 功能。

如果没有凭据，则无法连接 Wix 后端——请停止并给出明确错误。

此技能的作用

始终先打开 DISCOVERY.md（它与认证无关——用于推断功能 / 品牌 / 意图，并设置图像检查关卡）。然后根据项目类型和操作进行路由：

仅后端（self-managed、stripe，或 managed 的仅后端模式）——精简主干流程：

1. 发现（references/DISCOVERY.md）——推断功能 + 品牌 + 意图 + 图像。
2. 设置（references/SETUP.md）——安装这些功能所需的 Wix 应用。
3. 播种（references/SEED.md）——创建后端内容（如果启用了图像，还要创建实体图像）。
4. 交接（references/SDK_HANDOFF.md）——完成设置和播种后，输出集成指南：SDK 引导、各功能的调用方式、已播种的 ID，以及 @wix/* 包列表。
5. 完成部署（<TYPE_DIR>/DEPLOYMENT.md）——执行该项目类型的完成步骤。 在整个运行过程中——如果用户要求向 Wix 发送反馈、抱怨或感到沮丧，或者运行遇到任何实际阻碍（令人困惑的错误、文档缺漏、工具使用陷入僵局、你不得不自行设计的变通方法——不需要反复出现），主动提出按照 references/FEEDBACK.md 将反馈转达给 Wix。默认主动提出，而不是等用户开口。每个流程的最终步骤（<TYPE_DIR>/DEPLOYMENT.md / managed/CREATE.md / managed/CONNECT.md）都以同一个检查点结束——将其视为必需的自检，而非可选项。只有在用户明确同意后才发送——绝不自动发送。

托管式创建 / 连接 / 迭代——完成 Discovery 后，将整个运行交给托管流程：

• 创建 → references/managed/CREATE.md（搭建脚手架 → Setup → Seed → 构建前端 → 发布）。
• 连接 → references/managed/CONNECT.md（初始化 → Setup → Seed → 接入现有 UI → 发布）。
• 迭代 → references/managed/CONNECT.md——项目已连接，因此会复用现有的 wix.config.json（不执行 init）。Setup / Seed / 接入都是增量式的：项目可能已在先前的运行中完成 Setup 和 Seed，因此 Agent 会先检查当前状态（已安装的应用、已有的种子内容、现有接入），只应用新意图所需的变更——绝不盲目地重复安装或 Seed。只有当前端构建输出发生变化时才重新发布。 这些流程会复用相同的 SETUP.md / SEED.md / SDK_HANDOFF.md，但会应用 SDK 指南，自行构建 / 接入前端，而不是输出指南；并通过 managed/DEPLOYMENT.md 发布。

每次 Wix 调用都使用通用调用格式（SETUP.md §1），并按照 <TYPE_DIR>/AUTHENTICATION.md 获取 $TOKEN / $SITE_ID。除了一次关于图像的问题（以及无法确定项目类型时询问项目类型），该技能以非交互方式运行。

除非用户要求验证，否则不要在本地对前端进行冒烟测试。 交付内容是已构建并发布的网站（托管式）或 SDK 指南（仅后端），而非本地测试报告。默认情况下不要启动开发服务器（wix dev / astro dev / npm run dev）来 curl 页面、操作购物车 / 预订 / 登录流程，或启动无头浏览器：遵循操作指南即可确保正确性，实际错误会在 wix build / wix release 时显现，而且无头运行无法完成交互式登录或真实付款——因此这类循环通常会耗费数分钟，却只能提供很少的信息（这与「只在最后发布一次」规则不同，除了该规则之外，本条也禁止额外的 构建+发布 循环，而不只是禁止开发服务器测试）。只有在用户的提示中明确要求验证 / 测试 / 确认其可用时，才启动开发服务器并进行冒烟测试——此时只进行一次轻量检查（页面可以编译并渲染），不要完整地操作购买 / 预订 / 登录流程。<TYPE_DIR>/DEPLOYMENT.md 中发布后的唯一检查是获准进行的验证。

**捐赠场景对上述冒烟测试政策的例外：**对于接受捐赠的构建，在声称其可用之前，请按照 references/inline-recipes/how-to-code-donations.md 中有范围限制的匿名 API 交接检查进行验证。此检查不授权进行付款或活动变更，也不要求循环进行开发服务器测试。该指南还规定了单独的托管式结账和付款检查。

路径解析

根据此文件计算 <SKILL_ROOT>（<SKILL_ROOT>/SKILL.md — 去掉 /SKILL.md）；将绝对路径保存在临时变量中。然后解析项目类型对应的文件夹，并一并保存：

<TYPE_DIR> = <SKILL_ROOT>/references/<projectType>/ — 以下目录之一：managed/、self-managed/、stripe/。

内容	路径
垂直领域索引（意图匹配 + 各垂直领域的网站规范）	<SKILL_ROOT>/references/CAPABILITIES.md
发现（推断功能、品牌和意图；已有网站 → §1 中的 Dynamic Context 调用）	<SKILL_ROOT>/references/DISCOVERY.md
设置（安装应用）	<SKILL_ROOT>/references/SETUP.md
初始化内容（创建后端内容）	<SKILL_ROOT>/references/SEED.md
SDK 集成交接（生成，或由 create/connect 应用）	<SKILL_ROOT>/references/SDK_HANDOFF.md
图像生成（可选；通用）	<SKILL_ROOT>/references/IMAGE_GENERATION.md
设计 — 用户未提供自己的设计方向时，为构建的前端设定备用视觉质量标准（仅限托管式 create）	<SKILL_ROOT>/references/DESIGN.md
内容 — 用户未提供自己的文案/语气方向时，为构建的前端设定备用文案质量标准（仅限托管式 create）	<SKILL_ROOT>/references/CONTENT.md
体验叠加层 — 在 DESIGN/CONTENT 基础上，为某个垂直领域设定自身的设计 + 文案标准（每个垂直领域可选；加载该垂直领域时读取）	<SKILL_ROOT>/references/inline-recipes/experience-<vertical>.md（目前：experience-store.md、experience-donations.md）
AI 功能 — 文本/聊天 + 嵌入（可选；通用）	<SKILL_ROOT>/references/AI_FEATURES.md
反馈 — 将用户对无头体验的反馈转达给 Wix（可选；需用户批准）	<SKILL_ROOT>/references/FEEDBACK.md
身份验证 — 获取 $TOKEN/$SITE_ID/clientId（因项目类型而异）	<TYPE_DIR>/AUTHENTICATION.md
部署 — 完成线上网站的最终部署（因项目类型而异）	<TYPE_DIR>/DEPLOYMENT.md
托管式 create 流程（搭建新项目）	<SKILL_ROOT>/references/managed/CREATE.md
托管式 connect 流程（接入现有项目）	<SKILL_ROOT>/references/managed/CONNECT.md
前端方向参考（前端如何接入 Wix）	<SKILL_ROOT>/references/astro.md、non-astro.md

开始运行时，先打开 DISCOVERY.md。 流程文件（CAPABILITIES、DISCOVERY、SETUP、SEED、SDK_HANDOFF、IMAGE_GENERATION、AI_FEATURES）不依赖项目类型；各类型的具体内容位于 <TYPE_DIR>/ 下（AUTHENTICATION.md、DEPLOYMENT.md，以及仅限托管式项目的 CREATE.md/CONNECT.md）。

how 从何而来

此技能没有上游技能——how 来自实时 Wix 文档 dev.wix.com/docs。阅读优先级：此技能链接的页面，优先直接通过 curl 获取其对应的 .md 文件（最高优先级——不要通过搜索重新发现已整理好的链接）；Wix MCP 文档/搜索工具优先级其次，用于查找此技能未链接的页面，或在获取失败时作为后备方案。（在任意文档 URL 后追加 .md 即可获取原始 Markdown；菜单页面列出子链接，内容页面包含架构。）

文档发现是两条路径共用的后备方案——绝不是第一步。 每条路径的主要来源都是其固定材料（见下文）；这些材料未涵盖所需内容时，再回退到 references/DOC_DISCOVERY.md——一种无论是否使用 Wix MCP 都能使用的语义文档搜索 + 架构查询方式。

• Seed 从每项能力的内联配方中读取其创建流程——这是一个自包含的本地 inline-recipes/setup-*.md 文件（在 SEED.md §“每项能力要 Seed 什么”中按能力映射），其中内联了调用内容，且取代 REST 文档页面，因此只需阅读该文件并据此 Seed。只有没有内联配方的能力（例如 coupons）才回退到文档发现（DOC_DISCOVERY.md）。
• Handoff 链接每项能力的 SDK 文档以了解其 API 结构，并从 SDK_HANDOFF.md 中内联的映射表提供运行时软件包列表（SDK .md 页面不会在导航中公开 @wix/* 导入字符串，因此软件包通过映射确定，而非导航查找）。

SETUP.md 内联提供了应用安装调用（以及 appDefId 常量）；CAPABILITIES.md 是纵向索引，可让 Discovery 匹配意图，并且针对每个已构建的垂直领域声明 Required site features + Implementation checklist，由 Seed 启用（由后端支持的功能），并由 Handoff 纳入指南（这样宿主构建的是完整网站，而不是单纯的数据转储）。此技能负责提供what（有哪些能力、内容量多少、完成的网站包含什么），并从文档中读取 how。