--- name: xbsl-deploy description: > Используй этот скилл для любых операций с приложениями на платформе 1С:Предприятие.Элемент (1cmycloud.com): создать приложение, задеплоить ветку из внешнего git-репозитория (GitHub, GitLab и др.), обновить, проверить статус, запустить, остановить, удалить, принять изменения (merge). Вызывай скилл всякий раз, когда пользователь упоминает деплой, запуск, остановку или управление приложением на Элементе — даже если он не говорит явно "задеплой", а просто спрашивает "как дела с приложением" или "смёрджи ветку". compatibility: runtime: - python3 --- # Деплой на 1С:Предприятие.Элемент > Справочник по API: `references/endpoints.md` — читай его если нужны детали по полям запросов/ответов. ## Шаг 0: Загрузи переменные окружения Перед любым обращением к API загрузи env vars. Выполни команду: ```bash set -a && source .env 2>/dev/null; set +a ``` Если `.env` не найден — продолжай: нужные переменные могут быть уже заданы в системе. Обязательные переменные: `ELEMENT_BASE_URL`, `ELEMENT_CLIENT_ID`, `ELEMENT_CLIENT_SECRET`. Если хотя бы одна отсутствует — сообщи пользователю и остановись. --- ## Два вида веток: внешний git vs внутренний git платформы В 1С:Элемент существуют **два независимых механизма веток** — не путай их: | | Внешний git (GitHub/GitLab) | Внутренний git платформы | |---|---|---| | Что это | Твой обычный git-репозиторий | Встроенная система групповой разработки платформы | | Как обновить приложение | `sync-branch` / кнопка «Загрузить из ветки» в IDE | Сценарий B (update-branch + restart) | | API | `/console/ui/module/call` (внутренний) | `GET/POST /console/api/v2/branches` | | Когда работает | Всегда (если репо доступен платформе) | Только если проект включил режим групповой разработки | | Ошибка если не поддерживается | — | 503 "does not use export branches" | | Merge изменений | Через git (PR/MR) | Сценарий G (merge-branch) | | Типичный сценарий | Деплой из GitHub на продакшн | Командная разработка задач внутри платформы (`issue/CRM-1`) | **Если получаешь 503 на `list-branches` / `get-branch`** — проект работает через внешний git. Используй Сценарий I (путь 2: `--from-branch`) вместо Сценария B. --- ## Шаг 1: Определи намерение | Фраза пользователя | Сценарий | |---|---| | создать / новое / задеплой с нуля / развернуть | **A: Создать + задеплоить** | | обновить / задеплой / загрузить ветку / редеплой | **B: Обновить существующее** | | статус / как дела / что с приложением / проверь | **C: Проверить статус** | | запусти / старт / включи | **D: Запустить** | | останови / стоп / выключи | **E: Остановить** | | удали / снести / delete / убери | **F: Удалить** | | принять изменения / смёрджи / merge | **G: Merge ветки** | | создать проект / загрузить сборку / новый проект из файла | **H: Создать проект из сборки** | | задеплой из исходников / собери и задеплой / deploy from source | **I: Собрать .xasm и задеплоить** | | sync-branch / обнови ветку в облаке / загрузить из ветки / pull из git | **J: sync-branch с фолбэком на сборку** | ## Шаг 2: Получи токен ```bash python3 .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` и проверь наличие поля `ВидПроекта: Библиотека`: ```bash grep "ВидПроекта" <путь>/Проект.yaml ``` Если найдено `ВидПроекта: Библиотека` — **остановись** и сообщи пользователю: > Платформа не может развернуть библиотеку как самостоятельное приложение. Библиотека предназначена для подключения через `Импорт` в другой проект, а не для деплоя. ### A1. Определи проект Если `ELEMENT_PROJECT_ID` не задан — выведи список проектов и попроси пользователя выбрать: ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-projects ``` Показывай только не удалённые (`"deleted": false`) проекты типа `Application`. Сохрани выбранный `project-id` для следующих шагов. ### A2. Определи space-id Если `ELEMENT_SPACE_ID` не задан: ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-spaces ``` - Если пространство **одно** — используй его `id` как `space-id`. Предложи пользователю сохранить в `.env`: `ELEMENT_SPACE_ID=`. - Если пространств **несколько** — покажи список и спроси пользователя выбрать. - Если пространств **нет** — сообщи пользователю, создать пространство нужно через веб-консоль. ### A3. Создай приложение Спроси имя приложения если не указано. ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action create-app --name --space-id --project-id ``` Сохрани `id` из ответа как `app-id`. ### A4. Запусти приложение ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action start-app --app-id ``` ### A5. Жди Running Опрашивай каждые 10 сек, до 5 мин: ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action get-app --app-id ``` Жди пока `status` == `Running`. Если `status` == `Error` — сообщи `error` пользователю и остановись. Если 5 мин прошло, а статус не `Running` — сообщи пользователю текущий статус и предложи проверить логи в консоли Элемента. ### A6. Верни ссылку Из последнего ответа `get-app` возьми поле `uri` и отправь пользователю. --- ## Сценарий B: Обновить приложение из ветки ### B1. Найди приложение Используй `ELEMENT_APP_ID` или спроси имя и найди: ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-apps --name ``` Сохрани `id` как `app-id`. ### B2. Определи project-id Используй `ELEMENT_PROJECT_ID`. Если не задан — извлеки из ответа B1: поле `project.id` в объекте приложения. Если поле `project` отсутствует или пустое: ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-projects ``` Спроси пользователя выбрать проект. Сохрани как `project-id`. ### B3. Создай дамп (страховка перед изменениями) Дамп нужен как точка отката на случай проблем после деплоя. ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action create-dump --app-id ``` Сохрани `id` из ответа как `dump-id`. Проверь статус **сразу** (без паузы), затем опрашивай каждые 3 сек (до 60 сек): ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action get-dump --app-id --dump-id ``` Жди пока `status` станет `Done` или `Completed`. **Если дамп завершился ошибкой или не готов за 60 сек — остановись и сообщи пользователю. Не продолжай.** ### B4. Найди ветку ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-branches --project-id --branch-name ``` ### B5. Привяжи ветку к приложению (если нужно) Если `branch.application.id != app-id`: ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action update-branch --branch-id --app-id ``` ### B6. Перезапусти (подхвати изменения из репозитория) Сначала останови (если приложение не `Stopped`): ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action stop-app --app-id ``` Жди `Stopped` (опрос каждые 10 сек, до 3 мин). Затем запусти: ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action start-app --app-id ``` ### B7. Жди Running → верни URL (как A5-A6) --- ## Сценарий C: Статус приложения ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action get-app --app-id ``` Выведи пользователю: - `status` (Running / Stopped / Error / ...) - `uri` — ссылка на приложение - `error` — если есть - `current-task` — текущая задача если есть - `technology-version` --- ## Сценарий D: Запустить приложение ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action start-app --app-id ``` Жди `Running` (опрос каждые 10 сек, до 5 мин) → верни статус и ссылку. Если таймаут — сообщи текущий статус и предложи проверить логи в консоли Элемента. --- ## Сценарий E: Остановить приложение ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action stop-app --app-id ``` Жди `Stopped` (опрос каждые 10 сек, до 3 мин) → сообщи что остановлено. Если таймаут — сообщи текущий статус. --- ## Сценарий F: Удалить приложение **Обязательно запроси подтверждение у пользователя** перед любым удалением. Сообщи имя удаляемого объекта и что действие необратимо. Продолжай только после явного подтверждения («да», «удали», «confirm» и т.п.). Если пользователь не подтвердил — остановись. Если приложение не `Stopped`: ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action stop-app --app-id ``` Жди `Stopped` (опрос каждые 10 сек, до 3 мин). Затем: ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action delete-app --app-id ``` Если ветка создавалась скиллом — предложи удалить и её. Удаляй ветку только после отдельного подтверждения: ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action delete-branch --branch-id ``` --- ## Сценарий G: Принять изменения (merge ветки) Если `branch-id` не известен — найди ветку. Для этого нужен `project-id` (из `ELEMENT_PROJECT_ID` или спроси пользователя через `list-projects`): ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-branches --project-id --branch-name ``` Затем выполни merge: ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action merge-branch --branch-id ``` Сообщи результат. --- ## Сценарий H: Создать проект из файла сборки Проект на Элементе создаётся загрузкой бинарного файла сборки (`.zip` или артефакт компилятора). Без файла создать проект через API нельзя. ### H1. Уточни параметры Спроси пользователя: - путь к файлу сборки (`--file`) - имя ветки (`--branch-name`), если нужно зафиксировать (иначе используется `ELEMENT_BRANCH`) - хэш коммита и сообщение (`--commit-id`, `--commit-message`) — опционально ### H2. Определи space-id Если `ELEMENT_SPACE_ID` не задан: ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-spaces ``` Если пространство одно — используй его автоматически. ### H3. Загрузи сборку и создай проект ```bash python3 .claude/skills/xbsl-deploy/scripts/api.py --action upload-build \ --file \ --space-id \ [--branch-name ] \ [--commit-id ] \ [--commit-message ] ``` Чтобы добавить сборку к **существующему** проекту, добавь `--project-id `. Из ответа возьми `project-id` для дальнейших операций (создание приложения, ветки и т.д.). --- ## Сценарий I: Деплой через deploy.py > Детали путей деплоя — см. `references/deploy-paths.md`. > Настройка CI/CD (GitHub Actions, GitLab CI) — см. `references/ci-cd.md`. ### I0. Проверь вид проекта Если известна папка проекта — прочитай `Проект.yaml` и проверь: ```bash grep "ВидПроекта" <путь>/Проект.yaml ``` Если найдено `ВидПроекта: Библиотека` — **остановись** и сообщи пользователю: > Платформа не может развернуть библиотеку как самостоятельное приложение. Библиотека предназначена для подключения через `Импорт` в другой проект, а не для деплоя. **Путь 1** (из исходников): нужны `ELEMENT_APP_ID`, `ELEMENT_PROJECT_ID`. ```bash python3 .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). ```bash python3 .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: из исходников**. Все шаги те же. --- ## Правила работы - **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` из ответа - **Удаление** (приложения, ветки, проекта) — всегда запрашивай явное подтверждение пользователя перед выполнением. Без подтверждения не удалять ничего.