Продвинутый

Ultraworkers/claw-code: Автономный музейный экспонат на Rust

Алексей Кузнецов
Алексей Кузнецов
Системный администратор3 ноября 2026 г.13 мин чтения

Статья рассказывает про claw-code — музейный экспонат, управляемый AI-агентами, написанный на Rust с использованием Gajae-Code и LazyCodex.

Ultraworkers/claw-code: Автономный музейный экспонат на Rust

Статья рассказывает про claw-code — музейный экспонат, управляемый AI-агентами, написанный на Rust с использованием Gajae-Code и LazyCodex.

Введение

Что такое claw-code

claw-code — это автономный музейный экспонат, который демонстрирует принципы работы AI-агентов в реальных условиях. Проект был создан не как демонстрация Rust-а, а как практический эксперимент по созданию системы, способной взаимодействовать с физическим миром без постоянного участия человека.

rust
// Пример основного цикла агента в claw-code
use gajae_code::{Agent, Environment};

#[tokio::main]
async fn main() {
    let mut env = Environment::new("museum_hall")
        .await
        .expect("Failed to initialize environment");
    
    let mut guide = Agent::new("claw-code")
        .with_memory(1024 * 1024) // 1MB памяти для состояния
        .with_tools(vec![
            Tool::new("vision", |img| analyze_artifact(img)),
            Tool::new("speech", |text| respond_naturally(text)),
            Tool::new("movement", |cmd| execute_physical_action(cmd)),
        ]);
    
    loop {
        let context = env.get_current_state().await;
        let decision = guide.think(&context).await;
        let result = guide.act(&decision).await;
        env.update(&result).await;
        
        // Небольшая пауза для предотвращения перегрева процессора
        tokio::time::sleep(Duration::from_millis(100)).await;
    }
}

В основе claw-code лежит концепция «умного экспоната», который может:

  • Распознавать посетителей через компьютерное зрение и определять их уровень знаний
  • Адаптировать рассказ в зависимости от интересов собеседника (сравнивая это с тем, как Docker Compose адаптирует конфигурацию под разные окружения)
  • Взаимодействовать с физическими объектами через контроллеры, подобно тому, как Proxmox управляет виртуальными машинами

Проект использует два ключевых компонента:

  • Gajae-Code — это фреймворк для создания AI-агентов, который обеспечивает предсказуемость поведения и стабильность состояния, как systemd обеспечивает предсказуемость сервисов
  • LazyCodex — библиотека для работы с кэшированием и асинхронными операциями, которая позволяет экспонату быстро реагировать на изменения в окружении
rust
// Конфигурация агента в claw-code
#[derive(Debug, Clone)]
struct AgentConfig {
    name: String,
    model_path: String,
    temperature: f32,        // Контроль предсказуемости ответов
    max_context_length: usize,
    tools: Vec<String>,
}

let config = AgentConfig {
    name: "museum_guide".to_string(),
    model_path: "/models/gajae-code-v2".to_string(),
    temperature: 0.3, // Низкая температура для более предсказуемых ответов
    max_context_length: 2048,
    tools: vec!["vision".to_string(), "speech".to_string()],
};

Цели проекта

Основная цель claw-code — доказать, что AI-агенты могут работать в реальных, непредсказуемых условиях, а не только в контролируемых лабораторных средах. Это не «еще один чат-бот», а практический инструмент для музеев, который:

  • Автоматизирует базовые диалоги — вместо того, чтобы музейные работники отвечали на одни и те же вопросы каждый день, claw-code может обрабатывать до 80% типичных запросов посетителей
  • Обеспечивает персонализацию — экспонат анализирует предыдущий опыт посетителя и адаптирует рассказ, подобно тому, как Nextcloud адаптирует синхронизацию файлов под разные устройства
  • Собирает аналитику — система анонимно собирает данные о том, что интересует посетителей больше всего, что помогает музеям планировать выставки
rust
// Пример сбора аналитики в claw-code
struct Analytics {
    total_visitors: u64,
    questions_by_topic: HashMap<String, u64>,
    satisfaction_scores: Vec<f32>,
}

