A1 Yandex KIT Skills
溝通
在生成任何面向使用者的訊息之前，請完整閱讀並套用
references/merchant-communication.md
的內容。
Yandex KIT（kit.yandex.ru，Beta 版）是 Yandex 的電子商務商店建置平台，本質上是俄羅斯版的 Shopify。其 REST API 是一個伺服器對伺服器的層，用於同步目錄、庫存與價格，並管理商家後端與平台之間的訂單。官方文件為俄文；完整的 OpenAPI 規格（160 個操作）已隨此技能打包在 data/kit_v1.json.gz 中，並可透過以下腳本離線搜尋。
API 基礎知識
- 基礎網址：
https://api.kit.yandex.net，每個路徑都以/v1/為前綴。 - 認證：
Authorization: Bearer <token>（純 HTTP Bearer，非 OAuth）。Token 在商家後台產生：設定 → API → 產生 Token — 該 Token 僅顯示一次，請安全儲存，若遺失則需產生新的。 - 速率限制：每個商店每秒 3 個請求，無配額標頭。超過限制會回傳代碼
LIMIT_EXCEEDED及 HTTP 400（非 429） — 請在客戶端節流，並透過code而非狀態碼來判斷錯誤。 - 錯誤合約：每個錯誤皆為 JSON 格式
{"code", "message", "trace_id"}。錯誤代碼包括：AUTHENTICATION_ERROR(401)、FORBIDDEN_ERROR(403)、VALIDATION_ERROR(400)、LIMIT_EXCEEDED(400)、UNSUPPORTED_MEDIA_TYPE(415)、NOT_FOUND(404)、CONFLICT(409)、UNKNOWN_ERROR(500)。聯繫支援時請引用trace_id。 - 日期時間：全部為 UTC。
- 無沙盒環境：僅限正式環境 — 探索時請優先使用唯讀呼叫，並在每次寫入前仔細確認。
- 分頁：列表端點接受
page+per_page（最多 100 個）查詢參數。 - 內容類型：請求主體為
application/json，但以下 5 個操作使用 JSON Merge Patch (application/merge-patch+json)：UpdateCategory、UpdateCharacteristic、UpdateVariant、UpdateVariantAttachment、UpdateWarehouse— 僅需傳送要變更的欄位。null僅在架構中標記為可為 null 時清除欄位 — 對這些操作而言，只有UpdateCategory的parent_id和file_id是如此；在其他地方使用null會導致驗證失敗（下方的validate.mjs會捕捉到）。POST /v1/files(UploadFile) 和POST /v1/videos(UploadVideo) 為multipart/form-data。 - 批量寫入：
BulkUpdatePrices和BulkUpdateStocks每個請求最多接受 5000 個項目，且為原子操作 — 任何一個無效項目都會拒絕整個批次（400）且不套用任何變更。對於目錄同步，建議優先使用它們而非逐個變體更新。
工作流程
從此技能目錄執行打包的腳本 — 它們是自包含的（Node.js >= 20，內建模組 + 一個捆綁的驗證器，無需 npm install，無需網路）。
-
搜尋你需要的操作：
node scripts/search_docs.mjs "<查詢>" [--tag "<標籤>"] [--limit N]比對操作 ID、路徑、標籤以及俄文的摘要/描述，例如
node scripts/search_docs.mjs "создать товар"。 -
檢查一個操作的完整合約 — 路徑/查詢參數以及完全解引用後的請求/回應架構：
node scripts/search_docs.mjs --operation CreateProduct -
驗證起草的請求主體，在實際發送前離線進行：
node scripts/validate.mjs --operation CreateProduct --body '<json>' # 或：node scripts/validate.mjs --operation CreateProduct --body-file body.json顯示
VALID（退出碼 0）或架構違規列表（退出碼 1）。 -
執行操作：
- 優先使用打包的
mcp-yandex-kitMCP 伺服器：使用專屬工具（請參閱領域技能），否則使用下列的元組三工具； - 任何沒有專用工具的操作：使用
kit_requestMCP 工具 — 它會在發送前根據相同架構驗證主體； - 或直接使用 HTTP：
curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/...（注意每秒 3 個請求的限制）。
- 優先使用打包的
領域技能
當任務明確屬於某個領域時，優先使用專注的技能 — 每個技能都打包了相同的腳本和資料，以及其標籤的端點表格：
a1-yandex-kit-catalog— 商品、變體（SKU、價格、庫存、批量價格/庫存同步）、分類、特性（群組、顏色）、影片、系列、情境系列、徽章。a1-yandex-kit-orders— 訂單、客戶、禮物卡、附加服務（加購）。a1-yandex-kit-promotions— 折扣、優惠碼、優惠碼群組、贈品。a1-yandex-kit-store— 商店設定檔、倉庫、使用者、地理位置、檔案、重新導向、部落格/新聞、通知。a1-yandex-kit-webhooks— Webhook：訂單事件、HTTPS 回呼、簽章密鑰。
相關 MCP 工具
打包的 mcp-yandex-kit MCP 伺服器提供了 70 個工具。精選工具涵蓋日常的目錄/訂單/促銷/商店/Webhook 工作流程（列於領域技能中）；下方的元組三工具則可觸及 所有 160 個操作：
search_operations— 依關鍵字搜尋所有 160 個 Yandex KIT API 操作的完整目錄。get_operation_schema— 依 operationId 取得單一 KIT API 操作的完整元資料：HTTP 方法、路徑、路徑/查詢參數、請求內容類型、分頁資訊，以及請求主體和回應的完全解引用 JSON 架構。kit_request— 逃生艙，可依 operationId 執行任何一個 Yandex KIT API 操作，包括沒有專用工具的操作。