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