Gestion des erreurs et tolérance aux pannes des compétences
Une compétence qui ne fonctionne que dans des conditions idéales est fragile.
Une compétence robuste doit anticiper les erreurs courantes, fournir un retour clair et récupérer automatiquement dans la mesure du possible.
Trois niveaux de gestion des erreurs
| Niveau | Emplacement | Méthode de traitement |
|---|---|---|
| Erreurs de validation des entrées | Avant l'exécution | Vérifiez l'entrée ; si elle est invalide, rejetez-la directement et expliquez la raison |
| Erreurs d'exécution | Pendant l'exécution du script | Interceptez les exceptions et produisez des informations d'erreur structurées |
| Résultats anormaux | Après l'exécution | Vérifier si la sortie correspond aux attentes ; si ce n'est pas le cas, déclencher le processus de remédiation |
Définir des stratégies de gestion des erreurs dans SKILL.md
SKILL.md doit inclure une section claire sur la gestion des erreurs qui indique à Claude quoi faire en cas de problème.
Exemple
## Gestion des erreurs
### Problèmes d'entrée
- Le fichier n'existe pas : informer l'utilisateur que le chemin du fichier est incorrect et lui demander de le téléverser à nouveau
- Format de fichier non pris en charge : lister les formats pris en charge (pdf, docx, txt) et demander à l'utilisateur de convertir et de réessayer
- Le fichier est vide : informer l'utilisateur que le contenu du fichier est vide et ne peut pas être traité
### Problèmes d'exécution
- Échec de l'exécution du script : afficher les informations complètes sur l'erreur à l'utilisateur, ne pas les masquer
- Dépendances non installées : essayer d'abord l'installation automatique (pipinstall), si cela échoue, informer l'utilisateur qu'il doit installer manuellement
- Délai d'attente : s'il dépasse60secondes sans se terminer, affichez la progression actuelle et demandez à l'utilisateur s'il souhaite continuer à attendre
### Problèmes de résultat
- Le fichier de sortie est vide : revérifiez la logique de traitement et expliquez les raisons possibles à l'utilisateur
- Le format de sortie ne correspond pas aux attentes : montrez la sortie réelle et demandez à l'utilisateur s'il est satisfait
### Problèmes d'entrée
- Le fichier n'existe pas : informer l'utilisateur que le chemin du fichier est incorrect et lui demander de le téléverser à nouveau
- Format de fichier non pris en charge : lister les formats pris en charge (pdf, docx, txt) et demander à l'utilisateur de convertir et de réessayer
- Le fichier est vide : informer l'utilisateur que le contenu du fichier est vide et ne peut pas être traité
### Problèmes d'exécution
- Échec de l'exécution du script : afficher les informations complètes sur l'erreur à l'utilisateur, ne pas les masquer
- Dépendances non installées : essayer d'abord l'installation automatique (pipinstall), si cela échoue, informer l'utilisateur qu'il doit installer manuellement
- Délai d'attente : s'il dépasse60secondes sans se terminer, affichez la progression actuelle et demandez à l'utilisateur s'il souhaite continuer à attendre
### Problèmes de résultat
- Le fichier de sortie est vide : revérifiez la logique de traitement et expliquez les raisons possibles à l'utilisateur
- Le format de sortie ne correspond pas aux attentes : montrez la sortie réelle et demandez à l'utilisateur s'il est satisfait
Modèles standard de gestion des erreurs dans les scripts
Les scripts Python doivent utiliser une structure try-except et retourner uniformément du JSON contenant un champ status.
Exemple
# Chemin de fichier : scripts/error_handling_demo.py
import json
import sys
import os
class SkillError(Exception):
"""Classe de base d'exception personnalisée de Skill"""
def __init__(self, message: str, code: str):
self.message = message
self.code = code # Codes d'erreur pour aider le programme à déterminer le type d'erreur
super().__init__(message)
class InputError(SkillError):
"""Erreur de validation d'entrée"""
pass
class ProcessError(SkillError):
"""Erreur de traitement"""
pass
def validate_input(file_path: str) -> None:
"""Valider l'entrée, lever InputError en cas d'erreur"""
if not file_path:
raise InputError("Aucun chemin de fichier fourni", "MISSING_FILE")
if not os.path.exists(file_path):
raise InputError(f"Le fichier n'existe pas : {file_path}", "FILE_NOT_FOUND")
if os.path.getsize(file_path) == 0:
raise InputError(f"Le contenu du fichier est vide : {file_path}", "EMPTY_FILE")
def process(file_path: str) -> dict:
"""Logique de traitement principale"""
try:
validate_input(file_path)
with open(file_path, "r", encoding="utf-8") as f:
content = f.read()
# Logique de traitement réelle (simplifiée ici en comptage de lignes)
lines = content.split("\n")
return {
"status": "success",
"data": {
"file": file_path,
"lines": len(lines),
"chars": len(content)
}
}
except InputError as e:
# Erreur d'entrée : l'utilisateur peut la corriger et réessayer
return {
"status": "input_error",
"code": e.code,
"message": e.message,
"hint": "Veuillez vérifier que le chemin du fichier est correct, et que le fichier existe et n'est pas vide"
}
except UnicodeDecodeError:
# Erreur d'encodage : fournissez des suggestions de correction spécifiques
return {
"status": "process_error",
"code": "ENCODING_ERROR",
"message": "L'encodage du fichier n'est pas UTF-8 et le fichier ne peut pas être lu",
"hint": "Veuillez enregistrer le fichier encodé en UTF-8 et réessayer"
}
except Exception as e:
# Erreur inattendue : enregistrez-la intégralement pour faciliter le débogage
return {
"status": "unexpected_error",
"code": "UNKNOWN",
"message": str(e),
"hint": "Veuillez fournir les informations d'erreur ci-dessus au développeur"
}
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))
import json
import sys
import os
class SkillError(Exception):
"""Classe de base d'exception personnalisée de Skill"""
def __init__(self, message: str, code: str):
self.message = message
self.code = code # Codes d'erreur pour aider le programme à déterminer le type d'erreur
super().__init__(message)
class InputError(SkillError):
"""Erreur de validation d'entrée"""
pass
class ProcessError(SkillError):
"""Erreur de traitement"""
pass
def validate_input(file_path: str) -> None:
"""Valider l'entrée, lever InputError en cas d'erreur"""
if not file_path:
raise InputError("Aucun chemin de fichier fourni", "MISSING_FILE")
if not os.path.exists(file_path):
raise InputError(f"Le fichier n'existe pas : {file_path}", "FILE_NOT_FOUND")
if os.path.getsize(file_path) == 0:
raise InputError(f"Le contenu du fichier est vide : {file_path}", "EMPTY_FILE")
def process(file_path: str) -> dict:
"""Logique de traitement principale"""
try:
validate_input(file_path)
with open(file_path, "r", encoding="utf-8") as f:
content = f.read()
# Logique de traitement réelle (simplifiée ici en comptage de lignes)
lines = content.split("\n")
return {
"status": "success",
"data": {
"file": file_path,
"lines": len(lines),
"chars": len(content)
}
}
except InputError as e:
# Erreur d'entrée : l'utilisateur peut la corriger et réessayer
return {
"status": "input_error",
"code": e.code,
"message": e.message,
"hint": "Veuillez vérifier que le chemin du fichier est correct, et que le fichier existe et n'est pas vide"
}
except UnicodeDecodeError:
# Erreur d'encodage : fournissez des suggestions de correction spécifiques
return {
"status": "process_error",
"code": "ENCODING_ERROR",
"message": "L'encodage du fichier n'est pas UTF-8 et le fichier ne peut pas être lu",
"hint": "Veuillez enregistrer le fichier encodé en UTF-8 et réessayer"
}
except Exception as e:
# Erreur inattendue : enregistrez-la intégralement pour faciliter le débogage
return {
"status": "unexpected_error",
"code": "UNKNOWN",
"message": str(e),
"hint": "Veuillez fournir les informations d'erreur ci-dessus au développeur"
}
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": "请检查文件路径是否正确，文件是否存在且非空"
}
Modèle de tolérance aux pannes pour l'installation automatique des dépendances
Lorsque les paquets Python dont dépend un script ne sont pas installés, le script peut automatiquement tenter de les installer.
Exemple
# Chemin du fichier : scripts/auto_install_demo.py
import subprocess
import sys
def ensure_package(package_name: str, import_name: str = None) -> bool:
"""
S'assurer que le paquet Python est installé ; sinon, l'installer automatiquement
Paramètres :
package_name : le nom du paquet utilisé pour l'installation avec pip (par exemple, "python-docx")
import_name : le nom utilisé pour l'import (par exemple, "docx"), par défaut identique à package_name
"""
import_name = import_name or package_name
try:
__import__(import_name)
return True # Déjà installé
except ImportError:
print(f"Installation de la dépendance : {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 réussie : {package_name}")
return True
else:
print(f"Échec de l'installation : {package_name}")
print(result.stderr)
return False
# Exemple d'utilisation : s'assurer que toutes les dépendances sont prêtes au début du script
if not ensure_package("pandas"):
sys.exit(1)
if not ensure_package("openpyxl"):
sys.exit(1)
# Une fois les dépendances prêtes, importer normalement
import pandas as pd
print("Toutes les dépendances sont prêtes, démarrage de l'exécution...")
import subprocess
import sys
def ensure_package(package_name: str, import_name: str = None) -> bool:
"""
S'assurer que le paquet Python est installé ; sinon, l'installer automatiquement
Paramètres :
package_name : le nom du paquet utilisé pour l'installation avec pip (par exemple, "python-docx")
import_name : le nom utilisé pour l'import (par exemple, "docx"), par défaut identique à package_name
"""
import_name = import_name or package_name
try:
__import__(import_name)
return True # Déjà installé
except ImportError:
print(f"Installation de la dépendance : {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 réussie : {package_name}")
return True
else:
print(f"Échec de l'installation : {package_name}")
print(result.stderr)
return False
# Exemple d'utilisation : s'assurer que toutes les dépendances sont prêtes au début du script
if not ensure_package("pandas"):
sys.exit(1)
if not ensure_package("openpyxl"):
sys.exit(1)
# Une fois les dépendances prêtes, importer normalement
import pandas as pd
print("Toutes les dépendances sont prêtes, démarrage de l'exécution...")
L'installation automatique ne convient qu'au développement et aux scénarios légers. Dans les Skills de production, les dépendances doivent être documentées et préinstallées par l'utilisateur, plutôt que d'être installées automatiquement à l'exécution.
Directives pour la rédaction des messages d'erreur
De bons messages d'erreur aident les utilisateurs à localiser rapidement les problèmes, tandis que de mauvais messages d'erreur ne font que semer la confusion.
| Dimension | Mauvaise rédaction | Bonne rédaction |
|---|---|---|
| Décrire le problème | "Une erreur est survenue" | "Le fichier report.csv n'existe pas dans le répertoire de téléversement" |
| Expliquez la raison | (None) | "Le nom du fichier est peut-être mal orthographié, ou le fichier n'a pas encore été téléversé" |
| Indiquez l'action | (None) | "Veuillez téléverser à nouveau le fichier, ou vérifier si le nom du fichier est correct" |
Exemple
# Mauvais message d'erreur
raise Exception("Error")
# Bon message d'erreur
raise InputError(
"Le fichier example_data.csv n'a pas été trouvé dans le répertoire de téléversement."
"Raisons possibles : le nom du fichier est mal orthographié, ou le fichier n'a pas encore été téléversé."
"Veuillez téléverser à nouveau le fichier et réessayer.",
code="FILE_NOT_FOUND"
)
raise Exception("Error")
# Bon message d'erreur
raise InputError(
"Le fichier example_data.csv n'a pas été trouvé dans le répertoire de téléversement."
"Raisons possibles : le nom du fichier est mal orthographié, ou le fichier n'a pas encore été téléversé."
"Veuillez téléverser à nouveau le fichier et réessayer.",
code="FILE_NOT_FOUND"
)