Add Notion Agent and FlowDeck integration docs

Document Notion Agent (2026) concepts and a FlowDeck Agent design that orchestrates tool calls through existing FastAPI routers, plus a chat UI screenshot.
2026-07-20 14:38:42 -04:00
parent 0ea447ee6f
commit b0d222b81a
3 changed files with 1166 additions and 0 deletions
@@ -0,0 +1,702 @@
 # FlowDeck Agent — Intégration & Fonctionnement
 > **Version:** 1.0 · **Date:** 2026-07-20 · **Auteur:** Hermes-Deepin
 > **Cible:** Agent IA natif pour FlowDeck, inspiré de Notion Agent (2026)
 > **Prérequis:** FlowDeck v4.0.x · FastAPI · SQLite · Gitea/GitHub
 ---
 ## Table des matières
 1. [Vision & Objectifs](#1-vision--objectifs)
 2. [Concept : de l'IA qui répond à l'IA qui réalise](#2-concept)
 3. [Positionnement dans l'architecture FlowDeck](#3-positionnement)
 4. [Placement dans l'interface (sidebar 🤖 Agents)](#4-placement-interface)
 5. [Boucle d'exécution de l'agent](#5-boucle-dexécution)
 6. [Sources de contexte FlowDeck](#6-sources-de-contexte)
 7. [Modèle de données (nouvelles tables)](#7-modèle-de-données)
 8. [Routes & API Agent](#8-routes--api)
 9. [Le service AgentEngine](#9-service-agentengine)
 10. [Système d'outils (Tools)](#10-système-doutils)
 11. [Permissions & sécurité](#11-permissions--sécurité)
 12. [Custom Agents & déclencheurs](#12-custom-agents)
 13. [Skills réutilisables](#13-skills)
 14. [Cas d'usage FlowDeck](#14-cas-dusage)
 15. [Plan de migration](#15-plan-de-migration)
 16. [Limitations](#16-limitations)
 ---
 ## 1. Vision & Objectifs
 FlowDeck Agent transforme FlowDeck d'un clone Notion **passif** (où l'utilisateur crée manuellement collections, pages, propriétés) en un espace de travail **agentique** où une IA peut :
 - Comprendre un objectif exprimé en langage naturel
 - Lire le contexte du workspace (collections, pages, propriétés, issues Gitea)
 - Planifier une suite d'actions
 - **Exécuter** ces actions via l'API interne (créer collections, pages, propriétés, vues, sync Gitea)
 - Retourner un résultat consolidé
 L'agent réutilise l'infrastructure existante : **il n'appelle pas directement la DB**, il passe par les mêmes routers FastAPI (`/db/*`, `/board/api/*`) que l'utilisateur, garantissant cohérence, validation et respect du `PermissionManager`.
 Cette fonctionnalité concrétise la ligne `v5.0.0 — AI Assistants` de la roadmap, en s'inspirant directement du modèle Notion Agent.
 ---
 ## 2. Concept : de l'IA qui répond à l'IA qui réalise {#2-concept}
 Assistant classique :
 Utilisateur → Prompt → Réponse texte
 FlowDeck Agent :
 Utilisateur → Objectif → Planification → Collecte contexte → Actions API → Résultat
 | Notion AI | FlowDeck Agent |
 |-----------|----------------|
 | Répond, résume, réécrit | Planifie, recherche, **agit** |
 | Bloc de texte | Crée collections, pages, propriétés, vues |
 | Sans état | Historique de conversation + snapshots |
 | Aucune action DB | Modifie le workspace via routers FastAPI |
 ---
 ## 3. Positionnement dans l'architecture FlowDeck {#3-positionnement}
 L'agent s'insère comme un **nouveau service** et un **nouveau router**, sans modifier le cœur existant.
 ```
 ┌──────────────────────────────────────────────────────────────────┐
 │                         CLIENT (Browser)                          │
 │  ┌─────────────────────────────────────────────────────────┐    │
 │  │  agent_panel.html  — Panneau conversation (Alpine.js)     │    │
 │  │  agent_message.html — Fragment message (HTMX streaming)   │    │
 │  └─────────────────────────────────────────────────────────┘    │
 └──────────────────────────┬───────────────────────────────────────┘
                           │ HTTP (SSE stream / JSON)
 ┌──────────────────────────▼───────────────────────────────────────┐
 │                    FASTAPI (Python 3.11+)                         │
 │  ┌─────────────────────────────────────────────────────────┐    │
 │  │  ROUTERS                                                  │    │
 │  │  ├─ agent.py  ← NOUVEAU  /api/agent/*                      │    │
 │  │  └─ (existants: board.py, api.py, collections.py, ...)    │    │
 │  └─────────────────────────────────────────────────────────┘    │
 │  ┌─────────────────────────────────────────────────────────┐    │
 │  │  SERVICES                                                 │    │
 │  │  ├─ AgentEngine    ← NOUVEAU  (orchestrateur)             │    │
 │  │  ├─ ToolRegistry   ← NOUVEAU  (outils actionnables)        │    │
 │  │  ├─ LLMClient      ← NOUVEAU  (GPT/Claude/Gemini/local)    │    │
 │  │  ├─ ContextBuilder ← NOUVEAU  (collecte workspace)         │    │
 │  │  ├─ SearchEngine   (réutilisé — FTS5)                      │    │
 │  │  ├─ PermissionManager (réutilisé — ACL)                    │    │
 │  │  └─ GiteaClient    (réutilisé — API Gitea)                 │    │
 │  └─────────────────────────────────────────────────────────┘    │
 │  ┌─────────────────────────────────────────────────────────┐    │
 │  │  DATA LAYER — SQLite                                      │    │
 │  │  ├─ agents            ← NOUVEAU                            │    │
 │  │  ├─ agent_conversations ← NOUVEAU                          │    │
 │  │  ├─ agent_messages    ← NOUVEAU                            │    │
 │  │  ├─ agent_actions     ← NOUVEAU (journal audit)           │    │
 │  │  ├─ agent_skills      ← NOUVEAU                            │    │
 │  │  └─ (tables existantes: collections, pages, ...)          │    │
 │  └─────────────────────────────────────────────────────────┘    │
 └──────────────────────────┬───────────────────────────────────────┘
                           │ HTTPS
        ┌──────────────────┴──────────────────┐
        ▼                                       ▼
 ┌──────────────────┐              ┌──────────────────────────┐
 │  GITEA API REST  │              │  PROVIDER LLM             │
 │  (contexte issues)│             │  OpenAI / Anthropic /     │
 │                  │              │  Gemini / Ollama local    │
 └──────────────────┘              └──────────────────────────┘
 ```
 **Principe clé — Tool-calling en boucle fermée :**
 Le `LLMClient` ne touche jamais la base. Il émet des *intentions d'outil* (function calls). L'`AgentEngine` les traduit en appels HTTP internes vers les routers existants, exécutés avec la session et les permissions de l'utilisateur.
 ---
 ## 4. Placement dans l'interface (sidebar 🤖 Agents) {#4-placement-interface}
 Le sidebar FlowDeck contient déjà une entrée **🤖 Agents** (voir ARCHITECTURE §5.2). Elle devient le point d'entrée de l'agent.
 ```
 ┌────────────┬─────────────────────────────────────────────────┐
 │ SIDEBAR    │ CONTENU PRINCIPAL                                │
 │            │                                                  │
 │ 🕒 Recents │   ┌─ Page / Collection courante ──────────────┐ │
 │ ⭐ Favoris │   │                                            │ │
 │ 🤖 Agents ◄┼── clic ouvre le panneau agent (droite)         │ │
 │ 👥 Shared  │   └────────────────────────────────────────────┘ │
 │            │                                    ┌────────────┐ │
 │            │                                    │ 🤖 Agent   │ │
 │            │                                    ├────────────┤ │
 │            │                                    │ Historique │ │
 │            │                                    │ Réponses   │ │
 │            │                                    │ ─────────  │ │
 │            │                                    │ @Sources   │ │
 │            │                                    │ 📎 Fichier │ │
 │            │                                    │ [Modèle ▾] │ │
 │            │                                    │ [Saisie... ]│ │
 │            │                                    └────────────┘ │
 └────────────┴─────────────────────────────────────────────────┘
 ```
 Deux modes d'accès, comme Notion Agent :
 - **Icône flottante** (coin inférieur droit) — accès global rapide
 - **Section 🤖 Agents** du sidebar — liste des agents (personnel + custom)
 L'affichage de la section 🤖 Agents est déjà prévu dans les 3 scénarios de compte (A/B/C) — voir ARCHITECTURE §6.5.4 : **toujours visible**.
 ---
 ## 5. Boucle d'exécution de l'agent {#5-boucle-dexécution}
 Adaptation du modèle Notion (Compréhension → Contexte → Raisonnement → Action) à l'architecture FlowDeck :
 ```
 Utilisateur formule un objectif
    │
    ▼
 ┌─────────────────────────────────────────────┐
 │ 1. COMPRÉHENSION (AgentEngine)               │
 │    Parse objectif + instructions custom      │
 └──────────────────┬──────────────────────────┘
                   ▼
 ┌─────────────────────────────────────────────┐
 │ 2. COLLECTE CONTEXTE (ContextBuilder)        │
 │    - Page/collection courante (cookie ws)    │
 │    - @mentions explicites                    │
 │    - SearchEngine FTS5 (pages pertinentes)   │
 │    - Issues Gitea liées (GiteaClient)        │
 │    - Fichiers joints                         │
 │    ⚠ filtré par PermissionManager            │
 └──────────────────┬──────────────────────────┘
                   ▼
 ┌─────────────────────────────────────────────┐
 │ 3. RAISONNEMENT (LLMClient + ToolRegistry)   │
 │    LLM reçoit: objectif + contexte + schéma  │
 │    des outils disponibles (function calling) │
 │    → émet un plan / une intention d'outil    │
 └──────────────────┬──────────────────────────┘
                   ▼
 ┌─────────────────────────────────────────────┐
 │ 4. ACTION (AgentEngine → routers FastAPI)    │
 │    Exécute l'appel outil → route interne     │
 │    POST /db → create_collection              │
 │    POST /db/{id}/properties → add_property   │
 │    POST /db/{id}/pages → create_page         │
 │    Journalise dans agent_actions             │
 └──────────────────┬──────────────────────────┘
                   ▼
        Résultat outil réinjecté dans le LLM
                   │
          ┌────────┴────────┐
          │ Objectif atteint?│
          └────┬────────┬────┘
           non │        │ oui
               │        ▼
        (retour étape 3)  ┌─────────────────────────────┐
                          │ 5. RÉSULTAT consolidé + lien │
                          │    vers les objets créés     │
                          └─────────────────────────────┘
 ```
 Cette boucle **ReAct** (Reason + Act) se répète jusqu'à `max_iterations` (défaut : 12) ou atteinte de l'objectif.
 ---
 ## 6. Sources de contexte FlowDeck {#6-sources-de-contexte}
 Correspondance avec les sources Notion Agent, adaptées aux entités FlowDeck :
 | Source Notion | Équivalent FlowDeck | Mécanisme |
 |---------------|---------------------|-----------|
 | Pages, sous-pages | `pages`, `collection_pages` (parent_id) | `SearchEngine` FTS5 + lecture directe |
 | Bases de données | `collections` + `collection_properties` | Lecture schéma `schema_json` |
 | Wikis / docs internes | Blocs éditeur (`content_json`) | Parsing blocs |
 | Jira | **Issues Gitea/GitHub** | `GiteaClient` (issues, labels, milestones) |
 | Slack / Drive | Fichiers uploadés (`/api/files/`) | Lecture `files` property |
 | Fichiers joints | Upload local-workspace | PDF/MD parsing |
 | `@Projet Alpha` | `@collection` / `@page` / `@repo` | Résolution de mention |
 **Résolution des mentions** — L'utilisateur peut cibler :
@collection:Roadmap      → force le contexte sur une collection
@page:123                → une page précise
@repo:bruno/flowdeck     → issues d'un repo Gitea
@ws                      → workspace courant complet
 Le `ContextBuilder` respecte strictement le `PermissionManager` : l'agent ne voit **que** ce que l'utilisateur peut voir (même token, mêmes ACL — voir ARCHITECTURE §6.2).
 ---
 ## 7. Modèle de données (nouvelles tables) {#7-modèle-de-données}
 ```sql
 -- Définition d'un agent (personnel ou custom)
 CREATE TABLE agents (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    workspace_id INTEGER REFERENCES workspaces(id),
    name TEXT NOT NULL DEFAULT 'FlowDeck Agent',
    icon TEXT DEFAULT '🤖',
    agent_type TEXT NOT NULL DEFAULT 'personal',
    -- 'personal' | 'custom'
    description TEXT DEFAULT '',
    -- Instructions personnalisées (ton, format, règles métier)
    system_instructions TEXT DEFAULT '',
    -- Modèle IA par défaut
    model TEXT DEFAULT 'claude-opus-4-8',
    -- gpt-* | claude-* | gemini-* | ollama:*
    -- Périmètre custom agent : collections/repos autorisés
    scope_json TEXT NOT NULL DEFAULT '{}',
    -- {collections:[3,7], repos:["bruno/flowdeck"], tools:["create_page"]}
    -- Déclencheurs (custom agents)
    trigger_json TEXT NOT NULL DEFAULT '{}',
    -- {type:"schedule", cron:"0 9 * * 1"} | {type:"webhook", event:"issue.opened"}
    is_active BOOLEAN NOT NULL DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    created_by INTEGER REFERENCES users(id),
    UNIQUE(workspace_id, name)
 );
 -- Conversations (fils de discussion, comme Notion history)
 CREATE TABLE agent_conversations (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    agent_id INTEGER NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
    user_id INTEGER NOT NULL REFERENCES users(id),
    title TEXT DEFAULT 'New conversation',
    -- Contexte de départ (page/collection ouverte à l'invocation)
    context_json TEXT NOT NULL DEFAULT '{}',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
 );
 -- Messages d'une conversation
 CREATE TABLE agent_messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    conversation_id INTEGER NOT NULL REFERENCES agent_conversations(id) ON DELETE CASCADE,
    role TEXT NOT NULL,
    -- 'user' | 'assistant' | 'tool' | 'system'
    content TEXT NOT NULL DEFAULT '',
    -- Pour role='tool' : nom de l'outil + payload + résultat
    tool_calls_json TEXT DEFAULT '[]',
    model TEXT,
    tokens_used INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
 );
 -- Journal d'audit : CHAQUE action modifiant le workspace
 CREATE TABLE agent_actions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    conversation_id INTEGER NOT NULL REFERENCES agent_conversations(id) ON DELETE CASCADE,
    tool_name TEXT NOT NULL,
    -- create_collection | create_page | add_property | ...
    target_type TEXT,
    -- collection | page | property | view | issue
    target_id TEXT,
    payload_json TEXT NOT NULL DEFAULT '{}',
    result_json TEXT NOT NULL DEFAULT '{}',
    status TEXT NOT NULL DEFAULT 'success',
    -- success | error | reverted
    -- Snapshot avant modification → permet le rollback
    undo_snapshot_json TEXT DEFAULT '{}',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    executed_by INTEGER REFERENCES users(id)
 );
 -- Skills réutilisables (mini-prompts)
 CREATE TABLE agent_skills (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    workspace_id INTEGER REFERENCES workspaces(id),
    name TEXT NOT NULL,
    -- "Génération de PRD", "Analyse SWOT", "Préparation sprint"
    description TEXT DEFAULT '',
    prompt_template TEXT NOT NULL,
    -- Outils que la skill peut invoquer
    allowed_tools_json TEXT NOT NULL DEFAULT '[]',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    created_by INTEGER REFERENCES users(id),
    UNIQUE(workspace_id, name)
 );
 CREATE INDEX idx_agent_conv_user ON agent_conversations(user_id, updated_at);
 CREATE INDEX idx_agent_msg_conv ON agent_messages(conversation_id, created_at);
 CREATE INDEX idx_agent_action_conv ON agent_actions(conversation_id);
 Intégration au diagramme de relations existant
 users ──1:N──► agent_conversations ──1:N──► agent_messages
  │                    │
  │                    └──1:N──► agent_actions ──► (collections/pages/...)
  │
 workspaces ──1:N──► agents ──1:N──► agent_conversations
       │
       └──1:N──► agent_skills
 ```
 ## 8. Routes & API Agent {#8-routes--api}
 Nouveau router agent.py, préfixe /api/agent.
 # Agents (définitions)
 ```
 GET    /api/agent                          → Liste agents du workspace
 POST   /api/agent                          → Créer custom agent
 GET    /api/agent/{agent_id}               → Détail agent
 PUT    /api/agent/{agent_id}               → Update (instructions, scope, model)
 DELETE /api/agent/{agent_id}               → Supprimer custom agent
 ```
 # Conversations
 ```
 GET    /api/agent/conversations            → Historique des conversations
 POST   /api/agent/conversations            → Nouvelle conversation
 GET    /api/agent/conversations/{id}       → Messages d'une conversation
 DELETE /api/agent/conversations/{id}       → Supprimer conversation
 ```
 # Exécution (cœur)
 ```
 POST   /api/agent/conversations/{id}/run   → Envoyer un objectif (SSE stream)
       body: {message, model?, mentions?, files?, skill_id?}
       → stream: reasoning → tool_call → tool_result → ... → final
 ```
 # Actions & audit
 ```
 GET    /api/agent/conversations/{id}/actions   → Journal des actions
 POST   /api/agent/actions/{action_id}/undo     → Annuler une action (rollback)
 ```
 # Skills
 ```
 GET    /api/agent/skills                    → Liste skills
 POST   /api/agent/skills                    → Créer skill
 POST   /api/agent/skills/{id}/apply         → Appliquer une skill
 ```
 # Custom agents — déclencheurs
 ```
 POST   /api/agent/{agent_id}/trigger        → Déclenchement manuel
 ```
 # (déclenchement auto via scheduler interne + webhooks.py)
 Streaming — La route /run renvoie un flux Server-Sent Events (SSE) pour afficher en temps réel le raisonnement et chaque action, à la manière de l'interface conversationnelle Notion. Le frontend (Alpine.js) consomme le flux et met à jour agent_panel.html.
 -------------------------
 ## 9. Le service AgentEngine {#9-service-agentengine}
 Orchestrateur central. Pseudo-implémentation :
 ```
 class AgentEngine:
    """Orchestrateur ReAct pour FlowDeck Agent."""
    def __init__(self, db, user, request):
        self.db = db
        self.user = user
        self.request = request               # pour réutiliser session/cookies
        self.llm = LLMClient()
        self.tools = ToolRegistry(db, user, request)
        self.ctx = ContextBuilder(db, user)
        self.perms = PermissionManager(db, user)
    async def run(self, conversation_id, objective, *, model=None,
                  mentions=None, files=None, skill_id=None):
        agent = self._load_agent(conversation_id)
        model = model or agent.model
        # 1. COMPRÉHENSION + instructions custom + skill
        system = self._build_system_prompt(agent, skill_id)
        # 2. COLLECTE CONTEXTE (respecte permissions)
        context = await self.ctx.build(
            workspace=self._active_workspace(),
            mentions=mentions,
            files=files,
        )
        messages = [
            {"role": "system", "content": system},
            {"role": "user", "content": f"{objective}\n\n# Contexte\n{context}"},
        ]
        # 3-4. BOUCLE RAISONNEMENT ↔ ACTION
        for _ in range(MAX_ITERATIONS):  # défaut 12
            response = await self.llm.complete(
                model=model,
                messages=messages,
                tools=self.tools.schema(scope=agent.scope),  # function calling
                stream=True,
            )
            yield {"type": "reasoning", "content": response.text}
            if not response.tool_calls:
                yield {"type": "final", "content": response.text}
                break
            for call in response.tool_calls:
                # Vérif permission AVANT exécution
                self.perms.assert_can(call.tool, call.args)
                result = await self.tools.execute(call.tool, call.args)
                # Journal d'audit + snapshot rollback
                self._log_action(conversation_id, call, result)
                yield {"type": "action",
                       "tool": call.tool,
                       "target": result.get("target"),
                       "status": result["status"]}
                messages.append({"role": "tool",
                                 "name": call.tool,
                                 "content": result})
 ```
 Points clés :
 - stream=True → SSE vers le frontend
 - Chaque tool_call passe par PermissionManager.assert_can() avant exécution
 - Chaque action modifiant la DB écrit un agent_actions avec undo_snapshot_json → rollback possible
 - La boucle réutilise le même token Gitea que l'utilisateur (via user_tokens)
 -------------------------
 10. Système d'outils (Tools) {#10-système-doutils}
 Les outils sont des wrappers autour des routers FastAPI existants — l'agent ne réinvente rien.
 | Outil | Route interne appelée | Ce que ça fait |
 |-------|----------------------|----------------|
 | `search_workspace` | `SearchEngine` (FTS5) | Recherche full-text pages/collections |
 | `read_collection` | `GET /db/{id}` | Lit schéma + pages d'une collection |
 | `read_page` | `GET /db/{c}/pages/{p}` | Lit une page + propriétés + blocs |
 | `create_collection` | `POST /db` | Crée une database |
 | `add_property` | `POST /db/{id}/properties` | Ajoute une propriété typée |
 | `create_view` | `POST /db/{id}/views` | Crée une vue (table/board/calendar…) |
 | `create_page` | `POST /db/{id}/pages` | Crée une page + valeurs propriétés |
 | `update_page` | `PUT /db/{c}/pages/{p}` | Modifie propriétés/contenu |
 | `write_blocks` | `POST /board/api/pages/{id}/blocks` | Écrit du contenu (éditeur de blocs) |
 | `add_relation` | `POST /db/{id}/properties` (type relation) | Lie deux collections |
 | `create_sub_item` | `POST /db/{c}/pages/{p}/sub-items` | Crée un sub-item |
 | `add_dependency` | `POST /db/{c}/pages/{p}/dependencies` | Ajoute blocks/blocked_by |
 | `sync_gitea` | `POST /board/api/sync/{o}/{r}` | Synchronise issues ↔ collection |
 | `read_gitea_issues` | `GiteaClient` | Lit issues/labels/milestones |
 | `create_gitea_issue` | `POST /api/issues/{o}/{r}` | Crée une issue Gitea |
 | `apply_template` | `POST /db/{id}/templates/{t}/apply` | Applique un template |
 Schéma d'un outil (function calling) exposé au LLM :
 ```
 {
  "name": "create_page",
  "description": "Crée une page dans une collection FlowDeck avec ses valeurs de propriétés.",
  "parameters": {
    "type": "object",
    "properties": {
      "collection_id": {"type": "integer"},
      "title": {"type": "string"},
      "property_values": {
        "type": "object",
        "description": "Map property_id → valeur (respecte le type)"
      }
    },
    "required": ["collection_id", "title"]
  }
 }
 ```
 Filtrage par scope — Pour un custom agent, ToolRegistry.schema(scope=...) ne renvoie que les outils autorisés dans agents.scope_json.tools, et limite les cibles aux collections/repos de scope_json.
 -------------------------
 ## 11. Permissions & sécurité {#11-permissions--sécurité}
 L'agent agit avec les permissions de l'utilisateur, jamais au-delà (principe Notion Agent : « mêmes permissions que l'utilisateur »).
 ```
 ┌───────────────────────────────────────────────────────────┐
 │  GARDE-FOUS AGENT                                          │
 │                                                            │
 │  1. Identité      → session utilisateur + user_tokens      │
 │  2. ACL           → PermissionManager.assert_can() par outil│
 │  3. Scope custom  → scope_json limite collections/repos     │
 │  4. Database lock  → collection is_locked ⇒ outils write KO │
 │  5. Audit          → agent_actions journalise TOUT          │
 │  6. Rollback       → undo_snapshot_json par action          │
 │  7. Rate limiting  → RateLimiter (middleware existant)      │
 │  8. Confirmation   → actions destructives ⇒ approbation UI  │
 └───────────────────────────────────────────────────────────┘
 ```
 Mode approbation — Configurable par agent :
 - auto : l'agent exécute directement (création de contenu)
 - confirm : actions destructives (delete_page, sync massif) demandent une confirmation dans le panneau avant exécution
 Cohérent avec le modèle de rôles workspace (owner/admin/editor/commenter/viewer, ARCHITECTURE §6.2) : un agent lancé par un viewer ne peut que lire.
 -------------------------
 ## 12. Custom Agents & déclencheurs {#12-custom-agents}
 Comme Notion (Custom Agents 2026), FlowDeck distingue :
 | Type | Portée | Exemple |
 |------|--------|---------|
 | **Personal Agent** | Généraliste, tout le workspace visible | Assistant quotidien |
 | **Custom Agent** | Spécialisé, scope restreint, déclencheurs | Agent Reporting, Agent Support |
 Déclencheurs (agents.trigger_json) :
 ```
 type: "manual"    → bouton dans l'UI
 type: "schedule"  → cron interne (ex: "0 9 * * 1" = lundi 9h)
 type: "webhook"   → branché sur webhooks.py (issue.opened, issue.closed…)
 ```
 Exemples de custom agents FlowDeck :
 - Agent Reporting — chaque lundi, scanne toutes les collections, produit une page « Rapport hebdo » avec KPI
 - Agent Gitea Triage — à issue.opened, classe l'issue dans la bonne collection et remplit ses propriétés
 - Agent Sprint — prépare une collection sprint depuis les issues du milestone courant
 Le scheduler s'appuie sur le lifespan FastAPI (main.py) et les webhooks réutilisent le router webhooks.py existant.
 -------------------------
 ## 13. Skills réutilisables {#13-skills}
 Une skill est un mini-prompt paramétrable + liste d'outils autorisés (table agent_skills).
 ```
 Skill "Préparation de sprint"
 ├─ prompt_template:
 │    "Analyse les issues ouvertes du repo {repo}, crée une collection
 │     sprint '{sprint_name}', ajoute les propriétés Status/Priority/Assignee,
 │     importe chaque issue comme page, groupe en vue Board."
 ├─ allowed_tools: [read_gitea_issues, create_collection,
 │                   add_property, create_page, create_view]
 └─ Invocation: POST /api/agent/skills/{id}/apply
 ```
 Autres skills livrées par défaut : Analyse SWOT, Génération de compte-rendu, Génération de PRD, Synthèse GitHub/Gitea.
 -------------------------
 ## 14. Cas d'usage FlowDeck {#14-cas-dusage}
 Gestion de produit
 > « Crée une roadmap Q3 à partir des issues du repo bruno/flowdeck »
 ```
 L'agent : read_gitea_issues → create_collection("Roadmap Q3") → add_property(Status, Priority, DueDate) → create_page × N → create_view(timeline).
 Développement logiciel
 ```
 > « Analyse les bugs des 6 derniers mois et crée un plan d'amélioration »
 ```
 sync_gitea → search_workspace → analyse LLM → create_collection("Plan qualité") → create_page (causes, actions) → add_dependency.
 Direction
 ```
 > « Génère les OKR du prochain trimestre depuis nos objectifs actuels »
 ```
 read_collection(Objectifs) → raisonnement → create_collection("OKR Q4") → create_page × N.
 Multi-étapes (comme Notion)
 ```
 > « Résume les notes de réunion du trimestre et crée les tâches de suivi »
 ```
 search_workspace(meetings) → synthèse → write_blocks (page résumé) → create_page × N (tâches) dans la collection Tasks.
 ```
 -------------------------
 ## 15. Plan de migration {#15-plan-de-migration}
 Phase 1 — Fondations DB & Service
  1. Créer tables agents, agent_conversations, agent_messages,
     agent_actions, agent_skills
  2. Implémenter LLMClient (abstraction multi-provider)
  3. Implémenter ContextBuilder (réutilise SearchEngine)
 Phase 2 — Tool-calling
  1. ToolRegistry : wrappers read-only d'abord (search, read_*)
  2. Ajouter outils write (create_collection, create_page, ...)
  3. Brancher PermissionManager.assert_can() sur chaque outil
  4. Journal agent_actions + snapshots rollback
 Phase 3 — Interface
  1. agent_panel.html (Alpine.js) branché sur section 🤖 Agents
  2. Streaming SSE (/run)
  3. Icône flottante coin inférieur droit
  4. Affichage temps réel reasoning + actions
 Phase 4 — Personnalisation
  1. Instructions custom par agent
  2. Skills (table + /apply)
  3. Sélecteur de modèle (GPT/Claude/Gemini/Ollama)
 Phase 5 — Custom Agents
  1. Scope + trigger_json
  2. Scheduler (lifespan FastAPI)
  3. Déclencheurs webhook (via webhooks.py)
  4. Mode approbation (auto/confirm)
 -------------------------
 ## 16. Limitations {#16-limitations}
 Alignées sur les limites connues de Notion Agent, adaptées à FlowDeck. L'agent ne peut pas :
 - Modifier les paramètres du workspace (/workspace/{id}/settings)
 - Gérer les membres / rôles (workspace_members)
 - Gérer l'authentification ou les intégrations OAuth (connexion/déconnexion Gitea/GitHub)
 - Publier ou partager publiquement une page sans confirmation utilisateur (/api/pages/{id}/publish, /share)
 - Modifier une collection verrouillée (is_locked = 1)
 - Agir au-delà des permissions de l'utilisateur qui l'invoque
 - Supprimer définitivement (hard delete) sans mode confirm
 -------------------------
 Résumé
 FlowDeck Agent porte le modèle Notion Agent dans FlowDeck en réutilisant l'infrastructure existante :
 - Un service AgentEngine orchestrant une boucle ReAct (raisonnement ↔ action)
 - Des outils qui sont de simples wrappers des routers FastAPI existants (/db/*, /board/api/*, Gitea)
 - Un contexte collecté via SearchEngine + GiteaClient, filtré par PermissionManager
 - Un audit complet (agent_actions) avec rollback
 - Custom Agents, skills et déclencheurs pour l'automatisation
 Le passage de « l'IA qui répond » à « l'IA qui réalise le travail » se fait sans réécrire FlowDeck : l'agent agit comme un utilisateur privilégié mais contraint, à travers les mêmes portes que l'interface humaine.
 J'ai créé le document `Flowdeck_Agent_integration.md`. Points saillants de l'intégration proposée :
 - **Réutilisation maximale** : l'agent n'accède jamais directement à SQLite — il appelle les routers FastAPI existants (`/db/*`, `/board/api/*`, `GiteaClient`), ce qui garantit validation, cohérence et respect du `PermissionManager`.
 - **Boucle ReAct** : Compréhension → Contexte → Raisonnement → Action, calquée sur le fonctionnement de Notion Agent mais mappée sur vos entités (`collections`, `collection_pages`, issues Gitea).
 - **5 nouvelles tables** seulement (`agents`, `agent_conversations`, `agent_messages`, `agent_actions`, `agent_skills`), plus un router `agent.py` et 4 services.
 - **Sécurité** : audit complet avec `undo_snapshot_json` pour rollback, respect des rôles workspace, mode `confirm` pour les actions destructives.
 - **Custom Agents + Skills + déclencheurs** (cron via `lifespan`, webhooks via votre `webhooks.py` existant).
@@ -0,0 +1,464 @@
 # Guide complet — Notion Agent (2026)
 ## Introduction
 Notion Agent est l'évolution la plus avancée de Notion AI. Contrairement à un assistant conversationnel classique qui répond uniquement à des questions, Notion Agent est conçu pour **agir directement dans votre espace de travail**.
 L'objectif est de transformer l'IA d'un simple outil de rédaction en un véritable collaborateur numérique capable d'exécuter des tâches complètes à travers les pages, bases de données et outils connectés.
 ---
 # 1. Qu'est-ce que Notion Agent ?
 Notion Agent est un agent IA intégré nativement dans Notion.
 Il possède :
 - Un accès au contexte de votre espace de travail
 - La capacité de lire des pages et bases de données
 - La capacité de créer et modifier du contenu
 - La possibilité d'effectuer des tâches multi‑étapes
 - L'accès à certaines sources externes et outils connectés
 Conceptuellement :
 Assistant IA traditionnel :
 Utilisateur → Prompt → Réponse
 Notion Agent :
 Utilisateur → Objectif → Planification → Recherche → Actions → Résultat
 L'agent agit davantage comme un employé numérique que comme un chatbot.
 ---
 # 2. Où apparaît-il dans l'interface ?
 ## Emplacement principal
 Notion affiche l'agent sous la forme d'une icône circulaire représentant un visage.
 Position habituelle :
 - Coin inférieur droit de l'écran
 Ou :
 - Section AI dans la barre latérale gauche
 ---
 ## Interface de conversation
 Lorsque l'utilisateur ouvre l'agent :
 ┌──────────────────────────┐
 │ Conversation Agent       │
 ├──────────────────────────┤
 │ Historique               │
 │                           │
 │ Réponses                  │
 │                           │
 ├──────────────────────────┤
 │ @Sources                  │
 │ 📎 Fichier                │
 │ Modèle IA                 │
 │ Zone de saisie            │
 └──────────────────────────┘
 L'interface ressemble à ChatGPT mais avec davantage de contrôles contextuels.
 ---
 # 3. Comment fonctionne l'agent ?
 ## Étape 1 : Compréhension
 L'utilisateur formule un objectif.
 Exemples :
 - Construis un CRM.
 - Résume les notes de réunion du trimestre.
 - Crée les OKR du prochain trimestre.
 L'agent interprète l'intention.
 ---
 ## Étape 2 : Collecte du contexte
 Il récupère automatiquement :
 - La page actuelle
 - Les blocs sélectionnés
 - Les bases de données liées
 - Les documents référencés
 - Les permissions utilisateur
 Il fonctionne avec les mêmes permissions que l'utilisateur.
 ---
 ## Étape 3 : Raisonnement
 L'agent décompose la demande.
 Exemple :
 Créer un CRM
 → déterminer les propriétés
 → créer la base
 → créer les vues
 → créer les relations
 → générer des exemples
 ---
 ## Étape 4 : Action
 L'agent modifie directement Notion.
 Contrairement à un chatbot traditionnel, il peut :
 - créer
 - modifier
 - organiser
 - restructurer
 le contenu.
 ---
 # 4. Sources de connaissances
 ## Sources Notion
 L'agent peut consulter :
 - Pages
 - Sous-pages
 - Bases de données
 - Wikis
 - Documents internes
 ---
 ## Sources connectées
 Selon la configuration du workspace :
 - Jira
 - Slack
 - Google Drive
 - GitHub
 - Figma
 - Outils connectés compatibles
 ---
 ## Fichiers
 L'utilisateur peut joindre :
 - PDF
 - Documents
 - Présentations
 - Fichiers importés
 ---
 ## Mention manuelle
 L'utilisateur peut préciser :
@Projet Alpha
 ou
@Équipe Marketing
 pour forcer l'utilisation d'un contexte particulier.
 ---
 # 5. Ce que Notion Agent peut faire
 ## Création de contenu
 - Pages
 - Sous-pages
 - Documentation
 - SOP
 - Guides
 - Rapports
 - Comptes-rendus
 ---
 ## Modification de contenu
 - Réécriture
 - Résumé
 - Traduction
 - Simplification
 - Restructuration
 ---
 ## Bases de données
 L'agent peut :
 - créer une base
 - ajouter des propriétés
 - ajouter des relations
 - créer des vues
 - remplir les données
 ---
 ## Recherche documentaire
 Il peut analyser :
 - des centaines de pages
 - plusieurs bases de données
 - des documents attachés
 pour produire un résultat consolidé.
 ---
 ## Analyse
 Exemples :
 - Identifier les tendances
 - Comparer des projets
 - Détecter les risques
 - Produire des synthèses exécutives
 ---
 ## Travail multi‑étapes
 Exemple :
 « Analyse les incidents des 6 derniers mois et crée un plan d'amélioration. »
 L'agent :
 1. collecte les incidents
 2. les analyse
 3. identifie les causes
 4. produit un rapport
 5. crée les tâches
 ---
 # 6. Fonctionnalités avancées
 ## Changement de modèle IA
 Le sélecteur de modèle permet selon la disponibilité :
 - GPT
 - Claude
 - Gemini
 - autres modèles partenaires
 Certains modèles peuvent n'utiliser que le Web alors que d'autres exploitent le contexte Notion.
 ---
 ## Historique
 L'agent conserve l'historique des conversations.
 Permet :
 - reprendre un travail
 - relancer une tâche
 - réutiliser un contexte
 ---
 ## Instructions personnalisées
 L'utilisateur peut définir :
 - ton
 - style
 - format
 - règles métier
 Exemple :
 « Toujours écrire les procédures en format SOP. »
 ---
 ## Skills
 Notion introduit des compétences réutilisables.
 Une skill agit comme un mini‑prompt réutilisable.
 Exemples :
 - Génération de compte-rendu
 - Analyse SWOT
 - Préparation de sprint
 ---
 # 7. Ce que l'agent ne peut pas faire
 À ce jour, certaines limitations existent.
 Il ne peut généralement pas :
 - modifier les permissions des pages
 - partager des pages
 - gérer la facturation
 - modifier les paramètres du workspace
 - créer certaines propriétés avancées complexes
 - créer des rappels système
 ---
 # 8. Différence entre Notion AI et Notion Agent
 ## Notion AI (ancienne approche)
 - Répond
 - Résume
 - Réécrit
 ## Notion Agent
 - Planifie
 - Recherche
 - Agit
 - Modifie le workspace
 - Réalise des tâches complètes
 ---
 # 9. Custom Agents (2026)
 Notion a également lancé les Custom Agents.
 Différence :
 Notion Agent :
 - Agent personnel généraliste
 Custom Agent :
 - Agent spécialisé
 Exemples :
 - Agent RH
 - Agent Support
 - Agent Produit
 - Agent Marketing
 - Agent GitHub
 - Agent Reporting
 Ces agents peuvent fonctionner automatiquement selon des déclencheurs et horaires.
 ---
 # 10. Cas d'usage réels
 ## Gestion de produit
 - Générer des PRD
 - Créer des roadmaps
 - Analyser Jira
 ## Développement logiciel
 - Synthèse GitHub
 - Documentation technique
 - Suivi des bugs
 ## Marketing
 - Rapports de campagne
 - Veille concurrentielle
 - Création de contenu
 ## Direction
 - OKR
 - KPI
 - Rapports exécutifs
 ---
 # 11. Architecture conceptuelle
 Utilisateur
    ↓
 Notion Agent
    ↓
 Contexte Workspace
    ↓
 Sources Connectées
    ↓
 Moteur IA
    ↓
 Planification
    ↓
 Actions Notion
    ↓
 Résultat
 ---
 # 12. Vision produit
 Notion cherche à transformer son produit en système d'exploitation du travail.
 L'évolution observée :
 2018 → Notes
 2020 → Bases de données
 2023 → Notion AI
 2025 → Notion Agent
 2026 → Custom Agents
 Direction probable :
 - équipes d'agents spécialisés
 - automatisation continue
 - orchestration inter‑outils
 - assistants autonomes de projet
 ---
 # Résumé
 Notion Agent est un agent IA intégré profondément dans Notion.
 Ses caractéristiques majeures :
 - Compréhension du contexte
 - Accès aux connaissances du workspace
 - Raisonnement multi‑étapes
 - Création et modification de contenu
 - Gestion des bases de données
 - Analyse documentaire
 - Personnalisation via instructions et skills
 - Intégration avec outils externes
 - Possibilité d'évoluer vers des agents spécialisés
 Il représente le passage de « l'IA qui répond » à « l'IA qui réalise le travail » directement dans l'environnement Notion.