Espaces de travail

Un espace de travail est un dossier que Guida ouvre pour organiser votre projet d’automatisation. Ouvrir un espace de travail active le stockage persistant (g.store), les files de travail (g.queue), la recherche plein texte (g.search), les déclencheurs d’événements et les outils MCP personnalisés.

Ouvrir un espace de travail

Utilisez File > Open Workspace ou le bouton de la barre d’outils pour sélectionner un dossier. Guida crée la structure par défaut si elle n’existe pas.

Structure des dossiers

my-workspace/
├── scripts/          # Vos scripts d'automatisation (*.js, *.lua, *.janet)
├── lib/              # Bibliothèques partagées pour JS, Lua et Janet
├── views/            # Configurations des vues de files d'attente
├── events.json       # Configuration des déclencheurs d'événements
├── tools.json        # Définitions des outils MCP personnalisés
├── queues.json       # Définitions des pools de processus de travail
├── domains.json      # Liste de domaines autorisés pour MCP
├── workflows/        # Pipelines d'automatisation nommés (facultatif)
├── store.db          # Stockage persistant (créé automatiquement)
├── queue.db          # Données des files de travail (créé automatiquement)
├── workflow-ledger.db # Historique exécutions/éléments des flux de travail (créé automatiquement)
└── search-index/     # Index de recherche plein texte (créé automatiquement)

Le panneau Workspace de Guida liste automatiquement tous les fichiers .js, .lua et .janet trouvés dans les dossiers scripts/, lib/ et dans les dossiers de flux de travail. Lorsque vous créez un nouveau fichier, utilisez l’extension du moteur que vous voulez utiliser.

Fichiers de base de données

Ces fichiers sont créés automatiquement lors de la première utilisation de l’API correspondante :

store.db — base LiteDB pour les opérations g.store.*. Les documents sont organisés en collections nommées.
queue.db — base SQLite pour les opérations g.queue.* appuyées par StratQueue. Prend en charge les files avec priorité, les stratégies d’extraction personnalisées, le travail pris en charge et les files des rejets.
workflow-ledger.db — base SQLite pour les exécutions de flux de travail, les éléments, événements, résultats liés, prises en charge, tentatives et historiques de reprise.
search-index/ — dossier d’index Lucene.NET pour les opérations g.search.*.

Toutes les données sont locales à l’espace de travail et se déplacent avec le dossier.

Utilisez File > Backup Workspace… pour créer une archive horodatée de tout l’espace de travail, ou File > Backup Managed Workspace Files… pour archiver uniquement les données opérationnelles créées par Guida, comme store.db, les instantanés des files et du registre, et search-index/. Voir Sauvegardes de l’espace de travail.

Fichiers de configuration

`events.json` — Déclencheurs d’événements

Exécutez automatiquement des scripts lorsque des événements du navigateur se produisent :

{
  "triggers": [
    {
      "event": "url-match",
      "pattern": "https://example.com/products/*",
      "script": "scripts/extract-product.js"
    },
    {
      "event": "page-loaded",
      "script": "scripts/inject-styles.js"
    },
    {
      "event": "tab-created",
      "script": "scripts/setup-tab.js"
    }
  ]
}

Types de déclencheurs :

Événement	Motif	Se déclenche quand
`url-match`	Motif glob (`*` = n’importe quels caractères)	La navigation se termine sur une URL correspondante
`page-loaded`	—	Une page termine son chargement
`tab-created`	—	Un nouvel onglet est créé
`tab-closed`	—	Un onglet est fermé
`tab-activated`	—	Un onglet devient actif
`dom-mutation`	Sélecteur(s) CSS	Un élément DOM observé change (texte, attributs ou enfants)
`external-queue`	—	Un script d’interrogation renvoie des données (intervalle configurable)

Si le même script est déjà en cours d’exécution, il ne sera pas déclenché à nouveau.

dom-mutation — observation réactive du DOM avec MutationObserver. Idéal pour des données en direct comme les prix d’actions, les cotes de paris ou les métriques de tableau de bord :

{
  "event": "dom-mutation",
  "selector": ".price-display",
  "script": "scripts/on-price-change.js",
  "debounce": 1000,
  "strategy": "exhaust"
}

selector — sélecteur CSS à observer (ou selectors pour un tableau de sélecteurs)
attributes — liste facultative de noms d’attributs précis à observer
debounce — millisecondes de debounce par élément (valeur par défaut : 0)
strategy — stratégie de gestion de la pression : "exhaust" (par défaut, ignorer si le script est en cours), "buffer" (collecter les changements dans un tableau), "sample" (ne garder que le dernier changement)

external-queue — interroge une source de données externe à intervalle configurable :

{
  "event": "external-queue",
  "source": "scripts/poll-api.js",
  "script": "scripts/handle-item.js",
  "interval": 30
}

Le script source s’exécute à chaque interrogation : il renvoie des données si du travail est disponible, ou null si rien n’est à traiter. Lorsque des données sont renvoyées, le gestionnaire script s’exécute et peut y accéder via g.trigger.getContext().

Contexte du déclencheur — tous les scripts déclenchés peuvent appeler g.trigger.getContext() pour accéder aux métadonnées de l’événement (type d’événement, ID d’onglet, URL, horodatage et champs propres au déclencheur, comme les détails de mutation).

`tools.json` — Outils MCP personnalisés

Définissez les outils que des agents IA externes peuvent invoquer. Voir Outils personnalisés.

`queues.json` — Pools de processus de travail

Définissez des pools déclaratifs de processus de travail pour le traitement par lot. Voir Processus de travail des files d’attente.

`domains.json` — Liste de domaines autorisés

Contrôlez vers quels domaines le serveur MCP peut naviguer. Voir Intégration MCP.

{
  "allowedDomains": [
    "example.com",
    "*.example.com",
    "trusted-site.org"
  ]
}

Services liés à l’espace de travail

Ces API nécessitent un espace de travail ouvert et renvoient une erreur sinon :

API	Description
`g.store.*`	Stockage persistant de documents
`g.queue.*`	Files de travail transactionnelles
`g.search.*`	Index de recherche plein texte
`g.workers.*`	Pools de processus de travail des files d’attente
`g.workflows.*`	Inspection et changement des flux de travail

Les API principales comme g.dom.click, g.nav.navigateToUrl et g.tabs.getTabs fonctionnent même sans espace de travail.

Étapes suivantes

Vue d’ensemble du scripting — apprendre l’API g.*
Extraire et stocker les données d’une page — utiliser le stockage local à l’espace de travail dans un vrai script d’extraction
Mettre des URL en file d’attente et les traiter — utiliser les files de l’espace de travail pour l’automatisation du navigateur par lot
Flux de travail — organiser plusieurs pipelines d’automatisation dans un seul espace de travail
Sauvegardes de l’espace de travail — archiver en sécurité des espaces de travail complets ou les données opérationnelles de Guida
Outils personnalisés — exposer des scripts de l’espace de travail aux agents IA via MCP
Processus de travail des files d’attente — traitement par lot avec des onglets de navigateur concurrents