impl Analytics {
    fn new() -> Self {
        Self {
            total_visitors: 0,
            questions_by_topic: HashMap::new(),
            satisfaction_scores: Vec::new(),
        }
    }
    
    fn record_interaction(&mut self, topic: &str, score: f32) {
        self.total_visitors += 1;
        *self.questions_by_topic.entry(topic.to_string()).or_insert(0) += 1;
        self.satisfaction_scores.push(score);
    }
}

Технические цели проекта включали:

  1. Низкое время отклика — каждый ответ агента должен генерироваться за менее чем 200 мс, чтобы взаимодействие казалось естественным, как при быстром ответе системы логирования journald
  2. Работа офлайн — экспонат должен функционировать без постоянного подключения к интернету, используя локально загруженные модели, подобно тому, как TrueNAS работает автономно при сбоях сети
  3. Безопасность и предсказуемость — система должна обрабатывать запросы без рисков для безопасности, обеспечивая предсказуемость поведения, как это делает systemd с сервисами
rust
// Пример безопасного выполнения действий агентом
async fn safe_execute(tool: &str, payload: &str) -> Result<String, SafetyError> {
    // Проверка на malicious payload
    if contains_suspicious_content(payload) {
        return Err(SafetyError::MaliciousInput);
    }
    
    // Ограничение ресурсов для предотвращения DoS
    let mut guard = ResourceGuard::new()
        .with_cpu_time(Duration::from_millis(500))
        .with_memory(50 * 1024 * 1024); // 50MB
    
    let result = match tool {
        "vision" => vision_tool.execute(payload).await,
        "speech" => speech_tool.execute(payload).await,
        _ => return Err(SafetyError::UnknownTool),
    };
    
    guard.release(); // Освобождаем ресурсы
    Ok(result)
}

Эти цели сделали claw-code не просто техническим экспериментом, а полезным инструментом, который может изменить подход к интерактивным музейным экспонатам, обеспечивая при этом стабильность и безопасность, которые необходимы в публичных пространствах.

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

Ultraworkers/claw-code: Автономный музейный экспонат на Rust

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

AI-агенты

Система claw-code использует множество специализированных AI-агентов, каждый из которых отвечает за определённый аспект поведения экспоната. Вместо монолитного ИИ проект разделяет ответственность по принципу предсказуемости — каждый агент знает только свою зону ответственности.

Основные типы агентов:

rust
// src/agents/mod.rs
pub mod curator;
pub mod historian;
pub mod interactive;
pub mod visualizer;

Кураторский агент отвечает за контентную стратегию и выбор экспонатов:

rust
struct CuratorAgent {
    knowledge_base: KnowledgeBase,
    interaction_rules: Vec<InteractionRule>,
}

impl CuratorAgent {
    fn select_exhibit(&self, visitor_profile: VisitorProfile) -> Option<Exhibit> {
        self.knowledge_base
            .find_best_match(visitor_profile.interests.clone())
            .filter(|exhibit| self.validate_interaction_rules(exhibit, visitor_profile))
    }
}

Исторический агент обеспечивает глубину контента:

rust
struct HistorianAgent {
    archives: Vec<ArchiveEntry>,
    timeline_engine: TimelineEngine,
}

impl HistorianAgent {
    fn generate_context(&self, exhibit_id: ExhibitId) -> HistoricalContext {
        let related_archives = self.archives
            .iter()
            .filter(|entry| entry.exhibit_id == exhibit_id)
            .collect();
        
        self.timeline_engine
            .build_narrative(related_archives)
    }
}

Интерактивный агент управляет диалогом с посетителями:

rust
struct InteractiveAgent {
    dialogue_patterns: DialoguePatterns,
    nlp_processor: NLPProcessor,
}

impl InteractiveAgent {
    fn respond(&self, visitor_input: String) -> AgentResponse {
        let entities = self.nlp_processor.extract_entities(&visitor_input);
        let pattern = self.dialogue_patterns.find_best_match(entities);
        
        pattern.generate_response(visitor_input)
    }
}

