CodeLab

Введение в CodeLab

CodeLab — AI-ассистент для разработчиков, который работает с вашим кодом: читает файлы, выполняет команды, создаёт и редактирует код — из терминала или IDE. …

Введение в CodeLab

AI-ассистент для разработчиков с открытой архитектурой и полным контролем над действиями агента.

Что такое CodeLab?

CodeLab — AI-ассистент для разработчиков, который работает с вашим кодом: читает файлы, выполняет команды, создаёт и редактирует код — из терминала или IDE. Все действия проходят через систему разрешений — вы контролируете каждое изменение агента.

CodeLab построен на базе [Agent Client Protocol (ACP)](https://github.com/pese-git/codelab-agent/blob/main/doc/protocols/Agent Client Protocol/get-started/01-Introduction.md) — открытого стандарта взаимодействия между AI-агентами и клиентами.

CodeLab объединяет в себе:

  • ACP-сервер — интеллектуальный агент с поддержкой 8+ LLM провайдеров (OpenAI, Anthropic, OpenRouter, Zen, Go, Ollama, LMStudio, Mock)
  • TUI-клиент — терминальный интерфейс пользователя на базе Textual (Clean Architecture + MVVM)
  • Web UI — браузерный интерфейс для работы через веб (textual-web)
  • stdio транспорт — основной транспорт ACP для интеграции с IDE (stdin/stdout JSON-RPC)

Для чего используется?

CodeLab позволяет:

  1. Автоматизировать разработку — AI-агент выполняет задачи по кодированию, рефакторингу, тестированию
  2. Работать с файловой системой — создание, редактирование, удаление файлов под контролем пользователя
  3. Выполнять команды терминала — запуск скриптов, сборка проектов, деплой
  4. Планировать задачи — агент формирует план действий и согласовывает его с пользователем
  5. Интегрироваться с MCP — подключение внешних инструментов через Model Context Protocol
  6. Интегрироваться с IDE — работа через stdio транспорт в Zed IDE и других редакторах

Ключевые возможности

🤖 Интеллектуальный агент

  • Поддержка 8+ LLM провайдеров: OpenAI, Anthropic, OpenRouter, Zen, Go, Ollama, LMStudio, Mock
  • Переключение модели mid-session через session/set_config_option
  • Fallback цепочки при ошибках провайдера (Sequential с Circuit Breaker)
  • Автоматическое планирование задач (plan-first mode)
  • Контекстное понимание кодовой базы
  • Цикл LLM с tool calls (до 10 итераций)
  • Отмена промптов без блокировки (lock-free cancel)

🛡️ Система разрешений

  • Гранулярный контроль над действиями агента
  • Подтверждение опасных операций
  • Глобальные и сессионные политики (GlobalPolicyManager)
  • Inline виджеты разрешений в чате

📁 Работа с файлами

  • Просмотр и редактирование файлов
  • Создание новых файлов и директорий
  • Интеллектуальное применение изменений (дифф)
  • Песочница (sandbox) для защиты от path traversal

💻 Терминал

  • Выполнение shell-команд
  • Потоковый вывод результатов
  • Фоновые процессы
  • Корректный terminal output flow по ACP spec

🔌 MCP интеграция

  • Подключение MCP-серверов
  • Расширение возможностей агента
  • Пользовательские инструменты
  • Управление несколькими MCP-серверами на сессию

🏗️ Архитектура

  • Dishka DI контейнер — управление зависимостями (APP scope / REQUEST scope)
  • Pipeline система — 7 стадий обработки промпта
  • Slash команды — /help, /mode, /status
  • Clean Architecture — 5 слоёв на клиенте
  • MVVM паттерн — 9 ViewModels для реактивного UI

Архитектура

CodeLab следует клиент-серверной архитектуре ACP с поддержкой нескольких транспортов:

graph TB
    subgraph Client["Клиент (Clean Architecture + MVVM)"]
        TUI["TUI Components<br/>45 widgets"]
        VM[9 ViewModels]
        UC[Use Cases]
        TS["Transport Service<br/>WebSocket / stdio"]
    end
    
    subgraph Transport["Транспорт"]
        WS["WebSocket<br/>JSON-RPC 2.0"]
        STDIO["stdio<br/>stdin/stdout"]
    end
    
    subgraph Server["Сервер (Dishka DI)"]
        AP[ACPProtocol]
        PO[PromptOrchestrator]
        EE[ExecutionEngine]
        TR[ToolRegistry]
        MCP[MCP Manager]
    end
    
    subgraph External["Внешние системы"]
        LLM["LLM Provider<br/>OpenAI/Anthropic/Mock"]
        FS[File System]
        TERM[Terminal]
    end
    
    TUI --> VM --> UC --> TS
    TS --> WS & STDIO
    WS & STDIO --> AP --> PO --> EE --> LLM
    PO --> TR --> FS & TERM
    PO --> MCP

Режимы работы:

РежимКомандаТранспортОписание
Локальныйcodelabstdio (subprocess)Сервер + TUI в одном процессе
WebSocket серверcodelab serveWebSocketУдалённые клиенты
stdio серверcodelab serve --stdiostdioДля IDE плагинов
WebSocket клиентcodelab connectWebSocketПодключение к серверу
stdio клиентcodelab connect --stdiostdio (subprocess)Запуск агента как subprocess

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

# Клонирование репозитория
git clone https://github.com/pese-git/codelab-agent.git
cd codelab-agent/codelab

# Установка зависимостей
uv sync

# Локальный режим (сервер + TUI)
uv run codelab

# Или сервер + клиент отдельно
uv run codelab serve --port 8765        # WebSocket сервер
uv run codelab connect --port 8765      # TUI клиент

# stdio транспорт (для IDE плагинов)
uv run codelab serve --stdio            # сервер в stdio режиме

Следующие шаги