Fehlerbehandlung und Fehlertoleranz bei Skills

Ein Skill, der nur unter idealen Bedingungen läuft, ist fragil.

Ein robuster Skill muss häufige Fehler vorhersehen, klares Feedback geben und sich nach Möglichkeit automatisch erholen.


Drei Ebenen der Fehlerbehandlung

Stufe Ort Behandlungsmethode
Fehler bei der Eingabevalidierung Vor der Ausführung Eingabe prüfen; wenn ungültig, direkt ablehnen und den Grund erklären
Laufzeitfehler Während der Skriptausführung Ausnahmen abfangen und strukturierte Fehlerinformationen ausgeben
Abnormale Ergebnisse Nach der Ausführung Überprüfen Sie, ob die Ausgabe den Erwartungen entspricht; falls nicht, lösen Sie den Korrekturprozess aus

Definieren von Fehlerbehandlungsstrategien in SKILL.md

SKILL.md sollte einen klaren Abschnitt zur Fehlerbehandlung enthalten, der Claude sagt, was zu tun ist, wenn Probleme auftreten.

Beispiel

## Fehlerbehandlung

### Eingabeprobleme
- Datei existiert nicht: Informieren Sie den Benutzer, dass der Dateipfad falsch ist, und bitten Sie ihn, die Datei erneut hochzuladen
- Dateiformat nicht unterstützt: Listen Sie die unterstützten Formate (pdf, docx, txt) auf und bitten Sie den Benutzer, die Datei zu konvertieren und es erneut zu versuchen
- Datei ist leer: Informieren Sie den Benutzer, dass der Dateiinhalt leer ist und nicht verarbeitet werden kann

### Ausführungsprobleme
- Skriptausführung fehlgeschlagen: Zeigen Sie dem Benutzer die vollständige Fehlerinformation an, verbergen Sie sie nicht
- Abhängigkeiten nicht installiert: Versuchen Sie zuerst die automatische Installation (pipinstall), wenn das fehlschlägt, informieren Sie den Benutzer, manuell zu installieren
- Timeout: Wenn es60Sekunden ohne Abschluss überschreitet, gib den aktuellen Fortschritt aus und frage den Benutzer, ob weiter gewartet werden soll

### Ergebnisprobleme
- Ausgabedatei ist leer: Überprüfe die Verarbeitungslogik erneut und erkläre dem Benutzer mögliche Ursachen
- Ausgabeformat entspricht nicht den Erwartungen: Zeige die tatsächliche Ausgabe und frage den Benutzer, ob er zufrieden ist

Standardmuster für Fehlerbehandlung in Skripten

Python-Skripte sollten eine try-except-Struktur verwenden und einheitlich JSON mit einem Statusfeld zurückgeben.

Beispiel

# Dateipfad: scripts/error_handling_demo.py
import json
import sys
import os

class SkillError(Exception):
    """Basisklasse für benutzerdefinierte Skill-Ausnahmen"""
    def __init__(self, message: str, code: str):
        self.message = message
        self.code    = code     # Fehlercodes, damit das Programm den Fehlertyp bestimmen kann
        super().__init__(message)

class InputError(SkillError):
    """Eingabevalidierungsfehler"""
    pass

class ProcessError(SkillError):
    """Verarbeitungsfehler"""
    pass

def validate_input(file_path: str) -> None:
    """Eingabe validieren, bei Fehler InputError auslösen"""
    if not file_path:
        raise InputError("Kein Dateipfad angegeben", "MISSING_FILE")
    if not os.path.exists(file_path):
        raise InputError(f"Datei existiert nicht: {file_path}", "FILE_NOT_FOUND")
    if os.path.getsize(file_path) == 0:
        raise InputError(f"Dateiinhalt ist leer: {file_path}", "EMPTY_FILE")

def process(file_path: str) -> dict:
    """Hauptverarbeitungslogik"""
    try:
        validate_input(file_path)

        with open(file_path, "r", encoding="utf-8") as f:
            content = f.read()

        # Tatsächliche Verarbeitungslogik (hier vereinfacht auf Zeilenzählung)
        lines = content.split("\n")
        return {
            "status": "success",
            "data": {
                "file": file_path,
                "lines": len(lines),
                "chars": len(content)
            }
        }

    except InputError as e:
        # Eingabefehler: Der Benutzer kann ihn korrigieren und erneut versuchen
        return {
            "status":  "input_error",
            "code":    e.code,
            "message": e.message,
            "hint":    "Bitte prüfen Sie, ob der Dateipfad korrekt ist und ob die Datei existiert und nicht leer ist"
        }
    except UnicodeDecodeError:
        # Kodierungsfehler: spezifische Korrekturvorschläge bereitstellen
        return {
            "status":  "process_error",
            "code":    "ENCODING_ERROR",
            "message": "Die Datei ist nicht UTF-8-kodiert und kann nicht gelesen werden",
            "hint":    "Bitte speichern Sie die Datei in UTF-8-Kodierung und versuchen Sie es erneut"
        }
    except Exception as e:
        # Unerwarteter Fehler: vollständig protokollieren, um das Debuggen zu erleichtern
        return {
            "status":  "unexpected_error",
            "code":    "UNKNOWN",
            "message": str(e),
            "hint":    "Bitte geben Sie die oben genannten Fehlerinformationen an den Entwickler weiter"
        }