Каждый агент работает в своём потоке, используя каналы для обмена данными. Это обеспечивает предсказуемость системы — сбой одного агента не влияет на работу остальных.

Архитектура экспоната

Архитектура claw-code построена на принципах модульности и асинхронности. Проект использует Rust для обеспечения безопасности типов и производительности, а также для предотвращения целого класса ошибок во время выполнения.

Основная структура проекта:

rust
// src/lib.rs
use gajae_code::{EventSystem, MessageBus};
use lazycodex::{AsyncProcessor, StateMachine};

#[derive(Debug)]
pub struct ClawCodeExhibit {
    id: ExhibitId,
    agents: AgentRegistry,
    event_system: EventSystem,
    state_machine: StateMachine<ExhibitState>,
    renderer: ExhibitRenderer,
}

impl ClawCodeExhibit {
    pub async fn new(config: ExhibitConfig) -> Result<Self, ExhibitError> {
        let agents = Self::initialize_agents(&config).await?;
        let event_system = EventSystem::new();
        let state_machine = StateMachine::new(ExhibitState::Initialized);
        let renderer = ExhibitRenderer::new(config.display_config);
        
        Ok(Self {
            id: config.id,
            agents,
            event_system,
            state_machine,
            renderer,
        })
    }
    
    pub async fn start(&mut self) {
        self.state_machine.transition(ExhibitState::Running).unwrap();
        
        // Запускаем все агенты
        for agent in self.agents.iter_mut() {
            agent.start().await;
        }
        
        // Основной цикл обработки событий
        self.event_system.start_processing().await;
    }
}

Конфигурация агентов хранится в TOML-файле для предсказуемости:

toml
# config/agents.toml
[agents.curator]
model = "gpt-4o-mini"
max_tokens = 1024
temperature = 0.3
context_window = 8192

[agents.historian]
model = "claude-3-opus"
max_tokens = 2048
temperature = 0.1
cache_enabled = true

[agents.interactive]
model = "llama-3-70b"
max_tokens = 512
temperature = 0.5
response_timeout = 5000

[agents.visualizer]
model = "gemini-pro-vision"
max_tokens = 1024
temperature = 0.2

Система событий обеспечивает предсказуемость взаимодействия между агентами:

rust
// src/event_system.rs
pub struct EventSystem {
    channels: HashMap<EventType, mpsc::UnboundedSender<Event>>,
    subscribers: HashMap<EventType, Vec<AgentId>>,
}

impl EventSystem {
    pub fn new() -> Self {
        let mut channels: HashMap<EventType, mpsc::UnboundedSender<Event>> = HashMap::new();
        let mut subscribers: HashMap<EventType, Vec<AgentId>> = HashMap::new();
        
        for event_type in &[
            EventType::VisitorInteraction,
            EventType::ExhibitUpdate,
            EventType::SystemNotification,
        ] {
            let (tx, rx) = mpsc::unbounded_channel();
            channels.insert(*event_type, tx);
            subscribers.insert(*event_type, Vec::new());
        }
        
        Self {
            channels,
            subscribers,
        }
    }
    
    pub fn subscribe(&mut self, event_type: EventType, agent_id: AgentId) {
        if let Some(subs) = self.subscribers.get_mut(&event_type) {
            subs.push(agent_id);
        }
    }
    
    pub fn emit(&self, event: Event) {
        if let Some(channel) = self.channels.get(&event.event_type) {
            let _ = channel.send(event);
        }
    }
}

Система состояний обеспечивает предсказуемость поведения экспоната:

rust
// src/state_machine.rs
pub enum ExhibitState {
    Initialized,
    Running,
    Paused,
    Maintenance,
    Error,
}

pub struct StateMachine<T> {
    current_state: T,
    transitions: HashMap<T, Vec<StateTransition>>,
}

impl<T> StateMachine<T> {
    pub fn new(initial: T) -> Self {
        Self {
            current_state: initial,
            transitions: HashMap::new(),
        }
    }
    
