Compétence de Recherche Approfondie
Objectif
Cette compétence permet une recherche complète et connectée à internet sur n'importe quel sujet en utilisant l'API Deep Research d'OpenAI (modèle o4-mini-deep-research). Elle améliore intelligemment les prompts de recherche de l'utilisateur grâce à des questions de clarification interactives, garantit que les paramètres de recherche sont sauvegardés pour la reproductibilité, et exécute une recherche approfondie avec des capacités de recherche web complètes.
Quand Utiliser Cette Compétence
Déclenchez cette compétence lorsque :
- L'utilisateur demande une recherche sur un sujet spécifique
- L'utilisateur demande une analyse, une enquête ou une collecte d'informations complète
- L'utilisateur souhaite explorer un sujet avec une recherche web et un raisonnement
- L'utilisateur fournit une requête de recherche brève qui pourrait être affinée
- L'utilisateur veut comprendre l'état actuel, les tendances ou les comparaisons dans un domaine
Exemples de demandes utilisateur :
- "Recherche les solutions RAG open-source les plus efficaces avec des performances de benchmark élevées"
- "Quelles sont les dernières avancées en IA en 2025 ?"
- "J'ai besoin d'une analyse complète des systèmes de bases de données distribuées"
- "Trouve les meilleures pratiques pour implémenter la recherche vectorielle"
- "Étudie comment l'IA impacte l'industrie du génie logiciel"
Aperçu du Flux de Travail
Entrée Utilisateur
↓
Évaluation : Le prompt est-il trop court ?
↓
OUI → Poser des Questions d'Amélioration → Collecter les Réponses
↓ ↓
└───────→ Construire un Prompt Amélioré ←──┘
↓
Sauvegarder dans un Fichier Horodaté
↓
Exécuter deep_research.py
↓
Rapport de Sortie + Sources
↓
Présenter à l'Utilisateur
Comment Claude Doit Utiliser Cette Compétence
Important pour l'Efficacité des Tokens : La recherche approfondie prend 10 à 20 minutes. La compétence est conçue pour s'exécuter de manière synchrone (bloquante) sans vérifications d'état intermédiaires. Cette approche minimise l'utilisation des tokens pendant l'attente. Claude doit :
- Démarrer la recherche
- Attendre la fin (le sous-processus bloque automatiquement)
- Présenter les résultats finaux une fois terminée
Pas besoin de sondage périodique ou de mises à jour de statut pendant l'exécution.
Étape 1 : Accepter la Demande de Recherche
Recevez le prompt de recherche de l'utilisateur. Cela peut aller d'un prompt court ("Dernières tendances IA") à très détaillé ("Impact des modèles de langage sur la productivité des développeurs avec un accent sur 2024-2025").
Étape 2 : Exécuter le Script d'Orchestration
Exécutez le script d'orchestration principal de la compétence avec le prompt de recherche de l'utilisateur :
python3 scripts/run_deep_research.py "Votre prompt de recherche ici"
Le script se trouve dans scripts/run_deep_research.py au sein de l'installation de la compétence.
Étape 3 : Déroulement du Script
Le script automatise :
-
Évalue la complétude du prompt : Vérifie si le prompt est trop court ou générique (< 15 mots ou commence par "qu'est-ce que", "comment", etc.)
-
Pose des questions de clarification (si nécessaire) :
- Présente 2-3 questions ciblées adaptées au type de recherche
- Détecte si la recherche est technique ou générale en fonction des mots-clés
- Permet aux utilisateurs de choisir parmi des options prédéfinies (1-4) ou de fournir un texte personnalisé
- Les questions couvrent : Périmètre/Période, Niveau de profondeur, Domaines d'intérêt
-
Améliore le prompt : Combine le prompt original avec les réponses de l'utilisateur en paramètres de recherche structurés
-
Sauvegarde le fichier de prompt : Écrit le prompt amélioré dans
research_prompt_YYYYMMDD_HHMMSS.txtpour la reproductibilité -
Exécute la recherche approfondie : Lance le script central
deep_research.pyavec :- Modèle : o4-mini-deep-research (configurable via
--model) - Délai d'attente : 1800 secondes / 30 minutes (configurable via
--timeout) - Outils : Recherche web activée par défaut
- Modèle : o4-mini-deep-research (configurable via
Étape 4 : Présenter les Résultats à l'Utilisateur
Le script automatise :
- Sauvegarde du fichier markdown : Rapport de recherche avec sources sauvegardé dans
research_report_YYYYMMDD_HHMMSS.md - Affichage dans le terminal : Rapport de recherche complet avec formatage markdown
- Liste des sources web : URLs numérotées citées dans la recherche
- Confirmation de fin : Chemin où les fichiers de recherche ont été sauvegardés
Note d'Efficacité des Tokens : La recherche approfondie prend 10 à 20 minutes. Le script s'exécute de manière synchrone (bloquante) sans sondage intermédiaire, minimisant l'utilisation des tokens pendant l'attente.
Ressources Incluses
Scripts
scripts/run_deep_research.py (Point d'Entrée Principal)
Le script d'orchestration qui gère :
- L'évaluation de la qualité du prompt
- Les questions d'amélioration interactives (avec détection intelligente pour la recherche technique vs. générale)
- La sauvegarde et l'horodatage du prompt
- L'exécution de la recherche approfondie centrale
Fonctionnalités Clés :
- Amélioration intelligente : Ne pose des questions que si le prompt est court/générique
- Questions basées sur des modèles : Ensembles de questions différents pour la recherche technique vs. générale
- Entrée flexible : Options numérotées + saisie de texte personnalisée
- Gestion des erreurs : Messages utiles si deep_research.py n'est pas trouvé
Options disponibles :
python3 run_deep_research.py <prompt> [OPTIONS]
--no-enhance Ignorer les questions d'amélioration
--model <model> Modèle à utiliser (défaut : o4-mini-deep-research)
--timeout <secondes> Délai d'attente en secondes (défaut : 1800)
--output-dir <chemin> Où sauvegarder le fichier de prompt
assets/deep_research.py
Script central qui interface avec l'API Deep Research d'OpenAI. Gère :
- L'authentification API via OPENAI_API_KEY
- La création et l'exécution des requêtes
- Sauvegarde automatique en markdown : Sauvegarde les fichiers de rapport horodatés par défaut
- Le formatage de la sortie (rapport + sources avec métadonnées)
- La gestion des erreurs et les tentatives
Nouvelles options en ligne de commande :
--output-file <chemin> Chemin de fichier de sortie personnalisé
--no-save Désactiver la sauvegarde automatique en markdown
Références
references/workflow.md
Documentation détaillée du flux de travail couvrant :
- Le flux de travail complet de la compétence avec des exemples
- Les stratégies d'amélioration des prompts
- L'explication des paramètres de recherche
- Les conseils d'intégration pour Claude
- La référence de l'interface en ligne de commande
- La gestion des erreurs et le dépannage
- Les astuces pour une recherche efficace
Comportements Clés
Amélioration Intelligente du Prompt
La compétence détermine intelligemment si une amélioration est nécessaire :
- Déclenche l'amélioration pour les prompts de moins de 15 mots ou aux débuts génériques
- Ignore l'amélioration pour les prompts détaillés et spécifiques
- Permet aux utilisateurs de désactiver avec l'option
--no-enhance - Conscient des modèles : Utilise des questions différentes pour la recherche technique vs. générale
Paramètres de Recherche
Les prompts améliorés incluent :
- La requête utilisateur originale avec le contexte complet
- Les préférences de périmètre et de période
- Le niveau de profondeur souhaité (résumé, technique, implémentation, comparatif)
- Les domaines d'intérêt spécifiques (performance, coût, sécurité, etc.)
Ces paramètres aident le modèle de recherche approfondie à fournir des résultats plus ciblés et pertinents.
Reproductibilité
Chaque exécution de recherche :
- Sauvegarde le prompt exact utilisé dans un fichier horodaté
- Permet de tracer les décisions de recherche
- Autorise des recherches de suivi en utilisant les mêmes prompts ou des prompts modifiés
- Maintient une piste d'audit des paramètres de recherche
Exemples
Prompt Court avec Amélioration
Utilisateur : "Recherche les solutions RAG open-source les plus efficaces"
Comportement du script :
- Détecte un prompt court (8 mots) + mots-clés techniques ("open-source", "RAG")
- Pose des questions de recherche technique :
- Périmètre technologique : Open-source uniquement ? (Utilisateur : Oui)
- Métriques clés : Performance/benchmarks ? (Utilisateur : Vitesse et Précision)
- Cas d'utilisation : Déploiement en production ? (Utilisateur : Aspects multiples)
- Améliore en un prompt détaillé avec paramètres
- Sauvegarde et exécute la recherche approfondie
- Renvoie un rapport complet avec des benchmarks comparatifs et les URLs des sources
Prompt Détaillé Sans Amélioration
Utilisateur : "Analyse l'impact des grands modèles de langage sur la productivité des développeurs de logiciels en 2024-2025, en se concentrant sur les outils de génération de code, la programmation en binôme et les métriques de productivité."
Comportement du script :
- Détecte un prompt détaillé (31 mots) avec un périmètre/un focus spécifique
- Ignore les questions d'amélioration
- Sauvegarde et exécute immédiatement la recherche approfondie
- Renvoie une analyse ciblée correspondant aux spécifications de l'utilisateur
Prérequis
- Python 3.7+
- Clé API OpenAI (définie via la variable d'environnement
OPENAI_API_KEYou le fichier.env) - Connexion internet (pour la recherche web)
- 30+ minutes pour la réalisation de la recherche (délai d'attente configurable)
Flux de Travail Efficace en Tokens
Optimisation des Tâches Longues
Les requêtes de recherche approfondie prennent généralement 10 à 20 minutes. Cette compétence est optimisée pour minimiser l'utilisation des tokens pendant les longues attentes :
Comment ça fonctionne :
- Exécution synchrone : Le script s'exécute comme un sous-processus bloquant (pas de sondage en arrière-plan)
- Aucune vérification intermédiaire : Claude attend silencieusement la fin sans mises à jour de statut
- Sortie unique : Les résultats sont présentés une seule fois à la fin
- Sauvegarde automatique : Les fichiers Markdown sont sauvegardés automatiquement, sans intervention manuelle
Économies de tokens :
- Approche traditionnelle : Vérifier le statut toutes les 30 secondes = ~40 vérifications × 500 tokens = ~20 000 tokens gaspillés
- Cette approche : Attente unique = ~1 000 tokens au total
Gestion Automatique des Fichiers
La compétence génère et sauvegarde automatiquement des fichiers :
Fichiers générés :
research_prompt_YYYYMMDD_HHMMSS.txt- Prompt de recherche amélioré avec paramètresresearch_report_YYYYMMDD_HHMMSS.md- Rapport Markdown complet avec :- Sections de recherche (historique, cognitive, culturelle, etc.)
- Citations de sources numérotées
- Pied de page des métadonnées (date, modèle)
Options de personnalisation :
# Emplacement de sortie personnalisé
python3 deep_research.py --prompt-file prompt.txt --output-file my_research.md
# Désactiver la sauvegarde automatique (sortie terminal uniquement)
python3 deep_research.py --prompt-file prompt.txt --no-save
Dépannage
OPENAI_API_KEY Manquante
Erreur : "OPENAI_API_KEY manquante"
Solution :
- Définir la variable d'environnement :
export OPENAI_API_KEY="votre-clé" - Ou créer un fichier
.envdans le répertoire de travail avecOPENAI_API_KEY=votre-clé
deep_research.py Introuvable
Erreur : "Impossible de trouver deep_research.py"
Solution :
- Assurez-vous que la compétence est correctement installée avec ses assets
- Le script recherche dans : dossier des assets de la compétence → répertoire courant → répertoire parent
Délai d'Attente de la Recherche
Erreur : La requête expire après 30 minutes
Solution :
- Augmenter le délai d'attente :
--timeout 5400(90 minutes) - Simplifier le prompt pour réduire le périmètre de la recherche
- Exécuter pendant les heures creuses pour des réponses API potentiellement plus rapides