@sergey-guns/tiny-agent

v0.1.1

Published

24 days ago

Autonomous AI coding agent with TUI — runs in the context of any directory

0High
0Medium
0Low

🤖 tiny-agent — Minimalist Multi-Agent Development Framework

Минималистичный фреймворк для создания автономных ИИ-разработчиков на базе TypeScript. Архитектура построена на чистом протоколе RLM (Recursive Language Model) без использования тяжелых сторонних абстракций (LangChain / LlamaIndex).

🎯 Основная концепция

Проект доказывает, что для создания надежного ИИ-агента достаточно стандартной библиотеки Node.js и прямых запросов к API модели. Система спроектирована для безопасного написания кода, автоматического тестирования и самокоррекции с жестким контролем изменений через Git.

Философия разработки:

Zero-Dependency Core: Минимальное количество внешних зависимостей. Только нативный fetch.
Полная прозрачность: Каждое действие и мысль логируются в файл сессии.
Безопасность через транзакции: Любое действие агента может быть автоматически откачено, если оно ломает проект.
Многовариантность моделей: Поддержка LM Studio, OpenRouter, Anthropic, OpenAI и других провайдеров через единый интерфейс.

✨ Ключевые возможности

Архитектура

RLM (Recursive Language Model): Модель сама решает, сколько вызовов инструментов сделать за один шаг. Результаты агрегируются и подаются обратно как батч.
Многодействие за один шаг: Агент может вызвать несколько независимых инструментов одновременно (параллельное чтение файлов, поиск + запись и т.д.).
Планирование (Plan Mode): Агент сначала строит план, затем выполняет его с промежуточными рефлексиями.
Декомпозиция задач: Сложные задачи разбиваются на атомарные подзадачи через subagent.
Валидация результатов: Каждый результат инструмента проверяется и корректируется субагентом.

Инструменты

search_web — Поиск в интернете (DuckDuckGo / Wikipedia / MCP web-search)
fetch_url_content — Извлечение текста из URL
list_directory — Просмотр структуры файлов
read_file_content — Чтение исходного кода
write_file_content — Безопасная запись файлов
create_directory — Создание директорий
write_plan_file — Запись плана задачи
search_in_files — Поиск по содержимому файлов
execute_shell_command — Выполнение команд в терминале
query_language_model — Рекурсивный вызов LLM (для классификации, анализа)
signal_task_complete — Сигнал о завершении задачи
decompose_and_execute — Декомпозиция и выполнение сложных задач

Пользовательский интерфейс

Текстовый TUI: Пошаговая цветная визуализация работы в терминале (256-цветный ANSI).
@filename TAB autocomplete: Автодополнение имен файлов с прикреплением содержимого.
Провайдеры: Переключение между моделями через \provider в TUI.
Прогресс-бар и статус: Индикация текущего шага, контекста, используемой модели.

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

READ ≠ WRITE: Агент не записывает файлы, если его просто попросили посмотреть/прочитать/объяснить.
Защита от циклов: Детектор бесконечных циклов (file read loop, search loop).
Защита от саморекурсии: Исключение LLM из интерактивного режима.
Предупреждение о перезаписи: Агент предупреждает при попытке перезаписать существующий файл.

📦 Быстрый старт

1. Требования

Node.js v18 или выше
Установленный Git в рабочей директории
(опционально) LM Studio, Anthropic API key или другой провайдер LLM

2. Установка

npm install

3. Настройка окружения

Создайте .env файл или экспортируйте переменные:

Вариант A: LM Studio (локальная модель)

export PROVIDER_URL="http://192.168.0.156:1234/v1"
export MODEL_NAME="qwen/qwen3.5-9b"

Вариант B: OpenRouter (облачные модели)

# Создайте providers.json или используйте \provider в TUI

Вариант C: Anthropic (Claude)

export API_KEY="sk-..."
export MODEL_NAME="claude-sonnet-4-20250514"


