Files
Support-AI/docs/spec.md
T

33 KiB
Executable File
Raw Blame History

Spec — Automatisation du support : LibreDesk + agents sur Gitea

Pour Claude Code. Ce document est le résultat d'un brainstorming entre Maxime et Claude (sans accès au code du projet). Il fixe l'intention, les contraintes, l'architecture cible et toutes les options envisagées. Les détails d'implémentation (structure exacte, noms de modules, réutilisation du code existant) sont à décider par toi à partir du projet réel.

Méthode attendue : commencer par la phase 0 (vérifications sur les instances réelles), puis rédiger un plan d'implémentation détaillé (ex. skill superpowers writing-plans si disponible), puis implémenter phase par phase. Plusieurs informations ci-dessous sont non vérifiées et marquées ⚠️ : ne pas les tenir pour acquises, les tester.

Philosophie de cette phase : ne fermer aucune porte. On construit, Maxime teste, on garde ce qui marche. Les options alternatives sont listées pour être essayées, pas écartées.


1. Règle absolue : aucun e-mail ne part au client

Ce sont de vrais e-mails de vrais clients. Pendant toute la phase de développement et de test :

  • Aucun message ne doit jamais être envoyé à un client par le système, ni directement, ni indirectement (assistant IA LibreDesk, macro, règle d'automatisation, appel API mal paramétré).
  • Le système produit uniquement des notes privées (et éventuellement des brouillons, cf. §8). Un humain relit, modifie et envoie lui-même.
  • Plus tard, une fois le système validé et peaufiné par Maxime, on pourra envisager plus d'automatisation. Pas avant, et pas sans décision explicite de Maxime.

Cette règle prime sur toutes les autres. Les garde-fous concrets sont au §7 : ils doivent être implémentés avant tout premier appel en écriture vers le LibreDesk de production.


2. Objectif

Traiter automatiquement les demandes de support arrivant par e-mail dans LibreDesk :

  1. Pré-tri : comprendre de quoi parle la demande et l'étiqueter.
  2. Traitement spécialisé : selon l'étiquette, un dépôt Gitea dédié fait l'analyse poussée (diagnostic technique, etc.) avec les agents existants.
  3. Restitution : le résultat (diagnostic + proposition de réponse) revient dans la conversation LibreDesk sous forme de note privée.
  4. Validation humaine : un membre du support relit, corrige, envoie.

Contraintes d'entreprise :

  • Tout doit s'aligner sur l'infrastructure de l'entreprise : Gitea + LibreDesk. L'entreprise tient à ce que tout soit conforme à Gitea. Pas de service maison à héberger à côté si on peut l'éviter.
  • Rien ne dépend de l'ordinateur de Maxime. Tout tourne sur le serveur de l'entreprise.
  • Personne ne doit avoir à intervenir sur le dépôt pour que ça tourne : exécution autonome.
  • Pas de contrainte de latence : ce sont des e-mails, traités en plusieurs jours. Un délai de 15–30 min est parfaitement acceptable.

Hors périmètre :

  • L'application React + FastAPI existante de Maxime n'est pas concernée. On ne la déploie pas.
  • Ce qu'on reprend : le dossier API du projet support agent (clients API, documentation, tout ce qui fait fonctionner les agents analyste et support) et la logique des agents (déjà capables de comprendre et traiter une demande).

3. Situation de départ (faits établis)

  • Les demandes clients arrivent par e-mail dans LibreDesk, auto-hébergé dans l'entreprise.
  • Gitea est une brique d'infrastructure importante de l'entreprise (Gitea, pas GitHub).
  • Le projet support agent de Maxime contient un dossier API encapsulant les appels aux API et la documentation nécessaires aux agents, et des agents (analyste, support) fonctionnels.
  • Les agents sont du code Python qui appelle l'API Anthropic avec une clé API (pas Claude Code, pas d'abonnement).
    • La clé sera stockée dans les secrets Gitea. Pour la production, prévoir une clé au nom de l'entreprise plutôt qu'une clé personnelle.
  • Données : envoyer le contenu des e-mails clients à l'API Anthropic est acceptable à ce stade.

