wix-docs

Wix 文档 — 查询 Wix API/SDK 文档

准确了解 Wix API 的真实情况——端点、HTTP 方法、请求/响应正文、字段、枚举或错误。绝不要凭记忆编造 Wix 端点、路径、正文或枚举——请先在这里确认。本技能中的示例端点也不例外：它们仅用于说明机制，可能像任何快照一样过时——依赖之前，请先查明真实契约。

查询流程很短：找到正确页面，然后阅读。 使用 curl（下文默认方式），或使用你的 Agent 配备的 Wix MCP 文档工具（路径 2）。无论哪种方式，都要根据你已掌握的信息选择路径：

• 你有文档 URL → 直接阅读 (§2)。不要重新搜索已经知道 URL 的页面。
• 多步骤工作流（“从服务设置到付款，完成一次预约”）→ 在搜索中纳入配方语料库：将 document_types: ["SKILLS", …] 与步骤所属的 API 语料库一同传入 (§1A)。配方包含步骤顺序、跨步骤注意事项，以及一个即可完成全部工作的组合端点——这些内容不会出现在任何单独的方法页面中。如果没有找到相关配方 → 使用同一组结果中经过验证的各方法契约来编排工作流。
• 某个具体操作、字段或枚举 → 搜索其 API 语料库（REST / SDK），然后阅读你找到的页面或检查其架构。

路径 1 — curl（默认方式）

文档是由 Markdown 页面构成的单一树：在任何 https://dev.wix.com/docs/… URL 后面附加 .md，即可获取该页面的 Markdown。无需 SDK，也无需 MCP。

1. 查找页面 — 搜索、浏览或查询索引

找到正确页面有三种方式——选择适合当前需求的方式。

A. 语义搜索。 用自然语言描述你想做什么（“允许客户预约”），不要只用关键词；搜索结果会按相关性排序。两个变体使用相同的 POST 正文：search_term（必填，1–500），以及 document_type（单个语料库）或 document_types（数组——可在一次排序搜索中查询多个语料库）二者之一；maximum_results（1–20，默认 15，在合并结果集中计数），lines_in_each_result（0–200，默认 20；0 = 不限制每条结果的行数）。语料库：REST（默认）· SDK · SKILLS · WIX_HEADLESS · BUSINESS_SOLUTIONS · VELO · WDS · BUILD_APPS · CLI · OVERVIEW。SKILLS 是专用的配方语料库——包含单一 API 搜索不会返回的多步骤工作流页面；OVERVIEW 用于了解平台概况（开发方式、API 系列）。

一次调用搜索问题实际涉及的语料库。 服务会将它们一起排序并交错呈现结果，因此不同语料库的结果会根据相关性竞争，而不必由你猜测该先尝试哪个——一次往返即可替代多次查询。语料库组合没有固定规则：根据问题选择即可。document_type 和 document_types 不能同时传入，否则会报错（"Pass either document_type or document_types, not both"）；未知语料库名称会被拒绝，并返回有效列表。

两个变体——根据当前操作选择：

/docs/search/markdown → 阅读结果（从这里开始）。 返回包含单个 content 字段的 JSON，该字段中是适合大模型使用的 Markdown 字符串（使用 jq -r '.content' 提取），每条结果都是一份精简的方法文档：包括 API 端点、真实请求代码示例、响应结构和方法说明（含注意事项）。搜索结果是预览，而非完整页面：精简格式对每个部分都设有固定限制，因此提高 lines_in_each_result 不会扩展每个部分；0 也只是取消每条结果的行数限制——绝不会还原完整的源页面。在基于搜索结果进行开发之前，请确认信息是否足够：是否有必需输入、适用于当前情况的条件，以及所需的 REST 契约或 SDK 签名？如果有，就可以继续——无需额外获取内容。如果没有，请进行一次有针对性的后续查询：阅读方法页面 (§2) 或获取其架构 (§C)。

curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown' \
  -H 'Content-Type: application/json' \
  --data-raw '{"search_term":"create a booking","document_type":"REST","maximum_results":3}' \
  | jq -r '.content'      # no jq? → python3 -c 'import sys,json;print(json.load(sys.stdin)["content"])'

横跨一个工作流及其各个调用的问题，需要同时查询两类语料——流程说明和每种方法的契约会一并出现在排名列表中：

curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown' \
  -H 'Content-Type: application/json' \
  --data-raw '{"search_term":"end to end booking flow","document_types":["SKILLS","REST"],"maximum_results":6}' \
  | jq -r '.content'

/docs/search（JSON）→ 据此路由。 返回 { results: [ { title, url, content, relevance_score, kb_name, … } ] }——结构化的命中结果。需要以编程方式选择/路由时使用：获取某条命中结果的 url，以读取对应页面（§2），或将其传给架构查询（§C）。

kb_name 会告诉你每条命中结果的类型——每条结果都包含此字段，而类型决定了你能对它做什么：只有方法页面才有可提取的架构（§C）；文章或流程说明则应作为正文阅读（§2）。

请求无法替你区分类型。语料会混合多种类型——搜索 API 参考会同时返回方法页面及其周边的正文内容——而且没有任何语料只包含方法页面。因此，请用 document_types 选择语料，再根据 kb_name 区分返回的类型。不要用以下两种方式代替：不要根据是否存在 url 来推断类型（每条结果都有 url，包括文章和流程说明），也不要根据请求的语料来推断类型。

大多数值会标明类型（方法页面使用 …_METHODS_…，正文内容使用 …_DOCS_…，流程说明使用 SKILLS_KB_ID），但并非全部如此——SDK 的方法索引是 API_REFERENCE_SDK_KB_ID。因此，请列出搜索实际返回的标签，再据此操作，而不是根据名称匹配模式或对 ID 列表进行硬编码。

# see what came back — label, title, url
curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search' \
  -H 'Content-Type: application/json' \
  --data-raw '{"search_term":"end to end booking flow","document_types":["REST","SKILLS","WIX_HEADLESS"],"maximum_results":10}' \
  | jq -r '.results[] | "\(.kb_name)\t\(.title)\t\(.url)"'
# no jq? → python3 -c 'import sys,json;[print(r.get("kb_name"),r["title"],r.get("url")) for r in json.load(sys.stdin)["results"]]'

# then take the kind you need, by the label you just saw
… | jq -r '.results[] | select(.kb_name == "REST_METHODS_KB_ID") | "\(.title)\t\(.url)"'

B. 将文档树用作菜单来浏览。 有两种方式：适用于受支持门户的结构化浏览端点（在这些门户中优先使用——有类型信息、计数且可筛选），以及适用于任何界面的 .md 菜单树，也可用于阅读页面。

B1. 结构化浏览——受支持的门户。 POST /mcp-docs-search/v1/docs/menu/browse 遍历门户的树，并返回每个子项及其类型、HTTP 动词（适用于方法）和子树计数（“Catalog V3 — 121 methods, 32 articles”），让你可以根据结构选择合适的区域——只需约 2 KB，无需处理约 40 KB、还得用 grep 搜索的菜单页面。使用 include、name_filter 和 depth 可直接跳转到所需内容。

门户（document_type）：REST（默认值——api-reference 门户）· FRONTEND_SDK（sdk）· CLI（wix-cli）· BUILD_APPS（build-apps）· WIX_HEADLESS（go-headless）。仅在浏览功能中，SDK 是 REST 的别名（API 参考中的每个页面都会说明两种视图）——它不会选择 FRONTEND_SDK，而且此别名不适用于语义搜索。若要查找门户中的区域，请省略 menu_url——这样会返回门户根目录；将受支持门户的 URL 传给 menu_url 也会自动推断门户。

