Kilo Code: обзор архитектуры Печать
Добавил(а) microsin   

Это перевод обзора на архитектуру платформы Kilo [1], который может помочь разработчикам понять, как различные компоненты этой системы взаимодействуют друг с другом.

[Архитектура системы]

Kilo это платформа искусственного интеллекта (AI) для программистов, построенная вокруг центральной подсистемы командного интерфейса (Kilo CLI engine), на основе которой работает каждый клиентский интерфейс — командная строка терминала, плагин VS Code и облачные сервисы. Архитектура следует традиционному подходу многоуровневых слоев, где все клиенты коммуницируют с CLI через HTTP + SSE, и CLI соединяется с провайдерами AI (моделью ИИ) либо напрямую, либо через Kilo Cloud.

kiloclaw architecture1

Рис. 1. Диаграмма архитектуры Kilo AI.

[Kilo CLI]

CLI (packages/opencode/) это ядро, на основе которого построены все продукты. Оно содержит среду выполнения ИИ-агента (AI agent runtime), запуск инструментария, управление сессией, интеграцию с провайдером выбранной модели, и HTTP-сервер. Каждый клиент порождает или подключается к процессу обслуживания (kilo serve) и коммуницирует с ним через HTTP + SSE с помощью @kilocode/sdk.

CLI может работать в нескольких режимах:

kilo — интерактивный TUI (Text User Interface, текстовый пользовательский интерфейс) для работы программиста в терминале.
kilo run — headless single-prompt execution (безголовое выполнение с одним запросом). Это режим работы, в котором программа не запускает полноценный интерфейс (TUI) и не ждёт постоянного взаимодействия с пользователем.
kilo serve — режим сервера HTTP для интеграции клиентов.

Ключевые подсистемы внутри CLI:

