wix-vibe-headless

Wix Vibe Headless — 仅客户端 REST 连接器

通过网站公开的 WIX_CLIENT_ID，从浏览器使用手动编写的 REST，将现有前端连接到在线 Wix 网站——不使用 @wix/sdk、不需要后端、无需构建步骤，也不需要依赖项。一个技能、一个共享传输层，以及针对每种 Wix 业务解决方案的独立 REST 层，可直接复制使用。所有操作都只读所有者的内容：渲染实时 Wix 数据，或如实显示空状态——绝不模拟、绝不创建、绝不虚构产品、帖子、活动、菜单、套餐、评价或数量。

何时使用此技能

• 用户已有（或正在构建）一个前端——例如通过氛围编程构建的应用、纯 HTML/JSX、Vite/React 项目或设计工具导出的项目——并希望它显示来自现有 Wix 网站的实时数据，且完全通过客户端完成真实购买/预订。
• 用户提供了一个公开的 WIX_CLIENT_ID，并要求“将它连接到我的 Wix 商店/博客/预订/活动/……”。
• 用户希望用真实的 Wix 内容替换占位符/模拟数据，或为已有应用添加购物车、结账、预订、RSVP、票务、预约、表单或订阅流程。

何时不应使用此技能

场景	改用
通过一个提示词端到端构建一个全新 Wix 网站（探索 → 设计 → 构建 → 托管）	wix-headless
项目应使用 Wix SDK（@wix/sdk）和/或 Wix CLI，或应托管在 Wix 上	wix-headless
通过 REST 管理/配置网站（安装应用、填充目录、设置业务解决方案）	wix-manage
构建 Wix 应用扩展（仪表板页面、小组件、后端、插件）	wix-app

此技能采用有意设计的仅客户端、仅 REST方案。它独立于 wix-headless（后者使用 SDK + CLI + 托管）——不要在同一个项目中混用两者。

共享模型（适用于每种业务类型）

• 认证 = 一个公开客户端 ID。 WIX_CLIENT_ID 是面向买家／访客的凭据—— 它只用于签发匿名访客令牌。它不是密钥；硬编码并提交都没问题。由用户提供（其 vibe／托管平台会显示一段已填入该 ID、可复制的提示词）。将其粘贴到 wix-config.js 中，替换 <YOUR-CLIENT-ID> 占位符。
• 金额／价格字段是对象，绝不是标量。 Wix API 返回的每个价格／金额—— Stores 的 price.actualPrice、Bookings 服务的 payment.fixed.price、Events 票券的 registration.tickets.lowestPrice，以及其他字段——都具有 { value, currency, formattedValue } 这样的结构。显示 formattedValue（其中已包含货币符号），或者使用 value + currency 进行回退拼接。绝不能直接将该对象放入 UI，也不能将其当作数字／字符串处理——否则会显示 [object Object] 或未经格式化的数字。 **捐赠例外：**活动价格使用 { amount, formattedAmount }，其中 amount 是十进制字符串；而捐赠购物车的 options.amount 必须是 JSON 数字。请遵循 Donations 配方。
• 访客令牌 = 身份。 wix-client.js 会签发匿名访客令牌，将 刷新令牌保存到 localStorage，并在令牌过期时刷新。该令牌就是购物车／预订／会员会话的身份——绝不要在每次加载时重新签发匿名令牌，否则购物车会悄无声息地清空。
• 会员登录会在同一客户端上替换令牌集。 members 垂直领域使用自定义登录——前端负责登录 UI；会员绝不会被重定向到 Wix 托管的登录页面。 登录成功后，会将会员令牌写入访客令牌使用的同一个存储位置 （setSessionTokens），因此后续每次 wixApiRequest 都会以会员身份运行，购物车／会话也会延续。只有登录后，“我的……”页面（套餐、订单、预订、注册）才会显示内容。
• ⚠️ 一旦基于 Wix 构建，就继续使用 Wix——认证、会员数据和其他业务功能也一样。 如果你通过 WIX_CLIENT_ID 接入 Wix 商店／博客等功能，也应优先让应用的其余部分使用 Wix，而不是转向托管平台自己的后端或登录系统。**尤其是认证：**用户需要会员功能时，应将其作为 Wix 会员登录（使用 members 垂直领域）——不要接入托管平台的认证。同样，会员生成的内容（点赞、评论、投稿、“我的……”列表）应存入 Wix CMS 集合（使用 cms 垂直领域），而不是托管平台的数据库。
  • **双重身份陷阱：**最常见的问题是混用两套系统——例如将“点赞”存入托管平台的数据库，却用 Wix 会话识别会员（或使用 Wix members 登录，却用托管平台的用户 ID 关联数据）。这两种身份永远无法匹配，所有权筛选会悄无声息地返回空结果（刷新后点赞消失），数据也不会与其余 Wix 内容存放在一起。
  • **经验法则：**每项功能只使用一个存储位置和一种身份。对于基于 Wix 的功能，应使用 Wix 会员 + Wix 集合，并通过 Wix 服务器写入的 _owner 记录所有权（绝不要手动存储或由托管平台提供会员 ID）。对于确实仅属于托管平台的数据，可以使用托管平台后端——但绝不要让同一项功能横跨两边。
