name: xbsl-deploy description: > Используй этот скилл для любых операций с приложениями на платформе 1С:Предприятие.Элемент (1cmycloud.com): создать приложение, задеплоить ветку из внешнего git-репозитория (GitHub, GitLab и др.), обновить, проверить статус, запустить, остановить, удалить, принять изменения (merge). Вызывай скилл всякий раз, когда пользователь упоминает деплой, запуск, остановку или управление приложением на Элементе — даже если он не говорит явно "задеплой", а просто спрашивает "как дела с приложением" или "смёрджи ветку". compatibility: Requires Python 3. metadata: version: "1.0.0"

Во всех командах ниже {python} означает python в Windows и python3 в macOS/Linux/WSL. Выбирай команду сразу по текущей ОС, не запускай оба варианта.

Деплой на 1С:Предприятие.Элемент

Справочник по API: references/endpoints.md — читай его если нужны детали по полям запросов/ответов.

Шаг 0: Загрузи переменные окружения

Перед любым обращением к API загрузи env vars. Выполни команду:

set -a && source .env 2>/dev/null; set +a

Если .env не найден — продолжай: нужные переменные могут быть уже заданы в системе.

Обязательные переменные: ELEMENT_BASE_URL, ELEMENT_CLIENT_ID, ELEMENT_CLIENT_SECRET. Если хотя бы одна отсутствует — сообщи пользователю и остановись.

Два вида веток: внешний git vs внутренний git платформы

В 1С:Элемент существуют два независимых механизма веток — не путай их:

Если получаешь 503 на `list-branches` / `get-branch` — проект работает через внешний git. Используй Сценарий I (путь 2: --from-branch) вместо Сценария B.

Шаг 1: Определи намерение

Шаг 2: Получи токен

{python} skills/xbsl-deploy/scripts/api.py --action get-token

Если ошибка — сообщи пользователю что нужно задать env vars: ELEMENT_BASE_URL, ELEMENT_CLIENT_ID, ELEMENT_CLIENT_SECRET.

Сценарий A: Создать новое приложение и задеплоить

По умолчанию: новое приложение привязывается к существующему проекту. Загрузка файла сборки для создания нового проекта — только если пользователь явно попросил («создать проект из сборки», «загрузить сборку» и т.п.) — тогда используй Сценарий H.

A0. Проверь вид проекта (если известна папка проекта)

Если пользователь указал локальную папку проекта — прочитай Проект.yaml и проверь ВидПроекта:

grep "ВидПроекта" <путь>/Проект.yaml

Если найдено ВидПроекта: Библиотека — остановись и сообщи пользователю:

Платформа не может развернуть библиотеку как самостоятельное приложение. Библиотека предназначена для подключения через Импорт в другой проект, а не для деплоя.

Если найдено ВидПроекта: Расширение — перейди к сценарию L. Расширение подключается к существующему приложению и не создаёт отдельное приложение.

A1. Определи проект

Если ELEMENT_PROJECT_ID не задан — выведи список проектов и попроси пользователя выбрать:

{python} skills/xbsl-deploy/scripts/api.py --action list-projects

Показывай только не удалённые ("deleted": false) проекты типа Application.

Сохрани выбранный project-id для следующих шагов.

A2. Определи space-id

Если ELEMENT_SPACE_ID не задан:

{python} skills/xbsl-deploy/scripts/api.py --action list-spaces

• Если пространство одно — используй его id как space-id. Предложи пользователю сохранить в .env: ELEMENT_SPACE_ID=<id>.
• Если пространств несколько — покажи список и спроси пользователя выбрать.
• Если пространств нет — сообщи пользователю, создать пространство нужно через веб-консоль.

A3. Создай приложение

Спроси имя приложения если не указано.

Если проект создан загрузкой сборки в сценарии H, используй id сборки из ответа upload-build как assembly-id. У нового проекта может ещё не быть сборки по умолчанию, поэтому передавай точную версию:

{python} skills/xbsl-deploy/scripts/api.py --action create-app --name <name> --space-id <space-id> --version-id <assembly-id>

