docs: guides d'utilisation, capture reelle et README ameliores
This commit is contained in:
@@ -91,6 +91,7 @@ bash scripts/run-e2e-local.sh -g "nom du test" # filtre / --headed
|
||||
| Travail à venir + index | `docs/ROADMAP.md` |
|
||||
| Historique des versions | `CHANGELOG.md` |
|
||||
| Conception par feature | `docs/features/<slug>.md` |
|
||||
| Guides d'utilisation | `docs/GUIDES/` |
|
||||
| Archive du complété | `docs/archive/COMPLETED_v1-v2.md` |
|
||||
| Bugs / TODO | `docs/ISSUES_TODOLIST.md` |
|
||||
| Build & releases | `docs/DEVELOPMENT_AND_RELEASES.md` |
|
||||
|
||||
+22
-1
@@ -6,7 +6,7 @@ Format basé sur [Keep a Changelog](https://keepachangelog.com/fr/1.1.0/),
|
||||
et [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
> **En cours de développement** : les changements à venir sont listés dans la section
|
||||
> [Unreleased](#unreleased). La dernière version livrée est **2.16.5**.
|
||||
> [Unreleased](#unreleased). La dernière version livrée est **2.16.6**.
|
||||
|
||||
---
|
||||
|
||||
@@ -14,6 +14,27 @@ et [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
---
|
||||
|
||||
## [2.16.6] — 2026-09-22
|
||||
|
||||
### Ajouté
|
||||
|
||||
- **Guides d'utilisation `docs/GUIDES/`** : nouvel index + 10 guides FR
|
||||
(prise en main, recherche/PDF/Excalidraw, assistant IA & Forge,
|
||||
collaboration temps réel, PWA & hors-ligne, API REST, serveur MCP,
|
||||
authentification & sécurité, déploiement Docker, desktop Tauri). Le guide MCP
|
||||
est déplacé dans `docs/GUIDES/MCP.md` ; `docs/MCP_GUIDE.md` devient une page
|
||||
de redirection.
|
||||
|
||||
### Modifié
|
||||
|
||||
- **README.md / README.fr.md** : capture d'écran réelle de l'application en tête
|
||||
(remplace l'illustration ASCII) ; un emoji sur chaque entrée de la table des
|
||||
matières ; nouvelle section « Guides » avec liens vers `docs/GUIDES/` ;
|
||||
renvois vers les guides depuis les sections API, Recherche, Sécurité, Desktop
|
||||
et Collaboration.
|
||||
|
||||
---
|
||||
|
||||
## [2.16.5] — 2026-09-22
|
||||
|
||||
### Corrigé
|
||||
|
||||
+63
-39
@@ -1,61 +1,75 @@
|
||||
# ObsiGate
|
||||
|
||||
> **Version française** — ce document est le miroir synchronisé de [README.md](README.md) (référence complète). Dernière synchronisation : juin 2026.
|
||||
> **Version française** — ce document est le miroir synchronisé de [README.md](README.md) (référence complète). Dernière synchronisation : septembre 2026.
|
||||
|
||||
**Porte d'entrée web ultra-léger pour vos vaults Obsidian** — Accédez, naviguez et recherchez dans toutes vos notes Obsidian depuis n'importe quel appareil via une interface web moderne et responsive.
|
||||
|
||||
[]()
|
||||
[]()
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://www.docker.com/)
|
||||
[](https://www.python.org/)
|
||||
[](https://git.dracodev.net/Projets/ObsiGate/actions)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ [🔍 Recherche...] [☀/🌙 Thème] ObsiGate │
|
||||
├──────────────┬──────────────────────────────────────────┤
|
||||
│ SIDEBAR │ CONTENT AREA │
|
||||
│ ▼ Recettes │ 📄 Titre du fichier │
|
||||
│ 📁 Soupes │ Tags: #recette #rapide │
|
||||
│ 📄 Pizza │ [Contenu Markdown rendu] │
|
||||
│ ▼ IT │ │
|
||||
│ 📁 Docker │ │
|
||||
│ Tags Cloud │ │
|
||||
└──────────────┴──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
|
||||
> Interface web d'ObsiGate : sidebar multi-vault, recherche globale, statistiques et raccourcis.
|
||||
|
||||
---
|
||||
|
||||
## 📚 Guides
|
||||
|
||||
Les **guides d'utilisation** pas à pas se trouvent dans [`docs/GUIDES/`](docs/GUIDES/) :
|
||||
|
||||
| Guide | Contenu |
|
||||
|---|---|
|
||||
| 🚀 [Prise en main](docs/GUIDES/PRISE_EN_MAIN.md) | Premier lancement, interface, navigation, vaults, raccourcis |
|
||||
| 🔍 [Recherche, PDF & Excalidraw](docs/GUIDES/RECHERCHE_PDF_EXCALIDRAW.md) | Syntaxe de requête, recherche sémantique, lecteur PDF, diagrammes |
|
||||
| 🤖 [Assistant IA & Forge](docs/GUIDES/ASSISTANT_IA_FORGE.md) | Fournisseurs, éditeur IA, BooksLM, Forge, commandes `@` / `/` |
|
||||
| 📝 [Édition & collaboration](docs/GUIDES/COLLABORATION.md) | Édition simultanée, curseurs distants, persistance |
|
||||
| 📱 [PWA & hors-ligne](docs/GUIDES/PWA_HORS_LIGNE.md) | Installation, cache hors-ligne, file de synchro, notifications |
|
||||
| 🔌 [API REST](docs/GUIDES/API_REST.md) | Authentification, clés API, endpoints, exemples `curl`, SSE |
|
||||
| 🧩 [Serveur MCP](docs/GUIDES/MCP.md) | Brancher Claude Desktop, Cursor, Cline… sur vos vaults |
|
||||
| 🔒 [Authentification & sécurité](docs/GUIDES/AUTHENTIFICATION_SECURITE.md) | Utilisateurs, MFA, permissions par vault, durcissement |
|
||||
| 🐳 [Déploiement Docker](docs/GUIDES/DEPLOIEMENT_DOCKER.md) | `docker-compose`, volumes, reverse proxy, mises à jour |
|
||||
| 🖥️ [Desktop (Tauri)](docs/GUIDES/DESKTOP.md) | Installation, premier lancement, build depuis les sources, dépannage |
|
||||
|
||||
> Index complet : [`docs/GUIDES/README.md`](docs/GUIDES/README.md).
|
||||
|
||||
---
|
||||
|
||||
## 📋 Table des matières
|
||||
|
||||
- [Fonctionnalités](#fonctionnalites)
|
||||
- [Prérequis](#prerequis)
|
||||
- [Installation rapide](#installation-rapide)
|
||||
- [Configuration détaillée](#configuration-detaillee)
|
||||
- [Variables d'environnement](#variables-denvironnement)
|
||||
- [🔒 Authentification](#authentification)
|
||||
- [Ajouter une nouvelle vault](#ajouter-une-nouvelle-vault)
|
||||
- [Build & déploiement avec build.sh](#build-deploiement-avec-buildsh)
|
||||
- [Rendu d'images Obsidian](#rendu-dimages-obsidian)
|
||||
- [Desktop (Tauri) — Application native](#desktop-tauri-application-native)
|
||||
- [Utilisation](#utilisation)
|
||||
- [API](#api)
|
||||
- [Recherche avancée](#recherche-avancee)
|
||||
- [Dépannage](#depannage)
|
||||
- [Performance](#performance)
|
||||
- [Sécurité](#securite)
|
||||
- [Stack technique](#stack-technique)
|
||||
- [Architecture](#architecture)
|
||||
- [Développement](#developpement)
|
||||
- [Licence](#licence)
|
||||
- [Changelog](#changelog)
|
||||
- ✨ [Fonctionnalités](#fonctionnalites)
|
||||
- 📚 [Guides](#guides)
|
||||
- 🚀 [Prérequis](#prerequis)
|
||||
- ⚡ [Installation rapide](#installation-rapide)
|
||||
- ⚙️ [Configuration détaillée](#configuration-detaillee)
|
||||
- 🌍 [Variables d'environnement](#variables-denvironnement)
|
||||
- 🔒 [Authentification](#authentification)
|
||||
- ➕ [Ajouter une nouvelle vault](#ajouter-une-nouvelle-vault)
|
||||
- 🔨 [Build & déploiement avec build.sh](#build-deploiement-avec-buildsh)
|
||||
- 🖼️ [Rendu d'images Obsidian](#rendu-dimages-obsidian)
|
||||
- 🖥️ [Desktop (Tauri) — Application native](#desktop-tauri-application-native)
|
||||
- 📖 [Utilisation](#utilisation)
|
||||
- 👥 [Collaboration temps réel](#collaboration-temps-reel)
|
||||
- 🔌 [API](#api)
|
||||
- 🔍 [Recherche avancée](#recherche-avancee)
|
||||
- 🔧 [Dépannage](#depannage)
|
||||
- ⚡ [Performance](#performance)
|
||||
- 🛡️ [Sécurité](#securite)
|
||||
- 🏗️ [Stack technique](#stack-technique)
|
||||
- 🏠 [Architecture](#architecture)
|
||||
- 📝 [Développement](#developpement)
|
||||
- 📄 [Licence](#licence)
|
||||
- 🤝 [Support](#support)
|
||||
- 📝 [Changelog](#changelog)
|
||||
|
||||
---
|
||||
|
||||
## ✨ Fonctionnalités
|
||||
|
||||
- **🤖 AI Editor intégré** — Éditeur CodeMirror 6 avec toolbar IA : amélioration, correction, traduction, génération, réécriture personnalisée, toolbox (liste, tableau, frontmatter, canvas) — multi-provider DeepSeek/OpenRouter/Gemini
|
||||
- **🧩 Serveur MCP & agent IA** — Serveur Model Context Protocol intégré (`/mcp`) et assistant avec function calling : lisez, cherchez et modifiez vos vaults depuis Claude Desktop, Cursor… avec confirmations two-step, permissions par vault, rate limiting et redaction des secrets ([guide](docs/MCP_GUIDE.md))
|
||||
- **🧩 Serveur MCP & agent IA** — Serveur Model Context Protocol intégré (`/mcp`) et assistant avec function calling : lisez, cherchez et modifiez vos vaults depuis Claude Desktop, Cursor… avec confirmations two-step, permissions par vault, rate limiting et redaction des secrets ([guide](docs/GUIDES/MCP.md))
|
||||
- **👥 Collaboration temps réel** — Édition simultanée d'un même document (Yjs/CRDT) : curseurs distants colorés, indicateur de présence, fusion sans conflit, reconnexion automatique et persistance serveur ([détail](docs/features/collaboration.md))
|
||||
- **📖 Guide d'utilisation intégré** — Aide complète en FR/EN accessible depuis le menu Options : interface, navigation, recherche, fichiers, IA, sécurité, API & intégrations (OpenAPI, MCP), hors-ligne, collaboration, desktop, plus une section **Architecture** avec diagramme Mermaid ; téléchargeable en **Markdown** et **PDF** dans la langue courante ([détail](docs/features/guide-coverage-105.md))
|
||||
- **📱 Éditeur mobile natif** — Édition optimisée pour le tactile : barre d'outils Markdown flottante (gras/italique/code/liste/lien), bouton « Coller » persistant (contournement iOS), zoom par pincement et hauteur ajustable, raccourcis swipe (liens entrants / table des matières) et mode lecture plein écran avec navigation entre fichiers ([détail](docs/features/mobile-editor.md))
|
||||
@@ -412,6 +426,8 @@ curl -X POST http://localhost:2020/api/attachments/rescan/MonVault
|
||||
|
||||
## 🖥️ Desktop (Tauri) — Application native
|
||||
|
||||
> 📖 Guide complet : [Desktop (Tauri)](docs/GUIDES/DESKTOP.md)
|
||||
|
||||
ObsiGate Desktop est une application native construite avec [Tauri](https://tauri.app/) (Rust + webview système). Elle embarque le backend Python et le frontend dans un exécutable standalone — zéro Docker, zéro ligne de commande.
|
||||
|
||||
> 🚧 **Version 2.0.0 — binaires en cours de stabilisation.** Pour l'instant, le build depuis les sources est recommandé.
|
||||
@@ -571,6 +587,8 @@ Cycle de vie : Tauri spawn le backend Python → health check → splash de dém
|
||||
|
||||
## 👥 Collaboration temps réel
|
||||
|
||||
> 📖 Guide complet : [Édition & collaboration](docs/GUIDES/COLLABORATION.md)
|
||||
|
||||
Plusieurs utilisateurs peuvent éditer le même document markdown simultanément (façon Google Docs) :
|
||||
|
||||
- **Fusion sans conflit** grâce à Yjs (CRDT) : deux personnes peuvent taper au même endroit, aucune
|
||||
@@ -590,6 +608,8 @@ fenêtres) pour voir la collaboration en action.
|
||||
|
||||
## 🔌 API
|
||||
|
||||
> 📖 Guide complet : [API REST](docs/GUIDES/API_REST.md) · [Serveur MCP](docs/GUIDES/MCP.md)
|
||||
|
||||
ObsiGate expose une API REST complète :
|
||||
|
||||
| Endpoint | Description | Méthode | Auth |
|
||||
@@ -637,6 +657,8 @@ curl "http://localhost:2020/api/file/Recettes?path=pizza.md"
|
||||
|
||||
## 🔍 Recherche avancée
|
||||
|
||||
> 📖 Guide complet : [Recherche, PDF & Excalidraw](docs/GUIDES/RECHERCHE_PDF_EXCALIDRAW.md)
|
||||
|
||||
### Syntaxe de requête
|
||||
|
||||
| Opérateur | Description | Exemple |
|
||||
@@ -758,6 +780,8 @@ Configurables via l'interface (Settings) ou l'API `/api/config`.
|
||||
|
||||
## 🛡️ Sécurité
|
||||
|
||||
> 📖 Guide complet : [Authentification & sécurité](docs/GUIDES/AUTHENTIFICATION_SECURITE.md)
|
||||
|
||||
- **Path traversal** : tous les endpoints fichier valident que le chemin résolu reste dans la vault
|
||||
- **Rate limiting** : 10 tentatives de login max par IP sur 15 minutes + lockout par compte (5 tentatives)
|
||||
- **Audit log** : écritures/suppressions/config journalisées dans `data/audit.log` (JSON lines, rotation 10 MB)
|
||||
@@ -927,8 +951,8 @@ Ce projet est sous licence **MIT** — voir le fichier [LICENSE](LICENSE) pour l
|
||||
|
||||
## 📝 Changelog
|
||||
|
||||
Consultez le [CHANGELOG.md](./CHANGELOG.md) pour l'historique complet de toutes les versions (v1.0.0 → v2.16.5).
|
||||
Consultez le [CHANGELOG.md](./CHANGELOG.md) pour l'historique complet de toutes les versions (v1.0.0 → v2.16.6).
|
||||
|
||||
---
|
||||
|
||||
*Projet : ObsiGate | Version : 2.16.5 | Dernière mise à jour : Juin 2026*
|
||||
*Projet : ObsiGate | Version : 2.16.6 | Dernière mise à jour : Septembre 2026*
|
||||
|
||||
@@ -2,53 +2,73 @@
|
||||
|
||||
**Ultra-light web gateway for your Obsidian vaults** — Access, browse, and search all your Obsidian notes from any device via a modern, responsive web interface.
|
||||
|
||||
[]()
|
||||
[]()
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://www.docker.com/)
|
||||
[](https://www.python.org/)
|
||||
[](https://git.dracodev.net/Projets/ObsiGate/actions)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ [🔍 Search...] [☀/🌙 Theme] ObsiGate │
|
||||
├──────────────┬──────────────────────────────────────────┤
|
||||
│ SIDEBAR │ CONTENT AREA │
|
||||
│ ▼ Recipes │ 📄 File Title │
|
||||
│ 📁 Soups │ Tags: #recipe #quick │
|
||||
│ 📄 Pizza │ [Rendered Markdown Content] │
|
||||
│ ▼ IT │ │
|
||||
│ 📁 Docker │ │
|
||||
│ Tags Cloud │ │
|
||||
└──────────────┴──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
|
||||
> ObsiGate web interface: multi-vault sidebar, global search, dashboard stats and shortcuts.
|
||||
|
||||
---
|
||||
|
||||
## 📚 Guides
|
||||
|
||||
Step-by-step **user guides** live in [`docs/GUIDES/`](docs/GUIDES/):
|
||||
|
||||
| Guide | What it covers |
|
||||
|---|---|
|
||||
| 🚀 [Getting Started](docs/GUIDES/PRISE_EN_MAIN.md) | First run, interface, navigation, vaults, shortcuts |
|
||||
| 🔍 [Search, PDF & Excalidraw](docs/GUIDES/RECHERCHE_PDF_EXCALIDRAW.md) | Query syntax, semantic search, PDF viewer, diagrams |
|
||||
| 🤖 [AI Assistant & Forge](docs/GUIDES/ASSISTANT_IA_FORGE.md) | Providers, AI editor, BooksLM, Forge, `@` / `/` commands |
|
||||
| 📝 [Editing & Collaboration](docs/GUIDES/COLLABORATION.md) | Simultaneous editing, remote cursors, persistence |
|
||||
| 📱 [PWA & Offline](docs/GUIDES/PWA_HORS_LIGNE.md) | Install as an app, offline cache, sync queue, push |
|
||||
| 🔌 [REST API](docs/GUIDES/API_REST.md) | Authentication, API keys, endpoints, `curl` examples, SSE |
|
||||
| 🧩 [MCP Server](docs/GUIDES/MCP.md) | Connect Claude Desktop, Cursor, Cline… to your vaults |
|
||||
| 🔒 [Auth & Security](docs/GUIDES/AUTHENTIFICATION_SECURITE.md) | Users, MFA, per-vault permissions, hardening |
|
||||
| 🐳 [Docker Deployment](docs/GUIDES/DEPLOIEMENT_DOCKER.md) | `docker-compose`, volumes, reverse proxy, updates |
|
||||
| 🖥️ [Desktop (Tauri)](docs/GUIDES/DESKTOP.md) | Install, first run, build from source, troubleshooting |
|
||||
|
||||
> All guides are currently written in **French**. See the full index:
|
||||
> [`docs/GUIDES/README.md`](docs/GUIDES/README.md).
|
||||
|
||||
---
|
||||
|
||||
## 📋 Table of Contents
|
||||
|
||||
- [Features](#features)
|
||||
- [Architecture](#architecture)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Quick Installation](#quick-installation)
|
||||
- [Detailed Configuration](#detailed-configuration)
|
||||
- [Environment Variables](#environment-variables)
|
||||
- [🔒 Authentication](#authentication)
|
||||
- [Adding a New Vault](#adding-a-new-vault)
|
||||
- [Build & Deployment with build.sh](#build--deployment-with-buildsh)
|
||||
- [Desktop (Tauri) — Native Application](#desktop-tauri--native-application)
|
||||
- [Usage](#usage)
|
||||
- [API](#api)
|
||||
- [Performance](#performance)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Tech Stack](#tech-stack)
|
||||
- [Changelog](#changelog)
|
||||
- ✨ [Features](#features)
|
||||
- 📚 [Guides](#guides)
|
||||
- 🚀 [Prerequisites](#prerequisites)
|
||||
- ⚡ [Quick Installation](#quick-installation)
|
||||
- ⚙️ [Detailed Configuration](#detailed-configuration)
|
||||
- 🌍 [Environment Variables](#environment-variables)
|
||||
- 🔒 [Authentication](#authentication)
|
||||
- ➕ [Adding a New Vault](#adding-a-new-vault)
|
||||
- 🔨 [Build & Deployment with build.sh](#build--deployment-with-buildsh)
|
||||
- 🖼️ [Obsidian Image Rendering](#obsidian-image-rendering)
|
||||
- 🖥️ [Desktop (Tauri) — Native Application](#desktop-tauri--native-application)
|
||||
- 📖 [Usage](#usage)
|
||||
- 👥 [Real-time Collaboration](#real-time-collaboration)
|
||||
- 🔌 [API](#api)
|
||||
- 🔍 [Advanced Search](#advanced-search)
|
||||
- 🛡️ [Security](#security)
|
||||
- ⚡ [Performance](#performance)
|
||||
- 🔧 [Troubleshooting](#troubleshooting)
|
||||
- 🏗️ [Tech Stack](#tech-stack)
|
||||
- 🏠 [Architecture](#architecture)
|
||||
- 📝 [Development](#development)
|
||||
- 📄 [License](#license)
|
||||
- 🤝 [Support](#support)
|
||||
- 📝 [Changelog](#changelog)
|
||||
|
||||
---
|
||||
|
||||
## ✨ Features
|
||||
|
||||
- **🤖 Integrated AI Editor** — CodeMirror 6 editor with AI toolbar: improve, correct, translate, generate, custom rewrite, toolbox (list, table, frontmatter, canvas) — multi-provider DeepSeek/OpenRouter/Gemini
|
||||
- **🧩 MCP Server & AI Agent** — Built-in Model Context Protocol server (`/mcp`) and tool-calling assistant: read, search and edit your vaults from Claude Desktop, Cursor… with two-step confirmations, per-vault permissions, rate limiting and secret redaction ([guide](docs/MCP_GUIDE.md))
|
||||
- **🧩 MCP Server & AI Agent** — Built-in Model Context Protocol server (`/mcp`) and tool-calling assistant: read, search and edit your vaults from Claude Desktop, Cursor… with two-step confirmations, per-vault permissions, rate limiting and secret redaction ([guide](docs/GUIDES/MCP.md))
|
||||
- **👥 Real-time Collaboration** — Simultaneous editing of the same document (Yjs/CRDT): colored remote cursors, presence indicator, conflict-free merge, automatic reconnection and server-side persistence ([details](docs/features/collaboration.md))
|
||||
- **📖 Built-in User Guide** — Complete FR/EN help from the Options menu: interface, navigation, search, files, AI, security, API & integrations (OpenAPI, MCP), offline, collaboration, desktop, plus an **Architecture** section with a Mermaid diagram; downloadable as **Markdown** and **PDF** in the current language ([details](docs/features/guide-coverage-105.md))
|
||||
- **📱 Native Mobile Editor** — Touch-optimised editing: floating Markdown toolbar (bold/italic/code/list/link), persistent Paste button (iOS workaround), pinch-zoom font & adjustable height, swipe shortcuts (backlinks / table of contents) and a full-screen reading mode with page navigation ([details](docs/features/mobile-editor.md))
|
||||
@@ -520,6 +540,8 @@ curl -X POST http://localhost:2020/api/attachments/rescan/MyVault
|
||||
|
||||
## 🖥️ Desktop (Tauri) — Native Application
|
||||
|
||||
> 📖 Full guide: [Desktop (Tauri)](docs/GUIDES/DESKTOP.md)
|
||||
|
||||
ObsiGate Desktop is a native application built with [Tauri](https://tauri.app/) (Rust + system webview). It embeds the Python backend and frontend in a standalone executable — zero Docker, zero command line.
|
||||
|
||||
> 🚧 **Version 2.0.0 — binaries are being stabilized.** For now, building from source is recommended.
|
||||
@@ -687,6 +709,8 @@ Lifecycle: Tauri spawns the Python backend → health check → opens the webvie
|
||||
|
||||
## 👥 Real-time Collaboration
|
||||
|
||||
> 📖 Full guide: [Editing & Collaboration](docs/GUIDES/COLLABORATION.md)
|
||||
|
||||
Multiple users can edit the same markdown document simultaneously (Google Docs style):
|
||||
|
||||
- **Conflict-free merge** via Yjs (CRDT): two people can type in the same place, no change is lost.
|
||||
@@ -703,6 +727,8 @@ No configuration is required: open the same file in two browsers (or two windows
|
||||
|
||||
## 🔌 API
|
||||
|
||||
> 📖 Full guide: [REST API](docs/GUIDES/API_REST.md) · [MCP Server](docs/GUIDES/MCP.md)
|
||||
|
||||
ObsiGate exposes a complete REST API :
|
||||
|
||||
| Endpoint | Description | Method | Auth |
|
||||
@@ -763,6 +789,8 @@ curl "http://localhost:2020/api/file/Recipes?path=pizza.md"
|
||||
|
||||
## 🔍 Advanced Search
|
||||
|
||||
> 📖 Full guide: [Search, PDF & Excalidraw](docs/GUIDES/RECHERCHE_PDF_EXCALIDRAW.md)
|
||||
|
||||
### Query Syntax
|
||||
|
||||
| Operator | Description | Example |
|
||||
@@ -915,6 +943,8 @@ These parameters are configurable via the interface (Settings) or the `/api/conf
|
||||
|
||||
## 🛡️ Security
|
||||
|
||||
> 📖 Full guide: [Auth & Security](docs/GUIDES/AUTHENTIFICATION_SECURITE.md)
|
||||
|
||||
- **Path traversal** : All file endpoints validate that the resolved path stays within the vault
|
||||
- **Rate limiting** : 10 login attempts max per IP over 15 minutes + per-account lockout (5 attempts)
|
||||
- **Audit log** : All writes, deletions, and config changes are logged in `data/audit.log` (JSON lines, 10 MB rotation)
|
||||
@@ -1070,7 +1100,9 @@ ObsiGate/
|
||||
├── Dockerfile # Multi-stage, healthcheck, non-root
|
||||
├── docker-compose.yml # Deployment with healthcheck and auth env vars
|
||||
├── build.sh # Automated build & deployment (docker compose build + up)
|
||||
└── docs/CONTRIBUTING.md # Contribution guide
|
||||
└── docs/
|
||||
├── GUIDES/ # User guides (getting started, API, MCP, desktop…)
|
||||
└── CONTRIBUTING.md # Contribution guide
|
||||
```
|
||||
|
||||
### Contributing
|
||||
@@ -1096,8 +1128,8 @@ This project is licensed under the **MIT License** - see the [LICENSE](LICENSE)
|
||||
|
||||
## 📝 Changelog
|
||||
|
||||
See [CHANGELOG.md](./CHANGELOG.md) for the complete version history (v1.0.0 → v2.16.5).
|
||||
See [CHANGELOG.md](./CHANGELOG.md) for the complete version history (v1.0.0 → v2.16.6).
|
||||
|
||||
---
|
||||
|
||||
*Project: ObsiGate | Version: 2.16.5 | Last updated: May 2026*
|
||||
*Project: ObsiGate | Version: 2.16.6 | Last updated: September 2026*
|
||||
|
||||
Generated
+1
-1
@@ -2626,7 +2626,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "obsigate-desktop"
|
||||
version = "2.16.5"
|
||||
version = "2.16.6"
|
||||
dependencies = [
|
||||
"chrono",
|
||||
"env_logger",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "obsigate-desktop"
|
||||
version = "2.16.5"
|
||||
version = "2.16.6"
|
||||
description = "ObsiGate Desktop — Porte d'entrée native pour vos vaults Obsidian"
|
||||
authors = ["Bruno Charest"]
|
||||
edition = "2021"
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/nicedoc/obsigate/main/desktop/tauri.conf.schema.json",
|
||||
"productName": "ObsiGate",
|
||||
"version": "2.16.5",
|
||||
"version": "2.16.6",
|
||||
"identifier": "com.obsigate.desktop",
|
||||
"build": {
|
||||
"frontendDist": "../frontend",
|
||||
|
||||
@@ -347,7 +347,7 @@ Pour répondre au besoin de cibler un fournisseur/modèle sans dépendre uniquem
|
||||
| **0 — Fondations** | `backend/tools/` (registry, context, service, audit) + extraction des services métier + tests unitaires | Couche d'outils testable sans IA |
|
||||
| **1 — Function calling in-app** | Abstraction tool-calling multi-provider, agent loop, confirmations UI, SSE réel, outils de navigation | Assistant qui lit/cherche/lit/ouvre/modifie avec confirmation |
|
||||
| **2 — Serveur MCP** | `backend/mcp/server.py` (tools + resources + prompts), **Streamable HTTP** (`/mcp`, auth JWT), confirmation two-step | ObsiGate accessible comme serveur MCP (local + distant, multi-utilisateur) |
|
||||
| **3 — Durcissement** ✅ | Rate limiting (`backend/tools/ratelimit.py`), quotas `BOOKSLM_MAX_*`, redaction systématique des résultats (`backend/tools/redaction.py`), doc OpenAPI (tag/path MCP) + [guide MCP](./MCP_GUIDE.md), tests E2E | Observabilité et sécurité complètes |
|
||||
| **3 — Durcissement** ✅ | Rate limiting (`backend/tools/ratelimit.py`), quotas `BOOKSLM_MAX_*`, redaction systématique des résultats (`backend/tools/redaction.py`), doc OpenAPI (tag/path MCP) + [guide MCP](./GUIDES/MCP.md), tests E2E | Observabilité et sécurité complètes |
|
||||
|
||||
Voir `docs/ROADMAP.md` (item dédié) pour le détail des activités.
|
||||
|
||||
@@ -380,7 +380,7 @@ Voir `docs/ROADMAP.md` (item dédié) pour le détail des activités.
|
||||
- `backend/mcp/confirmations.py` — jetons de confirmation signés (two-step, anti-rejeu)
|
||||
- `backend/tools/ratelimit.py` — rate limiting par jeton/outil (phase F)
|
||||
- `backend/tools/redaction.py` — redaction récursive des résultats d'outils (phase F)
|
||||
- `docs/MCP_GUIDE.md` — guide d'installation et d'utilisation des clients MCP
|
||||
- `docs/GUIDES/MCP.md` — guide d'installation et d'utilisation des clients MCP
|
||||
- `backend/bookslm.py`, `backend/bookslm_routes.py` — assistant contextuel (+ endpoint `/agent`)
|
||||
- `frontend/js/ai.js`, `frontend/js/bookslm.js` — UI IA
|
||||
- `backend/auth/middleware.py` — permissions
|
||||
|
||||
@@ -0,0 +1,326 @@
|
||||
# 🔌 Guide de l'API REST
|
||||
|
||||
ObsiGate expose une **API REST complète** couvrant toute l'application :
|
||||
vaults, fichiers, recherche, sauvegardes, exports, IA, partage, webhooks et
|
||||
administration. Ce guide explique l'authentification, la création de clés et
|
||||
donne des exemples prêts à l'emploi.
|
||||
|
||||
> **Public :** développeurs, intégrateurs, scripts d'automatisation
|
||||
> **Doc interactive :** `/docs` (Swagger UI) · `/redoc` (ReDoc) · `/openapi.json`
|
||||
> **Voir aussi :** [Serveur MCP](./MCP.md) · [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. Base et conventions
|
||||
|
||||
| Élément | Valeur |
|
||||
|---|---|
|
||||
| URL de base | `http://<hôte>:2020` (Docker) ou `http://127.0.0.1:17890` (desktop) |
|
||||
| Préfixe API | `/api` |
|
||||
| Format | JSON (`application/json`) |
|
||||
| Version | suit la version d'ObsiGate (header `X-…`, `/api/health`) |
|
||||
| Erreurs | `{"detail": "..."}` + code HTTP (`400`, `401`, `403`, `404`, `409`, `422`, `500`) |
|
||||
|
||||
Quand l'authentification est **désactivée** (`OBSIGATE_AUTH_ENABLED=false`), tous
|
||||
les endpoints sont accessibles sans jeton (utilisateur anonyme avec accès à tous
|
||||
les vaults).
|
||||
|
||||
---
|
||||
|
||||
## 2. Authentification
|
||||
|
||||
### 2.1 Jeton de session (JWT)
|
||||
|
||||
Obtenu via `POST /api/auth/login`. Le jeton d'accès a une durée de vie courte
|
||||
(`OBSIGATE_ACCESS_TOKEN_TTL`, défaut 3600 s) et un refresh token longue durée est
|
||||
posé en cookie HTTP-only.
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://localhost:2020/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"votre_mot_de_passe"}'
|
||||
```
|
||||
|
||||
Réponse (extrait) :
|
||||
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJ...",
|
||||
"token_type": "bearer",
|
||||
"expires_in": 3600,
|
||||
"user": { "username": "admin", "role": "admin", "vaults": ["*"] }
|
||||
}
|
||||
```
|
||||
|
||||
Deux façons de présenter le jeton :
|
||||
|
||||
```http
|
||||
Authorization: Bearer <access_token>
|
||||
```
|
||||
|
||||
ou, pour un client navigateur, le cookie HTTP-only avec
|
||||
`credentials: "include"` (le login pose aussi un cookie `access_token`).
|
||||
|
||||
### 2.2 Clés API longue durée (recommandé pour scripts & MCP)
|
||||
|
||||
Une **seule clé** authentifie **l'API REST et le serveur MCP**. Créez-la depuis
|
||||
l'interface (Configurations → **🔑 Clés API & MCP**) ou par API :
|
||||
|
||||
```bash
|
||||
# 1. Se connecter, récupérer le token (section 2.1)
|
||||
# 2. Créer une clé valable 30 jours
|
||||
curl -s -X POST http://localhost:2020/api/auth/tokens \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"Script backup","expiry":"30d"}'
|
||||
```
|
||||
|
||||
Réponse (`token` affiché **une seule fois**) :
|
||||
|
||||
```json
|
||||
{
|
||||
"token": "eyJ...",
|
||||
"jti": "…",
|
||||
"name": "Script backup",
|
||||
"created_at": 1790000000,
|
||||
"expires_at": 1792592000,
|
||||
"expiry_key": "30d"
|
||||
}
|
||||
```
|
||||
|
||||
| `expiry` | Durée |
|
||||
|---|---|
|
||||
| `1d` | 1 jour |
|
||||
| `30d` | 1 mois |
|
||||
| `180d` | 6 mois |
|
||||
| `365d` | 1 an |
|
||||
| `never` | sans expiration |
|
||||
|
||||
Gestion :
|
||||
|
||||
| Endpoint | Rôle |
|
||||
|---|---|
|
||||
| `GET /api/auth/tokens` | Lister vos clés (`last_used_at`, statut) |
|
||||
| `POST /api/auth/tokens` | Créer (`{name, expiry}`) |
|
||||
| `DELETE /api/auth/tokens/{jti}` | Révoquer immédiatement (API **et** MCP) |
|
||||
|
||||
> Le JWT brut n'est **jamais persisté** : copiez-le à la création. Plafond :
|
||||
> 50 clés actives par utilisateur.
|
||||
|
||||
---
|
||||
|
||||
## 3. Référence des endpoints
|
||||
|
||||
> Liste non exhaustive — la référence faisant foi est `/openapi.json`. Les
|
||||
> colonnes **Auth** indiquent le niveau requis (`—`, `Oui`, `Admin`).
|
||||
|
||||
### 3.1 Système
|
||||
|
||||
| Endpoint | Description | Méthode | Auth |
|
||||
|---|---|---|---|
|
||||
| `/api/health` | Santé (statut, version, stats) | GET | — |
|
||||
| `/api/health/detailed` | Santé détaillée | GET | — |
|
||||
| `/api/config` | Lire / écrire la configuration | GET/POST | Oui/Admin |
|
||||
| `/api/diagnostics` | Statistiques index & mémoire | GET | Admin |
|
||||
| `/api/dashboard` | Statistiques du tableau de bord | GET | Oui |
|
||||
| `/api/events` | Flux SSE temps réel | GET | Oui |
|
||||
|
||||
### 3.2 Vaults
|
||||
|
||||
| Endpoint | Description | Méthode | Auth |
|
||||
|---|---|---|---|
|
||||
| `/api/vaults` | Liste (filtrée par permissions) | GET | Oui |
|
||||
| `/api/vaults/status` | Statut de toutes les vaults | GET | Oui |
|
||||
| `/api/vaults/add` | Ajouter une vault (volume déjà monté) | POST | Admin |
|
||||
| `/api/vaults/{name}` | Supprimer une vault | DELETE | Admin |
|
||||
| `/api/index/reload` | Réindexation complète | GET | Admin |
|
||||
| `/api/index/reload/{vault}` | Réindexer une vault | GET | Oui |
|
||||
| `/api/vaults/{vault}/settings` | Lire / écrire les réglages | GET/POST | Oui |
|
||||
| `/api/attachments/rescan/{vault}` | Rescanner les attachements | POST | Oui |
|
||||
|
||||
### 3.3 Fichiers
|
||||
|
||||
| Endpoint | Description | Méthode | Auth |
|
||||
|---|---|---|---|
|
||||
| `/api/browse/{vault}?path=` | Naviguer dans les dossiers | GET | Oui |
|
||||
| `/api/file/{vault}?path=` | Contenu rendu (Markdown) | GET | Oui |
|
||||
| `/api/file/{vault}/raw?path=` | Contenu brut | GET | Oui |
|
||||
| `/api/file/{vault}/download?path=` | Télécharger | GET | Oui |
|
||||
| `/api/file/{vault}/save?path=` | Enregistrer | PUT | Oui |
|
||||
| `/api/file/{vault}` | Créer | POST | Oui |
|
||||
| `/api/file/{vault}` | Renommer | PATCH | Oui |
|
||||
| `/api/file/{vault}` | Supprimer | DELETE | Oui |
|
||||
| `/api/directory/{vault}` | Créer / renommer / supprimer un dossier | POST/PATCH/DELETE | Oui |
|
||||
| `/api/move/{vault}` | Déplacer un fichier/dossier | POST | Oui |
|
||||
| `/api/vault/{vault}/batch-upload` | Upload multiple (multipart) | POST | Oui |
|
||||
| `/api/image/{vault}?path=` | Servir une image | GET | Oui |
|
||||
|
||||
### 3.4 Recherche & graphe
|
||||
|
||||
| Endpoint | Description | Méthode | Auth |
|
||||
|---|---|---|---|
|
||||
| `/api/search` | Recherche simple (legacy) | GET | Oui |
|
||||
| `/api/search/advanced` | Recherche TF-IDF avancée (facettes, tri, pagination, `semantic=`) | GET | Oui |
|
||||
| `/api/search/replace` | Recherche/remplacement multi-fichiers | POST | Oui |
|
||||
| `/api/tags?vault=` | Tags uniques avec compteurs | GET | Oui |
|
||||
| `/api/suggest?q=` | Autocomplétion de titres | GET | Oui |
|
||||
| `/api/tags/suggest?q=` | Autocomplétion de tags | GET | Oui |
|
||||
| `/api/tree-search` | Recherche de fichiers/dossiers | GET | Oui |
|
||||
| `/api/vault/{vault}/paths` | Liste de chemins | GET | Oui |
|
||||
| `/api/graph/{vault}` | Graphe de liens | GET | Oui |
|
||||
|
||||
### 3.5 Sauvegardes
|
||||
|
||||
| Endpoint | Description | Méthode | Auth |
|
||||
|---|---|---|---|
|
||||
| `/api/file/{vault}/backups` | Backups d'un fichier | GET | Oui |
|
||||
| `/api/file/{vault}/diff` | Diff avec une version | GET | Oui |
|
||||
| `/api/file/{vault}/restore` | Restaurer une version | POST | Oui |
|
||||
| `/api/backups` | Lister les backups | GET | Oui |
|
||||
| `/api/backups/content` | Contenu d'un backup | GET | Oui |
|
||||
| `/api/backups/delete` / `/purge` / `/compress` / `/auto` | Gestion & purge | POST | Oui |
|
||||
|
||||
### 3.6 Exports
|
||||
|
||||
| Endpoint | Description | Méthode |
|
||||
|---|---|---|
|
||||
| `/api/export/html` | Exporter en HTML | GET |
|
||||
| `/api/export/md-bundle` | Exporter en bundle Markdown (ZIP) | GET |
|
||||
| `/api/export/epub` | Exporter en ePub | GET |
|
||||
| `/api/guide/download?format=md\|pdf&lang=fr\|en` | Télécharger le guide intégré | GET |
|
||||
|
||||
### 3.7 PDF
|
||||
|
||||
| Endpoint | Description | Méthode |
|
||||
|---|---|---|
|
||||
| `/api/file/{vault}/pdf/info` | Métadonnées sans transfert | GET |
|
||||
| `/api/file/{vault}/pdf/stream` | Streaming (HTTP Range, 206) | GET |
|
||||
|
||||
### 3.8 IA
|
||||
|
||||
| Endpoint | Description | Méthode |
|
||||
|---|---|---|
|
||||
| `/api/ai/status` | Statut des fournisseurs | GET |
|
||||
| `/api/ai/improve`, `/fix-spelling`, `/summarize`, `/translate`, `/rewrite`, `/to-list`, `/to-table`, `/frontmatter`, `/inline-complete`, `/to-canvas`… | Actions éditeur IA | POST |
|
||||
| `/api/ai/model-capabilities?provider=&model=` | Capacités d'un modèle | GET |
|
||||
| `/api/ai/bookslm/*` | Console IA par répertoire | POST/GET |
|
||||
| `/api/ai/skills` | Lister / créer / supprimer des skills | GET/POST/DELETE |
|
||||
| `/api/config/ai-keys` · `/api/config/tool-keys` | Clés fournisseurs & sources | GET/POST/DELETE |
|
||||
|
||||
### 3.9 Authentification & administration
|
||||
|
||||
| Endpoint | Description | Méthode | Auth |
|
||||
|---|---|---|---|
|
||||
| `/api/auth/status` | Statut de l'auth | GET | — |
|
||||
| `/api/auth/login` · `/refresh` · `/logout` | Cycle de session | POST | — / Cookie / Oui |
|
||||
| `/api/auth/me` | Profil courant | GET/PATCH | Oui |
|
||||
| `/api/auth/change-password` | Changer le mot de passe | POST | Oui |
|
||||
| `/api/auth/mfa/*` | TOTP, WebAuthn, recovery | POST/GET | Oui |
|
||||
| `/api/auth/tokens` | Clés API (voir §2.2) | GET/POST/DELETE | Oui |
|
||||
| `/api/auth/admin/users` | Lister / créer des utilisateurs | GET/POST | Admin |
|
||||
| `/api/auth/admin/users/{u}` | Modifier / supprimer | PATCH/DELETE | Admin |
|
||||
| `/api/admin/stats` · `/audit` · `/backup-stats` · `/stream` | Monitoring admin | GET | Admin |
|
||||
|
||||
### 3.10 Partage, webhooks, conflits, plugins, push
|
||||
|
||||
| Endpoint | Description | Méthode |
|
||||
|---|---|---|
|
||||
| `/api/share/{vault}` | Créer un lien de partage public | POST |
|
||||
| `/api/shares` | Lister / supprimer les partages | GET/DELETE |
|
||||
| `/api/webhooks` | CRUD webhooks (HMAC-SHA256) | GET/POST/PATCH/DELETE |
|
||||
| `/api/conflicts` · `/api/conflicts/resolve` | Conflits Syncthing | GET/POST |
|
||||
| `/api/plugins` | Installer / activer / désactiver | GET/POST/DELETE |
|
||||
| `/api/push/*` | Abonnement Web Push (VAPID) | GET/POST/DELETE |
|
||||
|
||||
---
|
||||
|
||||
## 4. Exemples `curl`
|
||||
|
||||
```bash
|
||||
BASE=http://localhost:2020
|
||||
TOKEN=$(curl -s -X POST $BASE/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"admin","password":"secret"}' | jq -r .access_token)
|
||||
|
||||
# Santé
|
||||
curl -s $BASE/api/health
|
||||
|
||||
# Lister les vaults
|
||||
curl -s $BASE/api/vaults -H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# Naviguer
|
||||
curl -s "$BASE/api/browse/Recettes?path=" -H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# Lire un fichier (rendu Markdown)
|
||||
curl -s "$BASE/api/file/Recettes?path=pizza.md" -H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# Lire en brut
|
||||
curl -s "$BASE/api/file/Recettes/raw?path=pizza.md" -H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# Sauvegarder
|
||||
curl -s -X PUT "$BASE/api/file/Recettes/save?path=pizza.md" \
|
||||
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
-d '{"content":"# Pizza\n\nNouvelle recette."}'
|
||||
|
||||
# Recherche avancée
|
||||
curl -s "$BASE/api/search/advanced?q=tag:cuisine%20pizza&vault=all&limit=20&offset=0&sort=relevance" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# Autocomplétion
|
||||
curl -s "$BASE/api/suggest?q=piz&vault=all" -H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# Forcer une réindexation
|
||||
curl -s $BASE/api/index/reload -H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
> Le mot de passe peut aussi être fourni par une clé API dans `Authorization`.
|
||||
> Quand l'auth est désactivée, omettez l'en-tête.
|
||||
|
||||
---
|
||||
|
||||
## 5. Temps réel
|
||||
|
||||
### 5.1 SSE — `/api/events`
|
||||
|
||||
Flux d'événements de changement d'index (fichiers créés/supprimés/modifiés), avec
|
||||
reconnexion automatique côté client.
|
||||
|
||||
```bash
|
||||
curl -N "$BASE/api/events"
|
||||
```
|
||||
|
||||
### 5.2 WebSocket — collaboration
|
||||
|
||||
`ws(s)://<hôte>/ws/collab/{vault}/{path}` transporte les mises à jour
|
||||
Yjs/CRDT et la présence (curseurs distants). Authentification par cookie
|
||||
`access_token` ou paramètre `?token=`, avec contrôle d'accès par vault.
|
||||
Voir [Édition & collaboration](./COLLABORATION.md).
|
||||
|
||||
---
|
||||
|
||||
## 6. Limites et bonnes pratiques
|
||||
|
||||
- **Rate limiting** : les endpoints de login et les outils IA sont limités ;
|
||||
respectez `retry_after` en cas de `429`.
|
||||
- **Permissions** : chaque endpoint fichier vérifie l'accès au vault et rejette
|
||||
les chemins hors vault (path traversal).
|
||||
- **Clés API** : préférez-les aux mots de passe pour les scripts ; révoquez-les
|
||||
dès qu'elles ne servent plus.
|
||||
- **Gros volumes** : utilisez la pagination (`limit`/`offset`) et le streaming
|
||||
HTTP Range pour les PDF.
|
||||
- **Exports** : `md-bundle` et `epub` renvoient un fichier binaire — utilisez
|
||||
`-o` avec `curl`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Dépannage
|
||||
|
||||
| Code | Cause probable |
|
||||
|---|---|
|
||||
| `401` | Jeton absent, expiré ou révoqué |
|
||||
| `403` | Compte sans accès à cette vault / réservé admin |
|
||||
| `404` | Vault, fichier ou chemin inexistant |
|
||||
| `409` | Conflit (fichier déjà existant, etc.) |
|
||||
| `422` | Corps de requête invalide (schéma Pydantic) |
|
||||
| `429` | Rate limit dépassé — voir `retry_after` |
|
||||
| `501` | Export PDF indisponible (WeasyPrint/GTK absent) |
|
||||
@@ -0,0 +1,217 @@
|
||||
# 🤖 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… |
|
||||
|
||||
Les mutations suivent un flux **two-step** : `propose_<tool>` renvoie un aperçu
|
||||
et un **jeton signé à usage unique**, puis `apply_<tool>` exécute.
|
||||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
@@ -0,0 +1,229 @@
|
||||
# 🔒 Guide Authentification & sécurité
|
||||
|
||||
ObsiGate embarque un système d'authentification optionnel **JWT + Argon2id**,
|
||||
un contrôle d'accès **par vault**, du MFA (TOTP, WebAuthn, codes de secours) et
|
||||
des mécanismes de durcissement. Ce guide couvre l'activation, la gestion des
|
||||
comptes et les bonnes pratiques.
|
||||
|
||||
> **Public :** administrateurs · **Voir aussi :**
|
||||
> [`features/api-mcp-tokens-107.md`](../features/api-mcp-tokens-107.md) ·
|
||||
> [API REST](./API_REST.md) · [MCP](./MCP.md) · [Déploiement Docker](./DEPLOIEMENT_DOCKER.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. Vue d'ensemble
|
||||
|
||||
- **Désactivée par défaut** (`OBSIGATE_AUTH_ENABLED=false`) — compatible avec
|
||||
toutes les installations existantes.
|
||||
- Quand elle est activée, l'écran de connexion s'affiche et chaque endpoint
|
||||
vérifie l'utilisateur et ses permissions.
|
||||
- Les données d'auth (`users.json`, `secret.key`, `api_tokens.json`) vivent dans
|
||||
`/app/data` — **montez ce dossier en volume** pour les persister.
|
||||
|
||||
---
|
||||
|
||||
## 2. Activer l'authentification
|
||||
|
||||
### 2.1 Fichier `.env`
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
```bash
|
||||
OBSIGATE_AUTH_ENABLED=true
|
||||
OBSIGATE_ADMIN_USER=admin
|
||||
OBSIGATE_ADMIN_PASSWORD=votre_mot_de_passe # vide = auto-généré (voir logs)
|
||||
# OBSIGATE_SECURE_COOKIES=false # true si derrière HTTPS
|
||||
```
|
||||
|
||||
### 2.2 `docker-compose.yml`
|
||||
|
||||
```yaml
|
||||
env_file:
|
||||
- .env
|
||||
```
|
||||
|
||||
> **Ne mettez jamais de mot de passe dans `docker-compose.yml` !** Utilisez
|
||||
> toujours `.env` (non committé).
|
||||
|
||||
### 2.3 Premier démarrage
|
||||
|
||||
Si aucun utilisateur n'existe, ObsiGate crée un compte admin et affiche le mot de
|
||||
passe **une seule fois dans les logs** :
|
||||
|
||||
```bash
|
||||
docker compose logs obsigate | grep -A4 "FIRST"
|
||||
```
|
||||
|
||||
```
|
||||
============================================================
|
||||
FIRST STARTUP — Admin account created automatically
|
||||
Username : admin
|
||||
Password : xK9mQ3pLr7wN2jT5
|
||||
CHANGE THIS PASSWORD on first login!
|
||||
============================================================
|
||||
```
|
||||
|
||||
Changez-le immédiatement (menu profil → *Changer le mot de passe*).
|
||||
|
||||
---
|
||||
|
||||
## 3. Gestion des utilisateurs
|
||||
|
||||
### 3.1 Interface d'administration
|
||||
|
||||
Un compte **admin** voit une icône 🛡️ dans le header. Le panneau permet de :
|
||||
|
||||
- lister tous les utilisateurs ;
|
||||
- créer / modifier / supprimer des comptes ;
|
||||
- assigner les vaults accessibles par utilisateur ;
|
||||
- activer / désactiver des comptes.
|
||||
|
||||
### 3.2 Ligne de commande
|
||||
|
||||
```bash
|
||||
# Créer un utilisateur
|
||||
docker exec obsigate python backend/create_admin.py create alice MotDePasse --role user --vaults Recettes IT
|
||||
|
||||
# Créer un admin avec accès total
|
||||
docker exec obsigate python backend/create_admin.py create bob SecretPass --role admin --vaults "*"
|
||||
|
||||
# Lister
|
||||
docker exec obsigate python backend/create_admin.py list
|
||||
|
||||
# Supprimer
|
||||
docker exec obsigate python backend/create_admin.py delete alice
|
||||
```
|
||||
|
||||
### 3.3 Contrôle d'accès par vault
|
||||
|
||||
| Valeur `vaults` | Accès |
|
||||
|---|---|
|
||||
| `["*"]` | Toutes les vaults (y compris futures) — défaut admin |
|
||||
| `["Recettes", "IT"]` | Uniquement ces vaults |
|
||||
| `[]` | Aucun accès |
|
||||
|
||||
Les permissions sont revérifiées à chaque requête (et à chaque connexion
|
||||
WebSocket de collaboration).
|
||||
|
||||
---
|
||||
|
||||
## 4. MFA (authentification multifacteur)
|
||||
|
||||
ObsiGate propose trois secondes facteurs, configurables par l'utilisateur.
|
||||
|
||||
### 4.1 TOTP (application d'authentification)
|
||||
|
||||
1. Menu profil → **Sécurité** → *Configurer TOTP* (`POST /api/auth/mfa/totp/setup`).
|
||||
2. Scannez le QR code avec Google Authenticator, Authy, etc.
|
||||
3. Validez le code (`POST /api/auth/mfa/totp/enable`).
|
||||
4. Désactivation : `POST /api/auth/mfa/totp/disable` (mot de passe requis).
|
||||
|
||||
### 4.2 Clés de sécurité & biométrie (WebAuthn)
|
||||
|
||||
- Enregistrement : `POST /api/auth/mfa/webauthn/register/options` puis
|
||||
`POST /api/auth/mfa/webauthn/register`.
|
||||
- Connexion : `POST /api/auth/mfa/webauthn/options` puis `/verify`.
|
||||
- Gestion des clés : `GET /api/auth/mfa/webauthn/credentials`,
|
||||
`POST /api/auth/mfa/webauthn/credentials/remove`.
|
||||
|
||||
> Le *relying party* (domaine) est **dérivé de la requête** (hôte exact, port
|
||||
> inclus) ; derrière un reverse proxy, activez `OBSIGATE_TRUST_PROXY=true` pour
|
||||
> que `X-Forwarded-Host/Proto` soient pris en compte.
|
||||
|
||||
### 4.3 Codes de secours
|
||||
|
||||
À l'activation du MFA, des **codes de récupération** sont générés. Utilisez-en un
|
||||
via `POST /api/auth/mfa/recovery` si vous perdez votre second facteur. Conservez-
|
||||
les hors ligne.
|
||||
|
||||
### 4.4 Statut
|
||||
|
||||
`GET /api/auth/mfa/status` indique les facteurs actifs pour le compte courant.
|
||||
|
||||
---
|
||||
|
||||
## 5. Clés API & MCP
|
||||
|
||||
Pour les scripts et les clients externes, créez une **clé API longue durée**
|
||||
(1 j, 1 mois, 6 mois, 1 an, sans fin) depuis Configurations → 🔑 **Clés API &
|
||||
MCP**. Une seule clé authentifie l'API REST **et** le serveur MCP.
|
||||
|
||||
- Le secret n'est **affiché qu'une fois** (pattern GitHub) et n'est jamais persisté.
|
||||
- La révocation est **immédiate** des deux côtés.
|
||||
- Une colonne « dernière utilisation » (throttlée) aide à repérer les clés
|
||||
dormantes.
|
||||
|
||||
Détails : [API REST §2.2](./API_REST.md#22-clés-api-longue-durée-recommandé-pour-scripts--mcp)
|
||||
et [`features/api-mcp-tokens-107.md`](../features/api-mcp-tokens-107.md).
|
||||
|
||||
---
|
||||
|
||||
## 6. Mécanismes de durcissement
|
||||
|
||||
| Mécanisme | Détail |
|
||||
|---|---|
|
||||
| **Path traversal** | Chaque endpoint fichier valide que le chemin résolu reste dans la vault |
|
||||
| **Rate limiting** | 10 tentatives de login max par IP / 15 min + lockout par compte |
|
||||
| **Rate limiting MFA** | Appliqué aux endpoints TOTP/WebAuthn/recovery |
|
||||
| **Audit log** | Écritures, suppressions, config dans `data/audit.log` (JSON lines, rotation 10 Mo) |
|
||||
| **Backup automatique** | Avant chaque modification/suppression dans `.obsigate-backup/` |
|
||||
| **Redaction** | Masquage des JWT, clés API, tokens dans les aperçus et retours d'outils |
|
||||
| **CSP** | `object-src`, `base-uri`, `form-action`, `frame-ancestors` restreints |
|
||||
| **Cookie HttpOnly** | Jeton retiré de `sessionStorage`, porté par cookie HTTP-only |
|
||||
| **Utilisateur non-root** | Conteneur sous `obsigate` (UID 1000) |
|
||||
| **Volumes read-only** | Vaults montées `:ro` par défaut |
|
||||
| **Atomic writes** | `users.json`, `shares.json`, `webhooks.json` écrits en tmp+replace |
|
||||
| **Symlinks ignorés** | L'index n'indexe pas les liens symboliques |
|
||||
|
||||
### Politique de mot de passe
|
||||
|
||||
Une politique minimale est validée à la création d'un compte. Choisissez des mots
|
||||
de passe longs et uniques ; activez le MFA pour les comptes admin.
|
||||
|
||||
---
|
||||
|
||||
## 7. Variables d'environnement
|
||||
|
||||
| Variable | Description | Défaut |
|
||||
|---|---|---|
|
||||
| `OBSIGATE_AUTH_ENABLED` | Activer l'authentification | `false` |
|
||||
| `OBSIGATE_ADMIN_USER` | Nom de l'admin auto-créé | `admin` |
|
||||
| `OBSIGATE_ADMIN_PASSWORD` | Mot de passe admin (vide = auto-généré) | *(auto)* |
|
||||
| `OBSIGATE_SECURE_COOKIES` | Cookie `Secure` (HTTPS uniquement) | `false` |
|
||||
| `OBSIGATE_ACCESS_TOKEN_TTL` | Durée de vie du token d'accès (s) | `3600` |
|
||||
| `OBSIGATE_REFRESH_TOKEN_TTL` | Durée de vie du refresh token (s) | `2592000` |
|
||||
| `OBSIGATE_LOGIN_MAX_ATTEMPTS` | Tentatives de login max par IP | `10` |
|
||||
| `OBSIGATE_ACCOUNT_MAX_ATTEMPTS` | Tentatives de login max par compte | `10` |
|
||||
| `OBSIGATE_LOGIN_WINDOW_SECONDS` | Fenêtre de rate limiting (s) | `900` |
|
||||
| `OBSIGATE_TRUST_PROXY` | Faire confiance à `X-Forwarded-For` / `Host` | `false` |
|
||||
|
||||
Toutes ces variables sont documentées dans `.env.example`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Déploiement sécurisé (checklist)
|
||||
|
||||
- [ ] `OBSIGATE_AUTH_ENABLED=true` sur toute instance exposée.
|
||||
- [ ] Mot de passe admin fort, changé après le premier démarrage.
|
||||
- [ ] MFA activé pour les comptes admin.
|
||||
- [ ] HTTPS via reverse proxy + `OBSIGATE_SECURE_COOKIES=true`.
|
||||
- [ ] `OBSIGATE_TRUST_PROXY=true` **uniquement** derrière un proxy de confiance.
|
||||
- [ ] Volume `./data:/app/data` monté et **sauvegardé**.
|
||||
- [ ] Vaults montées en `:ro` (lecture seule) sauf besoin d'écriture.
|
||||
- [ ] Clés API révoquées dès qu'elles ne servent plus.
|
||||
- [ ] Accès réseau restreint (VPN / pare-feu) si possible.
|
||||
|
||||
---
|
||||
|
||||
## 9. Dépannage
|
||||
|
||||
| Symptôme | Piste |
|
||||
|---|---|
|
||||
| Login bloqué `429` | Rate limit : attendre la fenêtre (`OBSIGATE_LOGIN_WINDOW_SECONDS`) |
|
||||
| WebAuthn refuse l'enregistrement | Domaine/port non dérivés — activer `OBSIGATE_TRUST_PROXY` derrière un proxy |
|
||||
| TOTP « challenge inattendu » | Relancer la cérémonie ; les 5 derniers challenges sont acceptés |
|
||||
| Perte du second facteur | Utiliser un code de secours (`/api/auth/mfa/recovery`) |
|
||||
| Sessions perdues au redémarrage | Le volume `./data` n'est pas monté |
|
||||
| Clé API `401` | Clé expirée ou révoquée — en créer une nouvelle |
|
||||
@@ -0,0 +1,86 @@
|
||||
# 📝 Guide Édition & collaboration temps réel
|
||||
|
||||
Plusieurs utilisateurs peuvent éditer le **même document Markdown
|
||||
simultanément**, façon Google Docs, grâce à Yjs (CRDT) et à un canal WebSocket.
|
||||
Ce guide explique le fonctionnement et l'utilisation.
|
||||
|
||||
> **Public :** tous les utilisateurs · **Fiche technique :**
|
||||
> [`features/collaboration.md`](../features/collaboration.md)
|
||||
> **Voir aussi :** [Prise en main](./PRISE_EN_MAIN.md) · [API REST](./API_REST.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. Ce que fait la collaboration
|
||||
|
||||
- **Fusion sans conflit** via **Yjs (CRDT)** : deux personnes peuvent taper au
|
||||
même endroit, aucune modification n'est perdue.
|
||||
- **Curseurs distants colorés** et sélections visibles dans CodeMirror, étiquetés
|
||||
avec le nom de chaque utilisateur.
|
||||
- **Indicateur de présence** dans l'en-tête de l'éditeur (avatars + statut de
|
||||
connexion).
|
||||
- **Reconnexion automatique** (backoff exponentiel) : l'état est fusionné au retour.
|
||||
- **Persistance serveur** : le document est écrit sur disque **2 s** après la
|
||||
dernière modification.
|
||||
|
||||
---
|
||||
|
||||
## 2. Utilisation
|
||||
|
||||
Aucune configuration n'est nécessaire :
|
||||
|
||||
1. Ouvrez le même fichier dans **deux navigateurs** (ou deux fenêtres).
|
||||
2. Passez en mode **Editer** (ou **Forge**) dans les deux.
|
||||
3. Tapez : les modifications apparaissent en temps réel des deux côtés, avec les
|
||||
curseurs de chacun.
|
||||
|
||||
> L'édition collaborative nécessite que la vault soit **accessible en écriture**
|
||||
> (le volume Docker doit être monté **sans** `:ro` pour les vaults modifiables).
|
||||
|
||||
---
|
||||
|
||||
## 3. Transport & protocole
|
||||
|
||||
| Élément | Valeur |
|
||||
|---|---|
|
||||
| Endpoint | `ws(s)://<hôte>/ws/collab/{vault}/{chemin}` |
|
||||
| Authentification | Cookie `access_token` (ou paramètre `?token=`) |
|
||||
| Autorisation | Contrôle d'accès **par vault** appliqué à chaque connexion |
|
||||
| Protocole | Yjs / CRDT — updates + awareness (curseurs) |
|
||||
| Persistance | Écriture disque débouncée (2 s) côté serveur |
|
||||
|
||||
Le canal est mis à niveau à partir de la même origine que l'application. Derrière
|
||||
un reverse proxy, autorisez les **upgrades WebSocket** et augmentez
|
||||
`proxy_read_timeout` (voir [Déploiement Docker](./DEPLOIEMENT_DOCKER.md)).
|
||||
|
||||
---
|
||||
|
||||
## 4. Sécurité
|
||||
|
||||
- L'accès au document est **revérifié à la connexion** (permissions du compte).
|
||||
- Un utilisateur sans droit sur la vault ne peut pas rejoindre la session.
|
||||
- Les échanges passent par le même domaine que l'application (pas de serveur
|
||||
tiers).
|
||||
|
||||
---
|
||||
|
||||
## 5. Limitations & bonnes pratiques
|
||||
|
||||
- La collaboration vise les fichiers **Markdown**.
|
||||
- Évitez d'éditer le même fichier simultanément depuis ObsiGate **et** une
|
||||
application de synchronisation externe (risque de conflits au niveau fichier).
|
||||
- Le document est écrit après un court délai ; attendez la fin de la sauvegarde
|
||||
avant de fermer brutalement l'onglet.
|
||||
- En cas de conflit de synchronisation externe (Syncthing), l'écran
|
||||
**Conflits** (`/api/conflicts`) aide à résoudre.
|
||||
|
||||
---
|
||||
|
||||
## 6. Dépannage
|
||||
|
||||
| Symptôme | Piste |
|
||||
|---|---|
|
||||
| Les curseurs des autres n'apparaissent pas | Vérifier le WebSocket (proxy sans support `Upgrade`) |
|
||||
| Reconnecté sans cesse | Réseau instable ou timeout proxy trop court |
|
||||
| Modifications non persistées | Vault montée en lecture seule (`:ro`) ? |
|
||||
| `401` à la connexion | Session expirée — se reconnecter |
|
||||
| Accès refusé | Le compte n'a pas la permission sur cette vault |
|
||||
@@ -0,0 +1,221 @@
|
||||
# 🐳 Guide de déploiement Docker
|
||||
|
||||
Ce guide couvre l'installation, la configuration et l'exploitation d'ObsiGate
|
||||
avec Docker / Docker Compose, y compris le reverse proxy HTTPS et les mises à jour.
|
||||
|
||||
> **Public :** administrateurs, ops
|
||||
> **Voir aussi :** [Prise en main](./PRISE_EN_MAIN.md) ·
|
||||
> [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md) ·
|
||||
> [`DEVELOPMENT_AND_RELEASES.md`](../DEVELOPMENT_AND_RELEASES.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. Prérequis
|
||||
|
||||
| Composant | Version minimale |
|
||||
|---|---|
|
||||
| Docker | ≥ 20.10 |
|
||||
| docker-compose | ≥ 2.0 |
|
||||
| Espace disque | ~200 Mo pour l'image |
|
||||
|
||||
Systèmes supportés : Linux (Ubuntu, Debian…), macOS (Intel & Apple Silicon),
|
||||
Windows (Docker Desktop), NAS compatibles Docker (Synology, QNAP…).
|
||||
|
||||
---
|
||||
|
||||
## 2. Configuration de `docker-compose.yml`
|
||||
|
||||
```yaml
|
||||
services:
|
||||
obsigate:
|
||||
build:
|
||||
context: .
|
||||
image: obsigate:latest
|
||||
container_name: obsigate
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "2020:8080" # port local 2020 → conteneur 8080
|
||||
volumes:
|
||||
- /home/user/Documents/Obsidian-Recettes:/vaults/Recettes:ro
|
||||
- /home/user/Documents/Obsidian-IT:/vaults/IT:ro
|
||||
- ./data:/app/data # persistance auth/config/backups
|
||||
environment:
|
||||
- VAULT_1_NAME=Recettes
|
||||
- VAULT_1_PATH=/vaults/Recettes
|
||||
- VAULT_2_NAME=IT
|
||||
- VAULT_2_PATH=/vaults/IT
|
||||
- OBSIGATE_AUTH_ENABLED=true
|
||||
- OBSIGATE_ADMIN_USER=admin
|
||||
env_file:
|
||||
- .env # secrets (mot de passe admin…)
|
||||
```
|
||||
|
||||
> **Important :** les chemins de vaults doivent être **absolus** et montés en
|
||||
> **lecture seule** (`:ro`) sauf si vous voulez autoriser l'édition depuis
|
||||
> ObsiGate. Le dossier `./data` doit être **persistant**.
|
||||
|
||||
### Variables de vault
|
||||
|
||||
| Variable | Description | Exemple |
|
||||
|---|---|---|
|
||||
| `VAULT_N_NAME` | Nom affiché | `Recettes` |
|
||||
| `VAULT_N_PATH` | Chemin dans le conteneur | `/vaults/Recettes` |
|
||||
| `VAULT_N_ATTACHMENTS_PATH` | Dossier d'attachements (optionnel) | `Assets/Images` |
|
||||
| `VAULT_N_SCAN_ATTACHMENTS` | Scanner les images au démarrage | `true` |
|
||||
|
||||
**Nommage :** lettres, chiffres et tirets uniquement ; le nom doit correspondre au
|
||||
chemin interne.
|
||||
|
||||
---
|
||||
|
||||
## 3. Construire et lancer
|
||||
|
||||
### 3.1 Script `build.sh` (recommandé)
|
||||
|
||||
```bash
|
||||
chmod +x build.sh # une seule fois
|
||||
./build.sh
|
||||
```
|
||||
|
||||
Le script :
|
||||
|
||||
1. vérifie Docker et Docker Compose (versions) ;
|
||||
2. valide `docker-compose.yml` (présence + syntaxe) ;
|
||||
3. contrôle chaque volume monté (avertit si la source n'existe pas) ;
|
||||
4. construit l'image (multi-stage, ~180 Mo) ;
|
||||
5. démarre le conteneur ;
|
||||
6. affiche le statut puis les logs en temps réel.
|
||||
|
||||
| Option | Description |
|
||||
|---|---|
|
||||
| `--help`, `-h` | Aide complète |
|
||||
| `--build-only` | Construire sans démarrer |
|
||||
| `--no-cache` | Rebuild complet sans cache **(défaut)** |
|
||||
| `--cache` | Utiliser le cache Docker (plus rapide) |
|
||||
| `--progress=plain` / `--progress=tty` | Sortie verbeuse / interactive |
|
||||
|
||||
### 3.2 Alternative manuelle
|
||||
|
||||
```bash
|
||||
docker compose build --no-cache
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 3.3 Exploitation
|
||||
|
||||
```bash
|
||||
docker compose down # arrêter
|
||||
docker compose up -d # redémarrer sans rebuild
|
||||
docker compose logs -f # logs temps réel
|
||||
docker compose logs --tail=100 obsigate
|
||||
```
|
||||
|
||||
> **Compatibilité Docker :** l'image utilise une variante `uvicorn` minimale et
|
||||
> `fastapi 0.110.3` pour éviter des dépendances natives optionnelles
|
||||
> (`watchfiles`, `uvloop`, `httptools`, `fastapi-cli`…) qui échouent sur Alpine,
|
||||
> ARM ou i386.
|
||||
|
||||
---
|
||||
|
||||
## 4. Reverse proxy & HTTPS
|
||||
|
||||
ObsiGate sert du HTTP en clair ; placez un reverse proxy devant pour TLS.
|
||||
|
||||
### 4.1 Nginx (exemple)
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name obsigate.example.com;
|
||||
|
||||
ssl_certificate /etc/letsencrypt/live/obsigate.example.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/obsigate.example.com/privkey.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:2020;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header Upgrade $http_upgrade; # WebSocket collab
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_read_timeout 3600s; # SSE / WebSocket
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 Variables à activer derrière un proxy
|
||||
|
||||
```bash
|
||||
OBSIGATE_SECURE_COOKIES=true # cookie Secure (HTTPS uniquement)
|
||||
OBSIGATE_TRUST_PROXY=true # confiance à X-Forwarded-For / Host
|
||||
```
|
||||
|
||||
> N'activez `OBSIGATE_TRUST_PROXY` **que** derrière un proxy de confiance, sinon
|
||||
> l'adresse IP client peut être usurpée (rate limiting, audit).
|
||||
|
||||
Cloudflare Tunnel, Caddy et Traefik fonctionnent de la même façon (pensez au
|
||||
support WebSocket et aux longs timeouts pour le SSE).
|
||||
|
||||
---
|
||||
|
||||
## 5. Healthcheck & supervision
|
||||
|
||||
L'image intègre un healthcheck sur `/api/health` (statut, version, stats). Vous
|
||||
pouvez aussi l'interroger depuis l'hôte :
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:2020/api/health
|
||||
curl -s http://localhost:2020/api/health/detailed # admin
|
||||
```
|
||||
|
||||
`/api/admin/stream` fournit un flux d'administration (admin uniquement).
|
||||
|
||||
---
|
||||
|
||||
## 6. Mises à jour
|
||||
|
||||
```bash
|
||||
git pull
|
||||
./build.sh # reconstruit et redémarre
|
||||
```
|
||||
|
||||
Vos données (`./data`) et vos vaults (volumes `:ro`) sont conservées. Pour un
|
||||
rebuild propre sans cache : `./build.sh --no-cache`.
|
||||
|
||||
> **Version :** le fichier `VERSION` à la racine est la source unique de vérité ;
|
||||
> l'image et l'UI affichent la même version. Voir
|
||||
> [`DEVELOPMENT_AND_RELEASES.md`](../DEVELOPMENT_AND_RELEASES.md).
|
||||
|
||||
---
|
||||
|
||||
## 7. Sauvegardes
|
||||
|
||||
- **Données applicatives** : sauvegardez `./data` (utilisateurs, clés, partages,
|
||||
webhooks, jetons).
|
||||
- **Vos notes** : ObsiGate n'écrit dans les vaults que si elles sont montées en
|
||||
écriture. Un backup automatique interne est créé dans `.obsigate-backup/` avant
|
||||
chaque modification (rotation 10 Mo d'audit).
|
||||
- **Backups desktop** : voir [Desktop](./DESKTOP.md).
|
||||
|
||||
---
|
||||
|
||||
## 8. Multi-plateforme
|
||||
|
||||
L'image est publiée pour `linux/amd64`, `linux/arm64`, `linux/arm/v7` et
|
||||
`linux/386`. Sur un NAS ou un Raspberry Pi, choisissez la variante correspondante
|
||||
(Buildx / `platform:` dans le compose).
|
||||
|
||||
---
|
||||
|
||||
## 9. Dépannage
|
||||
|
||||
| Symptôme | Piste |
|
||||
|---|---|
|
||||
| Port déjà utilisé | `sudo netstat -tulpn \| grep 2020` puis changer `ports: "2021:8080"` |
|
||||
| Vault introuvable | Chemin absolu, permissions de lecture, redémarrer après modif |
|
||||
| Build qui échoue | `docker system prune -f` puis `./build.sh --progress=plain` |
|
||||
| Logs | `docker compose logs -f obsigate` |
|
||||
| Widgets temps réel inopérants derrière un proxy | Autoriser les upgrades WebSocket et augmenter `proxy_read_timeout` |
|
||||
| Login « insecure cookie » | Passer en HTTPS ou retirer `OBSIGATE_SECURE_COOKIES` |
|
||||
@@ -0,0 +1,201 @@
|
||||
# 🖥️ Guide de l'application desktop (Tauri)
|
||||
|
||||
ObsiGate Desktop est une application native construite avec
|
||||
[Tauri](https://tauri.app/) (Rust + webview système). Elle embarque le backend
|
||||
Python et le frontend dans un exécutable autonome — **zéro Docker, zéro ligne de
|
||||
commande**.
|
||||
|
||||
> **Public :** tous les utilisateurs · **Statut :** version 2.x, binaires en
|
||||
> cours de stabilisation (build depuis les sources recommandé)
|
||||
> **Fiche technique :** [`features/desktop-tauri.md`](../features/desktop-tauri.md) ·
|
||||
> **Checklist E2E :** [`DESKTOP_E2E_CHECKLIST.md`](../DESKTOP_E2E_CHECKLIST.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. Fonctionnalités natives
|
||||
|
||||
| Fonctionnalité | Web | Desktop |
|
||||
|---|---|---|
|
||||
| Accès fichiers local | Via upload | Natif (sélecteur de dossier) |
|
||||
| Thème système | Manuel | Auto (suit l'OS clair/sombre) |
|
||||
| Notifications | Service Worker | Natif OS |
|
||||
| Association `.md` | ❌ | ✅ « Ouvrir avec ObsiGate » |
|
||||
| Icône de barre des tâches (tray) | ❌ | ✅ |
|
||||
| Auto-update | ❌ | ✅ (vérifie les releases Gitea) |
|
||||
| Mode hors-ligne | Limité | Complet (backend local) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Téléchargement des binaires
|
||||
|
||||
Les releases sont publiées sur
|
||||
[Gitea](https://git.dracodev.net/Projets/ObsiGate/releases) :
|
||||
|
||||
| Plateforme | Formats |
|
||||
|---|---|
|
||||
| **Linux** | `.deb` + `.AppImage` |
|
||||
| **Windows** | `.msi` + `.exe` (NSIS) |
|
||||
|
||||
### Linux
|
||||
|
||||
```bash
|
||||
# .deb (Debian / Ubuntu / Deepin)
|
||||
sudo dpkg -i obsigate_2.0.0_amd64.deb
|
||||
# Lancer : ObsiGate depuis le menu applications, ou `obsigate-desktop`
|
||||
|
||||
# .AppImage (toute distribution)
|
||||
chmod +x ObsiGate_2.0.0_amd64.AppImage
|
||||
./ObsiGate_2.0.0_amd64.AppImage
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
```cmd
|
||||
:: Double-cliquer sur ObsiGate_2.0.0_x64.msi (ou le setup NSIS)
|
||||
:: Ou lancer ObsiGate depuis le menu Démarrer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Démarrage
|
||||
|
||||
1. **Lancez l'application** depuis le menu ou la ligne de commande.
|
||||
2. Le backend Python démarre automatiquement sur `127.0.0.1:17890`
|
||||
(splash « Démarrage… » pendant le boot).
|
||||
3. La fenêtre s'ouvre et charge l'interface ObsiGate.
|
||||
4. **Premier lancement** : sélectionnez le dossier de vos vaults Obsidian via le
|
||||
sélecteur natif.
|
||||
5. Pour fermer : icône tray → **Quitter** (arrêt propre du backend).
|
||||
|
||||
---
|
||||
|
||||
## 4. Construire depuis les sources
|
||||
|
||||
Guide détaillé : [`desktop/README.md`](../../desktop/README.md).
|
||||
|
||||
### 4.1 Prérequis communs
|
||||
|
||||
| Outil | Version | Installation |
|
||||
|---|---|---|
|
||||
| Rust (cargo) | ≥ 1.75 | `rustup` |
|
||||
| Tauri CLI | ≥ 2.0 | `cargo install tauri-cli` |
|
||||
| Git | — | — |
|
||||
| Dépendances système Linux | — | `sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev` |
|
||||
|
||||
> **Important — staging :** `tauri.conf.json` embarque `backend/**` et
|
||||
> `frontend/**` **depuis le dossier `desktop/`**. Les scripts de build copient
|
||||
> automatiquement `../backend` et `../frontend` dans `desktop/` avant
|
||||
> `cargo tauri build`. Sans ce staging, le build échoue avec
|
||||
> « glob pattern backend/**/* path not found ».
|
||||
|
||||
### 4.2 Windows — `build-windows.bat`
|
||||
|
||||
```cmd
|
||||
REM Prérequis (via Scoop) : rustup, curl, git
|
||||
scoop install rustup curl git
|
||||
rustup default stable
|
||||
cargo install tauri-cli
|
||||
|
||||
cd desktop
|
||||
build-windows.bat
|
||||
```
|
||||
|
||||
Étapes du script :
|
||||
|
||||
1. Tue les processus Python résiduels (`taskkill /F /IM python.exe`).
|
||||
2. Télécharge **Python 3.11 embed** (python.org) → `desktop\python-embed\` +
|
||||
active pip (`python311._pth`).
|
||||
3. `pip install -r ..\backend\requirements.txt` dans l'embed.
|
||||
4. **Staging** : copie `..\backend` et `..\frontend` dans `desktop\`.
|
||||
5. `cargo tauri build --target x86_64-pc-windows-msvc --bundles nsis`.
|
||||
6. Copie `python-embed` à côté de l'exécutable pour le mode dev local.
|
||||
7. Nettoie les dossiers stagés.
|
||||
|
||||
→ **Artefact :** `desktop\target\x86_64-pc-windows-msvc\release\bundle\nsis\ObsiGate_2.0.0_x64-setup.exe`
|
||||
|
||||
### 4.3 Linux — `build-linux.sh`
|
||||
|
||||
```bash
|
||||
cd desktop
|
||||
chmod +x build-linux.sh
|
||||
./build-linux.sh
|
||||
```
|
||||
|
||||
Étapes du script :
|
||||
|
||||
1. Vérifie Rust + Tauri CLI, installe les dépendances système (apt).
|
||||
2. Crée un venv `desktop/python-embed/venv` + `pip install -r ../backend/requirements.txt`.
|
||||
3. **Staging** : copie `../backend` et `../frontend` dans `desktop/`.
|
||||
4. `cargo tauri build --target x86_64-unknown-linux-gnu --bundles deb,appimage`.
|
||||
5. Copie le runtime (`python-embed/`, `backend/`, `frontend/`) à côté de l'exécutable.
|
||||
|
||||
→ **Artefacts :**
|
||||
|
||||
- `desktop/target/x86_64-unknown-linux-gnu/release/bundle/deb/obsigate_2.0.0_amd64.deb`
|
||||
- `desktop/target/x86_64-unknown-linux-gnu/release/bundle/appimage/ObsiGate_2.0.0_amd64.AppImage`
|
||||
|
||||
---
|
||||
|
||||
## 5. Builds CI/CD automatiques
|
||||
|
||||
Le workflow [`.gitea/workflows/desktop-build.yml`](../../.gitea/workflows/desktop-build.yml)
|
||||
construit les binaires desktop à chaque push sur `main` touchant `desktop/**`,
|
||||
`frontend/**` ou `backend/**` (et manuellement via `workflow_dispatch`), sur des
|
||||
**runners self-hosted** :
|
||||
|
||||
| Job | Runner | Artefacts (30 jours) |
|
||||
|---|---|---|
|
||||
| `build-windows` | `[self-hosted, windows, desktop]` | `desktop/target/release/bundle/msi/*.msi` |
|
||||
| `build-linux` | `[self-hosted, linux, desktop]` | `*.AppImage` + `*.deb` |
|
||||
|
||||
Les artefacts sont téléchargeables depuis la page **Actions** du run Gitea ; la
|
||||
publication en **Gitea Release** est prévue sur les tags `v*`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Architecture desktop
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────┐
|
||||
│ Tauri (Rust) │
|
||||
│ ├─ Webview (webview système) │
|
||||
│ │ └─ Frontend (HTML/JS/CSS) │
|
||||
│ └─ Sidecar Python │
|
||||
│ └─ uvicorn backend.main:app │
|
||||
│ └─ port 127.0.0.1:17890 │
|
||||
└────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Cycle de vie : Tauri spawn le backend Python → health check → splash → webview.
|
||||
À la fermeture : arrêt propre du backend (SIGTERM / kill).
|
||||
|
||||
---
|
||||
|
||||
## 7. Mises à jour
|
||||
|
||||
L'application vérifie les **releases Gitea** et propose la mise à jour (updater
|
||||
Tauri signé). Le manifeste `latest.json` est généré automatiquement.
|
||||
|
||||
> La **signature de code Windows** n'est pas retenue (pas de certificat) : le
|
||||
> binaire peut déclencher un avertissement SmartScreen. Alternatives possibles :
|
||||
> SignPath.io (OSS gratuit), Certum OSS, Azure Trusted Signing, certificat EV.
|
||||
|
||||
---
|
||||
|
||||
## 8. Logs & dépannage
|
||||
|
||||
Les logs du backend sont écrits dans :
|
||||
|
||||
- **Windows** : `%APPDATA%\ObsiGate\logs\backend.log`
|
||||
- **Linux** : `~/.config/obsigate/logs/backend.log`
|
||||
|
||||
| Symptôme | Piste |
|
||||
|---|---|
|
||||
| « Backend ne répond pas » | Vérifier le port `17890` (conflit) et relancer |
|
||||
| Build « glob pattern backend/**/* not found » | Le staging n'a pas été fait — utiliser les scripts fournis |
|
||||
| Le sélecteur de dossier ne s'ouvre pas | Permissions système / dialogue natif bloqué |
|
||||
| Fenêtre blanche | Consulter `backend.log` ; le backend a peut-être échoué au boot |
|
||||
| Mise à jour non proposée | Vérifier la connectivité aux releases Gitea |
|
||||
|
||||
Voir aussi [Prise en main](./PRISE_EN_MAIN.md) et
|
||||
[Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md).
|
||||
@@ -0,0 +1,191 @@
|
||||
# 🧩 Guide MCP (Model Context Protocol)
|
||||
|
||||
ObsiGate expose ses vaults à des **clients MCP externes** (Claude Desktop, Cursor,
|
||||
Cline, tout client compatible MCP) via un serveur **Streamable HTTP** monté sur
|
||||
`/mcp`. Les outils sont les **mêmes** que ceux de l'assistant in-app : la couche
|
||||
`backend/tools/` est la source unique de vérité.
|
||||
|
||||
> **Statut :** livré (#79 phase E + F) · **Dernière mise à jour :** 2026-09
|
||||
> **Voir aussi :** [`features/ai-tools-mcp.md`](../features/ai-tools-mcp.md) ·
|
||||
> [`AI_ARCHITECTURE_GUIDE.md`](../AI_ARCHITECTURE_GUIDE.md) ·
|
||||
> [API REST](./API_REST.md) · [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. Prérequis
|
||||
|
||||
1. Une instance ObsiGate accessible (locale ou distante).
|
||||
2. Une **clé API** (recommandé) ou un **jeton JWT** valide
|
||||
(`Authorization: Bearer <token>`). Une seule clé fonctionne pour l'API REST
|
||||
**et** le MCP. Créez-la depuis l'interface (Configurations → 🔑 Clés API & MCP)
|
||||
ou via `POST /api/auth/tokens` — voir [API REST §2.2](./API_REST.md#22-clés-api-longue-durée-recommandé-pour-scripts--mcp).
|
||||
3. Si l'authentification est désactivée (`OBSIGATE_AUTH_ENABLED=false`), le
|
||||
serveur MCP accepte un utilisateur anonyme disposant de tous les vaults.
|
||||
|
||||
> Le transport `stdio` n'est pas encore supporté ; utilisez le transport HTTP
|
||||
> (un pont local type `mcp-remote` si votre client ne gère pas nativement le
|
||||
> Streamable HTTP distant).
|
||||
|
||||
---
|
||||
|
||||
## 2. Endpoint & protocole
|
||||
|
||||
| Élément | Valeur |
|
||||
|---|---|
|
||||
| URL | `https://<obsigate>/mcp` |
|
||||
| Transport | Streamable HTTP (`POST` JSON-RPC 2.0, `Accept: application/json, text/event-stream`) |
|
||||
| Auth | `Authorization: Bearer <JWT>` |
|
||||
| Protocole MCP | `2025-03-26` (négocié à l'`initialize`) |
|
||||
| Réponses | JSON (`json_response=True`) |
|
||||
|
||||
Handshake minimal :
|
||||
|
||||
```bash
|
||||
curl -sS https://obsigate.example/mcp \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Accept: application/json, text/event-stream" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
|
||||
"protocolVersion":"2025-03-26","capabilities":{},
|
||||
"clientInfo":{"name":"curl","version":"1.0"}}}'
|
||||
```
|
||||
|
||||
La réponse contient l'en-tête `Mcp-Session-Id` à réutiliser pour les appels
|
||||
suivants (`tools/list`, `tools/call`, `resources/read`, …).
|
||||
|
||||
---
|
||||
|
||||
## 3. Configuration des clients
|
||||
|
||||
### Claude Desktop (via pont `mcp-remote`)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"obsigate": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y", "mcp-remote",
|
||||
"https://obsigate.example/mcp",
|
||||
"--header", "Authorization: Bearer ${OBSIGATE_TOKEN}"
|
||||
],
|
||||
"env": { "OBSIGATE_TOKEN": "eyJ..." }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Cursor
|
||||
|
||||
`.cursor/mcp.json` :
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"obsigate": {
|
||||
"url": "https://obsigate.example/mcp",
|
||||
"headers": { "Authorization": "Bearer eyJ..." }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Client générique (config raccourcie)
|
||||
|
||||
```json
|
||||
{"mcpServers": {"obsigate": {
|
||||
"url": "http://localhost:2020/mcp",
|
||||
"headers": {"Authorization": "Bearer <clé API>"}
|
||||
}}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Primitives exposées
|
||||
|
||||
### 4.1 Tools
|
||||
|
||||
Les outils de **lecture/recherche** sont exposés directement. Les outils
|
||||
**d'écriture/destructifs** sont exposés via une paire **two-step** :
|
||||
`propose_<tool>` (aperçu + jeton de confirmation, aucune modification) puis
|
||||
`apply_<tool>` (consomme le jeton et exécute).
|
||||
|
||||
| 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` |
|
||||
|
||||
Flux d'une mutation :
|
||||
|
||||
```text
|
||||
1. tools/call { name: "propose_edit_file",
|
||||
arguments: { vault, path, content } }
|
||||
→ { tool, arguments, diff, confirmation_token, expires_in }
|
||||
|
||||
2. (l'utilisateur / l'agent valide)
|
||||
|
||||
3. tools/call { name: "apply_edit_file",
|
||||
arguments: { confirmation_token } }
|
||||
→ { ok: true, data: { ... } }
|
||||
```
|
||||
|
||||
Le jeton est **signé (JWT), à usage unique et à durée de vie limitée**
|
||||
(`OBSIGATE_MCP_CONFIRMATION_TTL`, défaut 300 s). Un rejeu renvoie `token_reused`.
|
||||
|
||||
### 4.2 Resources
|
||||
|
||||
| URI | Contenu |
|
||||
|---|---|
|
||||
| `vault://<name>` | Vault accessible (métadonnées, nombre de fichiers) |
|
||||
| `vault://<name>/<path>` | Contenu d'un fichier (lecture seule, **secrets redactés**) |
|
||||
|
||||
### 4.3 Prompts
|
||||
|
||||
`summarize-directory`, `generate-note`, `find-related`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Sécurité
|
||||
|
||||
- **Permissions par vault** : `check_vault_access` est appliqué à chaque outil
|
||||
et chaque resource ; un utilisateur ne voit que ses vaults.
|
||||
- **Anti path-traversal** : `resolve_safe_path` rejette tout chemin hors du vault.
|
||||
- **Confirmation two-step** pour toute mutation (jeton signé, usage unique).
|
||||
- **Toggle par vault** `aiDestructiveTools` (défaut : activé) : le désactiver
|
||||
bloque rename/move/replace/delete tout en laissant create/edit/append.
|
||||
- **Backup automatique** avant chaque opération destructive.
|
||||
- **Rate limiting** : par jeton et par outil
|
||||
(`OBSIGATE_TOOL_RATE_LIMIT`, `OBSIGATE_TOOL_RATE_LIMIT_PER_TOOL`,
|
||||
`OBSIGATE_TOOL_RATE_WINDOW`). Une limite dépassée renvoie le code `rate_limited`.
|
||||
- **Redaction des secrets** : les résultats d'outils (lectures, diffs, extraits
|
||||
de recherche) sont nettoyés avant tout retour au client.
|
||||
- **Audit** : chaque appel est journalisé (`data/audit.log`, action
|
||||
`ai_tool_call`) avec arguments sensibles résumés.
|
||||
|
||||
### Variables d'environnement
|
||||
|
||||
| Variable | Défaut | Rôle |
|
||||
|---|---|---|
|
||||
| `OBSIGATE_MCP_CONFIRMATION_TTL` | `300` | Durée de vie (s) des jetons de confirmation |
|
||||
| `OBSIGATE_TOOL_RATE_LIMIT` | `60` | Appels d'outils max par identité et par fenêtre |
|
||||
| `OBSIGATE_TOOL_RATE_LIMIT_PER_TOOL` | = global | Appels max par outil et par fenêtre |
|
||||
| `OBSIGATE_TOOL_RATE_WINDOW` | `60` | Longueur de la fenêtre (s) |
|
||||
| `BOOKSLM_MAX_TOOL_CALLS` | `25` | Quota d'appels d'outils par run d'agent |
|
||||
| `BOOKSLM_MAX_TOOL_READ_BYTES` | `200000` | Taille max renvoyée par `read_file` |
|
||||
|
||||
---
|
||||
|
||||
## 6. Dépannage
|
||||
|
||||
| Symptôme | Cause probable / remède |
|
||||
|---|---|
|
||||
| `401 Authentification requise` | En-tête `Authorization: Bearer` absent ou jeton expiré |
|
||||
| `vault_access_denied` | Le jeton n'a pas accès à ce vault (`vaults` / `_token_vaults`) |
|
||||
| `destructive_tools_disabled` | `aiDestructiveTools=false` pour ce vault |
|
||||
| `confirmation_required` | Appeler d'abord `propose_<tool>` puis `apply_<tool>` |
|
||||
| `token_reused` / `invalid_confirmation` | Jeton déjà consommé ou expiré → refaire un `propose_` |
|
||||
| `rate_limited` | Quota dépassé ; respecter `retry_after` |
|
||||
| Le client ne se connecte pas | Vérifier le transport Streamable HTTP / le pont `mcp-remote` |
|
||||
@@ -0,0 +1,236 @@
|
||||
# 🚀 Guide de prise en main
|
||||
|
||||
Ce guide vous fait passer d'une installation fraîche à une utilisation courante
|
||||
d'ObsiGate : première connexion, découverte de l'interface, navigation dans vos
|
||||
vaults Obsidian et raccourcis essentiels.
|
||||
|
||||
> **Public :** tous les utilisateurs · **Durée de lecture :** ~10 min
|
||||
> **Voir aussi :** [Déploiement Docker](./DEPLOIEMENT_DOCKER.md) ·
|
||||
> [Recherche, PDF & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md) ·
|
||||
> [API REST](./API_REST.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. Qu'est-ce qu'ObsiGate ?
|
||||
|
||||
ObsiGate est une **porte d'entrée web ultra-légère** vers vos vaults Obsidian.
|
||||
Il indexe vos notes en mémoire, les rend accessibles depuis n'importe quel
|
||||
navigateur (ordinateur, tablette, téléphone) et ajoute une couche moderne :
|
||||
recherche avancée, lecture Markdown, liens `[[wikilinks]]`, images, PDF,
|
||||
Excalidraw, Mermaid, assistant IA, collaboration temps réel.
|
||||
|
||||
Points clés :
|
||||
|
||||
- **Aucune modification de vos vaults** : les volumes sont montés en lecture seule (`:ro`) par défaut.
|
||||
- **Pas de base de données** : tout l'état tient dans des fichiers JSON sous `data/`.
|
||||
- **Temps réel** : un watcher surveille le système de fichiers et met l'index à jour à chaud.
|
||||
- **Multi-vault** : plusieurs vaults peuvent être affichés et recherchés simultanément.
|
||||
|
||||
---
|
||||
|
||||
## 2. Prérequis
|
||||
|
||||
| Composant | Version | Remarque |
|
||||
|---|---|---|
|
||||
| Docker | ≥ 20.10 | ou Node/`uv` pour un lancement manuel |
|
||||
| docker-compose | ≥ 2.0 | inclus avec Docker Desktop |
|
||||
| Navigateur | récent | Chrome, Edge, Firefox, Safari |
|
||||
|
||||
Vous aurez aussi besoin du **chemin absolu** de chaque vault Obsidian sur la
|
||||
machine qui héberge Docker.
|
||||
|
||||
---
|
||||
|
||||
## 3. Lancer ObsiGate en 3 étapes
|
||||
|
||||
> La procédure complète (reverse proxy, HTTPS, mises à jour) est détaillée dans le
|
||||
> [Guide de déploiement Docker](./DEPLOIEMENT_DOCKER.md).
|
||||
|
||||
### 3.1 Cloner le dépôt
|
||||
|
||||
```bash
|
||||
git clone https://git.dracodev.net/Projets/ObsiGate.git
|
||||
cd ObsiGate
|
||||
```
|
||||
|
||||
### 3.2 Déclarer vos vaults
|
||||
|
||||
Éditez `docker-compose.yml` pour monter vos dossiers (chemins absolus, lecture seule) :
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- /home/user/Documents/Obsidian-Recettes:/vaults/Recettes:ro
|
||||
- /home/user/Documents/Obsidian-IT:/vaults/IT:ro
|
||||
- ./data:/app/data # persistance auth/config
|
||||
environment:
|
||||
- VAULT_1_NAME=Recettes
|
||||
- VAULT_1_PATH=/vaults/Recettes
|
||||
- VAULT_2_NAME=IT
|
||||
- VAULT_2_PATH=/vaults/IT
|
||||
```
|
||||
|
||||
Créez le fichier de secrets à partir du modèle :
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Éditez .env (mot de passe admin, options d'auth…)
|
||||
```
|
||||
|
||||
### 3.3 Construire et démarrer
|
||||
|
||||
```bash
|
||||
chmod +x build.sh # une seule fois
|
||||
./build.sh
|
||||
```
|
||||
|
||||
`build.sh` vérifie Docker, valide les volumes, construit l'image et démarre le
|
||||
conteneur. Ouvrez ensuite **http://localhost:2020**.
|
||||
|
||||
> Options utiles : `./build.sh --help`, `./build.sh --cache` (rebuild rapide),
|
||||
> `./build.sh --build-only` (construire sans démarrer).
|
||||
|
||||
---
|
||||
|
||||
## 4. Premier accès
|
||||
|
||||
### 4.1 Si l'authentification est désactivée (défaut)
|
||||
|
||||
Vous arrivez directement sur l'interface. Toutes les fonctionnalités sont
|
||||
accessibles sans compte — **à réserver à un usage sur réseau de confiance**.
|
||||
|
||||
### 4.2 Si l'authentification est activée
|
||||
|
||||
L'écran de connexion s'affiche. Au **tout premier démarrage**, ObsiGate crée un
|
||||
compte admin et affiche le mot de passe **une seule fois dans les logs** :
|
||||
|
||||
```bash
|
||||
docker compose logs obsigate | grep -A4 "FIRST"
|
||||
```
|
||||
|
||||
Changez ce mot de passe dès la première connexion (menu → profil →
|
||||
*Changer le mot de passe*). La gestion complète des comptes, du MFA et des
|
||||
permissions est décrite dans le
|
||||
[Guide Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md).
|
||||
|
||||
---
|
||||
|
||||
## 5. Découvrir l'interface
|
||||
|
||||
L'interface se compose de trois zones principales.
|
||||
|
||||
### 5.1 L'en-tête (header)
|
||||
|
||||
| Élément | Rôle |
|
||||
|---|---|
|
||||
| 🔍 **Barre de recherche globale** | Recherche dans toutes les vaults autorisées |
|
||||
| Filtre | Restreint la recherche (type, tag, vault…) |
|
||||
| Sélecteur de vault | Bascule l'arborescence sur une vault ou « Toutes les vaults » |
|
||||
| Utilisateur | Nom du compte connecté (si auth activée) |
|
||||
| Version | Version courante d'ObsiGate |
|
||||
| ⚙️ **Options** | Configuration, thème, guide d'utilisation, administration |
|
||||
|
||||
### 5.2 La barre latérale (sidebar)
|
||||
|
||||
Elle regroupe les vues principales via des icônes :
|
||||
|
||||
- **Arborescence** — parcourt les dossiers et fichiers de la vault sélectionnée.
|
||||
- **Graphe** — vue force-directed des liens entre notes.
|
||||
- **Récents** — derniers fichiers ouverts.
|
||||
- **Signets** — vos fichiers et recherches enregistrés.
|
||||
- **Partagés** — liens de partage public que vous avez créés.
|
||||
|
||||
Un champ **« Filtrer fichiers… »** restreint l'arborescence en temps réel, et le
|
||||
bouton **Aa** ajuste l'affichage des libellés.
|
||||
|
||||
### 5.3 La zone de contenu
|
||||
|
||||
Elle affiche l'onglet actif : tableau de bord **Statistiques**, **Bookmarks**,
|
||||
**Récents**, **Partagés**, ou le document ouvert. Les documents s'ouvrent dans
|
||||
des **onglets** (avec possibilité de vue multi-panneaux / split view).
|
||||
|
||||
---
|
||||
|
||||
## 6. Navigation et lecture
|
||||
|
||||
1. **Déployez une vault** dans la sidebar (clic sur son nom).
|
||||
2. **Cliquez sur un dossier** pour l'ouvrir, sur un **fichier** pour l'afficher.
|
||||
3. Le **breadcrumb** en haut du document permet de remonter rapidement.
|
||||
4. Les **wikilinks** `[[note]]` sont cliquables ; les images et diagrammes
|
||||
s'affichent automatiquement.
|
||||
5. Utilisez **Ctrl + clic** sur un lien pour l'ouvrir en aperçu rapide selon le
|
||||
contexte, ou ouvrir le graphe centré sur un nœud.
|
||||
|
||||
### Créer et modifier
|
||||
|
||||
- **Bouton « Editer »** : ouvre le document dans l'éditeur Markdown (CodeMirror).
|
||||
- **Bouton « Forge »** (éditeur avancé) : ouvre la version enrichie avec
|
||||
assistant IA intégré. Voir [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md).
|
||||
- **Nouveau fichier / dossier** : depuis les actions de la sidebar ou la palette
|
||||
de commandes.
|
||||
- **Sauvegarde** : `Ctrl + S` (et auto-sauvegarde dans l'éditeur IA).
|
||||
|
||||
> Selon le mode, la lecture et l'édition se remplacent : `Editer` et `Forge`
|
||||
> prennent la place de la vue lecture ; revenez avec `✓` / `×` ou `Échap`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Rechercher
|
||||
|
||||
La recherche est un point fort d'ObsiGate : index inversé TF-IDF, stemming
|
||||
français, normalisation des accents, facettes et pagination. La syntaxe complète
|
||||
(`tag:`, `#`, `vault:`, `title:`, `path:`, `ext:`, phrases exactes) est décrite
|
||||
dans le [Guide Recherche, PDF & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md).
|
||||
|
||||
Démarrage rapide :
|
||||
|
||||
- Tapez dans la barre de recherche, `Ctrl + K` pour y revenir.
|
||||
- `/` focalise la recherche hors champ de saisie.
|
||||
- `/` + `↑`/`↓` navigue dans les suggestions.
|
||||
|
||||
---
|
||||
|
||||
## 8. Apparence et confort
|
||||
|
||||
- **Thème clair/sombre** : bascule persistée en `localStorage` ; le desktop suit
|
||||
aussi le thème du système.
|
||||
- **Thèmes** : clair, sombre, contraste élevé, sépia — import/export possible.
|
||||
- **Responsive** : l'interface s'adapte au mobile (éditeur tactile, barre
|
||||
d'outils flottante).
|
||||
- **PWA** : installable comme application native, mode hors-ligne partiel.
|
||||
|
||||
Voir [PWA & mode hors-ligne](./PWA_HORS_LIGNE.md).
|
||||
|
||||
---
|
||||
|
||||
## 9. Raccourcis clavier essentiels
|
||||
|
||||
| Action | Raccourci |
|
||||
|---|---|
|
||||
| Palette de commandes | `Ctrl + Shift + Space` |
|
||||
| Palette de fichiers (navigation rapide) | `Ctrl + Alt + Space` |
|
||||
| Focus barre de recherche | `Ctrl + K` |
|
||||
| Recherche rapide (hors champ texte) | `/` |
|
||||
| Sauvegarder le fichier ouvert | `Ctrl + S` |
|
||||
| Rechercher dans le document | `Ctrl + F` |
|
||||
| Completion IA inline (éditeur) | `Ctrl + J` |
|
||||
| Insertion rapide (éditeur Forge) | `Alt + I` |
|
||||
| Fermer l'éditeur / modale | `Échap` |
|
||||
| Aide de l'éditeur Forge | `F1` |
|
||||
| Naviguer dans les suggestions | `↑` / `↓` |
|
||||
| Lancer la recherche / valider | `Entrée` |
|
||||
|
||||
> Le panneau **Raccourcis & Astuces** du tableau de bord Statistiques récapitule
|
||||
> ces raccourcis directement dans l'application.
|
||||
|
||||
---
|
||||
|
||||
## 10. Et ensuite ?
|
||||
|
||||
| Objectif | Guide |
|
||||
|---|---|
|
||||
| Mieux chercher, lire PDF et Excalidraw | [Recherche, PDF & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md) |
|
||||
| Utiliser l'IA intégrée | [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md) |
|
||||
| Éditer à plusieurs | [Édition & collaboration](./COLLABORATION.md) |
|
||||
| Sécuriser l'accès | [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md) |
|
||||
| Automatiser via API/MCP | [API REST](./API_REST.md) · [MCP](./MCP.md) |
|
||||
| Installer l'application native | [Desktop (Tauri)](./DESKTOP.md) |
|
||||
@@ -0,0 +1,136 @@
|
||||
# 📱 Guide PWA & mode hors-ligne
|
||||
|
||||
ObsiGate est une **Progressive Web App (PWA)** : installez-la comme une
|
||||
application native, consultez vos notes **hors-ligne**, recevez des
|
||||
notifications et synchronisez vos modifications à la reconnexion.
|
||||
|
||||
> **Public :** tous les utilisateurs · **Guides techniques :**
|
||||
> [`PWA_GUIDE.md`](../PWA_GUIDE.md) · [`INSTALLATION_PWA.md`](../INSTALLATION_PWA.md)
|
||||
> **Voir aussi :** [Prise en main](./PRISE_EN_MAIN.md) · [Édition & collaboration](./COLLABORATION.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. Qu'est-ce que la PWA d'ObsiGate ?
|
||||
|
||||
Une PWA combine le meilleur du web et du natif :
|
||||
|
||||
- **Installation** sur l'écran d'accueil, sans store.
|
||||
- **Mode hors-ligne** : interface et dernières données consultées mises en cache.
|
||||
- **Notifications** : alertes de mise à jour et Web Push.
|
||||
- **Performance** : chargement rapide via cache intelligent.
|
||||
- **Multi-plateforme** : desktop, mobile, tablette.
|
||||
|
||||
---
|
||||
|
||||
## 2. Installer la PWA
|
||||
|
||||
### Desktop (Chrome, Edge, Brave)
|
||||
|
||||
1. Ouvrez ObsiGate dans le navigateur.
|
||||
2. Cliquez sur l'icône d'installation dans la barre d'adresse (➕ / ⬇️).
|
||||
3. Cliquez sur **Installer** dans la popup.
|
||||
4. ObsiGate apparaît dans vos applications.
|
||||
|
||||
*Alternative :* menu ⋮ → **Installer ObsiGate…**
|
||||
|
||||
### Android (Chrome)
|
||||
|
||||
1. Ouvrez ObsiGate dans Chrome.
|
||||
2. Menu ⋮ → **Ajouter à l'écran d'accueil**.
|
||||
3. Confirmez.
|
||||
|
||||
### iOS / iPadOS (Safari)
|
||||
|
||||
1. Ouvrez ObsiGate dans Safari.
|
||||
2. Bouton Partager 📤 → **Sur l'écran d'accueil**.
|
||||
3. Nommez l'application puis **Ajouter**.
|
||||
|
||||
---
|
||||
|
||||
## 3. Mode hors-ligne
|
||||
|
||||
Le **Service Worker** (`frontend/sw.js`) met en cache :
|
||||
|
||||
- l'interface (HTML, CSS, JavaScript, manifeste) ;
|
||||
- les ressources statiques (icônes, polices) ;
|
||||
- les dernières données API consultées.
|
||||
|
||||
### Stratégies de cache
|
||||
|
||||
| Ressource | Stratégie |
|
||||
|---|---|
|
||||
| Code (HTML/JS/CSS/manifest) | **Network-first** (cache en secours hors-ligne) |
|
||||
| API | **Network-first** (+ cache hors-ligne) |
|
||||
| Autres assets (images, polices) | **Stale-while-revalidate** |
|
||||
| Nettoyage | Purge des caches d'une version antérieure à l'activation |
|
||||
|
||||
> Le choix **network-first** est délibéré : les assets ne sont pas fingerprintés,
|
||||
> un cache-first servirait indéfiniment un ancien build sur mobile.
|
||||
|
||||
### File de synchronisation & conflits
|
||||
|
||||
- Les modifications faites hors-ligne sont stockées (IndexedDB) et rejouées à la
|
||||
reconnexion.
|
||||
- Les conflits éventuels sont détectés et peuvent être résolus (écran
|
||||
**Conflits**, `GET /api/conflicts`).
|
||||
|
||||
### Tester hors-ligne
|
||||
|
||||
1. DevTools (F12) → onglet **Network**.
|
||||
2. Cochez **Offline**.
|
||||
3. Rechargez : l'application doit fonctionner avec le cache.
|
||||
|
||||
---
|
||||
|
||||
## 4. Notifications (Web Push)
|
||||
|
||||
- Abonnement à partir de l'interface (permission navigateur requise).
|
||||
- Endpoints : `GET /api/push/vapid-public-key`,
|
||||
`POST /api/push/subscribe`, `DELETE /api/push/subscribe`,
|
||||
`GET /api/push/subscriptions`.
|
||||
- Les notifications sont signées **VAPID** et peuvent prévenir de changements
|
||||
(collaboration, mises à jour).
|
||||
|
||||
---
|
||||
|
||||
## 5. Mises à jour
|
||||
|
||||
- Vérification régulière des mises à jour.
|
||||
- Notification quand une nouvelle version est disponible.
|
||||
- Mise à jour en un clic, **sans perte de données**.
|
||||
- Le numéro `SW_VERSION` invalide l'ancien cache à chaque livraison.
|
||||
|
||||
### Forcer une mise à jour (console)
|
||||
|
||||
```javascript
|
||||
navigator.serviceWorker.getRegistration().then(reg => reg.update());
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Débogage
|
||||
|
||||
### Vérifier l'installation
|
||||
|
||||
Chrome DevTools → onglet **Application** :
|
||||
|
||||
- **Manifest** : métadonnées ;
|
||||
- **Service Workers** : enregistrement ;
|
||||
- **Cache Storage** : contenu du cache.
|
||||
|
||||
### Désinstaller le Service Worker
|
||||
|
||||
```javascript
|
||||
navigator.serviceWorker.getRegistrations().then(regs => regs.forEach(r => r.unregister()));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Limites
|
||||
|
||||
- Le hors-ligne dépend des données déjà mises en cache.
|
||||
- Les actions d'écriture hors-ligne s'appliquent à la reconnexion (pas en temps
|
||||
réel).
|
||||
- iOS applique des contraintes spécifiques (persistance, notifications).
|
||||
|
||||
Voir [Édition & collaboration](./COLLABORATION.md) pour le temps réel.
|
||||
@@ -0,0 +1,54 @@
|
||||
# 📚 Guides d'utilisation ObsiGate
|
||||
|
||||
Bienvenue dans le répertoire des **guides utilisateur** d'ObsiGate. Chaque guide est
|
||||
autonome, écrit en français et illustré d'exemples concrets (commandes, configuration,
|
||||
captures conceptuelles).
|
||||
|
||||
> **Vous découvrez ObsiGate ?** Commencez par le **[Guide de prise en main](./PRISE_EN_MAIN.md)**.
|
||||
> Une aide rapide est aussi intégrée directement dans l'application (menu Options →
|
||||
> **Guide d'utilisation**, FR/EN, téléchargeable en Markdown et PDF).
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ Sommaire des guides
|
||||
|
||||
| Guide | Public | Contenu |
|
||||
|---|---|---|
|
||||
| 🚀 [Prise en main](./PRISE_EN_MAIN.md) | Tous | Premier lancement, interface, navigation, vaults, raccourcis |
|
||||
| 🔍 [Recherche, PDF & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md) | Tous | Syntaxe de requête, recherche sémantique, lecteur PDF, diagrammes |
|
||||
| 🤖 [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md) | Tous | Fournisseurs, éditeur IA, BooksLM, Forge, commandes `@` / `/` |
|
||||
| 📝 [Édition & collaboration](./COLLABORATION.md) | Tous | Édition simultanée, curseurs distants, persistance |
|
||||
| 📱 [PWA & mode hors-ligne](./PWA_HORS_LIGNE.md) | Tous | Installation PWA, cache, file de synchronisation, notifications |
|
||||
| 🔌 [API REST](./API_REST.md) | Développeurs | Authentification, clés API, endpoints, exemples `curl`, SSE |
|
||||
| 🧩 [Serveur MCP](./MCP.md) | Développeurs / IA | Brancher Claude Desktop, Cursor, Cline… sur vos vaults |
|
||||
| 🔒 [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md) | Admin | Utilisateurs, MFA, permissions par vault, bonnes pratiques |
|
||||
| 🐳 [Déploiement Docker](./DEPLOIEMENT_DOCKER.md) | Admin / Ops | `docker-compose`, volumes, reverse proxy, mises à jour |
|
||||
| 🖥️ [Application desktop (Tauri)](./DESKTOP.md) | Tous | Installation, premier lancement, build depuis les sources |
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Par où commencer ?
|
||||
|
||||
- **Je veux juste utiliser l'application** → [Prise en main](./PRISE_EN_MAIN.md)
|
||||
- **Je veux sécuriser mon instance** → [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md)
|
||||
- **Je veux brancher une IA** → [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md) puis [MCP](./MCP.md)
|
||||
- **Je veux scripter/automatiser** → [API REST](./API_REST.md)
|
||||
- **Je veux héberger sur un serveur** → [Déploiement Docker](./DEPLOIEMENT_DOCKER.md)
|
||||
|
||||
---
|
||||
|
||||
## 📖 Documentation associée
|
||||
|
||||
| Type | Où |
|
||||
|---|---|
|
||||
| Vue d'ensemble produit | [`README.fr.md`](../../README.fr.md) · [`README.md`](../../README.md) |
|
||||
| Conception détaillée par fonctionnalité | [`docs/features/`](../features/) |
|
||||
| Standards de code | [`docs/CONTRIBUTING.md`](../CONTRIBUTING.md) |
|
||||
| Méthode de livraison (Definition of Done) | [`docs/DELIVERY_WORKFLOW.md`](../DELIVERY_WORKFLOW.md) |
|
||||
| Roadmap / travail à venir | [`docs/ROADMAP.md`](../ROADMAP.md) |
|
||||
| Historique des versions | [`CHANGELOG.md`](../../CHANGELOG.md) |
|
||||
| API interactive (Swagger / ReDoc) | `/docs` · `/redoc` (instance ObsiGate) |
|
||||
|
||||
> **Convention :** ce répertoire est la **porte d'entrée utilisateur**. Le *comment*
|
||||
> (utilisation) vit ici ; le *pourquoi* (conception technique) vit dans
|
||||
> [`docs/features/`](../features/). Ne jamais dupliquer le détail technique des fiches.
|
||||
@@ -0,0 +1,193 @@
|
||||
# 🔍 Guide Recherche, PDF & Excalidraw
|
||||
|
||||
ObsiGate va au-delà de la simple lecture : recherche puissante, rendu des
|
||||
documents riches (PDF, diagrammes) et indexation de leur contenu pour que tout
|
||||
soit retrouvable.
|
||||
|
||||
> **Public :** tous les utilisateurs
|
||||
> **Fiches techniques :** [`features/semantic-search.md`](../features/semantic-search.md) ·
|
||||
> [`features/pdf.md`](../features/pdf.md) · [`features/excalidraw.md`](../features/excalidraw.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. Recherche plein texte (TF-IDF)
|
||||
|
||||
Le moteur d'ObsiGate s'appuie sur un **index inversé** et un scoring **TF-IDF**
|
||||
avec :
|
||||
|
||||
- **Boost titre** — une correspondance dans le titre pèse 3× plus.
|
||||
- **Normalisation des accents** — `resume` trouve `résumé`, `elephant` trouve `éléphant`.
|
||||
- **Stemming français** — les variantes des mots sont rapprochées.
|
||||
- **Snippets surlignés** — les termes trouvés sont mis en `<mark>` dans l'extrait.
|
||||
- **Facettes** — compteurs par vault et par tag sur les résultats.
|
||||
- **Pagination** — 50 résultats par page.
|
||||
- **Tri** — par pertinence (TF-IDF) ou par date de modification.
|
||||
- **Chips de filtres** — les filtres actifs apparaissent sous forme de puces retirables.
|
||||
- **Historique** — les 50 dernières recherches sont conservées en `localStorage`.
|
||||
|
||||
La recherche s'effectue **sans I/O disque** : le contenu est déjà en mémoire.
|
||||
|
||||
---
|
||||
|
||||
## 2. Syntaxe de requête
|
||||
|
||||
| Opérateur | Description | Exemple |
|
||||
|---|---|---|
|
||||
| `tag:<nom>` | Filtre par tag | `tag:recette docker` |
|
||||
| `#<nom>` | Raccourci de tag | `#linux serveur` |
|
||||
| `vault:<nom>` | Filtre par vault | `vault:IT kubernetes` |
|
||||
| `title:<texte>` | Filtre par titre | `title:pizza` |
|
||||
| `path:<texte>` | Filtre par chemin | `path:recettes/soupes` |
|
||||
| `ext:<type>` | Filtre par type de fichier | `ext:md kubernetes` |
|
||||
| `"phrase exacte"` | Recherche d'une phrase | `tag:"multi mots"` |
|
||||
|
||||
Les opérateurs sont **combinables** :
|
||||
|
||||
```text
|
||||
tag:linux vault:IT ext:md serveur web
|
||||
```
|
||||
|
||||
Cette requête cherche « serveur web » dans les fichiers Markdown de la vault
|
||||
`IT` portant le tag `linux`.
|
||||
|
||||
### Filtres par extension
|
||||
|
||||
| Extension | Contenu |
|
||||
|---|---|
|
||||
| `ext:md` | Notes Markdown |
|
||||
| `ext:py`, `ext:sh`, `ext:js` | Scripts et code |
|
||||
| `ext:pdf` | Documents PDF (texte extrait) |
|
||||
| `ext:excalidraw` | Diagrammes Excalidraw (texte extrait) |
|
||||
|
||||
---
|
||||
|
||||
## 3. Autocomplétion et suggestions
|
||||
|
||||
- **`/api/suggest`** — suggère des titres de fichiers.
|
||||
- **`/api/tags/suggest`** — suggère des tags.
|
||||
- Navigation clavier : `↑` / `↓` puis `Entrée` ; `Échap` ferme les suggestions.
|
||||
|
||||
### Raccourcis de recherche
|
||||
|
||||
| Raccourci | Action |
|
||||
|---|---|
|
||||
| `Ctrl + K` / `Cmd + K` | Focaliser la barre de recherche |
|
||||
| `/` | Focaliser la recherche (hors champ texte) |
|
||||
| `↑` / `↓` | Naviguer dans les suggestions |
|
||||
| `Entrée` | Sélectionner la suggestion active ou lancer la recherche |
|
||||
| `Échap` | Fermer les suggestions / quitter la recherche |
|
||||
|
||||
Recherches sauvegardées et signets sont disponibles via l'API
|
||||
(`/api/saved-searches`, `/api/bookmarks`).
|
||||
|
||||
---
|
||||
|
||||
## 4. Recherche sémantique (optionnelle)
|
||||
|
||||
Au classement TF-IDF peut s'ajouter un classement **par embeddings**, fusionné
|
||||
via la méthode **RRF** (Reciprocal Rank Fusion). Activation : touche `~`
|
||||
(ou `Alt + S`) dans la recherche.
|
||||
|
||||
Deux modes :
|
||||
|
||||
1. **Sans dépendance** — un *embedder* par hachage fournit une base utilisable
|
||||
immédiatement.
|
||||
2. **Embeddings réels** — installez `backend/requirements-semantic.txt` et/ou
|
||||
renseignez les variables `OBSIGATE_EMBEDDING_*` pour utiliser
|
||||
`all-MiniLM-L6-v2`.
|
||||
|
||||
Détails et configuration :
|
||||
[`features/semantic-search.md`](../features/semantic-search.md).
|
||||
|
||||
---
|
||||
|
||||
## 5. Support PDF
|
||||
|
||||
### Lecture
|
||||
|
||||
Les fichiers PDF de vos vaults s'affichent **en ligne** dans le navigateur via le
|
||||
visualiseur PDF natif (iframe + `<embed>`). Le fichier est **streamé** en HTTP
|
||||
Range (`206 Partial Content`) : les gros PDF se chargent progressivement.
|
||||
|
||||
### Recherche
|
||||
|
||||
Le texte est **extrait à l'indexation** (`pypdf` / `pymupdf`), donc le contenu
|
||||
des PDF est recherchable via la recherche plein texte. Utilisez `ext:pdf` pour
|
||||
limiter les résultats aux PDF.
|
||||
|
||||
### Métadonnées
|
||||
|
||||
`GET /api/file/{vault}/pdf/info` renvoie les métadonnées (pages, titre, auteur)
|
||||
**sans transférer** le document.
|
||||
|
||||
```bash
|
||||
curl "http://localhost:2020/api/file/Recettes/pdf/info?path=menu.pdf"
|
||||
```
|
||||
|
||||
### Limites
|
||||
|
||||
- **Pas d'OCR** : les PDF scannés (images) ne sont pas recherchables.
|
||||
- Pas d'annotation ni d'édition du PDF lui-même.
|
||||
|
||||
---
|
||||
|
||||
## 6. Diagrammes Excalidraw
|
||||
|
||||
Les fichiers `.excalidraw` et `.excalidraw.md` (dont le format compressé du
|
||||
**plugin Obsidian Excalidraw**) s'ouvrent dans un **éditeur visuel Excalidraw
|
||||
complet**, dans une iframe sandboxée.
|
||||
|
||||
- **Dessin et édition** sans quitter ObsiGate.
|
||||
- **Sauvegarde automatique** (débounce 2 s) ou `Ctrl + S`.
|
||||
- **Thème** clair/sombre suivi automatiquement.
|
||||
- **Texte indexé** : le texte des éléments du diagramme est extrait à
|
||||
l'indexation et donc recherchable (`ext:excalidraw`).
|
||||
|
||||
Fiche technique : [`features/excalidraw.md`](../features/excalidraw.md).
|
||||
|
||||
---
|
||||
|
||||
## 7. Autres contenus riches
|
||||
|
||||
### Mermaid
|
||||
|
||||
Les blocs de code ` ```mermaid ` sont rendus en diagrammes interactifs (live
|
||||
preview, thèmes, zoom, plein écran, pré-processeur compatible syntaxe Obsidian).
|
||||
|
||||
### Images Obsidian
|
||||
|
||||
Toutes les syntaxes d'images sont supportées avec résolution intelligente en
|
||||
7 stratégies :
|
||||
|
||||
1. chemin absolu ;
|
||||
2. dossier d'attachements configuré (`VAULT_N_ATTACHMENTS_PATH`) ;
|
||||
3. index de démarrage (correspondance unique) ;
|
||||
4. même répertoire que la note ;
|
||||
5. racine de la vault ;
|
||||
6. index de démarrage (correspondance la plus proche) ;
|
||||
7. repli : `[image not found: fichier.ext]`.
|
||||
|
||||
Rescan manuel des attachements :
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:2020/api/attachments/rescan/Recettes"
|
||||
```
|
||||
|
||||
### Graphe et backlinks
|
||||
|
||||
- **Graphe** : vue force-directed (Barnes-Hut), filtres (tag, type), profondeur,
|
||||
mode focus, export PNG, aperçu au survol (`Ctrl + clic`).
|
||||
- **Backlinks** : `GET /api/file/{vault}/backlinks?path=…` liste les notes
|
||||
pointant vers un document.
|
||||
|
||||
---
|
||||
|
||||
## 8. Dépannage
|
||||
|
||||
| Symptôme | Piste |
|
||||
|---|---|
|
||||
| Un PDF ne s'affiche pas | Vérifier la taille (`OBSIGATE_PDF_MAX_SIZE_MB`, défaut 50 Mo) |
|
||||
| Le texte d'un PDF scanné n'est pas trouvé | Pas d'OCR : normal |
|
||||
| Une image reste introuvable | Configurer `VAULT_N_ATTACHMENTS_PATH`, puis rescan |
|
||||
| La recherche sémantique ne s'active pas | Vérifier le toggle `~` et `OBSIGATE_EMBEDDING_*` |
|
||||
| Résultats obsolètes | Forcer une réindexation : `GET /api/index/reload` |
|
||||
+7
-179
@@ -1,182 +1,10 @@
|
||||
# ObsiGate — Guide MCP (Model Context Protocol)
|
||||
# Guide MCP — déplacé
|
||||
|
||||
> **Statut :** livré (#79 phase E + F) · **Dernière mise à jour :** 2026-09-11
|
||||
> **Voir aussi :** [AI_ARCHITECTURE_GUIDE.md](./AI_ARCHITECTURE_GUIDE.md) ·
|
||||
> [features/ai-tools-mcp.md](./features/ai-tools-mcp.md) · [ROADMAP.md](./ROADMAP.md)
|
||||
> Ce guide a été déplacé dans le répertoire des guides utilisateur :
|
||||
> **[docs/GUIDES/MCP.md](./GUIDES/MCP.md)**.
|
||||
|
||||
ObsiGate expose ses vaults à des **clients MCP externes** (Claude Desktop, Cursor,
|
||||
tout client compatible MCP) via un serveur **Streamable HTTP** monté sur `/mcp`.
|
||||
Les outils sont les **mêmes** que ceux de l'assistant in-app : la couche
|
||||
`backend/tools/` est la source unique de vérité.
|
||||
Le serveur MCP d'ObsiGate (`/mcp`) expose les mêmes outils que l'assistant IA à
|
||||
Claude Desktop, Cursor, Cline et tout client compatible MCP. Configuration,
|
||||
outils, resources/prompts, sécurité et dépannage s'y trouvent désormais.
|
||||
|
||||
---
|
||||
|
||||
## 1. Prérequis
|
||||
|
||||
1. Une instance ObsiGate accessible (locale ou distante).
|
||||
2. Un **jeton JWT** valide (`Authorization: Bearer <token>`), obtenu via
|
||||
`POST /api/auth/login` (ou une clé API). Le jeton porte les permissions par
|
||||
vault de l'utilisateur — l'autorisation MCP réutilise `get_current_user`.
|
||||
3. Si l'authentification est désactivée (`OBSIGATE_AUTH_ENABLED=false`), le
|
||||
serveur MCP accepte un utilisateur anonyme disposant de tous les vaults.
|
||||
|
||||
> Le transport `stdio` n'est **pas** encore supporté ; utilisez le transport
|
||||
> HTTP (un pont local type `mcp-remote` si votre client ne gère pas nativement
|
||||
> le Streamable HTTP distant).
|
||||
|
||||
---
|
||||
|
||||
## 2. Endpoint & protocole
|
||||
|
||||
| Élément | Valeur |
|
||||
|---|---|
|
||||
| URL | `https://<obsigate>/mcp` |
|
||||
| Transport | Streamable HTTP (`POST` JSON-RPC 2.0, `Accept: application/json, text/event-stream`) |
|
||||
| Auth | `Authorization: Bearer <JWT>` |
|
||||
| Protocole MCP | `2025-03-26` (négocié à l'`initialize`) |
|
||||
| Réponses | JSON (`json_response=True`) |
|
||||
|
||||
Handshake minimal :
|
||||
|
||||
```bash
|
||||
curl -sS https://obsigate.example/mcp \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Accept: application/json, text/event-stream" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
|
||||
"protocolVersion":"2025-03-26","capabilities":{},
|
||||
"clientInfo":{"name":"curl","version":"1.0"}}}'
|
||||
```
|
||||
|
||||
La réponse contient l'en-tête `Mcp-Session-Id` à réutiliser pour les appels
|
||||
suivants (`tools/list`, `tools/call`, `resources/read`, …).
|
||||
|
||||
---
|
||||
|
||||
## 3. Configuration des clients
|
||||
|
||||
### Claude Desktop (via pont `mcp-remote`)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"obsigate": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y", "mcp-remote",
|
||||
"https://obsigate.example/mcp",
|
||||
"--header", "Authorization: Bearer ${OBSIGATE_TOKEN}"
|
||||
],
|
||||
"env": { "OBSIGATE_TOKEN": "eyJ..." }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Cursor
|
||||
|
||||
`.cursor/mcp.json` :
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"obsigate": {
|
||||
"url": "https://obsigate.example/mcp",
|
||||
"headers": { "Authorization": "Bearer eyJ..." }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Primitives exposées
|
||||
|
||||
### 4.1 Tools
|
||||
|
||||
Les outils de **lecture/recherche** sont exposés directement. Les outils
|
||||
**d'écriture/destructifs** sont exposés via une paire **two-step** :
|
||||
`propose_<tool>` (aperçu + jeton de confirmation, aucune modification) puis
|
||||
`apply_<tool>` (consomme le jeton et exécute).
|
||||
|
||||
| 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` |
|
||||
|
||||
Flux d'une mutation :
|
||||
|
||||
```text
|
||||
1. tools/call { name: "propose_edit_file",
|
||||
arguments: { vault, path, content } }
|
||||
→ { tool, arguments, diff, confirmation_token, expires_in }
|
||||
|
||||
2. (l'utilisateur / l'agent valide)
|
||||
|
||||
3. tools/call { name: "apply_edit_file",
|
||||
arguments: { confirmation_token } }
|
||||
→ { ok: true, data: { ... } }
|
||||
```
|
||||
|
||||
Le jeton est **signé (JWT), à usage unique et à durée de vie limitée**
|
||||
(`OBSIGATE_MCP_CONFIRMATION_TTL`, défaut 300 s). Un rejeu renvoie
|
||||
`token_reused`.
|
||||
|
||||
### 4.2 Resources
|
||||
|
||||
| URI | Contenu |
|
||||
|---|---|
|
||||
| `vault://<name>` | Vault accessible (métadonnées, nombre de fichiers) |
|
||||
| `vault://<name>/<path>` | Contenu d'un fichier (lecture seule, **secrets redactés**) |
|
||||
|
||||
### 4.3 Prompts
|
||||
|
||||
`summarize-directory`, `generate-note`, `find-related`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Sécurité
|
||||
|
||||
- **Permissions par vault** : `check_vault_access` est appliqué à chaque outil
|
||||
et chaque resource ; un utilisateur ne voit que ses vaults.
|
||||
- **Anti path-traversal** : `resolve_safe_path` rejette tout chemin hors du vault.
|
||||
- **Confirmation two-step** pour toute mutation (jeton signé, usage unique).
|
||||
- **Toggle par vault** `aiDestructiveTools` (défaut : activé) : le désactiver
|
||||
bloque rename/move/replace/delete tout en laissant create/edit/append.
|
||||
- **Backup automatique** avant chaque opération destructive.
|
||||
- **Rate limiting** : par jeton et par outil
|
||||
(`OBSIGATE_TOOL_RATE_LIMIT`, `OBSIGATE_TOOL_RATE_LIMIT_PER_TOOL`,
|
||||
`OBSIGATE_TOOL_RATE_WINDOW`). Une limite dépassée renvoie le code
|
||||
`rate_limited`.
|
||||
- **Redaction des secrets** : les résultats d'outils (lectures, diffs,
|
||||
extraits de recherche) sont nettoyés avant tout retour au client.
|
||||
- **Audit** : chaque appel est journalisé (`data/audit.log`, action
|
||||
`ai_tool_call`) avec arguments sensibles résumés.
|
||||
|
||||
### Variables d'environnement
|
||||
|
||||
| Variable | Défaut | Rôle |
|
||||
|---|---|---|
|
||||
| `OBSIGATE_MCP_CONFIRMATION_TTL` | `300` | Durée de vie (s) des jetons de confirmation |
|
||||
| `OBSIGATE_TOOL_RATE_LIMIT` | `60` | Appels d'outils max par identité et par fenêtre |
|
||||
| `OBSIGATE_TOOL_RATE_LIMIT_PER_TOOL` | = global | Appels max par outil et par fenêtre |
|
||||
| `OBSIGATE_TOOL_RATE_WINDOW` | `60` | Longueur de la fenêtre (s) |
|
||||
| `BOOKSLM_MAX_TOOL_CALLS` | `25` | Quota d'appels d'outils par run d'agent |
|
||||
| `BOOKSLM_MAX_TOOL_READ_BYTES` | `200000` | Taille max renvoyée par `read_file` |
|
||||
|
||||
---
|
||||
|
||||
## 6. Dépannage
|
||||
|
||||
| Symptôme | Cause probable / remède |
|
||||
|---|---|
|
||||
| `401 Authentification requise` | En-tête `Authorization: Bearer` absent ou jeton expiré |
|
||||
| `vault_access_denied` | Le jeton n'a pas accès à ce vault (`vaults` / `_token_vaults`) |
|
||||
| `destructive_tools_disabled` | `aiDestructiveTools=false` pour ce vault |
|
||||
| `confirmation_required` | Appeler d'abord `propose_<tool>` puis `apply_<tool>` |
|
||||
| `token_reused` / `invalid_confirmation` | Jeton déjà consommé ou expiré → refaire un `propose_` |
|
||||
| `rate_limited` | Quota dépassé ; respecter `retry_after` |
|
||||
| Le client ne se connecte pas | Vérifier le transport Streamable HTTP / le pont `mcp-remote` |
|
||||
Sommaire des guides : [docs/GUIDES/README.md](./GUIDES/README.md).
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
# ObsiGate — Roadmap
|
||||
|
||||
> **Version :** 2.16.5 | **Dernière mise à jour :** 2026-09-22
|
||||
> **Version :** 2.16.6 | **Dernière mise à jour :** 2026-09-22
|
||||
> **Ce fichier ne contient que le travail à venir** (🔵 En cours + ⚪ Backlog) et un index compact
|
||||
> vers les fonctionnalités livrées.
|
||||
> - **Méthode de livraison à appliquer pour toute tâche : [DELIVERY_WORKFLOW.md](./DELIVERY_WORKFLOW.md)**
|
||||
|
||||
@@ -67,7 +67,7 @@
|
||||
`call_tool` (couvre les diffs, extraits de recherche et lectures non pré-redactées).
|
||||
- [x] **F3.** Documentation OpenAPI + guide MCP — `backend/openapi_docs.py` : tag `MCP`,
|
||||
règle `/mcp`, injection du path `/mcp` (Streamable HTTP, JSON-RPC) dans le schéma ;
|
||||
nouveau [`docs/MCP_GUIDE.md`](../MCP_GUIDE.md) (endpoint, auth, config Claude Desktop /
|
||||
nouveau [`docs/GUIDES/MCP.md`](../GUIDES/MCP.md) (endpoint, auth, config Claude Desktop /
|
||||
Cursor, tools/resources/prompts, sécurité, variables, dépannage).
|
||||
- [x] **F4.** Tests E2E de bout en bout — `tests/test_ai_e2e.py` : agent in-app
|
||||
read→confirmation→write, quota d'outils, rate limiting, redaction, et flux MCP complet
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 84 KiB |
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "obsigate",
|
||||
"version": "2.16.5",
|
||||
"version": "2.16.6",
|
||||
"description": "**Porte d'entrée web ultra-léger pour vos vaults Obsidian** — Accédez, naviguez et recherchez dans toutes vos notes Obsidian depuis n'importe quel appareil via une interface web moderne et responsive.",
|
||||
"main": "patch.js",
|
||||
"directories": {
|
||||
|
||||
Reference in New Issue
Block a user