请求体：menu_url?（绝对文档 URL；省略时返回门户根目录）、document_type?、depth?（1，最大值为 6）、include?（CATEGORY·RESOURCE·METHOD·ARTICLE·WEBHOOK·OBJECT·SKILL）、deprecated?（默认值为 HIDE·SHOW·ONLY）、name_filter?、max_nodes?、format?（默认值为 MARKDOWN → content 字符串；STRUCTURED → JSON 树，包含 url/http_method/resource_id/child_counts，以及 counts_by_type、truncated、deprecated_counts_by_type）。

以下两个响应信号应采取相应操作，不要忽略：

• truncated: true——节点数量上限导致列表被截断。应缩小范围，而不是重新读取：浏览更深层的 menu_url、收紧 include/name_filter 条件，或降低 depth。
• 弃用筛选——默认隐藏已弃用条目；deprecated_counts_by_type 会报告被筛除的条目数量。浏览结果中缺少某个 API，可能是因为它已弃用，而非不存在——请用 deprecated: "SHOW"（或 "ONLY"）重新浏览以查看该条目，并遵循文档中提供的替代项指引。

# a vertical's structure, with per-child subtree counts
curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse' \
  -H 'Content-Type: application/json' \
  --data-raw '{"menu_url":"https://dev.wix.com/docs/api-reference/business-solutions/stores"}' \
  | jq -r '.content'

# jump straight to a method by name — no multi-level grep
curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse' \
  -H 'Content-Type: application/json' \
  --data-raw '{"menu_url":"https://dev.wix.com/docs/api-reference/business-solutions/bookings","include":["METHOD"],"name_filter":"cancel","depth":4}' \
  | jq -r '.content'

# a non-REST portal: the CLI docs, from the portal root
curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse' \
  -H 'Content-Type: application/json' \
  --data-raw '{"document_type":"CLI","depth":2}' | jq -r '.content'

仅用于浏览：它会提供页面的 URL——在末尾添加 .md 来读取页面（§2），并通过 §C 获取确切的架构。 B2. .md 菜单树——适用于任何界面，以及如何阅读页面。 每个文档路径都有对应的 .md 文件，因此无需依赖即可浏览任何界面；对于结构化浏览未覆盖的界面（例如 Velo），以及阅读叶子页面，都可以使用它。curl https://dev.wix.com/docs/llms.txt 是顶层地图；其下的入口如下：

入口	从这里开始
api-reference.md	所有后端／业务解决方案 API——主要入口。 每个页面都介绍其 REST 和 SDK 用法（SDK 视图见 .md?apiView=SDK）。
sdk.md	**API 参考中没有的 SDK 专属界面：**客户端设置（createClient、OAuthStrategy）、核心模块（@wix/sdk、@wix/essentials）、宿主模块（dashboard／editor／site）以及前端模块（members、pay、seo、storage、pricing-plans，等等）。
go-headless.md	Headless 设置、身份验证、托管、框架集成。
build-apps.md	构建 Wix 应用／扩展。
wix-cli.md · velo.md	Wix CLI 命令；Velo 站点编码 API。

像浏览菜单一样逐层深入——在任何路径后追加 .md（章节 → 子链接菜单，叶子页面 → 内容／方法页面）；截短路径向上返回，延长路径向下深入。也要阅读同级的简介／“关于……”／流程文章，不要只看方法页面。示例——逐个搜索菜单中的下一个链接，深入到创建预订方法：

curl -sS https://dev.wix.com/docs/api-reference/business-solutions.md            | grep -i bookings   # → .../bookings.md
curl -sS https://dev.wix.com/docs/api-reference/business-solutions/bookings.md   | grep -iE 'bookings|flow'  # → resource/flow pages
curl -sS https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings.md | grep -i create      # → the create method leaf
curl -sS https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md  # read it

API 参考入口的两级地图（涵盖所有垂直领域，向下一级）见 references/EXTRACTING.md。

C. 查询 API 索引——一次调用，结构化结果。 code-mode 搜索端点会对 lightIndex（完整 REST API 规范：包含每个资源和方法及其 operationId、httpMethod、menuPath、docsUrl 和可执行的 publicUrl）运行 JS 函数。适用于需要以编程方式枚举／筛选方法的场景——浏览某个垂直领域，或搜索所有方法——并一次性返回 docsUrl 和 publicUrl，无需逐层浏览菜单：

