Премини към основното съдържание
Български— Изберете език
Меню

Shell: Изпълнение на команди

Урок 18 от 20 Програмист
На тази страница
  1. Shell: Изпълнение на команди
  2. Концепция и архитектура
  3. Случай на употреба: Системна диагноза
  4. Осигуряване на изпълнението
  5. Внедряване като персонализирана функция
  6. Работни потоци за автоматизация
  7. Ключови изводи

Shell: Изпълнение на команди

Това е най-мощният инструмент в този курс и единственият, при който грешка може да обърне силата му срещу Вас. Другите инструменти четат, изчисляват или търсят; този действа върху машината. Лошо формулирана системна диагноза остава просто диагноза; лошо формулирана команда за почистване изтрива файлове.

Този урок разглежда употребата и предпазните мерки заедно, защото те не могат да бъдат разделени. Златното правило: моделът никога не трябва да изпълнява команда, която не сте изрично autorizirali предварително.

Концепция и архитектура

Разликата спрямо Code Interpreter е критична и се свежда до една дума: изолация. Code Interpreter работи в изолирана от мрежата пясъчница за еднократна употреба, където най-лошият сценарий е грешно изчисление. Shell работи в среда, конфигурирана от Вас – потенциално Вашата локална машина, потенциално сървър – където най-лошият сценарий е необратима операция.

Тази свобода е смисълът: без нея автоматизираното внедряване и поддръжка са невъзможни. Това обаче изисква от Вас съзнателен избор на обхвата на изпълнение. Специализиран контейнер с ограничени привилегии е почти винаги правилният избор пред директен достъп до хоста.

from openai import OpenAI

client = OpenAI()

# The Shell tool is used via the Agents SDK
# because it requires a controlled execution environment
from agents import Agent, Runner

agent = Agent(
    name="devops-assistant",
    model="gpt-5.6-terra",
    instructions=(
        "You are a DevOps assistant. You execute system commands "
        "to diagnose and resolve infrastructure issues. "
        "Explain each command before executing it."
    ),
    tools=[{"type": "shell"}]
)

Случай на употреба: Системна диагноза

# The agent can execute diagnostic commands
agent = Agent(
    name="diagnostic",
    model="gpt-5.6-terra",
    instructions=(
        "Diagnose the system state by executing appropriate commands. "
        "Start with basic checks (disk, memory, CPU) "
        "then dig deeper based on symptoms."
    ),
    tools=[{"type": "shell"}]
)

# The agent will execute commands like:
# df -h          -> disk space
# free -m        -> memory
# top -bn1       -> CPU load
# systemctl status nginx  -> service status

Осигуряване на изпълнението

Три предпазни мерки работят заедно и нито една не е достатъчна сама по себе си. Списъкът с позволени (allowlist) е основата: изброявате какво е позволено, а не какво е забранено, защото списъкът със забрани винаги пропуска някой вариант – а е достатъчен само един. Таймаутът предотвратява заседнала команда да блокира системата. Ограничената работна директория ограничава щетите, ако легитимна команда сочи към грешното място.

Четвъртата предпазна мярка е нетехническа, но струва колкото другите три взети заедно: изисквайте човешко потвърждение за всяка деструктивна или необратима операция. Моделът прави грешки със същата увереност, с която е прав.

# Pattern: wrapper function with validation
import subprocess
import shlex

ALLOWED_COMMANDS = {
    "diagnostic": ["df", "free", "top", "uptime", "ps", "netstat", "curl", "ping"],
    "deployment": ["git", "docker", "npm", "pip"],
    "files": ["ls", "cat", "head", "tail", "wc", "grep", "find"],
}

FORBIDDEN_COMMANDS = ["rm", "dd", "mkfs", "shutdown", "reboot", "kill", "passwd"]

def execute_secure_command(command: str, category: str = "diagnostic") -> dict:
    """Executes a command with security validation."""
    # Parse the command
    parts = shlex.split(command)
    executable = parts[0]

    # Check prohibitions
    if executable in FORBIDDEN_COMMANDS:
        return {
            "error": f"Forbidden command: {executable}",
            "reason": "This command is on the blocklist"
        }

    # Check permissions
    allowed = ALLOWED_COMMANDS.get(category, [])
    if executable not in allowed:
        return {
            "error": f"Command not allowed in category '{category}'",
            "allowed": allowed
        }

    # Execute with timeout
    try:
        result = subprocess.run(
            parts,
            capture_output=True,
            text=True,
            timeout=30,
            cwd="/tmp"  # Restricted working directory
        )
        return {
            "stdout": result.stdout,
            "stderr": result.stderr,
            "return_code": result.returncode
        }
    except subprocess.TimeoutExpired:
        return {"error": "Timeout: command exceeded 30 seconds"}

