GiteaAdmin/go-lcg

Fork 0

mirror of https://github.com/Direct-Dev-Ru/go-lcg.git synced 2025-11-16 01:29:55 +00:00

Files

Anton Kuznetcov eb9a7dcf32 v2.0.15

2025-11-08 16:02:35 +06:00

34 KiB

Raw Blame History

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

Что это

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

Требования

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

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

Установка

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


git clone --depth 1 https://github.com/Direct-Dev-Ru/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)ничего:

Что нового в 2.0.14

Аутентификация: Добавлена система аутентификации с JWT токенами и HTTP-only cookies
CSRF защита: Полная защита от CSRF атак с токенами и middleware
Безопасность: Улучшенная безопасность с проверкой токенов и сессий
Kubernetes деплой: Полный набор манифестов для деплоя в Kubernetes с Traefik
Flux CD: GitOps конфигурация для автоматического деплоя
Reverse Proxy: Поддержка работы за reverse proxy с настройкой cookies
Веб-интерфейс: Улучшенный веб-интерфейс с современным дизайном
Мониторинг: Prometheus метрики и ServiceMonitor
Масштабирование: HPA для автоматического масштабирования
Тестирование: Инструменты для тестирования CSRF защиты

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

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

Переменная	Значение по умолчанию	Назначение
`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_BROWSER_PATH`	пусто	Путь к браузеру для автооткрытия (`--browser`).
`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_ALLOW_EXECUTION`	пусто	Если `1`/`true` — включает возможность выполнения команд через опцию `(e)` в меню действий.
`LCG_SERVER_PORT`	`8080`	Порт для HTTP сервера просмотра результатов.
`LCG_SERVER_HOST`	`localhost`	Хост для HTTP сервера просмотра результатов.
`LCG_SERVER_REQUIRE_AUTH`	`false`	Требовать аутентификацию для доступа к веб-интерфейсу.
`LCG_SERVER_PASSWORD`	`admin#123456`	Пароль для аутентификации.
`LCG_COOKIE_SECURE`	`false`	Использовать Secure флаг для cookies (для HTTPS).
`LCG_DOMAIN`	пусто	Домен для cookies (для reverse proxy).
`LCG_COOKIE_PATH`	`/`	Путь для cookies (для reverse proxy).
`LCG_COOKIE_TTL_HOURS`	`168`	Время жизни cookies в часах (по умолчанию 7 дней).
`LCG_CSRF_SECRET`	пусто	Секрет для CSRF токенов (генерируется автоматически).

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

# 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

# Аутентификация и безопасность
export LCG_SERVER_REQUIRE_AUTH=true
export LCG_SERVER_PASSWORD=my_secure_password
export LCG_COOKIE_SECURE=false
export LCG_DOMAIN=.example.com
export LCG_COOKIE_PATH=/lcg
export LCG_COOKIE_TTL_HOURS=72  # 3 дня

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

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

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

