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

Руководство пользователя HSM: Управление Стеком

hsm (Hyper Stack Manager) — это инструмент для декларативного управления окружением проекта, объединяющий Python-пакеты и Docker-сервисы.

1. Манифест hsm.yaml​

Файл hsm.yaml в корне вашего проекта описывает желаемое состояние стека.

project:
  name: "my-rag-app"

# Группы библиотек
libraries:
  groups:
    vector-db:
      strategy: 1-of-N
      selection: qdrant-adapter

# Группы сервисов
services:
  groups:
    infra:
      strategy: M-of-N
      selection: ["postgres", "redis"]

modes:
  qdrant-adapter: dev
  postgres: prod
  redis: prod

2. Команды управления проектом​

hsm init​

Инициализирует новый проект, создавая hsm.yaml. Команда также подготавливает структуру локального реестра hsm-registry/, обеспечивая автономность проекта.

hsm check​

Выполняет валидацию проекта без внесения изменений. Проверяет наличие всех компонентов в реестре и отсутствие конфликтов в зависимостях. Это критически важный этап для CI/CD и перед запуском синхронизации.

hsm sync​

Материализует намерения из hsm.yaml в реальные конфиги и окружение.

  • Обновляет pyproject.toml.
  • Генерирует docker-compose.hsm.yml.
  • Вызывает uv sync.
  • Транзакционность: Если синхронизация не удалась, HSM откатит изменения в pyproject.toml.

hsm list​

Показывает текущий состав вашего стека: активные группы, пакеты и их режимы.

3. Редактирование стека​

hsm library add / remove​

Управление отдельными библиотеками.

hsm library add langchain
hsm library remove langchain

hsm library init​

Создает новую локальную библиотеку в папке ./libraries/ и автоматически регистрирует ее в реестре. Это реализует паттерн Self-Bootstrapping Sandbox, позволяя мгновенно переходить от идеи к коду.

hsm group add / remove​

Управление логическими группами (интерфейсами).

hsm group add vector-db --option qdrant-adapter

При добавлении опции HSM автоматически разрешает зависимости через механизм Implies.

hsm mode​

Глобальное переключение режима для всего проекта.

hsm mode dev

hsm library mode / hsm service mode​

Атомарное переключение режима для конкретной библиотеки или сервиса.

hsm library mode qdrant-adapter dev
hsm service mode postgres prod

4. Работа с Реестром​

Реестр — это база знаний о доступных компонентах.

hsm registry search <query>​

Поиск пакетов, контейнеров и групп в глобальном реестре.

hsm registry show <name>​

Просмотр детальной информации о компоненте (источники, версии, зависимости).

5. Командная работа и CI/CD​

Для воспроизводимости в CI/CD используйте:

hsm sync --frozen

Это гарантирует, что окружение будет собрано строго по зафиксированным версиям без попыток обновления.