Bridge

#Overview

SXL Studio Bridge (@sxl-studio/bridge) — это Node.js-процесс, связывающий запущенный плагин SXL Studio в Figma с внешними инструментами (Cursor, AI-клиенты, скрипты, CI). Он поднимает три интерфейса на одном порту (BRIDGE_PORT, по умолчанию 37830):

На практике Bridge даёт единый контролируемый канал для:

• токен- и style-процессов SXL;
• генерации реальных экранов и документации в Figma через SXL agent skills;
• codegen-потока Dev Mode без расхождений;
• git-процессов синхронизации файлов;
• автоматизаций для команд и агентов.

#Когда использовать Bridge

Используйте Bridge, когда нужно запускать функции SXL Studio удалённо (из AI или скриптов), а не только вручную в UI плагина.

Типовые сценарии:

• экспорт/применение tokens и styles;
• генерация/применение composition JSON в bulk;
• сборка/обновление Figma-экранов из существующих компонентов дизайн-системы;
• отрисовка документации, палитр, component docs и scenario flows в Figma;
• получение codegen-выводов (designer-json, vue3, react, swiftui, uikit, kotlin, divkit);
• автоматизация Git pull/push и обновления token-файлов;
• usage, coverage, drift, component и prop analytics в масштабе.

#Требования

Перед использованием Bridge:

1. Установите и запустите @sxl-studio/bridge.
2. Откройте Figma-файл и запустите SXL Studio.
3. Включите Remote Connect в плагине.
4. Держите Bridge запущенным на время выполнения команд.

Git Sync Local Storage — исключение: он использует HTTP endpoints Bridge (/api/status, /api/workspace-blob) и не требует активной websocket-сессии Remote Connect.

#Установка и запуск

npm (рекомендуется)

npm install -g @sxl-studio/bridge
sxl-bridge

Обновление до последней совместимой версии (1.8.9 для SXL Studio Plugin 2.8.1):

npm install -g @sxl-studio/bridge@latest

После обновления перезапустите Bridge: закройте старый процесс и снова выполните sxl-bridge — работающий процесс держит прежнюю версию в памяти. Проверка версии: при запуске Bridge печатает её в консоль, либо выполните curl http://127.0.0.1:37830/api/workspace-path — у 1.8.0+ вернётся JSON с полем root.

Из монорепозитория

cd Utils/bridge
npm install
npm run build
npm start

По умолчанию Bridge работает на порту 37830.

BRIDGE_PORT=38000 sxl-bridge

Если используете нестандартный порт, укажите это же значение в overlay Remote Connect плагина SXL Studio и в URL вашего MCP-клиента.

#Безопасный доступ (рекомендуется)

Чтобы защитить MCP, HTTP и plugin Remote Connect WebSocket endpoints, задайте общий секрет.

BRIDGE_AUTH_TOKEN не выдаётся Figma, GitHub, GitLab или SXL Studio. Это локальный общий секрет: пользователь генерирует его сам и указывает одно и то же значение в Bridge-клиентах.

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# или
openssl rand -hex 32

Запустите Bridge с полученным значением:

BRIDGE_AUTH_TOKEN=<generated_secret> sxl-bridge

Тогда HTTP/MCP клиенты должны передавать:

• Authorization: Bearer <generated_secret>

Для live Remote Connect укажите это же значение в token-поле overlay Remote Connect плагина. Если включён Git Sync Local Storage, также укажите его в форме Sync в поле Bridge Auth Token. Если Bridge запущен без BRIDGE_AUTH_TOKEN, оставьте эти поля пустыми.

#Опциональный Figma REST companion

Для read-only hosted context без активной plugin session запустите Bridge с Figma REST token:

FIGMA_TOKEN=figd_xxx npm start
# или OAuth/plan token через bearer auth
FIGMA_ACCESS_TOKEN=xxx FIGMA_AUTH_MODE=bearer npm start

Сначала вызовите figma_rest_diagnose или GET /api/figma-rest-diagnostics?checks=whoami,fileMetadata&fileKey=..., чтобы проверить token/auth/scopes/permissions без вывода токена. Затем используйте figma_rest_whoami, figma_rest_get_file_metadata, figma_rest_get_file_nodes, figma_rest_get_images, figma_rest_get_file_components, figma_rest_get_file_component_sets, figma_rest_get_file_styles, figma_rest_get_team_components, figma_rest_get_team_component_sets, figma_rest_get_team_styles, figma_rest_get_variables_local, figma_rest_get_variables_published и figma_rest_search_design_system для известных file/team REST reads. Для Figma MCP-style library discovery предпочитайте Bridge get_libraries и search_design_system: они объединяют enabled libraries активного файла с known REST file/team sources, если они настроены. Bridge по-прежнему не создаёт новые файлы и не выполняет FigJam/Slides asset upload. Для Figma Design asset insertion используйте Bridge upload_assets с активной Remote Connect session.

Для библиотек, уже включённых в открытом Figma-файле, get_libraries и search_design_system являются основными agent-facing tools. Используйте search_enabled_library_assets для низкоуровневого enabled-library search, inspect_enabled_libraries для raw enabled descriptors, а list_enabled_library_variables — для переменных конкретной enabled collection. Figma Plugin API не умеет включать библиотеки из кода; Bridge сообщает это ограничение в ответах compatibility tools.

