HMVMFlow — настройка от А до Я

Канон для людей и агентов, когда непонятно, как устроены Flow, SDD и оркестратор. Код UI: hmvm-flow/web/. Деплой UI не рестартит MCP.

Краткий указатель: этот файл. Карточка продукта в хабе: Flow / марка FL. HTML: <strong>HMVM</strong>Flow. Title: HMVMFlow.

0. За 30 секунд

Три разные вещи, не путать:

Одной фразой: SDD — билет, Flow — дорога, оркестратор — турникет, Cursor — руки, прод — только ты.

Пачка до кода, как это делают Spec Kit и Kiro: устав проекта, истории, проверяемые критерии (КОГДА … система …), закрытые вопросы, план «как», задачи со ссылкой на критерий. «Готова» и скачиваемый SPEC.md держат эту пачку. Код страница не запускает.

1. Инвентарь

WAN домашний: 95.165.147.52. SSH с ноутбука вне LAN — через portal jump (:4000), скрипт сам переключается.

Gold UI (эталон змейки+мастера, не затирать при новых слоях): hmvm-flow/gold/2026-08-22-snake-wizard/ · git 7f3bd7c · id 2026.08.22-flow-gold.1.

2. Как открыть и войти

1. Браузер: https://flow.hmvm.ru. Справа в шапке ссылка Документация → https://flow.hmvm.ru/docs (этот текст).
2. Без сессии справа ссылка SSO / TG → https://auth.hmvm.ru/?service=flow (passkey / Telegram).
3. После входа токен в query ?hmvm_token=… снимается в sessionStorage ключ hmvm:flow:session. Чип в цвете Flow: {имя} / SSO после passkey, {имя} / TG после QR. Пока в JWT нет auth_via (старая сессия) — только имя, ссылка SSO / TG остаётся, чтобы войти заново.
4. Одна страница: слева спека, справа модели из Orch. Чип: нет спеки / черновик: … / спека: ….
5. Документация: https://flow.hmvm.ru/docs. Подключить модель — https://ai.hmvm.ru/admin, не на этой странице.

Модалки (мастер на карточке) закрываются только ✕, не кликом по фону.

Если страница «старая» (нет вкладок) — жёсткое обновление (кэш app.js?v=…).

3. Вкладка SDD — билет (делать первым)

Это не Markdown-файл руками и не логин в Git. Поля пишутся в браузер: localStorage ключ hmvm:flow:spec.

3.1. Что должно быть заполнено, чтобы Готова сработала

Иначе кнопка напишет «Ещё не готова: …»:

• название;
• «что сделать»;
• хотя бы одна строка Делаем;
• минимум три пункта Готово когда (непустых);
• репо из выпадашки (allowlist в коде).

Замки: не prod всегда включён и снять нельзя. не merge и не live PVE по умолчанию включены.

3.2. Поля

Куда (репо) — это выбор цели, не авторизация. PAT и пароль Git сюда не вводятся. См. §7.

Список репо в коде (hmvm-flow/web/app.js, REPOS):

Канон кода портала — GitLab. Cursor ходит в GitHub-зеркало. В SDD выбирай зеркало, которое видит Cloud Agent.

3.3. Кнопки

3.4. Пример А — «Kimi смотрит PR портала»

Задача: настроить чертёж так, чтобы после Git стоял ревьюер Kimi. Живой вызов Kimi ещё не включён; это пометка на схеме.

Название:        Kimi ревьюер на портал
Что сделать:     Cursor пишет фичу в GitHub-зеркало HMVM_PORTAL.
                 Kimi (потом) смотрит diff. Прод не трогаем.

Делаем:
  - PR в GitHub jnxwl-git/HMVM_PORTAL
  - карточка Code Reviewer после Git / PR

Не делаем:
  - merge в main
  - прод
  - live PVE из чата
  - рестарт MCP ai.hmvm.ru

Готово когда:
  - на Flow у шага Код подписан Cursor
  - после Git есть карточка Code Reviewer · Kimi
  - замок «не prod» включён
  (четвёртый пункт по желанию)

Репо:    jnxwl-git/HMVM_PORTAL
Ветка:   main
Пишет:   Cursor
Смотрит: Kimi

Дальше Готова → Открыть Flow. На змейке шаг Код = Cursor · Coder, после Git / PR — пунктирная карточка Code Reviewer с Kimi.

3.5. Пример Б — «только документация, без ревьюера»

Название:        Docs-only README Flow
Что сделать:     Обновить docs/HMVM_FLOW.md. Код сервисов не менять.

Делаем:
  - правки только docs/HMVM_FLOW.md и ссылок на него

