From 1f6f95a3a094501c4a2c0b3ec7f1ead38ec32f04 Mon Sep 17 00:00:00 2001 From: StillHammer Date: Wed, 26 Nov 2025 17:17:03 +0800 Subject: [PATCH] docs: Update succession document for MCP integration session MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/SUCCESSION.md | 249 +++++++++++++++++++++++++++------------------ 1 file changed, 152 insertions(+), 97 deletions(-) diff --git a/docs/SUCCESSION.md b/docs/SUCCESSION.md index b85bcea..6a822c1 100644 --- a/docs/SUCCESSION.md +++ b/docs/SUCCESSION.md @@ -1,124 +1,179 @@ -# Document de Succession - Refactoring AISSIA +# Document de Succession - AISSIA Agent Vocal -## Contexte +## Contexte Actuel -Refactoring du code AISSIA pour le rendre conforme aux principes GroveEngine (audit initial : 33% conforme, 2/6 modules). +AISSIA est maintenant un **assistant vocal agentique** basé sur GroveEngine, capable d'utiliser des tools (internes + MCP) pour accomplir des tâches. Architecture "Claude Code en vocal". -## Ce qui a été fait +**Dernier commit** : `059709c` - feat: Implement MCP client and internal tools for agentic LLM -### 1. Architecture Services (nouveau) +## Ce qui a été fait (Session actuelle) -Créé 4 services dans `src/services/` qui gèrent l'infrastructure : +### 1. Infrastructure Tools Internes -| Service | Fichiers | Responsabilité | -|---------|----------|----------------| -| LLMService | `LLMService.hpp/.cpp` | HTTP vers Claude/OpenAI API | -| StorageService | `StorageService.hpp/.cpp` | SQLite persistence | -| PlatformService | `PlatformService.hpp/.cpp` | Win32 window tracking | -| VoiceService | `VoiceService.hpp/.cpp` | TTS/STT engines | +Créé `src/shared/tools/` : -Interface commune : `IService.hpp` +| Fichier | Description | +|---------|-------------| +| `IOBridge.hpp` | Request/response synchrone sur IIO async (correlation_id) | +| `InternalTools.hpp/.cpp` | 11 tools pour interagir avec les modules GroveEngine | -### 2. Modules refactorisés (logique pure) +**Tools disponibles** : +- **Scheduler** : `get_current_task`, `list_tasks`, `start_task`, `complete_task`, `start_break` +- **Monitoring** : `get_focus_stats`, `get_current_app` +- **Storage** : `save_note`, `query_notes`, `get_session_history` +- **Voice** : `speak` -| Module | Avant | Après | Changements | -|--------|-------|-------|-------------| -| AIModule | 306 lignes, HTTP direct | ~170 lignes | Publie `llm:request`, écoute `llm:response` | -| StorageModule | 273 lignes, sqlite3 | ~130 lignes | Publie `storage:save_*` | -| MonitoringModule | 222 lignes, Win32 | ~190 lignes | Écoute `platform:window_*` | -| VoiceModule | 209 lignes, COM/TTS | ~155 lignes | Publie `voice:speak` | -| SchedulerModule | - | - | Topics corrigés (`:` au lieu de `/`) | -| NotificationModule | - | - | Déjà conforme | +### 2. Client MCP -### 3. main.cpp réécrit +Créé `src/shared/mcp/` : -- Initialise les 4 services avant les modules -- `MessageRouter` gère le routage IIO entre services et modules -- Services process() avant modules dans la boucle principale +| Fichier | Description | +|---------|-------------| +| `MCPTypes.hpp` | Types MCP (Tool, Resource, ServerConfig, JSON-RPC) | +| `MCPTransport.hpp` | Interface transport abstrait | +| `StdioTransport.hpp/.cpp` | Transport stdio (fork/exec + JSON-RPC) | +| `MCPClient.hpp/.cpp` | Orchestration multi-serveurs MCP | -### 4. CMakeLists.txt +**Serveurs MCP supportés** (désactivés par défaut dans `config/mcp.json`) : +- `filesystem` - read/write fichiers +- `brave-search` - recherche web +- `fetch` - HTTP requests +- `memory` - knowledge graph -- SQLite bundled dans `deps/sqlite/` (amalgamation) -- OpenSSL rendu optionnel -- Nouvelles targets : `AissiaServices`, `AissiaLLM`, `AissiaPlatform`, `AissiaAudio` +### 3. Handlers dans les Modules -## État du build +Chaque module répond aux requêtes tools via IIO : -### Problème actuel -``` -CMake Error: Cannot determine link language for target "sqlite3" +| Module | Topics écoutés | Topic réponse | +|--------|---------------|---------------| +| SchedulerModule | `scheduler:query`, `scheduler:command` | `scheduler:response` | +| MonitoringModule | `monitoring:query` | `monitoring:response` | +| StorageModule | `storage:query`, `storage:command` | `storage:response` | +| VoiceModule | `voice:command` | (fire-and-forget) | + +### 4. Intégration LLMService + +`LLMService` unifie tous les tools : + +```cpp +void LLMService::initializeTools() { + // 1. Tools internes (via GroveEngine IIO) + m_internalTools = std::make_unique(m_io); + + // 2. Tools MCP (via serveurs externes) + m_mcpClient = std::make_unique(); + m_mcpClient->loadConfig("config/mcp.json"); + m_mcpClient->connectAll(); +} ``` -### Fix appliqué (dans CMakeLists.txt) -```cmake -enable_language(C) # SQLite is C code -add_library(sqlite3 STATIC - ${CMAKE_CURRENT_SOURCE_DIR}/deps/sqlite/sqlite3.c -) -set_target_properties(sqlite3 PROPERTIES LINKER_LANGUAGE C) +## Architecture Finale + +``` +┌─────────────────────────────────────────────────────────────┐ +│ LLMService │ +│ (Agentic Loop) │ +├─────────────────────────────────────────────────────────────┤ +│ ToolRegistry │ +│ ├── InternalTools (11 tools) ─────► IIO pub/sub │ +│ └── MCPClient (tools externes) ─────► stdio JSON-RPC │ +└─────────────────────────────────────────────────────────────┘ + │ + ┌──────────────┬─────┴──────┬──────────────┐ + Scheduler Monitoring Storage Voice + Module Module Module Module ``` -### Pour terminer le build +## État du Build + +✅ **Compile sans erreur** - `cmake --build build -j4` + +Fixes appliqués cette session : +- Ajout `#include ` partout où `stdout_color_mt` est utilisé +- Ajout `#include ` dans les modules .cpp +- `const_cast` pour `getChildReadOnly` (IDataNode non-const) +- Fonction `cloneDataNode()` dans main.cpp (workaround pour `clone()` manquant) +- Restauration du symlink `external/GroveEngine` + +## Fichiers Clés + +### Nouveaux (cette session) +``` +src/shared/tools/ +├── IOBridge.hpp +├── InternalTools.hpp +└── InternalTools.cpp + +src/shared/mcp/ +├── MCPTypes.hpp +├── MCPTransport.hpp +├── StdioTransport.hpp +├── StdioTransport.cpp +├── MCPClient.hpp +└── MCPClient.cpp + +config/mcp.json +docs/PLAN_MCP_INTEGRATION.md +``` + +### Modifiés (cette session) +``` +CMakeLists.txt # Ajout AissiaTools lib +src/services/LLMService.hpp # Ajout InternalTools + MCPClient +src/services/LLMService.cpp # initializeTools() +src/modules/SchedulerModule.* # Tool handlers +src/modules/MonitoringModule.* # Tool handlers +src/modules/StorageModule.* # Tool handlers + Note struct +src/modules/VoiceModule.* # Tool handlers +``` + +## Prochaines Étapes + +### Priorité Haute +1. **Tester la boucle agentique** - Envoyer une requête LLM et vérifier que les tools sont appelés +2. **Activer un serveur MCP** - Tester avec `filesystem` par exemple +3. **Streaming responses** - Pour feedback temps réel pendant la génération + +### Priorité Moyenne +4. **Améliorer IOBridge** - Le timeout de 5s peut être trop court pour certains tools +5. **Ajouter plus de tools internes** - Ex: `add_task`, `set_reminder`, etc. +6. **Persistance des notes** - Actuellement en mémoire dans StorageModule + +### Priorité Basse +7. **Tests unitaires** - Mock IIO pour tester InternalTools +8. **Tests MCP** - Mock server pour tester StdioTransport +9. **Optimisation latence** - Le request/response via IIO ajoute ~100ms + +## Pour Tester + ```bash -cd C:\Users\alexi\Documents\projects\aissia -rm -rf build # Clean start recommandé -cmake -G "MinGW Makefiles" -B build -cmake --build build -j4 +# Build +cd /mnt/e/Users/Alexis\ Trouvé/Documents/Projets/Aissia +cmake -B build && cmake --build build -j4 + +# Run +./build/aissia + +# Les modules se chargent automatiquement depuis build/modules/ +# Les tools sont enregistrés au démarrage de LLMService ``` -## Fichiers créés/modifiés +## Variables d'Environnement Requises -### Nouveaux fichiers -- `src/services/IService.hpp` -- `src/services/LLMService.hpp` / `.cpp` -- `src/services/StorageService.hpp` / `.cpp` -- `src/services/PlatformService.hpp` / `.cpp` -- `src/services/VoiceService.hpp` / `.cpp` -- `deps/sqlite/sqlite3.c` (téléchargé) -- `deps/sqlite/sqlite3.h` +```bash +# Pour Claude API +export ANTHROPIC_API_KEY="sk-ant-..." -### Fichiers modifiés -- `src/main.cpp` - réécrit complètement -- `src/modules/AIModule.h` / `.cpp` -- `src/modules/StorageModule.h` / `.cpp` -- `src/modules/MonitoringModule.h` / `.cpp` -- `src/modules/VoiceModule.h` / `.cpp` -- `src/modules/SchedulerModule.h` / `.cpp` -- `CMakeLists.txt` -- `external/GroveEngine/CMakeLists.txt` (OpenSSL optionnel) +# Pour MCP servers (optionnel) +export BRAVE_API_KEY="..." # Si brave-search activé +``` -## Communication Inter-Modules (Topics) +## Commandes Git Utiles -Format : `module:event` (utiliser `:` pas `/`) +```bash +# Voir les derniers commits +git log --oneline -5 -### LLM -- `llm:request` - Module -> Service -- `llm:response` - Service -> Module -- `llm:error` - Service -> Module - -### Storage -- `storage:save_session` - Module -> Service -- `storage:save_app_usage` - Module -> Service -- `storage:session_saved` - Service -> Module -- `storage:ready` - Service -> Module - -### Platform -- `platform:window_info` - Service -> Module -- `platform:window_changed` - Service -> Module -- `platform:idle_detected` - Service -> Module - -### Voice -- `voice:speak` - Module -> Service -- `voice:speaking_started` - Service -> Module - -### Scheduler (existant) -- `scheduler:hyperfocus_alert` -- `scheduler:break_reminder` -- `scheduler:focus_session_started` - -## Prochaines étapes - -1. Terminer le build (fix SQLite C language) -2. Tester compilation de tous les modules -3. Vérifier hot-reload fonctionne -4. Tests d'intégration services <-> modules +# Voir les changements depuis le refactoring +git diff 26a5d34..HEAD --stat +```