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

AstraCode реализован как монорепо из ~97 Rust-крейтов в astracode-rs/, плюс npm-пакет-обёртка в astracode-cli/. Архитектура разделена на слои: CLI → TUI → app-server (JSON-RPC) → core (агентский цикл) → провайдеры моделей и инструменты.

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

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

text

astracode                  → интерактивный TUI
astracode exec ...         → режим без графического интерфейса (одна команда)
astracode app-server       → запуск только app-server (для удалённого подключения)
astracode mcp ...          → управление MCP-серверами
astracode plugin ...       → управление плагинами
astracode debug ...        → отладочные подкоманды

npm-обёртка astracode-cli — это тонкое средство запуска, выбирающее правильный бинарник под платформу (Linux x86_64-gnu, macOS arm64, macOS x86_64, Windows).

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-ответов.
`core-plugins`	Система плагинов и их активация.
`core-skills`	Парсинг и загрузка скиллов (SKILL.md + frontmatter + yaml).

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

Крейт	Назначение
`model-provider`	Трейт `ModelProvider`, абстракция над HTTP-API.
`model-provider-info`	Каталог провайдеров с метаданными моделей.
`models-manager`	Кэширование и обновление каталога моделей.
`api`	Базовая HTTP-инфраструктура.
`backend-openapi-models`	Сгенерированные типы из OpenAPI.
`responses-api-proxy`	Прокси к Responses API.

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

Крейт	Назначение
`state`	SQLite-БД для метаданных потоков, целей, UI-состояния.
`rollout`	Запись событий сессии в JSONL.
`rollout-trace`	Расширенный трейсинг событий.
`thread-store`	Файловое хранилище потоков и истории.
`memories`	Память (Phase 1/Phase 2).
`secrets`	Шифрование секретов (age + scrypt + keyring).
`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`	Реестр встроенных инструментов.
`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`	События жизненного цикла и обработчики.
`feedback`	Отправка фидбэка/логов.
`login`	Аутентификация (OAuth, API key).
`device-key`	Привязка устройства.
`analytics`	Телеметрия.
`otel`	OpenTelemetry экспорт.
`external-agent-migration` / `external-agent-sessions`	Совместимость с внешними агентами.
`network-proxy`	HTTP/SOCKS-прокси через config.
`terminal-detection`	Определение терминала и его возможностей.
`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()
  → инициализация InProcessAppServerClient (mpsc-канал)
  → app-server поднимается в фоновой задаче tokio
  → загружаются config.toml, skills, MCP-серверы, hooks
  → TUI отправляет Initialize RPC → получает capabilities
  → ChatWidget готов к вводу

Один ход (turn)

text

Пользователь печатает в ChatComposer
  → Enter → ChatWidget собирает UserInput (текст, mentions, attachments)
  → AppServerClient::send_message() (JSON-RPC SendMessage)
  → app-server/message_processor.rs → AstraCodeThread
  → core/agent.rs:
       1. строит prompt (история + skills + tools + system instructions)
       2. вызывает ModelProvider::stream_completion()
       3. провайдер отправляет HTTP-запрос (OpenAI/Anthropic/local)
       4. читает SSE-стрим, выдаёт ResponseEvent'ы
       5. для каждого tool_use → ExecServer / MCP / встроенный инструмент
       6. результаты возвращаются в модель → следующий шаг цикла
  → RolloutRecorder пишет события в JSONL (~/.astracode/sessions/...)
  → ServerNotifications (TextDelta, ToolUseStart, ApprovalRequest)
       стримятся обратно в TUI через тот же канал
  → TUI обновляет экран в реальном времени

Процесс подтверждения

text

Tool требует разрешения (по политике)
  → core отправляет ApprovalRequest в 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           # история пользовательских вводов (поля: session_id, ts, text)
├── secrets/local.age       # зашифрованные секреты
├── memories/               # система памяти (фаза 1 → фаза 2)
├── sessions/YYYY/MM/DD/    # rollout-файлы по дате
├── skills/.system/         # встроенные скиллы
├── skills/<custom>/        # пользовательские скиллы
├── shell_snapshots/        # снимки окружения shell
└── log/                    # текстовые логи (astracode-tui.log)

history.jsonl хранит только пользовательские вводы (по одной JSON-записи на строку с полями session_id, ts, text). Список тредов для /resume строится не из этого файла, а из rollout/state-хранилища (sessions/ и state_5.sqlite).

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)

Процесс подтверждения

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

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

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

7. Сборка

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

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