• 绝不模拟数据，绝不代为创建。 这些脚手架只读取所有者的内容。所有者应在 Wix 控制面板中添加产品／帖子／服务／活动／菜单／套餐。如果集合为空，就显示空状态——绝不要伪造数据、评论、评分或数量。
• 购买必须通过 Wix 完成。 结账／售票／套餐购买始终通过 Wix 重定向会话／Wix 托管表单完成——绝不要手动构造 /checkout 或购买 URL。
• 明确报告失败。 辅助函数在商品缺货、购物车为空、时段不可预订、保留已过期或仍需付款时会抛出错误。成功路径必须代表操作确实成功——不要吞掉错误。
• 按原样使用随附的辅助函数——不要重写其内部逻辑。 将 UI 接入已导出的函数；不要“重构”或重新实现辅助函数的函数体。有些 Wix 请求格式必须精确，稍有不慎就会出错（members 的 createRedirectSession 请求体就是典型陷阱——重写后会返回 400，导致登录失败）。通过调用导出函数来扩展；若确有缺失，则添加新的 wixApiRequest 调用——绝不要修改随附的函数。
• 超出代码片段范围时，查阅文档——绝不要猜。 模板和随附的 references/<vertical>/ 辅助函数就是实现依据——先以它们为基础构建。遇到代码片段未覆盖的实际缺口（字段、端点或错误）时，应先确认确切的端点、方法和请求体，再使用 wixApiRequest 扩展客户端。在该迭代和故障排查过程中——查找正确的端点、阅读方法的请求／响应结构，或诊断 API 错误时，请使用环境中可用的文档技能查阅 Wix 官方 API 文档，以搜索方法、阅读页面并检查 API 结构。 参考索引：https://dev.wix.com/docs/api-reference.md
• 向用户提供 Wix 控制面板的深层链接：在许多情况下，用户需要在 Wix 控制面板中修改垂直领域的默认数据。请始终向用户提供这些链接。各垂直领域对应链接的相关信息位于其 INSTRUCTIONS.md 文件中。

此技能的结构

<SKILL_ROOT> 是此文件所在的目录（去掉 /SKILL.md）。每个垂直领域都会在 references/<vertical>/app/ 下提供集成代码：REST 辅助工具位于 app/rest/，此外还会根据垂直领域提供实用工具、钩子、上下文、组件或页面。所有代码都使用 references/shared/app/ 中的共享传输层（app/rest/wix-client.js + wix-config.js），每个垂直领域都相同。在 wix-config.js 中设置 WIX_CLIENT_ID（和 WIX_METASITE_ID）。将 references/<vertical>/app/ 和 references/shared/app/ 部署到应用的 src/ 中，即可放置好所有文件——REST 辅助工具会位于 src/rest/ 中，因此其相对导入可以正常解析。

这些文件在应用中的存放位置以及放置方式（设置时预先安装，或复制进去）由你的平台决定——请遵循相应的平台说明。

每个垂直领域的 INSTRUCTIONS.md 都会说明其前置条件、提供的内容、导出的接口，以及你必须构建的呈现层。开始实现前请先阅读：复用提供的内容，构建缺失的呈现层，不要重新实现已提供的逻辑。如有提供，请遵循平台和垂直领域的完成指南。

路由 — 根据请求选择一个或多个垂直领域

加载用户应用所需的垂直领域；一个项目可以组合多个领域（例如，带博客的餐厅，或提供定价方案的商店）。

每个垂直领域的集成文件都位于 references/<vertical>/app/；将该目录和 references/shared/app/ 复制到应用的 src/ 中（base44 会在安装时通过 deploy.cjs 完成此操作）。

