GuidesOneMux

Cline en production : configurer les sessions et récupérer en toute sécurité

Un guide pratique pour configurer les sessions ClineCore, séparer les paramètres d’exécution de la configuration du fournisseur et définir des règles prudentes de nouvelle tentative et de reprise.

AI

Résumé · TL;DR

ClineCore sépare les choix d’exécution — comme le mode de backend, les capacités, les règles des outils et l’automatisation — du fournisseur et du modèle configurés pour chaque session. Ce guide explique comment rendre cette séparation explicite et concevoir une stratégie de reprise fondée sur les identifiants de session et l’état persistant, plutôt que de répéter aveuglément les opérations.

Points clés

  • Traitez l’exécution, les autorisations des outils et la configuration du fournisseur et du modèle comme des décisions distinctes.
  • Avant de réessayer, utilisez les identifiants de session et les messages persistés pour analyser les échecs.
  • Les nouvelles tentatives peuvent reproduire des effets de bord : définissez des points de contrôle et des règles de reprise adaptés à votre workflow.
  • La référence de l’API décrit les opérations de session, mais ne précise ni la sémantique des nouvelles tentatives, ni le format des points de contrôle, ni les garanties de compatibilité des fournisseurs.
Sur cette page (9)

ClineCore permet à une application de contrôler la création des sessions, la sélection de l’environnement d’exécution, les autorisations des outils et l’historique des sessions. Pour gérer des workflows en production, la question essentielle n’est pas simplement de savoir s’il faut réessayer un appel ayant échoué : il faut déterminer ce qui s’est déjà passé avant de relancer le travail.

La configuration ci-dessous est donnée à titre indicatif et ne constitue pas une recette de déploiement testée. La référence de l’API ClineCore décrit les options et méthodes abordées ici ; consultez la version du SDK que vous installez pour connaître les types et le comportement exacts.

Séparer les paramètres d’exécution des paramètres du modèle

Une configuration bien délimitée comporte trois parties :

  • Exécution : sélection du backend, identité du client et, le cas échéant, paramètres de connexion à un hub ou à un service distant.
  • Politique d’exécution : règles des outils, capacités et activation ou non des API d’automatisation.
  • Configuration du modèle de session : identifiant du fournisseur, identifiant du modèle, identifiants d’accès, chemins d’espace de travail et disponibilité des outils pour une session donnée.

Cette séparation facilite la gestion de la politique d’exécution indépendamment d’un changement de modèle. Elle ne rend pas pour autant interchangeables les champs propres aux fournisseurs : providerId, modelId et apiKey doivent toujours être valides pour le fournisseur sélectionné. La référence de l’API ne garantit pas la compatibilité avec tous les fournisseurs ou points de terminaison.

Créer un environnement d’exécution et démarrer une session

Prérequis : installez la version du SDK Cline que vous comptez déployer, fournissez les identifiants d’accès selon la méthode de gestion des secrets de votre application et déterminez quels outils l’agent peut utiliser. Ne placez pas d’identifiants dans les journaux ou les métadonnées de session.

import { ClineCore } from "@cline/sdk"

const cline = await ClineCore.create({
  clientName: "repo-maintenance-worker",
  backendMode: "auto",
  toolPolicies: {},
  automation: false,
})

const session = await cline.start({
  prompt: "Inspect the repository and report failing tests. Do not modify files.",
  source: "scheduled-check",
  interactive: false,
  sessionMetadata: { jobId: "job-123" },
  config: {
    providerId: "anthropic",
    modelId: "claude-sonnet-4-6",
    apiKey: process.env.ANTHROPIC_API_KEY,
    systemPrompt: "Follow the task scope and report actions taken.",
    cwd: process.cwd(),
    workspaceRoot: process.cwd(),
    enableTools: true,
    enableSpawnAgent: false,
    enableAgentTeams: false,
  },
})

console.log(session.sessionId)

Les valeurs de fournisseur et de modèle ci-dessus reprennent l’exemple de la référence de l’API ; elles ne constituent ni une recommandation ni une garantie de compatibilité au-delà de cet exemple. La référence documente les valeurs auto, local, hub et remote pour backendMode, ainsi que les paramètres facultatifs hub et remote. Elle ne précise pas quel mode convient le mieux à un déploiement donné. Faites un choix éclairé, puis vérifiez la connectivité et les autorisations dans votre environnement.

Un objet toolPolicies vide ne constitue pas une politique de sécurité. Définissez des valeurs par défaut explicites et des règles par session, conformément aux types de politiques pris en charge par le SDK installé. Utilisez capabilities lorsque le client fournit des exécuteurs d’outils ou des fonctions de validation, et vérifiez que les actions restreintes sont effectivement refusées.

Définir les règles de nouvelle tentative en fonction de l’état de la session

Une erreur réseau ou l’expiration du délai d’un worker ne prouve pas que l’agent s’est arrêté avant d’avoir terminé son travail. Répéter la requête initiale peut entraîner des modifications en double, des appels externes répétés ou d’autres effets de bord. La référence de l’API répertorie get, readMessages, getAccumulatedUsage, abort, stop et restore, mais ne précise ni la gestion automatique des nouvelles tentatives, ni une garantie d’exécution exactement une fois, ni le contenu d’un point de contrôle.