### 4. Запуск
```bash
# Компиляция и запуск интерактивного TUI
npx tsc && node dist/agent.js

# Или через npm-скрипт
npm run tui

5. Команды TUI

\provider — переключить провайдер/модель
\test — запуск тестов
\steps — показать шаги текущей сессии
\expand N — развернуть шаг N
@filename — прикрепить файл к сообщению (TAB для автодополнения)

🧪 Тестирование

# Юнит-тесты (библиотека)
npm test

# TUI-тесты (интеграционные)
npm run test:tui

# Все тесты
npm run test:all

# Конкретный тест
node --test dist/test/rlm.test.js

Структура тестов:

test/lib.test.ts — Юнит-тесты инструментов (list_directory, read_file_content, write_file_content)
test/rlm.test.ts — Тесты RLM-цикла (35 тестов, включая loop detection, классификаторы)
test/tui.test.ts — TUI-тесты (25 кейсов, 5 категорий: CHAT/READ/WRITE/MULTI/EDGE)

📊 Бенчмарк

Запуск оценки производительности на наборе задач:

# Полный бенчмарк
npm run bench

# По категории
npm run bench:unit
npm run bench:category -- terminal
npm run bench:category -- research

# Отдельная задача
npm run bench:task -- T-001

Категории задач:

terminal — Файловые операции (Terminal-Bench style)
tool_use — Использование инструментов (Tau-Bench style)
research — Многошаговое исследование (GAIA style)
planning — Планирование и декомпозиция
rlm — Рекурсивные вызовы LLM

Сложность:

easy — простые задачи (вес 1)
medium — средние (вес 2)
hard — сложные (вес 3)
expert — экспертные (вес 5)

🏗️ Структура проекта

tiny-agent/
├── agent.ts              # Точка входа: TUI, @filename autocomplete, провайдеры
├── lib.ts                # Barrel re-export (обратная совместимость)
├── types.ts              # Общие типы (Message, ToolCallRecord, ReActState)
├── src/
│   ├── rlm.ts            # RLM executor: multi-action, loop detection, classifiers
│   ├── tools.ts          # Реализация всех инструментов
│   ├── llm.ts            # LLM клиент: queryLLM, классификаторы, профили
│   ├── prompt.ts         # Системные промпты (BENCH_SYSTEM_PROMPT)
│   ├── parser.ts         # Парсер Action: toolName[{...}]
│   ├── config.ts         # Конфигурация: .env, провайдеры, значения по умолчанию
│   ├── provider.ts       # Управление провайдерами (add/list/use/remove)
│   ├── search.ts         # Поиск: Wikipedia API, перевод RU→EN
│   ├── html.ts           # HTML → text extraction, DuckDuckGo parser
│   ├── mcp-client.ts     # MCP (Model Context Protocol) stdio клиент
│   ├── task-decomposer.ts # Декомпозиция задач на подзадачи
│   ├── with-subagent.ts  # Валидация результатов через субагента
│   └── format-specs.ts   # Динамические спецификации форматов файлов
├── bench/
│   ├── runner.ts         # Benchmark runner: подготовка, выполнение, оценка
│   ├── types.ts          # Типы бенчмарка (Task, EvalContext, BenchmarkReport)
│   └── tasks/            # Набор задач по категориям
├── test/
│   ├── lib.test.ts       # Юнит-тесты инструментов
│   ├── rlm.test.ts       # Тесты RLM-цикла
│   ├── tui.test.ts       # TUI интеграционные тесты
│   └── tui-cases.ts      # TUI тест-кейсы
├── package.json
└── tsconfig.json

🔧 Конфигурация

Переменные окружения (.env)

| Переменная | По умолчанию | Описание | |---|---|---| | PROVIDER_URL | http://localhost:1234/v1 | URL провайдера LLM | | MODEL_NAME | qwen/qwen3.5-9b | Модель по умолчанию | | API_KEY | — | API ключ (если требуется) | | MAX_STEPS | 50 | Максимум шагов за задачу | | RETRIES | 3 | Повторы при ошибке LLM | | TEMPERATURE | 0.7 | Температура генерации |

Провайдеры (providers.json)

Можно сохранять конфигурации провайдеров:

[
  { "name": "lm-studio", "url": "http://192.168.0.156:1234/v1", "model": "qwen/qwen3.5-9b" },
  { "name": "openrouter", "url": "https://openrouter.ai/api/v1", "model": "google/gemini-2.0-flash-001", "apiKey": "sk-or-..." }
]

📝 Пример сессии

╔══════════════════════════════════════════╗
║  🤖 tiny-agent v0.1.1                   ║
║  Model: qwen/qwen3.5-9b                 ║
╚══════════════════════════════════════════╝

> Прочитай README.md и расскажи о структуре

[1/50] 256k/128k  ▸ assistant
  📎 README.md

Структура проекта tiny-agent:
- agent.ts — точка входа с TUI...
- src/rlm.ts — RLM executor...

🏆 Результаты бенчмарка

| Версия | Модель | Результат | |---|---|---| | v21 | qwen3.5-9b | 87.5% (21/24) |

📄 Лицензия

ISC