用户想要……	垂直领域	阅读
在线商店：产品、分类、购物车、结账	storefront	references/storefront/INSTRUCTIONS.md
捐赠：筹款活动、一次性或定期捐赠、托管式结账	donations	references/donations/INSTRUCTIONS.md
预约：服务、时段、预订、结账——以及附加到可预订服务的表单	bookings	references/bookings/INSTRUCTIONS.md
租赁：客户可以自行选择租用时长的物品（按小时或按天）——Wix Rentals 使用 Bookings API，因此属于同一垂直领域	bookings	references/bookings/INSTRUCTIONS.md（“Rentals”）
博客/新闻：文章动态、文章页面、分类、标签	blog	references/blog/INSTRUCTIONS.md
活动：浏览、活动页面、RSVP、票务——RSVP 属于此处，而不是 forms，即使活动只有一场且不售票	events	references/events/INSTRUCTIONS.md
作品集/展示：合集、项目、媒体图库	portfolio	references/portfolio/INSTRUCTIONS.md
餐厅：菜单、在线点餐、餐桌预订	restaurants	references/restaurants/INSTRUCTIONS.md
任何访客可填写的表单：联系/咨询、潜在客户、注册、候补名单、申请、反馈/调查、报价请求、信息采集或登记。不包括活动 RSVP（events）、每项服务的预约表单（bookings）或捐赠款项（donations）	forms	references/forms/INSTRUCTIONS.md
CMS 内容：列表/详情、筛选/搜索、数据 CRUD。访客可填写的表单属于 forms——只有当应用必须读回这些条目时才使用 cms	cms	references/cms/INSTRUCTIONS.md
方案与定价：会员资格/订阅、订阅、我的方案	pricing-plans	references/pricing-plans/INSTRUCTIONS.md
会员账户：自定义登录/注册（邮箱+密码、Google/Facebook、SSO）、账户区域、受限内容	members	references/members/INSTRUCTIONS.md

⚠️ 访客填写并提交的任何内容都属于 forms——以下四种情况除外：

1. 应用必须读回这些条目 → cms。 例如公开图库、列表、会员的“我的提交”。访客无法读取 Forms 提交内容，因此这类情况需要使用集合。仅提交的场景始终使用 forms：连接到 insertDataItem 的表单虽可工作，但会失去仪表板表单构建器、垃圾信息防护、提交通知和 CRM 联系人映射功能，而且所有者必须先手动设置集合权限，才能让任何人提交。
2. 确认参加活动或场合 → events。 婚礼、派对或聚会——events 内置 RSVP 登记表单。即使只有一场活动且不售票，也应路由到此处。
3. 附加到可预订服务的表单 → bookings。
4. 向捐赠活动捐款 → donations。 定期捐赠不是 Pricing Plans 购买；捐赠表单必须保留活动的金额/频率规则，并使用其目录引用。

请求未指定 Wix Business Solution 时——询问用户，或检查网站

不要根据含糊的需求推断要构建哪种 Wix Business Solution（商店、预约、博客、活动、作品集、餐厅、CMS、定价方案、会员等）。向用户简短地询问一个问题——他们提供什么服务（产品？预约？文章？活动？）——或者检查网站的实际内容：使用每种可能解决方案对应的辅助工具（queryProducts、queryServices、queryPosts、queryEvents，等等）发起一次成本较低的读取请求——使用通过 WIX_CLIENT_ID 生成的访客令牌进行身份验证；如果有管理员令牌，也可以使用管理员令牌——然后为返回真实内容的解决方案构建功能。428“未安装应用”（博客为 401）意味着网站未启用该解决方案；看起来像示例的内容（“示例产品 3”）只能证明应用已安装，不能说明商家经营什么。用户没有明确说明时，绝不要默认选择商店或预约。

执行流程

1. 获取 WIX_CLIENT_ID。 它由用户提供（来自其 Wix/vibe 平台的交接提示）。如果缺少该值，先向用户索取，再进行接线——没有它，任何功能都无法运行。
2. 根据路由表选择垂直领域；如果请求没有指定任何领域，先询问用户或检查网站（见上文），不要猜测。打开每个所选垂直领域的 INSTRUCTIONS.md。
3. 确保垂直领域的文件已就位——将 references/<vertical>/app/ 和 references/shared/app/ 复制到应用的 src/ 中，并在 wix-config.js 中设置 WIX_CLIENT_ID。（具体放置位置和方式由你的平台决定——参阅平台说明。在 base44 上，安装步骤会为你写入并验证 wix-config.js，因此无需手动设置。）
4. 按照垂直领域的 INSTRUCTIONS.md 完成界面构建和集成接线。 通过文档规定的接口复用其提供的组件，构建尚需你完成的界面，并按指定要求连接路由和 Provider。不要重新实现已提供的逻辑。使用现有平台主题为新界面设置样式。
5. 完成适用的平台和垂直领域指南中的所有要求，包括其中规定的检查和交接说明。

有些流程需要用户稍后在 Wix 端完成设置（连接支付方式、将部署域名加入 OAuth 客户端的允许列表以便托管结账后跳转、设置集合权限）。 这些不在此处的处理范围内——如果调用因这些原因失败，请指出问题并继续；不要回退到模拟数据。