Ricazo: кратко о главном
🎯 О чём этот конспект: Пошаговый разбор архитектуры и методологии создания open-source AI-ассистента Ricazo за один день. Автор делится практическими паттернами: использование локальных эмуляторов для обхода API-лимитов, обязательная верификация через скриншоты в CI/CD и автономное управление репозиторием с сотнями контрибьюторов с помощью AI-агентов.
👤 Кому будет полезно: Вайбкодерам, инженерам и соло-фаундерам, которые создают сложные кроссплатформенные продукты с помощью LLM-агентов и хотят автоматизировать тестирование, код-ревью и поддержку масштабных проектов.
✨ Что получите: Готовую систему валидации кода нейросетями через эмуляцию внешних сервисов (Slack, GitHub, Stripe, sandboxes), шаблоны настройки скриншот-тестов на Playwright и пайплайн автономного мерджа pull request'ов без участия человека.
1. Архитектурное планирование: абстракция провайдеров и zero-lock-in
Контекст: Попытка создать крупный AI-продукт по одной короткой текстовой инструкции гарантированно заведёт нейросеть в тупик или создаст жёсткую зависимость от сторонних библиотек. Для создания масштабируемого open-source решения требуется предварительная фаза планирования (Plan Mode) длительностью около часа, где фиксируются строгие правила изоляции компонентов. Все внешние зависимости (LLM-модели, песочницы для запуска кода, интеграции) должны быть скрыты за едиными интерфейсами, чтобы пользователи могли выбирать любой бэкенд без переписывания кодовой базы.
Тайминг:
Выгода: Полная независимость от конкретных вендоров (OpenAI, Anthropic, E2B, Daytona, Composio) и возможность для комьюнити подключать любые альтернативные сервисы через простые адаптеры.
Как применить:
- Шаг 1: Формирование спецификации проекта — AI-ассистент — Запустите диалог планирования (например, в Cursor/Claude с включенным Plan Mode) и зафиксируйте в
AGENTS.mdархитектурные ограничения. - Шаг 2: Реализация интерфейсной изоляции — TypeScript — Создайте строгие TypeScript-интерфейсы для каждого типа внешних сервисов (LLM-провайдеры, Sandbox-провайдеры, каталоги инструментов).
// Пример интерфейса изоляции песочниц (Sandbox Provider)
export interface SandboxProvider {
id: string;
createEnvironment(config: EnvironmentConfig): Promise<SandboxInstance>;
executeCommand(instanceId: string, command: string): Promise<ExecutionResult>;
destroyEnvironment(instanceId: string): Promise<void>;
}
// Пример интерфейса универсального LLM-адаптера
export interface ModelClient {
generateStream(messages: ChatMessage[], tools: ToolDefinition[]): AsyncIterable<StreamChunk>;
validateApiKey(key: string): Promise<boolean>;
}- Шаг 3: Автономное выполнение плана через Goal-режим — Claude / Grok / Cursor — Передайте сформированный файл плана агенту с командой последовательного выполнения задач с проверкой чек-листа до полной готовности.
Проанализируй спецификацию в AGENTS.md. Реализуй проект пошагово, закрывая пункты плана.
Любая новая интеграция ДОЛЖНА реализовывать базовые интерфейсы из src/core/interfaces/.
Прямые вызовы сторонних SDK (Composio, Daytona, Boat, OpenAI) внутри бизнес-логики строго запрещены.Результат: Модульная архитектура, работающая на Web, Desktop (Electron) и Mobile (Expo / React Native) с поддержкой любых LLM (OpenRouter, локальные модели через Ollama, ChatGPT, Claude) и песочниц.
2. Локальные эмуляторы: тестирование интеграций без реальных API и лимитов
Контекст: При автономной разработке агентом главная проблема тестирования сложных интеграций (Slack, Gmail, GitHub, Stripe, Sandbox API) — блокировки сервисов, строгие rate-limits и необходимость ввода реальных учетных данных. Классические моки часто поверхностны и не сохраняют состояние системы между запросами. Решение заключается в создании полноценных легковесных in-memory эмуляторов, которые полностью повторяют протоколы и HTTP-эндпоинты реальных платформ и хранят состояние сессии.
Тайминг:
Выгода: Полностью офлайн-тестирование в CI/CD без затрат на API, нулевой риск словить бан от Google/Slack при тысячах автоматических прогонов.
Как применить:
- Шаг 1: Выбор или генерация эмуляторов — AI-ассистент / TypeScript — Используйте готовые решения (например,
@vercel/emulate, LocalStack) или попросите AI спарсить документацию нужного сервиса и сгенерировать локальный HTTP-сервер с базой данных в памяти.
// in-memory эмулятор для Slack/Composio API
import express from 'express';
const app = express();
app.use(express.json());
const messagesDb: Array<{ id: string; channel: string; text: string; ts: number }> = [];
app.post('/api/chat.postMessage', (req, res) => {
const { channel, text } = req.body;
const message = { id: `msg_${Date.now()}`, channel, text, ts: Date.now() };
messagesDb.push(message);
return res.status(200).json({ ok: true, message });
});
app.get('/api/conversations.history', (req, res) => {
const { channel } = req.query;
const history = messagesDb.filter(m => m.channel === channel);
return res.status(200).json({ ok: true, messages: history });
});
app.listen(4030, () => console.log('Stateful Mock Server running on http://localhost:4030'));- Шаг 2: Настройка окружения для тестов — Bash / Node.js — Настройте подмену URL внешних сервисов на переменные окружения, указывающие на локальный порт эмулятора при выполнении тестов.
# Запуск локальных эмуляторов перед тестами
export SLACK_API_BASE_URL="http://localhost:4030/api"
export COMPOSIO_API_URL="http://localhost:4031/api"
npm run test:e2eРезультат: AI-агент получает возможность самостоятельно проверять цепочки действий (создание репозитория -> открытие PR -> отправка вебхука -> нотификация в чат) в герметичном окружении.
3. Скриншот-верификация: сквозной контроль качества UI и артефактов
Контекст: Доверять текстовым отчётам нейросети о том, что функционал «готов и работает», нельзя: LLM часто галлюцинируют успешными сборками при сломанном UI. Единственный надёжный способ заставить AI-агента довести интерфейс до идеала — требовать визуальное доказательство в виде скриншота каждого экрана и компонента во всех состояниях (светлая/тёмная тема, мобильный и десктопный лейаут).
Тайминг:
Выгода: Мгновенный визуальный аудит сотен страниц и состояний приложения без необходимости разворачивать проект локально при каждом PR.
Как применить:
- Шаг 1: Настройка Playwright для автоматического снятия скриншотов — Playwright / Maestro — Создайте тестовый сценарий, который проходит по всем роутам, кликает по элементам и сохраняет скриншоты в артефакты сборки.
// tests/visual-verification.spec.ts
import { test, expect } from '@playwright/test';
const routes = [
{ path: '/', name: 'landing' },
{ path: '/chat', name: 'chat-interface' },
{ path: '/settings/providers', name: 'provider-settings' },
{ path: '/artifacts', name: 'artifact-viewer' }
];
for (const route of routes) {
test(`Capture screenshot for ${route.name}`, async ({ page }) => {
await page.goto(`http://localhost:3000${route.path}`);
await page.waitForLoadState('networkidle');
// Светлая тема
await page.screenshot({ path: `screenshots/${route.name}-light.png`, fullPage: true });
// Переключение в темную тему
await page.emulateMedia({ colorScheme: 'dark' });
await page.screenshot({ path: `screenshots/${route.name}-dark.png`, fullPage: true });
});
}- Шаг 2: Включение скриншотов в обязательный регламент агента — Промпт / AGENTS.md — Пропишите в инструкциях агента правило: задача считается выполненной только при наличии прикрепленного скриншота работоспособности.
Задача считается завершенной ТОЛЬКО ЕСЛИ:
1. Запущен Playwright/Maestro тест.
2. Получен скриншот измененного или нового интерфейса.
3. На скриншоте отсутствуют артефакты верстки, битые шрифты и наложения элементов.
Если скриншот не сгенерирован или содержит ошибки, продолжай исправлять код.Результат: База из 350+ скриншотов, генерируемая на каждом прогоне CI, которая отображает реальное состояние каждого экрана проекта.
4. Автономный CI/CD: AI-ревьюер, автомердж и очистка от AI-мусора
Контекст: Когда open-source репозиторий привлекает сотни контрибьюторов, использующих AI для создания PR, мейнтейнер физически не успевает вручную разбирать тысячи изменений. Чтобы закрывать свыше 1 200 PR силами одного человека, требуется делегировать рутинный мердж и ревью автономному AI-агенту, работающему по расписанию (cron) или вебхукам GitHub.
Тайминг:
Выгода: Обработка сотен пулл-реквестов в фоновом режиме, мгновенный мердж проверенных багфиксов и поддержание чистоты UI/копирайта.
Как применить:
- Шаг 1: Настройка GitHub Actions для автоматического тестирования — GitHub Actions — Запустите пайплайн, запускающий линтеры, unit/e2e тесты и генерацию скриншотов на бесплатных раннерах для Open Source.
# .github/workflows/verify-pr.yml
name: Verify and Capture PR
on: [pull_request]
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npx playwright install --with-deps
- run: npm run test:visual
- uses: actions/upload-artifact@v4
with:
name: pr-screenshots
path: screenshots/- Шаг 2: Настройка AI-агента для триажа и мерджа PR — Node.js / Claude / Grok — Разверните скрипт по крону (или через фонового агента), который анализирует diff, проверяет скриншоты и принимает решение о мердже.
// scripts/ai-maintainer.ts
import { Octokit } from '@octokit/rest';
const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
async function triagePR(prNumber: number, diff: string, testResults: boolean) {
if (!testResults) {
await octokit.issues.createComment({
owner: 'owner', repo: 'ricazo', issue_number: prNumber,
body: 'Тесты или скриншот-валидация не прошли. Исправьте ошибки.'
});
return;
}
// Промпт для оценки риска изменений
const reviewDecision = await evaluateDiffWithAI(diff); // 'AUTO_MERGE' | 'NEEDS_HUMAN'
if (reviewDecision === 'AUTO_MERGE') {
await octokit.pulls.merge({ owner: 'owner', repo: 'ricazo', pull_number: prNumber });
} else {
await octokit.issues.createComment({
owner: 'owner', repo: 'ricazo', issue_number: prNumber,
body: 'Изменение классифицировано как крупная фича. Ожидает аппрува мейнтейнера.'
});
}
}- Шаг 3: Автоматическая очистка UI-копирайта (Anti-Slop Bot) — Cron Job — Запустите фоновую задачу, которая проверяет новые тексты интерфейса на наличие типичной «нейросетевой воды» и длинных ненужных пояснений, сокращая их до лаконичных фраз.
Результат: Репозиторий обрабатывает тысячи PR, удерживая число открытых задач на минимальном уровне (около 15), без перегрузки мейнтейнера.
5. Защита и харднинг: аудит безопасности через DeepSeek/DeepSec
Контекст: Быстрая генерация кода через AI часто приводит к появлению скрытых уязвимостей: некорректная санитизация входных данных, утечки переменных окружения в клиентский бандл, небезопасный запуск команд в sandbox-контейнерах. После завершения фазы базовой генерации проекта необходим отдельный автоматизированный прогон через специализированные инструменты аудита безопасности.
Тайминг:
Выгода: Предотвращение RCE (удаленного выполнения кода) и утечек секретов до публикации приложения в открытый доступ.
Как применить:
- Шаг 1: Запуск аудита безопасности — DeepSec / Snyk / SonarQube — Просканируйте весь сгенерированный репозиторий на предмет уязвимостей зависимостей и логических дыр в обработке команд.
# Пример запуска сканирования безопасности проекта
npx @vercel/deepsec scan --dir . --report json > security-report.json- Шаг 2: Скармливание отчёта агенту на исправление — LLM Prompt — Передайте JSON-отчет модели с требованием устранить все найденные уязвимости без изменения внешних API.
Проанализируй security-report.json. Исправь все уязвимости уровня HIGH и CRITICAL.
Особое внимание удели изоляции вызовов в sandbox-провайдерах и валидации пользовательских токенов.
После правок запусти тесты и убедись, что обратная совместимость сохранена.Результат: Защищенная кодовая база, готовая к безопасному селф-хостингу пользователями.
Ricazo: ответы на частые вопросы
В: Зачем нужны локальные эмуляторы, если можно использовать стандартные моки (jest.mock / vitest spy)?
О: Обычные моки лишь подменяют ответ одной функции и не сохраняют состояние. Эмуляторы поднимают настоящий локальный HTTP-сервер со встроенной in-memory БД. Это позволяет тестировать сложные многошаговые цепочки (создание ресурса, повторный запрос, изменение статуса, удаление) без обращения к реальным API.
В: Как AI-агент делает скриншоты мобильного приложения на Expo / React Native?
О: Для тестирования мобильного UI используется фреймворк Maestro или связка Appium/Playwright, запущенная поверх веб-сборки Expo (expo start --web) или в эмуляторе Android/iOS, с автоматическим захватом кадров экрана по завершении сценариев взаимодействия.
В: Не опасно ли доверять AI автоматический мердж pull request'ов?
О: Автомердж применяется только для низкорисковых задач (простые багфиксы, обновление типов, локализация) и ТОЛЬКО при условии успешного прохождения всех Playwright-тестов, скриншот-проверок и линтеров. Крупные фичи и потенциально опасные изменения размечаются ботом для обязательного ручного аппрува человеком.
В: Какую модель лучше использовать для планирования, а какую — для кодинга?
О: Для фазы проектирования и архитектуры (Plan Mode) лучше использовать reasoning-модели с глубокой проработкой логики (например, GPT-4.5/GPT-5/Claude Opus), а для непосредственного написания кода и реализации компонентов — быстрые и мощные кодинг-модели (Grok, Claude Sonnet).
В: Как бороться с «нейромусором» (slop) в текстах интерфейса при генерации AI?
О: Настройте регулярный скрипт или промпт в CI/CD, который сканирует языковые файлы и компоненты, отслеживая избыточные многословные описания, и заменяет их на минималистичный UI-копирайт в стиле современных SaaS-интерфейсов.
Ricazo: инструменты и ссылки из видео
- Ricazo — Open-source AI-ассистент с поддержкой собственных компьютеров для каждого бота и кроссплатформенной синхронизацией — упомянут в видео.
- Inbox Zero — Open-source инструмент для автоматизации и очистки почты от того же автора — упомянут в видео.
- Expo — Фреймворк для кроссплатформенной разработки на React Native (iOS, Android, Web) —
https://expo.dev - Electron — Фреймворк для создания кроссплатформенных десктопных приложений на JS/TS —
https://www.electronjs.org - Boat (ранее Box) — Провайдер изолированных облачных песочниц для запуска кода агентами —
https://boat.dev - Daytona — Open-source среда разработки и платформа изолированных рабочих пространств —
https://daytona.io - E2B — Платформа изолированных облачных песочниц для AI-агентов —
https://e2b.dev - Composio — Платформа интеграции AI-агентов с тысячами внешних сервисов и MCP-инструментов —
https://composio.dev - Emulate.dev — Инструмент от Vercel Labs для локальной эмуляции сторонних API со стейтом —
https://emulate.dev - Playwright — Фреймворк для сквозного E2E и визуального регрессионного тестирования —
https://playwright.dev - Maestro — Фреймворк UI-тестирования для мобильных приложений на React Native / Native —
https://maestro.mobile.dev - LocalStack / FlowKey — Локальные эмуляторы облачных сервисов AWS для тестирования —
https://localstack.cloud
Конспект создан на основе видео «How I Built an Open Source Grokbot in a Day» канала Ricazo / Inbox Zero. Все права на оригинальный материал принадлежат авторам. Источник: https://www.youtube.com/watch?v=xk-aLMQRYfk
