231 lines
9.5 KiB
Markdown
231 lines
9.5 KiB
Markdown
# 🤖 Guide Assistant IA & Forge
|
||
|
||
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`](../features/ai-tools-mcp.md) ·
|
||
> [`ai-assistant-commands.md`](../features/ai-assistant-commands.md) ·
|
||
> [`ai-quick-actions.md`](../features/ai-quick-actions.md) ·
|
||
> [`forge-assistant.md`](../features/forge-assistant.md) ·
|
||
> [`bookslm.md`](../features/bookslm.md) ·
|
||
> [`ai-tools-roadmap.md`](../features/ai-tools-roadmap.md)
|
||
> **Voir aussi :** [Serveur MCP](./MCP.md) · [API REST](./API_REST.md)
|
||
|
||
---
|
||
|
||
## 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 :
|
||
|
||
1. **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.
|
||
2. **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.
|
||
|
||
---
|
||
|
||
## 3. Éditeur IA (toolbar)
|
||
|
||
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é](./AUTHENTIFICATION_SECURITE.md) et
|
||
[`MCP.md`](./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 |
|