Przejdź do głównej treści
Polski— Wybierz język
Menu

Shell: Wykonywanie poleceń

Lekcja 18 z 20 Programista
Na tej stronie
  1. Shell: Wykonywanie poleceń
  2. Koncepcja i architektura
  3. Przypadek użycia: Diagnoza systemu
  4. Zabezpieczanie wykonywania
  5. Implementacja jako funkcja niestandardowa
  6. Przepływy pracy automatyzacji
  7. Kluczowe wnioski

Shell: Wykonywanie poleceń

To najpotężniejsze narzędzie w tym kursie i jedyne, w którym błąd może obrócić jego moc przeciwko Tobie. Inne narzędzia tylko odczytują dane, wykonują obliczenia lub przeszukują zasoby; to narzędzie działa na maszynie. Źle sformułowana diagnoza systemu pozostaje jedynie diagnozą; źle sformułowane polecenie czyszczące usuwa pliki.

W tej lekcji omawiamy sposób użycia i środki bezpieczeństwa łącznie, ponieważ nie można ich rozdzielić. Złota zasada brzmi: model nigdy nie powinien wykonywać polecenia, którego wcześniej wyraźnie nie autoryzowałeś.

Koncepcja i architektura

Różnica względem Code Interpreter jest kluczowa i sprowadza się do jednego słowa: izolacja. Code Interpreter działa w jednorazowym piaskownicy odizolowanej od sieci, gdzie najgorszym scenariuszem jest błędne obliczenie. Shell działa w środowisku skonfigurowanym przez Ciebie – potencjalnie na Twojej lokalnej maszynie, potencjalnie na serwerze – gdzie najgorszym scenariuszem jest operacja nieodwracalna.

Ta swoboda jest sednem sprawy: bez niej automatyczne wdrażanie i utrzymanie systemu są niemożliwe. Wymaga ona jednak świadomego wyboru zakresu wykonywania. Dedykowany kontener z ograniczonymi uprawnieniami jest prawie zawsze lepszym wyborem niż bezpośredni dostęp do hosta.

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"}]
)

Przypadek użycia: Diagnoza systemu

# 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

Zabezpieczanie wykonywania

Trzy mechanizmy bezpieczeństwa działają razem i żaden z nich nie jest wystarczający samodzielnie. Podstawą jest allowlista (biała lista): wymieniasz to, co dozwolone, a nie to, co zabronione, ponieważ lista blokad (blacklista) zawsze pominie jakąś wariantację – a wystarczy jeden błąd. Limit czasu (timeout) zapobiega zawieszeniu systemu przez utknięte polecenie. Ograniczony katalog roboczy minimalizuje szkody, jeśli poprawne polecenie wskaże niewłaściwą lokalizację.

Czwarty mechanizm, nietechniczny, ale wart tyle co pozostałe trzy razem wzięte: wymagaj potwierdzenia przez człowieka dla każdej operacji destrukcyjnej lub nieodwracalnej. Model popełnia błędy z taką samą pewnością siebie, z jaką ma rację.

# 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"}

Implementacja jako funkcja niestandardowa

Samodzielna implementacja tego mechanizmu poprzez wywołania funkcji (function calling) oferuje przewagę, której nie powinieneś traktować jako ostateczności: walidacja żyje w Twoim kodzie. To Ty decydujesz o allowliście, logowaniu i krokach potwierdzenia, a także możesz przeprowadzać audyt wszystkiego. W przypadku narzędzia obarczonego tak dużym ryzykiem, utrzymanie kontroli nad punktem kontrolnym jest preferowane, nawet jeśli dostępna stanie się wersja natywna.

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)

Przepływy pracy automatyzacji

Automatyczne wdrażanie

Wdrażanie jest najbardziej wartościowym przypadkiem użycia, pod warunkiem że rozumiesz, co delegujesz. Model nie wymyśla procedury: łączy w łańcuch kroki, które zdefiniowałeś, weryfikuje wyniki pośrednie i zatrzymuje się przy każdej anomalii. Jest uważnym operatorem, a nie decydentem.

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")

Monitorowanie i alerty

Monitorowanie odwraca logikę reszty tej lekcji: polecenia są tutaj tylko do odczytu, więc są nieszkodliwe, a wartość tkwi w interpretacji. Model, który odczytuje zajętość dysku, obciążenie i logi błędów, wykrywa korelacje, które umykają przy izolowanych progach – co czyni to najbezpieczniejszym punktem wejścia do rozpoczęcia pracy z tym narzędziem.

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
)

Kluczowe wnioski

  • Narzędzie Shell łączy model z Twoją infrastrukturą
  • Wdrażaj allowlisty i blacklisty dla poleceń
  • Używaj limitów czasu i ograniczonych katalogów roboczych
  • Wywołania funkcji pozwalają zaimplementować Shell jako narzędzie niestandardowe
  • Łącz Shell z innymi narzędziami, aby tworzyć kompletne przepływy pracy DevOps