4. Ce qu'on sait de LibreDesk

Sources en fin de document. ✅ = confirmé par une source ; ⚠️ = à vérifier sur l'instance.

4.1 Intégration

  • ✅ API HTTP/JSON, authentification par clé API + secret générés par agent (Admin → Teammates → Agents → générer une clé). Certains points d'accès ne sont pas documentés.
  • ✅ Messages d'une conversation :
    • GET /api/v1/conversations/{uuid}/messages : lire les messages.
    • POST /api/v1/conversations/{cuuid}/messages : envoyer un message. Champs : message, attachments, private (note interne), to, cc, bcc, sender_type.
    • ⚠️ DANGER : c'est le même point d'accès pour une réponse au client et pour une note privée. Seul le booléen private fait la différence. Source = schéma d'un wrapper MCP communautaire (metanmai/libredesk-mcp), pas la doc officielle. À vérifier sur une instance de test avant tout usage en production (cf. §7).
  • ✅ Suppression de notes privées par API (depuis v2.5.0) : utile pour nettoyer pendant les tests. Restreinte à l'auteur de la note ou à un admin (v2.8.0).
  • ✅ Webhooks : message.created se déclenche à chaque nouveau message (entrant, sortant, note privée, activité). Il faut donc filtrer pour ne pas retraiter ses propres notes.
  • ✅ Règles d'automatisation : étiquetage, assignation, routage selon des conditions personnalisées. Pas d'IA.
  • ✅ Macros : réponses enregistrées, pose d'étiquettes en un clic.
  • ✅ Étiquettes, statuts personnalisés, attributs personnalisés sur les conversations.
  • ⚠️ Points d'accès API étiquettes (ajout/retrait sur une conversation) et filtrage des conversations par étiquette : à trouver (doc officielle, spécification OpenAPI, code source Go du dépôt abhinavxd/libredesk).
  • ⚠️ Brouillons : depuis v2.5.0, les brouillons sont stockés par type (réponse / note privée). Existe-t-il un point d'accès API pour créer un brouillon de réponse visible par l'agent humain dans l'éditeur ? Si oui, c'est une sortie très intéressante (cf. §8).

4.2 Fonctions IA de LibreDesk (v2.6.0+, bêta)

Fonction Ce qu'on sait Intérêt pour nous
Assistant IA Une règle d'automatisation route une conversation vers un assistant. Il répond à partir de la base de connaissances et passe la main à un humain s'il ne peut pas aider. Le README le décrit pour le chat en direct. Option de passage à l'humain configurable par assistant. ⚠️ Il répond au client. Contraire au §1 tant qu'on n'a pas prouvé qu'on peut l'empêcher de répondre. Ne jamais le router vers la boîte e-mail de production pendant les tests. Explorable sur une instance de test uniquement.
Outils IA personnalisés Branchent l'assistant sur nos propres API (GET et POST uniquement, plusieurs en-têtes d'authentification). Conditionnés à une vérification OTP par e-mail du contact. Permettrait en théorie à l'assistant d'appeler un service de diagnostic. Mais : lié à l'assistant (qui répond au client) et nécessite d'exposer une API. À explorer, pas prioritaire.
Copilote (Juno) Onglet latéral : répond aux questions sur la conversation et la base de connaissances. Outils d'historique client, choix de persona, suggestions d'étiquettes. Suggestions d'étiquettes = tri assisté par IA, validé par un humain. ⚠️ Rien n'indique qu'elles sont appliquées automatiquement : à vérifier.
Suggestions d'étiquettes Tirées de la liste d'étiquettes existante. Présélection par embeddings, puis le LLM choisit. Cœur de l'option de tri T2 (§6). ⚠️ Existe-t-il un point d'accès API interne qu'on pourrait appeler depuis un cron pour automatiser le tri (option T3b) ?
Générer une réponse Rédige un brouillon dans l'éditeur, que l'agent humain modifie avant d'envoyer. Compatible avec le §1. Peut compléter notre note privée.
Résumé IA Ajoute un résumé de la conversation en note privée. Montre que LibreDesk sait poster des notes privées IA en interne.
Apprentissage sur conversations résolues Rédige des extraits pour la base de connaissances, qu'un agent approuve ou rejette. Piste pour la boucle de retour d'expérience (§12).
Fournisseur de modèle N'importe quel service compatible OpenAI, y compris un modèle local. Suivi de la consommation de jetons. ⚠️ Tester si l'API Anthropic via son point d'accès compatible OpenAI fonctionne, pour réutiliser la même clé.

