Архитектура
Карта верхнего уровня внутренностей VibeOS. Ориентир по дереву кода; детали реализации — в docs конкретной подсистемы.
Обзор системы
┌─────────────────────────────────────────────────────────────────────┐
│ Entry Points │
│ │
│ CLI (cli.py) Gateway (gateway/run.py) ACP (acp_adapter/) │
│ Batch Runner API Server Python Library │
└──────────┬──────────────┬───────────────────────┬───────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ AIAgent (run_agent.py) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Prompt │ │ Provider │ │ Tool │ │
│ │ Builder │ │ Resolution │ │ Dispatch │ │
│ │ (prompt_ │ │ (runtime_ │ │ (model_ │ │
│ │ builder.py) │ │ provider.py)│ │ tools.py) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ┌──────┴───────┐ ┌──────┴───────┐ ┌──────┴───────┐ │
│ │ Compression │ │ 3 API Modes │ │ Tool Registry│ │
│ │ & Caching │ │ chat_compl. │ │ (registry.py)│ │
│ │ │ │ codex_resp. │ │ 70+ tools │ │
│ │ │ │ anthropic │ │ 28 toolsets │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────┴─────────────────┴─────────────────┴───────────────────────┘
│ │
▼ ▼
┌───────────────────┐ ┌──────────────────────┐
│ Session Storage │ │ Tool Backends │
│ (SQLite + FTS5) │ │ Terminal (6 backends) │
│ vibeos_state.py │ │ Browser (5 backends) │
│ gateway/session.py│ │ Web (4 backends) │
└───────────────────┘ │ MCP (dynamic) │
│ File, Vision, etc. │
└──────────────────────┘
Структура каталогов
vibeos-agent/
├── run_agent.py # AIAgent — core conversation loop (large file)
├── cli.py # VibeOSCLI — interactive terminal UI (large file)
├── model_tools.py # Tool discovery, schema collection, dispatch
├── toolsets.py # Tool groupings and platform presets
├── vibeos_state.py # SQLite session/state database with FTS5
├── vibeos_constants.py # VIBEOS_HOME, profile-aware paths
├── batch_runner.py # Batch trajectory generation
│
├── agent/ # Agent internals
│ ├── prompt_builder.py # System prompt assembly
│ ├── context_engine.py # ContextEngine ABC (pluggable)
│ ├── context_compressor.py # Default engine — lossy summarization
│ ├── prompt_caching.py # Anthropic prompt caching
│ ├── auxiliary_client.py # Auxiliary LLM for side tasks (vision, summarization)
│ ├── model_metadata.py # Model context lengths, token estimation
│ ├── models_dev.py # models.dev registry integration
│ ├── anthropic_adapter.py # Anthropic Messages API format conversion
│ ├── display.py # KawaiiSpinner, tool preview formatting
│ ├── skill_commands.py # Skill slash commands
│ ├── memory_manager.py # Memory manager orchestration
│ ├── memory_provider.py # Memory provider ABC
│ └── trajectory.py # Trajectory saving helpers
│
├── vibeos_cli/ # CLI subcommands and setup
│ ├── main.py # Entry point — all `vibeos` subcommands (large file)
│ ├── config.py # DEFAULT_CONFIG, OPTIONAL_ENV_VARS, migration
│ ├── commands.py # COMMAND_REGISTRY — central slash command definitions
│ ├── auth.py # PROVIDER_REGISTRY, credential resolution
│ ├── runtime_provider.py # Provider → api_mode + credentials
│ ├── models.py # Model catalog, provider model lists
│ ├── model_switch.py # /model command logic (CLI + gateway shared)
│ ├── setup.py # Interactive setup wizard (large file)
│ ├── skin_engine.py # CLI theming engine
│ ├── skills_config.py # vibeos skills — enable/disable per platform
│ ├── skills_hub.py # /skills slash command
│ ├── tools_config.py # vibeos tools — enable/disable per platform
│ ├── plugins.py # PluginManager — discovery, loading, hooks
│ ├── callbacks.py # Terminal callbacks (clarify, sudo, approval)
│ └── gateway.py # vibeos gateway start/stop
│
├── tools/ # Tool implementations (one file per tool)
│ ├── registry.py # Central tool registry
│ ├── approval.py # Dangerous command detection
│ ├── terminal_tool.py # Terminal orchestration
│ ├── process_registry.py # Background process management
│ ├── file_tools.py # read_file, write_file, patch, search_files
│ ├── web_tools.py # web_search, web_extract
│ ├── browser_tool.py # 10 browser automation tools
│ ├── code_execution_tool.py # execute_code sandbox
│ ├── delegate_tool.py # Subagent delegation
│ ├── mcp_tool.py # MCP client (large file)
│ ├── credential_files.py # File-based credential passthrough
│ ├── env_passthrough.py # Env var passthrough for sandboxes
│ ├── ansi_strip.py # ANSI escape stripping
│ └── environments/ # Terminal backends (local, docker, ssh, modal, daytona, singularity)
│
├── gateway/ # Messaging platform gateway
│ ├── run.py # GatewayRunner — message dispatch (large file)
│ ├── session.py # SessionStore — conversation persistence
│ ├── delivery.py # Outbound message delivery
│ ├── pairing.py # DM pairing authorization
│ ├── hooks.py # Hook discovery and lifecycle events
│ ├── mirror.py # Cross-session message mirroring
│ ├── status.py # Token locks, profile-scoped process tracking
│ ├── builtin_hooks/ # Extension point for always-registered hooks (none shipped)
│ └── platforms/ # 20 adapters: telegram, discord, slack, whatsapp,
│ # signal, matrix, mattermost, email, sms,
│ # dingtalk, feishu, wecom, wecom_callback, weixin,
│ # bluebubbles, qqbot, homeassistant, webhook, api_server,
│ # yuanbao
│
├── acp_adapter/ # ACP server (VS Code / Zed / JetBrains)
├── cron/ # Scheduler (jobs.py, scheduler.py)
├── plugins/memory/ # Memory provider plugins
├── plugins/context_engine/ # Context engine plugins
├── skills/ # Bundled skills (always available)
├── optional-skills/ # Official optional skills (install explicitly)
├── website/ # Docusaurus documentation site
└── tests/ # Pytest suite (~25,000 tests across ~1,250 files)
Data Flow
CLI Session
User input → VibeOSCLI.process_input()
→ AIAgent.run_conversation()
→ prompt_builder.build_system_prompt()
→ runtime_provider.resolve_runtime_provider()
→ API call (chat_completions / codex_responses / anthropic_messages)
→ tool_calls? → model_tools.handle_function_call() → loop
→ final response → display → save to SessionDB
Сообщение шлюза
Platform event → Adapter.on_message() → MessageEvent
→ GatewayRunner._handle_message()
→ authorize user
→ resolve session key
→ create AIAgent with session history
→ AIAgent.run_conversation()
→ deliver response back through adapter
Задание Cron
Scheduler tick → load due jobs from jobs.json
→ create fresh AIAgent (no history)
→ inject attached skills as context
→ run job prompt
→ deliver response to target platform
→ update job state and next_run
Рекомендуемый порядок чтения
Если вы новичок в кодовой базе:
- Эта страница — ориентируйтесь
- Внутреннее устройство цикла агента — как работает AIAgent
- Быстрая сборка — построение системной подсказки
- Разрешение во время выполнения поставщика — способ выбора поставщиков
- Добавление провайдеров — практическое руководство по добавлению нового провайдера
- Tools Runtime — реестр инструментов, отправка, среды
- Хранилище сеансов — схема SQLite, FTS5, линия сеанса
- Внутреннее устройство шлюза — шлюз платформы обмена сообщениями
- Сжатие контекста и кэширование подсказок — сжатие и кэширование
- ACP Внутренние устройства — IDEintegration
Основные подсистемы
Агент Loop
Механизм синхронной оркестрации (AIAgent в run_agent.py). Управляет выбором поставщика, созданием подсказок, выполнением инструмента, повторными попытками, откатом, обратными вызовами, сжатием и сохранением. Поддерживает три режима API для серверных частей разных поставщиков.
→ Внутренние элементы цикла агента
Подсказка System
Prompt создание и обслуживание на протяжении всего жизненного цикла диалога:
system_prompt.py+prompt_builder.py— собирает упорядоченные уровни системных подсказок (stable→context→volatile): identity/tool guidance/skills, контекстные файлы, затем memory/profile/timestamp блокиprompt_caching.py— применяет точки останова кэша Anthropic для кэширования префиксаcontext_compressor.py— суммирует промежуточные повороты разговора, когда контекст превышает пороговые значения
→ Подсказка сборки, Сжатие контекста и подсказка кэширования
Разрешение поставщика
Общий преобразователь времени выполнения, используемый CLI, шлюз, cron, ACP и вспомогательные вызовы. Сопоставляет кортежи (provider, model) с (api_mode, api_key, base_url). Обрабатывает более 18 провайдеров, потоки OAuth, пулы учетных данных и разрешение псевдонимов. System
Центральный реестр инструментов (tools/registry.py) с более чем 70 зарегистрированными инструментами в ~28 наборах инструментов. Каждый файл инструмента самостоятельно регистрируется во время импорта. Реестр управляет сбором, отправкой, проверкой доступности и переносом ошибок схемы. Инструменты терминала поддерживают 6 бэкэндов (локальных, Docker, SSH, Daytona, Modal, Singularity).
→ Среда выполнения инструментов
Сохранение сеанса
SQLite на базе хранилища сеансов с FTS5 полнотекстовый поиск. Сеансы имеют отслеживание происхождения (parent/child при сжатии), изоляцию для каждой платформы и атомарную запись с обработкой конфликтов.
→ [Session] Хранилище](./session-storage.md)
Шлюз обмена сообщениями
Длительный процесс с 20 адаптерами платформы, унифицированная маршрутизация сеансов, авторизация пользователей (списки разрешенных + соединение DM), диспетчеризация slash-команд, перехватчик системы, тиканье cron и фоновое обслуживание.
Плагин Система
Три источника обнаружения: ~/.vibeos/plugins/ (пользователь), .vibeos/plugins/ (проект) и точки входа в пункты. Плагины регистрируют инструменты, перехватчики и команды CLI через контекст API. Существует два специализированных типа плагинов: поставщики памяти (plugins/memory/) и механизмы контекста (plugins/context_engine/). Оба доступны по одному выбору — одновременно может быть активен только один из каждого, настроенный через vibeos plugins или config.yaml.
→ Руководство по плагинам, Поставщик памяти Плагин
Cron
Первоклассные задачи агента (не задачи оболочки). Задания хранятся в JSON, поддерживают несколько форматов расписаний, могут прикреплять навыки и сценарии и доставляться на любую платформу. ACP Интеграция
Открывает VibeOS в качестве собственного агента редактора над stdio/JSON-RPC для VS Code, Zed и JetBrains.
Траектории
Генерирует траектории в формате ShareGPT из сеансов агента для создания обучающих данных.
→ Траектории и обучение Формат
Принципы проектирования
| Принцип | Что это означает на практике |
|---|---|
| Быстрая стабильность | Системное приглашение не меняется во время разговора. Никаких мутаций, нарушающих кэш, за исключением явных действий пользователя (/model). |
| Наблюдаемое исполнение | Каждый вызов инструмента виден пользователю через обратные вызовы. Обновления прогресса в CLI (спиннер) и шлюзе (сообщения чата). |
| Прерываемый | Вызовы API и выполнение инструментов могут быть отменены в процессе выполнения с помощью действий пользователя или сигналов. |
| Независимое от платформы ядро | Один класс AIAgent обслуживает CLI, шлюз, ACP, пакетную обработку и сервер API. Различия платформ заключаются в точке входа, а не в агенте. |
| Слабая связь | Дополнительные подсистемы (MCP, плагины, поставщики памяти, среды RL) используют шаблоны реестра и шлюзование check_fn, а не жесткие зависимости. |
| Изоляция профиля | Каждый профиль (vibeos -p <name>`) получает свой собственный VIBEOS_HOME, конфигурацию, память, сеансы и шлюз PID. Несколько профилей работают одновременно. |
Цепочка зависимостей файлов
tools/registry.py (no deps — imported by all tool files)
↑
tools/*.py (each calls registry.register() at import time)
↑
model_tools.py (imports tools/registry + triggers tool discovery)
↑
run_agent.py, cli.py, batch_runner.py, environments/
Эта цепочка означает, что регистрация инструмента происходит во время импорта, до создания экземпляра агента. Любой файл tools/*.py с вызовом registry.register() верхнего уровня обнаруживается автоматически — список импорта вручную не требуется.