KinBot — Plan de développement

Ce document sert de feuille de route pour le développement de KinBot. Chaque phase est conçue pour être autonome et testable. Les phases doivent être suivies dans l'ordre car chacune dépend des précédentes.

Convention : chaque tâche est marquée [ ] (à faire), [~] (en cours), ou [x] (terminé).

Phase 0 — Initialisation du projet

Mise en place du monorepo, de la toolchain, et des fichiers de configuration.

Critère de validation : bun run dev démarre le frontend (Vite) et le backend (Hono) sans erreur. La page par défaut s'affiche.

Phase 0.5 — Design system et validation visuelle

BLOQUANT : aucun développement frontend réel (pages, composants métier) ne démarre avant que cette phase soit validée par le porteur du projet. Le backend (phases 1-6) peut avancer en parallèle.

Création d'une page showcase présentant tous les éléments visuels de base. L'objectif est de valider la direction graphique (palette, typographie, composants, dark mode) avant de construire les vrais écrans.

Critère de validation : le porteur du projet ouvre /design-system, passe en revue chaque section en light et dark mode, et approuve la direction visuelle. Les ajustements demandés sont appliqués avant de continuer.

Une fois validé : les phases frontend (3, 7, 8, 9.6-9.10, etc.) peuvent démarrer en s'appuyant sur les composants et tokens approuvés. La page /design-system reste disponible en dev comme référence.

Phase 1 — Base de données et schéma

Définition complète du schéma Drizzle et création de la base SQLite.

1.1 Créer src/server/db/index.ts — connexion SQLite via bun:sqlite avec chargement des extensions (sqlite-vec, FTS5)
1.2 Créer src/server/db/schema.ts — définir toutes les tables Drizzle conformes à schema.md :
- Tables Better Auth : user, session, account, verification
- Tables custom : user_profiles, providers, kins, mcp_servers, kin_mcp_servers, messages, compacting_snapshots, memories, contacts, custom_tools, tasks, crons, vault_secrets, queue_items, files
1.3 Créer les index conformes au schéma (tous les idx_* documentés)
1.4 Créer les tables virtuelles FTS5 (memories_fts, messages_fts) avec triggers de synchronisation
1.5 Créer la table virtuelle sqlite-vec (memories_vec)
1.6 Générer et exécuter la première migration Drizzle
1.7 (Optionnel) Créer src/server/db/seed.ts pour le développement

Critère de validation : bun run db:push crée la base avec toutes les tables. Vérifiable via sqlite3 data/kinbot.db ".tables".

Phase 2 — Authentification et gestion des utilisateurs

Critère de validation : un utilisateur peut s'inscrire, se connecter, se déconnecter. Le middleware bloque les requêtes non authentifiées. La page de login fonctionne.

Phase 3 — Onboarding

3.1 Frontend : créer src/client/pages/onboarding/OnboardingPage.tsx — wizard avec navigation entre étapes
3.2 Frontend : créer src/client/pages/onboarding/StepIdentity.tsx — formulaire (photo, prénom, nom, email, pseudonyme, langue, mot de passe)
3.3 Frontend : créer src/client/pages/onboarding/StepProviders.tsx — configuration des AI providers avec test de connexion en temps réel
3.3b Frontend : créer src/client/pages/onboarding/StepSearchProviders.tsx — configuration des search providers (step optionnel, même UX que StepProviders)
3.4 Backend : logique de validation de l'onboarding (vérifier que les capacités llm et embedding sont couvertes)
3.5 Backend : créer le premier user_profiles avec rôle admin à l'issue de l'onboarding
3.6 Après onboarding réussi, redirection vers l'interface principale avec ouverture automatique de la modale de création du premier Kin

Critère de validation : un utilisateur neuf arrive sur le wizard, configure son profil et au moins un provider, et atterrit sur l'interface principale.

Phase 4 — Providers IA

Gestion des providers et abstraction des capacités.

Critère de validation : on peut créer un provider (ex: OpenAI), tester la connexion, et lister les modèles disponibles via l'API.

Phase 5 — Event bus et hooks

Infrastructure transversale utilisée par toutes les couches suivantes.

