Overview
Le SDK Copilot communique avec l’interface CLI via JSON-RPC protocole. Les fonctionnalités doivent être explicitement exposées via ce protocole pour être disponibles dans le Kit de développement logiciel (SDK). De nombreuses fonctionnalités cli interactives sont spécifiques au terminal et non disponibles par programme.
Comparaison des fonctionnalités
✅ Disponible dans le Kit de développement logiciel (SDK)
| Fonctionnalité | méthode du SDK | Remarques |
|---|---|---|
| Gestion de session | ||
| Créer une session | createSession() | Prise en charge complète de la configuration |
| Reprendre la session | resumeSession() | Avec des espaces de travail de session infinis |
| Déconnecter la session | disconnect() | Libérer des ressources en mémoire |
| Détruire la session (déconseillée) | destroy() | Utilisation de disconnect() à la place |
| Supprimer une session | deleteSession() | Supprimer du stockage |
| Répertorier les sessions | listSessions() | Toutes les sessions stockées |
| Obtenir la dernière session | getLastSessionId() | Pour reprendre rapidement |
| Obtenir une session de premier plan | getForegroundSessionId() | Coordination multisession |
| Définir une session de premier plan | setForegroundSessionId() | Coordination multisession |
| Messaging | ||
| Envoyer un message | send() | Avec des pièces jointes |
| Envoyer et attendre | sendAndWait() | Bloque jusqu'à ce que ce soit terminé. |
| Direction (mode immédiat) | send({ mode: "immediate" }) | Injecter mi-tour sans abandon |
| Mise en file d’attente (mode file d’attente) | send({ mode: "enqueue" }) | Mémoire tampon pour le traitement séquentiel (par défaut) |
| Pièces jointes | send({ attachments: [{ type: "file", path }] }) | Images codées automatiquement et redimensionnées |
| Pièces jointes de répertoire | send({ attachments: [{ type: "directory", path }] }) | Attacher le contexte de répertoire |
| Obtenir l’historique | getEvents() | Tous les événements de session |
| annuler | abort() | Annuler la demande en cours d’exécution |
| Outils | ||
| Inscrire des outils personnalisés | registerTools() | Prise en charge complète du schéma JSON |
| Contrôle d’autorisation de l’outil | ||
onPreToolUse Accroche | Autoriser/refuser/demander | |
| Modification des résultats de l’outil | ||
onPostToolUse Accroche | Transformer les résultats | |
| Outils disponibles ou exclus | ||
availableTools, excludedTools configuration | Outils de filtre | |
| Modèles | ||
| Lister les modèles | listModels() | Avec les fonctionnalités, la facturation, la politique |
| Définir le modèle (lors de la création) | ||
model dans la configuration de session | Par session | |
| Changer de modèle (mi-session) | session.setModel() | Également via session.rpc.model.switchTo() |
| Obtenir le modèle actuel | session.rpc.model.getCurrent() | Interroger un modèle actif |
| Effort de raisonnement | ||
reasoningEffort Config | Pour les modèles pris en charge | |
| Agent Mode | ||
| Obtenir le mode actuel | session.rpc.mode.get() | Retourne le mode actuel |
| Définir le mode | session.rpc.mode.set() | Basculer entre les modes |
| Gestion du plan | ||
| Lire le plan | session.rpc.plan.read() | Obtenez le contenu et le chemin d'accès du fichier plan.md |
| Mettre à jour le plan | session.rpc.plan.update() | Écrire le contenu de plan.md |
| Suppression de programme | session.rpc.plan.delete() | Supprimer plan.md |
| Fichiers de l’espace de travail | ||
| Répertorier les fichiers d’espace de travail | session.rpc.workspace.listFiles() | Fichiers dans l’espace de travail de session |
| Lire le fichier d’espace de travail | session.rpc.workspace.readFile() | Lire le contenu du fichier |
| Créer un fichier d’espace de travail | session.rpc.workspace.createFile() | Créer un fichier dans l’espace de travail |
| Authentication | ||
| Obtenir l’état de l’authentification | getAuthStatus() | Vérifier l’état de connexion |
| Utiliser un jeton | ||
gitHubToken option | Authentification programmatique | |
| Connectivité | ||
| Ping | client.ping() | Vérification de l'état avec l’horodatage du serveur |
| Obtenir l’état du serveur | client.getStatus() | Informations sur la version du protocole et le serveur |
| Serveurs MCP | ||
| Serveurs locaux ou stdio | ||
mcpServers Config | Créer des processus | |
| HTTP/SSE distant | ||
mcpServers Config | Se connecter aux services | |
| Hooks | ||
| Pré-utilisation de l’outil | onPreToolUse | Autorisation, modification des arguments |
| Après utilisation de l’outil (succès) | onPostToolUse | Modifier les résultats |
| Après l’utilisation de l’outil (échec) | onPostToolUseFailure | Surveiller les appels d’outils ayant échoué, injecter des instructions de réessai |
| Message d'invite | onUserPromptSubmitted | Modifier les invites |
| Début/fin de session | ||
onSessionStart, onSessionEnd | Cycle de vie avec source/raison | |
| Gestion des erreurs | onErrorOccurred | Gestion personnalisée |
| Événements | ||
| Tous les événements de session | ||
on(), once() | 40+ types d’événements | |
| Diffusion en continu | streaming: true | Événements delta |
| Configuration de session | ||
| Agents personnalisés | ||
customAgents Config | Définir des agents spécialisés | |
| Message système | ||
systemMessage Config | Ajouter ou remplacer | |
| Fournisseur personnalisé | ||
provider Config | Prise en charge de BYOK | |
| Sessions infinies | ||
infiniteSessions Config | Compactage automatique | |
| Gestionnaire d’autorisations | onPermissionRequest | Approuver/refuser des demandes |
| Gestionnaire d’entrée utilisateur | onUserInputRequest | Gérer ask_user |
| Compétences | ||
skillDirectories Config | Compétences personnalisées | |
| Compétences désactivées | ||
disabledSkills Config | Désactiver des compétences spécifiques | |
| Répertoire de configuration | ||
configDir Config | Remplacer l’emplacement de configuration par défaut | |
| Nom du client | ||
clientName Config | Identifier l’application dans User-Agent | |
| Répertoire de travail | ||
workingDirectory Config | Définir la session cwd | |
| Version expérimentale | ||
| Gestion des agents | session.rpc.agent.* | Répertorier, sélectionner, désélectionner, obtenir l’agent actuel |
| Mode flotte | session.rpc.fleet.start() | Exécution de sous-agent parallèle |
| Compactage manuel | session.rpc.history.compact() | Compactage du déclencheur à la demande |
| Troncation de l’historique | session.rpc.history.truncate() | Supprimer les événements à partir d’un point donné |
| Duplication de session | server.rpc.sessions.fork() | Bifurquer une session à partir d’un point de l’historique |
❌ Non disponible dans le Kit de développement logiciel (CLI uniquement)
| Fonctionnalité | Commande/option en ligne de commande | Reason |
|---|---|---|
| Exportation de session | ||
| Exporter vers le fichier | ||
--share, /share | Non dans le protocole | |
| Exporter vers gist | ||
--share-gist, /share gist | Non dans le protocole | |
| Interface utilisateur interactive | ||
| Commandes slash | ||
/help, /clear, /exit, etc. | TUI uniquement | |
| Boîte de dialogue de sélection d’agents | /agent | Interface utilisateur interactive |
| Boîte de dialogue mode Diff | /diff | Interface utilisateur interactive |
| Boîte de dialogue Commentaires | /feedback | Interface utilisateur interactive |
| Sélecteur de thème | /theme | Interface utilisateur du terminal |
| Sélecteur de modèles | /model | Interface utilisateur interactive (utiliser le Kit de développement logiciel (SDK setModel() ) à la place |
| Copier dans le Presse-papiers | /copy | Spécifique au terminal |
| Gestion du contexte | /context | Interface utilisateur interactive |
| Recherche & Histoire | ||
| Recherche approfondie | /research | Flux de travail TUI avec recherche web |
| Outils d’historique des sessions | /chronicle | Standup, conseils, amélioration, réindexation |
| Fonctionnalités de terminal | ||
| Sortie de couleur | --no-color | Spécifique au terminal |
| Mode lecteur d’écran | --screen-reader | Accessibilité |
| Affichage enrichi des différences | --plain-diff | Rendu du terminal |
| Bannière de démarrage | --banner | Élément visuel |
| Mode diffusion | /streamer-mode | Mode d’affichage TUI |
| Tampon d'écran alternatif | ||
--alt-screen, --no-alt-screen | Rendu du terminal | |
| Prise en charge de la souris | ||
--mouse, --no-mouse | Entrée du terminal | |
| Raccourcis de chemin d'accès/autorisation | ||
| Autoriser tous les chemins d’accès | --allow-all-paths | Utiliser le gestionnaire d’autorisations |
| Autoriser toutes les URL | --allow-all-urls | Utiliser le gestionnaire d’autorisations |
| Autoriser toutes les autorisations | ||
--yolo, --allow-all, /allow-all | Utiliser le gestionnaire d’autorisations | |
| Autorisations d’outil granulaires | ||
--allow-tool, --deny-tool | Utiliser un onPreToolUse hook | |
| Contrôle d’accès d’URL | ||
--allow-url, --deny-url | Utiliser le gestionnaire d’autorisations | |
| Réinitialiser les outils autorisés | /reset-allowed-tools | Commande TUI |
| Gestion des répertoires | ||
| Ajouter un répertoire | ||
/add-dir, --add-dir | Configurer dans la session | |
| Répertorier les répertoires | /list-dirs | Commande TUI |
| Modifier le répertoire | /cwd | Commande TUI |
| Gestion du plug-in/MCP | ||
| Commandes de plug-in | /plugin | Gestion interactive |
| Gestion du serveur MCP | /mcp | Interface utilisateur interactive |
| Gestion des comptes | ||
| Flux de connexion | ||
/login, copilot auth login | Flux d’appareil OAuth | |
| Déconnexion | ||
/logout, copilot auth logout | Interface CLI directe | |
| Informations de l′utilisateur | /user | Commande TUI |
| Opérations de session | ||
| Supprimer la conversation | /clear | TUI uniquement |
| Vue en plan | /plan | TUI uniquement (utiliser le Kit de développement logiciel (SDK session.rpc.plan.* ) à la place |
| Gestion des sessions | ||
/session, /resume, /rename | Flux de travail TUI | |
| Mode flotte (interactif) | /fleet | TUI uniquement (utiliser le Kit de développement logiciel (SDK session.rpc.fleet.start() ) à la place |
| Gestion des compétences | ||
| Gérer les compétences | /skills | Interface utilisateur interactive |
| Gestion des tâches | ||
| Afficher les tâches en arrière-plan | /tasks | Commande TUI |
| Statistiques d’utilisation | ||
| Utilisation des jetons | /usage | S’abonner aux événements d’utilisation |
| Évaluation du code | ||
| Examiner les modifications | /review | Commande TUI |
| Délégation | ||
| Déléguer au service des relations publiques | /delegate | Flux de travail TUI |
| Configuration du terminal | ||
| Intégration de Shell | /terminal-setup | Spécifique à l’interpréteur de commandes |
| Développement | ||
| Activer/désactiver les fonctionnalités expérimentales | ||
/experimental, --experimental | Indicateur d’exécution | |
| Gestion des instructions personnalisées | --no-custom-instructions | Indicateur CLI |
| Diagnostiquer la session | /diagnose | Commande TUI |
| Afficher/gérer les instructions | /instructions | Commande TUI |
| Collecter les journaux de débogage | /collect-debug-logs | Outil de diagnostic |
| Réindexer l’espace de travail | /reindex | Commande TUI |
| Intégration de l’IDE | /ide | Flux de travail spécifique à l’IDE |
| Mode non interactif | ||
| Mode d'interaction | ||
-p, --prompt | Exécution en un seul coup | |
| Invite interactive | ||
-i, --interactive | Exécution automatique, puis interactive | |
| Sortie silencieuse | ||
-s, --silent | Compatible avec les scripts | |
| Continuer la session | --continue | Reprendre la version la plus récente |
| Sélection de l’agent | --agent <agent> | Indicateur CLI |
Solutions de contournement
Exportation de session
L’option --share n’est pas disponible via le Kit de développement logiciel (SDK). Contournements:
-
Collectez manuellement des événements : abonnez-vous aux événements de session et générez votre propre exportation :
const events: SessionEvent[] = []; session.on((event) => events.push(event)); // ... after conversation ... const messages = await session.getEvents(); // Format as markdown yourself -
Utilisez l’interface CLI directement pour l’exportation : exécutez l’interface CLI avec
--sharepour les exportations ponctuelles.
Contrôle d’autorisation
Le Kit de développement logiciel (SDK) utilise un modèle d’autorisation refuser par défaut . Toutes les demandes d’autorisation (écritures de fichiers, commandes d’interpréteur de commandes, extractions d’URL, etc.) sont refusées, sauf si votre application fournit un onPermissionRequest gestionnaire.
Au lieu de --allow-all-paths ou --yolo, utilisez le gestionnaire d’autorisations :
const session = await client.createSession({
onPermissionRequest: approveAll,
});
Suivi de l’utilisation des jetons
Au lieu de /usage, abonnez-vous aux événements d’utilisation :
session.on("assistant.usage", (event) => {
console.log("Tokens used:", {
input: event.data.inputTokens,
output: event.data.outputTokens,
});
});
Compactage de contexte
Au lieu de /compact, configurez le compactage automatique ou déclenchez-le manuellement :
// Automatic compaction via config
const session = await client.createSession({
infiniteSessions: {
enabled: true,
backgroundCompactionThreshold: 0.80, // Start background compaction at 80% context utilization
bufferExhaustionThreshold: 0.95, // Block and compact at 95% context utilization
},
});
// Manual compaction (experimental)
const result = await session.rpc.history.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);
Remarque
Les seuils sont des ratios d’utilisation du contexte (0,0-1,0), et non des nombres de jetons absolus.
Gestion du plan
Lire et écrire des plans de session programmatiquement.
// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
console.log(plan.content);
}
// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });
// Delete the plan
await session.rpc.plan.delete();
Direction des messages
Injectez un message dans l'itération actuelle de LLM sans l'interrompre.
// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });
// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });
Limitations du protocole
Le Kit de développement logiciel (SDK) peut accéder uniquement aux fonctionnalités exposées via le protocole JSON-RPC de l’interface CLI. Si vous avez besoin d’une fonctionnalité CLI qui n’est pas disponible :
- Rechercher des alternatives : de nombreuses fonctionnalités ont des équivalents sdk (voir les solutions de contournement ci-dessus)
- Utiliser l’interface CLI directement - Pour les opérations ponctuelles, appelez l’interface CLI
- Demander la fonctionnalité - Ouvrir un problème pour demander la prise en charge du protocole
Compatibilité des versions
| Plage de protocoles SDK | Version du protocole CLI | Compatibilité |
|---|---|---|
| v2-v3 | v3 | Prise en charge complète |
| v2-v3 | v2 | Pris en charge par les adaptateurs v2 automatiques |
Le Kit de développement logiciel (SDK) négocie les versions du protocole avec l’interface CLI au démarrage. Le SDK prend en charge les versions de protocole 2 à 3. Lors de la connexion à un serveur CLI v2, le SDK adapte automatiquement les messages tool.call et permission.request au modèle d’événement v3, sans qu’aucun changement de code ne soit nécessaire.
Vérifiez les versions au moment de l’exécution :
const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);