Non mentionné dans les notes de version : l'IA de LibreDesk qui applique des étiquettes, assigne des équipes ou crée des notes privées en dehors du résumé. Ça ne veut pas dire que c'est impossible : vérifier dans l'interface et le code de la version installée. Il peut y avoir des subtilités qui nous échappent.

4.3 Version

  • ⚠️ Vérifier la version de LibreDesk installée. Fonctions IA : ≥ 2.6.0. Suppression de notes par API : ≥ 2.5.0. Dernière version connue au moment du brainstorming : 2.8.0 (août 2026). Une mise à jour peut être nécessaire.

5. Ce qu'on sait de Gitea Actions

  • ✅ Compatible avec la syntaxe GitHub Actions. Déclencheurs : push, pull_request, schedule (cron), workflow_dispatch (manuel).
  • ✅ Déclenchement par API de workflow_dispatch : point d'accès de dispatch de workflow, exposé dans le SDK Go (DispatchRepoActionWorkflow) et le CLI tea (tea actions workflows dispatch). ⚠️ C'est récent : vérifier que la version de l'instance l'expose. Rappel : workflow_dispatch ne fonctionne que pour un workflow présent sur la branche par défaut.
  • ✅ Exécution dans un runner (act_runner) installé sur le serveur.
  • ✅ Secrets de dépôt (ou d'organisation) pour les clés.
  • ✅ Un webhook LibreDesk ne peut pas déclencher directement une Action : formats de données et authentification incompatibles. Il faut un cron ou un relais.
  • ⚠️ Support de concurrency: (empêcher deux exécutions simultanées) : dépend de la version de Gitea. À vérifier. Sinon, verrou applicatif (§9.3).
  • ⚠️ actions/upload-artifact : version supportée selon l'instance. À vérifier si on veut publier les sorties du mode simulation en artefact.

6. Architecture cible

6.1 Principe : l'étiquette LibreDesk est l'interface

Les briques ne se parlent jamais directement. Elles communiquent par étiquettes sur les conversations LibreDesk.

  • Une brique de tri pose une étiquette tri-*.
  • Chaque dépôt de traitement lit les conversations qui portent « son » étiquette tri-*, fait son travail, poste une note privée et pose une étiquette d'état.

Conséquences :

  • Qui pose l'étiquette de tri est interchangeable : règle LibreDesk, copilote + humain, assistant IA LibreDesk, dépôt de tri dédié, humain à la main. Les dépôts de traitement ne voient pas la différence. C'est ce qui permet de tester toutes les options de tri (§6.3) sans rien changer en aval.
  • L'état vit dans LibreDesk : pas de base de données, pas d'état persistant côté runner.
  • Un dépôt = une responsabilité. On ajoute un nouveau type de traitement en créant un dépôt qui écoute une nouvelle étiquette tri-*.
E-mail client
   │
   ▼
LibreDesk ──────────────────────────────────────────────────────────┐
   │                                                                 │
   │  TRI (une ou plusieurs options, cf. §6.3)                       │
   │   → pose  tri-diagnostic | tri-<autre> | tri-humain | tri-ignore│
   │                                                                 │
   │  [dépôt support-diagnostic]  cron Gitea, toutes les 15–30 min   │
   │   lit : tri-diagnostic  ET  aucune étiquette diag-*             │
   │   → agents existants (dossier API + agents analyste/support)    │
   │   → note privée « Brouillon IA » dans la conversation ──────────┤
   │   → pose diag-fait | diag-erreur | diag-ignore                  │
   │                                                                 │
   │  [futurs dépôts]  même modèle, autre étiquette tri-*            │
   │                                                                 │
   ▼                                                                 │
Humain du support : lit la note, corrige, ENVOIE LUI-MÊME ◄─────────┘

6.2 Contrat d'étiquettes (proposition, à ajuster)

⚠️ Vérifier les caractères autorisés dans les noms d'étiquettes (il existe une validation). Utiliser : si autorisé (tri:diagnostic), sinon -.

Étiquette Posée par Signification
tri-diagnostic brique de tri La demande relève du diagnostic technique.
tri-<domaine> brique de tri Autres domaines futurs (facturation, compte…).
tri-humain brique de tri Doute ou cas sensible : un humain décide.
tri-ignore brique de tri Spam, accusé de réception, hors sujet.
diag-en-cours dépôt diagnostic Verrou pendant le traitement (§9.3).
diag-fait dépôt diagnostic Note privée postée.
diag-erreur dépôt diagnostic Échec. Une note d'alerte courte est postée si possible.
diag-ignore dépôt diagnostic Les agents ont jugé qu'aucun diagnostic n'est pertinent (la note explique pourquoi).
diag-relancer humain Demande un nouveau diagnostic (par exemple après une réponse du client).

Règle de sélection du dépôt diagnostic : tri-diagnostic présent ET (aucune étiquette diag-* OU diag-relancer présent).

Relance du client dans un ticket déjà traité : par défaut, pas de relance automatique. L'humain pose diag-relancer. À rediscuter après les tests.

6.3 Options de tri — toutes à tester

Maxime préfère que le tri se fasse dans LibreDesk avec ses outils d'IA. D'après ce qu'on sait, le tri IA entièrement automatique des e-mails n'est pas une fonction documentée de LibreDesk. On garde donc toutes les options ouvertes, à essayer dans cet ordre de préférence :

# Option Automatique ? Où vit la logique Statut
T1 Règles d'automatisation LibreDesk (boîte de réception, mots-clés du sujet, domaine de l'expéditeur…) → pose tri-* Oui LibreDesk ✅ Disponible. Tri grossier, sans IA. Bon socle.
T2 Copilote LibreDesk : suggestions d'étiquettes → un humain valide d'un clic Semi LibreDesk ✅ Existe (≥ 2.6). Vérifier l'ergonomie et si une application automatique est possible. Combine IA et garde-fou humain.
T3a Assistant IA LibreDesk configuré pour uniquement classer (instructions + éventuel outil personnalisé qui pose l'étiquette), sans jamais répondre Oui LibreDesk ⚠️ Expérimental et risqué (§1). Uniquement sur une instance ou une boîte de test sans SMTP sortant. Vérifier : canal e-mail supporté ? Peut-on l'empêcher de répondre ?
T3b Un cron Gitea qui appelle l'API interne de suggestion d'étiquettes de LibreDesk et applique la suggestion Oui LibreDesk (IA) + Gitea (application) ⚠️ Seulement si ce point d'accès est accessible par clé API. À chercher dans le code source.
T4 Dépôt support-triage : cron Gitea, agent de tri Python + Anthropic avec garde-fous, pose tri-* Oui Gitea Plan B robuste, entièrement maîtrisé et versionné.
T5 Humain pose l'étiquette à la main (ou via une macro) Non — Toujours possible. Utile pour démarrer et pour cibler.

Ces options se combinent : par exemple T1 pour le gros du flux, T2/T5 pour le reste, T4 si on veut plus d'intelligence. Toute brique de tri IA doit avoir des garde-fous : liste fermée d'étiquettes, tri-humain en cas de doute, aucune capacité d'écriture autre que l'étiquette.

Désactiver (ou ne jamais router vers la boîte e-mail réelle) l'assistant IA LibreDesk tant que T3a n'est pas validé, pour éviter qu'il réponde aux clients.


7. Garde-fous « zéro envoi au client » (obligatoires, implémentés en premier)

Défense en profondeur. Chaque couche doit suffire seule à empêcher un envoi.

  1. Instance LibreDesk de test d'abord. Monter un LibreDesk local (docker compose officiel) sans SMTP sortant configuré, avec des conversations factices. Tous les développements et toutes les vérifications du §10 se font d'abord là.
  2. Client LibreDesk restreint, refus par défaut. Le module qui parle à LibreDesk n'expose qu'une liste fermée d'opérations : lister/lire des conversations, lire des messages, ajouter/retirer des étiquettes, poster une note privée, supprimer sa propre note privée. Aucune méthode générique « envoyer un message » ou « requête arbitraire ».
  3. post_private_note verrouillée :
    • force private: true en dur, non paramétrable ;
    • ne transmet jamais to, cc, bcc ;
    • vérifie la réponse de l'API (si elle renvoie le message créé, contrôler qu'il est bien privé). Sinon : exception, arrêt immédiat de l'exécution entière et étiquette diag-erreur. Ne pas continuer sur les autres tickets.
  4. Les agents LLM n'ont aucun accès en écriture à LibreDesk. Ils reçoivent du texte et renvoient du texte. Seul l'orchestrateur, déterministe, écrit (note + étiquettes). C'est aussi la protection contre l'injection de prompt : le contenu des e-mails clients est une entrée non fiable.
  5. Mode simulation par défaut (DRY_RUN=true) : aucune écriture vers LibreDesk. Les notes prévues sont écrites dans les journaux du job (et en artefact si disponible). Passer en écriture réelle exige un changement explicite de configuration.
  6. Liste blanche de conversations (ALLOWED_CONVERSATION_IDS) pour la première phase en production : le système n'écrit que sur des conversations explicitement autorisées.
  7. Plafond par exécution (MAX_CONVERSATIONS_PER_RUN, par exemple 3 à 5) : limite le coût et les dégâts possibles.
  8. Interrupteur d'arrêt : une variable ou un secret Gitea (KILL_SWITCH) vérifié au démarrage. Désactiver le workflow dans Gitea fonctionne aussi.
  9. Compte technique LibreDesk dédié (par exemple « Agent IA ») avec les permissions minimales. ⚠️ Vérifier si les rôles LibreDesk permettent d'autoriser les notes privées sans autoriser les réponses. Si oui, c'est la meilleure barrière.
  10. Tests automatisés : un test vérifie que tout appel POST …/messages passe par post_private_note avec private: true. Un test (ou une règle de lint/grep en CI) interdit tout autre usage de ce point d'accès.
  11. Marquage visible de la note : en-tête du type « 🤖 BROUILLON IA — à relire, ne pas envoyer tel quel », pour qu'un humain ne la confonde jamais avec une réponse validée.
  12. Pas de mention @agent dans les notes au début : éviter les notifications parasites.
  13. Vérifier les règles d'automatisation et les macros existantes dans LibreDesk : aucune ne doit envoyer automatiquement une réponse quand une étiquette tri-* ou diag-* est posée.