Подсистема Назначение
Agent Runtime Главная управляющая логика ИИ (Orchestrates AI): запуск инструментов, ведет диалог, принимает решения и контролирует последовательность действий, запускает пошаговые задачи для заданной обработки.
Tools Service Встроенные инструменты для редактирования файла, выполнения исполняемого кода в терминале (shell execution), поиска, и для других действий.
MCP Servers Model Context Protocol поддерживает систему расширения с помощью внешних инструментов (таких как GitHub, Linear, Jira, Postgres, Context7, Browserbase и других, см. Q007 [2]).
LSP Client Это компонент, который подключает Language Server Protocol (LSP) — стандартный протокол для передачи "интеллектуальных" функций редактирования кода от сервера (например, анализатора Python) клиенту (например, редактору или ИИ-агенту).
Session Manager Поддержка сохранения состояния сессии (persistent session state, истории диалогов (conversation history) и контрольных точек сохранения состояния сессии (checkpoints).
Provider Router Обеспечивает подключение к 500+ AI моделям через direct API (прямое подключение к провайдеру модели) или через Kilo Gateway.
HTTP Server REST API + SSE стриминг для коммуникации с клиентом.
Config System Управление конфигурацией проекта и глобальной конфигурацией, режимами, разрешениями.

[Client Layer]

Все клиенты — это всего лишь тонкие обертки над CLI (интерфейсом командной строки). Это означает:

● Вся "умная" логика (обработка ИИ, вызов инструментов, LSP, управление сессиями) находится в CLI-бинарном файле.

● Клиент (расширение VS Code, TUI в терминале) отвечает только за:

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

Преимущество такого подхода: любой новый клиент можно создать, просто реализовав обертку для вызова CLI-движка.

VS Code Extension. Слой клиента в виде плагина/расширения VScode (packages/kilo-vscode/) содержит в себе бинарник CLI, и порождает kilo serve как дочерний процесс. Плагин включает:

Sidebar Chat — основной интерфейс с пользователем. Текстовый диалог, в котором программист задает вопросы, и модель AI ему отвечает.
Agent Manager — панель для управления параллельными задачами с использованием git worktree изоляции. Это означает, что каждый агент работает в своей собственной копии репозитория, изолированной от других. Это позволяет безопасно запускать параллельные задачи (например, один агент рефакторит модуль А, другой исправляет баг в модуле Б), не мешая друг другу и не конфликтуя через общий рабочий каталог.

TUI, текстовый пользовательский интерфейс - еще один слой клиента. Это встроенный в сам CLI интерфейс, который работает прямо в терминале. Отличительная особенность: TUI построен с использованием SolidJS — библиотеки для создания веб-интерфейсов (как React, но быстрее). Рендерится в терминале через OpenTUI — библиотеку, которая позволяет отображать веб-компоненты (HTML/CSS/JS) в текстовой среде терминала.

[Kilo Cloud]

Сервис облачного слоя платформы, который расширяет возможности локального CLI, добавляя управление доступом, маршрутизацию к моделям и автономных агентов в облаке. Важный момент: инфраструктура облака живет в отдельном репозитории — то есть это отдельный продукт/компонент, не смешанный с кодом локального CLI.

Kilo Gateway. Шлюз (packages/kilo-gateway/ в этом репозитории, плюс маршруты API в облаке) обрабатывает следующие задачи:

Authentication — аутентификация (вход в систему через GitHub, Google, корпоративный SSO, см. Q007 [2]), управление API-ключами для доступа к Kilo Cloud из скриптов/CI. Обеспечивает контроль доступа на основе ролей (RBAC) — кто может использовать дорогие модели (GPT-4, Claude Opus), кто может создавать автономных агентов.
Provider Routing — маршрутизация провайдеров, умный шлюз, который направляет ваши запросы к нужной модели ИИ. Обслуживает запросы ИИ либо через управляемые Kilo ключи API, либо через собственные ключи пользователя.
Model Catalog — каталог моделей, компонент облачной платформы Kilo Cloud, который предоставляет актуальный список доступных моделей ИИ и их конфигурацию провайдеров (то есть, через какого поставщика и с какими параметрами к ним подключаться).
Usage & Billing — отслеживает потребление токенов и управляет кредитами (работу платной подписки на модель провайдера ИИ).

Cloud Agent. Это ключевой компонент Kilo Cloud, который выполняет AI-задачи по кодингу непосредственно в облаке, а не на локальной машине пользователя. Cloud Agent реализован как Cloudflare Worker — бессерверная функция, работающая на границе сети Cloudflare. Это обеспечивает глобальную доступность, автоматическое масштабирование и изоляцию. Обеспечивает запуск Kilo CLI в изолированных средах (sandbox) через web-дашборд, webhooks или автоматизированные рабочие процесса. Обеспечивает защищенное API для следующих задач:

● Создание и управление сессиями кодирования с полной интеграцией GitHub/GitLab.
● Запуск ИИ-задач (AI tasks) в Docker-контейнерах с предварительно установленной подсистемой Kilo CLI.
● Отправка результатов обратно через WebSocket.

Kilo Bot. это бот для GitHub/GitLab, который автоматически реагирует на комментарии в issues и упоминания в pull requests (PR). Он не выполняет работу сам, а отправляет задачи в Cloud Agent. Простыми словами: это интерфейс, который позволяет вам "общаться" с Kilo прямо в вашем репозитории, как с коллегой.

KiloClaw. Это отдельная многопользовательская (multi-tenant) платформа для выполнения вычислений, работающая поверх Fly.io (сервис глобального развертывания приложений) и управляемая через Cloudflare Worker (выполняет роль главного контролера: принимает запросы пользователя, создаёт или выбирает нужную машину на Fly.io, перенаправляет трафик, координирует работу через Durable Objects).

Durable Objects — это особая возможность Cloudflare Workers, позволяющая поддерживать согласованное состояние между запросами:

State management: хранит информацию о пользователе, т. е. какая машина ему выделена, какой у неё статус (запущена, остановлена, обновляется), какие задачи выполняются.
Self-healing reconciliation ("самовосстановление", или "самолечение"): Durable Object периодически проверяет состояние машины на Fly.io и, если она упала или зависла, автоматически пересоздаёт её или перезапускает. Это и есть "самолечение" — приведение желаемого состояния в соответствие с реальным.

kiloclaw architecture2

Рис. 2. Диаграмма архитектуры Kilo Cloud.

Code Review. Это автоматизированный сервис проверки кода, который интегрируется с GitHub через веб-hooks, анализирует pull requests (PR) с помощью Cloud Agent и публикует замечания/предложения прямо в PR. Сервис учитывает лимиты параллельности на организацию и автоматически ставит задачи в очередь. Поддерживает лимиты одновременной работы организации и автоматическую обработку очереди запросов.

Простыми словами: автоматический ревьюер кода в вашем GitHub-репозитории, который пишет комментарии к строкам кода, как живой разработчик.

Auto Triage. Это автоматический сервис для обработки GitHub issues, который классифицирует задачи (баг, фича, вопрос), находит дубликаты через поиск векторной похожести (semantic similarity) и опционально создаёт PR с исправлением для уверенных в своем действии проблем.

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

App Builder. Это сервис, который строит (build) и развертывает (deploy) пользовательские приложения через Cloud Agent. Пользователи могут генерировать полноценные приложения из промптов (текстовых описаний запросов), а App Builder координирует работу Cloud Agent для создания каркаса, итеративной доработки и развертывания результата.

Gas Town. Это платформа для мульти-агентного управления, которая координирует работу автономных AI-агентов по кодингу над реальными Git-репозиториями. Gas Town работает полностью на Cloudflare (центральный Durable Object управляет всем состоянием, а Docker-контейнеры на Cloudflare Containers запускают процессы агентов через Kilo CLI).

Простыми словами: "фабрика AI-разработчиков", где множество агентов параллельно работают над разными задачами в разных репозиториях, полностью автоматически и без участия человека.

Ключевые концепции:

Town — workspace/project, который содержит один или несколько rig-ов (репозиториев).
Rig — Git-репозиторий, подключенный к town, где агенты выполняют свою работу.
Bead — рабочая единица (issue, task, merge request или message).
Convoy — группа связанных bead-ов с отслеживанием зависимостей, управляемых как единое целое.

Агенты работают в следующей иерархии:

Агент Роль
Mayor Постоянный координатор, который управляет всем процессом — декомпозирует задачи и делегирует их рабочим агентам.
Polecat Рабочий агент — клонирует дерево репозитория, пишет код, выполняет фиксации (commits), выкладывает фиксацию (pushes) и создает PR-ы.
Refinery Агент рецензирования кода — проверяет ветки, созданные polecat, запускает контрольные точки проверки качества (quality gates), выполняет слияния (merges) или выставляет запрос на доработки (requests rework).
Triage Это временный (эпизодически запускаемый) агент, который активируется только тогда, когда автоматические патрульные проверки обнаруживают неоднозначную или непонятную ситуацию.

Reconciler Loop (цикл приведения к желаемому состоянию) запускается каждые 5 секунд и управляет всеми переходами состояния в системе. Этот цикл постоянно сравнивает:

Желаемое состояние (desired state) — какие задачи должны быть выполнены, какие конвои активны, какие агенты свободны.
Фактическое состояние (actual state) — что на самом деле происходит: какие агенты работают, какие PR открыты, какие биды завершены.

Если есть расхождение → Reconciler принимает действия, чтобы привести систему к желаемому состоянию.

[Ключевые концепции]

Modes (режимы). Это конфигурируемые пресеты, с помощью которых настраивается поведение агентов:

● Определение, какие инструменты доступны.
● Установка пользовательских системных приглашений диалога (system prompts).
● Конфигурирование ограничений на доступ к файлам.
● Примеры: Code, Architect, Debug, Ask.

Model Context Protocol (MCP). MCP позволяет расширить функционал агента с помощью внешних инструментов:

● Серверы (например GitHub, Linear, Jira, Postgres, Context7, Browserbase) предоставляют дополнительные функциональные возможности.
● Стандартизированный протокол для взаимодействия с инструментами.
● Конфигурирование через mcp.json.

Checkpoints. Система управления состоянием на основе Git, которая позволяет безопасно экспериментировать (safe exploration). Она создаёт фиксации (commits) для отслеживания изменений, позволяет откатываться к предыдущим состояниям и использует теневой репозиторий для изоляции. Выполняет следующие функции:

● Создает фиксации (commits) для отслеживания изменений.
● Позволяет выполнить откат к предыдущим состояниям.
● Создает для этих действий временный теневой репозиторий (shadow repository) для обеспечения изоляции.

Простыми словами: "машина времени для кода", встроенная в Kilo/Gas Town, которая позволяет агентам пробовать разные решения, не боясь сломать основную ветку.

Worktrees. Git-изоляция рабочих деревьев (worktrees) для параллельного выполнения задач:

● Каждая сессия агента может работать в своем собственном worktree.
● Предотвращаются конфликты между одновременно работающими задачами.
● Используется Agent Manager в VS Code для множественной обработки сессий (multi-session workflows).

[Шаблоны разработки]

Коммуникация клиент - сервер. Все клиенты общаются с CLI через его HTTP + SSE API. Пакет @kilocode/sdk предоставляет клиента TypeScript:

import { KiloClient } from "@kilocode/sdk"

const client = new KiloClient({ baseUrl: "http://localhost:3000" })
const session = await client.session.create({ ... })

Module Export Pattern. Организация экспортов построена вокруг плоских ESM-экспортов внутри каждого модуля с последующим повторным экспортом через пространства имён (namespace) из индексного файла для группового доступа. Ключевое правило: не добавлять новых деклараций export namespace, так как экспорт на верхнем уровне проще для tree-shaking и лучше работает с Node runtime для удаления типов (type-stripping runtime).

// packages/opencode/src/session/session.ts
export const create = fn(CreateSchema, async (input) => {
  // ...
})

export const list = fn(ListSchema, async (input) => {
  // ...
})

// packages/opencode/src/session/index.ts
export * as Session from "./session"

Импортируйте конкретный экспорт, когда это возможно, и используйте namespace re-export (Session.create, Session.list) только когда вызывающему коду нужен групповой доступ к модулю или когда необходимо сохранить существующую публичную форму API.

CLI Server API. API сервера построен на базе Hono (лёгкий веб-фреймворк для JavaScript/TypeScript) и публикует OpenAPI-совместимый HTTP + SSE API, который используется пакетом @kilocode/sdk. Некоторые группы маршрутов мигрируются за экспериментальный Effect HttpApi мост с сохранением формы SDK. Клиенты не должны зависеть от деталей миграции.

● Обеспечивается стабильный вывод SDK, когда маршруты перемещаются между Hono и Effect HttpApi.
● Флаг KILO_EXPERIMENTAL_HTTPAPI используется только для тестирования миграции; публичные клиенты не должны зависеть от деталей реализации моста.
● Регенерация packages/sdk/js/ после изменения конечной точки сервера.
● Удержание обработки запросов в состоянии возможности наблюдения. Каждый запрос должен создавать trace span с стабильными атрибутами для наблюдаемости (мониторинг, отладка, аналитика).

Реализация инструмента. Шаблон реализации инструмента следуют единообразному паттерну с валидацией схем через Zod:

export const ReadTool = Tool.define({
  name: "read",
  description: "Read a file",
  parameters: z.object({
    path: z.string(),
  }),  async execute(params) {
    // ...
  },
})

[Build System]

Проект использует следующую систему сборки (Build System). Это набор инструментов, используемых для управления моно-репозиторием, сборки артефактов и тестирования:

Bun — пакетный менеджер (monorepo workspaces) и среда для запуска утилит (runtime).
Turborepo — Monorepo task orchestration, организует задачи между пакетами с кэшированием и параллельным выполнением.
esbuild — связывает CLI и расширение VS Code.
TypeScript — проверка типов через tsgo по всем пакетам.
Vitest / Bun test — система запуска тестов.

[Репозитории]

Репозиторий Что содержит
Kilo-Org/kilocode CLI engine, плагин VS Code (extension), SDK, gateway client, телеметрия, документация, компоненты интерфейса пользователя (UI)
Cloud (private) Web dashboard, Cloud Agent, Kilo Bot, KiloClaw, Gas Town, code review, auto triage, billing и поддержка Cloudflare Workers

См. также:

Настройка окружения разработки [3].
Подробное описание возможностей архитектуры [4].
Экосистема — связанные с Kilo проекты и интеграции [5].

[Ссылки]

1. Kilo Code Architecture Overview.
2. kilo.ai: что это такое, как пользоваться.
3. Kilo Development Environment.
4. Kilo Architecture Features.

5. Building for the Kilo Ecosystem https://kilo.ai/docs/contributing/ecosystem