Skip to content

README_RU.md

Latest commit

 

History

History
502 lines (366 loc) · 21.7 KB

README_RU.md

File metadata and controls

502 lines (366 loc) · 21.7 KB

🧪 ProjectEvolve

Автономная система исследования и улучшения проектов с помощью AI

🇬🇧 English Documentation → README.md


Python Platform License Claude

💡 Философия

"Give an AI agent a real project and let it experiment autonomously." — Inspired by karpathy/autoresearch

Отличие от оригинала

Оригинальный karpathy/autoresearch — AI агент исследует обучение нейросетей (nanochat), модифицируя только train.py с одной метрикой val_bpb.

ProjectEvolve — расширяет эту идею на любой проект:

  • Любой язык программирования (Python, JavaScript, Go, Rust, ...)
  • Любые типы задач (backend, frontend, DevOps, документация, ...)
  • Любые файлы и директории (полная свобода действий)
  • Кроссплатформенность (Windows, Linux, macOS)
  • Накопление знаний между запусками

Ключевое наследство: агент работает autonomously, итеративно улучшает проект, сохраняет успешные изменения, отбрасывает неудачные.

📖 Описание

ProjectEvolve — это универсальный инструмент для запуска AI-агента на любом проекте. Агент autonomously анализирует код, предлагает улучшения, вносит изменения и учитывает результаты предыдущих экспериментов.

Что делает ProjectEvolve?

  1. Анализирует — изучает структуру, код, документацию проекта
  2. Предлагает — генерирует идеи для улучшений
  3. Внедряет — вносит изменения в код/структуру/документацию
  4. Тестирует — проверяет, что ничего не сломалось
  5. Накапливает — следующая итерация видит результаты предыдущей
  6. Повторяет — цикл продолжается autonomously

🎯 Зачем это нужно?

  • 🔄 Автономные эксперименты — AI самостоятельно анализирует, предлагает и внедряет улучшения
  • 📚 Накопление знаний — каждая итерация видит результаты предыдущих, создавая базу знаний проекта
  • ⚡ Универсальность — работает с Python, JavaScript, Go, Rust и любыми другими технологиями
  • 🎨 Гибкая настройка — простой опросник адаптирует под ваш проект
  • 🌐 Кроссплатформенность — Windows, Linux, macOS
  • 🔧 Нулевое обслуживание — агент всё делает сам

💡 Как это работает?

┌─────────────────┐      ┌──────────────┐      ┌─────────────┐
│  Ваш проект     │─────▶│ ProjectEvolve│─────▶│  AI Агент   │
│  (любой язык)   │      │  (скрипт)    │      │  (Claude)   │
└─────────────────┘      └──────────────┘      └─────────────┘
                                │                      │
                                ▼                      ▼
                        ┌──────────────┐      ┌─────────────┐
                        │ Конфигурация │      │ Эксперимент │
                        │ .autoresearch│      │ #1, #2, #3  │
                        └──────────────┘      └─────────────�
                                │                      │
                                ▼                      ▼
                        ┌──────────────┐      ┌─────────────┐
                        │  Улучшения   │◀─────│  Контекст   │
                        │  кода/доков   │      │  накапливает│
                        └──────────────┘      └─────────────┘

🎨 Возможности

✨ Что может ProjectEvolve?

  • 🔍 Анализировать — изучает структуру проекта, код, документацию
  • 💡 Предлагать — генерирует идеи для улучшений
  • 🔨 Внедрять — вносит изменения в код, структуру, документацию
  • 🧪 Quality Loop — встроенная система самотестирования с количественными метриками
  • 📊 Оценивать — автоматический скоринг (0.0-1.0) с pass/fail решениями
  • 📝 Документировать — обновляет README, создаёт новую документацию
  • 🔄 Итерировать — каждая следующая итерация учитывает предыдущие

🌐 Кроссплатформенность

Платформа Поддержка Установка
Windows ✅ Полная autoresearch.bat
Linux ✅ Полная python autoresearch.py
macOS ✅ Полная python autoresearch.py

🔧 Технологии

  • Python 3.10+
  • Claude CLI (Anthropic)
  • Git (опционально)

🔄 Quality Loop

ProjectEvolve включает встроенную систему самотестирования, вдохновлённую quality gates:

Как работает Quality Loop

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   Generate   │─────▶│    Apply     │─────▶│   Evaluate   │
│   (Идея)     │      │  (Изменения) │      │   (Скоринг)  │
└──────────────┘      └──────────────┘      └──────┬───────┘
                                                    │
                                                    ▼
                                             ┌──────────────┐
                                             │   Decision   │
                                             │ СОХРАНИТЬ/   │
                                             │ ОТБРОСИТЬ    │
                                             └──────────────┘
                                                    │
                              ┌─────────────────────┘
                              │ (если сохранено)
                              ▼
                      ┌──────────────┐
                      │ След. итер.  │
                      └──────────────┘

