Во всех командах ниже {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} .claude/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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

A5. Жди Running

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

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

Жди пока status == Running. Если status == Error — сообщи error пользователю и остановись. Если 5 мин прошло, а статус не Running — сообщи пользователю текущий статус и предложи проверить логи в консоли Элемента.

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

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

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

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

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

{python} .claude/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} .claude/skills/xbsl-deploy/scripts/api.py --action list-projects

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{python} .claude/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} .claude/skills/xbsl-deploy/scripts/api.py --action start-app --app-id <app-id>

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

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

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

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

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

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

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

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

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

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

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

{python} .claude/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} .claude/skills/xbsl-deploy/scripts/api.py --action list-branches --project-id <project-id> --branch-name <branch>

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

{python} .claude/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} .claude/skills/xbsl-deploy/scripts/api.py --action list-spaces

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

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

{python} .claude/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>.

Из ответа возьми project-id для дальнейших операций (создание приложения, ветки и т.д.).

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

Детали путей деплоя — см. references/deploy-paths.md. Настройка CI/CD (GitHub Actions, GitLab CI) — см. references/ci-cd.md.

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

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

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

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

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

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

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

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

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

{python} .claude/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: Версия технологии

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

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

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

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

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

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

{python} .claude/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} .claude/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} .claude/skills/xbsl-deploy/scripts/api.py --action stop-app --app-id <app-id>

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

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

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

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

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

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

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

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

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