    pub fn transition(&mut self, new_state: T) -> Result<(), StateError> {
        // Проверяем, разрешён ли переход
        if self.is_valid_transition(&self.current_state, &new_state) {
            self.current_state = new_state;
            Ok(())
        } else {
            Err(StateError::InvalidTransition)
        }
    }
    
    pub fn current(&self) -> &T {
        &self.current_state
    }
}

Рендеринг обеспечивает визуальную составляющую экспоната:

rust
// src/renderer.rs
pub struct ExhibitRenderer {
    output_config: OutputConfig,
    cache: RenderCache,
}

impl ExhibitRenderer {
    pub fn render(&mut self, exhibit: &ExhibitData) -> Result<RenderedOutput, RenderError> {
        // Проверяем кэш для предсказуемости
        if let Some(cached) = self.cache.get(&exhibit.id) {
            return Ok(cached.clone());
        }
        
        let output = match self.output_config.format {
            OutputFormat::Html => self.render_html(exhibit)?,
            OutputFormat::AsciiArt => self.render_ascii(exhibit)?,
            OutputFormat::InteractiveWeb => self.render_interactive(exhibit)?,
        };
        
        self.cache.insert(exhibit.id, output.clone());
        Ok(output)
    }
}

Интеграция с Rust-библиотеками обеспечивает высокую производительность:

rust
// src/integrations.rs
pub struct RustIntegrations {
    zfs_handler: ZfsHandler,
    prometheus_exporter: PrometheusExporter,
    monitoring: MonitoringSystem,
}

impl RustIntegrations {
    pub fn new() -> Self {
        Self {
            zfs_handler: ZfsHandler::new(),
            prometheus_exporter: PrometheusExporter::new(),
            monitoring: MonitoringSystem::new(),
        }
    }
    
    pub async fn collect_metrics(&self) -> SystemMetrics {
        let zfs_stats = self.zfs_handler.get_pool_stats().await;
        let prometheus_metrics = self.prometheus_exporter.get_metrics().await;
        let monitoring_data = self.monitoring.get_system_data().await;
        
        SystemMetrics {
            zfs: zfs_stats,
            prometheus: prometheus_metrics,
            monitoring: monitoring_data,
        }
    }
}

Архитектура claw-code демонстрирует, как Rust может обеспечить предсказуемость и производительность в сложных системах с множеством взаимодействующих компонентов. Каждый элемент проекта — от агентов до системы состояний — построен с учётом надёжности и ясности поведения.

Ultraworkers Repository — исходный код проекта на GitHub, где можно ознакомиться с полной документацией и примером конфигурации.

Техническая реализация

Техническая реализация

Проект claw-code — это пример того, как Rust может быть использован для создания автономных систем с высокой производительностью. Алексей Кузнецов выбрал этот язык не случайно: предсказуемость работы компилятора, отсутствие GC и возможность работы на низком уровне оказались идеальны для музейного экспоната, который должен работать 24/7 без сбоев.

Основная философия проекта — «делать правильно с первого раза». Если в других проектах можно было бы использовать Python для быстрой прототипизации, здесь был сделан упор на надежность. Результат — Rust-приложение, которое работает в режиме реального времени, обрабатывает данные посетителей и управляет AI-агентами без единой ошибки за месяцы непрерывной работы.

Стек на Rust

Ядро проекта написано на Rust 2021 edition с использованием современных конструкторов. В качестве асинхронной runtime используется Tokio — это обеспечивает высокую пропускную способность и эффективную обработку множества одновременных подключений от посетителей.

rust
// Cargo.toml
[package]
name = "claw-code"
version = "0.1.0"
edition = "2021"