Возможности Quality Gate

  • Универсальность — работает с Python, JavaScript, Go, Rust, Ruby, Java, любым языком
  • Автодетект — автоматически находит команды для тестов (npm test, pytest, cargo test, и т.д.)
  • Количественные метрики — скоринг 0.0-1.0 с pass/fail решениями
  • Две фазы — Phase A (базовое качество, порог 70%) → Phase B (строгое качество, порог 85%)
  • Автоматически — запускает тесты после каждого эксперимента, решает сохранять или отбросить изменения

Запуск Quality Loop

# Автономная проверка качества
python F:/IdeaProjects/autoresearch/utils/quality_loop.py --project /path/to/project

# Кастомные пороги
python utils/quality_loop.py --project . --threshold-a 0.7 --threshold-b 0.85

# JSON вывод для парсинга
python utils/quality_loop.py --project . --json

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

Конфигурационный файл .autoresearch/quality.yml создаётся автоматически:

metrics:
  tests:
    enabled: true
    command: ""  # Автодетект: npm test, pytest, cargo test, etc.
  build:
    enabled: false
    command: ""  # Автодетект: npm run build, cargo build, etc.

thresholds:
  a:
    min_score: 0.7  # Порог Phase A
    required_checks: ["tests"]
  b:
    min_score: 0.85  # Порог Phase B
    required_checks: ["tests", "build"]

Логика решений

Сохранить изменения если:

  • ✅ Score ≥ baseline + 0.05 (улучшение на 5%+)
  • ✅ Все обязательные проверки пройдены
  • ✅ Нет критических ошибок

Отбросить изменения если:

  • ❌ Score уменьшился
  • ❌ Критические тесты fail
  • ❌ Нарушены ограничения проекта

Ручная проверка если:

  • ⚠️ Score ~ baseline (минимальные изменения)
  • ⚠️ Некоторые некритичные тесты fail

⚠️ Важно: Разрешения Claude Code

ProjectEvolve требует Claude Code с соответствующими разрешениями.

Режим разрешений

  • ✅ "bypass permissions on" — Рекомендуется! Никаких подтверждений не нужно
  • ⚠️ Другие режимы (auto/manual) — Могут требоваться подтверждения во время выполнения
  • ❌ Риск: Агент может зависнуть в ожидании одобрения использования инструментов

Необходимые инструменты

Агенту ProjectEvolve нужны эти инструменты (если не в режиме bypass):

Основные инструменты:

  • Edit — Изменение файлов
  • Read — Чтение содержимого файлов
  • Write — Создание новых файлов
  • Glob — Поиск файлов по шаблону
  • Grep — Поиск по содержимому файлов

Дополнительные инструменты:

  • Bash — Выполнение shell команд (для Quality Loop)
  • Agent — Запуск суб-агентов

Рекомендуемые настройки

Вариант 1: Режим Bypass (Рекомендуется)

{
  "permissionMode": "bypass"
}

Вариант 2: Авто-одобрение безопасных инструментов

{
  "permissionMode": "auto",
  "autoApproveSafeTools": true,
  "alwaysAllowTools": ["Edit", "Read", "Write", "Glob", "Grep"]
}
Режим Поведение Рекомендация
bypass Без prompt'ов, полная автономия ✅ Лучше для ProjectEvolve
auto Авто-одобрение безопасных ⚠️ Pre-approve основных инструментов
manual Prompt на каждый инструмент ❌ Не рекомендуется

Если агент завис во время выполнения:

  1. Проверьте, ожидает ли permission prompt подтверждения
  2. Одобрите требуемый инструмент (Edit, Read, Write и т.д.)
  3. Или переключитесь в режим bypass для полной автономии