Для screenshots или rendered node images используйте get_screenshot. mode: "plugin-svg" возвращает inline SVG из active-file nodes или текущего selection через Remote Connect. mode: "rest-image" возвращает Figma-hosted PNG/JPG/SVG/PDF URLs для известных fileKey/url + nodeIds через REST Images endpoint.

Для metadata используйте get_metadata. mode: "plugin" возвращает active-file selection/page structure или node tree metadata через Remote Connect. mode: "rest" возвращает hosted file metadata или node metadata для известных fileKey/url и optional nodeIds.

Для active-file design context используйте get_design_context. Он собирает SXL codegen/composition JSON, sparse metadata, native variable/style definitions, optional SVG screenshot и optional local Code Connect suggestions для текущего selection или переданных node ids. Это соответствует intent official MCP get_design_context как structured starting point для агента; это не final production code.

Для Code Connect template/binding context используйте get_context_for_code_connect. Он собирает SXL registry/settings, selection status, existing bindings, SXL codegen/composition context, component discovery с props и local source-file suggestions. Он закрывает active-file/local-codebase часть official MCP workflow get_context_for_code_connect; hosted remote-only context остаётся companion scope official Figma MCP.

Для генерации .figma.ts Code Connect template используйте generate_code_connect_template. Он принимает полный SXL CodeConnectBinding или local targets/component names, по умолчанию возвращает dry-run content/path и пишет файл только при явном writeFile: true. Держите includePropertyAttrs выключенным, пока не проверили, что имена Figma properties совпадают с props code component.

Для variable/style definitions используйте get_variable_defs. mode: "selection" — official-MCP-style route для variables/styles, используемых в текущем Figma Design selection; он читает native boundVariables, text segment bindings, style ids и resolved variable/style definitions через Remote Connect, затем добавляет SXL applied-token metadata как compatibility context. mode: "local" читает active-file local variables/styles; mode: "enabled-libraries" читает variables из libraries, уже enabled в открытом файле; mode: "rest" читает known-file REST variable endpoints.

#Font preflight для migration workflow

Перед migration, rebind, detach или repair-сценариями, которые могут менять текстовые слои, используйте migration_font_preflight.

Figma Plugin API требует загрузить точный шрифт текстового слоя до любого изменения этого слоя. При этом шрифт может быть виден в интерфейсе Figma, но быть недоступным для figma.loadFontAsync() в текущем plugin runtime. Поэтому Bridge даёт read-only preflight: он сканирует текстовые слои, группирует точные пары { family, style }, пробует загрузить их и возвращает отчёт, какие текстовые слои будут заблокированы.

Пример payload:

{
  "scope": "selection",
  "sampleLimit": 20
}

Доступные scope: selection, currentPage, allPages и node (для node обязателен nodeId).

Ответ содержит:

• availableFontsCount
• requiredFonts
• missingFamilies
• loadFailures
• textNodesBlocked
• sampleNodeIds
• affectedPages
• requiredAction

Если точный шрифт не загружается, SXL Studio не подставляет похожую семью автоматически. Например, SF Pro Display Regular не заменяется на SF Pro Regular, пока будущий workflow явно не получит пользовательский mapping. Безопасное действие: включить или загрузить точный shared font для файла/пользователя, перезагрузить Figma-файл, перезапустить SXL Studio и повторить preflight.

После успешного font preflight агенты могут использовать migration-команды через runtime SXL Studio plugin:

• migration_text_variable_bindings — typography variables на text ranges (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, paragraph fields).
• migration_text_fill_bindings — text fill color variables на text ranges.

Сначала запускайте dryRun: true, проверяйте affectedTextNodes, affectedRanges или affectedSegments, rebindCount, detachCount, skippedCount, leftoverCount, errors, leftovers и samples, и только потом повторяйте с dryRun: false для подтверждённых mappings. Результат применения дополнительно проверяется: команда не считается успешной, пока старые alias остаются на диапазонах. Typography migration также возвращает rangeResults со снимками bindings до/после. Text fill migration возвращает partial, changed, failed и skipped, чтобы агент видел прерванные проходы по instance sublayers/table cells и мог безопасно продолжить. Для больших файлов используйте maxTextNodes или maxNodesPerChunk и продолжайте, пока в ответе есть continueCursor.

Пример dry-run:

{
  "scope": "page",
  "dryRun": true,
  "mappings": [
    {
      "kind": "variable",
      "fromId": "VariableID:old",
      "fromName": "Projects/ff/label",
      "toId": "VariableID:new",
      "toName": "Projects/ff/label"
    }
  ],
  "sampleLimit": 20
}

Команда меняет только variable bindings. Она не меняет текст, font names, raw typography values и не создаёт отсутствующие переменные. Чтобы осознанно отвязать legacy binding и оставить raw formatting, используйте toId: "__SXL_GHOST_DETACH_RAW__" только после dry-run.

