go-lcg/USAGE_GUIDE.md

# Руководство по использованию (USAGE_GUIDE)

## Что это

Linux Command GPT (`lcg`) преобразует описание на естественном языке в готовую Linux‑команду. Инструмент поддерживает сменные провайдеры LLM (Ollama или Proxy), управление системными промптами, историю запросов, сохранение результатов, HTTP сервер для просмотра результатов и интерактивные действия над сгенерированной командой.

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

- Установленный Go (для сборки из исходников) или готовый бинарник.
- Для функции «скопировать в буфер обмена»: установите `xclip` или `xsel`.

```bash
# Debian/Ubuntu
sudo apt-get install xclip
# или
sudo apt-get install xsel
```

## Установка

Сборка из исходников:

```bash
git clone --depth 1 https://github.com/asrul10/linux-command-gpt.git ~/.linux-command-gpt
cd ~/.linux-command-gpt
go build -o lcg

# Добавьте бинарник в PATH
ln -s ~/.linux-command-gpt/lcg ~/.local/bin
```

Или скачайте готовый бинарник из раздела релизов.

## Быстрый старт

Простой запрос:

```bash
lcg "хочу извлечь файл linux-command-gpt.tar.gz"
```

Смешанный ввод: часть из файла, часть — текстом:

```bash
lcg --file /path/to/context.txt "хочу вывести список директорий с помощью ls"
```

После генерации вы увидите:

```text
🤖 Запрос: <ваше описание>
✅ Выполнено за X.XX сек

ВНИМАНИЕ: ОТВЕТ СФОРМИРОВАН ИИ. ТРЕБУЕТСЯ ПРОВЕРКА И КРИТИЧЕСКИЙ АНАЛИЗ. ВОЗМОЖНЫ ОШИБКИ И ГАЛЛЮЦИНАЦИИ.

📋 Команда:
   <сгенерированная команда>

Действия: (c)копировать, (s)сохранить, (r)перегенерировать, (e)выполнить, (v|vv|vvv)подробно, (n)ничего:
```

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

Можно настроить поведение без изменения командной строки.

| Переменная | Значение по умолчанию | Назначение |
| --- | --- | --- |
| `LCG_HOST` | `http://192.168.87.108:11434/` | Базовый URL API провайдера (для Ollama поставьте, например, `http://localhost:11434/`). |
| `LCG_PROXY_URL` | `/api/v1/protected/sberchat/chat` | Относительный путь эндпоинта для Proxy провайдера. |
| `LCG_COMPLETIONS_PATH` | `api/chat` | Относительный путь эндпоинта для Ollama. |
| `LCG_MODEL` | `hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M` | Имя модели у выбранного провайдера. |
| `LCG_PROMPT` | См. значение в коде | Содержимое системного промпта по умолчанию. |
| `LCG_API_KEY_FILE` | `.openai_api_key` | Файл с API‑ключом (для Ollama/Proxy не требуется). |
| `LCG_RESULT_FOLDER` | `~/.config/lcg/gpt_results` | Папка для сохранения результатов. |
| `LCG_PROVIDER` | `ollama` | Тип провайдера: `ollama` или `proxy`. |
| `LCG_JWT_TOKEN` | пусто | JWT токен для `proxy` провайдера (альтернатива — файл `~/.proxy_jwt_token`). |
| `LCG_PROMPT_ID` | `1` | ID системного промпта по умолчанию. |
| `LCG_TIMEOUT` | `300` | Таймаут запроса в секундах. |
| `LCG_RESULT_HISTORY` | `$(LCG_RESULT_FOLDER)/lcg_history.json` | Путь к JSON‑истории запросов. |
| `LCG_PROMPT_FOLDER` | `~/.config/lcg/gpt_sys_prompts` | Папка для хранения системных промптов. |
| `LCG_NO_HISTORY` | пусто | Если `1`/`true` — полностью отключает запись/обновление истории. |
| `LCG_SERVER_PORT` | `8080` | Порт для HTTP сервера просмотра результатов. |
| `LCG_SERVER_HOST` | `localhost` | Хост для HTTP сервера просмотра результатов. |

Примеры настройки:

```bash
# Ollama
export LCG_PROVIDER=ollama
export LCG_HOST=http://localhost:11434/
export LCG_MODEL=codegeex4

# Proxy
export LCG_PROVIDER=proxy
export LCG_HOST=http://localhost:8080
export LCG_MODEL=GigaChat-2
export LCG_JWT_TOKEN=your_jwt_token_here
```

## Базовый синтаксис

