wix-app

Wix 应用构建器

帮助为 Wix CLI 应用构建扩展。涵盖所有扩展类型：控制台页面、模态框、插件、菜单插件、自定义元素小部件、Editor React 组件、站点插件、嵌入式脚本、后端 API、事件、服务插件和数据集合。

脚手架由 Wix CLI 负责。 所有受支持的类型都使用 wix generate --params。它会生成文件，以及在适用时生成构建器样板代码、UUID 和 src/extensions.ts 注册项。HTTP 端点会通过文件自动发现，无需注册。本技能提供决策逻辑、API 指南、配置语义和业务逻辑模式，用于完善生成的存根。

⚠️ 强制工作流检查清单 ⚠️

在向用户报告已完成之前，必须勾选所有项目：

• 步骤 1： 确定所需的扩展类型
  • 如果需求不明确，提出澄清问题
  • 🛑 SDK 优先关卡（在任何数据集合操作之前必须完成）： 确认数据不属于现有 Wix 应用；如果属于，则使用该应用的 SDK 模块，绝不可使用 CMS（参见 SDK 优先规则）
  • 检查是否隐含需要数据集合——除非用户直接提供了集合 ID（参见 数据集合推断）
  • 如果要创建数据集合扩展，获取应用命名空间
  • 如果要创建数据集合扩展，确定完整的作用域集合 ID（参见 集合 ID 协调）
  • 说明推荐方案及其理由
• 步骤 2： 阅读所选类型的扩展参考文件，以及项目级的 CODE_QUALITY.md
  • 控制台页面 UI： 在选择组件之前，将提示词转化为工作流——用户必须理解、关注、调查、执行什么操作，以及看到什么确认信息。参见 UX 成功模型，以及已安装软件包自带的 Collection Toolkit.md 指南，了解每项需求对应的组件（发现链）。
    • 除非请求明确要求，否则不要使用 SummaryBar——提示词中必须出现一个明确的总计、计数或“多少 / 多大”数字。不能因为“页面看起来需要”就添加：未经请求的栏会把行向下推，并在屏幕上显示一个没人要求你保证准确的数字。如果请求确实要求显示该数字，则它必须来自某个计数来源（QUERY_AND_PAGING.md），并通过 useSelector 读取，因为状态由 MobX 管理（TABLE_STATE.md）。
    • 用户可打开的行应作为页面呈现，且默认可编辑——对于 CMS 和纵向 SDK 数据，都使用 navigateToEntityPage 跳转到带有可用表单和保存功能的 EntityPage；三个只读情形见 DRAFT_TEMPLATE.md。除非提示词明确要求报告或导出。绝不可使用 SidePanel：在 Cairo 中，它承载页面自身的面板。
    • 每个筛选条件都必须传入查询：在集合钩子的 filters 中声明，并在 fetchData 中读取。无法缩小行范围的筛选 UI 是一个伪装成功能的缺陷。 没有下钻功能、筛选器也无法正常工作的筛选表格，就是没人说明需求时最终做出来的东西——这是生成式仪表板最常见的令人失望之处。汇总数据如何呈现需要自行判断；下钻功能和筛选器则不需要。
  • 🛑 模板优先关卡（强制，仅限仪表板 UI，必须先于编写任何 shell/provider/router）： 遵循了 DRAFT_TEMPLATE.md：找到已安装的 @wix/patterns 提供的页面模板，根据其 Page Templates.md 指南选定一个模板——确定上述工作流需要哪些页面，以及行数据的来源（自行获取，还是来自 CMS 集合）——阅读该模板的页面，并复制 --templates 为其列出的每个文件。当模板已经展示了页面 shell、provider 嵌套或 router 接线方式时，仍从头拼装这些内容，正是此关卡要防止的失败模式——下方的 Patterns/组件文档关卡针对的是模板未涵盖的内容，不能取代从模板开始的步骤。反过来也一样：模板可以替代拼装 shell，但绝不能取代发现流程；模板未展示的每个符号仍须通过下一关卡。
  • 🛑 Patterns 文档关卡（任何仪表板页面 UI 的强制要求）： 在执行第一条涉及 node_modules/@wix/patterns 的命令之前，先阅读 WIX_PATTERNS_DOCS.md——其中的发现流程（pkg-root.cjs、索引、只需阅读一次的 Composition and Providers.md，以及用于判断哪个组件能满足需求的 Collection Toolkit.md）仅在该文件中说明；本条只是其步骤 1 的摘要，不能替代实际打开该文件。然后，在一次 node <pkgRoot>/bin/patterns-lookup.cjs <name…> 调用中解析计划编写的每个 patterns 名称：每个名称都会输出导入语句、示例和一个 props 文件。如果缺少 dist/docs/index.json，请升级 @wix/patterns。Patterns API 信息只能来自已发布的 dist/docs/（页面）、dist/examples/（完整调用示例）、dist/dts-bundle/（类型）和 dist/templates/（完整页面）目录树——绝不能来自 src/、dist/esm/、dist/types/ 或软件包中的其他路径。bundle 存根中未包含的 prop，位于该存根所指向的文件中（Reading the Doc Indices.md）。
  • 🛑 组件文档关卡（强制，仅限仪表板 UI）： 对于即将编写的每个 patterns 符号，根据 lookup 输出，确定哪个单一资源能回答你实际的问题——导入语句、示例或 props 文件——并按照组件选择顺序中的“简明版”仅阅读该资源。在第一行 JSX 之前，说明每个符号阅读了哪个资源，以及原因。对同一符号同时阅读文档和 bundle，或为查找 lookup 已提供的导入语句而打开页面，正是此关卡要防止的失败。 对于 useTableCollection() 返回的对象，请阅读 TABLE_STATE.md——这是你接收到的状态对象，而非自行构造的对象；其成员并不直观，而且有几个看似合理的成员实际上不存在。
