Guide utilisateur

1. Chat assistant

Le chat général permet de dialoguer avec l'assistant IA. Vos conversations sont privées et isolées par compte utilisateur.

Fonctionnalités

• Nouvelle conversation — bouton + dans la barre latérale.
• Recherche — filtre les conversations par titre ou contenu.
• Interrompre — arrête une réponse en cours de génération.
• Export Markdown / PDF — boutons en haut à droite une fois une conversation ouverte.

Export

• Markdown — télécharge un fichier .md avec tout l'historique.
• PDF — ouvre une page imprimable ; utilisez « Enregistrer au format PDF » du navigateur.

Si aucune conversation n'existe au chargement, une conversation par défaut est créée automatiquement.

2. Espace Code

Mini-IDE dans le navigateur : explorateur de fichiers, éditeur CodeMirror et assistant capable de modifier réellement les fichiers du projet.

Projets

• Chaque utilisateur dispose de ses propres projets (isolation par compte).
• + Projet — modèle Site web (PHP).
• À la création : workspace, README (MySQL + SSH), base de données et conteneur preview lancés automatiquement.
• Télécharger — archive ZIP (fichiers, versions, conversations, export SQL de la base MySQL).
• Archiver / Supprimer — conteneur Docker arrêté et retiré.
• ↗ Workspace — listing des fichiers (/ws/{id}/).
• ↻ Preview — redéploie le conteneur (après erreur ou changement d'infra).
• ◇ Analyser le code / ↗ Voir le rapport — analyse qualité ; voir §4 Analyse du code.

Explorateur et éditeur

• Glisser-déposer de fichiers ou dossiers dans l'explorateur.
• Versions fichier — historique automatique par fichier (voir §8).
• ⊕ Version projet — snapshot manuel avec compte-rendu IA (voir §8).
• Ctrl+S — sauvegarde le fichier ouvert.

Assistant code

• Décrivez ce que vous voulez ; l'agent crée ou modifie les fichiers du workspace.
• L'agent s'adapte à la stack et aux conventions déjà présentes dans le projet.
• ↩ Annuler agent — annule la dernière série de modifications appliquées par l'agent.
• Interrompre — stoppe une réponse en cours (sans appliquer de modification si interrompu tôt).

Après les modifications de l'agent ou les vôtres, testez le code dans le conteneur preview — voir §3.

3. Tester le code (preview)

Chaque projet dispose d'un conteneur Docker dédié qui exécute votre code PHP. C'est l'outil principal pour valider un site pendant le développement.

Cycle de travail recommandé

1. Décrivez la tâche à l'agent — il modifie les fichiers du workspace.
2. Vérifiez ou ajustez le code dans l'éditeur ; Ctrl+S pour sauvegarder.
3. Ouvrez /preview/{id}/ dans un nouvel onglet (ou le lien preview depuis l'Espace Code).
4. Testez les pages, formulaires, API ; en cas d'erreur, revenez à l'IDE et corrigez.
5. PHP : les fichiers .php sont servis tout de suite après sauvegarde.

URL de test

En cas de problème

• Preview indisponible — conteneur arrêté ou image manquante : ↻ Preview dans l'Espace Code.
• HTTP 500 (PHP) — erreur dans le code du projet (BDD, syntaxe, includes…).
• Page blanche — consultez les logs via SSH (section §6) ou le README du projet.

La plateforme utilise l'image maia-preview-php sur le NUC : en cas de régression, signalez-le à l'admin.

4. Analyse du code (qualité)

L'Espace Code intègre une analyse statique du projet : détection de bugs, vulnérabilités, code mort, mauvaises pratiques, etc. Le moteur s'exécute côté serveur (service d'analyse type SonarQube) ; les résultats sont stockés dans le projet et consultables sans quitter l'IDE.

Lancer une analyse

1. Ouvrez l'Espace Code et sélectionnez un projet.
2. Cliquez sur ◇ Analyser le code dans la barre du haut.
3. Confirmez — un indicateur de progression s'affiche pendant le scan.
4. À la fin : message de succès et dossier Rapports (.maia) visible dans l'explorateur.

Le bouton n'apparaît que si l'analyse est activée sur l'instance (configuration admin). Un scan en cours désactive temporairement les boutons d'analyse.

Fichiers générés

• .maia/rapport-analyse.md — rapport lisible (export, impression).
• .maia/rapport-analyse.json — données structurées pour la modale.
• .maia-sonar-scan.log — journal technique du dernier scan (dépannage).

Lire le rapport (↗ Voir le rapport)

La modale Rapport d'analyse propose deux vues :

• Détails — problèmes regroupés par criticité (bloquant, critique, majeur, mineur, info) et par fichier ; chaque entrée est dépliable.
• Source — contenu brut du fichier Markdown.

Pour corriger rapidement : cliquez sur un problème (ou le lien fichier/ligne) — la modale se ferme et l'éditeur s'ouvre sur la ligne concernée. Vous pouvez aussi ouvrir le rapport dans l'éditeur via le bouton Éditeur, ou Actualiser pour régénérer le rapport depuis les données du dernier scan.

Quand l'utiliser ?

• Après une grosse série de modifications par l'agent — vérifier la qualité avant de tester en preview.
• Avant un partage ou une démo — repérer les erreurs évidentes.
• En complément du test manuel (§3) : l'analyse ne remplace pas l'exécution du site, elle pointe des risques dans le code source.

Limites et dépannage

• Durée variable (taille du projet, charge du serveur d'analyse).
• Message d'erreur en cas de service indisponible ou d'échec du scanner — réessayez plus tard ou contactez l'admin.
• À la suppression ou archivage du projet, le projet est aussi retiré du service d'analyse.

5. Aperçu conteneur (détails techniques)

Chaque projet dispose de son propre conteneur Docker, distinct de la plateforme Mon Agent IA.

Conteneur

Cycle de vie

• Création — déploiement Portainer (quelques secondes à ~2 min la première fois).
• Modification — fichiers immédiatement visibles (volume partagé).
• ↻ Preview — recrée la stack si le conteneur est en erreur.

Pour le mode d'emploi utilisateur (tester le code), voir surtout §3 Tester le code.

6. SSH conteneur (DEV)

Chaque conteneur preview expose un accès SSH root sur un port hôte aléatoire (mode développement).

• Identifiants dans workspace/README.md (section « SSH (DEV) »).
• Exemple : ssh -p 33042 root@192.168.1.254 (adapter hôte et port).
• Usage : composer install, pip install -r requirements.txt, logs, tests CLI.
• L'agent IA modifie les fichiers via l'éditeur — il ne se connecte pas en SSH à votre place.

Client SSH externe (Terminal, PuTTY) ou bouton ▸ Terminal dans l'Espace Code (shell web, session Maia uniquement).

7. Discussions (Espace Code)

Une discussion n'est pas votre connexion au site : c'est un fil de conversation avec l'assistant code, propre à un projet.

Utilisation

• La discussion active (nom cliquable + menu ▾) reçoit vos messages et l'historique affiché.
• + — démarre une nouvelle discussion sans mélanger l'historique.
• Les autres discussions du même projet servent de contexte à l'assistant (mémoire des décisions passées).

Nom et renommage

• À la création, le nom par défaut est la date et l'heure.
• Au premier message, l'assistant peut proposer un titre court décrivant le sujet.
• Cliquez sur le nom pour renommer : Entrée pour valider, Échap pour annuler.

Recherche dans la discussion

Le bouton loupe (à côté de +) ouvre un champ de recherche pour retrouver un mot ou une phrase dans les messages affichés.

• Les messages correspondants sont mis en évidence ; les autres sont atténués.
• Le compteur indique la position (2/5) ; les flèches ou Entrée / Maj+Entrée passent au résultat suivant ou précédent.
• Échap ou le bouton × ferme la recherche.

Quand créer une nouvelle discussion ?

• Changement de tâche (ex. page d'accueil → module admin).
• Historique trop long ou confus.
• Tester une autre approche sans effacer l'ancienne conversation.

8. Versions projet et versions fichier

Deux mécanismes distincts : l'un pour le projet entier, l'autre pour un fichier à la fois.

Versions projet (snapshots manuels)

Bouton ⊕ Version projet dans la barre du haut (si le module est activé).

• Archive complète dans project/.releases/ + mise à jour de VERSIONS.md et CHANGELOG.md.
• Compte-rendu IA des fonctionnalités modifiées (pas seulement les noms de fichiers).
• Aperçu avant création, liste des versions, vue chronologique (frise + détail au clic).
• Téléchargement de l'archive depuis le détail d'une version.
• ↩ Restaurer cette version — fichiers + base MySQL ; une sauvegarde de sécurité est créée automatiquement avant.

Versions fichier (historique automatique)

Bouton Versions fichier dans la barre de l'éditeur (fichier ouvert requis).

• Archive à chaque sauvegarde (Ctrl+S), autosave (~2 s) ou modification par l'agent.
• Stockage dans project/.versions/.
• Restauration d'une version antérieure du fichier courant depuis la modale.

Ne confondez pas Versions fichier (automatique, un fichier) et Version projet (manuel, snapshot complet).

9. Exporter une conversation

Disponible dans le Chat et l'Espace Code (discussion active).

Les boutons sont grisés tant qu'aucune conversation / discussion n'est sélectionnée.

10. Réponses à choix cliquables

L'agent peut proposer des boutons de réponse au lieu d'une simple liste numérotée (Chat et Espace Code).

1. L'agent pose une question avec des options, ou propose un plan par étapes.
2. Des boutons apparaissent sous le message.
3. Cliquez sur une option pour l'envoyer, ou écrivez une réponse libre.

Les étapes utilisent le même format <<<choices>>>. Module activable/désactivable en administration. Dans l'Espace Code, les boutons sont affichés sous la bulle, hors markdown.

11. Fournisseurs d'IA

L’administrateur configure un fournisseur pour le Chat et un autre (éventuellement différent) pour l’Espace Code. Les utilisateurs voient ensuite les modèles disponibles dans les sélecteurs (format fournisseur|modèle).

ILAAS

Routeur LLM compatible OpenAI (https://llm.ilaas.fr/v1). Une clé API donne accès à un catalogue de modèles hébergés (Llama, Mistral, GPT-OSS, etc.). La plateforme appelle /v1/models et /v1/chat/completions.

ALBERT

Albert API (Etalab / DINUM) : offre d’IA générative pour le secteur public français, avec des modèles open-weight et une API compatible OpenAI. Utile pour un usage plus souverain que les clouds commerciaux classiques.

LITELLM

LiteLLM est un proxy : il traduit une API OpenAI unique vers des dizaines de backends (OpenAI, Azure, Anthropic, Ollama, vLLM…). Vous exposez les modèles dans LiteLLM ; Mon Agent IA se connecte uniquement au proxy (URL + clé master ou virtual key), comme pour ILAAS ou ALBERT.

• Endpoints utilisés : /v1/models, /v1/chat/completions (streaming inclus).
• Exemple d’URL locale : http://192.168.x.x:4001.
• Avantage : un seul point de contrôle (clés, quotas, logs) pour plusieurs fournisseurs derrière.

Résumé public aussi sur l’accueil : Fournisseurs d’IA.

12. Modules fonctionnels

La plateforme propose des modules optionnels. Un administrateur les active ou les désactive dans Administration → Paramètres selon le besoin.

Vue condensée sur l’accueil : Modules activables.

13. Administration

Réservée aux comptes avec le rôle admin.

Tableau de bord

• Espace disque occupé par data/.
• Nombre de projets, utilisateurs, conversations chat.
• Connexions actives (utilisateurs connectés récemment).
• Journal des événements récents (connexions, admin, erreurs LLM, projets…).

Autres pages admin

• Utilisateurs — créer, réinitialiser mot de passe, supprimer des comptes.
• Paramètres — fournisseurs LLM (ILAAS, ALBERT, LITELLM), preprompts (chat, code), MySQL, modules fonctionnels (voir §12).
• Projets — vue globale, suppression de projets (tous utilisateurs).

Les logs détaillés sont enregistrés dans data/logs/ (format JSON, un fichier par jour).

Raccourcis utiles