ultraworkers/claw-code: автономный экспонат на Rust
Разбираем проект claw-code: автономный музейный экспонат на Rust, который разрабатывает и поддерживает себя без участия человека.
Что такое claw-code
Что такое claw-code
Идея автономного музейного экспоната
Обычный музейный экспонат — это статичный объект. Его создали, установили, и дальше он существует до тех пор, пока не сломается или его не демонтируют. claw-code предлагает другой подход: экспонат, который сам пишет свой код, компилирует его, запускает и исправляет ошибки без участия человека.
С практической точки зрения это близко к тому, как я когда-то настраивал авторазвёртывание на кластере Proxmox. Разница в одном: там человек всё ещё писал плейбуки и следил за алертами, а в claw-code человек вынут из цикла полностью. Экспонат сам решает, что ему нужно изменить, и применяет изменения.
Во-первых, это меняет роль музея. Вместо куратора, который следит за состоянием экспоната, получается среда, в которой экспонат эволюционирует сам. Во-вторых, появляется вопрос предсказуемости. Если система меняет себя сама, сложно заранее сказать, в каком состоянии она будет через неделю. Именно поэтому в проекте уделяют внимание детерминизму и системным журналам, которые позволяют восстановить цепочку изменений.
Если мы посмотрим на автономность с точки зрения инженерии, то получается нечто вроде сада, который поливает сам себя. Серверы в моей домашней лаборатории названы в честь персонажей советских мультфильмов — Винни-Пух, Пятачок, Сова — и каждый из них делает свою строго определённую работу. claw-code пытается перенести эту предсказуемость на уровень, где сервис не просто выполняет задачи, но и сам решает, какие задачи ставить.
Стек технологий: Rust, Gajae-Code и LazyCodex
Для автономной системы выбор языка — не вопрос предпочтений, а вопрос надёжности. Rust подходит здесь по нескольким причинам. Отсутствие сборщика мусора означает, что не будет неожиданных пауз в работе экспоната. Модель владения и заимствований отлавливает ошибки с памятью на этапе компиляции, а не в момент, когда музейный посетитель смотрит на экран. Для меня, как для человека, который ценит предсказуемость в конфигурациях, это критично.
В проекте используются три основных компонента:
- Rust — базовый язык, на котором написан сам экспонат и его инфраструктура.
- Gajae-Code — модуль генерации кода, который позволяет системе создавать новые фрагменты программы на лету.
- LazyCodex — слой отложенного выполнения, отвечающий за то, чтобы компоненты загружались и инициализировались только тогда, когда в них реальная необходимость.
Пример минимального Cargo.toml может выглядеть так:
toml[package]
name = "claw-code"
version = "0.1.0"
edition = "2021"
[dependencies]
# Генерирует код во время компиляции
gajae-code = "0.3"
# Управляет отложенной загрузкой модулей
lazy-codex = "0.2"
# Логирование в системный журнал
tracing-subscriber = "0.3"
Сам входной пункт может быть простым:
rustuse tracing::{info, warn};
use lazy_codex::LazyModule;
use gajae_code::CodeGenerator;
fn main() {
tracing_subscriber::fmt::init();
let generator = CodeGenerator::new();
let module = LazyModule::load("exhibit_core");
info!("Автономный экспонат запущен");
if let Some(mut code) = generator.generate_next() {
module.update(code).expect("не удалось применить сгенерированный код");
}
}
Здесь важно не сам код, а принцип: система не ждёт команды извне. Она sama решает, что сгенерировать, и sama применяет изменения. С точки зрения эксплуатации это означает, что администратор не пишет Ansible-плейбуки для обновления — он только настраивает начальные условия и наблюдает.
Я привык писать конфиги руками, даже если есть GUI, потому что только так ясно, что происходит под капотом. В claw-code этот подход доведён до extremos: конфиг пишет сама система, а человек получает только логи и метрики.
Разработка без участия человека
Разработка без участия человека
Как агент вносит изменения в код
Автономный агент в claw-code работает по простому принципу: он читает текущее состояние репозитория, анализирует issue или запрос на изменение, вносит правки и запускает проверки. Если всё зелёное — коммитит и пушит. Если нет — откатывает и пробует иначе.
С практической точки зрения, процесс выглядит так. Агент поднимает локальную копию репозитория, запускает cargo check и cargo test, чтобы понять базовое состояние. Затем вносит изменения в код, снова прогоняет проверки и только после этого фиксирует коммит. Ниже пример того, как может выглядеть цикл агента в виде скрипта:
bash#!/bin/bash
set -e
# Обновляем локальную копию
git pull origin main
# Проверяем, что проект собирается
cargo check --all-targets
# Запускаем тесты
cargo test --all
# Вносим изменения (примерно так агент правит код)
sed -i 's/old_function/new_function/' src/main.rs
# Снова проверяем после изменений
cargo check --all-targets
cargo test --all
# Коммитим, если всё прошло
git add -A
git commit -m "chore: autonomous update by claw-code agent"
git push origin main
Важный момент: агент не пишет код «от фонаря». Он опирается на существующие тесты и типы. Rust здесь играет на руку — строгая типизация и borrow-checker отсекают целый класс ошибок ещё до запуска. Если агент попытается передать не тот тип или нарушить время жизни заимствования, компилятор не пропустит. Это даёт предсказуемость конфигураций, которой так не хватает в динамических языках.
Конфигурация агента может выглядеть примерно так:
toml[agent]
name = "claw-code"
repository = "https://github.com/ultraworkers/claw-code"
branch = "main"
[checks]
command = "cargo check --all-targets"
timeout = 300
[tests]
command = "cargo test --all"
timeout = 600
[commit]
author = "claw-code <bot@ultraworkers.dev>"
message_prefix = "chore:"
Агент работает в изолированной среде — обычно это контейнер с предустановленным Rust и необходимыми зависимостями. После каждого успешного коммита он может запустить сборку Docker-образа и обновить развёрнутый экземпляр экспоната, но только если тесты прошли.
Ограничения полностью автономной разработки
Полностью автономная разработка — это не волшебная кнопка «сделай сам». У неё есть жёсткие границы, и лучше понимать их до того, как доверить агенту продакшен.
Во-первых, агент не понимает контекст бизнеса. Он может идеально реализовать функцию, которая решает не ту проблему. Например, если пользователь просит «ускорить загрузку экспоната», агент может оптимизировать рендеринг, хотя узким местом была сеть. Без человека в цикле такая оптимизация бесполезна.
Во-вторых, агент не умеет принимать архитектурные решения. Он может добавить зависимость в Cargo.toml, которая тянет за собой десяток транзитивных критов, и не заметить, что один из них abandonné или содержит уязвимость. Человек всё равно должен аудитировать зависимости:
toml[dependencies]
# Агент может добавить это бездумно
some-crate = "0.1.0"
В-третьих, агент не видит реального оборудования. Музейный экспонат работает на конкретном железе с конкретными датчиками, экранами и блоками питания. Агент может изменить код так, что он будет работать в симуляторе, но упадёт на реальном устройстве из-за нехватки памяти или другого тайминга.
Наконец, есть проблема отладки. Когда автономный агент ломает сборку, он может сделать десяток коммитов, пытаясь исправить ошибку, и в итоге запутаться в своей же истории. Человеку придётся разбираться, что именно пошло не так, и откатывать изменения вручную.
bash# Пример отката изменений агента
git log --oneline -20
git revert <commit-hash>
git push origin main
Вывод простой: автономный агент полезен для рутины — рефакторинга, исправления типовых ошибок, обновления зависимостей. Но архитектурные решения, оценка влияния на бизнес и работа с реальным оборудованием остаются за человеком. Без этого «автономная разработка» быстро превращается в автономное создание проблем.
Архитектура и взаимодействие
Архитектура и взаимодействие
claw-code собран вокруг одной идеи: экспонат должен работать годами без вмешательства. В Rust это получается благодаря отсутствию сборщика мусора и строгой проверке типов на этапе компиляции. Но язык — только половина дела. Важнее, как части общаются между собой и с внешним миром.
Связь с посетителями музея
Посетитель подходит к экспонату — срабатывает датчик движения, экран просыпается, интерфейс предлагает взаимодействие. Это выглядит просто, но под капотом цепочка из нескольких компонентов.
Во-первых, нужен способ узнать, что кто-то подошёл. В домашней лаборатории я использовал аналогичную схему с датчиком HC-SR501 на Raspberry Pi — срабатывание триггерит скрипт, который будит дисплей. В claw-code роль датчика играет модуль на базе ESP32, который шлёт событие по MQTT в основной процесс на Rust.
С практической точки зрения, удобнее всего выставить локальный веб-интерфейс на Axum. Посетитель не устанавливает приложение, он открывает страницу по локальному адресу или взаимодействует через сенсорный экран, подключённый напрямую к плате.
Пример конфига systemd-юнита, который держит экспонат в работе:
ini[Unit]
Description=claw-code autonomous exhibit
After=network.target mosquitto.service
[Service]
Type=simple
User=exhibit
WorkingDirectory=/opt/claw-code
ExecStart=/opt/claw-code/target/release/claw-code
Restart=always
RestartSec=5
Environment=RUST_LOG=info
Environment=MQTT_BROKER=tcp://mosquitto:1883
[Install]
WantedBy=multi-user.target
systemd поднимет процесс через пять секунд после падения. Это базовая предсказуемость, без которой не стоит выносить устройство в публичное пространство.
Для чтения GPIO я использую libgpiod — современная замена старого sysfs интерфейса. Пример инициализации в Rust:
rustuse gpiod::{Chip, LineRequestFlags};
let chip = Chip::open("gpiochip0").expect("не удалось открыть чип GPIO");
let line = chip.get_line(17).expect("линия 17 не найдена");
line.request(
LineRequestFlags::INPUT,
0,
"claw-motion-sensor",
).expect("не удалось запросить линию");
Если мы посмотрим на взаимодействие с посетителем как на запрос-ответ, то всё укладывается в привычную веб-модель: GET запрос отдаёт текущее состояние экспоната, POST принимает действие посетителя. Axum обрабатывает это без лишних зависимостей.
Управление состоянием экспоната
Автономный экспонат не может позволить себе зависнуть в неопределённом состоянии. Если посетитель нажал кнопку, а система не отреагировала — это уже инцидент. Поэтому состояние описывается конечным автоматом.
Я именую серверы в честь персонажей советских мультфильмов, но состояния экспоната называю по-взрослому: Idle, Interacting, Error, Maintenance, Sleep. Переходы между ними прописаны явно, никакой магии.
Пример определения состояний:
rust#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ExhibitState {
Idle,
Interacting,
Error,
Maintenance,
Sleep,
}
impl ExhibitState {
pub fn next(self, event: Event) -> Option<Self> {
match (self, event) {
(ExhibitState::Idle, Event::MotionDetected) => Some(ExhibitState::Interacting),
(ExhibitState::Interacting, Event::Timeout) => Some(ExhibitState::Idle),
(ExhibitState::Interacting, Event::CriticalError) => Some(ExhibitState::Error),
(ExhibitState::Error, Event::Reset) => Some(ExhibitState::Idle),
(ExhibitState::Maintenance, Event::MaintenanceEnd) => Some(ExhibitState::Idle),
_ => None,
}
}
}
С практической точки зрения, важно не только переключать состояния, но и сохранять их. Если экспонат перезагрузится после отключения питания, он должен знать, в каком состоянии был. Я использую простой JSON-файл на файловой системе, который пишется при каждом переходе:
json{
"state": "Idle",
"updated_at": "2024-01-15T14:32:00Z",
"visitor_count": 142
}
При старте приложение читает этот файл и восстанавливает состояние. Если файла нет — начинает с Idle. Это дешёвый и надёжный способ избежать состояния «неизвестно», которое чаще всего приводит к простою.
Если мы посмотрим на мониторинг, то состояние экспоната отдаётся через Prometheus метрику claw_exhibit_state. Alertmanager может среагировать, если экспонат застрял в Error дольше пяти минут. В музее никто не будет ждать, пока администратор заметит проблему сам.
Выводы для инженеров
Выводы для инженеров
Когда автономная разработка оправдана
Автономная разработка системы, такая как claw-code, оправдана, когда проект обладает трех ключевыми свойствами: стабильность работы без вмешательства, предсказуемость поведения и отсутствие критических точек отказа, требующих ручного вмешательства. В случае с музееским экспонатом на Rust эти условия соблюдаются благодаря компилятору, который гарантирует отсутствие утечек памяти и отступлений по производительности, а Rust-компилятор отсекает ошибки времени выполнения на этапе сборки.
Для кластера из трёх нод на Proxmox и TrueNAS с Raspberry Pi это оправдано, потому что:
- Каждый узел имеет изолированную среду выполнения (container или VM)
- Система не требует постоянного мониторинга состояния — она сама реагирует на сбои
- Код написан на Rust, что обеспечивает безопасность и предсказуемость
Пример запуска основного контейнера с автостартом:
bashdocker run -d \ --name claw-exhibit \ --restart unless-stopped \ -v /data:/mnt/data \ -p 8080:8080 \ claw-code/claw-exhibit:latest
Конфигурация системы включает автоматический бэкап и мониторинг:
yaml# config/auto-backup.yaml
backup:
schedule: "0 2 * * *" # в 2 часа ночи
destination: "s3://museum-backups"
retention: 30
enabled: true
Риски и границы применимости
Несмотря на преимущества автономности, существуют риски, которые необходимо учитывать. Главная проблема — непредсказуемость поведения при экстремальных условиях. Если экспонат должен работать в условиях нестабильного электропитания или сетевого разрыва, без внешнего контроля вероятность отказа возрастает. Решение — реализовать fallback-логику, которая переключает систему на критическое состояние при обнаружении аномалии.
Другой риск — скрытые деградации производительности. Rust гарантирует отсутствие утечек памяти, но не гарантирует оптимального использования CPU при неправильно подобранных алгоритмах. Например, в кластере из трёх нод TrueNAS нагрузка может распределяться неравномерно, что приведёт к перегреву и снижению lifespan диска.
Границы применимости включают:
- Масштабирование: автономная система подходит для статических наборов данных (фотографии, аудио), но сложные вычисления в реальном времени требуют внешнего оркестратора
- Обновления: замена версии claw-code без остановки экспоната возможно только через hot-reload или миграцию контейнеров; в критических ситуациях это требует ручного вмешательства
- Отказоустойчивость: при отказе основного узла кластер должен иметь механизм восстановления (например, через Kubernetes или Proxmox HA)
Для минимизации рисков рекомендуется внедрить:
- Мониторинг ресурсов с алертами (Prometheus + Alertmanager)
- Регулярный аудит конфигураций (Ansible playbooks)
- Тестирование отказоустойчивости в стендовой среде перед развёртыванием