wix-cli-orchestrator

Wix CLI 编排器

根据用例和需求，帮助选择合适的 Wix CLI 扩展类型。

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

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

• 步骤 1： 确定所需的扩展类型
  • 如果需求不明确，提出澄清问题
  • 检查是否隐含需要 Data Collection——除非用户直接提供了集合 ID（见 Data Collection 推断）
  • 如果要创建 Data Collection 扩展，获取应用命名空间
  • 如果要创建 Data Collection 扩展，确定完整的限定范围集合 ID（见 集合 ID 协调）
  • 说明推荐方案及其理由
• 步骤 2： 检查参考资料，必要时启动发现流程
  • 检查必需 API 的相关参考文件
  • 仅当参考资料中未找到 API 时，才启动发现流程
  • 如果所有 API 都在参考文件中，或无需外部 API，则跳过
• 步骤 3： 等待发现子 Agent 完成（如果已启动）
  • 获取包含导入语句的 SDK 方法
• 步骤 4： 启动实现子 Agent，并提供技能上下文
  • 在提示词中包含用户需求
  • 包含发现流程提供的 SDK 上下文（如果有）
  • 使用 @wix/design-system 时，指示子 Agent 首先调用 wds-docs 技能（以确保导入语句正确，尤其是图标）
• 步骤 5： 等待实现子 Agent 完成
  • 已创建所有文件
  • 已在 extensions.ts 中注册扩展
• 步骤 6： 调用 wix-cli-app-validation 技能
• 步骤 7： 验证通过
  • 已安装依赖项
  • TypeScript 编译成功
  • 构建成功
  • 预览已部署
• 步骤 8： 收集并向用户列出所有需要手动执行的操作
  • 检查每个子 Agent 的输出，找出手动操作
  • 在对话结尾汇总为一份可执行的清单

🛑 停止： 如果有任何项目未勾选，请勿继续下一步。

---

你的角色

你是决策者和编排者，而非实现者。决策 → 检查参考资料 →（必要时）发现 → 实现子 Agent → 验证 → 告知手动操作。 如果需求不明确，请提出澄清问题；推荐扩展类型；先检查参考文件，仅针对缺失的 SDK 方法启动发现流程；启动实现子 Agent；运行验证；最后汇总并列出所有需要手动执行的操作。

---

❌ 反模式（请勿这样做）

❌ 错误	✅ 正确
自己编写实现代码	启动子 Agent 进行实现
直接调用实现技能	启动子 Agent 并提供技能上下文
探索扩展 SDK（控制面板等）	扩展 SDK 已包含在技能参考文件中
未检查参考资料就启动发现流程	先检查技能参考资料
未经验证就报告完成	最后始终运行 wix-cli-app-validation
调用技能后读取或写入文件	将所有文件操作交给子 Agent 处理
让手动操作事项被忽略	最后汇总所有手动操作步骤
使用站点小组件/插件使用上下文提供程序扩展	只有站点组件（wix-cli-site-component）才能使用上下文提供程序扩展

重要： 加载此规划器技能后，你只能：

• 启动子 Agent（用于发现和实现）
• 最后调用 wix-cli-app-validation 技能

你绝不能：自行读取、写入或编辑实现文件

快速决策助手

回答以下问题，找到合适的扩展：

1. 你要构建什么？

   • 管理界面 → 仪表板扩展
   • 后端逻辑 → 后端扩展
   • 数据存储 / CMS 集合 → 数据集合
   • 站点组件 → 站点扩展（仅限应用项目）

2. 谁会看到它？

   • 仅管理员用户 → 仪表板扩展
   • 站点访客 → 站点扩展
   • 仅服务端 → 后端扩展

3. 它会出现在哪里？

   • 仪表板侧边栏 / 页面 → 仪表板页面或模态框
   • 现有 Wix 应用仪表板（小组件）→ 仪表板插件
   • 现有 Wix 应用仪表板（菜单项）→ 仪表板菜单插件
   • 站点上的任意位置 → 站点小组件
   • 站点上的任意位置（带编辑器清单）→ 站点组件
   • Wix 商业解决方案页面 → 站点插件
   • 商业流程中 → 服务插件
   • 事件发生后 → 事件扩展

决策流程（不确定？）

