gpu-rent/docs/extensions.md

# Расширения: git-репы на bootstrap

## Быстрый старт

```powershell
copy extensions.example.yaml extensions.yaml
# добавь url реп (публичные — без GIT_TOKEN)
.\gpu-rent.ps1 up --yes
# доклонировать на уже живой VM:
.\gpu-rent.ps1 seed-extensions
# записать установленные на VM репы обратно в extensions.yaml (без clone локально):
.\gpu-rent.ps1 capture extensions
```

Срабатывает на каждом `up` (и `seed-extensions`):

- нет каталога → `git clone`;
- каталог есть → по умолчанию `fetch` + `reset --hard` на `ref` (или текущую ветку для уже установленных вне yaml);
- `--no-update` / `UPDATE_GIT=false` → существующие репы не трогаем, только недостающие clone.

Также обновляется сам SwarmUI в `/opt/swarmui` (тот же флаг).

Два разных мира — не путать:

| Вид | Куда клонировать | Что это |
| --- | --- | --- |
| `swarmui` | `/mnt/swarm_data/Extensions/<dir>` → `/opt/swarmui/src/Extensions/<dir>` | C# extension SwarmUI (класс `: Extension`). После рестарта подхватывается сам |
| `comfy` | `/mnt/swarm_data/DLNodes/<dir>` → `…/ComfyUIBackend/DLNodes/<dir>` | Custom nodes ComfyUI (Python). `requirements.txt` ставит SwarmUI/Comfy при первом старте backend |
| `assistent` | `/mnt/swarm_data/Assistent/extensions/<dir>/` | Persona pack (полки JSON + `assistent-pack.yaml`). Без рестарта C# — Assistent читает с диска |

Пустой манифест или его нет — ничего не клонируем, SwarmUI как из коробки. Это не связано с Civitai-токеном.

## Манифест

Пример: [`extensions.example.yaml`](../extensions.example.yaml). Рабочая копия: `extensions.yaml` в корне репо (или `EXTENSIONS_MANIFEST`).

```yaml
swarmui:
  - url: https://gitea.hsrv.site/mrleo1nid/swarm-assistent.git
    ref: main
    dir: swarm-assistent
    requires: ollama   # none | ollama | any-llm; default none = always
  - url: https://github.com/example/SwarmUI-SomeExt.git
    ref: main
    dir: SomeExt
assistent: []
  # - url: https://example.com/org/some-persona-pack.git
  #   ref: main
  #   dir: some-persona-pack
  #   requires: ollama
comfy:
  - url: https://github.com/example/ComfyUI-Something.git
    ref: v1.2.0
```

| `requires` | Когда клонировать |
| --- | --- |
| `none` (или поле отсутствует) | всегда |
| `ollama` | только при `LLM_RUNTIME=ollama` |
| `any-llm` | при `LLM_RUNTIME=ollama` (сейчас единственный LLM-рантайм; llama.cpp снят) |

Строки с несовпавшим `requires` пропускаются (лог), остальные ставятся как обычно. В `extensions.example.yaml` по умолчанию — **swarm-assistent** с `requires: ollama` (чат + доска Generate/Ref + persona/Cards, ветка `main`). После `seed-extensions` + рестарта SwarmUI подтягивается текущий `main` (с **0.13.1+**: `CopyLocalLockFileAssemblies` копирует `Microsoft.Data.Sqlite` + `SQLitePCLRaw*` рядом с extension DLL — иначе ListMemory/ListChats/SaveChat падают; с **0.10.11**: default chat = `default_chat` / старший тег, warm той же моделью).

### Persona packs

Bundled в swarm-assistent: `neutral` (Нормальный), `aggressive`, `dreamer`. Дополнительные личности — git-паки:

1. **Конфиг** — секция `assistent:` в `extensions.yaml` (clone на VM в `Assistent/extensions/<dir>/`).
2. **Локально** — клоны в `assistent-extensions/<dir>/` (gitignored). На `up` / `seed-personas` / `push` уезжают SFTP **без** `.git` в тот же dest. Приватные паки можно держать только так — без URL в yaml (capture их не увидит).

Формат пака: `assistent-pack.yaml` (`kind: persona`, `id: …`) + полки JSON в корне (или `personas/<id>/` для мульти-пака). На `up` также пишется `_base/assistant.json` (`default_persona: neutral`, опционально `num_ctx` с GPU tier). Seed **не** удаляет overlay-личности, созданные в UI. Legacy `assistent-personas/` / `personas.json` больше не сидятся.

Если есть `datasets/civitai/search.jsonl`, на том же шаге пушится FTS-индекс → `/mnt/swarm_data/Assistent/civitai-examples.jsonl` ([datasets/README](../datasets/README.md)). Диагностика Assistent: Debug API `/assistent/*` ([cli.md](cli.md)).

В git репозитория gpu-rent не коммитить рабочий список с лишними приватными URL сверх примера.

## Когда в жизненном цикле

Idle-killer ещё не вооружён. Git нужен на VM (`apt` в bootstrap, если нет в образе).

1. Маркер FS data volume.
2. **Clone extensions** (этот документ). Маркер `/mnt/swarm_data/.gpu-rent-extensions-seeded` после успешного прохода всех строк.
3. Civitai-seed моделей ([models.md](models.md)), если есть токен.
4. Первый `systemctl start swarmui`: видит `src/Extensions`, собирает их; ComfyUI ставит pip из DLNodes.
5. Backend Idle → idle-killer.

Порядок 2→3 важен: расширения до старта UI, модели тоже до старта (чтобы не качать дефолт SwarmUI).

Позже: `gpu-rent seed-extensions` — те же clone/fetch на живом диске, затем **рестарт** SwarmUI (иначе новый C# extension не подхватится). CLI предупреждает и делает `systemctl restart swarmui`, если VM жива.

## Clone на VM

- `git clone --recurse-submodules`.
- Если `ref` — ветка/тег: `--depth 1` + `checkout`.
- Если `ref` похож на SHA: fetch этого commit (shallow может не хватить).
- Каталог уже есть и `remote origin` совпадает с `url` → `fetch` + `checkout ref`, не `rm -rf`.
- Каталог есть, origin другой → fail этой строки, не молча перезаписывать.

Публичный HTTPS без секретов. Приватный репозиторий:

- `GIT_TOKEN` в `.env` (GitHub: `x-access-token`; GitLab: `oauth2` / PAT). CLI подставляет в URL **только на VM**, не пишет токен в yaml и не в cloud-init.
- Либо отдельный deploy key `<repo>/.gpu-rent/git_deploy` — v1.1, не обязательно сейчас.

Не использовать `git://`. Только `https://` и `git@` + ключ.

## Сбой

Одна строка упала (404, auth, сеть) — остальные можно продолжить; `up` в конце ненулевой, маркер seeded не ставить, повтор доклонирует. Не оставлять полупустой `.git`.

## Конфиг

```env
EXTENSIONS_MANIFEST=   # пусто = <repo>/extensions.yaml
GIT_TOKEN=             # опционально, для приватных https
```