GiteaAdmin/go-lcg
1
0
Fork 0
mirror of https://github.com/Direct-Dev-Ru/go-lcg.git synced 2025-11-15 17:20:00 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
58c29349242f4f51059f1464e20016736b9dd0e1
go-lcg/USAGE_GUIDE.md
Anton Kuznetcov 58c2934924 alpha v.2
2025-10-21 18:51:30 +06:00

22 KiB
Raw Blame History

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

Что это

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

Требования

  • Установленный Go (для сборки из исходников) или готовый бинарник.
  • Для функции «скопировать в буфер обмена»: установите xclip или xsel.
# Debian/Ubuntu
sudo apt-get install xclip
# или
sudo apt-get install xsel

Установка

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

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

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

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

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

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

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

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

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

🤖 Запрос: <ваше описание>
✅ Выполнено за 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 сервера просмотра результатов.

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

# 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

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

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) в файл вида:

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

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

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

# Запуск с настройками по умолчанию
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:
export LCG_PROVIDER=ollama
export LCG_HOST=http://localhost:11434/
export LCG_MODEL=codegeex4

lcg "хочу извлечь linux-command-gpt.tar.gz"
  1. Полный ответ от LLM (пример настройки):
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‑провайдер:
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. Работа с файлами и промптами:
lcg --file ./context.txt "сгенерируй команду jq для выборки поля name"
lcg --prompt-id 2 "удали все *.tmp в текущем каталоге"
lcg --sys 1 "показать размер каталога в человеко‑читаемом виде"
  1. Диагностика и модели:
lcg health
lcg models
  1. HTTP сервер для просмотра результатов:
# Запуск сервера
lcg serve-result

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

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

История

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

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).
  • Формат — массив объектов:
[
  {
    "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.