Перейти к основному содержимому

HSM Workflow Guide: Единый процесс управления стеком

Этот документ является точкой входа для понимания того, как Hyper Stack Manager (hsm) оркестрирует разработку сложных систем, объединяя миры Python и Docker.

1. Концепция: Intent vs Artifacts​

hsm разделяет "желаемое состояние" и "техническую реализацию":

  • Intent (Намерение): Описывается в hsm.yaml. Вы указываете компоненты, их версии и режимы (dev/prod).
  • Artifacts (Артефакты): Результат hsm sync. Это конфиги pyproject.toml (для Python) и docker-compose.hsm.yml (для Docker), которые HSM генерирует автоматически.

2. Основные сценарии (Deep Dives)​

Для детального изучения каждого направления используйте специализированные руководства:

  • Python Workflow — управление зависимостями через uv, editable-режимы и замена Git Submodules.
  • Docker Workflow — динамическое управление контейнерами, использование Profiles и генерация Override-файлов.
  • VES Workflow — работа с изолированными сервисами через рантайм uv.

3. Гибридный воркфлоу (Hybrid Stack)​

Главная сила HSM — в одновременном управлении кодом и инфраструктурой.

Пример из жизни: Вы разрабатываете RAG-систему и хотите заменить Qdrant на Milvus.

  1. Команда: hsm group add vector-db --option milvus.
  2. Действие HSM:
    • В pyproject.toml прописывается клиент для Milvus.
    • В docker-compose.hsm.yml прописывается запуск контейнера Milvus вместо Qdrant.
  3. Sync: Один вызов hsm sync перестраивает весь стек.

4. Жизненный цикл проекта с HSM​

ЭтапКомандаРезультат
Инициализацияhsm initСоздание hsm.yaml и структуры реестра.
Добавлениеhsm library add <name>Поиск в Реестре и добавление в манифест.
Разработкаhsm library mode <name> devПереключение компонента на локальные исходники.
Валидацияhsm checkПроверка целостности стека (dry-run).
Синхронизацияhsm syncАтомарное обновление конфигов uv и docker.

5. Почему это удобно?​

  • Транзакционность: Если uv sync не прошел, ваш проект не "развалится" — HSM откатит изменения в pyproject.toml.
  • Чистота: Все временные пути разработки (/home/user/...) живут только в генерируемых файлах и не попадают в Git.
  • Скорость: HSM берет на себя всю рутину по связыванию компонентов, позволяя вам фокусироваться на логике.