Для уже существующего проекта, когда конкретная сборка не выбрана, сохрани прежний вариант:

{python} skills/xbsl-deploy/scripts/api.py --action create-app --name <name> --space-id <space-id> --project-id <project-id>

Сохрани id из ответа как app-id.

A4. Запусти приложение

{python} skills/xbsl-deploy/scripts/api.py --action start-app --app-id <app-id>

A5. Жди Running

Опрашивай каждые 10 сек, до 5 мин:

{python} skills/xbsl-deploy/scripts/api.py --action get-app --app-id <app-id>

Жди пока status == Running. Если status == Error — сообщи error пользователю и остановись. Если 5 мин прошло, а статус не Running — сообщи пользователю текущий статус и предложи проверить логи в консоли Элемента. После создания из сборки дополнительно проверь, что source.project-version-id совпадает с assembly-id из H4. Старый Running для другой сборки не доказывает успех новой публикации.

A6. Верни ссылку

Из последнего ответа get-app возьми поле uri и отправь пользователю.

Сценарий B: Обновить приложение из ветки

B1. Найди приложение

Используй ELEMENT_APP_ID или спроси имя и найди:

{python} skills/xbsl-deploy/scripts/api.py --action list-apps --name <name>

Сохрани id как app-id.

B2. Определи project-id

Используй ELEMENT_PROJECT_ID. Если не задан — извлеки из ответа B1: поле project.id в объекте приложения. Если поле project отсутствует или пустое:

{python} skills/xbsl-deploy/scripts/api.py --action list-projects

Спроси пользователя выбрать проект. Сохрани как project-id.

B3. Создай дамп (страховка перед изменениями)

Дамп нужен как точка отката на случай проблем после деплоя.

{python} skills/xbsl-deploy/scripts/api.py --action create-dump --app-id <app-id>

Сохрани id из ответа как dump-id. Проверь статус сразу (без паузы), затем опрашивай каждые 3 сек (до 60 сек):

{python} skills/xbsl-deploy/scripts/api.py --action get-dump --app-id <app-id> --dump-id <dump-id>

Жди пока status станет Done или Completed. Если дамп завершился ошибкой или не готов за 60 сек — остановись и сообщи пользователю. Не продолжай.

B4. Найди ветку

{python} skills/xbsl-deploy/scripts/api.py --action list-branches --project-id <project-id> --branch-name <branch>

B5. Привяжи ветку к приложению (если нужно)

Если branch.application.id != app-id:

{python} skills/xbsl-deploy/scripts/api.py --action update-branch --branch-id <branch-id> --app-id <app-id>

B6. Перезапусти (подхвати изменения из репозитория)

Сначала останови (если приложение не Stopped):

{python} skills/xbsl-deploy/scripts/api.py --action stop-app --app-id <app-id>

Жди Stopped (опрос каждые 10 сек, до 3 мин). Затем запусти:

{python} skills/xbsl-deploy/scripts/api.py --action start-app --app-id <app-id>

B7. Жди Running → верни URL (как A5-A6)

Сценарий C: Статус приложения

{python} skills/xbsl-deploy/scripts/api.py --action get-app --app-id <app-id>

Выведи пользователю:

• status (Running / Stopped / Error / ...)
• uri — ссылка на приложение
• error — если есть
• current-task — текущая задача если есть
• technology-version

Сценарий D: Запустить приложение

{python} skills/xbsl-deploy/scripts/api.py --action start-app --app-id <app-id>

Жди Running (опрос каждые 10 сек, до 5 мин) → верни статус и ссылку. Если таймаут — сообщи текущий статус и предложи проверить логи в консоли Элемента.

Сценарий E: Остановить приложение

{python} skills/xbsl-deploy/scripts/api.py --action stop-app --app-id <app-id>

Жди Stopped (опрос каждые 10 сек, до 3 мин) → сообщи что остановлено. Если таймаут — сообщи текущий статус.

Сценарий F: Удалить приложение

Обязательно запроси подтверждение у пользователя перед любым удалением. Сообщи имя удаляемого объекта и что действие необратимо. Продолжай только после явного подтверждения («да», «удали», «confirm» и т.п.). Если пользователь не подтвердил — остановись.