Не делаем:
  - merge в main
  - прод
  - live PVE из чата
  - рестарт hmvm-ai-orchestrator

Готово когда:
  - в PR только markdown/ссылки
  - нет изменений backend/
  - спека в статусе готова

Репо:    jnxwl-git/HMVM_PORTAL
Ветка:   main
Пишет:   Cursor
Смотрит: Никто

На Flow Готовый набор → Только документация → Поставить — мастер покажет, какие карточки добавятся (docs + reviewer). Для «никто не смотрит» ревьюер из набора можно убрать кликом по карточке → убрать шаг.

3.6. Пример В — «я сам пишу, чертёж только для памяти»

Пишет код: Я сам
Смотрит:   Позже

Шаг Код получит роль «Я сам», без модели Cursor. Билет всё равно нужен: рамки и «готово когда».

3.7. Пример JSON спеки (как лежит в браузере)

Ключ hmvm:flow:spec. Посмотреть: DevTools → Application → Local Storage → flow.hmvm.ru.

{
  "version": 1,
  "id": "n_abc12xyz",
  "status": "ready",
  "title": "Kimi ревьюер на портал",
  "goal": "Cursor пишет фичу. Kimi смотрит diff. Прод не трогаем.",
  "inScope": ["PR в GitHub jnxwl-git/HMVM_PORTAL", "карточка Code Reviewer после Git"],
  "outScope": ["merge в main", "прод", "live PVE из чата"],
  "doneWhen": [
    "на Flow у Кода подписан Cursor",
    "после Git есть Code Reviewer · Kimi",
    "замок не prod включён"
  ],
  "repo": "portal",
  "branch": "main",
  "locks": { "noMerge": true, "noProd": true, "noLivePve": true },
  "writer": "cursor",
  "reviewer": "kimi"
}

writer: cursor | me | later. reviewer: kimi | claude | none | later.

4. Змейка снята

Живая страница — спека и колонка моделей. Конвейер из 11 шагов не рисуется. Старый UI лежит в hmvm-flow/gold/2026-08-22-snake-wizard/ и оттуда на прод не возвращается сам.

Колонка Модели читает GET /api/orch/connections (сессия Flow). Это факт, не настройка:

• Cursor на шлюзе — model-default.json или env оркестратора
• твой Cursor — личный ключ и модель из workspace того же sub, без шифротекста
• чат — есть ли секрет коннектора

Ключ Cursor, master и секрет чата здесь не показываются и не пишутся. Смена модели — в Orch.

Ниже — как змейка была устроена, пока её не вернули.

4a. Бывшая дорога (змейка, не на проде)

Читай змейкой: ряд 1 вправо, вниз, ряд 2 влево, вниз, ряд 3 вправо. После каждого шага голубая стрелка.

Канон 11 шагов:

Карточки с рамкой акцента — шаги, которые подписала готовая спека (Код и Code Reviewer).

4.1. Мастер на карточке

• Клик по карточке — роль → модель → сохранить (или убрать добавленный шаг).
• + — вставить шаг после этой карточки: тип → роль → модель.
• Готовый набор — не сыплет карточки молча: Поставить сначала объясняет, что добавится.

Модели в мастере (пока пометка, не живой ключ): Kimi, Grok, ChatGPT, Cursor, Claude, позже.

4.2. Чертёж JSON

Кнопки Скачать JSON / Загрузить JSON. Ключ localStorage: hmvm:flow:pipeline.

Сброс змейки: Сбросить чертёж (11 шагов). Спеку не трогает.

5. Что уже живое, а что только чертёж

6. Оркестратор (MCP) — турникет

Grok или ChatGPT не ходят на PVE и не мержат main. Они вызывают tools оркестратора. Оркестратор:

