go-lcg/docs/API_GUIDE.md

API Guide - Linux Command GPT

Обзор

API позволяет выполнять запросы к Linux Command GPT через HTTP POST запросы с помощью curl. API принимает только запросы от curl (проверка User-Agent).

Endpoint

POST /execute

Запуск сервера

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

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

# Запуск с автоматическим открытием браузера
lcg serve --browser

Структура запроса

JSON Payload

{
  "prompt": "создать директорию test",
  "system_id": 1,
  "system": "альтернативный системный промпт",
  "verbose": "vv",
  "timeout": 120
}

Поля запроса

Поле	Тип	Обязательное	Описание
prompt	string	✅	Пользовательский запрос
system_id	int	❌	ID системного промпта (1-5)
system	string	❌	Текст системного промпта (альтернатива system_id)
verbose	string	❌	Степень подробности: "v", "vv", "vvv"
timeout	int	❌	Таймаут в секундах (по умолчанию: 120)

Структура ответа

{
  "success": true,
  "command": "mkdir test",
  "explanation": "Команда mkdir создает новую директорию...",
  "model": "hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M",
  "elapsed": 2.34
}

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

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

curl -X POST http://localhost:8080/execute \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "создать директорию test"
  }'

Ответ:

{
  "success": true,
  "command": "mkdir test",
  "model": "hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M",
  "elapsed": 1.23
}

2. Запрос с системным промптом по ID

curl -X POST http://localhost:8080/execute \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "найти все файлы .txt",
    "system_id": 2
  }'

3. Запрос с кастомным системным промптом

curl -X POST http://localhost:8080/execute \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "показать использование памяти",
    "system": "Ты эксперт по Linux. Отвечай только командами без объяснений."
  }'

4. Запрос с подробным объяснением

curl -X POST http://localhost:8080/execute \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "архивировать папку documents",
    "verbose": "vv",
    "timeout": 180
  }'

Ответ:

{
  "success": true,
  "command": "tar -czf documents.tar.gz documents/",
  "explanation": "Команда tar создает архив в формате gzip...",
  "model": "hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M",
  "elapsed": 3.45
}

5. Запрос с максимальной подробностью

curl -X POST http://localhost:8080/execute \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "настроить SSH сервер",
    "system_id": 3,
    "verbose": "vvv",
    "timeout": 300
  }'

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

ID	Название	Описание
1	basic	Базовые команды Linux
2	advanced	Продвинутые команды
3	system	Системное администрирование
4	network	Сетевые команды
5	security	Безопасность

Степени подробности

Уровень	Описание
v	Краткое объяснение
vv	Подробное объяснение с альтернативами
vvv	Максимально подробное объяснение с примерами

Обработка ошибок

Ошибка валидации

{
  "success": false,
  "error": "Prompt is required"
}

Ошибка AI

{
  "success": false,
  "error": "Failed to get response from AI"
}

Ошибка доступа

HTTP 403 Forbidden
Only curl requests are allowed

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

Убедитесь, что настроены необходимые переменные:

# Основные настройки
export LCG_PROVIDER="ollama"
export LCG_HOST="http://localhost:11434"
export LCG_MODEL="hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M"

# Для proxy провайдера
export LCG_PROVIDER="proxy"
export LCG_HOST="https://your-proxy-server.com"
export LCG_JWT_TOKEN="your-jwt-token"

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

• ✅ Только curl: API принимает только запросы от curl
• ✅ POST только: Только POST запросы к /execute
• ✅ JSON валидация: Строгая проверка входных данных
• ✅ Таймауты: Ограничение времени выполнения запросов

Примеры скриптов

Bash скрипт для автоматизации

#!/bin/bash

API_URL="http://localhost:8080/execute"

# Функция для выполнения запроса
execute_command() {
    local prompt="$1"
    local verbose="${2:-}"
    
    curl -s -X POST "$API_URL" \
        -H "Content-Type: application/json" \
        -d "{\"prompt\": \"$prompt\", \"verbose\": \"$verbose\"}" | \
        jq -r '.command'
}

# Использование
echo "Команда: $(execute_command "создать директорию backup")"

Python скрипт

import requests
import json

def execute_command(prompt, system_id=None, verbose=None):
    url = "http://localhost:8080/execute"
    payload = {"prompt": prompt}
    
    if system_id:
        payload["system_id"] = system_id
    if verbose:
        payload["verbose"] = verbose
    
    response = requests.post(url, json=payload)
    return response.json()

# Использование
result = execute_command("показать использование диска", verbose="vv")
print(f"Команда: {result['command']}")
if 'explanation' in result:
    print(f"Объяснение: {result['explanation']}")