Если приложение не Stopped:

{python} skills/xbsl-deploy/scripts/api.py --action stop-app --app-id <app-id>

Жди Stopped (опрос каждые 10 сек, до 3 мин). Затем:

{python} skills/xbsl-deploy/scripts/api.py --action delete-app --app-id <app-id>

Если ветка создавалась скиллом — предложи удалить и её. Удаляй ветку только после отдельного подтверждения:

{python} skills/xbsl-deploy/scripts/api.py --action delete-branch --branch-id <branch-id>

Сценарий G: Принять изменения (merge ветки)

Если branch-id не известен — найди ветку. Для этого нужен project-id (из ELEMENT_PROJECT_ID или спроси пользователя через list-projects):

{python} skills/xbsl-deploy/scripts/api.py --action list-branches --project-id <project-id> --branch-name <branch>

Затем выполни merge:

{python} skills/xbsl-deploy/scripts/api.py --action merge-branch --branch-id <branch-id>

Сообщи результат.

Сценарий H: Создать проект из файла сборки

Проект на Элементе создаётся загрузкой бинарного файла сборки (.zip или артефакт компилятора). Без файла создать проект через API нельзя.

H1. Уточни параметры

Спроси пользователя:

• путь к файлу сборки (--file)
• имя ветки (--branch-name), если нужно зафиксировать (иначе используется ELEMENT_BRANCH)
• хэш коммита и сообщение (--commit-id, --commit-message) — опционально

H2. Определи space-id

Если ELEMENT_SPACE_ID не задан:

{python} skills/xbsl-deploy/scripts/api.py --action list-spaces

Если пространство одно — используй его автоматически.

H3. Выполни fail-closed проверку идентичности

При создании без project-id команда upload-build до бинарной загрузки автоматически:

1. читает точную пару Vendor + Name из корневого Assembly.yaml;
2. получает список проектов через read-only GET /projects;
3. для каждого активного проекта целевого пространства читает его сборки и

сравнивает project-developer + project-name как единую пару;

1. использует строгое регистрозависимое сравнение без fuzzy-сопоставления,

нормализации или попытки вывести пару только из ProjectDto.name: в ProjectDto нет второй координаты identity — поставщика.

Если найдена одна или несколько точных пар, команда завершается до POST /projects, выводит все найденные ID и требует повторного вызова с явным --project-id. Не выбирай найденный проект автоматически и не создавай дубль. Совпадение в метаданных любой доступной сборки считается консервативным конфликтом; выведенный ID — кандидат для ручной проверки, а не доказательство, что именно его следует выбрать. Ошибка или неполный ответ любого read-only шага также блокирует загрузку (deploy.project_identity_preflight_failed). Не обходи эту проверку ручным вызовом бинарного endpoint.

H4. Загрузи сборку и создай проект

{python} skills/xbsl-deploy/scripts/api.py --action upload-build \
  --file <path> \
  --space-id <space-id> \
  [--branch-name <branch>] \
  [--commit-id <hash>] \
  [--commit-message <msg>]

Чтобы добавить сборку к существующему проекту, добавь --project-id <id>. Явный ID переводит команду на endpoint существующего проекта; автоматический выбор по совпавшей идентичности запрещён.

Из ответа возьми project-id и id загруженной сборки. Если следующим шагом создаёшь приложение, перейди к A3 и передай именно id сборки через --version-id; одного --project-id для нового проекта недостаточно.

Сценарий I: Деплой через deploy.py

Детали путей деплоя — см. references/deploy-paths.md.

Настройка CI/CD (GitHub Actions, GitLab CI) — см. references/ci-cd.md.

I0. Проверь вид проекта

Если известна папка проекта — прочитай Проект.yaml и проверь:

grep "ВидПроекта" <путь>/Проект.yaml

Если найдено ВидПроекта: Библиотека — остановись и сообщи пользователю:

Платформа не может развернуть библиотеку как самостоятельное приложение. Библиотека предназначена для подключения через Импорт в другой проект, а не для деплоя.