• проверяет allowlist репо / ветки;
• не стартует с внутренних cursor/*, если ref не виден на GitHub;
• не делает prod/merge;
• при разрешении вызывает Cursor (cursor_start_task и соседние tools).

Запрещено без окна: systemctl restart hmvm-ai-orchestrator, смена имён tools, ротация MCP_SHARED_SECRET, сужение ALLOWED_HOSTS.

Проверка, что жив:

curl -sf https://ai.hmvm.ru/healthz
./maintenance/ssh-ai.sh 'systemctl is-active hmvm-ai-orchestrator hmvm-flow-web'

Подключение MCP в ChatGPT / Grok / Claude: URL https://ai.hmvm.ru/mcp. Admin доступ: https://ai.hmvm.ru/admin (SSO grant ai) — именные токены, revoke, ротация master, просмотр настроек. Claude/друг: на Allow ввести именованный токен из admin (не обязательно master). OAuth redirect allowlist: ChatGPT/OpenAI, claude.ai / claude.com, Grok/x.ai (+ loopback для Claude Code).

Когда (потом) Run включат: оркестратор должен требовать spec_id из готовой спеки. Пока спека только в браузере.

7. Git: куда ключи, куда нет

Два Git, разные роли:

В SDD / Flow не настраивают Git-логин. Нет поля token, нет OAuth «войти в GitHub».

Где авторизация на самом деле:

1. Cursor — GitHub App / token в Cloud Environment / аккаунт агента. Это настраивается в Cursor, не на flow.hmvm.ru.
2. Оркестратор — allowlist хостов/репо в своём .env на LXC 115 (не в git портала). Менять только в окно.
3. Ты — SSH/HTTPS к GitLab как обычно.

Если агент «не видит репо»: сначала проверь, что зеркало на GitHub существует и ref запушен; потом allowlist MCP; не вставляй PAT в спеку.

Когда Flow сам начнёт читать diff — отдельный GitHub App на сервере LXC, токен не в localStorage.

8. SSO / Auth

Плитка Flow на auth.hmvm.ru. Grant flow. Секрет на auth VM: FLOW_JWT_SECRET (см. auth/.env.example). Пустой → fallback на portal JWT, как у соседних сервисов.

Без входа чертёж в браузере всё равно рисуется (localStorage). SSO нужен как у остальных продуктов хаба, не как ключ Git.

9. Деплой и откат UI

Только статика+python UI, unit hmvm-flow-web. MCP не рестартится скриптом:

./maintenance/deploy-flow-to-prod.sh
curl -sf https://flow.hmvm.ru/health
curl -sf https://ai.hmvm.ru/healthz

Путь на LXC: /opt/hmvm-flow. Скрипт: LAN 10.10.1.51, иначе portal wan-jump.

Вернуть gold-змейку (без вкладок SDD — это снимок до вкладок):

cp hmvm-flow/gold/2026-08-22-snake-wizard/{index.html,app.js,styles.css,favicon.svg} hmvm-flow/web/
./maintenance/deploy-flow-to-prod.sh

Откат «вкладок» — git checkout нужного коммита hmvm-flow/web/, не gold, если нужны SDD-вкладки.

DNS / NPM (уже сделано, не гонять без нужды):

./maintenance/setup-hmvm-flow.sh          # DNS
./maintenance/setup-hmvm-flow-npm.sh      # NPMplus + LE, не трогает ai.hmvm.ru

10. SSH на LXC

./maintenance/ssh-ai.sh --print-target
./maintenance/ssh-ai.sh 'hostname; ss -lptn | grep -E "8787|8088"; systemctl is-active hmvm-ai-orchestrator hmvm-flow-web'

Не ssh root@10.10.1.51 с ноутбука вне дома — только обёртка.

11. Частые сбои

Очистить только чертёж: сброс на Flow. Очистить спеку: DevTools → удалить hmvm:flow:spec.

12. Что не делать

• Рестартить hmvm-ai-orchestrator «чтобы Flow заработал».
• Класть GitHub PAT, Moonshot, Anthropic, MCP_SHARED_SECRET в SDD или в JSON чертежа.
• Считать выбор репо в SDD логином в Git.
• Включать Run и Always allow без окна.
• Деплоить Flow через deploy-to-prod.sh портала — для UI есть deploy-flow-to-prod.sh.
• Ломать gold-каталог правками «упростим змейку поверх».

13. Порядок «хочу прогон», когда появится окно

1. SDD заполнить → Готова.
2. Flow проверить подписи Код / ревьюер.
3. В чате Grok/ChatGPT (живой MCP) или будущая кнопка Run — старт Cursor с тем же репо.
4. PR на GitHub → ревью (человек / потом Kimi) → ты мержишь на GitLab → прод сам.

До окна шаг 3 из UI не существует.

14. Файлы в репо

Код оркестратора MCP — отдельный репо GitHub jnxwl-git/hmvm-ai-orchestrator (не путать с UI в этом дереве).

15. Вкладка HMVMAi — основная модель Cursor

https://flow.hmvm.ru/#orch. Нужна сессия Flow (SSO / TG). Ключ Cursor в браузер не попадает.

1. Опросить Cursor — Flow на HMVMAi читает каталог GET /v1/models.
2. Сделать основной — пишет /opt/hmvm-ai-orchestrator/data/model-default.json (id, effort, fast, время). Без ключей.
3. Оркестратор читает этот файл на каждом cursor_start_task / follow-up, если в вызове нет своего modelId. Явный modelId в вызове важнее.
4. Auto основной поставить нельзя.

Пока файла нет, основная — CURSOR_DEFAULT_MODEL_ID из env (grok-4.6 / xhigh / Fast off).