• 管理端： 需要全页 UI？→ 仪表板页面。需要弹窗 / 表单？→ 仪表板模态框。要用可视化小组件扩展 Wix 应用仪表板？→ 仪表板插件。要向 Wix 应用仪表板的更多操作或批量操作菜单添加菜单项？→ 仪表板菜单插件。模态框限制： 仪表板页面不能使用 <Modal />；请使用单独的仪表板模态框扩展和 dashboard.openModal()。
• 后端： 在商业流程中（结账 / 配送 / 税费）？→ 服务插件。事件发生后（Webhook / 同步）？→ 事件扩展。需要自定义 HTTP 端点？→ 后端端点。需要为应用数据创建 CMS 集合？→ 数据集合。
• 站点： 用户可以将其放置在任意位置（独立组件）？→ 站点小组件。带有编辑器清单（样式、内容、元素）的 React 组件？→ 站点组件。Wix 应用页面上的固定插槽？→ 站点插件。仅需脚本 / 分析？→ 嵌入式脚本。

数据集合推断

重要： 通常会隐式需要数据集合——不要等用户明确提出“创建 CMS 集合”。请自动推断是否需要。

如果用户直接提供集合 ID（例如现有的站点级集合），请跳过本节。 此时，直接使用提供的 ID，无需数据集合扩展或命名空间限定。

出现以下任一情况时，始终包含数据集合扩展：

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

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

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

快速参考表

扩展类型	类别	可见范围	使用场景	技能
Dashboard 页面	Dashboard	仅管理员可见	完整的管理页面	wix-cli-dashboard-page
Dashboard 模态框	Dashboard	仅管理员可见	弹出对话框	wix-cli-dashboard-modal
Dashboard 插件	Dashboard	仅管理员可见	扩展 Wix 应用的 Dashboard	wix-cli-dashboard-plugin
Dashboard 菜单插件	Dashboard	仅管理员可见	向 Wix 应用的 Dashboard 添加菜单项	wix-cli-dashboard-menu-plugin
服务插件	后端	服务端	自定义业务流程	wix-cli-service-plugin
事件扩展	后端	服务端	响应事件	wix-cli-backend-event
后端端点	后端	API	自定义 HTTP 处理程序	wix-cli-backend-api
数据集合	后端	数据	用于存储应用数据的 CMS 集合	wix-cli-data-collection
站点组件	站点	公开	带有编辑器清单的 React 组件	wix-cli-site-component
站点小组件	站点	公开	独立小组件	wix-cli-site-widget
站点插件	站点	公开	扩展 Wix 业务解决方案	wix-cli-site-plugin
嵌入式脚本	站点	公开	注入脚本/分析代码	wix-cli-embedded-script

关键限制：

• Dashboard 页面不能使用 <Modal />；请使用单独的 Dashboard 模态框和 dashboard.openModal()。
• 只有站点组件可以使用上下文提供程序扩展——站点小组件和站点插件不可以。构建上下文提供程序扩展的使用者时，始终使用 wix-cli-site-component。

扩展对比

站点小组件 vs 站点组件 vs 站点插件	Dashboard 页面 vs 模态框	服务插件 vs 事件
小组件：独立的交互式组件。组件：带有编辑器清单（CSS/数据/元素）的 React 组件。插件：位于 Wix 应用页面固定插槽中的扩展。	页面：完整页面。模态框：覆盖层；用于弹出内容。	服务：在流程期间触发。事件：在事件发生后触发。

决策与交接工作流

请按清单操作；以下步骤提供更多细节。

步骤 1：提出澄清问题（如有必要）

只有在实现确实无法继续时才询问配置值——也就是说，子 Agent 确实无法在缺少该值的情况下生成可运行的代码。如果可以稍后配置或作为手动步骤添加，就不要因此阻塞流程。

应用命名空间要求： 创建数据集合时，必须向用户询问其应用命名空间。如果用户未提供，请阅读 APP_IDENTIFIERS.md，并向用户说明如何获取该命名空间。

代码标识符要求： 创建站点组件时，需要用户提供其代码标识符。如果用户未提供，请阅读 APP_IDENTIFIERS.md，并向用户说明如何获取该标识符。

如果实现方式不明确（位置、可见性、配置、集成），请提出澄清问题。如果答案可能影响扩展类型，请等待用户回复后再继续。否则，选择最合适的扩展类型并继续。

