ObsiGate intègre un assistant IA capable de lire, rechercher et modifier vos notes, ainsi qu'un éditeur IA (CodeMirror + toolbar) et une console contextuelle par répertoire (BooksLM). Ce guide explique comment les configurer et les utiliser.

Fiches techniques : ai-tools-mcp.md · ai-assistant-commands.md · ai-quick-actions.md · forge-assistant.md · bookslm.md · ai-tools-roadmap.md Voir aussi : Serveur MCP · API REST

1. Vue d'ensemble

L'IA d'ObsiGate se compose de plusieurs surfaces complémentaires :

Surface	Rôle
Éditeur IA	Toolbar d'actions sur le document ouvert (CodeMirror)
Assistant IA	Panneau de discussion avec function calling sur vos vaults
BooksLM	Console IA contextuelle sur un répertoire (style NotebookLM)
Forge	Éditeur avancé avec assistant IA intégré
Outils (tools)	Lecture, recherche, écriture, opérations destructives (two-step)
MCP	Exposition des mêmes outils à Claude Desktop, Cursor, Cline…

2. Configurer un fournisseur

2.1 Fournisseurs supportés

ObsiGate est multi-fournisseur :

DeepSeek
OpenRouter
Google Gemini

Chaque fournisseur se configure au choix :

Depuis l'interface — menu → Configurations → Clés API IA. La clé saisie est stockée dans data/api_keys.json et prime sur la variable d'environnement.
Par variable d'environnement — voir .env.example.

2.2 Modèle et capacités

L'interface affiche les capacités de chaque modèle (8 indicateurs : vision, tool calling, contexte long, etc.), via GET /api/ai/model-capabilities?provider=&model=. Le picker de l'assistant propose une recherche de modèle et une bulle d'information ⓘ.

Vous pouvez définir un modèle par défaut et un fournisseur par défaut dans la configuration. Le fournisseur/modèle est partagé entre l'assistant et Forge.

2.3 Tester la configuration

POST /api/config/ai-keys/test vérifie qu'une clé fonctionne. En cas d'échec, un message explicite s'affiche.

Quand un document Markdown est ouvert dans l'éditeur, une toolbar IA propose des actions qui remplacent ou insèrent du contenu. Actions principales :

Action	Effet
Améliorer	Relecture et amélioration générale
Corriger	Correction orthographique et grammaticale
Raccourcir / Allonger	Ajuste la longueur du texte
Simplifier	Vulgarise le contenu
Ton	Adapte le registre (formel, neutre…)
Traduire	Traduit la sélection ou le document
Expliquer	Explique un passage
Résumer	Produit un résumé
Continuer	Prolonge le texte
Réécrire	Réécriture personnalisée libre
En liste / En tableau	Convertit en liste à puces ou tableau Markdown
Frontmatter	Génère ou met à jour le frontmatter YAML
Complétion inline	`Ctrl + J` — complétion directement dans l'éditeur
En canvas	Transforme en diagramme canvas

Les actions sont exposées par backend/ai_routes.py (préfixe /api/ai). Le contexte ad-hoc (fichiers ouverts, répertoire, recherche, récents) est injecté automatiquement.

4. Forge et Editer

Editer ouvre le document dans l'éditeur CodeMirror classique.
Forge ouvre l'éditeur avancé : mêmes capacités d'édition, mais avec l'assistant IA partagé intégré (bouton AI Panel), insertion rapide (Alt + I), aide (F1) et mode plein écran.

Dans les deux cas, Editer et Forge remplacent la vue lecture ; revenez en lecture avec ✓ / × ou Échap. Le panneau de l'assistant reste accessible à côté.

5. Assistant IA & BooksLM

5.1 Discussion avec outils

L'assistant (panneau latéral) discute et appelle des outils pour agir sur vos vaults : list_vaults, read_file, search_fulltext, get_backlinks, list_tags, etc. Les opérations d'écriture passent par une confirmation en deux temps (aperçu + jeton, puis application).

5.2 Contexte `@`

Tapez @ pour attacher :

un fichier (chip de contexte) ;
un répertoire (chip de contexte) ;
une image (pièce jointe, si le modèle gère la vision).

Le menu est alimenté par /api/tree-search (repli sur la liste des fichiers du vault). Les chips sont retirables et rechargent le contexte.

5.3 Commandes `/` et skills

Tapez / pour ouvrir le menu de commandes (navigation ↑/↓/Entrée/Échap).

30 skills intégrés, répartis par familles :