Если найдено ВидПроекта: Расширение — перейди к сценарию L. Не запускай deploy.py, build.py --kind application, project-update основного проекта.

Путь 1 (из исходников): нужны ELEMENT_APP_ID, ELEMENT_PROJECT_ID.

{python} skills/xbsl-deploy/scripts/deploy.py [--project-dir PATH] [--branch B] [--commit C]

Если команда завершилась ошибкой (exit code != 0):

1. Покажи пользователю полный текст ошибки из вывода.
2. Проанализируй ошибку и предложи конкретный вариант исправления (что именно изменить в файлах проекта).
3. Жди явного подтверждения пользователя («да», «исправь», «ок» и т.п.).
4. Только после подтверждения — внеси исправление и повтори деплой.

deploy.py не считает старое состояние Running доказательством успешного обновления. Перед project-update он сохраняет существующие application task, после вызова использует явный task ID из ответа/current-task либо требует ровно одну новую UpdateApplicationConfiguration, читает её через /tasks/application-tasks/{id} и ждёт terminal status. Неоднозначный набор новых задач блокирует проверку. После Completed дополнительно проверяются Running, error == null, current-task == null и точный source.project-version-id загруженной сборки.

• ошибка API/transport или нечитаемый API-ответ: deploy.api_request_failed;
• Failed/Error/Cancelled/Canceled у task или ошибка приложения:

deploy.application_update_failed;

• отсутствие новой terminal task, таймаут, незавершённая current-task или

несовпавший project-version-id: deploy.application_update_unverified.

Все диагностики fail-closed: команда завершится с ненулевым кодом и не выведет сообщение об успешном деплое.

Путь 2 (из git-ветки): нужны ELEMENT_APP_ID, ELEMENT_BRANCH_ID. ⚠️ sync-branch требует браузерную сессию — через API невозможен (Bearer возвращает 403).

{python} skills/xbsl-deploy/scripts/deploy.py --from-branch [--branch-id ID]

Сценарий J: sync-branch с фолбэком на сборку

sync-branch через API невозможен — эндпоинт /console/ui/module/call требует браузерную сессию (cookie), Bearer-токен возвращает 403.

J1. Объясни ограничение и предложи альтернативу

Сообщи пользователю:

Обновить ветку напрямую через API невозможно — платформа требует браузерную сессию.

Можно обновить приложение через сборку из исходников (Путь 1): Claude соберёт .xasm из локальных файлов и загрузит на платформу.

Обновить через сборку?

Жди явного согласия («да», «давай», «конечно», «ок» и т.п.). Если пользователь не согласился — остановись и напомни про ручной способ:

Раздел «Ветки» в веб-консоли → три точки у ветки → «Обновить приложение по ветке».

J2. Если пользователь согласился — выполни Сценарий I (Путь 1)

Перейди к Сценарию I, Путь 1: из исходников. Все шаги те же.

Сценарий K: Версия технологии

technology-version — точная версия технологии облачного приложения в формате <major>.<minor>.<patch>-<build>, например 9.2.9-12. Она не является РежимСовместимости проекта.

• Не сравнивай полную строку technology-version с РежимСовместимости и не выводи

одно значение из другого. Например, РежимСовместимости: 9.1 и technology-version: 9.2.9-12 — два независимых входа.

• Изменение версии технологии через API не изменяет Проект.yaml и не должно

перезаписывать РежимСовместимости.

• Если платформа отклонила сборку из-за режима совместимости, покажи точную

ошибку, текущую technology-version и значение из Проект.yaml. Не изменяй файл без явного решения пользователя.

K1. Показать текущую версию

{python} skills/xbsl-deploy/scripts/api.py --action get-technology-version --app-id <app-id>

Вывести пользователю: technology-version. Поле date-updated может быть null — это нормально.

K2. Определить целевую версию

Если пользователь не указал версию явно — спросить. Формат: 9.1.11-21. Актуальные версии видны в панели управления (раздел «Версия технологии»).