```bash
lcg [глобальные опции] <описание команды>
```

Глобальные опции:

- `--file, -f string` — прочитать часть запроса из файла и добавить к описанию.
- `--sys, -s string` — системный промпт (содержимое или ID как строка). Если не задан, используется `--prompt-id` или `LCG_PROMPT`.
- `--prompt-id, --pid int` — ID системного промпта (1–5 для стандартных, либо ваш кастомный ID).
- `--timeout, -t int` — таймаут запроса в секундах (по умолчанию 300).
- `--no-history, --nh` — отключить запись/обновление истории для текущего запуска.
- `--debug, -d` — показать отладочную информацию (параметры запроса и промпты).
- `--version, -v` — вывести версию.
- `--help, -h` — помощь.

## Подкоманды

- `lcg update-key` (`-u`): обновить API‑ключ. Для `ollama` и `proxy` не требуется — команда сообщит, что ключ не нужен.
- `lcg delete-key` (`-d`): удалить API‑ключ (не требуется для `ollama`/`proxy`).
- `lcg update-jwt` (`-j`): обновить JWT для `proxy`. Токен будет сохранён в `~/.proxy_jwt_token` (права `0600`).
- `lcg delete-jwt` (`-dj`): удалить JWT файл для `proxy`.
- `lcg models` (`-m`): показать доступные модели у текущего провайдера.
- `lcg health` (`-he`): проверить доступность API провайдера.
- `lcg config` (`-co`): показать текущую конфигурацию и состояние JWT.
- `lcg history list` (`-l`): показать историю из JSON‑файла (`LCG_RESULT_HISTORY`).
- `lcg history view <id>` (`-v`): показать запись истории по `index`.
- `lcg history delete <id>` (`-d`): удалить запись истории по `index` (с перенумерацией).
- Флаг `--no-history` (`-nh`) отключает запись истории для текущего запуска и имеет приоритет над `LCG_NO_HISTORY`.
- `lcg prompts ...` (`-p`): управление системными промптами:
  - `lcg prompts list` (`-l`) — список всех промптов с содержимым в читаемом формате.
  - `lcg prompts list --full` (`-f`) — полный вывод содержимого без обрезки длинных строк.
  - `lcg prompts add` (`-a`) — добавить пользовательский промпт (по шагам в интерактиве).
  - `lcg prompts delete <id>` (`-d`) — удалить пользовательский промпт по ID (>5).
- `lcg test-prompt <prompt-id> <описание>` (`-tp`): показать детали выбранного системного промпта и протестировать его на заданном описании.
- `lcg serve-result` (`serve`): запустить HTTP сервер для просмотра сохраненных результатов:
  - `--port, -p` — порт сервера (по умолчанию из `LCG_SERVER_PORT`)
  - `--host, -H` — хост сервера (по умолчанию из `LCG_SERVER_HOST`)

### Подробные объяснения (v/vv/vvv)

- `v` — кратко: что делает команда и ключевые опции, без альтернатив.
- `vv` — средне: назначение, основные ключи, 1–2 примера, кратко об альтернативах.
- `vvv` — максимально подробно: полный разбор ключей, сценариев, примеры, разбор альтернатив и сравнений.

После вывода подробного объяснения доступно вторичное меню: `Действия: (c)копировать, (s)сохранить, (r)перегенерировать, (n)ничего:`

## Провайдеры

### Ollama (`LCG_PROVIDER=ollama`)

- Требуется запущенный Ollama API (`LCG_HOST`, например `http://localhost:11434/`).
- `models`, `health` и генерация используют REST Ollama (`/api/tags`, `/api/chat`).
- API‑ключ не нужен.

### Proxy (`LCG_PROVIDER=proxy`)

- Требуется доступ к прокси‑серверу (`LCG_HOST`) и JWT (`LCG_JWT_TOKEN` или файл `~/.proxy_jwt_token`).
- Основные эндпоинты: `/api/v1/protected/sberchat/chat` и `/api/v1/protected/sberchat/health`.
- Команды `update-jwt`/`delete-jwt` помогают управлять токеном локально.

## Рекомендации по выбору провайдера, модели и таймаутов

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

- **Ollama**: выбирайте для локальной работы (офлайн/частные данные), когда есть доступ к GPU/CPU и готовность поддерживать локальные модели. Минимальные задержки сети, полная приватность.
- **Proxy**: выбирайте для централизованного хостинга моделей, более мощных/обновляемых моделей, простоты развёртывания у команды. Обязательно используйте HTTPS и корректный `JWT`.

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