Une séquence opérationnelle plus sûre consiste à :

  1. Enregistrer immédiatement l’identifiant de session. Conservez-le avec l’identifiant de votre tâche afin qu’un worker redémarré puisse retrouver la même session.
  2. Qualifier l’échec. Distinguez un échec terminal confirmé d’une expiration de délai ou d’une perte de connexion, lorsque l’issue reste incertaine.
  3. Inspecter avant de soumettre à nouveau. Utilisez get et readMessages pour vérifier les métadonnées de session et les messages persistés. Le cas échéant, consultez l’utilisation cumulée comme indice opérationnel, et non comme preuve qu’une action donnée a été effectuée.
  4. Choisir la stratégie de reprise en connaissance de cause. Si la session est toujours active, décidez s’il faut attendre, l’annuler ou l’arrêter. Si le travail doit continuer, send accepte un identifiant de session et une requête de suivi. Si un point de contrôle est disponible et adapté, l’API expose restore ; consultez la documentation du SDK pour connaître les paramètres requis et la sémantique de cette méthode.
  5. Rendre les effets de bord répétables sans risque. Pour les actions hors de l’état propre à la session de l’agent, utilisez des clés d’idempotence au niveau de l’application, une déduplication ou une étape de validation humaine, selon le cas.

Évitez d’entourer start d’une boucle de nouvelle tentative inconditionnelle. Si la requête initiale a pu créer une session avant que l’appelant ne perde sa réponse, un nouvel appel à start peut lancer un travail distinct. La référence de l’API ne documente aucune clé d’idempotence pour start : ne partez donc pas du principe qu’il en existe une.

Résoudre les problèmes courants en production

La session démarre avec le mauvais environnement d’exécution

Consignez le mode de backend sélectionné et les identifiants de session non sensibles. Vérifiez les options backendMode, hub et remote en fonction de l’environnement dans lequel le worker s’exécute. La référence les décrit comme des options de sélection de l’environnement d’exécution, mais ne documente pas de comportement de basculement automatique ; vérifiez le fonctionnement de auto dans la version de votre SDK au lieu de supposer qu’un mécanisme de repli est prévu.

Les outils sont indisponibles ou autorisés de façon inattendue

Vérifiez à la fois la config de la session et les toolPolicies ou capabilities applicables, par défaut et par session. La référence les décrit comme des contrôles de politique des outils et des contrôles d’exécution ou de validation gérés par le client. Le résumé de l’API fourni ne précise pas la priorité des règles : vérifiez-la dans la documentation du SDK installé et testez les cas d’autorisation comme de refus.

Un worker perd sa connexion en cours d’exécution

Conservez l’identifiant de session et l’identifiant de tâche dans un état applicatif persistant. Au redémarrage, inspectez la session existante avant de décider de continuer avec send, de l’arrêter ou de la restaurer à partir d’un point de contrôle. Ne déduisez pas que le travail est terminé de la seule absence d’une réponse.

La configuration du fournisseur ou du modèle échoue

Vérifiez l’identifiant du fournisseur, l’identifiant du modèle, les identifiants d’accès et les éventuelles exigences liées au point de terminaison dans la documentation du fournisseur et de Cline correspondant à votre configuration. La référence de ClineCore présente une structure de configuration fournisseur/modèle ; elle ne garantit pas que des points de terminaison OpenAI-compatibles quelconques ou des paramètres propres à un fournisseur fonctionneront sans modification.

Liste de vérification pour la production

  • Stockez les identifiants de session de manière durable et ne divulguez pas de secrets dans les journaux ou les métadonnées.
  • Définissez explicitement les autorisations des outils et testez les processus d’approbation et de refus.
  • Faites la distinction entre une opération qui a échoué et une opération dont l’issue est inconnue.
  • Consultez l’historique de session avant de soumettre à nouveau le travail.
  • Rendez les effets de bord externes idempotents ou exigez une approbation avant de les rejouer.
  • Vérifiez le comportement du backend et du fournisseur dans l’environnement réel de déploiement.
  • Libérez les ressources d’exécution lors d’un arrêt normal, conformément au cycle de vie documenté du SDK.

La règle pratique est simple : ne réessayez qu’après avoir déterminé ce que vous relancez. ClineCore fournit des API liées aux sessions et à la reprise, mais la sécurité du fonctionnement en production dépend toujours du suivi durable des tâches par votre application, de la conception des autorisations et de la gestion des effets de bord en double.

FAQ

Quels paramètres ClineCore sont indépendants du fournisseur du modèle ?

Les options d’exécution telles que `clientName`, `backendMode`, les paramètres facultatifs de hub ou de service distant, les capacités, les règles des outils et l’automatisation sont distinctes des champs de fournisseur et de modèle de la session. Vérifiez le comportement exact des options dans la version du SDK utilisée.

Dois-je réessayer ClineCore.start après une expiration de délai ?

Pas sans vérifier. Une expiration de délai ne permet pas de savoir si une session a été créée. Conservez l’identifiant de session lorsqu’il est disponible et inspectez les sessions existantes avant de démarrer un nouveau travail. La référence de l’API fournie ne documente aucune clé d’idempotence pour `start`.

ClineCore peut-il restaurer une session ayant échoué ?

La référence de l’API répertorie une méthode `restore`, mais le résumé fourni ne précise ni ses paramètres requis ni la sémantique des points de contrôle. Consultez la documentation du SDK installé avant de concevoir une stratégie de reprise qui repose sur cette méthode.

Cette configuration fonctionne-t-elle avec n’importe quel fournisseur compatible avec OpenAI ?

La référence ClineCore citée ne l’établit pas. La compatibilité des fournisseurs et les paramètres acceptés dépendent de la prise en charge documentée du point de terminaison et de la configuration du fournisseur sélectionné ; vérifiez-les au lieu de supposer qu’ils sont interchangeables.

Articles liés