# pinpoint a method by keyword across the whole index → its docsUrl + executable publicUrl
curl -sS -X POST 'https://mcp.wix.com/api/code-mode/search' -H 'Content-Type: application/json' \
  --data-raw '{"code":"async function(){ return lightIndex.flatMap(r=>r.methods).filter(m=>/createBooking$/i.test(m.operationId)).map(m=>({op:m.operationId, httpMethod:m.httpMethod, publicUrl:m.publicUrl, docsUrl:m.docsUrl})); }"}'

缩小筛选范围，只返回所需字段——索引很大，未经筛选的转储内容会非常多。范围：REST 界面。lightIndex 为 REST 方法建立索引；同级的 articles 索引，以及 getArticleContentByUrl(docsUrl)／getArticleContent(resourceId)，则涵盖 REST 入口中的文字内容（简介、操作指南、流程页面）。这里不包含 SDK 专属界面和其他入口——请使用 A／B；另请注意，返回的架构是 REST 合约，而非 SDK 签名（同一方法的 SDK 视图位于其文档页面，§2）。更多示例（浏览垂直领域、遍历 menuPath、资源架构）以及架构／文章读取器，请参阅 references/API_SPEC_SEARCH.md。

如果有 Wix MCP，它会将这些相同功能作为原生工具提供（无需 curl／JSON 样板代码）——路线 2。

2. 阅读你打开的页面

在 URL 后附加 .md，会得到三种页面之一。先判断你看到的是哪种页面，再采用相应的处理方式：

• 菜单页 — 一个 section 路径（通过浏览找到，§1B）。页面列出子链接，内容通常有几十 KB —— 不要通读；用 grep 搜索你要的子页面，然后深入阅读：

  curl -sS 'https://dev.wix.com/docs/api-reference/business-solutions/bookings.md' | grep -i 'booking'
  

• 文章／指南 — 介绍、概念、示例流程页面。Markdown 正文通常较短 —— 通读全文：

  curl -sS 'https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/introduction.md'
  

• 方法页 — 一个 API 方法，也是内容最庞大的页面：包含 REST 和 JavaScript SDK 两个部分、完整的请求／响应架构，以及代码示例，通常有 100 KB 以上。不要一口气读完整页 —— 先梳理页面结构，再提取所需部分（通常代码示例就足以了解如何调用）：

  curl -sS "$URL.md" | grep -nE '^#{1,3} '                                              # 1. map the outline
  curl -sS "$URL.md" | awk '/^## REST API/{r=1} r&&/^### Examples/{f=1} /^## JavaScript SDK/{f=0} f'  # 2. just the REST examples
  curl -sS "$URL.md" | grep -nE 'name: (selectedPaymentOption|totalParticipants)'       # 3. grep specific schema fields
  

  更多提取方法（拆分 REST 与 SDK、解析枚举）→ references/EXTRACTING.md。

  若要获取准确的结构化架构和枚举值，不要手动截取 Markdown —— 使用 curl POST 请求查询 API 规范：https://mcp.wix.com/api/code-mode/search（无需 MCP 即可实现 MCP SearchWixAPISpec 的等效功能）。code 是一个作用域中包含 lightIndex 和 getResourceSchemaByUrl(docsUrl) 的 JS 函数；只返回所需内容。

  getResourceSchemaByUrl 会将查询范围限定为传入的 URL：传入方法 URL会返回一个架构，其中的 methods 数组仅包含该方法 —— 读取 methods[0]，不要通过将 m.docsUrl 与输入进行比较来选择它（读取器会规范化 URL）。传入资源 URL（即删去方法 URL 最后一个路径段）会返回整个资源 —— 需要查看同级操作或共享资源上下文时，获取此 URL。

  # find a method by keyword → its docsUrl + executable publicUrl
  curl -sS -X POST 'https://mcp.wix.com/api/code-mode/search' -H 'Content-Type: application/json' \
    --data-raw '{"code":"async function(){ return lightIndex.flatMap(r=>r.methods).filter(m=>/createBooking$/i.test(m.operationId)).map(m=>({op:m.operationId, httpMethod:m.httpMethod, publicUrl:m.publicUrl, docsUrl:m.docsUrl})); }"}'
  
  # a METHOD URL → that one method's contract (resolve $circular refs via s.components.schemas)
  curl -sS -X POST 'https://mcp.wix.com/api/code-mode/search' -H 'Content-Type: application/json' \
    --data-raw '{"code":"async function(){ const s=await getResourceSchemaByUrl(\"https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking\"); const m=s.methods[0]; return { publicUrl:m.publicUrl, requestBody:m.requestBody, responses:m.responses }; }"}'
  

  响应封装格式为 { "result": … } 或 { "error": "<message>" } —— 两者的 HTTP 状态码都是 200，因此要检查响应正文，而不是状态码。错误文本会说明如何修正：如果是文章 URL → 改用 getArticleContentByUrl；如果是未知 URL → 按关键词搜索 lightIndex。不要重复发送完全相同的失败查询 —— 根据错误调整查询；如果仍无法找到，请说明这一限制，而不是猜测接口约定。

  完整示例集（资源列表、部分 URL 解析、枚举／嵌套引用展开）→ references/API_SPEC_SEARCH.md。

