01. Архитектура — AstraCode — Техническая документация

AstraCode реализован как монорепо из Rust-крейтов в astracode-rs/ (см. Cargo.toml [workspace] members) и внутренней compatibility/staging-обёртки в astracode-cli/. Архитектура разделена на слои: CLI → TUI → app-server (JSON-RPC) → core (агентский цикл) → провайдеры моделей и инструменты.

1. Точка входа

Бинарник astracode — единый multitool. Источник: astracode-rs/cli/src/main.rs.

text

astracode                  → интерактивный TUI
astracode exec ...         → headless-режим (одна команда)
astracode app-server       → запуск только app-server (для удалённого подключения)
astracode mcp ...          → управление MCP-серверами
astracode plugin ...       → управление плагинами
astracode debug ...        → отладочные подкоманды
astracode review ...       → code review non-interactively
astracode mcp-server       → запуск AstraCode как MCP-сервера (stdio)
astracode completion ...   → генерация shell-completion
astracode update           → обновление до последней версии
astracode sandbox ...      → запуск команд в sandbox
astracode sessions         → picker сохранённых сессий (алиас: astracode resume)
astracode fork             → ответвить сессию
astracode license ...      → активация/статус лицензии
astracode features         → инспекция feature-флагов
astracode exec-server      → [экспериментальный] standalone exec-server

astracode-cli/bin/astracode.js — внутренний JS launcher, умеющий выбирать optional platform binary. Он сохраняется в исходном дереве для совместимости и staging-сценариев; текущая developer documentation не определяет его как канал установки или публикации.

2. Слои и крейты

Уровень UI

Крейт	Назначение
`tui`	TUI на ratatui + crossterm. ChatWidget, BottomPane, ChatComposer, оверлеи.
`cli`	Парсинг аргументов (clap), маршрутизация в подкоманды.

Коммуникация TUI ↔ ядро

Крейт	Назначение
`app-server`	Внутрипроцессный сервер, обработка JSON-RPC от TUI/CLI.
`app-server-protocol`	Версионированный протокол (v1, v2). Структуры запросов/ответов.
`app-server-client`	Типизированный клиент. Поддерживает in-process (mpsc) и remote (UDS/TCP).
`app-server-test-client`	Тестовая обёртка над клиентом.

Ядро (агентский цикл)

Крейт	Назначение
`core`	Управление сессией, ThreadManager, agent loop, обработка LLM-ответов. Содержит `agent/` — роли субагентов (`role.rs`, `registry.rs`, `builtins/*.toml`), resolver, mailbox, контроль жизненного цикла.
`core-plugins`	Система плагинов и их активация.
`core-skills`	Парсинг и загрузка скиллов (SKILL.md + frontmatter + yaml).

Субагенты и роли