8. Sorties vers l'humain — options

Option Description Statut
S1 — Note privée (principale) Diagnostic + proposition de réponse dans une note privée. ✅ Supporté (private: true), à valider sur l'instance de test.
S2 — Brouillon de réponse Préremplir l'éditeur de réponse de l'agent humain, qui n'a plus qu'à relire et envoyer. ⚠️ À explorer : existe-t-il une API de brouillon ? Gros gain d'ergonomie si oui. Un brouillon ne doit jamais s'envoyer seul : à vérifier.
S3 — « Générer une réponse » natif L'humain clique sur « Générer une réponse » dans LibreDesk, qui peut s'appuyer sur notre note privée présente dans la conversation. ✅ Existe (≥ 2.6). À tester en combinaison avec S1.
S4 — Attributs personnalisés Stocker des champs structurés (catégorie, gravité, confiance) dans des attributs de conversation. ⚠️ Vérifier l'API. Utile pour filtrer et faire des statistiques.

Format de la note : à valider avec l'équipe support. Proposition de départ :

  • en-tête « Brouillon IA » ;
  • résumé de la demande en 1–2 lignes ;
  • diagnostic (constats, vérifications faites, sources/données consultées) ;
  • niveau de confiance et points incertains ;
  • proposition de réponse au client, prête à copier ;
  • pied de page technique : identifiant d'exécution Gitea, version du dépôt (commit), modèle utilisé.

