klp3-code/README.md

🚀 Advanced AI Assistant - Умный AI-помощник с красивым интерфейсом, встроенным Groq AI, системой плагинов

# 🚀 Klp3 AI - Advanced AI Assistant

<div align="center">

![Klp3 Logo](https://img.shields.io/badge/Klp3-v3.0.0-8B5DFF?style=for-the-badge&logo=artificial-intelligence)
[![NPM](https://img.shields.io/npm/v/klp3-code?style=for-the-badge&color=success)](https://npmjs.com/package/klp3-code)
[![Python](https://img.shields.io/badge/Python-3.8+-blue?style=for-the-badge&logo=python)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)

**🤖 Умный AI-ассистент с встроенным бесплатным Groq AI**

**🌙 Красивый темно-фиолетовый интерфейс с анимациями**

**🔌 Расширяемая система плагинов**

[⚡ Быстрая установка](#-установка) • [📖 Использование](#-использование) • [🔌 Плагины](#-плагины) • [🛠️ Разработка](#-разработка-плагинов)

</div>

---


## ✨ Что такое Klp3?

**Klp3** — это продвинутый AI-ассистент для командной строки, который работает **"из коробки"** без необходимости настройки API ключей. Встроенный **бесплатный Groq AI** (Mixtral 8x7B) обеспечивает быстрые и качественные ответы.

### 🎯 Основные особенности

- 🆓 **Бесплатный AI** — встроенный Groq Mixtral, никаких API ключей не нужно
- ⚡ **Сверхбыстрая работа** — асинхронная архитектура и оптимизированные запросы  
- 🌙 **Красивый интерфейс** — темно-фиолетовая тема с анимациями как у Claude Code
- 🎨 **Генерация кода** — Python, JavaScript, HTML, CSS и другие языки
- 🔌 **Система плагинов** — легко расширяется пользовательскими плагинами
- 📊 **Умная статистика** — отслеживание токенов и производительности
- 🔄 **Автообновления** — автоматическая проверка и установка обновлений
- 💾 **Сохранение сессий** — история разговоров сохраняется автоматически

---


## ⚡ Установка

### Через NPM (Рекомендуется)

```bash
# Глобальная установка
npm install -g klp3-code

# Запуск
klp3
```

### Требования

- **Python 3.8+** - [Скачать Python](https://python.org/downloads/)
- **Node.js 14+** - [Скачать Node.js](https://nodejs.org/)

Klp3 автоматически установит необходимые Python зависимости при первом запуске.

---


## 📖 Использование

### Запуск

```bash
klp3
```

При первом запуске Klp3:
1. 🔍 Проверит наличие обновлений
2. 📦 Установит Python зависимости (если нужно)
3. 📁 Создаст системные папки в `~/.klp3/`
4. 🚀 Запустится с красивым экраном приветствия

### Основные команды

| Команда | Описание |
|---------|----------|
| `/help` | Показать справку |
| `/stats` | Статистика использования |
| `/plugins` | Управление плагинами |
| `/clear` | Очистить экран |
| `/reset` | Очистить историю чата |
| `/update` | Проверить обновления |
| `/exit` | Выйти из приложения |

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

#### 💬 Обычное общение
```
💬 Вы: Расскажи о квантовых компьютерах
🤖 Klp3 AI: Квантовые компьютеры — это вычислительные устройства...
```

#### 🎨 Генерация кода
```
💬 Вы: Создай Python функцию для сортировки списка
🤖 Klp3 AI: 
```python
def sort_list(data, reverse=False):
    """
    Сортировка списка
    
    Args:
        data: Список для сортировки
        reverse: Обратная сортировка (по умолчанию False)
    
    Returns:
        list: Отсортированный список
    """
    return sorted(data, reverse=reverse)

# Пример использования
numbers = [3, 1, 4, 1, 5, 9, 2, 6]
sorted_numbers = sort_list(numbers)
print(sorted_numbers)  # [1, 1, 2, 3, 4, 5, 6, 9]
```
```

#### 🔌 Использование плагинов
```
💬 Вы: /ls
🔌 FileManager: 📁 Содержимое текущей папки:
📁 documents
📁 downloads  
📄 readme.txt (1.2 KB)

💬 Вы: /system
🔌 SystemInfo: 🖥️ Система: Windows 11
🏗️ Архитектура: AMD64
💻 Процессор: Intel Core i7
🐍 Python: 3.11.5
```

---


## 🔌 Плагины

Klp3 поставляется с встроенными плагинами и поддерживает пользовательские расширения.

### Встроенные плагины

#### 📁 FileManager
- `/ls [path]` - Список файлов и папок
- `/cat <file>` - Просмотр содержимого файла
- `/mkdir <dir>` - Создание папки
- `/pwd` - Текущая папка

#### 🖥️ SystemInfo  
- `/system` - Информация о системе
- `/memory` - Использование памяти
- `/disk` - Использование диска
- `/python` - Информация о Python

### Управление плагинами

```bash
# Список всех плагинов
/plugins list

# Включить плагин
/plugins enable FileManager

# Выключить плагин  
/plugins disable SystemInfo

# Перезагрузить плагины
/plugins reload
```

### Создание собственных плагинов

1. **Скопируйте шаблон:**
   ```bash
   cp ~/.klp3/templates/plugin_template.py ~/.klp3/plugins/my_plugin.py
   ```

2. **Отредактируйте плагин:**
   ```python
   class MyPlugin(BasePlugin):
       def get_name(self) -> str:
           return "MyPlugin"
       
       def can_handle(self, command: str) -> bool:
           return command.startswith("/my_command")
       
       async def handle_command(self, command: str, context=None):
           return {"success": True, "result": "Привет из плагина!"}
   
   plugin = MyPlugin()
   ```

3. **Перезагрузите плагины:**
   ```bash
   /plugins reload
   /plugins enable MyPlugin
   ```

---


## 📁 Структура системных папок

Klp3 создает папки в домашней директории:

```
~/.klp3/                    # Главная папка
├── plugins/                # Пользовательские плагины
│   ├── plugin_template.py  # Шаблон для создания плагинов
│   └── my_plugin.py        # Ваши плагины
├── data/                   # Сессии и данные
├── cache/                  # Кэш системы
└── config.json            # Пользовательские настройки
```

---


## 🛠️ Разработка плагинов

### Базовая структура плагина

```python
from core.plugins import BasePlugin

class MyPlugin(BasePlugin):
    def get_name(self) -> str:
        return "MyPlugin"
    
    def get_description(self) -> str:
        return "Описание плагина"
    
    def get_version(self) -> str:
        return "1.0.0"
    
    def get_commands(self) -> List[str]:
        return ["/my_command - Описание команды"]
    
    async def initialize(self) -> bool:
        # Инициализация плагина
        return True
    
    async def cleanup(self):
        # Очистка ресурсов
        pass
    
    def can_handle(self, command: str) -> bool:
        return command.startswith("/my_command")
    
    async def handle_command(self, command: str, context=None):
        return {
            "success": True,
            "result": "Результат выполнения команды"
        }

# Обязательно: экспорт плагина
plugin = MyPlugin()
```

### API для плагинов

#### Возвращаемые значения

Метод `handle_command()` должен возвращать словарь:

```python
# Успешное выполнение
{
    "success": True,
    "result": "Текст для показа пользователю"
}

# Ошибка
{
    "success": False, 
    "error": "Описание ошибки"
}
```

#### Контекст выполнения

Параметр `context` может содержать:
- `user_input` - исходный ввод пользователя
- `session` - информация о сессии
- Другие данные от системы

### Советы по разработке

- 🔒 **Безопасность** - проверяйте входные данные, не используйте `eval()`
- ⚡ **Производительность** - делайте долгие операции асинхронными
- 🎨 **UX** - используйте понятные сообщения и эмодзи
- 🧪 **Тестирование** - проверяйте edge cases
- 📝 **Документация** - описывайте команды в `get_commands()`

---


## ⚙️ Конфигурация

### Настройки пользователя

Файл `~/.klp3/config.json`:

```json
{
  "ui": {
    "animations": true,
    "typing_effect": true,
    "auto_save_sessions": true
  },
  "system": {
    "check_updates": true,
    "max_history": 50,
    "auto_load_plugins": true
  },
  "plugins": {
    "auto_install_examples": true,
    "safety_check": true,
    "max_plugins": 10
  }
}
```

### Переменные окружения

Klp3 не требует настройки переменных окружения - все работает "из коробки".

---


## 🔄 Обновления

Klp3 автоматически проверяет обновления при запуске (не чаще раза в день).

### Ручная проверка обновлений

```bash
# В приложении
/update

# Или через npm
npm update -g klp3-code
```

### Что включают обновления

- 🐛 Исправления ошибок
- ✨ Новые функции
- 🔌 Улучшения системы плагинов
- 🎨 Улучшения интерфейса
- ⚡ Оптимизация производительности

---


## 📊 Статистика

Klp3 отслеживает использование и показывает статистику:

```
📊 Статистика использования
┌─────────────────────┬──────────────────┐
│ Метрика             │ Значение         │
├─────────────────────┼──────────────────┤
│ 🤖 AI Модель        │ mixtral-8x7b-32768│
│ 🆓 Провайдер        │ Groq (Free)      │
│ 📊 Токены (сессия)  │ 1,247            │
│ 📈 Токены (всего)   │ 5,892            │
│ 🔄 Запросов         │ 23               │
│ 💬 Сообщений        │ 46               │
│ ⏱️ Время сессии     │ 15м 32с          │
└─────────────────────┴──────────────────┘
```

---


## ❓ FAQ

### Нужны ли API ключи?

**Нет!** Klp3 использует встроенный бесплатный Groq AI. Никакой регистрации или ключей не требуется.

### Работает ли офлайн?

Klp3 требует интернет-соединения для запросов к AI, но система плагинов и интерфейс работают локально.

### Безопасно ли это?

Да! Klp3 не отправляет личные данные. История разговоров хранится только локально в `~/.klp3/data/`.

### Можно ли использовать другие AI модели?

В текущей версии встроен только Groq AI для простоты использования. Поддержка других провайдеров планируется в будущих версиях.

### Как удалить Klp3?

```bash
# Удалить приложение
npm uninstall -g klp3-code

# Удалить данные (опционально)
rm -rf ~/.klp3
```

---


## 🐛 Сообщение об ошибках

Нашли ошибку? Создайте issue на GitHub:

1. Опишите проблему
2. Укажите версию (`klp3 --version`)
3. Приложите логи из `~/.klp3/cache/`

[🔗 Создать issue](https://github.com/kilopa-ai/klp3-code/issues)

---


## 🤝 Вклад в проект

Мы приветствуем вклад в развитие Klp3! 

### Способы помочь

- 🐛 Сообщать об ошибках
- 💡 Предлагать новые функции  
- 🔌 Создавать плагины
- 📖 Улучшать документацию
- ⭐ Ставить звездочки на GitHub

### Для разработчиков

```bash
# Клонировать репозиторий
git clone https://github.com/kilopa-ai/klp3-code.git
cd klp3-code

# Установить зависимости
pip install -r requirements.txt

# Запустить в режиме разработки
python main.py
```

---


## 📄 Лицензия

MIT License. Смотрите [LICENSE](LICENSE) для подробностей.

---


## 🙏 Благодарности

- **[Groq](https://groq.com/)** за бесплатный доступ к Mixtral AI
- **[Rich](https://github.com/Textualize/rich)** за красивый терминальный интерфейс
- **[Claude](https://claude.ai/)** за вдохновение дизайна
- Всем контрибьюторам и пользователям! ❤️

---


<div align="center">

**Создано с ❤️ командой KilopaAI**

[🌟 GitHub](https://github.com/kilopa-ai/klp3-code) • [📦 NPM](https://npmjs.com/package/klp3-code) • [💬 Поддержка](mailto:support@kilopa.ai)

</div>