Внедряване като персонализирана функция

Внедряването на това самостоятелно чрез извикване на функции предлага предимство, което не бива да разглеждате като резервен вариант: валидацията живее във Вашия код. Вие решавате списъка с позволени команди, регистрирането и стъпките за потвърждение и можете да одитирате всичко. За инструмент с това ниво на риск, запазването на контрол над контролната точка е за предпочитане, дори когато стане налична нативна версия.

tools = [
    {
        "type": "function",
        "name": "execute_command",
        "description": (
            "Execute a shell command on the server. "
            "Allowed commands: system diagnostics (df, free, top, uptime, ps), "
            "file reading (ls, cat, head, tail, grep), "
            "network (curl, ping, netstat). "
            "Destructive commands are forbidden."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "command": {
                    "type": "string",
                    "description": "The shell command to execute"
                },
                "directory": {
                    "type": "string",
                    "description": "Working directory (default: /tmp)"
                }
            },
            "required": ["command"],
            "additionalProperties": False
        },
        "strict": True
    }
]

import json

def handle_calls(response):
    results = []
    for item in response.output:
        if item.type == "function_call" and item.name == "execute_command":
            args = json.loads(item.arguments)
            result = execute_secure_command(
                args["command"],
                category="diagnostic"
            )
            results.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(result)
            })
    return results

# Full loop
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Check disk space and available memory",
    tools=tools
)

results = handle_calls(response)
final_response = client.responses.create(
    model="gpt-5.6-terra",
    input=response.output + results,
    tools=tools
)
print(final_response.output_text)

Работни потоци за автоматизация

Автоматизирано внедряване

Внедряването е най-ценният случай на употреба, при условие че разбирате какво делегирате. Моделът не измисля процедурата: той свързва заедно стъпки, които сте дефинирали, проверява междинните изходи и спира при всяка аномалия. Той е внимателен оператор, а не вземащ решения.

tools_deploy = [
    {
        "type": "function",
        "name": "execute_deploy_step",
        "description": (
            "Execute a deployment step. "
            "Possible steps: git_pull, tests, build, deploy, rollback. "
            "Each step is validated before proceeding to the next."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "step": {
                    "type": "string",
                    "enum": ["git_pull", "tests", "build", "deploy", "rollback"]
                },
                "parameters": {
                    "type": "object",
                    "properties": {
                        "branch": {"type": "string"},
                        "environment": {"type": "string", "enum": ["staging", "production"]}
                    }
                }
            },
            "required": ["step"],
            "additionalProperties": False
        },
        "strict": True
    }
]

def execute_step(step: str, params: dict) -> dict:
    scripts = {
        "git_pull": "cd /app && git pull origin {branch}",
        "tests": "cd /app && npm test",
        "build": "cd /app && npm run build",
        "deploy": "cd /app && ./deploy.sh {environment}",
        "rollback": "cd /app && ./rollback.sh {environment}"
    }
    command = scripts[step].format(**params)
    return execute_secure_command(command, "deployment")

Мониторинг и известия

Мониторингът обръща логиката на останалата част от този урок: командите тук са само за четене, следователно са безвредни, а стойността е в интерпретацията. Модел, който чете дисково пространство, натоварване и логове за грешки, открива корелации, които един изолиран праг пропуска – което прави това най-безопасната входна точка за започване на работа с този инструмент.

def check_system_health() -> dict:
    """Checks system health and returns a report."""
    checks = {}

    # Disk space
    r = execute_secure_command("df -h /", "diagnostic")
    checks["disk"] = r

    # Memory
    r = execute_secure_command("free -m", "diagnostic")
    checks["memory"] = r

    # Services
    for service in ["nginx", "postgresql", "redis"]:
        r = execute_secure_command(
            f"systemctl is-active {service}",
            "diagnostic"
        )
        checks[f"service_{service}"] = r

    return checks

# The AI analyzes the results and suggests actions
response = client.responses.create(
    model="gpt-5.6-terra",
    input=f"Analyze this system health report and identify issues:\n"
          f"{json.dumps(check_system_health(), indent=2)}",
    tools=tools
)

Ключови изводи

  • Инструментът Shell свързва модела с Вашата инфраструктура
  • Внедрете списъци с позволени и забранени команди
  • Използвайте таймаути и ограничени работни директории
  • Извикването на функции Ви позволява да внедрите Shell като персонализиран инструмент
  • Комбинирайте Shell с други инструменти за пълни DevOps работни потоци