Для файлов, мигрированных между variable collections, используйте migration_explicit_modes_audit, чтобы найти page-level explicit mode references на отсутствующие collections и увидеть оставшиеся live collection refs. Если нужна очистка, сначала запустите migration_clear_orphan_explicit_modes с dryRun: true. Cleanup использует live collection objects там, где Figma их отдаёт. Если Figma отвергает очистку missing collection id, Bridge возвращает unsupportedByFigmaApi, manualFallbackRequired, manualSteps и unsupportedMissingCollectionRefs, а не ложный success. После ручной очистки повторите audit и продолжайте только когда missingCollectionRefs равен 0.

#Подключение AI-клиента (MCP)

Любой AI-клиент с поддержкой MCP, установленный на том же компьютере, что и Bridge, может вызывать инструменты Bridge и читать/управлять открытым Figma-файлом — пока Bridge запущен, а в плагине включён Remote Connect. Каждому клиенту нужен только endpoint Bridge MCP: http://127.0.0.1:37830/mcp.

Cursor — .cursor/mcp.json:

{ "mcpServers": { "sxl-studio": { "url": "http://127.0.0.1:37830/mcp" } } }

Claude Desktop — claude_desktop_config.json (проксируем HTTP-endpoint через mcp-remote):

{ "mcpServers": { "sxl-studio": { "command": "npx", "args": ["-y", "mcp-remote", "http://127.0.0.1:37830/mcp"] } } }

Codex CLI — ~/.codex/config.toml:

[mcp_servers.sxl-studio]
command = "npx"
args = ["-y", "mcp-remote", "http://127.0.0.1:37830/mcp"]

Если задан BRIDGE_AUTH_TOKEN, добавьте заголовок Authorization: Bearer <token> (для URL-клиентов) или передайте --header в mcp-remote, и укажите тот же токен в overlay Remote Connect плагина.

После сохранения конфига: перезапустите MCP-сессию клиента, убедитесь, что Bridge запущен, и что в плагине включён Remote Connect.

#Проверка подключения

Быстрая проверка статуса:

curl http://127.0.0.1:37830/api/status

Ответ включает поля подключения/сессии, runtime.health (ready, busy, degraded или disconnected), actionable runtime.issues, sanitized snapshot очереди и telemetry счетчики/метаданные последней ошибки без значений payload.

Проверка каталога команд:

curl http://127.0.0.1:37830/api/tools

Для MCP-клиентов используйте list_tools, чтобы получить актуальный список команд.

#Операционный контракт для AI-агента

Если вы даёте эту страницу AI-агенту, агент должен воспринимать Bridge как контролируемый слой управления SXL Studio, а не как универсальный раннер произвольных скриптов. Безопасный порядок работы:

1. Проверить live-состояние через get_bridge_runtime_summary или GET /api/runtime-summary.
2. Если задача требует открытый Figma-файл, а summary показывает, что Remote Connect не подключён, остановиться и попросить оператора открыть SXL Studio в Figma и включить Remote Connect. Не имитировать live-результат.
3. Для natural-language запросов вызвать route_intent, затем plan_workflow, затем preview_workflow до write-команд.
4. Для создания дизайна сначала изучить дизайн-систему через inspect_design_system; затем выполнить validate_screen_spec; затем запустить build_screen или update_screen с dryRun: true; только после этого применять изменения.
5. Для token export сначала выполнить preview_export_variables, затем export_variables. Разрушающие export-опции требуют явный confirmDestructive: true; delete/reset-класс Remote Connect команд может дополнительно требовать, чтобы пользователь включил Allow destructive commands в overlay плагина для текущей сессии.
6. Для документации в Figma использовать apply_doc_spec, build_component_doc, build_doc_flow, bind_variable_palette или build_scenario_from_md. Не писать composition JSON вручную и не строить ad hoc canvas scripts, если есть thick command Bridge.
7. Для больших сканов сначала запрашивать summaries и переходить к paginated detail tools только по нужной части данных.
8. После write-команд повторно запускать соответствующий read/audit и сообщать, что изменилось, что было пропущено и нужна ли визуальная проверка.

Критичные границы для агента:

