Files

403 lines
33 KiB
Markdown
Raw Permalink Normal View 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)
```yaml
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
- LibreDesk, notes de version v2.6.0 (fonctions IA) : https://github.com/abhinavxd/libredesk/releases/tag/v2.6.0
- LibreDesk, notes de version v2.8.0 : https://github.com/abhinavxd/libredesk/releases/tag/v2.8.0
- LibreDesk, notes de version v2.5.0 (suppression de notes privées, brouillons par type) : https://newreleases.io/project/github/abhinavxd/libredesk/release/v2.5.0
- LibreDesk, README : https://raw.githubusercontent.com/abhinavxd/libredesk/main/README.md
- Schéma `send_message` (wrapper MCP communautaire, champ `private`) : https://glama.ai/mcp/servers/metanmai/libredesk-mcp/tools/send_message
- DeepWiki LibreDesk, messages et points d'accès : https://deepwiki.com/abhinavxd/libredesk/3.1-messages-and-replies
- Gitea `tea`, dispatch de workflow par API : https://gitea.com/gqx/tea/src/branch/main/docs/example-workflows.md
- Gitea, ajout de `workflow_dispatch` (PR #28163) : https://git.sim1222.com/sim1222-mirror/gitea/commits/commit/4f5c96627b4622d64593db2d436b1f3befa5f3c3
- Document de brainstorming initial de Maxime (« Automatisation du support : LibreDesk + agents sur Gitea »), intégré et corrigé ici.