if __name__ == "__main__":
    file_path = sys.argv[1] if len(sys.argv) > 1 else ""
    result    = process(file_path)
    print(json.dumps(result, ensure_ascii=False, indent=2))
# 文件存在时的成功输出:
{
  "status": "success",
  "data": {
    "file": "/mnt/user-data/uploads/example.txt",
    "lines": 128,
    "chars": 5432
  }
}

# 文件不存在时的错误输出:
{
  "status": "input_error",
  "code": "FILE_NOT_FOUND",
  "message": "文件不存在:/mnt/user-data/uploads/missing.txt",
  "hint": "请检查文件路径是否正确,文件是否存在且非空"
}

Fehlertoleranzmuster für die automatische Installation von Abhängigkeiten

Wenn die Python-Pakete, von denen ein Skript abhängt, nicht installiert sind, kann das Skript automatisch versuchen, sie zu installieren.

Beispiel

# Dateipfad: scripts/auto_install_demo.py
import subprocess
import sys

def ensure_package(package_name: str, import_name: str = None) -> bool:
    """
Stellt sicher, dass das Python-Paket installiert ist; falls nicht, wird es automatisch installiert

Parameter:
package_name: der für die pip-Installation verwendete Paketname (z. B. "python-docx")
import_name: der für den Import verwendete Name (z. B. "docx"), standardmäßig identisch mit package_name
    """

    import_name = import_name or package_name
    try:
        __import__(import_name)
        return True  # Bereits installiert
    except ImportError:
        print(f"Installiere Abhängigkeit: {package_name}...")
        result = subprocess.run(
            [sys.executable, "-m", "pip", "install", package_name,
             "--break-system-packages", "--quiet"],
            capture_output=True, text=True
        )
        if result.returncode == 0:
            print(f"Installation erfolgreich: {package_name}")
            return True
        else:
            print(f"Installation fehlgeschlagen: {package_name}")
            print(result.stderr)
            return False

# Anwendungsbeispiel: Stelle sicher, dass alle Abhängigkeiten zu Beginn des Skripts bereit sind.
if not ensure_package("pandas"):
    sys.exit(1)
if not ensure_package("openpyxl"):
    sys.exit(1)

# Nachdem die Abhängigkeiten bereit sind, normal importieren
import pandas as pd
print("Alle Abhängigkeiten sind bereit, Ausführung wird gestartet...")

Die automatische Installation eignet sich nur für Entwicklung und leichtgewichtige Szenarien. In Produktions-Skills sollten Abhängigkeiten dokumentiert und vom Benutzer vorinstalliert werden, statt zur Laufzeit automatisch installiert zu werden.


Richtlinien für das Schreiben von Fehlermeldungen

Gute Fehlermeldungen helfen Benutzern, Probleme schnell zu lokalisieren, während schlechte Fehlermeldungen Menschen nur verwirren.

Dimension Schlechte Formulierung Gute Formulierung
Beschreibe das Problem "Ein Fehler ist aufgetreten" "Die Datei report.csv existiert nicht im Upload-Verzeichnis"
Erklären Sie den Grund (None) "Der Dateiname ist möglicherweise falsch geschrieben, oder die Datei wurde noch nicht hochgeladen"
Aktion angeben (None) "Bitte laden Sie die Datei erneut hoch, oder prüfen Sie, ob der Dateiname korrekt ist"

Beispiel

# Schlechte Fehlermeldung
raise Exception("Error")

# Gute Fehlermeldung
raise InputError(
    "Die Datei example_data.csv wurde im Upload-Verzeichnis nicht gefunden."
    "Mögliche Gründe: Der Dateiname ist falsch geschrieben, oder die Datei wurde noch nicht hochgeladen."
    "Bitte laden Sie die Datei erneut hoch und versuchen Sie es erneut.",
    code="FILE_NOT_FOUND"
)
Andere Erweiterungen