23 KiB
Phase 1 : squelette sécurisé, instance de test — plan d'implémentation
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal : une conversation LibreDesk étiquetée tri:diagnostic reçoit, sur l'instance de test, une note privée « Brouillon IA » écrite par les agents support et analyste, avec ses étiquettes d'état, sans qu'aucun message sortant n'apparaisse.
Architecture : un point d'entrée non interactif, python -m support_diagnostic.run, lit les conversations éligibles par l'API LibreDesk, passe chaque mail aux agents existants (copiés de Support-Agent/API/, sortie mail), et seul ce code déterministe écrit dans LibreDesk : une note privée et des étiquettes, par un client restreint. L'état vit dans les étiquettes. Un workflow Gitea le lance à la main.
Tech Stack : Python ≥ 3.12, bibliothèque standard (urllib, http.server, unittest) ; anthropic, langsmith, matplotlib pour les agents copiés ; Docker Compose pour l'instance de test ; Gitea Actions.
Spec : docs/spec.md (§1, §6.2, §7, §8 S1, §9) ; constats de la phase 0 : docs/verifications.md.
Global Constraints
- Aucun message ne part au client (spec §1). Le seul
POST …/messagesdu dépôt est dansLibreDesk.note_privee, avec"private": Trueen dur,"sender_type": "agent", jamaisto,cc,bcc. - Les agents LLM n'écrivent jamais dans LibreDesk : ils reçoivent du texte, rendent du texte (spec §7.4).
DRY_RUN: seule la valeur exactefalsepermet d'écrire ; absente ou toute autre valeur, rien n'est écrit (spec §7.5).- Écrire exige aussi
ALLOWED_CONVERSATION_IDSnon vide : des uuid séparés par des virgules, ou*pour toutes (spec §7.6). MAX_CONVERSATIONS_PER_RUN: défaut3(spec §7.7).KILL_SWITCHnon vide et différent defalseet0: sortie immédiate, code 0, rien lu ni écrit (spec §7.8).- Le compte technique a le rôle « Agent IA » :
conversations:read,conversations:read_all,messages:read,messages:write_private,conversations:update_tags, et rien d'autre (verifications.md, point 1). - Étiquettes, toujours avec
actionadd_tagsouremove_tags, jamaisset_tagsni sansaction(sans, LibreDesk remplace toutes les étiquettes). - Contrat d'étiquettes (à confirmer par Maxime à la revue du plan) :
tri:diagnostic,diag:en-cours,diag:fait,diag:erreur,diag:ignore,diag:relancer. Éligible :tri:diagnosticprésent et (aucunediag:*oudiag:relancerprésente). - En-tête de chaque note, mot pour mot :
🤖 BROUILLON IA — à relire, ne pas envoyer tel quel. Pas de mention@agent(spec §7.11, §7.12). - Langue : code et documents en français, comme
Support-Agent. - Le runner Gitea : son label est inconnu (verifications.md, Gitea) ; les workflows portent
runs-on: ubuntu-latestjusqu'à ce que Maxime donne le label.
Hors de ce plan
- Phase 2 et au-delà : la planification (cron), la production.
- Les données des stations sur le runner (verifications.md, point 6) : en phase 1, le diagnostic réel tourne sur le poste avec
AIMSIGHT_DATA=~/Support-Agent/data; le workflow ne fait qu'un passage à blanc. À décider avant la phase 2. De même : en phase 2, un cron en simulation, qui n'écrit pas d'étiquette, rediagnostiquerait les mêmes conversations à chaque passage. - Les verrous orphelins (
diag:en-courslaissé par un runner tué, spec §9.3) : un humain retire l'étiquette ; marquéponytail:dans le code. supprimer_note(spec §7.2) : inutile tant que l'instance de test se remet à zéro pardocker compose down -v.- Le nom du site → la station (Crissier = LENZSPITZE) : le support le déduit du mail, ou le demande, et sa question devient la note (
diag:ignore).
Review Focus
- Une conversation porte déjà une étiquette d'un humain (
urgent) : nos opérations ne la retirent jamais. → Tâche 2,test_etiqueter_n_envoie_jamais_set. - La réponse de LibreDesk à la note n'est pas une note privée (changement d'API, 200 sans
private: true) : tout s'arrête, plus rien n'est écrit. → Tâches 2 et 4,test_note_non_privee_leve_garde,test_garde_arrete_tout. - Les agents échouent au milieu d'une conversation :
diag:en-coursest retiré,diag:erreurposé, la suivante est traitée. → Tâche 4,test_erreur_passe_a_la_suivante. - Relance (
diag:relancer) d'une conversation où figure déjà notre note : notre note n'entre ni dans le mail ni dans le contexte ; les notes privées des humains entrent dans le contexte. → Tâche 4,test_relance_ecarte_nos_notes. - Mail du client vide (image seule, HTML sans texte) : pas d'appel aux agents,
diag:ignoreet une note qui le dit. → Tâche 4,test_mail_vide_ignore.
Structure
Support-AI/
agents/ copie de Support-Agent/API/ (prompts, knowledge, tools sans typst/, support/), PROVENANCE.md
support_diagnostic/
__init__.py
libredesk.py le client restreint (seul à parler à LibreDesk)
diagnostic.py l'adaptateur vers agents/support/seance.py
run.py la configuration, le cycle, la note
tests/
faux_libredesk.py un faux LibreDesk (http.server) qui enregistre les requêtes
test_libredesk.py
test_garde_fou.py
test_diagnostic.py
test_run.py
test_instance.py intégration, sautée sans LIBREDESK_TEST_URL
instance-de-test/ docker-compose.yml, verifier.py (phase 0), preparer.py
.gitea/workflows/tests.yml, diagnostic.yml
requirements.txt, .gitignore, README.md
Tests : python -m unittest discover -s tests -v depuis la racine.
Task 1 : la copie des agents
Files :
- Create :
agents/(copie),agents/PROVENANCE.md,requirements.txt,.gitignore
Interfaces :
-
Produces :
agents/support/seance.py(Seance,CASES),agents/support/agent.py, inchangés ;requirements.txt. -
Step 1 : copier
Support-Agent/API/versagents/, sanscases/,docs/,.venv/,.env,__pycache__/,tools/typst/(la sortie PDF n'est pas utilisée).agents/PROVENANCE.md: la provenance deAPI/PROVENANCE.md, plus une ligne «Support-Agent/API/→agents/, commit<sha de Support-Agent>, 2026-11-09, sanstools/typst/nicases/». -
Step 2 :
requirements.txt= celui deAPI/(anthropic,langsmith,matplotlib)..gitignore:.venv/,__pycache__/,.env,cases/,instance-de-test/config.toml,instance-de-test/uploads/. -
Step 3 : vérifier que le prompt du support se construit sans la PDF
Run : python3 -m venv .venv && .venv/bin/pip install -r requirements.txt && .venv/bin/python -c "import sys; sys.path.insert(0,'agents/support'); import seance; print(len(seance.systeme('support','mail')), len(seance.systeme('analyste')))"
Expected : deux nombres > 10000, pas d'exception.
- Step 4 : commit
git add agents requirements.txt .gitignore && git commit -m "Copie des agents de Support-Agent/API (sortie mail)"
Task 2 : le client LibreDesk restreint
Files :
- Create :
support_diagnostic/__init__.py(vide),support_diagnostic/libredesk.py,tests/faux_libredesk.py,tests/test_libredesk.py,tests/test_garde_fou.py
Interfaces :
-
Produces :
class Garde(Exception): anomalie du garde-fou d'envoi ; l'appelant arrête toute l'exécution.class LibreDesk(url: str, cle: str, secret: str, ecrire: bool); en-têteAuthorization: token <cle>:<secret>; timeout 30 s.moi() -> int: l'id du compte technique (GET /api/v1/agents/me).ids_etiquettes() -> dict[str, int](GET /api/v1/tags).conversations(avec: int) -> list[dict]: toutes les pages deGET /api/v1/conversations/all?page_size=50&filters=…avec le filtre{"model":"conversations","field":"tags","operator":"contains","value":"[<avec>]"}.etiquettes(uuid: str) -> list[str](GET /api/v1/conversations/{uuid}→tags).messages(uuid: str) -> list[dict](GET …/messages?page_size=500).piece(url: str) -> bytes.etiqueter(uuid: str, ajouter: list[str] = (), retirer: list[str] = ()) -> None: unPOST …/tagspar action non vide ; siecrireest faux, journalise et ne fait rien ; après un ajout, relitetiquettes(uuid)et lèveRuntimeErrors'il en manque une (LibreDesk ignore en silence une étiquette inconnue).note_privee(uuid: str, html: str) -> dict | None: siecrireest faux, journalise[simulation] note pour <uuid>puis le html, rendNone; sinonPOST …/messagesavec exactement{"message": html, "private": True, "sender_type": "agent"}, et lèveGardesi la réponse n'a pasprivate is True.- Aucune autre méthode qui écrit ; pas de méthode de requête générique publique.
-
Step 1 : le faux LibreDesk.
tests/faux_libredesk.py:FauxLibreDesk()démarre unThreadingHTTPServersur127.0.0.1:0;.url;.requetes : list[tuple[str, str, dict | None]](méthode, chemin avec la requête, corps JSON) ;.reponses : dict[tuple[str, str], object](méthode, chemin sans la requête → la valeur dedata, ou unintpour un code d'erreur) ;.arreter(). -
Step 2 : les tests qui échouent, dans
tests/test_libredesk.py:
def test_note_privee_envoie_exactement_le_corps_fige(self):
self.faux.reponses[("POST", "/api/v1/conversations/c1/messages")] = {"uuid": "m1", "private": True}
LibreDesk(self.faux.url, "k", "s", ecrire=True).note_privee("c1", "<p>x</p>")
m, chemin, corps = self.faux.requetes[-1]
assert (m, chemin) == ("POST", "/api/v1/conversations/c1/messages")
assert corps == {"message": "<p>x</p>", "private": True, "sender_type": "agent"}
def test_note_non_privee_leve_garde(self): # réponse {"uuid": "m1", "private": False}, puis {} : Garde les deux fois
def test_simulation_n_ecrit_rien(self): # ecrire=False : note_privee et etiqueter → aucune requête POST
def test_etiqueter_n_envoie_jamais_set(self): # etiqueter("c1", ["diag:fait"], ["diag:en-cours"]) : deux POST,
# actions add_tags puis remove_tags, aucun autre champ
def test_etiquette_inconnue_leve(self): # après add_tags, GET rend tags sans "diag:fait" → RuntimeError
def test_authentification(self): # en-tête Authorization == "token k:s" (le faux l'enregistre aussi)
def test_conversations_pagine_et_filtre(self):# deux pages (total_pages=2) → résultats concaténés ; le filtre
# décodé == [{"model":"conversations","field":"tags","operator":"contains","value":"[7]"}]
Et tests/test_garde_fou.py (spec §7.10), sur le texte de support_diagnostic/*.py :
def test_un_seul_post_de_messages(self):
# "/messages" n'apparaît que dans libredesk.py, dans le corps de note_privee et de messages() (GET)
def test_private_en_dur(self):
# libredesk.py contient '"private": True' ; aucun fichier ne contient '"to"', '"cc"', '"bcc"', 'set_tags'
- Step 3 : lancer, vérifier l'échec — Run :
.venv/bin/python -m unittest tests.test_libredesk tests.test_garde_fou -v— Expected : ImportError sursupport_diagnostic.libredesk. - Step 4 : écrire
support_diagnostic/libredesk.py(urllib, commeSupport-Agent/app/serveur/libredesk.py;add_unredirected_headerpour l'authentification). - Step 5 : lancer, vérifier le succès — même commande — Expected : tout OK.
- Step 6 : commit
git commit -m "Client LibreDesk restreint : notes privées et étiquettes seulement"
Task 3 : l'adaptateur vers les agents
Files :
- Create :
support_diagnostic/diagnostic.py,tests/test_diagnostic.py
Interfaces :
- Consumes :
agents/support/seance.py(Seance(mail, images, contexte, donnees, journal, client=None, sortie="mail"),.demarrer(),.derniere_version(),.cout(),.support.messages,.dossier, le module attributCASES). - Produces :
@dataclass Resultat: statut: str("fait"ou"ignore"), texte: str, pieces: list[Path], cout: float, dossier: Path | None(Nonequand les agents n'ont pas tourné)MODELE = "claude-opus-5-5"(celui deagents/support/agent.py, pour le pied de note)diagnostiquer(mail: str, images: list[tuple[str, bytes]], contexte: str, donnees: Path, cases: Path, client=None) -> Resultat
Approche : sys.path reçoit agents/support ; seance.CASES = cases avant de créer la séance ; journal écrit chaque événement en une ligne sur stdout ([agent] type : texte, tronqué à 300 caractères). Si derniere_version() existe : fait, texte et pieces (chemins dans s.dossier) lus du JSON. Sinon : ignore, texte = le texte du dernier message assistant du support (sa question ou son explication). Une exception des agents remonte telle quelle.
- Step 1 : les tests qui échouent, avec un faux client Anthropic sur le modèle de
agents/support/check.py(FauxClient,reponse,Bloc: les recopier dans le test,check.pyn'est pas importable sans données) :
def test_mail_ecrit_donne_fait(self):
# le support appelle ecrire_mail({"texte": "Bonjour, …", "pieces_jointes": []}) puis end_turn
r = diagnostiquer("mail", [], "", Path(tmp), Path(tmp), client=faux)
assert r.statut == "fait" and r.texte == "Bonjour, …" and r.pieces == []
def test_question_donne_ignore(self):
# le support répond par du texte, end_turn, sans ecrire_mail
assert r.statut == "ignore" and r.texte == "Quelle station ?"
- Step 2 : lancer, vérifier l'échec — Run :
.venv/bin/python -m unittest tests.test_diagnostic -v— Expected : ImportError. - Step 3 : écrire
support_diagnostic/diagnostic.py. - Step 4 : lancer, vérifier le succès — même commande — Expected : OK.
- Step 5 : commit
git commit -m "Adaptateur non interactif vers le support et l'analyste"
Task 4 : le cycle
Files :
- Create :
support_diagnostic/run.py,tests/test_run.py
Interfaces :
- Consumes :
LibreDesk,Garde(tâche 2) ;diagnostiquer,Resultat,MODELE(tâche 3). - Produces :
@dataclass Config: url, cle, secret: str; ecrire: bool; autorisees: set[str] | None(None=*); plafond: int; conversation: str(""= toutes); donnees: Path; cases: PathConfig.depuis_env(env: Mapping[str, str]) -> Config | None:NonesiKILL_SWITCHest actif. Variables :LIBREDESK_URL,LIBREDESK_API_KEY,LIBREDESK_API_SECRET,DRY_RUN,ALLOWED_CONVERSATION_IDS,MAX_CONVERSATIONS_PER_RUN,KILL_SWITCH,CONVERSATION,AIMSIGHT_DATA(défautdata),AIMSIGHT_CASES(défaut un dossier temporaire). LèveValueErrorsiecrireetALLOWED_CONVERSATION_IDSvide.eligible(etiquettes: list[str]) -> boolfil(messages: list[dict], moi: int) -> tuple[str, str]: (le mail, le contexte). Le mail : messagesincomingetoutgoingnon privés, le plus récent en tête, au format demail()deSupport-Agent/app/serveur/libredesk.py(le recopier). Le contexte : les notes privées dont l'auteur n'est pasmoi, en texte.note(r: Resultat, execution: str) -> str: le HTML de la note.traiter(ld: LibreDesk, cfg: Config, diag=diagnostiquer) -> dict[str, str]: uuid → statut (fait,ignore,erreur).main() -> int:python -m support_diagnostic.run; code 1 surGarde.
Le cycle de traiter (spec §9.2) :
- Candidates :
ld.conversations(ids["tri:diagnostic"]), ou la seulecfg.conversation; garder celles donteligible(ld.etiquettes(uuid))et, sicfg.autorisees, l'uuid y est ; s'arrêter àcfg.plafond. - Pour chacune :
etiqueter(uuid, ["diag:en-cours"]);fil(ld.messages(uuid), ld.moi()); images des messages entrants (typesimage/png|jpeg|gif|webp, ≥ 10 000 octets, commeSupport-Agent) ; mail vide aprèsstrip()→Resultat("ignore", "Le mail du client ne contient pas de texte.", …)sans appelerdiag; sinondiag(...);note_privee(uuid, note(r, execution));etiqueter(uuid, ["diag:" + r.statut], ["diag:en-cours", "diag:relancer"]). - Exception d'une conversation (autre que
Garde) :note_privee(uuid, …)courte (en-tête, « Diagnostic en échec », nom de l'exception,execution),etiqueter(uuid, ["diag:erreur"], ["diag:en-cours"]), chacun dans son propretry; conversation suivante. Garde:etiqueter(uuid, ["diag:erreur"])dans untry, puis la relancer : tout s'arrête.- Fin : une ligne par conversation (uuid, statut, coût), le total, la durée.
execution : ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID} si ces variables existent (Gitea les fournit), sinon local ; plus GITHUB_SHA[:7].
La note (spec §8, version de départ ; format à valider avec l'équipe support) :
<p><strong>🤖 BROUILLON IA — à relire, ne pas envoyer tel quel</strong></p>
<p><em>Proposition de réponse au client :</em></p> <!-- statut fait ; « Pas de proposition : » pour ignore -->
<p>…texte échappé (html.escape), un <p> par paragraphe, <br> aux retours simples…</p>
<p><em>Figures préparées (non jointes) : figure-1.png, …</em></p> <!-- seulement s'il y en a -->
<hr><p><small>Exécution … · commit … · modèle claude-opus-5-5 · coût 1.23 $</small></p>
- Step 1 : les tests qui échouent,
tests/test_run.py, avec un fauxLibreDesken mémoire (mêmes méthodes, enregistre les appels ;ecrirecomme le vrai) et un fauxdiag:
def test_dry_run_par_defaut(self): # depuis_env({...sans DRY_RUN}).ecrire is False ; "False", "0", "no" → False ; "false" → True
def test_ecrire_exige_liste_blanche(self):# DRY_RUN=false sans ALLOWED_CONVERSATION_IDS → ValueError ; "*" → autorisees is None
def test_kill_switch(self): # KILL_SWITCH="1" → None ; "false", "0", "" → Config
def test_eligible(self): # ["tri:diagnostic"] True ; + "diag:fait" False ; + "diag:fait","diag:relancer" True ; [] False
def test_plafond_et_liste_blanche(self): # 5 éligibles, plafond 3 → 3 traitées ; liste blanche {c2} → seule c2
def test_cycle_fait(self): # étiquettes : add en-cours, puis add diag:fait / remove en-cours, relancer ;
# une note qui commence par l'en-tête exact et contient le texte du diag
def test_mail_vide_ignore(self): # Review Focus 5
def test_erreur_passe_a_la_suivante(self):# Review Focus 3 : diag lève sur c1 → c1 "erreur" (en-cours retiré), c2 "fait"
def test_garde_arrete_tout(self): # Review Focus 2 : note_privee lève Garde sur c1 → c2 jamais lue, Garde remonte
def test_relance_ecarte_nos_notes(self): # Review Focus 4 : fil() avec une note privée de moi (exclue) et une d'un
# humain (dans le contexte, pas dans le mail)
def test_note_echappe_le_html(self): # texte "<script>" → "<script>" dans la note
- Step 2 : lancer, vérifier l'échec — Run :
.venv/bin/python -m unittest tests.test_run -v— Expected : ImportError. - Step 3 : écrire
support_diagnostic/run.py, avec le commentaire# ponytail: verrou orphelin non détecté (runner tué) : un humain retire diag:en-cours ; date de l'étiquette si ça arriveà la pose dediag:en-cours. - Step 4 : lancer tous les tests — Run :
.venv/bin/python -m unittest discover -s tests -v— Expected : OK (test_instancesauté). - Step 5 : commit
git commit -m "Cycle : conversations éligibles, agents, note privée, étiquettes d'état"
Task 5 : l'instance de test, de bout en bout
Files :
- Create :
instance-de-test/preparer.py,tests/test_instance.py
Interfaces :
-
Consumes :
traiter,Config(tâche 4),LibreDesk(tâche 2). -
Produces :
preparer.py <mot de passe System> <fichier du mail>: sur une instance neuve, crée la boîte e-mail (SMTP = Mailpit), les six étiquettes du contrat, le rôle « Agent IA » (les cinq permissions), l'agent et sa clé, une conversation du contact avec le mail du fichier, étiquetéetri:diagnostic; écrit dansinstance-de-test/.env(hors de git)LIBREDESK_URL,LIBREDESK_API_KEY,LIBREDESK_API_SECRET,CONVERSATION; reprend les appels deverifier.py(cookie de session sansSecure,csrf_tokenposé à la main,initiator: "contact"). -
Step 1 :
tests/test_instance.py, sauté sansLIBREDESK_TEST_URL:
def test_bout_en_bout_sans_envoi(self):
# instance préparée ; traiter() avec ecrire=True, autorisees={CONVERSATION}, diag factice (pas d'appel API) :
# la conversation porte diag:fait sans diag:en-cours ; son dernier message est private et commence par l'en-tête ;
# Mailpit (GET http://127.0.0.1:9125/api/v1/messages) : messages_count inchangé
- Step 2 : écrire
preparer.py, lancer l'instance neuve et le test
cd instance-de-test && docker compose -p ldtest down -v; LIBREDESK_SYSTEM_USER_PASSWORD='TestAdmin-2026!' docker compose -p ldtest up -d
.venv/bin/python -I instance-de-test/preparer.py 'TestAdmin-2026!' instance-de-test/mail-exemple.txt && set -a && . instance-de-test/.env && set +a && LIBREDESK_TEST_URL=$LIBREDESK_URL .venv/bin/python -m unittest tests.test_instance -v
Expected : OK. mail-exemple.txt : un mail inventé sur une station de Support-Agent/data/ (pas un vrai mail de client dans un dépôt public).
- Step 3 : le vrai diagnostic, une fois (critère de sortie de la phase ; coûte des crédits) :
set -a && . instance-de-test/.env && set +a && DRY_RUN=false ALLOWED_CONVERSATION_IDS=$CONVERSATION AIMSIGHT_DATA=$HOME/Support-Agent/data ANTHROPIC_API_KEY=… .venv/bin/python -m support_diagnostic.run
Expected : diag:fait ou diag:ignore ; la note dans l'interface (http://127.0.0.1:9100) ; Mailpit inchangé. Maxime juge la note.
- Step 4 : commit
git commit -m "Instance de test : préparation et test de bout en bout sans envoi"
Task 6 : les workflows Gitea et le mode d'emploi
Files :
- Create :
.gitea/workflows/tests.yml,.gitea/workflows/diagnostic.yml,README.md
Interfaces :
-
Consumes :
python -m support_diagnostic.runet ses variables (tâche 4). -
Step 1 :
tests.yml: surpush; Python 3.12 (actions/setup-python) ;pip install -r requirements.txt;python -m unittest discover -s tests -v. -
Step 2 :
diagnostic.yml: l'esquisse du §9.4 de la spec, sansschedule; entréesdry_run(défaut"true") etconversation(défaut"", passée enCONVERSATION) ;concurrency: support-diagnostic;AIMSIGHT_DATAabsent (hors de ce plan). -
Step 3 :
README.md: ce que fait le dépôt, la règle « aucun mail ne part » et ses garde-fous, les variables et secrets Gitea, lancer les tests, l'instance de test (renvoi àdocs/verifications.md). -
Step 4 : vérifier sur Gitea (le runner ne joint pas l'instance de test du poste : ce passage lit la production, en simulation, sans rien écrire ; Maxime : secrets
LIBREDESK_API_KEY,LIBREDESK_API_SECRET,ANTHROPIC_API_KEY, variableLIBREDESK_URLvers la production, avec la clé d'un rôle « Agent IA ») : pousser ;tests.ymlpasse ;diagnostic.ymllancé à la main en simulation liste les conversations éligibles (aucune tant que personne n'a posétri:diagnostic) et sort en code 0. Siconcurrency:est refusé, le retirer et le noter dansdocs/verifications.md. -
Step 5 : commit et push
git commit -m "Workflows Gitea : tests et diagnostic manuel en simulation" && git push