• Bridge ориентирован на Figma Design + active-file workflows SXL Studio.
• Official Figma MCP остаётся companion для создания новых файлов, FigJam/Slides-специфичного редактирования, сгенерированных диаграмм и hosted-only Code Connect context.
• Bridge умеет читать известные hosted Figma files через REST при настроенных FIGMA_TOKEN / FIGMA_ACCESS_TOKEN, но REST reads не заменяют Remote Connect для active canvas writes.
• Git Sync Local Storage и /api/workspace-blob входят в публичный контракт Bridge. Они должны работать без активной Remote Connect websocket-сессии; если включён BRIDGE_AUTH_TOKEN, им нужен тот же bearer token, что и остальным /api/*.

Полезный официальный контекст: Figma описывает MCP server как agent interface для design context и write-to-canvas workflows, а также перечисляет несколько remote-only tools, включая create_new_file, generate_diagram, use_figma, get_libraries, search_design_system и upload_assets. Figma также публикует skills figma-use, figma-code-connect, figma-generate-library и figma-generate-design. Bridge честно закрывает только те части, которые доступны через локальный plugin и SXL workflows, а остальное явно помечает как companion scope.

Официальные ссылки:

• Figma MCP server documentation
• Figma MCP tools and prompts
• Figma skills for MCP

Быстрая карта intent routing

Паттерн raw HTTP command

MCP-клиентам лучше использовать MCP tools. HTTP-клиенты могут обращаться к /api/command напрямую:

curl -s -X POST http://127.0.0.1:37830/api/command \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: export-preview-001' \
  -d '{
    "commandType": "preview_export_variables",
    "payload": {
      "settings": {
        "dryRun": true
      }
    }
  }'

Если включён BRIDGE_AUTH_TOKEN, добавьте Authorization: Bearer <token>. Write-команды возвращают normalized envelope с command id, status, result и typed errors, где это возможно. Для повторов из скриптов и агентов используйте Idempotency-Key.

Для короткого start-here гайда вызывайте get_operator_runbook, подключайте sxl://agent/operator-runbook или используйте prompt sxl-operator. HTTP-клиенты могут использовать GET /api/operator-runbook. Он маппит типовые RU/EN запросы на нужный SXL workflow, ресурсы, preferred tools, dry-run gates, done criteria и handoff в official Figma MCP companion scope.

Для широких natural-language запросов сначала вызывайте route_intent. Он возвращает ranked SXL recipes, preferred tools, dryRunFirst и schema resources, например sxl://agent/schemas/design-dsl-v1, sxl://agent/schemas/doc-spec-v2, sxl://agent/schemas/code-connect-context-v1 или sxl://agent/schemas/code-connect-template-v1.

Для многошаговых задач вызывайте plan_workflow, затем проверяйте предложенную последовательность tools через preview_workflow до write-команд. Preview покажет unknown tools, пропущенные или misordered status checks, discovery дизайн-системы, dry-run gates, preflight tools из preferredAfter, и guard-шаги, которые стоят после write-команды вместо того, чтобы защищать ее.

Для token export сначала запускайте preview_export_variables, затем export_variables. Для Figma Design library discovery/search используйте Bridge get_libraries / search_design_system. Для official Figma MCP companion scope вроде создания нового файла, FigJam/Slides, диаграмм или hosted Code Connect repository context планировщик добавляет явный handoff step; не используйте Bridge write tools, если пользователь не сузил задачу обратно до SXL/active-file Figma Design.

Для больших workflow сначала вызывайте get_capability_matrix. HTTP-клиенты могут использовать эквивалентный endpoint:

curl http://127.0.0.1:37830/api/capabilities

Он возвращает тот же каталог с execution metadata (plugin, bridge-orchestration, bridge-local), точными pluginCommandTypes, aliases, natural-language intents, dryRunSupported, returnsLargeData, подсказками порядка вызова и Bridge timeouts.

Чтобы сравнить Bridge с official Figma MCP tools, используйте:

curl http://127.0.0.1:37830/api/figma-mcp-parity

MCP-клиенты могут вызвать get_figma_mcp_parity или подключить sxl://agent/figma-mcp-parity. Matrix помечает каждый official Figma MCP tool как covered by Bridge/SXL, companion-required, future scope или unsupported by plugin API. Bridge plugin tools закрывают enabled-library search и active-file metadata в открытом файле. Bridge REST tools закрывают authenticated whoami и known file/team library reads, если настроен Figma REST token. get_libraries / search_design_system дают Figma MCP-compatible Figma Design library discovery/search по active-file и known REST sources. get_design_context закрывает active-file SXL-native design context. get_metadata закрывает hosted file/node metadata. get_variable_defs закрывает selection/local/enabled-library/known-file variable definitions. get_screenshot закрывает active-file SVG и known-node REST image rendering. Bridge upload_assets закрывает Figma Design image insertion из URL/base64 с dry-run и лимитом 10MB на asset. get_context_for_code_connect закрывает active-file Code Connect context, generate_code_connect_template генерирует dry-run-first local .figma.ts templates, а get_code_connect_suggestions закрывает локальный поиск кандидатов перед codeconnect_save_binding. Remote-only hosted capabilities вроде создания нового файла, hosted Code Connect repository context и FigJam/Slides asset upload всё ещё требуют official Figma MCP как companion.

Для skill-level routing используйте:

curl http://127.0.0.1:37830/api/figma-mcp-skills-parity

MCP-клиенты могут вызвать get_figma_mcp_skills_parity или подключить sxl://agent/figma-mcp-skills-parity. Matrix маппит текущие official Figma MCP skills figma-use, figma-use-figjam, figma-use-slides, figma-swiftui, figma-code-connect, figma-create-new-file, figma-generate-diagram, figma-generate-library и figma-generate-design на SXL recipes/resources/tools, companion scope или agent-side работу с кодовой базой.

route_intent и plan_workflow понимают текущие official skills и legacy/client aliases. FigJam, Slides, new-file и diagram skills маршрутизируются в official Figma MCP companion. figma-swiftui использует Bridge для active-file design context и Code Connect hints, затем агент правит Swift-код. Старые aliases остаются поддержаны: figma-implement-design маршрутизируется в sxl-implement-design, figma-create-design-system-rules — в sxl-generate-library, а figma-code-connect-components — в sxl-code-connect.

Для чувствительных к производительности workflow используйте performance profile Bridge:

curl http://127.0.0.1:37830/api/performance-profile

MCP-клиенты могут вызвать get_performance_profile или подключить sxl://agent/performance-profile. Он помечает local, summary, paginated-detail, write-preview и long-running команды, отдаёт целевые бюджеты и подсвечивает large-data, dry-run-first и destructive-write риски. Используйте его перед широкими сканами, генерацией экранов, bulk export/apply или отладкой медленных workflow.

Для operational preflight вызывайте get_operator_runbook как start-here workflow chooser, затем get_bridge_runtime_summary перед live-работой. HTTP-клиенты могут использовать:

curl http://127.0.0.1:37830/api/operator-runbook
curl http://127.0.0.1:37830/api/runtime-summary

Runbook выбирает workflow, tools, dry-run gates и companion handoff. Runtime summary показывает plugin connection, current/queued commands, recent event/audit failures, auth state, MCP URL и рекомендации, чтобы агент понял: продолжать, ждать, смотреть логи или попросить оператора открыть Remote Connect.

Для release/readiness оценки вызывайте get_ultimate_readiness или:

curl http://127.0.0.1:37830/api/ultimate-readiness

Локальный оператор может запустить тот же аудит без запущенного Bridge server:

cd Utils/bridge
npm run readiness
sxl-bridge-readiness --json

Он раскладывает Ultimate Bridge plan на requirement rows: contract surface, SXL skills, Design DSL, analytics, database, variables/styles, compositions, docs, Code Connect, production safety, official Figma MCP tool parity и official Figma MCP skill parity. Contract row включает Remote Connect whitelist и handler-path evidence при доступном исходнике плагина. Companion/future scope для Figma MCP остаётся явным. Добавьте --runtime, чтобы рядом с local readiness получить доказательство running Bridge HTTP/MCP surface; добавьте --require-live, когда release sign-off должен падать без активной Remote Connect сессии плагина и успешной live validation.

Tools с returnsLargeData поддерживают bridgeResponseMode. Используйте summary, чтобы сначала получить counts, preview и pagination hints; auto оставляет budget-aware поведение по умолчанию; full используйте только когда нужен точный полный payload. Bridge удаляет эти control fields перед отправкой команды в плагин, а raw HTTP /api/command остаётся fallback для exact result.

В Bridge также есть destructive confirmation gate. Команды delete_*, remove_*, reset_*, git_hard_pull, detach_instance, flatten_nodes, boolean_operation и export_variables с deleteOrphans или allowDestructiveReorder требуют top-level confirmDestructive: true. Если доступен dry-run/preview, сначала запускайте его; перед token export используйте preview_export_variables, чтобы без изменений в Figma увидеть exact settings payload, effective plugin defaults, risk flags и required confirmation. Bridge удаляет confirmDestructive и destructiveReason перед отправкой payload в плагин.

Plugin 2.6+ добавляет второй, пользовательский gate для delete/reset-класса Remote Connect команд. Команды delete_*, batch_delete_variables, remove_variable_mode, reset_diff* и git_hard_pull остаются заблокированными, пока пользователь не включит Allow destructive commands в overlay Remote Connect плагина. confirmDestructive не обходит этот plugin-gate. Если команда падает с blocked by session policy, включите toggle в overlay и повторите команду.

Bridge сохраняет sanitized command audit log на диск. Используйте get_bridge_audit_log или:

curl http://127.0.0.1:37830/api/log?source=disk

Корень по умолчанию — OS cache directory из env-paths внутри sxl-studio-bridge/audit; его можно переопределить через SXL_BRIDGE_AUDIT_ROOT. Audit entries содержат ids, command type, status, timings, имена payload keys и idempotency keys, но никогда не сохраняют значения payload.

Для release-проверок или подключения нового агента/клиента запускайте contract audit Bridge:

curl http://127.0.0.1:37830/api/contract-audit

MCP-клиенты могут вызвать get_contract_audit. Он проверяет обязательные meta tools, ссылки recipes, schema entrypoints, workflow gates, объявления plugin commands, покрытие Remote Connect whitelist и handler-path coverage при доступном исходнике плагина, а также timeouts. status: "fail" считается блокирующим.

Для CLI-проверок используйте health gate Bridge:

# локальный contract gate; запущенный сервер не нужен
npm run bridge:check

# локальная проверка agent routing/planning/preview; Figma-сессия не нужна
cd Utils/bridge
npm run workflow:agent

# локальный Ultimate Bridge requirement audit; запущенный сервер не нужен
npm run readiness

# local readiness + running Bridge HTTP/MCP proof
npm run bridge:readiness:runtime
sxl-bridge-readiness --runtime

# строгий Figma E2E proof; требует активный Remote Connect
npm run bridge:readiness:live
sxl-bridge-readiness --runtime --require-live --suite all

# runtime HTTP + MCP smoke против запущенного Bridge
npm run health:runtime

# требовать живую Remote Connect сессию плагина
node dist/bridge-health-cli.js --runtime --require-plugin

# live workflow smoke через Remote Connect: status -> get_plugin_status -> find_components -> build_mockup dryRun
npm run workflow:smoke

# расширенная non-destructive live validation: baseline reads + Design DSL dryRun
npm run workflow:validate

# явная write-path проверка: создать tiny frame, проверить rootNodeId, удалить его
sxl-bridge-live --suite all --write-canary --cleanup

workflow:agent локально валидирует representative RU/EN requests через route_intent, plan_workflow и preview_workflow. Он ловит stale routing, missing preflight dependencies, unsafe generated plans и read-only intents, которые случайно планируют write tools. readiness печатает тот же Ultimate Bridge requirement audit локально без запущенного сервера. health:local включает тот же agent workflow gate плюс Ultimate Bridge readiness audit. Здоровая сборка возвращает PASS; WARN нужно разбирать перед релизом, а explicit companion/future scope выводится отдельно в readiness.

health:runtime проверяет /mcp initialize/session/tools-list/tools-call (get_libraries + search_design_system zero-config envelopes, get_operator_runbook, list_tools, validate_screen_spec, preview_export_variables, get_figma_mcp_skills_parity и plan_workflow для Figma Design library discovery routing), resources-list/resources-read для runtime-summary + operator-runbook + figma-mcp-skills-parity, prompts-list/prompts-get для sxl-operator + sxl-generate-design и REST runtime endpoints, включая /api/operator-runbook. Для readiness/performance endpoints проверяется не только shape, но и status: runtime fail блокирует gate, runtime warn выводится как предупреждение. Активная сессия плагина не нужна, пока не передан --require-plugin.

workflow:smoke требует запущенный Bridge и активную Remote Connect сессию плагина SXL Studio. По умолчанию он не меняет canvas; sxl-bridge-smoke --apply создаёт небольшой smoke-frame только при явном opt-in и если Figma возвращает writesAllowed=true. sxl-bridge-smoke --apply --cleanup удаляет rootNodeId, который вернул этот же apply step, поэтому canary доказывает create/delete доступ и не оставляет frame в файле.

workflow:validate также требует активную Remote Connect сессию. Baseline suite проверяет Bridge status, /mcp initialize/session/tools-list/tools-call (get_libraries + search_design_system zero-config envelopes, get_operator_runbook, list_tools, validate_screen_spec, preview_export_variables, get_figma_mcp_skills_parity и plan_workflow для Figma Design library discovery routing), resources-list/resources-read для runtime-summary + operator-runbook + figma-mcp-skills-parity, prompts-list/prompts-get для sxl-operator + sxl-generate-design, ultimate readiness, performance profile, operator runbook, tool catalogue, чтение tokens/config, чтение variables/styles, discovery компонентов и Design DSL dry-run. Readiness/performance status enforced: fail валит suite, warn выводится как предупреждение. sxl-bridge validate --suite all дополнительно проверяет Code Connect registry/settings/selection status, selection variable definitions, dry-run генерацию .figma.ts template, database list commands, database payload export плюс import dry-run, variable/style spec dry-runs, dedupe dry-runs, variable/style coverage summary и paginated detail, variable/style coverage dry-run apply previews, unused variable/style scans, composition list плюс bulk dry-run и drift audit, component usage summary/detail pagination, component prop usage summary/detail pagination и Doc Builder build_doc_flow dry-run. Добавляйте --write-canary --cleanup только с явным operator approval; этот режим создаёт tiny validation frame, проверяет returned rootNodeId, затем удаляет этот же node.

Live diagnostics очереди:

curl http://127.0.0.1:37830/api/queue

Endpoint возвращает current, queued и immediate команды с ids, status, timings и payloadKeys. Значения payload не раскрываются.

Timeline событий команд:

curl http://127.0.0.1:37830/api/events?limit=100
curl http://127.0.0.1:37830/api/events?commandId=<command-id>

Endpoint возвращает sanitized lifecycle/progress events (queued, started, completed/failed, timeout/cancel и plugin progress events). Значения не раскрываются; доступны только ids, status, timings, payloadKeys и detailKeys.

Persisted audit после рестарта:

curl http://127.0.0.1:37830/api/log?source=disk&limit=50

#Основные рабочие сценарии

1) Tokens и styles

Через Bridge можно:

• экспортировать variables/styles;
• повторно применять token bindings;
• управлять token-файлами и config в workspace;
• запускать cross-file sync действия.

preview_export_variables — read-only preflight для export modes. Он возвращает exact export_variables payload, effective plugin defaults, risk flags и признак required destructive confirmation. export_variables использует безопасные defaults плагина: не применяет code syntax/scopes, не делает force-update всего, не удаляет orphans и не запускает destructive reorder, если эти опции не переданы явно.

Результат export — это реальный результат Plugin: Bridge не заменяет counts, warnings, errors и отчёт по partial modes общим сообщением об успехе. Отсутствующие mode-ячейки обрабатываются в том же недеструктивном запуске: существующие значения Figma не меняются, новые назначения сохраняют созданные Figma значения, а orphan cleanup/destructive reorder отключаются. get_export_report возвращает последний ручной, автоматический или Remote Connect результат; до первого export ответ содержит available: false.

Стартовые команды:

• list_token_files
• get_token_file_content
• save_token_file
• save_tokens_config
• preview_export_variables
• export_variables
• get_export_report

2) Composition-сценарии

Через Bridge можно:

• экспортировать composition JSON из выделения;
• генерировать/применять/превьюить композиции;
• проверять composition drift;
• запускать bulk-операции по композициям.

Стартовые команды:

• export_composition_json
• generate_composition
• apply_composition
• bulk_generate_compositions
• audit_composition_drift

Bridge использует тот же оптимизированный pipeline Generate / Apply для Composition, что и UI плагина. Для больших библиотек передавайте явный список файлов в bulk_generate_compositions, держите Remote Connect открытым до завершения операции и проверяйте результат через audit_composition_drift.

Для тяжелых Figma-файлов или запусков с десятками композиций используйте chunked bulk generation:

{
  "operation": "generate",
  "fileIds": ["button-primary-sm", "button-primary-md"],
  "chunkSize": 12,
  "pauseBetweenChunksMs": 300
}

chunkSize позволяет Bridge выполнять тот же bulk-запрос небольшими возобновляемыми партиями, а не отправлять весь canvas-run одной длинной командой в плагин. Для больших component libraries хороший стартовый размер — 10-15. Bridge возвращает progress по чанкам, следующий cursor и target hash, поэтому агент может безопасно продолжить работу, если оператору нужно переоткрыть Figma или Remote Connect.

3) Codegen-сценарии (паритет с Dev Mode)

get_codegen даёт тот же класс output, что и SXL Studio в Dev Mode:

• designer-json
• vue3
• swiftui
• kotlin
• divkit (generic DivKit JSON card)

4) Design и документация

Bridge отдаёт SXL agent skill resources:

• sxl://agent/operator-runbook
• sxl://agent/recipes/sxl-use
• sxl://agent/recipes/sxl-implement-design
• sxl://agent/recipes/sxl-generate-design
• sxl://agent/recipes/sxl-generate-library
• sxl://agent/recipes/sxl-code-connect
• sxl://agent/recipes/sxl-audit
• sxl://agent/recipes/sxl-doc-builder
• sxl://agent/recipes/sxl-data-apply-mapping
• sxl://agent/recipes/sxl-data-apply-all
• sxl://agent/recipes/sxl-data-generate-instances
• sxl://agent/recipes/sxl-database-transfer
• sxl://agent/recipes/figma-mcp-companion
• sxl://agent/schemas/code-connect-context-v1
• sxl://agent/schemas/code-connect-template-v1
• sxl://agent/figma-mcp-parity
• sxl://agent/figma-mcp-skills-parity
• sxl://agent/performance-profile
• sxl://agent/runtime-summary
• sxl://agent/ultimate-readiness

MCP-клиенты с поддержкой prompts также могут использовать prompts/list / prompts/get для sxl-operator, sxl-router, sxl-use, sxl-implement-design, sxl-generate-design, sxl-generate-library, sxl-code-connect, sxl-audit, sxl-doc-builder и figma-mcp-companion. Prompts возвращают тот же SXL skill intent как actionable instructions: preferred tools, resources, dry-run gates и done criteria. Используйте figma-mcp-companion, когда route_intent определяет remote-only scope official Figma MCP: создание нового файла, FigJam/Slides или диаграммы; для Figma Design library discovery используйте Bridge get_libraries / search_design_system.

Для сборки или обновления editable Figma-экранов из существующих компонентов используйте inspect_design_system, validate_screen_spec, build_screen и update_screen. Для документации в Figma используйте apply_doc_spec, build_component_doc, build_doc_flow, bind_variable_palette и build_scenario_from_md. build_doc_flow принимает страницы с nodeId или compositionFileId; composition-страницы проходят через существующий composition pipeline и рендерятся во flow как instance или clone.

5) CRUD Variables и локальных styles

Bridge поддерживает полный цикл для:

• variable collections, modes, values, scopes, code syntax;
• локальных paint/text/effect styles;
• назначения styles и import-by-key;
• bulk import/dedupe/rebind/audit-потоков.

6) Audit, analytics и coverage

Bridge поддерживает read-first аудит:

• usage и coverage для variables;
• style coverage и drift;
• поиск неиспользуемых variables/styles;
• component usage и component prop usage analytics;
• сценарии применения рекомендаций (сначала dry-run).

Coverage audit recipes работают read-only. Если пользователь просит исправить findings, переключайтесь на apply_coverage_suggestions / apply_style_coverage_suggestions и сначала запускайте preview mode.

7) Code Connect и database

Bridge отдаёт Code Connect settings, registry, node UI status, active-file Code Connect context (get_context_for_code_connect), dry-run-first генерацию .figma.ts templates (generate_code_connect_template), локальные suggestions по source files, а также чтение/сохранение полных binding payloads: docs URL, files, Storybook metadata и status component API.

Database tools умеют list/get/save/delete для datasets, assets и mappings. Save/delete команды поддерживают dryRun preview до изменения состояния плагина. export_database_payload собирает переносимый backup/transfer payload через существующие CRUD reads; asset content не включается, пока явно не передан includeAssetContent=true. import_database_payload по умолчанию работает как dryRun, показывает конфликты существующих IDs и требует confirmDestructive=true плюс причину перед перезаписью datasets, assets или mappings. Mapping write tools (apply_mapping, apply_all_mappings, generate_instances) тоже поддерживают dryRun previews, чтобы агент мог проверить mappings, target counts и row estimates перед записью. Apply/count/generate workflows принимают явные targetNodeIds как deterministic selection roots; без них Bridge использует текущую selection или scope.

8) Git Sync

Через Bridge можно вызывать git-действия, используемые в SXL Studio:

• git_pull
• git_hard_pull
• git_push

#Local Storage для крупных Git Sync проектов

Для средних и крупных наборов данных включайте Local Storage в настройке Git Sync.

Так большие синхронизируемые данные сохраняются на диск через Bridge и стабильность выше для больших workspace. Перед Pull плагин проверяет GET /api/status, а затем читает/пишет payload конкретного workspace через /api/workspace-blob.

Если задан BRIDGE_AUTH_TOKEN, заполните Bridge Auth Token в этом же Sync-подключении. Используйте тот же сгенерированный секрет, с которым запущен Bridge, а не Git provider token и не Figma REST token. Для Local Storage не нужна отдельная websocket-сессия Remote Connect, но Bridge должен быть доступен на localhost.

Используйте SXL_BRIDGE_WORKSPACE_BLOB_ROOT, если нужно перенести директорию blob-хранилища. Если Pull остановился с предупреждением Local Storage, проверьте, что Bridge запущен на той же машине, что и Figma, порт совпадает, а auth token указан одинаково.

Пользовательский обзор: Git — интеграция

#Поведение в Dev Mode

В Figma Dev Mode:

• read и file-сценарии доступны;
• прямые canvas-write операции могут ограничиваться контекстом Figma;
• token/config/git file workflows остаются доступны при валидном соединении.

Если write-действие заблокировано режимом, выполните его в Design Mode.

#Категории команд (практическая карта)

Каталог команд Bridge большой и развивается. Используйте таблицу как карту, а точный актуальный список берите через list_tools.

#Рекомендуемая модель работы

1. Начинайте с read/audit вызовов.
2. Где доступно, сначала запускайте dry-run.
3. После проверки применяйте write-действия.
4. Храните token и composition JSON в git.
5. После изменений повторно запускайте audit.

#Устранение проблем

Bridge запущен, но команды не выполняются

• Проверьте, что в плагине включён Remote Connect.
• Проверьте URL/порт в .cursor/mcp.json.
• Если включён BRIDGE_AUTH_TOKEN, проверьте Authorization header для MCP/HTTP, token в overlay Remote Connect и поле Bridge Auth Token в Sync-подключении для Local Storage.

Unauthorized / forbidden

• Несовпадает токен в Authorization header, overlay Remote Connect или поле Bridge Auth Token в Sync-подключении.
• После изменения env-переменных перезапустите Bridge.

Команды видны, но canvas-write не проходит

• Текущий контекст Figma может ограничивать запись в Dev Mode.
• Повторите операцию в Design Mode.

Ошибки Git-операций

• Проверьте валидность Sync-подключения в плагине.
• Проверьте scopes токена провайдера и настройки пути репозитория.

#Совместимость версий (короткое правило)

Сверяйте версии Bridge и плагина по release notes. Для релиза, описанного на этой странице, используйте точную пару:

Старый Bridge может не показывать новые инструменты, а старый Plugin — отклонять команду нового Bridge. reapply_compositions не публикуется в этой паре, потому что раньше эта команда фактически не выполняла Apply. Для одной композиции используйте apply_composition, для явного проверенного набора — bulk_generate_compositions с operation apply.

Практическое правило:

• обновляйте Bridge и SXL Studio plugin в одном окне обслуживания;
• после обновления запускайте list_tools, get_performance_profile, workflow:smoke и workflow:validate против живой Remote Connect сессии.

#Промты для пользователя

Вы не вызываете инструменты вручную — вы описываете задачу на естественном языке, а AI-клиент сам выбирает нужные инструменты Bridge. В Bridge есть natural-language роутер (route_intent), который сопоставляет запросы на RU/EN с нужным рецептом и инструментами. Готовые промты:

#Справочник команд (MCP-инструменты)

Bridge предоставляет 250+ MCP-инструментов по категориям. Каждый вызывается любым подключённым AI-клиентом (большинство мапится на одну команду плагина через Remote Connect). Read-only и dryRun-first инструменты безопасны для исследования; write-инструменты меняют Figma-файл.

Tokens (19)

Variables (25)

Variables — bulk / orchestration (5)

Styles (9)

Styles — bulk / orchestration (5)

Compositions (12)

Compositions — bulk (2)

Canvas & nodes (68)

Datasets, assets, mappings & Code Connect (36)

Audit & analytics (13)

Mockups & Design DSL (7)

Orchestration, docs & meta (24)

Figma REST companion (16)

Git Sync (3)

#Связанные разделы

• Git — интеграция
• Dev Mode — обзор
• Composition
• Экспорт Variables и Styles