Lane 2 — Wix MCP 文档工具（仅当你的 Agent 可使用这些工具时）

如果已连接 Wix MCP，这些工具与 Lane 1 使用相同的后端（文档搜索服务和 API 规范索引），并封装为原生工具 —— 会验证架构、处理响应大小，且无需编写 curl／JSON 样板代码。这只是比 curl 流程更方便，并非更丰富的数据源；有这些工具时就使用，没有时则回退到 Lane 1。此流程为可选项 —— 如果没有这些工具，就跳过此流程。

工具	用途
SearchWixRESTDocumentation	按关键词查找 REST 方法／操作指南
SearchWixSDKDocumentation	查找 SDK 方法（可显示模块菜单中未列出的运行时函数）
SearchWixAPISpec → getResourceSchemaByUrl	结构化架构 —— 使用方法 URL获取该方法的接口约定，使用资源 URL获取整个资源
ReadFullDocsArticle	通读操作指南／流程／文章页面
BrowseWixRESTDocsMenu	浏览菜单树，深入查找方法

• 获取方法以查看其接口约定；获取资源以了解上下文。 方法 URL 会精确返回该方法。如果某项要求可能出现在同级方法中（例如，单条创建方法要求 memberId，但批量创建页面未提及），请改为获取资源 URL —— 资源视图包含该资源下的所有方法以及共享对象架构。
• 此技能顶部的先查操作指南的路由方式也适用于此处：对于多步骤工作流，应先搜索操作指南内容库（许多垂直领域会在 …/business-solutions/<vertical>/skills 节点下发布操作指南），再组合各方法的调用。

.md 后缀

仅在使用 curl 直接请求页面时，才附加 .md。MCP 工具和搜索端点都接受不带 .md 的普通文档 URL —— 绝不要向 MCP 工具传入带 .md 的 URL。

从文档到调用

理解契约是此技能的职责；执行契约则需要身份。方法接受哪些身份，是你需要了解的内容之一——调用前请查看方法页面上的权限和身份说明，并确认令牌的站点／账户范围相符。令牌签发（CLI 管理员令牌、访客令牌）、身份模型以及动态站点上下文报告 → references/CALLING.md。

编写代码前

请在页面上确认，而不要凭记忆判断：端点、HTTP 动词、请求体结构、必填字段以及任何枚举值。然后编写调用。如果你要扩展某个技能自带的客户端，请沿用该技能现有的传输／辅助函数风格；你只是在添加一次调用，而不是重新设计架构。