# Плагин AI Rewriter — Полное руководство пользователя

## 📝 Содержание

1. [Что такое AI Rewriter](#что-такое-ai-rewriter)
2. [Возможности плагина](#возможности-плагина)
3. [Системные требования](#системные-требования)
4. [Установка и настройка](#установка-и-настройка)
5. [Выбор AI-провайдера](#выбор-ai-провайдера)
6. [Пошаговая настройка для каждого провайдера](#пошаговая-настройка-для-каждого-провайдера)
7. [Как использовать плагин](#как-использовать-плагин)
8. [Настройки рерайта](#настройки-рерайта)
9. [Автоматический рерайт](#автоматический-рерайт)
10. [Устранение неполадок](#устранение-неполадок)
11. [Часто задаваемые вопросы](#часто-задаваемые-вопросы)
12. [Безопасность](#безопасность)
13. [Советы и рекомендации](#советы-и-рекомендации)

---

## Что такое AI Rewriter

**AI Rewriter** — это плагин для системы управления контентом NGCMS, который использует возможности искусственного интеллекта для автоматического рерайта (переписывания) текстов новостей и статей.

### Основное назначение:

- **Повышение уникальности** — создание оригинального контента на основе существующего
- **Экономия времени** — автоматизация процесса переписывания текстов
- **Сохранение смысла** — AI переписывает текст, сохраняя его суть и структуру
- **Гибкость** — поддержка разных AI-провайдеров и моделей

---

## Возможности плагина

### ✨ Основные функции:

1. **Рерайт прямо в редакторе**
   - Кнопка в панели инструментов редактора
   - Мгновенная обработка текста без сохранения
   - Возможность предварительного просмотра результата

2. **Поддержка нескольких AI-провайдеров**
   - OpenAI (ChatGPT)
   - Anthropic (Claude)
   - OpenAI-совместимые API (OpenRouter, Together, LM Studio, Ollama и др.)
   - Возможность использования локальных моделей

3. **Гибкие настройки качества**
   - Настройка процента оригинальности (0-100%)
   - Выбор тональности текста
   - Регулировка креативности (temperature)
   - Настройка таймаутов для медленных соединений

4. **Автоматизация**
   - Автоматический рерайт при добавлении новостей
   - Автоматический рерайт при редактировании
   - Выборочное применение

5. **Сохранение форматирования**
   - Поддержка HTML-разметки
   - Сохранение BBCode
   - Работа с ссылками и специальными символами
   - Сохранение структуры заголовков и абзацев

6. **Безопасность**
   - CSRF-защита всех административных функций
   - Требование авторизации администратора
   - Валидация и санитизация данных
   - Расширенное логирование операций

---

## Системные требования

### Минимальные требования:

- **NGCMS**: версия 0.9.3 или выше
- **PHP**: версия 7.0 или выше
- **ng-helpers**: версия 0.2.2 или выше (для CSRF-защиты)
- **PHP расширение cURL**: должно быть включено
- **Доступ к интернету**: для работы с облачными AI-провайдерами
- **API-ключ**: от выбранного AI-провайдера (кроме локальных решений)

### Рекомендуемые требования:

- PHP 7.4 или выше
- Стабильное интернет-соединение (для облачных API)
- Достаточный баланс на аккаунте AI-провайдера

---

## Установка и настройка

### Шаг 1: Установка плагина

1. Откройте административную панель NGCMS
2. Перейдите в раздел **Плагины**
3. Найдите плагин **ai_rewriter** в списке доступных плагинов
4. Нажмите кнопку **Установить**
5. Дождитесь подтверждения успешной установки

### Шаг 2: Первоначальная настройка

После установки плагин необходимо настроить:

1. В разделе **Плагины** найдите установленный плагин **AI Rewriter**
2. Нажмите на кнопку **Настройки** (значок шестеренки)
3. Откроется страница конфигурации плагина

---

## Выбор AI-провайдера

Плагин поддерживает три основных типа провайдеров:

### 1. **OpenAI (официальный)**

**Особенности:**

- Самые передовые модели (GPT-4, GPT-4o-mini)
- Высокое качество рерайта
- Стабильная работа
- Требует платного API-ключа

**Когда использовать:**

- Нужно максимальное качество
- Есть бюджет на API
- Работаете с важными текстами

**Модели:**

- `gpt-4o-mini` — быстрая и недорогая (рекомендуется для старта)
- `gpt-4o` — более мощная версия
- `gpt-4-turbo` — для сложных текстов
- `gpt-3.5-turbo` — экономичный вариант

### 2. **OpenAI-совместимые API**

**Особенности:**

- Альтернативные провайдеры с более низкими ценами
- Возможность использования локальных моделей
- Больше гибкости в выборе моделей

**Популярные сервисы:**

#### **OpenRouter**

- Доступ к десяткам моделей через один API
- Гибкое ценообразование
- Простая интеграция

#### **Together AI**

- Хорошее соотношение цена/качество
- Быстрые ответы
- Поддержка множества моделей

#### **LM Studio** (локально)

- Бесплатное использование
- Полная конфиденциальность
- Требует мощное железо

#### **Ollama** (локально)

- Простота установки
- Бесплатно
- Работает на вашем сервере

### 3. **Anthropic (Claude)**

**Особенности:**

- Модели Claude известны качественными текстами
- Хорошее понимание контекста
- Безопасность и этичность ответов

**Когда использовать:**

- Нужны длинные контексты
- Важна безопасность контента
- Требуется высокое качество

**Модели:**

- `claude-3-5-sonnet-20240620` — топовая модель (рекомендуется)
- `claude-3-haiku-20240307` — быстрая и экономичная
- `claude-3-opus-20240229` — для самых сложных задач

---

## Пошаговая настройка для каждого провайдера

### Вариант 1: Настройка OpenAI (официальный)

#### 1. Получение API-ключа

1. Перейдите на сайт [platform.openai.com](https://platform.openai.com)
2. Зарегистрируйтесь или войдите в аккаунт
3. Перейдите в раздел [API Keys](https://platform.openai.com/api-keys)
4. Нажмите **Create new secret key**
5. Скопируйте полученный ключ (начинается с `sk-...`)
6. **Важно:** Пополните баланс в разделе Billing

#### 2. Настройка в плагине

```
Провайдер ИИ: OpenAI / OpenAI-совместимые
Модель: gpt-4o-mini
API ключ: sk-ваш_ключ_здесь
API Base: [оставьте пустым]
Процент оригинальности: 60
Тональность: нейтральный
Temperature: 0.7
Таймаут запроса (сек): 20
```

#### 3. Проверка

После сохранения настроек откройте любую новость на редактирование и попробуйте использовать кнопку рерайта.

---

### Вариант 2: Настройка OpenRouter

#### 1. Регистрация и получение ключа

1. Перейдите на [openrouter.ai](https://openrouter.ai)
2. Зарегистрируйтесь через GitHub или email
3. Перейдите в [Keys](https://openrouter.ai/keys)
4. Создайте новый API-ключ
5. Пополните баланс ($5-10 для начала)

#### 2. Выбор модели

На OpenRouter доступны сотни моделей. Рекомендуемые:

- `meta-llama/llama-3.2-3b-instruct:free` — бесплатная
- `google/gemini-flash-1.5` — быстрая и недорогая
- `anthropic/claude-3.5-sonnet` — высокое качество
- `openai/gpt-4o-mini` — проверенное качество

Полный каталог: [openrouter.ai/models](https://openrouter.ai/models)

#### 3. Настройка в плагине

```
Провайдер ИИ: Совместимый (кастомный API Base)
Модель: meta-llama/llama-3.2-3b-instruct:free
API ключ: sk-or-v1-ваш_ключ
API Base: https://openrouter.ai/api/v1
Процент оригинальности: 60
Тональность: информационный
Temperature: 0.7
Таймаут запроса (сек): 30
```

---

### Вариант 3: Настройка Together AI

#### 1. Получение ключа

1. Зарегистрируйтесь на [together.ai](https://www.together.ai)
2. Перейдите в [Settings → API Keys](https://api.together.xyz/settings/api-keys)
3. Создайте новый ключ
4. Пополните баланс

#### 2. Настройка в плагине

```
Провайдер ИИ: Совместимый (кастомный API Base)
Модель: meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo
API ключ: ваш_ключ_together
API Base: https://api.together.xyz/v1
Процент оригинальности: 70
Тональность: нейтральный
Temperature: 0.7
Таймаут запроса (сек): 25
```

---

### Вариант 4: Настройка LM Studio (локально)

#### 1. Установка LM Studio

1. Скачайте [LM Studio](https://lmstudio.ai/) для вашей ОС
2. Установите и запустите программу
3. Скачайте модель (рекомендуется: Llama 3 или Mistral)
4. Загрузите модель в LM Studio

#### 2. Запуск локального сервера

1. В LM Studio перейдите на вкладку **Local Server**
2. Выберите загруженную модель
3. Нажмите **Start Server**
4. Убедитесь, что сервер запущен на `http://127.0.0.1:1234`

#### 3. Настройка в плагине

```
Провайдер ИИ: Совместимый (кастомный API Base)
Модель: llama-3-8b-instruct (точное имя из LM Studio)
API ключ: [оставьте пустым]
API Base: http://127.0.0.1:1234/v1
Процент оригинальности: 60
Тональность: нейтральный
Temperature: 0.7
Таймаут запроса (сек): 60
```

**Важно:**

- LM Studio должен быть запущен при использовании плагина
- Требуется мощный компьютер (желательно с GPU)
- Обработка займет больше времени, чем облачные API

---

### Вариант 5: Настройка Ollama (локально)

#### 1. Установка Ollama

**Windows:**

```bash
# Скачайте установщик с ollama.ai
```

**Linux:**

```bash
curl -fsSL https://ollama.ai/install.sh | sh
```

#### 2. Установка модели

```bash
ollama pull llama3
# или
ollama pull mistral
```

#### 3. Проверка работы

```bash
ollama list  # Проверить установленные модели
ollama serve # Запустить сервер (если не запущен автоматически)
```

#### 4. Настройка в плагине

```
Провайдер ИИ: Совместимый (кастомный API Base)
Модель: llama3
API ключ: [оставьте пустым]
API Base: http://127.0.0.1:11434/v1
Процент оригинальности: 65
Тональность: нейтральный
Temperature: 0.7
Таймаут запроса (сек): 90
```

---

### Вариант 6: Настройка Anthropic (Claude)

#### 1. Получение API-ключа

1. Перейдите на [console.anthropic.com](https://console.anthropic.com)
2. Зарегистрируйтесь
3. Перейдите в [Settings → API Keys](https://console.anthropic.com/settings/keys)
4. Создайте новый ключ
5. Пополните баланс

#### 2. Настройка в плагине

```
Провайдер ИИ: Anthropic (Claude)
Модель: claude-3-5-sonnet-20240620
API ключ: sk-ant-ваш_ключ
API Base: [не используется для Anthropic]
Процент оригинальности: 70
Тональность: информационный
Temperature: 0.7
Таймаут запроса (сек): 25
```

---

## Как использовать плагин

### Метод 1: Ручной рерайт через кнопку в редакторе

Это основной и наиболее контролируемый способ использования плагина.

#### Пошаговая инструкция:

1. **Откройте редактор**
   - Перейдите в **Админка → Новости**
   - Нажмите **Добавить новость** или откройте существующую на редактирование

2. **Введите или вставьте текст**
   - Напишите или вставьте текст, который нужно переписать
   - Можно использовать как полный текст, так и отдельные части

3. **Найдите кнопку рерайта**
   - В панели инструментов редактора найдите кнопку с иконкой "волшебной палочки" 🪄
   - Обычно она находится в верхней панели инструментов

4. **Запустите рерайт**
   - Нажмите на кнопку рерайта
   - Появится индикатор загрузки
   - Дождитесь завершения обработки (обычно 5-30 секунд)

5. **Проверьте результат**
   - Текст в редакторе автоматически заменится на переписанную версию
   - **Важно:** Новость НЕ сохраняется автоматически
   - Внимательно прочитайте новый текст

6. **Внесите корректировки**
   - При необходимости отредактируйте текст вручную
   - Можно запустить рерайт повторно для другого варианта

7. **Сохраните новость**
   - Нажмите обычную кнопку **Сохранить** или **Опубликовать**
   - Теперь переписанный текст сохранен

#### Преимущества ручного режима:

- ✅ Полный контроль над процессом
- ✅ Возможность предварительного просмотра
- ✅ Можно отменить и вернуться к оригиналу
- ✅ Возможность многократного рерайта до получения нужного результата

---

### Метод 2: Автоматический рерайт при сохранении

Плагин может автоматически переписывать текст при добавлении или редактировании новостей.

#### Настройка автоматического режима:

1. Откройте **Настройки плагина AI Rewriter**
2. Найдите раздел **Автоприменение**
3. Включите нужные опции:

```
Рерайт при добавлении: Да
Рерайт при редактировании: Нет  (или Да, если нужно)
```

#### Как это работает:

**При добавлении новости:**

1. Вы пишете текст новости
2. Заполняете все поля (заголовок, категория и т.д.)
3. Нажимаете **Сохранить**
4. Плагин автоматически переписывает текст перед сохранением
5. В базу данных попадает уже переписанный вариант

**При редактировании новости:**

1. Вы открываете существующую новость
2. Вносите изменения в текст
3. Нажимаете **Сохранить**
4. Плагин переписывает обновленный текст
5. Сохраняется переписанная версия

#### ⚠️ Важные моменты автоматического режима:

- **Нет предварительного просмотра** — текст переписывается сразу
- **Нельзя отменить** — оригинал не сохраняется
- **Увеличивает время сохранения** — ожидание ответа от AI
- **Расходует API-запросы** — каждое сохранение = 1 запрос

#### Когда использовать автоматический режим:

✅ **Рекомендуется для:**

- Массового импорта новостей
- Автоматизированных процессов
- Когда вы полностью доверяете качеству AI
- При использовании RSS-лент или парсеров

❌ **НЕ рекомендуется для:**

- Важных текстов, требующих проверки
- Первого тестирования плагина
- Редактирования уже опубликованных новостей
- Когда нужен контроль над результатом

---

## Настройки рерайта

Детальное объяснение каждого параметра настройки.

### 1. Процент оригинальности (0-100)

**Что это:**
Целевой уровень уникальности переписанного текста.

**Диапазон:** 0-100
**По умолчанию:** 60

#### Рекомендации по выбору:

- **30-40%** — Минимальные изменения
  - Текст остается максимально близким к оригиналу
  - Меняются только отдельные слова и фразы
  - Подходит для технических текстов

- **50-70%** — Средняя переработка (рекомендуется)
  - Оптимальный баланс между уникальностью и сохранением смысла
  - Заметные изменения в формулировках
  - Подходит для большинства новостей

- **80-100%** — Глубокая переработка
  - Максимальная уникальность
  - Может изменить структуру текста
  - Риск потери части информации
  - Подходит для творческих текстов

**Пример:**

Исходный текст:

```
Сегодня состоялась презентация нового смартфона компании XYZ.
Устройство получило улучшенную камеру и процессор последнего поколения.
```

При 40% оригинальности:

```
Сегодня прошла презентация нового телефона от XYZ.
Аппарат оснащен улучшенной камерой и современным процессором.
```

При 80% оригинальности:

```
Компания XYZ представила публике свой новейший смартфон.
Главными особенностями гаджета стали передовая система камер и чип нового поколения.
```

---

### 2. Тональность

**Что это:**
Стиль и манера изложения переписанного текста.

**Варианты:**

#### **Нейтральный** (по умолчанию)

- Объективное изложение фактов
- Без эмоциональной окраски
- Подходит для новостей и официальных текстов

**Пример:**

```
Компания объявила о выпуске нового продукта.
Устройство поступит в продажу в следующем месяце.
```

#### **Информационный**

- Четкое и структурированное изложение
- Фокус на фактах и деталях
- Подходит для аналитических материалов

**Пример:**

```
Производитель сообщил о запуске нового продукта.
Согласно пресс-релизу, старт продаж запланирован на следующий месяц.
```

#### **Дружелюбный**

- Более легкий и непринужденный стиль
- Ближе к разговорной речи
- Подходит для блогов и развлекательного контента

**Пример:**

```
Отличные новости! Компания готовит к выпуску свой новый продукт.
Совсем скоро, уже в следующем месяце, вы сможете его приобрести.
```

#### **Профессиональный**

- Деловой стиль
- Использование специальной терминологии
- Подходит для B2B контента

#### **Как указать:**

```
Тональность: нейтральный
# или
Тональность: информационный, деловой
```

---

### 3. Temperature (Температура) — 0.0 до 1.0

**Что это:**
Параметр, контролирующий "креативность" и вариативность ответов AI.

**Диапазон:** 0.0 - 1.0
**По умолчанию:** 0.7

#### Как работает:

**0.0 - 0.3** — Детерминированный режим

- Всегда выбирается наиболее вероятный вариант
- Предсказуемые и последовательные результаты
- Минимум креативности

**Когда использовать:**

- Технические тексты
- Инструкции
- Когда важна точность

**0.4 - 0.7** — Сбалансированный режим (рекомендуется)

- Хороший баланс между предсказуемостью и разнообразием
- Достаточно креативно, но сохраняет логику
- Универсальный вариант

**Когда использовать:**

- Новости
- Статьи
- Большинство текстов

**0.8 - 1.0** — Креативный режим

- Максимальное разнообразие вариантов
- Неожиданные формулировки
- Может быть менее предсказуемым

**Когда использовать:**

- Творческие тексты
- Эксперименты
- Когда нужны необычные формулировки

#### Практический пример:

Исходная фраза: "Погода сегодня солнечная"

При temperature = 0.2:

```
Сегодня солнечная погода
```

При temperature = 0.7:

```
День выдался солнечным
```

При temperature = 0.9:

```
Небо озарено ярким солнцем
```

---

### 4. Таймаут запроса (секунды)

**Что это:**
Максимальное время ожидания ответа от AI-провайдера.

**Диапазон:** 5-120 секунд
**По умолчанию:** 20 секунд

#### Рекомендации:

**15-25 секунд** — Стандартный режим

- Для быстрых облачных API (OpenAI, Anthropic)
- Стабильное интернет-соединение
- Короткие и средние тексты

**30-60 секунд** — Увеличенный таймаут

- Для медленных соединений
- Длинные тексты (более 2000 слов)
- Альтернативные провайдеры

**60-120 секунд** — Максимальный таймаут

- Локальные модели (LM Studio, Ollama)
- Очень большие тексты
- Слабое железо или медленные модели

#### Что происходит при превышении таймаута:

```
Ошибка: cURL error: Operation timed out
```

**Решение:**

1. Увеличьте таймаут в настройках
2. Проверьте скорость интернета
3. Попробуйте другой провайдер
4. Разбейте текст на части

---

### 5. API Base (для совместимых провайдеров)

**Что это:**
Базовый URL API-сервера для OpenAI-совместимых провайдеров.

#### Важные URL:

```
OpenAI (официальный):
https://api.openai.com/v1

OpenRouter:
https://openrouter.ai/api/v1

Together AI:
https://api.together.xyz/v1

LM Studio (локально):
http://127.0.0.1:1234/v1

Ollama (локально):
http://127.0.0.1:11434/v1
```

**Для Anthropic:** Поле не используется (свой эндпоинт)

---

## Автоматический рерайт

### Настройка автоматического режима

В настройках плагина есть два переключателя:

```
Рерайт при добавлении: Да/Нет
Рерайт при редактировании: Да/Нет
```

### Сценарии использования

#### Сценарий 1: Только для новых новостей

```
Рерайт при добавлении: Да
Рерайт при редактировании: Нет
```

**Подходит для:**

- Импорта контента из внешних источников
- Автоматической обработки RSS-лент
- Создания уникального контента из черновиков

#### Сценарий 2: Для всех операций

```
Рерайт при добавлении: Да
Рерайт при редактировании: Да
```

**Подходит для:**

- Полной автоматизации
- Когда весь контент должен быть переписан
- При использовании агрегаторов новостей

**⚠️ Осторожно:**

- При редактировании ваши изменения будут переписаны AI
- Может создать непредсказуемые результаты

#### Сценарий 3: Только ручной режим (рекомендуется)

```
Рерайт при добавлении: Нет
Рерайт при редактировании: Нет
```

**Подходит для:**

- Максимального контроля
- Важного контента
- Когда нужна проверка результата

---

## Устранение неполадок

### Типичные ошибки и их решение

#### Ошибка 1: "AI ключ не задан"

**Причина:**
API-ключ не указан в настройках плагина.

**Решение:**

1. Откройте настройки плагина
2. Введите корректный API-ключ
3. Сохраните настройки

---

#### Ошибка 2: "You exceeded your current quota"

**Полное сообщение:**

```
You exceeded your current quota, please check your plan and billing details
```

**Причина:**

- Закончился баланс на аккаунте OpenAI
- Не настроен биллинг
- Достигнут лимит бесплатного тарифа

**Решение:**

1. Войдите в [platform.openai.com](https://platform.openai.com)
2. Перейдите в раздел **Billing**
3. Пополните баланс (минимум $5)
4. Убедитесь, что установлен payment method

**Альтернатива:**
Используйте другой провайдер (OpenRouter, Together) с более низкими ценами.

---

#### Ошибка 3: "Провайдер/модель не совпадают"

**Полное сообщение:**

```
AI Rewriter: выбран провайдер Anthropic, но указана модель OpenAI (gpt-4o-mini)
```

**Причина:**
Несоответствие между выбранным провайдером и указанной моделью.

**Решение:**

Для **Anthropic**:

```
Провайдер: Anthropic (Claude)
Модель: claude-3-5-sonnet-20240620
(НЕ gpt-4o-mini!)
```

Для **OpenAI**:

```
Провайдер: OpenAI
Модель: gpt-4o-mini
(НЕ claude-3-5-sonnet!)
```

---

#### Ошибка 4: "cURL error: Operation timed out"

**Причина:**
Запрос к API превысил установленный таймаут.

**Решение:**

1. **Увеличьте таймаут:**

```
Таймаут запроса: 45-60 секунд
```

2. **Проверьте соединение:**

```bash
ping api.openai.com
# Должен быть стабильный ответ
```

3. **Попробуйте другой провайдер:**
   - OpenRouter обычно быстрее OpenAI
   - Together AI хорошая альтернатива

4. **Для локальных моделей:**
   - Увеличьте таймаут до 90-120 секунд
   - Используйте более легкие модели
   - Проверьте нагрузку на систему

---

#### Ошибка 5: "Invalid API key"

**Причина:**
API-ключ неверный или устаревший.

**Решение:**

1. **Проверьте формат ключа:**
   - OpenAI: начинается с `sk-...`
   - Anthropic: начинается с `sk-ant-...`
   - OpenRouter: начинается с `sk-or-v1-...`

2. **Создайте новый ключ:**
   - Удалите старый
   - Создайте новый в панели провайдера
   - Обновите в настройках плагина

3. **Проверьте права ключа:**
   - Ключ должен иметь доступ к Chat Completions API

---

#### Ошибка 6: "Empty response from provider"

**Причина:**
AI вернул пустой ответ.

**Решение:**

1. **Проверьте исходный текст:**
   - Должен быть не пустым
   - Минимум 10-20 слов
   - Без специальных символов, которые могут сломать запрос

2. **Измените параметры:**

```
Temperature: 0.7 (вместо 0.0)
Процент оригинальности: 60
```

3. **Попробуйте другую модель:**
   - Некоторые модели могут отказаться обрабатывать определенный контент

---

#### Ошибка 7: "cURL not available"

**Причина:**
PHP расширение cURL не установлено или отключено.

**Решение:**

**Для Windows (OpenServer/XAMPP):**

1. Откройте `php.ini`
2. Найдите строку: `;extension=curl`
3. Уберите `;` в начале: `extension=curl`
4. Перезапустите веб-сервер

**Для Linux:**

```bash
# Ubuntu/Debian
sudo apt-get install php-curl

# CentOS/RHEL
sudo yum install php-curl

# Перезапуск Apache
sudo service apache2 restart
```

**Проверка:**

```php
<?php
phpinfo();
// Найдите секцию cURL
```

---

#### Ошибка 8: Кнопка рерайта не появляется в редакторе

**Причина:**

- Плагин не установлен корректно
- Отсутствует интеграция с шаблоном редактора

**Решение:**

1. **Проверьте установку плагина:**
   - Админка → Плагины
   - ai_rewriter должен быть в статусе "Установлен"

2. **Переустановите плагин:**
   - Удалите плагин
   - Установите заново

3. **Проверьте кэш:**
   - Очистите кэш браузера (Ctrl+F5)
   - Очистите кэш NGCMS

4. **Проверьте шаблон:**
   - Убедитесь, что используется поддерживаемый шаблон
   - Файл `engine/skins/default/tpl/qt_news.tpl` должен содержать кнопку

---

#### Ошибка 9: Медленная работа

**Симптомы:**

- Запрос выполняется 30-60+ секунд
- Частые таймауты

**Решение:**

1. **Для облачных API:**

```
# Измените провайдера на более быстрый
OpenRouter часто быстрее OpenAI
Together AI - хорошая альтернатива
```

2. **Для локальных моделей:**

```
# Используйте более легкие модели
Ollama: llama3.2:3b вместо llama3:8b
LM Studio: модели с меньшим количеством параметров
```

3. **Оптимизация:**

```
Temperature: 0.5 (ниже = быстрее)
Процент оригинальности: 50-60 (меньше = проще задача)
```

4. **Сократите текст:**
   - Разбейте длинные тексты на части
   - Рерайтите по абзацам

---

### Диагностика проблем

#### Включение детального логирования

Плагин пишет логи в файл: `engine/logs/ai_rewriter.log`

**Как проверить лог:**

1. Откройте файл через FTP или файловый менеджер
2. Найдите последние записи
3. Обратите внимание на строки с `[ERROR]`

**Пример лога:**

```
[2026-02-04 14:23:15] [INFO] OpenAI request: model=gpt-4o-mini, temp=0.7, timeout=20
[2026-02-04 14:23:17] [INFO] HTTP success: code=200, time=1842.23ms, size=1024 bytes
[2026-02-04 14:23:17] [INFO] OpenAI success: length=856 chars
[2026-02-04 14:23:17] [INFO] Rewrite started: provider=openai, length=645 chars
```

**Ошибка в логе:**

```
[2026-02-04 14:25:10] [ERROR] HTTP error: Operation timed out, code=0, time=20000.00ms
[2026-02-04 14:25:10] [ERROR] OpenAI error: cURL error: Operation timed out
```

---

## Часто задаваемые вопросы

### Общие вопросы

**Q: Сколько стоит использование плагина?**

A: Сам плагин бесплатный, но вам нужно оплачивать API выбранного провайдера:

- OpenAI: ~$0.0001-0.001 за запрос (зависит от длины текста)
- Anthropic: аналогичные цены
- OpenRouter: от $0 (бесплатные модели) до $0.001
- Локальные модели (Ollama, LM Studio): полностью бесплатно

**Q: Можно ли рерайтить текст без сохранения?**

A: Да! Это основной режим работы. Кнопка в редакторе только меняет текст в поле, но не сохраняет новость. Вы можете проверить результат и при необходимости запустить рерайт снова.

**Q: Сохраняется ли оригинальный текст?**

A: При использовании кнопки в редакторе — нет, текст заменяется. Если нужно сохранить оригинал, скопируйте его перед рерайтом. В автоматическом режиме оригинал также не сохраняется.

**Q: Можно ли использовать несколько провайдеров одновременно?**

A: Нет, в настройках можно выбрать только одного провайдера. Но вы можете легко переключаться между ними в настройках.

**Q: Работает ли плагин с BBCode?**

A: Да, плагин сохраняет BBCode-теги, как и HTML-разметку.

---

### Технические вопросы

**Q: Какие модели лучше использовать?**

A: Рекомендации:

- **Для качества:** GPT-4, Claude 3.5 Sonnet
- **Для скорости:** GPT-4o-mini, Claude Haiku
- **Для экономии:** OpenRouter free models, Together AI
- **Для приватности:** Ollama, LM Studio (локально)

**Q: Можно ли использовать плагин для других языков кроме русского?**

A: Да, плагин работает с любыми языками, которые поддерживает выбранная AI-модель (практически все основные языки).

**Q: Как плагин определяет язык текста?**

A: AI автоматически определяет язык исходного текста и переписывает на том же языке.

**Q: Влияет ли длина текста на качество рерайта?**

A: Да:

- Короткие тексты (до 500 слов) — лучшее качество
- Средние тексты (500-2000 слов) — хорошее качество
- Длинные тексты (2000+ слов) — может потребоваться ручная проверка

**Q: Можно ли настроить промпт для AI?**

A: В текущей версии промпт встроен в код плагина. Если нужна кастомизация, можно отредактировать файл `ai_rewriter.php` (секция с переменными `$sys` и `$req`).

---

### Вопросы о безопасности

**Q: Безопасно ли отправлять тексты в AI?**

A: Зависит от провайдера:

- **OpenAI, Anthropic:** Данные могут использоваться для обучения (если не отключено)
- **OpenRouter:** Зависит от конкретной модели
- **Локальные модели:** Полностью приватно, данные не покидают ваш сервер

Не рекомендуется отправлять конфиденциальную информацию.

**Q: Защищены ли административные функции?**

A: Да, плагин использует:

- Требование авторизации администратора
- CSRF-защиту через ng-helpers
- Валидацию и санитизацию данных
- Проверку прав доступа

**Q: Где хранится API-ключ?**

A: API-ключ хранится в конфигурационных файлах NGCMS на вашем сервере. Убедитесь, что файлы конфигурации недоступны извне через веб-сервер.

---

### Вопросы о производительности

**Q: Сколько времени занимает рерайт?**

A: Типичное время:

- OpenAI/Anthropic: 5-15 секунд
- OpenRouter: 3-20 секунд (зависит от модели)
- Together AI: 5-15 секунд
- Локальные модели: 30-120 секунд

**Q: Можно ли ускорить работу?**

A: Да:

1. Используйте более быстрые модели (GPT-4o-mini, Claude Haiku)
2. Сократите текст
3. Уменьшите temperature
4. Используйте провайдеры с лучшей инфраструктурой

**Q: Влияет ли рерайт на работу сайта?**

A: Запрос к AI выполняется синхронно, поэтому:

- В ручном режиме — нет влияния (администратор ждет)
- В автоматическом режиме — увеличивает время сохранения новости

---

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

### Что защищено в плагине (версия 0.1.2+)

1. **Административные функции:**
   - Доступ только для авторизованных администраторов
   - RPC-функции требуют авторизации

2. **CSRF-защита:**
   - Все формы настроек защищены от CSRF-атак
   - Использует библиотеку ng-helpers >= 0.2.2

3. **Валидация данных:**
   - Проверка URL API перед запросами
   - Санитизация пользовательских данных
   - Проверка типов и диапазонов параметров

4. **Логирование:**
   - Все операции записываются в лог
   - Уровни логирования: INFO, WARNING, ERROR
   - Файл лога: `engine/logs/ai_rewriter.log`

### Рекомендации по безопасности

1. **Защита API-ключей:**

```
# Убедитесь, что конфиг недоступен извне
# В .htaccess:
<FilesMatch "config\.php$">
    Order allow,deny
    Deny from all
</FilesMatch>
```

2. **Использование HTTPS:**
   - Всегда используйте HTTPS для админ-панели
   - Это защитит API-ключи при передаче

3. **Ограничение доступа:**
   - Используйте сложные пароли администратора
   - Регулярно обновляйте API-ключи
   - Отзывайте неиспользуемые ключи

4. **Конфиденциальность данных:**
   - Не отправляйте в AI персональные данные
   - Для конфиденциального контента используйте локальные модели
   - Проверяйте политику конфиденциальности провайдера

5. **Мониторинг:**

```
# Регулярно проверяйте лог:
tail -f engine/logs/ai_rewriter.log

# Ищите подозрительную активность
grep ERROR engine/logs/ai_rewriter.log
```

---

## Советы и рекомендации

### Лучшие практики использования

#### 1. Начните с тестирования

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

1. Выберите недорогой провайдер (OpenRouter free models)
2. Установите низкие лимиты расходов
3. Протестируйте на нескольких текстах
4. Оцените качество результата

**Тестовый текст:**

```
Используйте простой текст из 200-300 слов
Проверьте сохранение ссылок
Проверьте работу с форматированием
Оцените время обработки
```

#### 2. Оптимизация качества

**Для новостей:**

```
Процент оригинальности: 60-70%
Тональность: нейтральный или информационный
Temperature: 0.7
Модель: gpt-4o-mini или claude-3-5-sonnet
```

**Для блогов:**

```
Процент оригинальности: 70-80%
Тональность: дружелюбный
Temperature: 0.8
Модель: gpt-4o или claude-sonnet
```

**Для технических текстов:**

```
Процент оригинальности: 40-50%
Тональность: профессиональный
Temperature: 0.3-0.5
Модель: gpt-4 или claude-opus
```

#### 3. Экономия средств

**Стратегии:**

1. **Используйте бесплатные модели для черновиков:**

```
OpenRouter: meta-llama/llama-3.2-3b-instruct:free
Затем финальную версию через GPT-4o-mini
```

2. **Предварительная обработка:**
   - Удалите лишние пробелы и переносы строк
   - Сократите избыточные описания
   - Меньше текста = меньше расходы

3. **Локальные модели для массовых операций:**
   - Установите Ollama для рутинных задач
   - Используйте облачные API только для важных текстов

4. **Мониторинг расходов:**

```
OpenAI: platform.openai.com/usage
Anthropic: console.anthropic.com/settings/billing
OpenRouter: openrouter.ai/activity
```

#### 4. Работа с большими текстами

**Если текст более 2000 слов:**

1. **Разбейте на части:**
   - Рерайтите каждую часть отдельно
   - Затем склейте результат

2. **Увеличьте таймаут:**

```
Таймаут запроса: 60-90 секунд
```

3. **Используйте модели с большим контекстом:**
   - Claude 3.5 Sonnet (200K tokens)
   - GPT-4 Turbo (128K tokens)

#### 5. Качество контроля

**Всегда проверяйте:**

- ✅ Сохранены ли все факты
- ✅ Корректны ли ссылки
- ✅ Нет ли фактических ошибок
- ✅ Сохранено ли форматирование
- ✅ Соответствует ли стиль ожиданиям

**Красные флаги:**

- ❌ Добавлены новые факты, которых не было в оригинале
- ❌ Потеряна важная информация
- ❌ Изменился смысл текста
- ❌ Сломалось форматирование

#### 6. Оптимизация рабочего процесса

**Эффективный workflow:**

```
1. Написать/скопировать черновик
2. Первый рерайт (быстрая модель)
3. Проверка и корректировка
4. Второй рерайт при необходимости (качественная модель)
5. Финальная проверка
6. Сохранение
```

**Горячие клавиши:**

- Создайте закладку для быстрого доступа к настройкам
- Используйте копирование в буфер перед рерайтом

---

### Интеграция в workflow

#### Сценарий 1: Новостной портал

**Задача:** Публикация 20-50 новостей в день из разных источников

**Решение:**

```
Провайдер: OpenRouter
Модель: meta-llama/llama-3.2-3b-instruct:free или недорогая
Процент оригинальности: 65%
Автоприменение: Да (для добавления)
```

**Workflow:**

1. Импорт новостей из RSS
2. Автоматический рерайт при импорте
3. Модератор проверяет выборочно
4. Публикация

#### Сценарий 2: Блог/Журнал

**Задача:** Качественные статьи, 3-5 в неделю

**Решение:**

```
Провайдер: Anthropic или OpenAI
Модель: claude-3-5-sonnet или gpt-4o
Процент оригинальности: 75%
Автоприменение: Нет (только ручной)
```

**Workflow:**

1. Автор пишет черновик
2. Ручной рерайт через кнопку
3. Автор проверяет и дополняет
4. При необходимости повторный рерайт
5. Публикация

#### Сценарий 3: Корпоративный сайт

**Задача:** Редкие обновления, высокие требования к качеству

**Решение:**

```
Провайдер: OpenAI или локальный (для конфиденциальности)
Модель: gpt-4 или ollama llama3
Процент оригинальности: 50% (минимальные изменения)
Температура: 0.3 (консервативный подход)
Автоприменение: Нет
```

**Workflow:**

1. Подготовка текста отделом маркетинга
2. Согласование
3. Рерайт для уникальности
4. Проверка юристом/редактором
5. Публикация

---

### Продвинутые настройки

#### Кастомизация промптов (для разработчиков)

Если нужны специфические инструкции для AI, можно отредактировать файл [ai_rewriter.php](C:\OSPanel\home\it\engine\plugins\ai_rewriter\ai_rewriter.php):

```php
// Найдите строки (примерно 200-210):
$sys = 'Ты профессиональный редактор и копирайтер. ' .
    'Переписывай текст сохраняя смысл, факты, структуру и разметку.';

// Можете изменить на свои инструкции:
$sys = 'Ты SEO-специалист. Переписывай тексты для поисковой оптимизации, ' .
    'добавляй ключевые слова естественным образом, сохраняя читабельность.';
```

**Примеры кастомных промптов:**

**Для SEO:**

```php
$sys = 'Ты SEO-копирайтер. При рерайте:
- Равномерно распредели ключевые слова
- Сохрани заголовки H1-H3
- Добавь релевантные синонимы
- Улучши читабельность';
```

**Для социальных сетей:**

```php
$sys = 'Ты SMM-менеджер. Адаптируй текст:
- Сделай его более эмоциональным
- Добавь призывы к действию
- Разбей на короткие абзацы
- Используй активный залог';
```

#### Мультиязычность

Плагин автоматически работает с любыми языками, но можно указать явно:

```php
$req = 'Rewrite the following text in English with ~60% originality...';
// или
$req = 'Перепиши следующий текст на русском языке...';
```

---

## Заключение

Плагин **AI Rewriter** — мощный инструмент для автоматизации создания уникального контента. При правильной настройке и использовании он может:

- ✅ Сэкономить часы ручной работы
- ✅ Повысить уникальность контента
- ✅ Поддерживать единый стиль текстов
- ✅ Масштабировать производство контента

### Ключевые рекомендации:

1. **Начните с тестирования** на недорогих моделях
2. **Всегда проверяйте результат** перед публикацией
3. **Используйте ручной режим** для важного контента
4. **Экспериментируйте с настройками** для оптимального качества
5. **Мониторьте расходы** на API

### Поддержка и обновления:

- **Документация:** Этот файл и `readme` в папке плагина
- **Логи:** `engine/logs/ai_rewriter.log`
- **Версия:** Проверяйте файл `version` на наличие обновлений
- **Changelog:** `CHANGELOG_NGHELPERS.md` для истории изменений

---

## Приложения

### Приложение A: Сравнение провайдеров

| Провайдер   | Цена  | Скорость | Качество   | Сложность | Приватность |
| ----------- | ----- | -------- | ---------- | --------- | ----------- |
| OpenAI      | $$$   | ⚡⚡⚡   | ⭐⭐⭐⭐⭐ | 😊 Просто | 🔒 Средняя  |
| Anthropic   | $$$   | ⚡⚡⚡   | ⭐⭐⭐⭐⭐ | 😊 Просто | 🔒 Средняя  |
| OpenRouter  | $-$$$ | ⚡⚡     | ⭐⭐⭐⭐   | 😐 Средне | 🔒 Зависит  |
| Together AI | $$    | ⚡⚡⚡   | ⭐⭐⭐⭐   | 😊 Просто | 🔒 Средняя  |
| LM Studio   | Free  | ⚡       | ⭐⭐⭐     | 😰 Сложно | 🔐 Высокая  |
| Ollama      | Free  | ⚡       | ⭐⭐⭐     | 😐 Средне | 🔐 Высокая  |

### Приложение B: Рекомендуемые модели

**Топ-5 для качества:**

1. GPT-4 (OpenAI) - лучшее качество
2. Claude 3.5 Sonnet (Anthropic) - отличное качество, большой контекст
3. GPT-4o (OpenAI) - быстрее GPT-4
4. Claude 3 Opus (Anthropic) - для сложных задач
5. GPT-4 Turbo (OpenAI) - баланс скорости и качества

**Топ-5 для скорости:**

1. GPT-4o-mini (OpenAI) - очень быстро
2. Claude 3 Haiku (Anthropic) - быстро и качественно
3. Together AI Llama models - хорошая скорость
4. GPT-3.5-turbo (OpenAI) - быстро и недорого
5. OpenRouter free models - бесплатно и быстро

**Топ-5 для экономии:**

1. OpenRouter free models - бесплатно
2. Ollama (локально) - бесплатно
3. LM Studio (локально) - бесплатно
4. GPT-3.5-turbo - очень дешево
5. Together AI models - недорого

### Приложение C: Полезные ссылки

**Официальные сайты провайдеров:**

- OpenAI: https://platform.openai.com
- Anthropic: https://console.anthropic.com
- OpenRouter: https://openrouter.ai
- Together AI: https://www.together.ai
- LM Studio: https://lmstudio.ai
- Ollama: https://ollama.ai

**Документация API:**

- OpenAI API: https://platform.openai.com/docs
- Anthropic API: https://docs.anthropic.com
- OpenRouter Docs: https://openrouter.ai/docs

**Сообщество:**

- NGCMS Forum: https://ngcms.ru/forum
- GitHub NGCMS: https://github.com/NG-CMS

**Мониторинг статуса:**

- OpenAI Status: https://status.openai.com
- Anthropic Status: https://status.anthropic.com

---

**Версия документа:** 1.0
**Дата:** 4 февраля 2026
**Версия плагина:** 0.1.2

---

_Этот документ является исчерпывающим руководством по использованию плагина AI Rewriter. Если у вас остались вопросы, обратитесь к технической документации в файле `readme` или в сообщество NGCMS._