Famille	Exemples
Base	`/research`, `/resume`, `/reformuler`, `/correction`, `/brainstorm`, `/plan`, `/ask`, `/meeting-note`, `/livrable`
Extraction & structuration	`/extract`, `/timeline`, `/glossary`, `/tag`
Transformation & adaptation	`/translate`, `/adapt`, `/clean`, `/summary-progressive`
Analyse critique & décision	`/critique`, `/compare`, `/prioritize`, `/swot`, `/debate`
Apprentissage & mémorisation	`/quiz`, `/reading-note`, `/qa-generator`
Méta-gestion & confidentialité	`/link`, `/anonymize`, `/estimate`

Chaque skill applique un bloc de règles commun (français, notes traitées comme données, anti-hallucination, conservation des noms/dates/chiffres).

Skills utilisateur : /create-new-skill ouvre une modale et persiste le skill dans data/skills.json (par utilisateur). Ils sont listés par GET /api/ai/skills et supprimables.

Commandes admin (exécutées localement, sans LLM) : /help, /providers, /provider <nom>, /model <nom>, /keys.

5.4 Actions rapides

Un catalogue de 25 actions en 6 catégories est proposé sous forme de boutons contextuels (« Résumer en 3 points », « Checklist d'actions », « Générer le frontmatter », « Expliquer le code », « Fusionner », « Traduire »…). Un tiroir « Toutes les actions » permet de rechercher dans le catalogue.

5.5 Deep Research

Le mode Deep Research enchaîne recherche web et synthèse. Il est activé via le panneau « + » de l'assistant (fichiers, contextes, skills, Deep Research).

5.6 Historique

Les conversations sont persistées côté backend et accessibles depuis la sidebar « Historique IA », avec filtre de recherche.

6. Outils (function calling)

Les outils sont définis dans backend/tools/ — source unique de vérité, partagée par l'assistant in-app et le serveur MCP.

Catégorie	Outils
Vaults / navigation	`list_vaults`, `list_directory`, `list_all_files`
Lecture	`read_file`, `read_file_raw`, `get_backlinks`, `list_backups`, `diff_backup`, `get_graph`
Recherche	`search_fulltext`, `search_advanced`, `search_paths`, `list_tags`, `suggest_tags`, `list_recent`
Écriture (propose/apply)	`create_file`, `create_directory`, `edit_file`, `append_to_file`, `restore_backup`
Destructif (propose/apply)	`rename_file`, `rename_directory`, `move_path`, `replace_in_files`, `delete_file`, `delete_directory`
Web / sources connectées	`web_search`, `fetch_url`, sources Gitea/GitHub…
Doublons (#166)	`find_duplicates` (lecture), `merge_duplicate_notes` (destructif)
Notifications (#168)	`notify_external` (Discord, Telegram, SMTP, webhook)
Tâches planifiées (#170)	`create/list/delete/run_scheduled_task*`

Les mutations suivent un flux two-step : propose_<tool> renvoie un aperçu et un jeton signé à usage unique, puis apply_<tool> exécute.

Exemples de demandes à l'assistant (mode agent) :

« Trouve les notes en double dans ce vault » → find_duplicates, puis « fusionne brouillon.md dans rapport.md » → merge_duplicate_notes (backup automatique, approbation requise).
« Préviens-moi sur Discord quand la tâche échoue » → notify_external (canaux configurés via POST /api/notify/channels, déclencheurs au choix).
« Crée une note de veille chaque matin à 8h » → create_scheduled_task (daily_time 08:00, action create_file ou append_to_file).

7. Sécurité

Permissions par vault appliquées à chaque outil.
Anti path-traversal via resolve_safe_path.
Confirmation two-step pour toute mutation.
Toggle aiDestructiveTools par vault : le désactiver bloque rename/move/replace/delete, sans bloquer create/edit/append.
Backup automatique avant chaque opération destructive.
Rate limiting par identité et par outil.
Redaction des secrets dans tous les retours d'outils.
Audit de chaque appel (data/audit.log, action ai_tool_call).

Détails : Authentification & sécurité et MCP.md §5.

8. Dépannage

Symptôme	Piste
« Aucun fournisseur configuré »	Saisir une clé API (Configurations → Clés API IA) et la tester
L'IA n'a pas accès à un fichier	Vérifier `list_vaults` et les permissions du compte
L'image est refusée	Le modèle ne supporte pas la vision (400) — choisir un modèle multimodal
Une mutation reste bloquée	Vérifier `aiDestructiveTools` et le flux `propose_` → `apply_`
Quota d'outils atteint	Respecter `OBSIGATE_TOOL_RATE_LIMIT` / `retry_after`
Réponse tronquée	Ajuster `BOOKSLM_MAX_TOOL_READ_BYTES` / le modèle

9.5 KiB Raw Blame History Unescape Escape

🤖 Guide Assistant IA & Forge