5.1 Créer src/server/services/events.ts — event bus in-memory (emit, on, off)
5.2 Créer src/server/hooks/types.ts — types des hooks (HookContext, HookHandler)
5.3 Créer src/server/hooks/index.ts — registry des hooks + exécution chainée (beforeChat, afterChat, beforeToolCall, afterToolCall, beforeCompacting, afterCompacting, onTaskSpawn, onCronTrigger)

Critère de validation : on peut émettre un événement et le recevoir dans un listener. Les hooks peuvent être enregistrés et exécutés.

Phase 6 — SSE (Server-Sent Events)

Communication temps réel du serveur vers le client.

6.1 Créer src/server/sse/types.ts — types des événements SSE (chat:token, chat:done, chat:message, task:status, task:done, cron:triggered, queue:update, kin:error)
6.2 Créer src/server/sse/index.ts — gestionnaire SSE (gestion des connexions, broadcast par kinId, cleanup)
6.3 Créer src/server/routes/sse.ts — GET /api/sse (connexion SSE globale, une par client)
6.4 Frontend : créer src/client/hooks/useSSE.ts — connexion SSE persistante, dispatch des événements par kinId, reconnexion automatique

Critère de validation : le frontend se connecte en SSE et reçoit un événement de test envoyé depuis le backend.

Phase 7 — CRUD Kins (sans moteur LLM)

Gestion des Kins : création, édition, suppression, avatar.

7.1 Créer les routes :
- src/server/routes/kins.ts — GET /api/kins, GET /api/kins/:id, POST /api/kins, PATCH /api/kins/:id, DELETE /api/kins/:id, POST /api/kins/:id/avatar
7.2 Logique de création du workspace du Kin ({dataDir}/workspaces/{kinId}/)
7.3 Gestion des avatars (upload, génération automatique si provider image disponible, prompt personnalisé)
7.4 Frontend : créer le hook src/client/hooks/useKins.ts
7.5 Frontend : créer src/client/components/kin/KinCreateModal.tsx
7.6 Frontend : créer src/client/components/kin/KinCard.tsx
7.7 Frontend : créer src/client/components/kin/KinSettingsModal.tsx

Critère de validation : on peut créer, modifier et supprimer un Kin via l'interface. Le workspace est créé sur le disque.

Phase 8 — Interface principale (layout)

Layout global de l'application : sidebar + panel de chat.

8.1 Frontend : créer src/client/components/sidebar/AppSidebar.tsx — layout avec sections Kins, Tâches, liens vers Mon compte et Settings
8.2 Frontend : créer src/client/components/sidebar/KinList.tsx — liste des Kins avec badges (queue, statut)
8.3 Frontend : créer src/client/components/sidebar/TaskList.tsx — liste des tâches en cours
8.4 Frontend : créer src/client/pages/chat/ChatPage.tsx — layout sidebar + panel principal
8.5 Utilisation des composants Avatar et Badge existants de shadcn/ui
8.6 Frontend : créer les pages settings :
- src/client/pages/settings/SettingsPage.tsx
- src/client/pages/settings/ProvidersSettings.tsx (AI providers)
- src/client/pages/settings/SearchProvidersSettings.tsx (search providers — même pattern que ProvidersSettings, composants partagés)
- McpSettings et VaultSettings en stub dans les tabs
8.7 Frontend : créer src/client/pages/account/AccountPage.tsx

Critère de validation : le layout complet est visible. On peut naviguer entre les Kins dans la sidebar et accéder aux pages settings/compte.

Phase 9 — Queue FIFO et moteur Kin (coeur du système)

Orchestration LLM, queue de messages, construction du prompt, streaming.

Critère de validation : on peut envoyer un message à un Kin et recevoir une réponse streamée en temps réel. Le message est sauvegardé en DB et visible dans l'historique.

Phase 10 — Outils natifs de base (Tool calling)

Intégration du tool calling Vercel AI SDK et outils fondamentaux.