[dependencies]
tokio = { version = "1.0", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
anyhow = "1.0"
tracing = "0.1"
tracing-subscriber = "0.3"

Основная архитектура основана на actor-модели с использованием Tokio Tasks. Каждый AI-агент работает в отдельной задаче, что обеспечивает изоляцию и предсказуемость поведения.

rust
// src/agents.rs
use tokio::task::JoinHandle;

pub struct Agent {
    id: String,
    task: JoinHandle<()>,
}

impl Agent {
    pub fn new(id: String, handler: impl std::future::Future<Output = ()> + Send + 'static) -> Self {
        let task = tokio::spawn(handler);
        Self { id, task }
    }

    pub async fn stop(self) -> Result<(), tokio::task::JoinError> {
        self.task.abort();
        self.task.await
    }
}

Для работы с устройствами ввода-выводa (сенсорами в музее, дисплеями для посетителей) используется библиотека async-trait, что позволяет писать чистый асинхронный код без callback-адской паттерны.

rust
// src/hardware.rs
use async_trait::async_trait;

#[async_trait]
pub trait Display: Send + Sync {
    async fn show(&self, text: &str) -> anyhow::Result<()>;
    async fn clear(&self) -> anyhow::Result<()>;
}

pub struct LedMatrix {
    // конфигурация пинов
}

#[async_trait]
impl Display for LedMatrix {
    async fn show(&self, text: &str) -> anyhow::Result<()> {
        // реализация вывода текста на матрицу
        Ok(())
    }

    async fn clear(&self) -> anyhow::Result<()> {
        // очистка матрицы
        Ok(())
    }
}

Интеграция с Gajae-Code/LazyCodex

Интеграция с AI-системами Gajae-Code и LazyCodex осуществляется через gRPC-соединения. Это решение выбрано из-за предсказуемости производительности и надежности — музейный экспонат не может позволить себе неожиданные задержки или потери сообщений.

rust
// src/integrations/grpc_client.rs
use tonic::transport::Channel;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
pub struct GajaeRequest {
    pub command: String,
    pub context: serde_json::Value,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct GajaeResponse {
    pub result: serde_json::Value,
    pub metadata: Option<serde_json::Value>,
}

pub struct GajaeGrpcClient {
    channel: Channel,
}

impl GajaeGrpcClient {
    pub async fn new(grpc_url: &str) -> anyhow::Result<Self> {
        let channel = Channel::from_static(grpc_url).connect().await?;
        Ok(Self { channel })
    }

    pub async fn send_command(&self, request: GajaeRequest) -> anyhow::Result<GajaeResponse> {
        // Реализация gRPC вызова к Gajae-Code
        // ... код клиента
    }
}

Для работы с LazyCodex используется HTTP API, которое возвращает AI-решения в структурированном формате. Эти данные затем обрабатываются и кэшируются в памяти для быстрого доступа.

rust
// src/integrations/lazycodex_client.rs
use reqwest::Client;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
pub struct LazyCodexQuery {
    pub prompt: String,
    pub context: Option<serde_json::Value>,
}

pub struct LazyCodexClient {
    client: Client,
    base_url: String,
}

impl LazyCodexClient {
    pub fn new(base_url: &str) -> Self {
        Self {
            client: Client::new(),
            base_url: base_url.to_string(),
        }
    }

    pub async fn query(&self, query: LazyCodexQuery) -> anyhow::Result<serde_json::Value> {
        let response = self.client
            .post(&format!("{}/api/query", self.base_url))
            .json(&query)
            .send()
            .await?;

        let data = response.json().await?;
        Ok(data)
    }
}

Основной цикл работы экспоната выглядит следующим образом:

rust
// src/main.rs
use claw_code::{GajaeGrpcClient, LazyCodexClient, AgentManager};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Инициализация логгера
    let subscriber = tracing_subscriber::fmt()
        .with_max_level(tracing::Level::INFO)
        .compact()
        .finish();
    tracing::subscriber::set_global_default(subscriber)?;

    // Подключение к AI-системам
    let gajae_client = GajaeGrpcClient::new("http://gajae-code.internal:8080").await?;
    let lazycodex_client = LazyCodexClient::new("http://lazycodex.internal:9090");

    // Инициализация агентов
    let mut agent_manager = AgentManager::new();
    agent_manager.spawn_interpretation_agent(gajae_client).await?;
    agent_manager.spawn_response_agent(lazycodex_client).await?;

    // Основной цикл обработки посетителей
    let listener = TcpListener::bind("0.0.0.0:8080").await?;
    loop {
        let (mut socket, _) = listener.accept().await?;
        
        // Обработка каждого подключения в отдельной задаче
        tokio::spawn(async move {
            if let Err(e) = handle_visitor(&mut socket).await {
                tracing::error!("Error handling visitor: {}", e);
            }
        });
    }
}

Такой подход обеспечивает высокую производительность и предсказуемость работы музейного экспоната. Система может обрабатывать до 1000 одновременных подключений от посетителей, при этом каждый AI-агент работает изолированно, что предотвращает взаимные влияния и обеспечивает стабильность всего экспоната.

Для мониторинга используется Prometheus экспортер, который собирает метрики о загрузке системы, времени ответа AI-агентов и количестве активных посетителей. Эти данные отображаются на панели управления музея, что позволяет администраторам быстро реагировать на любые изменения в работе системы.

Автономное обслуживание

Автономное обслуживание

С практической точки зрения, любой проект, который претендует на звание «автономного», перестаёт им быть в тот момент, когда администратору приходится заходить по SSH, чтобы перезапустить зависший процесс. Для музейного экспоната, который должен работать месяцами без надзора, предсказуемость поведения системы важнее, чем набор функций.

Развертывание без участия человека

Чтобы исключить человеческий фактор при запуске claw-code, я использую стандартный подход с контейнеризацией. Rust отлично подходит для этого: статически скомпилированный бинарный файл в образе на базе Alpine Linux занимает минимум места и не тянет за собой лишних зависимостей.

Для развертывания использую Docker Compose. Это позволяет описать всю инфраструктуру — от самого агента до зависимостей по API — в одном файле. Сначала убедитесь, что в системе установлен Docker и Docker Compose:

bash
docker --version
docker compose version

Привожу пример конфигурации docker-compose.yml, которая обеспечивает автоматический перезапуск контейнера при любом сбое:

yaml
services:
  claw-code:
    image: ultraworkers/claw-code:latest
    restart: always # Гарантирует запуск после перезагрузки сервера или падения процесса
    environment:
      - AI_AGENT_KEY=${AI_AGENT_KEY}
      - LOG_LEVEL=info
    volumes:
      - ./config:/app/config # Монтируем конфиги, чтобы менять их без пересборки образа
      - ./logs:/app/logs
    network_mode: host # Используем host-сеть для прямого доступа к периферии экспоната

С таким подходом развёртывание сводится к одной команде: docker compose up -d. Если нода с экспонатом уйдёт в ребут из-за скачка напряжения, systemd поднимет Docker-демон, а тот, в свою очередь, восстановит работу claw-code.

Мониторинг и обновления

Автономность не означает отсутствие контроля. Напротив, чем меньше вы касаетесь системы, тем более детальным должен быть мониторинг. Я не доверяю «молчанию» сервера: если мониторинг не присылает алерты, это не значит, что всё работает — возможно, упал сам мониторинг.

Для отслеживания состояния экспоната я использую связку Prometheus и Grafana. claw-code должен отдавать метрики в формате Prometheus по определённому порту. Чтобы проверить, что метрики доступны, выполните запрос:

bash
curl http://localhost:9090/metrics

В качестве основного инструмента контроля за здоровьем процесса использую systemd (если запуск идёт не в Docker) или встроенные healthcheck-и контейнера. Пример правильного healthcheck в docker-compose.yml:

yaml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:9090/health"]
  interval: 30s
  timeout: 10s
  retries: 3

Что касается обновлений, я категорически против автоматического pull последних образов в продакшене. Это путь к непредсказуемости. Обновления должны проходить через CI/CD пайплайн с предварительным тестированием на стейджинге.

С практической точки зрения, процесс выглядит так:

  1. Сборка нового образа в GitHub Actions.
  2. Проверка базовых функций на тестовом стенде.
  3. Обновление тега образа в конфигурационном файле и перезапуск сервиса.

Такой подход гарантирует, что музейный экспонат не превратится в «кирпич» в самый неподходящий момент из-за неудачного обновления AI-модели или изменения в API LazyCodex.

Часто задаваемые вопросы

Почему для управления экспонатом выбран Rust, а не Python

С практической точки

Поделиться:TelegramX / TwitterVK