Если строка не соответствует формату <major>.<minor>.<patch>-<build>, остановись с диагностикой deploy.technology_version_format. Не используй для этой проверки формат РежимСовместимости.

K3. Обновить версию через групповую задачу

{python} skills/xbsl-deploy/scripts/api.py --action update-technology-version \
  --app-id <app-id> --technology-version <версия>

Вызов создаёт групповую задачу (GroupTaskDto). Сохранить поле `id` из ответа — идентификатор задачи для опроса.

Если API вернул ошибку — endpoint недоступен. Сообщи пользователю:

Обновление версии технологии через API недоступно на этой платформе.

Используйте Панель управления: откройте приложение → раздел «Версия технологии»

→ выберите нужную версию → примените изменение. После этого запустите приложение снова.

На этом шаге остановись — дальнейшие шаги (K3.1–K5) выполнит пользователь вручную.

K3.1. Дождаться завершения задачи

{python} skills/xbsl-deploy/scripts/api.py --action get-group-task --task-id <task-id>

Опрашивать каждые 10 сек, до 5 мин. Завершение: completed-count + cancelled-count == total-count. При any-failure не равном null или "false" — сообщить об ошибке из поля error-message и остановиться.

K4. Остановить приложение (если Running)

{python} skills/xbsl-deploy/scripts/api.py --action stop-app --app-id <app-id>

Жди Stopped (опрос каждые 10 сек, до 3 мин).

K5. Запустить и дождаться Running

{python} skills/xbsl-deploy/scripts/api.py --action start-app --app-id <app-id>

Жди Running (опрос каждые 10 сек, до 5 мин) → сообщи новую версию и ссылку на приложение.

K6. Создать приложение с конкретной версией технологии

При создании нового приложения (Сценарий A, шаг A3) можно задать версию сразу через API:

{python} skills/xbsl-deploy/scripts/api.py --action create-app \
  --name <name> --space-id <space-id> --project-id <project-id> \
  --technology-version <версия>

Сценарий L: Расширение Element 10.0

ВидПроекта: Расширение имеет отдельный жизненный цикл. До действий проверь РасширяемыеПроекты: все перечисленные проекты должны быть установлены в целевом приложении, а их версии — входить в заданные диапазоны. Отсутствие списка означает универсальное расширение.

1. Собери проект расширения в среде разработки Element 10.0 и выбери сборку

расширения. build.py и deploy.py не формируют и не загружают такую сборку: формат архива расширения не подтверждён в опубликованной документации. При попытке запуска сборщика покажи диагностику xbsl-deploy.extension_archive_unsupported.

1. В панели управления открой Приложения → нужное приложение → вкладка

Расширение → Обновить. Подключи нужную сборку расширения, укажи порядок применения и нажми Далее.

1. Включи Проверить ошибки применения проекта, затем Начать обновление.

Для управления несколькими приложениями используй карточку проекта расширения → меню сборки → Установить в приложения.

1. Для дальнейших изменений в форме обновления можно поменять сборку,

порядок расширений, включить, выключить или отключить расширение. Каждая из этих операций запускает процедуру обновления приложения.

Структура расширения, управление в приложении, установка в несколько приложений.

Правила работы

• app-id: берётся из ELEMENT_APP_ID → аргумента → поиска по имени
• project-id: берётся из ELEMENT_PROJECT_ID → аргумента → выбора пользователя
• branch: берётся из ELEMENT_BRANCH (по умолчанию main)
• Дамп нужен только перед обновлением существующего приложения (Сценарий B). При создании нового — не нужен.
• space-id: берётся из ELEMENT_SPACE_ID → автоопределения через list-spaces (если пространство одно — используется автоматически, предложи сохранить в ELEMENT_SPACE_ID)
• При ошибке API — показывай поле error и details из ответа
• При HTTP- или транспортной ошибке api.py печатает JSON-диагностику и

завершает команду с ненулевым кодом; не переходи к следующему шагу деплоя после такого ответа.

• Удаление (приложения, ветки, проекта) — всегда запрашивай явное подтверждение пользователя перед выполнением. Без подтверждения не удалять ничего.