- Для генерации Linux‑команд подходят компактные «code»/«general» модели (по умолчанию `codegeex4`).
- Для подробных объяснений (`v`/`vv`/`vvv`) точность выше у более крупных моделей (например, семейства LLaMA/Qwen/GigaChat), но они медленнее.
- Русскоязычные запросы часто лучше обрабатываются в `GigaChat-*` (режим proxy), английские — в популярных open‑source (Ollama).
- Балансируйте: скорость (малые модели) vs качество (крупные модели). Тестируйте `lcg models` и подбирайте `LCG_MODEL`.

### Таймауты

- Стартовые значения: локально с Ollama — **120–300 сек**, удалённый proxy — **300–600 сек**.
- Увеличьте таймаут для больших моделей/длинных запросов. Флаг `--timeout` перекрывает `LCG_TIMEOUT` на время запуска.
- Если часто видите таймауты — проверьте здоровье API (`lcg health`) и сетевую доступность `LCG_HOST`.

### Практические советы

- Если данные чувствительные — используйте Ollama локально и `--no-history` при необходимости.
- Для «черновой» команды начните с `Ollama + небольшая модель`; для «объяснений и альтернатив» используйте более крупную модель/Proxy.
- Не вставляйте секреты в запросы. Перед выполнением (`e`) проверяйте команду вручную.
- Для структуры API см. `API_CONTRACT.md` (эндпоинты и форматы запросов/ответов).

## Системные промпты

### Управление промптами

Системные промпты хранятся в папке, указанной в переменной `LCG_PROMPT_FOLDER` (по умолчанию: `~/.config/lcg/gpt_sys_prompts`).

**Логика загрузки:**

- Если файл `sys_prompts` **не существует** — создается файл с системными промптами (ID 1–5) и промптами подробности (ID 6–8)
- Если файл `sys_prompts` **существует** — загружаются все промпты из файла
- **Промпты подробности** (v/vv/vvv) сохраняются в том же файле с ID 6, 7, 8

### Встроенные промпты (ID 1–5)

| ID | Name | Описание |
| --- | --- | --- |
| 1 | linux-command | «Ответь только Linux‑командой, без форматирования и объяснений». |
| 2 | linux-command-with-explanation | Сгенерируй команду и кратко объясни, что она делает (формат: COMMAND: explanation). |
| 3 | linux-command-safe | Безопасные команды (без потери данных). Вывод — только команда. |
| 4 | linux-command-verbose | Команда с подробными объяснениями флагов и альтернатив. |
| 5 | linux-command-simple | Простые команды, избегать сложных опций. |

### Промпты подробности (ID 6–8)

| ID | Name | Описание |
| --- | --- | --- |
| 6 | verbose-v | Подробный режим (v) - детальное объяснение команды |
| 7 | verbose-vv | Очень подробный режим (vv) - исчерпывающее объяснение с альтернативами |
| 8 | verbose-vvv | Максимально подробный режим (vvv) - полное руководство с примерами |

### Веб-интерфейс управления

Через HTTP сервер (`lcg serve-result`) доступно полное управление промптами:

- **Просмотр всех промптов** (встроенных и пользовательских)
- **Редактирование любых промптов** (включая встроенные)
- **Добавление новых промптов**
- **Удаление промптов**
- **Автоматическое сохранение** в файл `sys_prompts`

## Сохранение результатов

При выборе действия `s` ответ сохраняется в `LCG_RESULT_FOLDER` (по умолчанию: `~/.config/lcg/gpt_results`) в файл вида:

```text
gpt_request_<MODEL>_YYYY-MM-DD_HH-MM-SS.md
```

## HTTP сервер для просмотра результатов

Команда `lcg serve-result` запускает веб-сервер для удобного просмотра всех сохраненных результатов:

```bash
# Запуск с настройками по умолчанию
lcg serve-result

# Запуск на другом порту
lcg serve-result --port 9090

# Запуск на другом хосте
lcg serve-result --host 0.0.0.0 --port 8080

# Использование переменных окружения
export LCG_SERVER_PORT=3000
export LCG_SERVER_HOST=0.0.0.0
lcg serve-result
```

### Возможности веб-интерфейса

- **Главная страница** (`/`) — отображает все сохраненные файлы с превью
- **Статистика** — количество файлов, файлы за последние 7 дней
- **Просмотр файлов** (`/file/{filename}`) — отображение содержимого конкретного файла
- **Современный дизайн** — адаптивный интерфейс с карточками файлов
- **Сортировка** — файлы отсортированы по дате изменения (новые сверху)
- **Превью содержимого** — первые 200 символов каждого файла