10.1 Créer src/server/tools/types.ts — types ToolDefinition, ToolResult
10.2 Créer src/server/tools/index.ts — registry de tous les outils, résolution par contexte (main agent vs sub-Kin)
10.3 Intégrer le tool calling dans kin-engine.ts — passage des tools au LLM, exécution des appels, boucle outil-réponse
10.4 Implémenter les hooks beforeToolCall / afterToolCall
10.5 Créer src/server/tools/search-tools.ts — web_search(query, count?, freshness?) (via search provider, conditionné à la présence d'un provider avec capacité search)

Critère de validation : le Kin peut appeler un outil natif et utiliser le résultat dans sa réponse. Si un search provider est configuré, le Kin peut rechercher sur le web.

Phase 11 — Contacts

Registre de contacts par Kin.

11.1 Créer src/server/services/contacts.ts — CRUD contacts, injection du résumé compact dans le prompt
11.2 Créer src/server/tools/contact-tools.ts — get_contact, search_contacts, create_contact, update_contact
11.3 Intégrer l'injection du bloc [4] (contacts) dans prompt-builder.ts

Critère de validation : le Kin peut créer et consulter des contacts via ses outils. Le résumé compact apparaît dans le prompt système.

Phase 12 — Mémoire long terme

Pipeline d'extraction, recall, memorize, recherche hybride.

12.1 Créer src/server/services/memory.ts — CRUD mémoires, génération d'embeddings, recherche hybride (sqlite-vec KNN + FTS5 rank fusion)
12.2 Créer src/server/tools/memory-tools.ts — recall, memorize, update_memory, forget, list_memories
12.3 Intégrer l'injection du bloc [5] (mémoires pertinentes) dans prompt-builder.ts — recherche sémantique à partir du message entrant
12.4 Créer src/server/tools/history-tools.ts — search_history (recherche hybride sur les messages)

Critère de validation : le Kin peut mémoriser et rappeler des informations. La recherche hybride retourne des résultats pertinents. Les mémoires sont injectées dans le prompt.

Phase 13 — Compacting

Résumé automatique des sessions et extraction de mémoires.

13.1 Créer src/server/services/compacting.ts conforme à compacting.md :
- Évaluation du seuil (messages + tokens)
- Sélection des messages à compacter (exclusion redact_pending)
- Appel LLM pour générer le résumé
- Sauvegarde du snapshot (activer/désactiver)
- Nettoyage des anciens snapshots
- Déclenchement du pipeline d'extraction de mémoires
13.2 Intégrer l'injection du bloc [9] (compacted summary) dans la construction des messages du contexte
13.3 Déclencher le compacting après chaque tour LLM dans kin-engine.ts
13.4 Créer les routes compacting :
- Routes dans src/server/routes/kins.ts : POST /api/kins/:id/compacting/purge, GET /api/kins/:id/compacting/snapshots, POST /api/kins/:id/compacting/rollback
13.5 Créer les routes memories (gestion via UI) :
- GET /api/kins/:id/memories, DELETE /api/kins/:id/memories/:memoryId

Critère de validation : après ~50 messages, le compacting se déclenche automatiquement. Le résumé apparaît en contexte. Les mémoires sont extraites. La purge et le rollback fonctionnent.

Phase 14 — Vault (secrets)

Gestion des secrets chiffrés et caviardage.

14.1 Créer src/server/services/vault.ts — CRUD secrets, chiffrement/déchiffrement AES-256-GCM, redact_message
14.2 Créer src/server/tools/vault-tools.ts — get_secret, redact_message
14.3 Créer les routes :
- src/server/routes/vault.ts — GET /api/vault, POST /api/vault, PATCH /api/vault/:id, DELETE /api/vault/:id
14.4 Implémenter la priorité du caviardage sur le compacting (bloquer le compacting si redact_pending = 1)

Critère de validation : on peut créer un secret, le Kin peut le lire via get_secret, et le caviardage fonctionne (le message est masqué et bloque le compacting).

Phase 15 — Tâches (sous-Kins)

Spawning, cycle de vie, request_input, résolution.

15.1 Créer src/server/services/tasks.ts — cycle de vie complet :
- Spawn (clone de soi-même ou d'un autre Kin)
- Modes await et async
- Gestion de la profondeur (depth, max configurable)
- Résolution : completed, failed, cancelled
- Restitution dans la session parente (via queue pour await, informatif pour async)
15.2 Créer src/server/tools/task-tools.ts — outils parent : spawn_self, spawn_kin, respond_to_task, cancel_task, list_tasks
15.3 Créer src/server/tools/subtask-tools.ts — outils sous-Kin : report_to_parent, update_task_status, request_input (max 3 appels)
15.4 Adapter kin-engine.ts pour exécuter un sous-Kin (prompt adapté, outils limités, contexte de tâche)
15.5 Créer les routes :
- src/server/routes/tasks.ts — GET /api/tasks, GET /api/tasks/:id, POST /api/tasks/:id/cancel
15.6 Émettre les événements SSE : task:status, task:done
15.7 Frontend : mettre à jour TaskList.tsx dans la sidebar avec les tâches en cours et leur statut

Critère de validation : un Kin peut spawner un sous-Kin, le sous-Kin exécute sa tâche, le résultat revient dans la session parente. Le mode await et async fonctionnent. request_input est limité à 3.

Phase 16 — Communication inter-Kins

Messagerie directe entre Kins avec garde-fous.

16.1 Créer src/server/services/inter-kin.ts — send_message, reply, corrélation request_id, rate limiting, compteur de profondeur
16.2 Créer src/server/tools/inter-kin-tools.ts — send_message, reply, list_kins
16.3 Intégrer les messages inter-Kins dans la queue FIFO (type kin_request, kin_inform, kin_reply)
16.4 Garantir que les reply sont toujours de type inform (pas de ping-pong)

Critère de validation : un Kin peut envoyer un request à un autre Kin, celui-ci répond via reply, et la réponse est corrélée au request original. Le rate limiting bloque les abus.

Phase 17 — Crons (tâches planifiées)

Scheduler in-process avec croner.

17.1 Créer src/server/services/crons.ts — scheduler croner, spawn de sous-Kin à chaque déclenchement, respect des limites (maxActive, maxConcurrentExecutions)
17.2 Créer src/server/tools/cron-tools.ts — create_cron, update_cron, delete_cron, list_crons
17.3 Créer les routes :
- src/server/routes/crons.ts — GET /api/crons, POST /api/crons, PATCH /api/crons/:id, DELETE /api/crons/:id, POST /api/crons/:id/approve
17.4 Logique d'approbation : un cron créé par un Kin nécessite une validation utilisateur (requires_approval)
17.5 Restitution du résultat : déposé dans la session comme message informatif (pas de tour LLM)
17.6 Émettre l'événement SSE cron:triggered

Critère de validation : un cron s'exécute à l'heure prévue, spawn un sous-Kin, et le résultat apparaît dans le chat. Un cron créé par un Kin attend l'approbation.

Phase 18 — MCP Servers

Gestion des serveurs MCP et exposition des outils aux Kins.

18.1 Créer les routes :
- src/server/routes/mcp-servers.ts — GET /api/mcp-servers, POST /api/mcp-servers, DELETE /api/mcp-servers/:id
18.2 Implémenter le lancement des processus MCP, la découverte des outils exposés, et leur injection dans le tool calling du Kin
18.3 Gérer la liaison Kin ↔ MCP servers (table kin_mcp_servers)

Critère de validation : on peut configurer un serveur MCP, l'assigner à un Kin, et le Kin peut utiliser les outils exposés par le serveur.

Phase 19 — Outils custom (auto-générés)

Permettre aux Kins de créer et gérer leurs propres outils.

19.1 Créer src/server/tools/custom-tool-tools.ts — register_tool, run_custom_tool, list_custom_tools
19.2 Implémenter l'exécution confinée au workspace du Kin (validation du path)
19.3 Injecter les outils custom dans les tool definitions du Kin

Critère de validation : un Kin peut créer un script dans son workspace, l'enregistrer comme outil, et l'exécuter via run_custom_tool.

Phase 20 — Upload de fichiers

20.1 Créer src/server/services/files.ts — upload, stockage local, référencement en DB
20.2 Créer les routes :
- src/server/routes/files.ts — POST /api/files/upload
20.3 Intégrer les fichiers dans les messages (référencement dans la table files, inclusion dans le contexte LLM)
20.4 Frontend : intégrer l'upload dans MessageInput.tsx (drag & drop, bouton d'ajout)

Critère de validation : un utilisateur peut envoyer un fichier avec son message. Le fichier est stocké et visible dans l'historique.

Phase 21 — Génération d'images

21.1 Créer src/server/tools/image-tools.ts — generate_image (via provider image)
21.2 Conditionner la disponibilité de l'outil à la présence d'un provider avec capacité image

Critère de validation : si un provider image est configuré, le Kin peut générer des images. Sinon, l'outil n'est pas disponible.

Phase 22 — Internationalisation

22.1 Compléter src/client/locales/en.json et fr.json avec toutes les clés de l'interface
22.2 Configurer src/client/lib/i18n.ts — détection de la langue à partir de user_profiles.language
22.3 Remplacer tous les textes en dur dans les composants React par des appels t('key')

Critère de validation : l'interface affiche correctement en français et en anglais selon la préférence utilisateur. Le changement de langue est immédiat.

Phase 23 — Dark mode

23.1 Implémenter le thème sombre dans globals.css (custom properties CSS)
23.2 S'assurer que tous les composants shadcn/ui et custom respectent les variables de thème
23.3 Ajouter un toggle dark mode (ou suivre la préférence système)

Critère de validation : le dark mode fonctionne sur toute l'interface avec des tons sombres chauds.

Phase 24 — Polissage et tests

24.1 Gestion des erreurs LLM : retry sur rate limit, messages d'erreur dans le chat, warning dans la sidebar
24.2 Limites de concurrence : vérifier tasks.maxConcurrent et crons.maxConcurrentExecutions
24.3 Vérifier que la suppression d'un provider bloquée si c'est le dernier couvrant une capacité requise (PROVIDER_REQUIRED)
24.4 Vérifier les garde-fous inter-Kins (rate limiting, profondeur max)
24.5 Vérifier que la profondeur de spawning est respectée
24.6 Responsive : s'assurer que la sidebar est utilisable sur tablette
24.7 Performance : vérifier que le compacting et les embeddings ne bloquent pas le thread principal
24.8 Sécurité : auditer les routes (injection SQL via Drizzle, XSS dans les messages, path traversal dans les workspaces)

Critère de validation : l'application est stable, les cas limites sont gérés, les performances sont acceptables.

Phase 25 — Docker et déploiement

25.1 Finaliser le Dockerfile (build multi-stage : Vite build + Bun runtime)
25.2 Finaliser le docker-compose.yml (volume pour data/, env vars)
25.3 Tester le déploiement complet via docker run
25.4 Vérifier que les extensions SQLite (sqlite-vec, FTS5) fonctionnent dans le conteneur
25.5 Générer automatiquement ENCRYPTION_KEY si absente au premier lancement

Critère de validation : docker run -v ./data:/app/data -p 3000:3000 kinbot lance l'application complète, fonctionnelle et persistante.

Résumé des dépendances entre phases

Phase 0 (Init)
  ├── Phase 0.5 (Design system) ← VALIDATION VISUELLE REQUISE
  │     │                          Le backend peut avancer en parallèle,
  │     │                          mais le frontend réel est bloqué.
  │     │
  └── Phase 1 (DB)
        └── Phase 2 (Auth)
              ├── Phase 3 (Onboarding) ← nécessite Phase 0.5 validée
              └── Phase 4 (Providers)
                    └── Phase 5 (Event bus)
                    └── Phase 6 (SSE)
                          └── Phase 7 (CRUD Kins) ← nécessite Phase 0.5 validée
                                └── Phase 8 (Layout) ← nécessite Phase 0.5 validée
                                └── Phase 9 (Queue + Engine) ← COEUR
                                      └── Phase 10 (Tool calling)
                                            ├── Phase 11 (Contacts)
                                            ├── Phase 12 (Mémoire)
                                            │     └── Phase 13 (Compacting)
                                            ├── Phase 14 (Vault)
                                            ├── Phase 15 (Tâches)
                                            │     └── Phase 16 (Inter-Kins)
                                            │     └── Phase 17 (Crons)
                                            ├── Phase 18 (MCP)
                                            ├── Phase 19 (Custom tools)
                                            ├── Phase 20 (Files)
                                            ├── Phase 21 (Images)
                                            └── (Search tools — Phase 10.5, requires Phase 4.6b)
Phase 22 (i18n) — peut commencer dès Phase 8
Phase 23 (Dark mode) — déjà couvert par Phase 0.5 (tokens + toggle), compléter si besoin
Phase 24 (Polish) — après toutes les phases fonctionnelles
Phase 25 (Docker) — en parallèle dès Phase 9

Notes pour l'agent développeur

Lire la documentation : avant de commencer chaque phase, relire le fichier de spec correspondant (idea.md, schema.md, api.md, config.md, structure.md, prompt-system.md, compacting.md)
Conventions : respecter strictement les conventions de nommage et d'imports décrites dans structure.md
Tests manuels : à la fin de chaque phase, valider le critère de validation avant de passer à la suivante
Commits : un commit par sous-tâche terminée, avec un message clair
Ne pas anticiper : ne pas implémenter de fonctionnalités des phases futures. Chaque phase doit être minimale et suffisante
Erreurs : suivre le format standard { "error": { "code": "...", "message": "..." } } pour toutes les routes API
Types partagés : tout type utilisé à la fois côté client et serveur doit être dans src/shared/types.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

KinBot — Plan de développement

Phase 0 — Initialisation du projet

Phase 0.5 — Design system et validation visuelle

Phase 1 — Base de données et schéma

Phase 2 — Authentification et gestion des utilisateurs

Phase 3 — Onboarding

Phase 4 — Providers IA

Phase 5 — Event bus et hooks

Phase 6 — SSE (Server-Sent Events)

Phase 7 — CRUD Kins (sans moteur LLM)

Phase 8 — Interface principale (layout)

Phase 9 — Queue FIFO et moteur Kin (coeur du système)

Phase 10 — Outils natifs de base (Tool calling)

Phase 11 — Contacts

Phase 12 — Mémoire long terme

Phase 13 — Compacting

Phase 14 — Vault (secrets)

Phase 15 — Tâches (sous-Kins)

Phase 16 — Communication inter-Kins

Phase 17 — Crons (tâches planifiées)

Phase 18 — MCP Servers

Phase 19 — Outils custom (auto-générés)

Phase 20 — Upload de fichiers

Phase 21 — Génération d'images

Phase 22 — Internationalisation

Phase 23 — Dark mode

Phase 24 — Polissage et tests

Phase 25 — Docker et déploiement

Résumé des dépendances entre phases

Notes pour l'agent développeur

FilesExpand file tree

DEVELOPMENT_PLAN.md

Latest commit

History

DEVELOPMENT_PLAN.md

File metadata and controls

KinBot — Plan de développement

Phase 0 — Initialisation du projet

Phase 0.5 — Design system et validation visuelle

Phase 1 — Base de données et schéma

Phase 2 — Authentification et gestion des utilisateurs

Phase 3 — Onboarding

Phase 4 — Providers IA

Phase 5 — Event bus et hooks

Phase 6 — SSE (Server-Sent Events)

Phase 7 — CRUD Kins (sans moteur LLM)

Phase 8 — Interface principale (layout)

Phase 9 — Queue FIFO et moteur Kin (coeur du système)

Phase 10 — Outils natifs de base (Tool calling)

Phase 11 — Contacts

Phase 12 — Mémoire long terme

Phase 13 — Compacting

Phase 14 — Vault (secrets)

Phase 15 — Tâches (sous-Kins)

Phase 16 — Communication inter-Kins

Phase 17 — Crons (tâches planifiées)

Phase 18 — MCP Servers

Phase 19 — Outils custom (auto-générés)

Phase 20 — Upload de fichiers

Phase 21 — Génération d'images

Phase 22 — Internationalisation

Phase 23 — Dark mode

Phase 24 — Polissage et tests

Phase 25 — Docker et déploiement

Résumé des dépendances entre phases

Notes pour l'agent développeur