Примечание: Все скрипты имеют 30-минутный тайм-аут на эксперимент. Если Claude CLI зависнет (например, на prompt'е разрешения), эксперимент завершится по тайм-ауту и перейдёт к следующему. Проверьте логи на наличие ошибок тайм-аута.

🚀 Быстрый старт

Шаг 1️⃣: Настройка окружения AI агентом

Для AI агента: Прочитайте INSTALL.md и настройте систему:

# AI агент настраивает окружение
# (установка Python, Node.js, Claude CLI, создание директорий)

AI агент выполнит:

  • ✅ Детекция ОС (Windows/Linux/macOS)
  • ✅ Установка недостающих зависимостей
  • ✅ Создание необходимых директорий
  • ✅ Проверка установки

Подробнее: См. INSTALL.md — это инструкция для AI агента по кроссплатформенной настройке.

Шаг 2️⃣: Запуск ProjectEvolve

После настройки окружения запустите скрипт:

# Базовый запуск (10 итераций, интервал 5 минут)
python F:/IdeaProjects/autoresearch/autoresearch.py --project /path/to/project

# С параметрами
python F:/IdeaProjects/autoresearch/autoresearch.py --project . --iter 50 --timeout 2

# Windows (через bat-файл)
F:/IdeaProjects/autoresearch/autoresearch.bat . 50 2

Параметры:

  • --project — путь к вашему проекту
  • --iter — количество итераций (по умолчанию 10)
  • --timeout — интервал между итерациями в минутах (по умолчанию 5)

📂 Структура проекта

autoresearch/
├── autoresearch.py          # Главный скрипт
├── autoresearch.bat         # Windows launcher
├── INSTALL.md               # Инструкция по установке (для AI)
├── README.md                # Английская версия (основная)
├── README_RU.md             # Русская версия (полная)
├── QUICKSTART.md            # Краткая инструкция
├── config/
│   ├── default_prompt.md    # Шаблон промпта для агента
│   └── quality.yml          # Конфигурация quality gate
├── utils/
│   ├── cli_setup.py         # Интерактивная настройка
│   └── quality_loop.py      # Реализация quality loop
└── .gitignore               # Git ignore

Что создаётся в вашем проекте

your-project/
├── .autoresearch/
│   ├── .autoresearch.json        # Конфигурация проекта
│   ├── quality.yml               # Конфигурация quality gate (авто-создаётся)
│   ├── experiments/
│   │   ├── prompt_1.md
│   │   ├── output_1.md
│   │   ├── accumulation_context.md  # Накопленный контекст
│   │   ├── last_experiment.md      # Последний эксперимент
│   │   ├── changes_log.md          # Лог изменений
│   │   └── summary.json            # Итоговая сводка
│   └── logs/
│       └── autoresearch.log         # Логи запуска

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

Первый запуск

========================================================================
   ProjectEvolve - First Time Setup
========================================================================

Проект: /path/to/your-project

Название проекта: My Awesome App
Краткое описание: Web приложение для управления задачами

Цели проекта (по одной на строке):
  > Улучшить производительность
  > Добавить тесты
  > Обновить документацию
  > [Enter]

Ограничения (опционально):
  > Не менять API
  > [Enter]

✓ Конфигурация сохранена!

Файл конфигурации (.autoresearch.json)

{
  "name": "My Awesome App",
  "description": "Web приложение для управления задачами",
  "goals": [
    "Улучшить производительность",
    "Добавить тесты",
    "Обновить документацию"
  ],
  "constraints": [
    "Не менять API"
  ],
  "tech_stack": ["Python", "FastAPI", "PostgreSQL"],
  "focus_areas": ["performance", "testing", "documentation"]
}

📊 Примеры использования

Пример 1: Быстрый тест (краткая форма)

# Краткая форма: 3 эксперимента, 1 минута интервал
python F:/IdeaProjects/autoresearch/autoresearch.py . 3 1

# Полная форма: то же самое
python F:/IdeaProjects/autoresearch/autoresearch.py --project . --iter 3 --timeout 1

Пример 2: Долгий сеанс исследования

# 50 экспериментов, интервал 10 минут
python F:/IdeaProjects/autoresearch/autoresearch.py --project . --iter 50 --timeout 10

Пример 3: Только настройка

# Первичная настройка
python F:/IdeaProjects/autoresearch/autoresearch.py --project /path/to/project --configure

# Позже — запуск
python F:/IdeaProjects/autoresearch/autoresearch.py --project /path/to/project --iter 10

Пример 4: Продолжение с указанного эксперимента

# Продолжить с Experiment 25 (после предыдущей сессии завершившейся на 24)
python F:/IdeaProjects/autoresearch/autoresearch.py --project . --iter 10 --start-from 25

# Это запустит Эксперименты 25-34 (10 экспериментов начиная с 25)
# Агент всё равно увидит накопленный контекст от всех предыдущих экспериментов

Пример 5: Автоопределение следующего номера

# Автоопределяет следующий номер (если output_1.md существует, начнёт с 2)
python F:/IdeaProjects/autoresearch/autoresearch.py . 10 1

# Или без параметра --project (использует текущую директорию)
python F:/IdeaProjects/autoresearch/autoresearch.py 10 1

Автоопределение номера:

  • Скрипт проверяет существующие output_N.md файлы
  • Находит максимальный номер и добавляет 1
  • Если файлов нет — начинается с Experiment 1

🛠️ Устранение проблем

Claude CLI не найден

npm install -g @anthropic-ai/claude-code

Python не найден

Установите Python 3.10+ и добавьте в PATH.

Эксперименты зависают

Увеличьте интервал между итерациями (--timeout).

Неправильный контекст

python F:/IdeaProjects/autoresearch/autoresearch.py --project . --reconfigure

📚 Документация

  • 📖 INSTALL.md — Инструкция по установке (для AI агента)
  • ⚡ QUICKSTART.md — Краткая инструкция
  • 🇬🇧 README.md — Английская версия (основная)

🤝 Участие в разработке

Вклад приветствуется! Создавайте issues и pull requests.

Идеи для улучшения

  • 🌐 Web UI для мониторинга экспериментов
  • 📊 Визуализация прогресса
  • 🔔 Уведомления о завершении
  • 📈 Метрики и аналитика
  • 🔄 Интеграция с CI/CD

📄 Лицензия

MIT License — свободно используйте в любых проектах.

⭐ Звёзды

Если этот проект вам полезен, поставьте звёздочку на GitHub!

Сделано с ❤️ для автономного исследования проектов