• 步骤 3： 检查了 API 参考；通过一次 sdk-lookup.cjs 调用解析了每个垂直领域实体（SDK 查询）；仅在查询未输出相关信息时才查阅文档
  • 基于 Wix 数据的仪表板页面： 从查询结果中获取方法，并根据该方法指向的声明（type … file:line）逐一核对所有映射字段——请参阅 DATA_SOURCES.md，并在编写 fetchData 前阅读 QUERY_AND_PAGING.md。标记为 @deprecated 的字段仍能通过编译并渲染出看似合理但实际错误的内容。
  • 垂直领域 SDK 前置条件——针对页面使用的每个 @wix/* 垂直领域，包括后来添加的： 确认该包确实是依赖项（若不是则安装），并记录读取操作所需的 Dev Center 权限范围——缺少权限范围会导致页面成功构建、挂载，却不显示任何内容。两项内容均见 DATA_SOURCES.md；权限范围需列在 Manual Steps Required 下。步骤 4b 中添加的第二个垂直领域也必须进行此检查，且其失败不能导致整个页面不可用——请参阅 添加第二个垂直领域就需要第二个权限范围。
  • 按照 SDK 而非 REST 页面来建模调用： 命名空间名称、_id 与 id 的区别、重载方法上不要使用 ReturnType、PagingMetadataV2 上没有 hasNext——请参阅 SDK 与 REST API 并不相同。
  • 仅限站点／编辑器扩展：默认将 SDK 调用留在扩展中，只将访客确实无法调用的业务级方法路由到外部（请参阅 身份与权限提升要求）
• 步骤 4a： 通过 wix generate --params 为 CLI 支持的每个扩展生成脚手架
• 步骤 4b： 在生成的文件中填入业务逻辑
  • 边写边编译： 在第一个导入 @wix/patterns 的文件编写后运行了 npx tsc --noEmit，而非等到步骤 5。Patterns 的状态和筛选器 API 是最常见的错误来源；页面写完后一次性发现二十个错误，远比早早发现两个错误费时。
  • 🛑 组件选择关卡（必做，仅限仪表板 UI）： 对于仪表板页面上的每个 UI 元素，先确认 @wix/patterns 是否提供该元素，再考虑使用 @wix/design-system——也绝不手动实现任一库已经提供的组件。请参阅 组件选择顺序。
  • 仅在编辑第一个导入 @wix/design-system 的 .tsx／.jsx 文件之前调用了 wix-design-system 技能。仅后端或纯数据扩展可跳过。
  • 渲染图片时，针对每个集合数据源： 遵循了 IMAGE_RENDERING.md。保留架构定义的图片渲染器和原始表单值；自定义 WDS／原生图片必须先规范化实际 SDK 图片值，再选择回退内容或空状态。SDK 解码可能会将 REST 图片对象替换为 URI 字符串。核验已加载的集合缩略图和详情预览；若无法通过浏览器核验，则报告这一情况。
  • WDS：每个应用只在一个位置导入设计系统样式表——仪表板界面放在 BusinessManagerTheme.tsx 中（见下一项），站点／编辑器扩展则放在主组件入口文件中。绝不在子文件、标签页或辅助文件中导入，也绝不重复导入。
  • 🛑 Business Manager 主题（每个仪表板界面——页面、模态框和插件）： 只编写一次 BusinessManagerTheme.tsx（包含两个样式表，包括 themes/odeditor.global.css，以及 WixDesignSystemProvider → WixDesignSystemIconThemeProvider → IconThemeProvider theme="odeditor" → WixDesignSystemDefaultPropsProvider），并将每个扩展的根节点都包在其中——置于 WixPatternsProvider 和 CustomModalLayout 之上。每个扩展都是独立的 iframe，不会继承重新设计的样式，因此为页面设置主题对其打开的模态框或插槽中的插件没有作用；每个扩展都需要自己的包装器。此外：所有图标都必须来自 @wix/wix-ui-icons-common/lazy，并使用 --wds-* 令牌或 skin／size 属性，而不是硬编码颜色、字号或内联 style（BUSINESS_MANAGER_TOKENS.md——请注意，该主题会将 SP* 间距单位从 6px 重新设为 4px）。未应用主题的界面也能通过 tsc、wix build 和 wix preview；只有查看界面才能发现这一问题。请参阅 BUSINESS_MANAGER_THEME.md。
• 步骤 4c（仅限仪表板页面 UI）： 重新打开并阅读刚编写的页面文件——而不是凭印象回忆——并根据实际代码确认：除非请求明确要求，否则不使用 SummaryBar；每一行都有路由式深入查看（navigateToEntityPage），且不使用 SidePanel 来代替；每个已声明的筛选器名称也都出现在 fetchData 中；对于带路由器的每个模板，入口文件都会传入并保护 location。请参阅 UX 完整性自审。
• 步骤 5： 运行了验证（请参阅 验证）
  • 已安装依赖项
  • TypeScript 编译通过
  • 构建成功
  • 预览已部署
• 步骤 6： 收集并向用户列出所有手动操作事项 **🛑 停止：**如果有任何复选框未勾选，请勿继续下一步。

---

快速决策助手

1. 你想构建什么？

   • 管理界面 → Dashboard Extensions
   • 后端逻辑 → Backend Extensions
   • 数据存储 / CMS 集合 → Data Collection（仅限应用自有数据 — 参见 SDK 优先规则）
   • 编辑器 React 组件 → Site Extensions（仅限应用项目）

2. 谁会看到它？

   • 仅管理员用户 → Dashboard Extensions
   • 网站访客 → Site Extensions
   • 仅服务端 → Backend Extensions

3. 它会出现在哪里？

   • Dashboard 侧边栏 / 页面 →
     • 完整管理屏幕：Dashboard Page — 使用 @wix/patterns + @wix/design-system 构建 UI（参见组件选择顺序）。不能使用 <Modal /> — 请改用单独的 Dashboard Modal 扩展，并使用 dashboard.openModal()。
     • 弹出窗口 / 表单：Dashboard Modal
   • 现有 Wix 应用 Dashboard（widget）→ Dashboard Plugin
   • 现有 Wix 应用 Dashboard（菜单项、更多操作 / 批量操作菜单）→ Dashboard Menu Plugin
   • 网站上的任意位置，独立显示 → custom element widget
   • 网站上的任意位置，带有编辑器清单（样式 / 内容 / 元素）→ Editor React component
   • Wix 商业解决方案页面上的固定插槽 → Site Plugin
   • 仅脚本 / 分析，无 UI → Embedded Script
   • 商业流程期间（结账 / 配送 / 税费）→ Service Plugin
   • 向 Wix AI 助手提供工具 → App Tools（需要同时声明 APP_TOOLS + 使用 TOOLS_PROVIDER_CONFIG 处理 — 参见 APP_TOOLS.md）
   • 事件发生后（webhook / 同步）→ Backend Event Extension
   • 自定义 HTTP 端点 → Backend API

---

组件选择顺序

**对于页面框架、Provider 嵌套和路由 — 每个 Dashboard 页面都需要的部分 — 请从 DRAFT_TEMPLATE.md 开始，而不是从本节开始。**它会查找已安装的 @wix/patterns 随附的页面模板（只读列表、带创建 / 编辑功能的列表、仅设置页，以及基于其架构的 CMS 集合）；复制与请求匹配的模板并进行调整。以下内容适用于模板尚未展示的单个 UI 元素 — 例如筛选器类型、列渲染器，或请求需要但模板中没有的组件。

Wix 的 Dashboard 页面由两个库构建。对于模板尚未涵盖的所有 UI 元素，请按以下顺序查找，并在找到第一个匹配项时停止。切勿跳过步骤，也不要凭记忆判断某个组件是否缺失 — 请进行检查。

1. @wix/patterns — 页面结构与数据集合

Patterns 管理页面外壳以及所有集合相关内容：页面外壳及其页眉／内容／页脚子部分、表格和网格及两者之间的切换、文件夹视图、集合状态（分页、排序、选择、加载）、筛选器、搜索、视图预设、行操作和批量操作、拖放、扩展内路由、与集合关联的覆盖层，以及单个列表项的添加／编辑／查看页面。如果你需要其中任何一项，它就属于 patterns——请查阅相关组件，而不是用 WDS 部件拼装。

哪个组件适用于特定需求，由库本身决定，而不是由这份技能决定。 库会在已安装的包中附带指南来说明这一点，并且其中的每个组件名称都会在构建时与真实包进行核对。请按此流程查阅：发现链。

整个页面也属于这个包：多页面扩展的路由配置，以及字段由 CMS 管理的集合——使用 @wix/patterns-cms 中的 useCmsSchemaSource，搭配 @wix/patterns/schema；schema 会提供数据获取、筛选器、列和表单——这两者都以页面模板的形式提供。参见 DRAFT_TEMPLATE.md。

简而言之：列出你打算使用的所有 patterns 名称，然后通过一次 node <pkgRoot>/bin/patterns-lookup.cjs <name…> 调用解析它们，而不是对每个名称分别探查索引。输出会提供每个名称对应的导入语句（无需读取）、使用示例，以及包含其 props 的文件。根据你当前的问题，阅读所需的一份资料即可。每个会话只需解析一次 <pkgRoot>（参见先决条件），之后重复使用即可。

打开集合中的某个项时，默认使用可编辑的 EntityPage；创建／编辑流程也使用 EntityPage，绝不使用 dashboard 模态框——参见实体创建与编辑，以及包中的 Collection to Entity Flow.md，了解具体流程。

因为查找不方便而直接跳到第 2 步，是 dashboard 页面最终完全由 WDS 构建的最常见原因。 找不到索引，意味着还没有执行查找，并不代表 patterns 缺少该组件。

2. @wix/design-system — 外壳内的所有内容

patterns 不负责叶级 UI：输入框、按钮、表单字段、文本、布局基元、卡片、徽章、工具提示、提示消息和图标。请通过查找来选择组件，而不是凭记忆——调用 wix-design-system 技能；该技能附带的辅助工具会读取已安装的包：

node <wix-design-system-skill-dir>/scripts/wds.cjs search <keyword>
node <wix-design-system-skill-dir>/scripts/wds.cjs component <Name>

如果没有安装该技能——它是一个独立技能，并且有些宿主提供 wix-app 时不会附带它——请勿直接凭记忆编写 WDS，也不要把缺少该技能当作可以自行实现组件的许可。请改为读取已安装的包；技能本来也会从该包读取：

ls node_modules/@wix/design-system/dist/types/            # the component inventory
cat node_modules/@wix/design-system/dist/types/<Name>/<Name>.d.ts   # its real props

使用组件前，请先准确写出你读取的文件名称，遵守 patterns 的 Component Docs Gate 要求。技能缺失只会降低便利性，不会降低标准。

3. 自定义 React — 仅在两者都没有结果时使用

使用 WDS 布局基元（Box、Card、Text）进行组合。不要添加第三个 UI 依赖，也不要重新设置 patterns 或 WDS 内部组件的样式。

重叠与适用范围

• 当两个库都提供相同概念（页面页眉、页面容器）时，在 patterns 页面中优先使用 patterns 提供的版本——它与外壳的布局和集合状态相连。仅在 patterns 页面外壳之外使用对应的 WDS 组件。
• Patterns 有自己的覆盖层。 PickerModal / usePickerModal 和 bulkActionModal 用于集合相关的覆盖层。“这是一个模态框”并不是绕开 patterns 的理由。
• Dashboard Plugins 在 patterns 页面外壳之外渲染，因此默认使用 WDS。当这类界面展示数据集合时，仍应使用 patterns 集合组件。

实体创建和编辑

打开集合页面中列出的记录时，默认使用可编辑的 EntityPage，无论记录来自 CMS 还是垂直 SDK。 用户只需请求表格或列表，无需另外提出编辑需求。三种只读情况见 DRAFT_TEMPLATE.md；只读详情页仍会作为路由打开，绝不会作为 Dashboard Modal 或侧边面板打开。

用于创建或编辑已列出记录的任何表单都是 EntityPage，而非 Dashboard Modal。 创建／“添加新记录”表单也包括在内：它会写入记录，所以即使尚未编辑任何内容，它仍然是 EntityPage。“这是一个简单的数据录入对话框，不是实体编辑”是对这条规则的错误理解。

不列出任何内容的页面——例如设置页面、嵌入式脚本配置页面——不受 EntityPage 要求约束。但“我没有使用 @wix/patterns 来构建列表”并非例外：列出记录的页面应当是 CollectionPage。

这是最容易遗漏选择顺序的地方：集合页面使用 patterns 正确构建后，“添加项目”流程却在模态框中手动构建成 WDS 表单。

文档中说明的流程：

1. 在集合页面的操作单元格或主操作中，调用 usePatternsNavigate() 中的 navigateToEntityPage({ path, entity })。（patterns 文档提供了这个确切用例——“在集合页面点击操作单元格时导航到实体页面”——它会立即渲染实体标题，无需等待 fetch 完成。）在创建路由上，没有可传入的记录：省略 entity，并阅读 <pkgRoot>/dist/docs/useEntityPage.md 中的创建路由部分，这正是整个“添加新记录”流程所依据的内容。
2. 在 PatternsReactRouter 内使用 PatternsReactRoute 注册路由。
3. 遵循所选模板的实体钩子：对于 SDK／API 数据，useEntityPage({ fetch, onSave }) 负责获取、保存、验证、脏状态、加载骨架屏和错误状态；对于 CMS，schema 变体会根据数据源生成读取和写入操作。表单状态来自 @wix/patterns/form。使用所选模板中记录的签名，并将保存操作连接到真实数据源，而不是本地状态或空操作。
4. 使用 EntityPage.Header、EntityPage.MainContent、EntityPage.AdditionalContent 和 EntityPage.Card 组合主体内容。WDS 应放在这些卡片中——各个字段使用 FormField、Input、Text。

对于既不写入数据也不显示已列出记录的对话框，请使用 Dashboard Modal：例如删除或放弃确认、未保存更改提示、信息通知，或者任何不列出内容的页面上的对话框。对话框尺寸和字段数量都不是例外——针对已列出记录的单字段创建表单仍然是 EntityPage。只有当交互不会持久化任何内容时才使用模态框，绝不能因为“表单应该在模态框中打开”而使用模态框。

扩展类型参考表

扩展类型	类别	extensionType（用于 wix generate --params）	参考文件
控制台页面	控制台	DASHBOARD_PAGE	DASHBOARD_PAGE.md
控制台模态框	控制台	DASHBOARD_MODAL	DASHBOARD_MODAL.md
控制台插件	控制台	DASHBOARD_PLUGIN	DASHBOARD_PLUGIN.md
控制台菜单插件	控制台	DASHBOARD_MENU_PLUGIN	DASHBOARD_MENU_PLUGIN.md
服务插件	后端	SERVICE_PLUGIN	SERVICE_PLUGIN.md
应用工具（AI 助手工具）	后端	APP_TOOLS，然后使用 pluginType: TOOLS_PROVIDER_CONFIG 配置 SERVICE_PLUGIN	APP_TOOLS.md
后端事件扩展	后端	EVENT	BACKEND_EVENT.md
后端 API（HTTP 端点）	后端	HTTP_ENDPOINT	BACKEND_API.md
数据集合	后端	DATA_COLLECTION	DATA_COLLECTION.md
编辑器 React 组件	网站	EDITOR_REACT_COMPONENT	EDITOR_REACT_COMPONENT.md
自定义元素小组件	网站	CUSTOM_ELEMENT	CUSTOM_ELEMENT_WIDGET.md
网站插件	网站	SITE_PLUGIN	SITE_PLUGIN.md
嵌入式脚本	网站	EMBEDDED_SCRIPT	EMBEDDED_SCRIPT.md

关键约束：

• 控制台页面不能使用 <Modal />；请使用单独的控制台模态框和 dashboard.openModal()。

HTTP 端点： 使用 extensionType: "HTTP_ENDPOINT" 生成（而不是 BACKEND_API）。有关项目专属目录、处理程序类型和前端 URL，请参阅 BACKEND_API.md。

跨领域参考资料

主题	参考资料
代码质量要求（适用于所有生成的代码）	CODE_QUALITY.md
扩展注册	EXTENSION_REGISTRATION.md
应用验证	APP_VALIDATION.md
应用市场审核	APP_MARKET_REVIEW.md
应用标识符（命名空间、代码 ID）	APP_IDENTIFIERS.md
Wix Stores 版本管理（V1/V3）	STORES_VERSIONING.md
官方文档链接	DOCUMENTATION.md
Wix Patterns 控制台页面	WIX_PATTERNS_DOCS.md
Business Manager 主题——每个控制台页面、模态框和插件都需要的包装层	BUSINESS_MANAGER_THEME.md
Business Manager 令牌——--wds-* 替代项、重新基准化后的间距单位以及各组件的调整	BUSINESS_MANAGER_TOKENS.md
控制台 UX 成功模型（优质控制台应包含的内容）	UX_SUCCESS_MODEL.md
草稿模板——从任何控制台页面着手：查找、复制并调整软件包的页面模板	DRAFT_TEMPLATE.md
useTableCollection() 返回的状态对象	TABLE_STATE.md
查找页面背后的 SDK 方法和字段名称	DATA_SOURCES.md
来自任何集合来源的图像——CMS、垂直领域 SDK 和自定义数据	IMAGE_RENDERING.md
筛选路径、WQL 运算符和游标分页	QUERY_AND_PAGING.md

---

SDK 优先规则（现有 Wix 应用数据绝不是 CMS）

重要： 现有 Wix 业务应用拥有的数据，应通过该应用的 SDK 模块读取和写入，绝不能将其建模为新的 CMS 数据集合。此类数据的自定义集合一开始是空的，并且会一直与真实记录脱节（例如，基于 CMS 构建的“退款仪表板”会显示空状态，即使 Wix 电商中存在已退款的订单）。

在实体 → SDK 模块映射中查找用户提及的实体，并使用对应的包；SDK 查询随后会指出命名空间和方法。如果实体未列出，且查询也没有结果，请针对该实体运行 SearchWixSDKDocumentation——没有这两项依据时，绝不能认定应使用 CMS。CMS 仅用于存储应用自身引入的数据（配置、规则、应用专用记录），且没有任何 Wix 应用负责管理这些数据。

SDK 类型： 通过导入的命名空间访问类型，格式为 <namespace>.<TypeName>，使用文档中显示的任意类型名称——绝不能从 @wix/<pkg> 根目录按名称导入类型。

import { orders } from '@wix/ecom';
const rows: orders.Order[] = [];              // ✅
// import type { Order } from '@wix/ecom';    // ❌ has no exported member 'Order'

由 SDK 枚举作为键的映射： 字段类型为 <Enum>WithLiterals（枚举或其字符串值）。Partial<Record<bookings.BookingStatusWithLiterals, V>> 不能按状态索引（TS7053）。请使用 Record<…WithLiterals, V> 并为每个值提供条目，或使用字符串值作为部分映射的键：Partial<Record<`${bookings.BookingStatus}`, V>>。

---

数据集合推断

重要： 即使用户没有明确提出“创建 CMS 集合”，也经常需要隐式创建数据集合——请自动推断这一需求。

⚠️ 请先应用 SDK 优先规则——以下指标仅适用于应用自身拥有的数据，不适用于 Wix 应用已管理的实体。

如果用户直接提供了集合 ID，请跳过本节（例如，现有的站点级集合）。在这种情况下，直接使用提供的 ID——无需添加数据集合扩展，也无需限定命名空间。

符合以下任意条件时，始终添加数据集合扩展：

指标	示例
用户提到保存／存储／持久化应用专用数据	“保存费用金额”、“存储产品推荐”
仪表板页面将管理（CRUD）领域实体	“管理费用的仪表板”、“编辑规则的管理页面”
服务插件在运行时读取应用配置的数据	“在结账时获取费用规则”、“查询运费”
用户提到“专用数据库／集合”	“保存在专用数据库集合中”
多个扩展引用相同的自定义数据	仪表板管理费用 + 服务插件读取费用

重要原因： 如果没有数据集合扩展，安装应用时不会创建该集合，Wix Data API 可能无法正常工作（未启用代码编辑器），集合 ID 也不会正确限定到应用命名空间。

如果推断出需要数据集合，请遵循应用命名空间要求，在继续操作前获取命名空间。

应用命名空间要求

创建数据集合时，必须向用户询问其从 Wix Dev Center 获取的应用命名空间。这是必需参数，必须从用户的 Dev Center 仪表板获取，不能由你推荐或猜测。

如果用户尚未提供应用命名空间，请阅读 APP_IDENTIFIERS.md，并向用户说明如何获取该命名空间。

Collection ID 协调

仅在创建 Data Collection 扩展时适用。 如果用户直接提供了 collection ID，请按原样使用——无需命名空间限定，也无需 Data Collection 扩展。

当创建 Data Collection 的同时，其他扩展也引用相同的 collection 时：

1. 获取应用命名空间（参见上文的应用命名空间要求）
2. 确定每个 collection 的 idSuffix（Data Collection 参考文档说明了完整的 ID 格式）
3. 在通过 Wix Data API 调用引用该 collection 的所有扩展中，使用完整的限定 collection ID（<app-namespace>/<idSuffix>）

---

Wix Stores 版本要求

使用任何 Wix Stores API 时均适用（产品、库存、订单等）：

1. 阅读 Stores 版本参考文档——参见 STORES_VERSIONING.md。其中包含模块映射、权限速查表、可复制粘贴的双目录操作方案（列出／获取／创建／更新／删除产品、库存、类别）、V1→V3 字段映射、Webhook 映射，以及 V3 的主要注意事项。先使用该文档，再搜索 SDK 文档——它涵盖了 80% 的常见情况。
2. 所有 Stores 操作都必须先使用 getCatalogVersion() 检查目录版本
3. 根据版本使用正确的模块：productsV3（V3）或 products（V1）
4. 应用必须同时支持 V1 和 V3——仅支持单一版本的应用无法在 App Market 上架，并且会在新站点上出错
5. 为每项 Stores 操作同时请求 V1 和 V3 权限范围

这是强制要求——V1 和 V3 不向后兼容。

---

身份与提权要求

每当扩展调用 Wix SDK 方法时均适用。 编写调用前，先确定调用的运行位置。

扩展的运行身份决定了以下所有内容——扩展类型参考表中的 Category 列会说明你属于哪一种：

• 站点和编辑器扩展——自定义元素小组件、站点插件、Editor React 组件、嵌入式脚本——以站点访客或会员身份运行，绝不会以应用身份运行。
• Dashboard 扩展以 Wix 用户身份运行——不是站点访客身份，也不是应用身份。
• Backend 扩展——Backend API、Backend Event、Service Plugin——以应用身份运行。

auth.elevate 仅适用于后端代码。 在站点、编辑器或 Dashboard 扩展中，它完全不起作用。

默认做法：直接从扩展调用 SDK。 将不需要转接的调用路由出去，并非无害的额外跳转——这正是导致正常功能出错的方式。应根据调用代表谁执行来分类，而不是根据其范围名称：

• 代表当前访客或会员执行——其购物车、结账、预订、订单、预约或个人资料：currentCartV2.*、cartV2.placeOrder、bookings.createBooking、members.getCurrentMember（REST Get My Member），以及其他任何操作“我的”或“当前”实体的调用。这些调用会根据调用方的会话确定执行者，因此提权会让调用以应用身份运行，并使结果与请求者脱离——产生没有买家的订单、没有参与者的预订。
• 平台会根据调用方筛选结果——提权调用会返回直接调用未提供的内容，因此用来修复结果不完整的“补救”反而会造成泄露。Wix Data items.* 遵循 collection 的 dataPermissions（脚手架生成的默认值：itemRead: 'ANYONE'，写入权限为 'PRIVILEGED'——应通过权限修复写入，而不是改变调用路由；参见 DATA_COLLECTION.md）。目录读取会向所有人返回基础字段，但会隐藏 MERCHANT_DATA 和不可见产品，除非应用持有 SCOPE.STORES.PRODUCT_READ_ADMIN。访客和会员调用方使用 members.getMember／queryMembers 时，会看不到 PRIVATE 会员。 只有当方法作用于整个业务、访客或会员确实无法执行时，才将调用路由到外部：archiveLocation、queryLocations、商品目录和库存写入、bookings.confirmBooking、订单管理。如果方法文档显示调用需要提升权限，就将其路由到外部并在那里提升权限——无论调用来自哪个宿主，包括仪表板，因为 auth.elevate 仅适用于后端代码，因此端点是唯一能运行文档所述模式的地方。

**不确定时，直接调用并让它失败。**网站扩展无法调用的方法会立即返回权限错误；而错误地路由到外部并提升权限后，调用却会成功，悄然返回错误数据，或以错误的身份执行操作。部分方法页面附有说明文字，可以据此判断——get-my-member：“此方法需要访客或会员身份验证。”如果存在此说明，它就是权威依据（SDK 查询会将其打印为方法的 note），但只有少数页面提供该说明，因此没有说明并不能说明什么。

有两个信号都不能作为判断依据：权限范围名称——名称指向错误方向的方法会列在 sdk-curated.json 规则中，SDK 查询会将其打印为 note；以及 SDK 架构行中的客户端前缀，同一方法在不同文档渠道中可能有不同前缀，因此没有参考价值，也不值得重新推导。

路由到外部意味着使用会提升权限的后端 API 端点，并通过 httpClient.fetchWithAuth() 调用。提升权限会绕过 Wix 的权限检查，因此端点必须自行重新检查调用者身份——有关各宿主实际能够验证的内容，以及为何仅所有者可执行的操作应放在仪表板扩展中，请参阅身份验证与授权。

某些扩展或 SDK 调用需要的权限范围，wix generate 不会自动添加。 添加权限范围需要更改 Dev Center 帐户，并非由 Agent 执行——请告知用户要添加哪个权限范围：在 https://manage.wix.com/apps/<appId>/home 打开其应用，在左侧菜单中选择 开发 > 权限，然后选择 添加权限，最后将其报告在需要手动完成的步骤下。如果应用已安装到网站上，所有者还必须通过安装／更新流程重新批准——重新打开同一应用页面的“测试应用”流程（或使用发布输出中的安装链接），然后接受“同意并更新”——该权限范围才会在该网站上生效。

---

App Market 审核

当用户希望将其应用提交到 Wix App Market、公开上架、准备 App Market 审核、评估被拒风险，或处理 App Market 审核反馈时适用。 私有应用或常规版本发布无需执行此流程。

请阅读 APP_MARKET_REVIEW.md——其中包含完整的技术检查清单、带有 Wix 文档链接的实现说明，以及便于追踪的审核分类 ID。

---

实现工作流

第 1 步：提出澄清问题（如有需要）

只有在绝对有必要继续实施时，才询问配置值。如果某个值可以稍后配置或作为手动步骤添加，就不要因此阻塞工作。

如果对实现方式（位置、可见性、配置、集成）不明确，请提出澄清问题。如果答案可能改变扩展类型，就先等待回复再继续。否则，选择最合适的扩展类型继续执行。

第 2 步：提出建议

使用“扩展类型参考表”和上文的决策内容。说明扩展类型并简要解释理由（位置、功能、集成）。

第 3 步：阅读扩展参考文档，检查 API 参考文档，然后按需发现

工作流：阅读扩展参考文档 → 检查 API 参考文档 → 针对垂直领域实体查询 SDK → 仅为查询未输出的内容查阅文档。

1. 阅读上表中所选扩展类型的参考文件
2. 根据用户需求确定所需的 API
3. 检查相关 API 参考文件：
   • 后端事件 → references/backend-event/COMMON-EVENTS.md
   • Wix Data → references/data-collection/WIX_DATA.md
   • Dashboard SDK → references/dashboard-page/DASHBOARD_API.md
   • Service Plugin SPI → 将 references/SERVICE_PLUGIN.md 与匹配的 references/service-plugin/<NAME>.md 叶级文件一起阅读
   • App Tools（AI 助手工具）→ 阅读 references/APP_TOOLS.md；其中链接到 references/app-tools/TOOLS.md（声明）和 references/service-plugin/TOOLS_PROVIDER.md（处理程序）
4. 在参考文档中确认具体方法／事件存在
5. 对于垂直领域实体，运行一次 SDK 查询，并包含所有实体；仅当参考文档和查询都无法解答时，才使用 MCP 发现

平台 API（切勿发现，参考文档中已有）：

• Wix Data、Dashboard SDK、Event SDK（常见事件）、Service Plugin SPI

垂直领域 API（按需发现）：

• Wix Stores（⚠️ 必须使用 Stores Versioning 参考文档——必须检查 V1／V3 目录）、Wix eCommerce、Wix Bookings、Wix Members、Wix Pricing Plans、第三方集成——先在 SDK-First Rule 模块映射表中找到合适的 @wix/* 包并安装，然后通过 SDK 查询获取命名空间和方法

决策表：

用户需求	是否需要检查参考文档／发现？	原因／参考文件
“显示商店商品”	✅ 是（SDK 查询）	Wix Stores API — 包含 Stores Versioning 参考文档
“订单／退款管理面板”	✅ 是（SDK 查询）	Wix eCommerce API（@wix/ecom）——绝不能使用 CMS 集合
“显示预约日历”	✅ 是（SDK 查询）	Wix Bookings API（@wix/bookings）；SPI 叶级文件仅涵盖服务插件
“向用户发送电子邮件”	✅ 是（先进行 SDK 查询，再使用 MCP）	参考文件中没有 Wix Triggered Emails
“获取会员信息”	✅ 是（SDK 查询）	参考文件中没有 Wix Members API
“监听购物车事件”	检查 COMMON-EVENTS.md	仅当参考文档中缺少事件时才使用 MCP 发现
“在集合中存储数据”	WIX_DATA.md ✅ 已找到	❌ 跳过发现（参考文档已涵盖）
“为我的应用创建 CMS 集合”	Data Collection 参考文档	❌ 跳过发现（专门的参考文档已涵盖）
“显示面板提示消息”	DASHBOARD_API.md ✅ 已找到	❌ 跳过发现
“显示提示消息／导航”	DASHBOARD_API.md ✅ 已找到	❌ 跳过发现
“仅涉及 UI（表单、输入框）”	不适用（没有外部 API）	❌ 跳过发现
“带表单输入项的设置页面”	不适用（仅 UI，没有外部 API）	❌ 跳过发现
“带本地状态的面板页面”	不适用（没有外部 API）	❌ 跳过发现

SDK 查询：每个垂直领域实体调用一次

node <this-skill-dir>/scripts/sdk-lookup.cjs contacts orders --intent search   # search | read | write | event | all

在应用目录中运行；垂直领域软件包安装完成后，对此功能涉及的所有实体一次性调用。根据功能只选择一次意图。仪表板集合页面默认会编辑其中的记录（DRAFT_TEMPLATE.md），因此使用 all：这会显示 search 和 write 行，且搜索方法排在前面。仅适用于只读页面时，使用 search（带搜索框）或 read；仅写入的功能则使用 write。不要通过 head 管道传递输出。每个实体会打印：

• 要使用的命名空间及原因（精选规则：在同一软件包中，搜索时优先使用 search* 方法，然后选择最高 API 版本；跨软件包导出同名实体时，使用模块映射所指的软件包，否则使用以该实体命名的软件包），以及其他命名空间——跨软件包时，每个命名空间都会附带实体描述，以便功能匹配其他实体时切换；
• 导入行；
• shape：针对该意图的唯一调用方式及其原因；对于搜索，还会标明搜索词应放在哪里；
• 针对该意图的每个方法，包括其调用形态（search、query-builder、query 等）、权限、必填字段（revision）及文档备注（note，包含更新的字段规则：字段缺失时会发生什么，以及如何清除字段）；当某个选项决定返回哪些字段时，显示 fieldsets（成员默认使用 PUBLIC，不包含 loginEmail 或 contact：请指定包含所有要展示字段的集合）；对于搜索、查询或列表方法，还会显示 arg 和 returns，即参数中的键（cursorPaging、filter、sort、search）以及响应中的键（pagingMetadata.cursors.next）；仅当软件包声明了筛选字段列表时才显示该列表（否则，字段会列在方法文档页面中）——不会显示谁可以调用该方法：这部分仍以身份与权限提升要求为准；
• 实体类型的位置，格式为 file:line——请对照此处的声明核实字段（DATA_SOURCES.md）；
• 每个方法自身声明的位置，格式为 decl file:line——请在此处查看 arg 和 returns 背后的类型，不要通过搜索类型定义来查找；
• 针对该实体的精选规则（note），例如 Stores V1/V3 检查。

使用查询输出中的命名空间、方法和调用形态；不要根据类型定义重新推导，并遵循 shape 下的说明。查询打印 site 时，选择取决于站点（Stores：调用 getCatalogVersion()，并同时支持两个版本）。如果显示 not installed，会打印安装命令：先安装，然后重新运行查询。遇到不认识的名称时会以退出码 1 退出，并提供相近名称。

它会打印每个搜索和查询方法的封闭筛选列表（自由文本字段、每个字段支持的运算符、排序），这些内容来自软件包自身的声明。仅当软件包声明某个方法的权限范围 ID时，才会打印该 ID；如果输出显示 scope: not in the package，请从该方法的文档页面获取权限范围（见下方列表）。

用于发现功能的 MCP 工具（查询未打印的信息）：

• SearchWixSDKDocumentation - SDK 方法和 API（始终使用 maxResults: 5）
• ReadFullDocsMethodSchema - 特定 SDK 方法的完整类型架构（参数、返回类型、权限）
• ReadFullDocsArticle - 仅用于说明性指南和概念性文章（不用于 SDK 方法签名）

步骤 4a：通过 CLI 搭建脚手架

对于每种受支持的类型，包括 HTTP 端点，运行 npx wix generate --params '<json>'。成功时，该命令会返回 {"success":true,"extensionType":"...","newFiles":[...]}。

如果命令因参数未知或无效而失败，请运行 npx wix schema generate --type <extensionType>，打印该扩展类型的 JSON Schema，修正 --params 内容，然后重试。不要改用手动搭建脚手架。唯一的例外是：CLI 版本早于 1.1.243 的 HTTP_ENDPOINT，该版本早于生成器，但仍支持此扩展：请按照 BACKEND_API.md 中的说明手动创建端点文件。

CLI 会自动执行的操作：

• 创建文件夹和存根文件
• 对于已注册的扩展，生成新的 UUID，并在 src/extensions.ts 中更新导入语句和 .use() 调用
• 对于 HTTP 端点，创建路由文件，但不更改 src/extensions.ts
• 强制执行命名规则（kebab-case、要求自定义元素名称包含连字符等）

**HTTP 端点：**运行 npx wix generate --params '{"extensionType":"HTTP_ENDPOINT","name":"hello"}'，然后在返回的文件中实现处理程序。请遵循 BACKEND_API.md；如果路由没有响应，其故障排查提示会说明如何通过构建输出确认是否已发现该路由。

步骤 4b：填充业务逻辑

打开 newFiles 中返回的每个路径，并根据扩展参考文件中的 API 和配置部分，将存根处理程序主体／UI／查询替换为用户的实际逻辑。

• ⚠️ 使用 WDS 时为强制要求：在编辑第一个导入了 @wix/design-system 的 .tsx／.jsx 文件之前，先调用 wix-design-system 技能。对于仅涉及后端或数据的任务，不要提前调用该技能——它会向上下文添加大量你用不到的内容。
• ⚠️ 使用 Data Collections 时为强制要求：使用 idSuffix 中完全一致的集合 ID（区分大小写）。如果 idSuffix 是 "product-recommendations"，请使用 <app-namespace>/product-recommendations，而不是 productRecommendations。

步骤 4c：UX 完整性自检

仅适用于仪表板页面 UI。tsc、wix build 和 wix preview 都会检查代码能否编译和运行，但它们都不会检查页面是否符合 UX Success Model 对仪表板的描述。一个只有未经汇总、无法打开的基础表格的页面，虽然能顺利编译，却仍不符合要求——正是这个差距，导致生成的仪表板通过了所有技术检查，却仍然令人失望。实测结果证实了这一点：页面即使能顺利编译，发布时仍可能完全缺少以下三项内容，因为较早的检查清单条目只表达了预期，并未根据最终实际写入的代码重新检查。

在进入步骤 5 之前，重新打开刚刚编写的每个页面文件，检查实际代码，而不是你原本打算包含的内容：

• 只有在请求要求时，页面才应包含 SummaryBar。 搜索它：未被要求的摘要栏是缺陷，不是额外加分项；修复方法就是删除它。如果请求确实有要求，那么每项指标都必须有其存在的理由，标题统计的应是符合筛选条件的数量（state.collection.total，由 fetchTotal 提供），而不是已分页加载的数量——任何基于 keyedItems 计算的指标都必须注明这一点。

• 如果 SummaryBar 中的数字由 fetchTotal 提供，就要沿着该函数追踪它调用的函数，并确认该调用会返回总数。 fetchTotal 若解析为 undefined——通常是因为 pagingMetadata.total，而游标分页响应不包含此字段——就会导致摘要栏显示 0，旁边的表格却有一整页数据；而且代码能编译、运行，也能通过清单上的其他所有检查。它必须从计数端点（items.query(id)…count()、垂直服务自身的计数接口，或设置了 returnTotalCount: true 的偏移分页）获取数字；如果 API 没有此类接口，就删除 fetchTotal，并将该指标标注为已加载的行数。请参阅 TABLE_STATE.md。

• 默认情况下，每一行都应打开可编辑的实体页面：onRowClick 调用 navigateToEntityPage，且目标页面包含 EntityPage、可正常使用的表单，以及真正的保存操作。只有符合 DRAFT_TEMPLATE.md 中列出的三种情况之一，才有理由使用只读路由；最终回复中必须注明适用的是哪一种。仅用于报告或导出的请求无需进入详情页。保存操作应调用源数据的真实更新方法，并允许调用失败时抛出错误，以便页面显示错误——不能是空操作、仅保存到本地状态，或吞掉错误的 catch。如果可以使用 Preview，请修改一个字段、重新加载以确认已保存，再将其改回；否则应说明保存功能未经验证。集合页面文件中出现 SidePanel，正是此处要替换的缺陷。grep -n "<SidePanel" <page files> 应无结果——要匹配 JSX 标签，而非单独的词，否则模板中“绝不使用 SidePanel”的注释也会导致检查失败，诱使他人去“修复”正确代码。

• 工具栏中声明的每个筛选器名称，也必须出现在 fetchData 的查询构造中——如果不确定，请分别在这两个位置搜索名称。

• 表格应连接 errorState——没有它，查询失败就无法与查询缓慢区分，而你刚交付的页面也无法告知你究竟是哪种情况。

• 仅适用于带路由的模板（设置模板除外）——入口文件既要传入 location，也要对其进行保护。 如果缺少 location，或首次渲染时它仍为 undefined，PatternsReactRouter 在打开时就会抛出错误；无论如何，tsc、wix build 甚至构建成功都不会发现问题。两项都不可少——既要有 location={location} 属性，也要用 location ? … : null 将其包起来，因为首次渲染时 observeState 尚未触发。请搜索入口文件，不要依赖记忆：

  grep -n "observeState\|location={location}\|location ?" src/extensions/dashboard/pages/<page>/<page>.tsx  # the file the builder's `component` points at
  

  有 3 处匹配才是正确的。缺少保护曾导致问题实际发布：一次有记录的运行中，页面的接线看似齐全，打开时仍然崩溃；而再次运行同一提示词却生成了可正常工作的页面——因此这类问题会间歇性出现，重新运行并不算检查。

• 页面 API 模块导入的每个 @wix/* 垂直服务都必须是已声明的依赖项，且每个服务的使用范围都必须列在 Manual Steps 下。对次要垂直服务的任何调用（例如补充信息查询、筛选器选项，或将搜索词解析为 ID）都必须经过封装，以便调用失败时仅影响该功能，而不会导致整个页面失败。

如果某项未通过且没有适用的例外，请立即补上缺失内容。不要把“能编译”当成“满足清单要求”——步骤 5 检查前者，此步骤检查后者，两者互不替代。

步骤 5：运行验证

运行下方验证中的四个步骤。验证通过前，请勿向用户报告已完成——如果失败，请修复错误并重新验证，直到通过为止。

步骤 6：报告完成情况

只有验证通过后，才在回复顶部提供一个简洁的摘要部分：

## ✅ Implementation Complete

[1-2 sentence description of what was built]

**Extensions Created:**
- [Extension 1 Name] - [Brief purpose]
- [Extension 2 Name] - [Brief purpose]

**Build Status:**
- ✅ Dependencies: [Installed / status message]
- ✅ TypeScript: [No compilation errors / status]
- ✅ Build: [Completed successfully / status]
- ✅/⚠️ Preview: [Created — Dashboard URL / Failed - reason]

**⚠️ IMPORTANT: [X] manual step(s) required to complete setup** (see "Manual Steps Required" section below)

• 如果无需执行任何手动步骤，请说明：“✅ 无需手动操作——一切就绪！”

步骤 7：列出手动操作事项

列出用户必须执行的所有手动步骤（例如，在 Wix 控制面板中配置设置、启用权限、设置外部服务）。

格式：

## 🔧 Manual Steps Required

The following actions need to be done manually by you:

### 1. [Action Category/Title]
[Detailed description with specific instructions]

### 2. [Action Category/Title]
[Detailed description]

---

扩展注册

对于已注册的扩展，wix generate --params 会自动更新 src/extensions.ts。HTTP 端点无需导入或调用 .use()；运行时会自动发现其文件。有关背景信息、故障排查，以及 src/extensions.ts 内容发生偏差时的手动恢复模式，请参阅 EXTENSION_REGISTRATION.md。

---

验证

所有实现完成后，按顺序执行以下步骤。完整指南请参阅 APP_VALIDATION.md。控制面板页面 UI：先运行步骤 4c 的 UX 完整性自审——以下检查仅验证代码能否运行，不会验证它是否为提示词要求的控制面板。

1. 安装软件包 — 检测包管理器并运行安装命令
2. TypeScript 编译 — npx tsc --noEmit -p .
3. 构建 — npx wix build
4. 预览 — 在前台运行 npx wix preview，不要通过管道传输：该命令会上传内容、输出预览 URL，并自行退出，因此不要使用 timeout、后台运行、sleep 或 | tail。如果 shell 仍将其转入后台，则表示它已停滞：阅读它输出的内容和 .wix/debug.log 一次，然后报告预览未能完成。不要轮询，也不要承诺提供 URL。

如果任何步骤失败，请停止并报告错误。失败时请检查 .wix/debug.log。

---

文档

有关所有扩展类型的 Wix CLI 官方文档链接，请参阅 DOCUMENTATION.md。