--file, -f string — прочитать часть запроса из файла и добавить к описанию.
--sys, -s string — системный промпт (содержимое или ID как строка). Если не задан, используется --prompt-id или LCG_PROMPT.
--prompt-id, --pid int — ID системного промпта (1–5 для стандартных, либо ваш кастомный ID).
--timeout, -t int — таймаут запроса в секундах (по умолчанию 120; через LCG_TIMEOUT — 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: запустить HTTP сервер для просмотра сохраненных результатов:
- --port, -p — порт сервера (по умолчанию из LCG_SERVER_PORT)
- --host, -H — хост сервера (по умолчанию из LCG_SERVER_HOST)
- --browser, -b — открыть браузер автоматически после старта
- --require-auth — включить аутентификацию (переопределяет LCG_SERVER_REQUIRE_AUTH)
- --password — пароль для аутентификации (переопределяет LCG_SERVER_PASSWORD)

Подробные объяснения (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 помогают управлять токеном локально.

Поддержка операционных систем

Автоматическое определение ОС

Приложение автоматически определяет операционную систему и использует соответствующие промпты:

Linux/Unix системы (включая macOS): используются промпты для Linux команд
Windows: используются промпты для Windows команд (PowerShell, CMD, Batch)

Промпты для Windows

На Windows системах доступны следующие встроенные промпты:

ID	Name	Описание
1	windows-command	Основной промпт для генерации Windows команд
2	windows-command-with-explanation	Промпт с подробным объяснением команд
3	windows-command-safe	Безопасный анализ команд с предупреждениями
4	windows-command-verbose	Подробный анализ с техническими деталями
5	windows-command-simple	Простое и понятное объяснение

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

# PowerShell команды
lcg "хочу получить список всех процессов"
lcg "показать информацию о дисках"

# CMD команды  
lcg "создать папку test и перейти в неё"
lcg "найти все файлы .txt в текущей директории"

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

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

Системные промпты хранятся в папке, указанной в переменной 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)

Промпты автоматически выбираются в зависимости от операционной системы:

Linux/Unix системы:

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	Простые команды, избегать сложных опций.

Windows системы:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# Автооткрытие браузера (опционально)
lcg serve --browser

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

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

Главная страница (/) — отображает все сохраненные файлы с превью
Статистика — количество файлов, файлы за последние 7 дней
Просмотр файлов (/file/{filename}) — отображение содержимого конкретного файла
Современный дизайн — адаптивный интерфейс с карточками файлов
Сортировка — файлы отсортированы по дате изменения (новые сверху)
Превью содержимого — первые 200 символов каждого файла
Аутентификация — защищенный доступ с JWT токенами
CSRF защита — защита от межсайтовых атак
История запросов (/history) — просмотр истории всех запросов
Управление промптами (/prompts) — редактирование системных промптов
Выполнение команд (/run) — интерактивное выполнение команд
Безопасность — HTTP-only cookies, проверка токенов

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

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

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

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

Браузер

По умолчанию UI не открывается автоматически. Для автооткрытия используйте --browser.
Путь к конкретному браузеру можно задать переменной LCG_BROWSER_PATH.

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

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

Примеры

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

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

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

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

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

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

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

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

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

lcg health
lcg models

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

# Запуск сервера
lcg serve

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

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

# Запуск с аутентификацией
lcg serve --require-auth --password my_secure_password

# Запуск с переменными окружения
export LCG_SERVER_REQUIRE_AUTH=true
export LCG_SERVER_PASSWORD=admin#123456
lcg serve

История

lcg history выводит историю из JSON‑файла (LCG_RESULT_HISTORY), сохраняется между запусками:

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 файлы.
Аутентификация не работает: проверьте LCG_SERVER_REQUIRE_AUTH=true и правильность пароля.
CSRF ошибки: убедитесь, что токены передаются в заголовках X-CSRF-Token.
Cookies не сохраняются: проверьте настройки LCG_DOMAIN и LCG_COOKIE_PATH для reverse proxy.
Kubernetes деплой не работает: проверьте права доступа к кластеру и наличие всех манифестов.

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.

Доступ к локальному API

Основные эндпоинты

POST /api/execute — выполнение запросов к LLM
POST /api/save-result — сохранение результатов
POST /api/add-to-history — добавление в историю
GET /api/login — страница аутентификации
POST /api/login — аутентификация
POST /api/logout — выход из системы
GET /metrics — Prometheus метрики

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

# Запустить сервер
lcg serve

# Выполнить запрос (без аутентификации)
curl -X POST http://localhost:8080/api/execute \
  -H "Content-Type: application/json" \
  -A curl \
  -d '{"prompt": "create directory test", "verbose": "vv"}'

# Аутентификация
curl -X POST http://localhost:8080/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin#123456"}'

# Выполнение с CSRF токеном
curl -X POST http://localhost:8080/api/execute \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: your_csrf_token" \
  -H "Cookie: auth_token=your_jwt_token" \
  -d '{"prompt": "create directory test"}'

Подробности и примеры: API_GUIDE.md.

Kubernetes деплой

Быстрый деплой

# Переход в папку деплоя
cd deploy

# Полный деплой (сборка + деплой + проверка)
./full-deploy.sh

# Или поэтапно
./build.sh lcg latest
./deploy.sh
./health-check.sh

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

# Справка
make help

# Сборка и деплой
make build
make deploy

# Мониторинг
make status
make logs
make monitor

# Удаление
make undeploy

Flux CD (GitOps)

# Настройка Flux CD
cd deploy/flux
./setup-flux.sh

# Создание Kustomization
./create_kustomization.sh

# Мониторинг
kubectl get kustomization lcg -n flux-system

Конфигурация для reverse proxy

# Настройка для работы за reverse proxy
export LCG_SERVER_REQUIRE_AUTH=true
export LCG_SERVER_ALLOW_HTTP=true
export LCG_DOMAIN=.example.com
export LCG_COOKIE_PATH=/lcg
export LCG_COOKIE_SECURE=false

# Запуск
./lcg serve -H 0.0.0.0 -p 8080

Мониторинг и безопасность

Prometheus метрики: /metrics endpoint
Health checks: автоматические проверки готовности
HPA: автоматическое масштабирование (2-10 replicas)
CSRF защита: токены для всех POST запросов
Аутентификация: JWT токены в HTTP-only cookies
Security context: non-root пользователь, минимальные права

Подробности: deploy/README.md и deploy/flux/README.md.

Тестирование CSRF защиты

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

# Запуск тестов CSRF защиты
./test_csrf.sh

# Проверка результатов
echo "Проверьте вывод на наличие ошибок 403 Forbidden"

Ручное тестирование

# Откройте csrf_test.html в браузере
open csrf_test.html

# Или используйте curl для тестирования
curl -X POST http://localhost:8080/api/execute \
  -H "Content-Type: application/json" \
  -d '{"prompt": "test"}' \
  -v

Демонстрация уязвимости

# Откройте csrf_demo.html для демонстрации атаки
open csrf_demo.html

Подробности: CSRF_TESTING_GUIDE.md.

34 KiB Raw Blame History Unescape Escape