Встроенные роли субагентов определены в core/src/agent/builtins/*.toml: explorer (read-only исследование кодовой базы), worker (bounded реализация), awaiter (ожидание завершения команды). Пользовательские роли создаются через /subagent и хранятся как standalone TOML-файлы. Назначения моделей для ролей выбираются через /submodel и сохраняются в [ui_state.role_models] (config/src/providers_toml.rs); для custom-ролей — в [ui_state].custom_agent_model. Маршрутизация провайдера субагента идёт через x-astracode-provider-id (core/src/client.rs) и разрешается bridge/responses-api-proxy.

Модели и провайдеры

Крейт	Назначение
`model-provider`	Трейт `ModelProvider`, абстракция над HTTP-API.
`model-provider-info`	Каталог провайдеров с метаданными моделей.
`models-manager`	Кэширование и обновление каталога моделей.
`api`	Базовая HTTP-инфраструктура.
`backend-openapi-models`	Сгенерированные типы из OpenAPI.
`bridge`	In-process обвязка chat-completions bridge: выбор provider target и loopback URL. Клиент AstraCode всегда говорит на Responses API; чтобы работать с бэкендами, понимающими только Chat Completions (vLLM, SGLang, llama.cpp, MiniMax, …), запросы маршрутизируются через этот мост.
`responses-api-proxy`	Трансляция Responses API ↔ Chat Completions, SSE и per-provider routing.

Хранение состояния

Крейт	Назначение
`state`	SQLite-БД для метаданных потоков, целей, UI-состояния.
`rollout`	Запись событий сессии в JSONL.
`rollout-trace`	Расширенный трейсинг событий.
`thread-store`	Файловое хранилище потоков и истории.
`memories`	Память (Phase 1/Phase 2).
`secrets`	Шифрование секретов (age + scrypt) и file/keyring storage мастер-ключа.
`keyring-store`	Обёртка над OS keyring.

Безопасность

Крейт	Назначение
`sandboxing`	Общая абстракция sandbox.
`linux-sandbox`	bwrap + seccomp + landlock.
`windows-sandbox-rs`	Windows-реализация.
`process-hardening`	Закалка процесса (NPR, PDeathSig).
`shell-escalation`	Протокол эскалации `exec()` через сокет.
`execpolicy`	Декларативная политика разрешённых команд.
`execpolicy-legacy`	Старая версия policy-engine.
`shell-command`	Парсинг и нормализация shell-команд.

MCP и инструменты

Крейт	Назначение
`mcp`	Менеджер MCP-серверов, регистрация инструментов.
`mcp-server`	AstraCode как MCP-сервер для внешних клиентов.
`rmcp-client`	Клиент для удалённых MCP.
`tools`	Реестр встроенных инструментов (спецификации + схема).
`slash-commands`	Единый registry slash-команд (метаданные, алиасы, availability, feature-gates). Не содержит обработчиков — TUI и app-server мапят `SlashCommandId` на свои хендлеры.
`file-search`	Полнотекстовый поиск по файлам.
`file-system`	Абстракция над FS с учётом sandbox.
`apply-patch`	Применение унифицированных патчей.
`git-utils`	Утилиты git (status, diff, blame).
`exec` / `exec-server`	Запуск команд через UDS-сервер.

Голос и реальное время

Крейт	Назначение
`realtime-webrtc`	WebRTC-клиент для realtime API.

Прочее

Крейт	Назначение
`config`	Загрузка `config.toml`, иерархия слоёв.
`hooks`	Lifecycle-события и обработчики.
`feedback`	Отправка фидбэка/логов.
`login`	Аутентификация (OAuth, API key).
`device-key`	Привязка устройства.
`analytics`	Телеметрия.
`otel`	OpenTelemetry экспорт.
`external-agent-migration` / `external-agent-sessions`	Совместимость с внешними агентами.
`network-proxy`	HTTP/SOCKS-прокси через config.
`terminal-detection`	Определение терминала и его capabilities.
`utils`, `async-utils`, `ansi-escape`	Общие утилиты.
`arg0`	Подмена argv[0] для разных режимов одного бинарника.
`stdio-to-uds`	Мост stdio↔UDS для MCP.
`code-mode`, `collaboration-mode-templates`	Шаблоны режимов совместной работы.
`connectors`, `plugin`	Коннекторы внешних сервисов.
`aws-auth`	AWS SigV4 для Bedrock.
`install-context`	Контекст установки (где находится бинарник).
`debug-client`	Клиент для подкоманды `debug`.
`experimental-api-macros`	Макросы для экспериментальных API.
`features`	Feature flags.
`response-debug-context`	Debug-контекст ответов LLM.
`state` / `models-manager` / `feedback`	(см. выше).
`v8-poc`	Эксперимент с V8-исполнением (PoC).

3. Поток управления

Запуск

text

astracode (без аргументов)
  → cli/src/main.rs
  → парсинг clap
  → astracode_tui::Cli::run_interactive_tui()  ([`cli/src/main.rs:2452`](https://gitlab.prosto.aib.pro/astracode/astracode/-/blob/65885722fe9f50ff9ebe364fa8c5bafe9a34a6d4/astracode-rs/cli/src/main.rs#L2452))
  → инициализация InProcessAppServerClient (mpsc-канал)
  → app-server поднимается в фоновой задаче tokio
  → загружаются config.toml, skills, MCP-серверы, hooks
  → TUI отправляет Initialize RPC → получает capabilities
  → ChatWidget готов к вводу

Один ход (turn)

text

Пользователь печатает в ChatComposer
  → Enter → ChatWidget собирает UserInput (текст, mentions, attachments)
  → AppServerClient::request() (JSON-RPC thread API: thread/start, thread/sendMessage)
  → app-server/message_processor.rs → AstraCodeThread
  → core/src/agent/mod.rs:
       1. строит prompt (история + skills + tools + system instructions)
       2. вызывает ModelClientSession::stream() (core/src/client.rs)
       3. провайдер отправляет HTTP-запрос (OpenAI/Anthropic/local)
       4. читает SSE-стрим, выдаёт ResponseEvent'ы
       5. для каждого tool_use → ExecServer / MCP / встроенный инструмент
       6. результаты возвращаются в модель → следующий шаг цикла
 → RolloutRecorder пишет события в JSONL (~/.astracode/sessions/...)
 → ServerNotifications (AgentMessageDelta, ItemStarted, ItemCompleted, task_started/task_complete) стримятся обратно в TUI через тот же канал по мере появления
  → TUI обновляет экран в реальном времени

Approval flow

text

Tool требует разрешения (по политике)
  → core отправляет ServerRequest (ExecApprovalRequest, ApplyPatchApprovalRequest, RequestPermissions) в TUI
  → ChatWidget показывает диалог approvals
  → пользователь жмёт Allow/Allow once/Deny
  → ответ возвращается в core
  → tool либо выполняется, либо отменяется

4. Связь TUI ↔ app-server

AppServerClient имеет две реализации:

In-process (по умолчанию): обе стороны живут в одном процессе, общение через tokio::sync::mpsc. Быстро, без сериализации.
Remote: app-server слушает UDS (Unix Domain Socket), TUI подключается. Позволяет переподключаться к фоновому app-server (например, при tmux detach).

Протокол — JSON-RPC 2.0 поверх app-server-protocol. Версионирование через namespaces (v1::, v2::).

5. Хранилище в `~/.astracode/`

См. подробно 15-storage.md. Краткая схема:

text

~/.astracode/
├── config.toml             # пользовательская конфигурация
├── installation_id         # стабильный ID инсталляции
├── state_5.sqlite          # threads, goals, UI state
├── logs_2.sqlite           # логи выполнения
├── history.jsonl           # общая история всех сессий
├── secrets/local.age       # зашифрованные секреты
├── memories/               # система памяти (фаза 1 → фаза 2)
├── sessions/YYYY/MM/DD/    # rollout-файлы по дате
├── skills/.system/         # встроенные скиллы
├── skills/<custom>/        # пользовательские скиллы
├── shell_snapshots/        # снимки окружения shell
├── projects/<sha256_cwd>/undo/<thread_id>.jsonl  # baseline'ы файловых изменений для `/undo`
└── log/                    # текстовые логи (astracode-tui.log)

6. Иерархия процессов в рантайме

text

astracode (родительский)
├── app-server (in-process task внутри того же процесса)
│   ├── core::agent (поток сессии)
│   ├── RolloutRecorder (фоновая задача)
│   └── ModelProvider (HTTP-клиент)
├── MCP-серверы (один процесс на сервер, stdio)
│   ├── mcp_server_1
│   └── mcp_server_2
├── ExecServer (UDS) — запускается по необходимости
└── bwrap/sandbox-exec — оборачивают каждую внешнюю команду

Сложная многопроцессность — это норма. ExecServer выполняет команды отдельно от core, чтобы изолировать sandbox.

7. Сборка

Стандартная сборка через Cargo:

bash

cd astracode-rs
cargo build --release --bin astracode

Альтернативно — через Bazel (MODULE.bazel в корне репозитория, BUILD.bazel в отдельных крейтах) для воспроизводимых билдов в CI. См. 17-development.md.

8. Чем AstraCode отличается от upstream codex

Локализация RU (полностью переведены TUI-сообщения, оверлеи, ошибки, описания скиллов).
Долгоиграющие задачи /goal с budget и продолжением через /resume.
Расширенная система скиллов (русские описания, неявная инвокация по script/doc).
Локализованный /help с pager-оверлеем.
Кастомные провайдеры моделей (включая on-prem).
Несколько новых slash-команд: /cd с popup-автодополнением, /sandbox-add-read-dir, /autoreview.

Подробнее об отличиях — CHANGELOG в корне репозитория.

1. Точка входа

2. Слои и крейты

Уровень UI

Коммуникация TUI ↔ ядро

Ядро (агентский цикл)

Субагенты и роли

Модели и провайдеры

Хранение состояния

Безопасность

MCP и инструменты

Голос и реальное время

Прочее

3. Поток управления

Запуск

Один ход (turn)

Approval flow

4. Связь TUI ↔ app-server

5. Хранилище в ~/.astracode/

6. Иерархия процессов в рантайме

7. Сборка

8. Чем AstraCode отличается от upstream codex

5. Хранилище в `~/.astracode/`