Lobster Multi-Agent System

Локальная динамическая мультиагентная система с оркестратором, Docker-изоляцией исполнения, постоянной памятью и восстановлением контекста из workdir.

• Единая точка входа по документации: docs/INDEX.md
• Исходный файл требований: requirements.md

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

python -m venv .venv
source .venv/bin/activate
pip install -e .

Запуск:

lobster-orchestrator

По умолчанию настройки читаются из config/settings.yaml.

Профильные YAML-файлы (чтобы не раздувать CLI-ключи):

• config/settings/base.yaml
• config/settings/dev.yaml
• config/settings/ci.yaml
• config/settings/strict.yaml
• config/settings/test.yaml
• config/settings/full_llm_docker.yaml

Запуск с отдельным файлом профиля:

lobster-orchestrator --settings ./config/settings/strict.yaml

Тестовый запуск:

lobster-orchestrator --settings ./config/settings/test.yaml

Полноценный запуск с Docker-агентами и реальной LLM:

lobster-orchestrator --settings ./config/settings/full_llm_docker.yaml

Опционально с Docker-образом для инструментов:

lobster-orchestrator --goal "Собрать MVP backend" --workdir /absolute/path/to/workdir --docker-image python:3.11-slim

Подключение вспомогательного проекта в workdir через hardlink:

lobster-orchestrator --goal "Собрать MVP backend" --workdir /absolute/path/to/workdir --hardlink-source /absolute/path/to/another/project

Что делает система

1. Запускает pre-run агента-аналитика и формирует initial assignment v1 из внешнего goal
2. Создаёт структуру workdir/ai_art и workdir/output
3. При повторном запуске анализирует содержимое ai_art
4. Формирует RACI-роли и узкоспециализированных агентов динамически под цель
5. Генерирует индивидуальные assignment и system_prompt для каждого агента
6. Создаёт BMAD-спеки и общий контекст в markdown
7. Сохраняет память в markdown + Mem0 (если установлен)
8. Создаёт задачи в формате FMA + A3
9. Выполняет команды через Docker-контейнер с примонтированным workdir
10. Экспортирует merged-каталог ролей в ai_art/specs/effective_roles_catalog.{json,md}
11. Выполняет действия агентов: terminal-команды и Python-сниппеты (по каталогу ролей)
12. Выполняет веб-поиск для агентов и сохраняет результаты в ai_art/runtime/web_search/*

Артефакт аналитика:

• ai_art/specs/analyst_initial_assignment.md

Каталог ролей (MD/JSON)

• Базовый JSON-каталог: config/roles_catalog.json
• Markdown overlay: config/roles_catalog.md (блоки json, приоритет выше JSON при совпадении slug)

CLI-переопределения:

lobster-orchestrator --goal "..." --workdir /tmp/lobster-work --roles-json /path/roles.json --roles-md /path/roles.md

Для terminal-команд роли можно задавать интерактивный режим:

{
	"default_terminal_commands": [
		"ls -la",
		{"command": "python manage.py createsuperuser", "interactive_mode": "interactive"}
	]
}

Явно указать YAML-файл настроек:

lobster-orchestrator --settings /path/to/settings.yaml

Отключить выполнение действий агентами:

lobster-orchestrator --goal "..." --workdir /tmp/lobster-work --no-agent-actions

Отключить pre-run аналитика:

lobster-orchestrator --goal "..." --workdir /tmp/lobster-work --no-analyst-prepass

Профили запуска:

lobster-orchestrator --profile dev
lobster-orchestrator --profile ci --goal "..." --workdir /tmp/lobster-work
lobster-orchestrator --profile strict --goal "..." --workdir /tmp/lobster-work

Провалидировать каталог ролей (JSON + MD overlay) и завершиться:

lobster-orchestrator --validate-catalog --roles-json ./config/roles_catalog.json --roles-md ./config/roles_catalog.md

Политика выполнения:

• По умолчанию policy-ограничения применяются и в Docker (unrestricted_in_docker: false)
• Локально действует deny/allow policy для terminal-команд
• Python-сниппеты по умолчанию запрещены (allow_python: false), включаются через --allow-python
• Включить ограничения и в Docker принудительно: --restricted-in-docker
• Дополнить policy: --allow-command-pattern и --deny-command-pattern

Ограничения рантайма:

• Таймаут команд: --command-timeout-sec
• Docker лимиты: --docker-cpus, --docker-memory, --docker-pids-limit, --docker-network
• Hardening Docker: --docker-read-only, --docker-user, --docker-keep-caps

Интерактивные команды (когда процесс ждёт ввод):

• При таймауте создаётся ai_art/runtime/input_requests/<request_id>.json с накопленным выводом.
• Повторный запуск с вводом:

lobster-orchestrator --workdir /tmp/lobster-work --resolve-input-request <request_id> --input-text "y\n"

Проверки качества

pip install -e '.[dev]'
ruff check src tests
mypy src
pytest -q

Публикация на GitHub

Репозиторий для публичного релиза: https://github.com/yudin-s/lobster.

Перед публикацией:

1. Убедиться, что в индексе git нет локальных артефактов (__pycache__, *.egg-info, workdir/*).
2. Запустить проверки качества:

ruff check src tests
mypy src
pytest -q

3. Проверить каталог ролей:

lobster-orchestrator --validate-catalog --roles-json ./config/roles_catalog.json --roles-md ./config/roles_catalog.md

Полезные файлы для публичного репозитория:

• Лицензия: LICENSE
• Правила вклада: CONTRIBUTING.md
• Политика безопасности: SECURITY.md
• Кодекс поведения: CODE_OF_CONDUCT.md
• История изменений: CHANGELOG.md

Модели для тестов

Рекомендуемые модели для локального MacBook Pro M1 Pro (32GB unified memory):

• Qwen3-Instruct
• KIMI 2.5

Система не привязана к конкретному рантайму модели: можно использовать Ollama/vLLM/LM Studio, если endpoint доступен локально.