Compaction UI v2.1.0
Système de compactage mémoire pour l'interface OpenClaw Control UI — exécution en arrière-plan avec notifications toast, déclenchement automatique à des seuils de tokens configurables, paragraphe de résumé de conversation dans la sortie compactée, onglet de paramètres dédié avec sélecteur de modèle et historique des résultats.
Statut : ✅ Actif
| Composant | Statut |
|---|---|
| Bouton Jauge de Contexte | ✅ Fonctionnel |
| Compactage en Arrière-plan (toast) | ✅ Fonctionnel |
| Déclenchement Automatique | ✅ Fonctionnel |
| Paragraphe de Résumé de Conversation | ✅ Fonctionnel |
| Onglet Paramètres (enregistré via plugin) | ✅ Fonctionnel |
| Sélecteur de Modèle | ✅ Fonctionnel |
| Stockage et Visualisation du Dernier Résultat | ✅ Fonctionnel |
| Persistance et Rechargement des Paramètres | ✅ Fonctionnel |
| Hiérarchie d'Authentification (OAuth > API > Fallback) | ✅ Fonctionnel |
| Filtres d'Historique de Chat | ✅ Fonctionnel |
| Isolation Complète en Arrière-plan (sans interférence avec le chat) | ✅ Fonctionnel |
Fonctionnalités
1. Bouton Jauge de Contexte (app-render.helpers.ts)
Un anneau de progression SVG circulaire dans la barre d'outils du chat qui sert également de déclencheur manuel de compactage.
- Emplacement : Après le menu déroulant de sélection de session dans
renderChatControls() - Source de données :
sessionsResult.sessions[].totalTokensetcontextTokensdes lignes de session - Couleurs : Vert (<60%), Jaune (60-85%), Rouge (≥85%)
- Désactivé : Lorsque l'utilisation est <20% ou pendant un compactage actif
- Info-bulle : Affiche "Contexte : XK / YK tokens (Z%)"
2. Compactage en Arrière-plan (Toast)
Au clic (ou déclenchement automatique), le compactage s'exécute en arrière-plan en utilisant le système de toast standard en bas à droite — aucune modale bloquante. L'interface utilisateur reste entièrement interactive.
- Toast d'exécution : Affiche "Compactage mémoire" avec un spinner
- Toast de fin : Affiche "Compacté : XK → YK" avec une coche (se ferme automatiquement après 5s)
- Toast d'erreur : Affiche un message d'échec (se ferme automatiquement après 5s)
- Utilise le système
backgroundJobToastscohérent avec tous les autres processus en arrière-plan (cron, extraction de connaissances, etc.)
3. Compactage Automatique
Après chaque réponse de chat (événement final), l'interface vérifie l'utilisation des tokens par rapport au seuil configuré. Si dépassé :
- Le compactage en arrière-plan se déclenche automatiquement
- Un toast affiche "Auto-compactage (X%)" avec l'utilisation actuelle
- Un délai de 5 minutes empêche les déclenchements répétés
- Le chat se rafraîchit automatiquement après un compactage réussi
- Suppression silencieuse du toast si rien n'a été compacté
4. Paragraphe de Résumé de Conversation
Chaque sortie de compactage commence désormais par une section ## Résumé de la Conversation avant la section structurée ## Objectif. Il s'agit d'un paragraphe de 3 à 6 phrases en langage naturel qui :
- Décrit le(s) sujet(s) général(aux) de la conversation
- Explique le déroulement de la discussion et les transitions clés
- Résume comment la conversation a progressé
- Rédigé au passé comme un aperçu narratif
Implémentation : Des instructions personnalisées sont injectées dans l'appel LLM de compactage en amont via compact.ts. L'instruction est ajoutée avant toutes instructions personnalisées fournies par l'utilisateur (via /compact [instructions]), afin que les deux coexistent.
Exemple de sortie :
## Résumé de la Conversation
La conversation a commencé avec l'utilisateur demandant des améliorations du système
de compactage, en particulier le passage d'une modale bloquante à des toasts en arrière-plan.
La discussion s'est ensuite orientée vers l'ajout d'un onglet de paramètres avec des
commandes de compactage automatique. Après avoir implémenté et testé ces fonctionnalités,
l'utilisateur a remarqué que les paramètres ne persistaient pas lors des navigations entre
les onglets, ce qui a conduit à une correction du cache d'état au niveau du module.
Enfin, l'utilisateur a demandé l'ajout d'un paragraphe de résumé narratif à la sortie
du compactage pour un meilleur contexte.
## Objectif
...
5. Onglet Paramètres (Enregistré via Plugin)
Un onglet Compaction dédié sous le groupe de navigation Agent, enregistré via l'architecture Plugin UI.
Enregistrement : plugins-ui.ts → BUILTIN_UI_VIEWS avec id: "compaction", group: "agent", position: 7, icon: "archive"
Cartes :
Carte d'Auto-compactage
- Interrupteur : Activer/désactiver le compactage automatique
- Curseur de seuil : 10% à 95% (par défaut : 60%)
- Codage couleur : Vert (<60%), Jaune (60-85%), Rouge (≥85%)
Carte du Modèle
- Menu déroulant : Sélectionner un modèle spécifique pour le compactage ou utiliser le modèle par défaut de la session
- Regroupé par fournisseur avec affichage de la taille de la fenêtre de contexte
- Avertissement lorsqu'un modèle personnalisé est sélectionné (rappel de la clé API)
- Repli : Si le modèle personnalisé échoue, retombe automatiquement sur le modèle par défaut de la session
Carte de Stockage des Résultats
- Interrupteur : Option pour enregistrer le texte du résumé compacté pour révision
Carte du Dernier Compactage
- Avant/Après : Grands compteurs de tokens stylisés dans une grille à 2 colonnes
- Statistiques : Tokens sauvegardés, pourcentage de réduction, type de déclencheur, horodatage, clé de session
- Voir les Résultats : Visualiseur de résumé extensible (lorsque le stockage est activé)
- Effacer : Réinitialiser le résultat stocké
- Astuce : Affiche le message "Activer le stockage des résultats" lorsque le stockage est désactivé
Gestion d'État :
- L'état au niveau du module persiste entre les rendus au sein d'une session
- Les paramètres sont rechargés depuis le backend à chaque visite de l'onglet (seuil d'obsolescence de 2 secondes)
resetCompactionSettingsState()est exportée pour les tests et les changements d'onglet
6. Hiérarchie d'Authentification
Le compactage utilise resolveApiKeyForProvider via getApiKeyForModel — la même chaîne d'authentification que le chat :
OAuth → Clé API → Repli
Aucune configuration distincte nécessaire. Si OAuth (Claude Max) est configuré comme profil d'authentification principal, le compactage l'utilise automatiquement. La sélection de modèle personnalisé utilise cette même chaîne d'authentification de manière indépendante.
7. Stockage des Résultats
Lorsqu'il est activé, le résultat de compactage le plus récent est persistant dans {agentDir}/compaction-config.json :
{
"settings": {
"autoEnabled": true,
"autoThresholdPercent": 60,
"storeLastResult": true,
"compactionModel": "anthropic/claude-sonnet-4-6"
},
"lastResult": {
"timestamp": 1709283600000,
"trigger": "manual",
"tokensBefore": 50614,
"tokensAfter": 4766,
"tokensSaved": 45848,
"percentReduction": 91,
"sessionKey": "agent:main:main",
"summary": "## Résumé de la Conversation\nLa conversation a porté sur...\n\n## Objectif\n..."
}
}
Lorsque le stockage est désactivé, les métadonnées (horodatages, compteurs de tokens) sont toujours sauvegardées mais le texte du résumé est omis.
8. Filtres d'Historique de Chat
- Filtrage NO_REPLY/HEARTBEAT_OK : Ignore les messages d'assistant contenant exactement ces textes
- Séparateur de compactage : Affiche une ligne de séparation étiquetée pour les messages
__openclaw.kind === "compaction"
Architecture
RPCs Backend
| Méthode | Description |
|---|---|
sessions.compact | Exécute le compactage (enregistre le résultat après la fin) |
compaction.getSettings | Lit les paramètres depuis le fichier de configuration |
compaction.saveSettings | Met à jour les paramètres (seuil automatiquement limité à 10-95%) |
compaction.getLastResult | Récupère le dernier résultat de compactage stocké |
compaction.clearLastResult | Efface le résultat stocké |
Fichiers Modifiés
| Fichier | Objectif |
|---|---|
src/gateway/server-methods/compaction.ts | RPCs de paramètres, E/S de configuration, enregistrement des résultats |
src/gateway/server-methods/sessions.ts | sessions.compact RPC (enregistre le résultat après compactage) |
src/gateway/server-methods/plugins-ui.ts | Enregistrement de la vue du plugin |
src/gateway/server-methods.ts | Câblage des gestionnaires |
src/gateway/server-methods-list.ts | Enregistrement des méthodes |
src/gateway/method-scopes.ts | Enregistrement des portées |
src/agents/pi-embedded-runner/compact.ts | Injection d'instructions de résumé de chat |
ui/src/ui/app-render.helpers.ts | Jauge de contexte + déclencheur de toast en arrière-plan |
ui/src/ui/app-gateway.ts | Vérification d'auto-compactage après l'événement final |
ui/src/ui/views/compaction-settings.ts | Vue de l'onglet paramètres |
ui/src/ui/app-render.ts | Câblage des vues + import |
ui/src/ui/views/chat.ts | Filtres d'historique de chat |
Fichier de Configuration
{agentDir}/compaction-config.json — par agent, créé lors de la première sauvegarde des paramètres.
Enregistrement du Plugin
L'onglet de compactage est enregistré comme une vue de plugin intégrée dans plugins-ui.ts :
{
id: "compaction",
label: "Compactage",
subtitle: "Gestion de la mémoire",
icon: "archive",
group: "agent",
position: 7,
pluginId: "compaction-ui",
}
Problèmes Connus
- Les paramètres ne persistent pas lors des visites d'onglets : Corrigé dans la v2.1.0. Le drapeau
_state.loadedau niveau du module empêchait les rechargements. Maintenant, les paramètres sont rechargés toutes les 2 secondes lors de la réentrée dans l'onglet. - Le sélecteur de modèle nécessite des clés API : Si vous sélectionnez un modèle personnalisé, assurez-vous que la clé API du fournisseur est configurée. L'interface affiche un avertissement.
- Format du modèle de compactage : Doit être au format
"fournisseur/modèle"(par exemple"anthropic/claude-sonnet-4-6"). Les formats invalides sont ignorés silencieusement et reviennent au modèle par défaut de la session. - La propagation du skip-set parentId doit être limitée aux messages : Lors du filtrage des messages de vidage mémoire de
readSessionMessages, le skip-set doit UNIQUEMENT se propager à travers les entrées avec un champmessage. Les entrées de protocole non-message (type:"custom") font le pont entre les tours logiques — si leurs ID entrent dans le skip-set, la conversation restante entière devient cachée. La correction : vérifier uniquement les entréesparsed?.messagedans le skip-set, et n'ajouter leurs ID que si nécessaire. - Aucune modale bloquante — jamais : Le bouton de jauge dans
app-render.helpers.tsne doit JAMAIS afficher une superposition modale plein écran. Le compactage est un processus en arrière-plan ; tout statut est communiqué via le système de toast en bas à droite. Supprimez toute superposition conditionnée parposition:fixed; inset:0surcompactState.phase. Le bouton peut afficher une icône de spinner pendant l'exécution, mais ne doit pas bloquer l'interface.
Journal des Modifications
v2.1.0
- Paragraphe de résumé de conversation : La sortie de compactage commence désormais par un paragraphe narratif
## Résumé de la Conversationavant les sections structurées - Sélecteur de modèle : Choisir un modèle spécifique pour le compactage ou utiliser le modèle par défaut de la session, avec un menu déroulant regroupé par fournisseur
- Correction du rechargement des paramètres : L'onglet recharge désormais les paramètres depuis le backend toutes les 2 secondes au lieu de les mettre en cache indéfiniment
- Fichiers de référence mis à jour :
references/synchronisé avec la source actuelle
v2.0.0
- Compactage en arrière-plan : Remplacement de la modale bloquante plein écran par un toast de tâche en arrière-plan
- Auto-compactage : Déclenchement après une réponse de chat lorsque l'utilisation des tokens dépasse le seuil (configurable, par défaut 60%, délai de 5 minutes)
- Onglet paramètres : Onglet Compactage enregistré via plugin sous le groupe de navigation Agent
- Enregistrement des résultats :
sessions.compactenregistre les compteurs de tokens avant/après et un résumé optionnel - Hiérarchie d'authentification : Même chaîne OAuth → API → Repli que pour le chat
- RPCs de paramètres :
compaction.getSettings,compaction.saveSettings,compaction.getLastResult,compaction.clearLastResult
v1.0.0
- Première version : Bouton jauge de contexte, modale bloquante avec phases animées,
sessions.compactRPC avec résumé LLM, filtrage d'historique de chat NO_REPLY/HEARTBEAT_OK, lignes de séparation de compactage