Структура файла (команда):

- `# <заголовок>` — H1, это ваш запрос, при длине >120 символов обрезается до 116 + `...`.
- `## Prompt` — запрос (включая системный промпт).
- `## Response` — сгенерированная команда.

Структура файла (подробное объяснение):

- `# <заголовок>` — H1, ваш исходный запрос (с тем же правилом обрезки).
- `## Prompt` — исходный запрос.
- `## Command` — первая сгенерированная команда.
- `## Explanation and Alternatives (model: <MODEL>)` — подробное объяснение и альтернативы.

## Выполнение сгенерированной команды

Действие `e` запустит команду через `bash -c`. Перед запуском потребуется подтверждение `y/yes`. Всегда проверяйте команду вручную, особенно при операциях с файлами и сетью.

## Примеры

1. Базовый запрос с Ollama:

```bash
export LCG_PROVIDER=ollama
export LCG_HOST=http://localhost:11434/
export LCG_MODEL=codegeex4

lcg "хочу извлечь linux-command-gpt.tar.gz"
```

1. Полный ответ от LLM (пример настройки):

```bash
LCG_PROMPT='Provide full response' LCG_MODEL=codellama:13b \
  lcg 'i need bash script to execute command by ssh on array of hosts'
```

1. Proxy‑провайдер:

```bash
export LCG_PROVIDER=proxy
export LCG_HOST=http://localhost:8080
export LCG_MODEL=GigaChat-2
export LCG_JWT_TOKEN=your_jwt_token_here

lcg "I want to extract linux-command-gpt.tar.gz file"

lcg health
lcg config
lcg update-jwt
```

1. Работа с файлами и промптами:

```bash
lcg --file ./context.txt "сгенерируй команду jq для выборки поля name"
lcg --prompt-id 2 "удали все *.tmp в текущем каталоге"
lcg --sys 1 "показать размер каталога в человеко‑читаемом виде"
```

1. Диагностика и модели:

```bash
lcg health
lcg models
```

1. HTTP сервер для просмотра результатов:

```bash
# Запуск сервера
lcg serve-result

# Запуск на другом порту
lcg serve-result --port 9090

# Запуск на всех интерфейсах
lcg serve-result --host 0.0.0.0 --port 8080
```

## История

`lcg history` выводит историю текущего процесса (не сохраняется между запусками, максимум 100 записей):

```bash
lcg history list
```

## Типичные проблемы

- Нет ответа/таймаут: увеличьте `--timeout` или `LCG_TIMEOUT`, проверьте `LCG_HOST` и сетевую доступность.
- `health` падает: проверьте, что провайдер запущен и URL верный; для `proxy` — что JWT валиден (`lcg config`).
- Копирование не работает: установите `xclip` или `xsel`.
- Нет допуска к папке результатов: настройте `LCG_RESULT_FOLDER` или права доступа.
- Для `ollama`/`proxy` API‑ключ не нужен; команды `update-key`/`delete-key` просто уведомят об этом.
- HTTP сервер не запускается: проверьте, что порт свободен, используйте `--port` для смены порта.
- Веб-интерфейс не отображает файлы: убедитесь, что в `LCG_RESULT_FOLDER` есть `.md` файлы.

## JSON‑история запросов

- Путь задаётся `LCG_RESULT_HISTORY` (по умолчанию: `$(LCG_RESULT_FOLDER)/lcg_history.json`).
- Формат — массив объектов:

```json
[
  {
    "index": 1,
    "command": "хочу извлечь linux-command-gpt.tar.gz",
    "response": "tar -xvzf linux-command-gpt.tar.gz",
    "explanation": "... если запрашивалось v/vv/vvv ...",
    "system_prompt": "Reply with linux command and nothing else ...",
    "timestamp": "2025-10-19T13:05:39.000000000Z"
  }
]
```

- Перед новым запросом, если такой уже встречался, будет предложено вывести сохранённый результат из истории с указанием даты.
- Сохранение в файл истории выполняется автоматически после завершения работы (любое действие, кроме `v|vv|vvv`).
- При совпадении запроса в истории спрашивается о перезаписи записи.
- Подкоманды истории работают по полю `index` внутри JSON (а не по позиции массива): используйте `lcg history view <index>` и `lcg history delete <index>`.
- При показе из истории запрос к API не выполняется: выводится CAPS‑предупреждение и далее доступно обычное меню действий над командой/объяснением.

## Лицензия и исходники

См. README и репозиторий проекта. Предложения и баг‑репорты приветствуются в Issues.