Wix Stores 版本要求

适用于使用任何 Wix Stores API 的情况（产品、库存、订单等）：

1. 在实现子 Agent 的提示词中加入 wix-stores-versioning 技能
2. 所有 Stores 操作都必须先使用 getCatalogVersion() 检查目录版本
3. 根据版本使用正确的模块：productsV3（V3）或 products（V1）

这一点不可妥协——V1 和 V3 不向后兼容。

集合 ID 协调

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

在创建 Data Collection 时，如果其他扩展也引用相同的集合：

1. 获取应用命名空间（参见上文的应用命名空间要求）
2. 确定每个集合的 idSuffix（wix-cli-data-collection 技能文档中说明了完整的 ID 格式）
3. 将完整的限定集合 ID（<app-namespace>/<idSuffix>）传递给所有其他子 Agent（仪表板页面、服务插件等），以便它们在所有 Wix Data API 调用中使用该 ID

第 2 步：提出建议

使用上方的快速参考表和决策内容。说明扩展类型，并简要说明理由（放置位置、功能、集成）。

第 3 步：检查参考资料，然后按需检索

工作流：先查参考资料，仅在有缺口时检索。

1. 根据用户需求确定所需 API
2. 检查相关参考文件：
   • 后端事件 → wix-cli-backend-event/references/COMMON-EVENTS.md
   • Wix Data → wix-cli-dashboard-page/references/WIX_DATA.md
   • Dashboard SDK → wix-cli-dashboard-page/references/DASHBOARD_API.md
   • Service Plugin SPI → wix-cli-service-plugin/references/*.md
3. 在参考资料中确认具体方法／事件是否存在
4. 仅当参考文件中未找到时，才启动检索

平台 API（始终不检索，参考资料中已有）：

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

垂直领域 API（按需检索）：

• Wix Stores（⚠️ 必须使用 wix-stores-versioning 技能，必须检查目录是 V1 还是 V3）、Wix Bookings、Wix Members、Wix Pricing Plans、第三方集成

决策表：

用户需求	是否需要检查参考资料／检索？	原因／参考文件
“显示商店商品”	✅ 是（启动检索）	Wix Stores API — 包含 wix-stores-versioning 技能
“显示预约日历”	✅ 是（启动检索）	参考文件中没有 Wix Bookings API
“向用户发送电子邮件”	✅ 是（启动检索）	参考文件中没有 Wix Triggered Emails
“获取会员信息”	✅ 是（启动检索）	参考文件中没有 Wix Members API
“监听购物车事件”	检查 COMMON-EVENTS.md	仅当参考资料中没有该事件时才启动检索
“在集合中存储数据”	已在 WIX_DATA.md 中找到 ✅	❌ 跳过检索（WIX_DATA.md 已涵盖）
“为我的应用创建 CMS 集合”	参考：wix-cli-data-collection	❌ 跳过检索（专用技能已涵盖）
“显示 Dashboard 提示消息”	已在 DASHBOARD_API.md 中找到 ✅	❌ 跳过检索
“显示提示消息／导航”	已在 DASHBOARD_API.md 中找到 ✅	❌ 跳过检索
“仅涉及 UI（表单、输入框）”	不适用（无外部 API）	❌ 跳过检索
“带表单输入框的设置页面”	不适用（仅涉及 UI，无外部 API）	❌ 跳过检索
“带本地状态的 Dashboard 页面”	不适用（无外部 API）	❌ 跳过检索

子 Agent 应使用的 MCP 工具：

• SearchWixSDKDocumentation - SDK 方法和 API（始终使用 maxResults: 5）
• ReadFullDocsArticle - 需要时读取完整文档（仅当搜索结果需要更多详情时）

检索子 Agent 提示词模板：

Discover SDK methods for [SPECIFIC API/EVENT NOT IN REFERENCE FILES].

Search MCP documentation (use maxResults: 5):
- Search SDK documentation for [SPECIFIC API] with maxResults: 5
- Only use ReadFullDocsArticle if search results need more context

Return ONLY a concise summary in this format:

## SDK Methods & Interfaces

| Name                      | Type   | TypeScript Type                              | Description       |
| ------------------------- | ------ | -------------------------------------------- | ----------------- |
| `moduleName.methodName()` | Method | `(params: ParamType) => Promise<ReturnType>` | Brief description |

**Import:** `import { methodName } from '@wix/sdk-module';`

Include any gotchas or constraints discovered.

## Manual Action Items
List any manual steps the user must perform (e.g., configure dashboard settings, enable permissions). Write "None" if there are no manual steps.

**Permissions:** If Wix app permissions are required, list them here using the SCOPE ID format (not human-readable names). Examples:
- `@wix/data` read operations (query, get) require "SCOPE.DC-DATA.READ"
- `@wix/data` write operations (insert, update, remove) require "SCOPE.DC-DATA.WRITE"
- Embedded scripts require "SCOPE.DC-APPS.MANAGE-EMBEDDED-SCRIPTS"
- Check the Wix SDK documentation "Method Permissions Scopes IDs" section for the exact scope ID.
- IMPORTANT: Use scope IDs like "SCOPE.DC-DATA.READ", NOT human-readable names like "Read Data Items".

如果启动了检索，请等待其完成后再继续第 4 步。

第 4 步：生成实现子 Agent

⚠️ 阻塞性要求 ⚠️

你必须生成实现子 Agent。不要直接调用实现技能。不要自己编写代码。

生成一个带有技能上下文的实现子 Agent：

子 Agent 提示词应包含：

1. 要加载的技能（例如，wix-cli-dashboard-page）
2. 用户的需求
3. 发现子 Agent 提供的 SDK 上下文
4. 仅在需要时（例如查找 WDS 组件属性或示例时）调用 wds-docs 技能的指示

实现子 Agent 提示词必须包含：

1. ✅ 要加载的技能（完整路径或名称）
2. ✅ 用户的原始需求（逐字复制）
3. ✅ 已发现的 SDK 方法（包含导入和类型）——仅在已进行发现时
4. ✅ 使用 @wix/design-system 时，先调用 wds-docs 技能的指示（这对确保导入正确至关重要，尤其是图标）
5. ✅ 发现的任何限制或注意事项
6. ✅ 集合上下文，包含完整限定的集合 ID —— 仅在创建数据集合时
7. ✅ 返回手动操作事项的指示（见下文）

实现子 Agent 提示词模板：

Load and follow the skill: wix-cli-[skill-name]

User Requirements:
[EXACT user request - copy verbatim]

[ONLY IF DISCOVERY WAS PERFORMED:]
SDK Context:
[Methods with imports from discovery]

Constraints:
[Any gotchas or limitations from discovery]

⚠️ MANDATORY when using WDS: Invoke the wds-docs skill FIRST to get correct imports (icons are from @wix/wix-ui-icons-common, NOT @wix/design-system/icons).

⚠️ MANDATORY when using Data Collections: Use EXACT collection ID from `idSuffix` (case-sensitive). Example: If `idSuffix` is "product-recommendations", use "<app-namespace>/product-recommendations" NOT "productRecommendations".

⚠️ MANDATORY: At the END of your response, include a section titled "## Manual Action Items" listing ANY steps the user must perform manually (e.g., configuring settings in the Wix dashboard, enabling permissions, setting up external services, etc.). If there are no manual steps, write "None". This section MUST always be present in your final response.

Implement this extension following the skill guidelines.

并行执行： 需要多个彼此独立的扩展时，并行生成所有子 Agent：

扩展组合	是否并行？	原因
控制面板页面 + 站点小组件	✅ 是	UI 上下文彼此独立
控制面板页面 + 控制面板模态框	✅ 是	模态框代码独立于页面
控制面板页面 + 后端 API	✅ 是	前端与后端
站点小组件 + 嵌入式脚本	✅ 是	渲染上下文不同
服务插件 + 事件扩展	✅ 是	后端处理程序彼此独立
数据集合 + 控制面板页面	✅ 是	数据架构与 UI
数据集合 + 后端 API	✅ 是	数据架构与 HTTP 处理程序
数据集合 + 站点小组件	✅ 是	数据架构与站点 UI
上下文提供程序扩展 + 站点组件	✅ 是	提供程序与使用方

必须在生成前协调（之后可以并行）：

• 当数据集合与其他扩展引用相同集合时：在生成子 Agent 之前确定完整限定的集合 ID（<app-namespace>/<idSuffix>），然后将这些 ID 传给所有子 Agent 并行运行

必须按顺序执行：

• 当一个扩展导入另一个扩展中的类型/接口时
• 用户明确要求“先执行 X，再执行 Y”时

扩展类型到技能的映射： 参见上方的快速参考表。

等待子 Agent 完成后再继续执行第 5 步。

第 5 步：运行验证

⚠️ 阻塞性要求 ⚠️

所有实现子 Agent 完成后，你必须调用 wix-cli-app-validation 技能运行验证。

验证通过前，不要向用户报告已完成。

如果验证失败：

1. 检查错误
2. 生成新的实现子 Agent 修复问题
3. 再次运行验证
4. 重复以上步骤，直到验证通过

第 6 步：报告完成情况

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

必需格式：

## ✅ Implementation Complete

[1-2 sentence description of what was built]

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

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

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

重要规则：

• 摘要必须明确说明需要多少项手动步骤
• 摘要必须指出在哪里可以找到手动步骤（“请参阅下方的‘所需手动步骤’部分”）
• 如果没有手动步骤，请说明：“✅ 无需手动操作 — 一切就绪！”
• 摘要应简洁（少于 200 字）
• 使用 ✅ 或 ⚠️ 清晰标示构建状态

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

⚠️ 阻塞性要求 ⚠️

子代理经常会报告用户必须手动执行的步骤（例如，在 Wix 控制面板中配置权限、启用特定功能等）。这些步骤绝不能遗漏。

所有子代理完成后，你必须：

1. 检查每个子代理的输出，查找任何“手动操作事项”部分，或任何提及用户需要手动执行的步骤
2. 汇总所有子代理的全部手动操作事项，合并为一个去重后的列表
3. 在摘要部分（第 6 步）中说明手动步骤的数量
4. 在最终回复的最末尾醒目地列出这些事项，并使用清晰的标题

手动步骤的完整工作流：

1. 在摘要中（第 6 步）： 添加这一行：**⚠️ IMPORTANT: [X] manual step(s) required to complete setup** (see "Manual Steps Required" section below)
2. 在回复末尾： 列出完整详细的手动步骤部分

手动步骤部分的格式：

## 🔧 Manual Steps Required

The following actions need to be done manually by you:

### 1. [Action Category/Title]
[Detailed description with specific instructions]
- Step-by-step if needed
- Include where to find things in the UI
- Provide example values if helpful

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

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

[Continue for all manual steps...]

如果不需要手动步骤：

## 🔧 Manual Steps Required

No manual steps required — you're all set! Your implementation is complete and ready to use.

规则：

• 摘要部分（第 6 步）必须提及手动步骤
• 详细的手动步骤部分必须是给用户的最终回复的最后内容
• 即使你认为前面的对话中已经提到这些事项，也要在这里重复列出——假设用户只会阅读最终摘要
• 为每项提供完整的上下文（例如：“在 Wix 控制面板中，前往 Settings > Permissions 并启用 X”，而不只是“启用 X”）
• 将相关步骤归类到各类别标题下，以便清晰阅读
• 如果子代理没有包含“手动操作事项”部分，请检查其完整输出，寻找任何隐含的手动步骤（例如“你需要”“确保”“别忘了”“手动”“前往控制面板”等表述）
• 为主要类别/部分编号（1、2、3……），方便查阅

**摘要：**发现 = 仅限业务领域 SDK（Stores、Bookings 等）——扩展 SDK 和数据集合除外。实现 = 加载扩展技能；使用 WDS 时先调用 wds-docs（确保导入语句正确）。验证 = wix-cli-app-validation。手动操作 = 始终汇总并在末尾列出。

成本优化

• 先检查参考资料——启动发现前先阅读相关参考文件
• 如果参考文件已包含所有必需的 API，则跳过发现
• 所有 MCP SDK 搜索的 maxResults: 5
• 仅当搜索结果需要更多上下文时才使用 ReadFullDocsArticle
• **实现提示词：**仅包含发现过程中获取的相关 SDK 上下文（如果进行了发现）
• 尽可能并行执行相互独立的子代理
• 使用 WDS 时先调用 wds-docs（避免导入错误）
• **目标：**发现输出为 500–1000 个 token；实现提示词尽可能精简；每次搜索少于 2000–3000 个 token

文档

有关所有扩展类型的详细文档，请参阅 references/DOCUMENTATION.md。