9. Dépôt support-diagnostic (phase 1)

9.1 Contenu

  • Le dossier API et la logique des agents repris du projet support agent (à toi de juger : copie, sous-module, ou paquet Python partagé).
  • Un point d'entrée non interactif (par exemple python -m support_diagnostic.run).
  • Le client LibreDesk restreint (§7).
  • Le workflow Gitea (.gitea/workflows/diagnostic.yml).
  • Tests (§7.10 + tests unitaires du cycle).

9.2 Cycle d'une exécution

  1. Vérifier l'interrupteur d'arrêt et la configuration (mode simulation, liste blanche, plafond).
  2. Lister les conversations éligibles (§6.2). ⚠️ Si l'API ne filtre pas par étiquette : lister les conversations ouvertes récentes et filtrer côté client.
  3. Pour chaque conversation, jusqu'au plafond :
    1. poser diag-en-cours ;
    2. lire les messages (ignorer les notes privées et nos propres notes ; ne garder que les messages client et les réponses humaines utiles comme contexte) ;
    3. exécuter les agents (pré-analyse → diagnostic → rédaction de la proposition de réponse) ;
    4. poster la note privée (ou l'écrire dans les journaux en mode simulation) ;
    5. retirer diag-en-cours et diag-relancer, poser diag-fait ou diag-ignore.
  4. En cas d'erreur sur une conversation : note d'alerte courte si possible, diag-erreur, retrait de diag-en-cours, passage à la suivante. Exception : une anomalie du garde-fou d'envoi (§7.3) arrête tout.
  5. Résumé de l'exécution dans les journaux : conversations traitées, statuts, jetons consommés, durée.

9.3 Doublons, concurrence, boucles

  • Doublons : l'état est porté par les étiquettes diag-*. Une conversation déjà traitée n'est pas reprise.
  • Concurrence : concurrency: dans le workflow si Gitea le supporte. Sinon, le verrou diag-en-cours plus un intervalle de cron largement supérieur à la durée d'une exécution.
  • Verrous orphelins (exécution plantée) : considérer diag-en-cours comme périmé après N heures (par exemple via la date de l'étiquette ou d'une note de démarrage) et le libérer.
  • Boucles : en cron, on ne réagit pas aux événements, donc le risque de retraiter ses propres notes est nul tant qu'on filtre sur les étiquettes. En mode webhook (§11), filtrer explicitement notes privées, messages sortants et messages de l'agent technique.

9.4 Workflow Gitea (esquisse)

name: support-diagnostic
on:
  schedule:
    - cron: "*/20 * * * *"     # toutes les 20 min, à ajuster
  workflow_dispatch:            # lancement manuel pour les tests
    inputs:
      dry_run:
        description: "Mode simulation (aucune écriture LibreDesk)"
        default: "true"
# concurrency: support-diagnostic   # si supporté par l'instance
jobs:
  run:
    runs-on: <label du runner>
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r requirements.txt   # envisager une image Docker préconstruite pour éviter la réinstallation à chaque exécution
      - run: python -m support_diagnostic.run
        env:
          LIBREDESK_URL: ${{ vars.LIBREDESK_URL }}
          LIBREDESK_API_KEY: ${{ secrets.LIBREDESK_API_KEY }}
          LIBREDESK_API_SECRET: ${{ secrets.LIBREDESK_API_SECRET }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          DRY_RUN: ${{ inputs.dry_run || vars.DRY_RUN || 'true' }}
          ALLOWED_CONVERSATION_IDS: ${{ vars.ALLOWED_CONVERSATION_IDS }}
          MAX_CONVERSATIONS_PER_RUN: ${{ vars.MAX_CONVERSATIONS_PER_RUN || '3' }}
          KILL_SWITCH: ${{ vars.KILL_SWITCH }}

Points d'attention :

  • Le runner doit joindre l'API LibreDesk (réseau interne), l'API Anthropic (sortie internet) et les API utilisées par le dossier API des agents.
  • Pas de GPU nécessaire a priori (les modèles sont appelés par API). À confirmer selon les détecteurs.
  • Traçabilité : chaque exécution Gitea est un journal horodaté. Mettre l'identifiant d'exécution dans la note pour remonter du ticket au journal.

10. Phase 0 — vérifications avant de développer

Faire ces vérifications sur les instances réelles, en lecture seule ou sur l'instance de test, et consigner les résultats dans un fichier docs/verifications.md du dépôt.

Gitea

  • Version de Gitea. Actions activées ? Runner installé, enregistré, label disponible ?
  • Le runner joint-il l'API LibreDesk, l'API Anthropic et les API du dossier API ?
  • workflow_dispatch via API disponible ? concurrency: supporté ? Quelle version d'upload-artifact ?
  • Secrets et variables de dépôt/organisation utilisables.

LibreDesk

  • Version installée (≥ 2.6 pour l'IA ; dernière connue : 2.8.0).
  • Monter l'instance de test sans SMTP sortant.
  • Spécification OpenAPI / doc API : points d'accès conversations (liste, filtres), messages, étiquettes, attributs personnalisés, brouillons.
  • Sur l'instance de test : POST …/messages avec private: true crée bien une note privée et n'envoie rien. Tester aussi un appel sans private pour comprendre le comportement par défaut (sur l'instance de test uniquement !).
  • Permissions des rôles : peut-on autoriser les notes privées sans autoriser les réponses ?
  • Caractères autorisés dans les noms d'étiquettes.
  • Fonctions IA : suggestions d'étiquettes (manuelles ou automatiques ? point d'accès API ?), assistant IA sur le canal e-mail (supporté ? peut-on l'empêcher de répondre ?), outils personnalisés, « Générer une réponse ».
  • Fournisseur IA : l'API Anthropic via son point d'accès compatible OpenAI fonctionne-t-elle ?
  • Inventaire des règles d'automatisation et des macros existantes : aucune ne doit envoyer de réponse automatiquement (§7.13).

Projet existant

  • Identifier dans support agent ce qui est réutilisable sans interface : dossier API, agents, détecteurs, prompts.
  • Les agents peuvent-ils être appelés de façon non interactive avec en entrée le contenu d'une conversation et en sortie un diagnostic plus une proposition de réponse ?

11. Modes de déclenchement — toutes les options

Mode Description Statut
D1 — Cron Gitea Workflow planifié qui interroge l'API LibreDesk. ✅ Choisi pour la phase 1. 100 % Gitea, pas de service à héberger, latence sans importance.
D2 — Manuel workflow_dispatch depuis l'interface Gitea, éventuellement avec un identifiant de conversation en entrée. ✅ Utile pour les tests et pour forcer un traitement.
D3 — Webhook + relais LibreDesk message.created → petit service toujours allumé → déclenche workflow_dispatch via l'API Gitea (ou traite directement). Plus réactif, mais ajoute un service hors Gitea. Inutile vu l'absence d'urgence. Garder pour plus tard.
D4 — LibreDesk appelle notre API Un outil IA personnalisé de l'assistant LibreDesk appelle une API de diagnostic exposée par nous. Nécessite d'héberger une API et passe par l'assistant qui répond au client (§1). Exploratoire.

12. Alternatives discutées

  • Déployer l'application FastAPI existante comme service permanent (conteneur sur le serveur, déployé par Gitea Actions, recevant directement les webhooks) : solution classique, réactive. Écartée car Maxime veut rester aligné sur Gitea + LibreDesk sans service maison, et l'application existante n'est pas concernée. À reconsidérer si le cron montre ses limites.
  • Limites connues de l'approche cron Gitea, acceptées :
    • chaque exécution repart de zéro (checkout, installation des dépendances) → image Docker préconstruite si c'est trop lent ;
    • pas d'état persistant → l'état est dans les étiquettes LibreDesk ;
    • risque d'exécutions simultanées → concurrency: ou verrou ;
    • journaux répartis par exécution → identifiant d'exécution dans la note.
  • Utiliser l'assistant IA intégré de LibreDesk pour le pré-tri et la finalisation (schéma initial) : il répond lui-même au client et semble limité au chat en direct. Il ne peut donc pas jouer ce rôle tel quel. On le garde comme option expérimentale de tri (T3a).

13. Plan par phases

Chaque phase a un critère de sortie validé par Maxime avant de passer à la suivante.

Phase 0 — Vérifications (§10) Sortie : docs/verifications.md rempli. Choix du contrat d'étiquettes final.

Phase 1 — Squelette sécurisé, instance de test

  • Dépôt support-diagnostic : client LibreDesk restreint et garde-fous du §7, avec tests.
  • Point d'entrée et cycle complet du §9.2, branché sur les agents existants.
  • Workflow Gitea en mode simulation, déclenchement manuel.
  • Sortie : sur l'instance de test, une conversation tri-diagnostic reçoit une note privée correcte, les étiquettes sont posées, et aucun message sortant n'apparaît.

Phase 2 — Production en simulation

  • Workflow branché sur le LibreDesk de production, DRY_RUN=true, cron actif.
  • Tri : T1 et/ou T5 pour poser tri-diagnostic.
  • Sortie : Maxime relit les notes prévues dans les journaux sur des tickets réels et juge la qualité.

Phase 3 — Production en écriture, liste blanche

  • DRY_RUN=false avec ALLOWED_CONVERSATION_IDS et un plafond bas.
  • Validation du format de la note avec l'équipe support.
  • Sortie : notes utiles, zéro incident d'envoi.

Phase 4 — Production élargie

  • Retrait de la liste blanche, plafond relevé, cron régulier.
  • Essai des options de tri T2, T3b, T3a (test uniquement), T4. On garde celle(s) qui marchent.
  • Essai des sorties S2, S3, S4.

Phase 5 — Plus tard, sur décision explicite de Maxime

  • Nouveaux dépôts spécialisés (tri-<domaine>).
  • Webhook (D3) si la réactivité devient utile.
  • Boucle de retour d'expérience : comparer la note IA à la réponse réellement envoyée par l'humain, alimenter les agents ou la base de connaissances (cf. l'apprentissage sur conversations résolues de LibreDesk).
  • Éventuellement plus d'automatisation, jamais d'envoi automatique sans validation explicite.

14. Questions ouvertes

  • Quels types de demandes sont visés en premier par tri-diagnostic ? Quels autres domaines à terme ?
  • Format exact de la note : à valider avec l'équipe support.
  • Journalisation : les journaux Gitea suffisent-ils, ou faut-il un historique consultable (fichier, attribut LibreDesk, tableau de bord) ?
  • Gestion des erreurs : note d'alerte et diag-erreur suffisent-elles, ou faut-il une notification (e-mail interne, autre canal) ?
  • Coût : budget de jetons acceptable par ticket et par mois ? Quel modèle Anthropic pour chaque agent (tri, diagnostic, rédaction) ?
  • Clé API : passage à une clé au nom de l'entreprise, et à quel moment ?
  • Relances client : faut-il un jour relancer automatiquement le diagnostic quand le client répond ?
  • Pièces jointes (captures, journaux envoyés par le client) : les agents doivent-ils les lire ?

Sources