Spazi di lavoro

Uno spazio di lavoro è una cartella che Guida apre per organizzare il tuo progetto di automazione. Aprire uno spazio di lavoro abilita l’archiviazione persistente (g.store), le code di lavoro (g.queue), la ricerca testuale (g.search), i generazione di eventi e gli strumenti MCP personalizzati.

Aprire uno spazio di lavoro

Usa File > Apri spazio di lavoro (File > Open Workspace) o il pulsante nella barra degli strumenti per selezionare una cartella. Guida crea la struttura predefinita se non esiste.

Struttura delle cartelle

my-workspace/
├── scripts/          # I tuoi script di automazione (*.js, *.lua, *.janet)
├── lib/              # Librerie condivise per JS, Lua e Janet
├── views/            # Configurazioni delle viste di coda
├── events.json       # Configurazione dei generazione di eventi
├── tools.json        # Definizioni degli strumenti MCP personalizzati
├── queues.json       # Definizioni dei pool di processi di lavoro
├── domains.json      # Elenco dei domini autorizzati per MCP
├── workflows/        # Pipeline di automazione nominate (opzionale)
├── store.db          # Archiviazione persistente (creata automaticamente)
├── queue.db          # Dati delle code di lavoro (creato automaticamente)
├── workflow-ledger.db # Cronologia di esecuzioni/elementi dei flussi di lavoro (creato automaticamente)
└── search-index/     # Indice di ricerca testuale (creato automaticamente)

Il pannello Spazio di lavoro (Workspace) di Guida elenca automaticamente tutti i file .js, .lua e .janet trovati nelle cartelle scripts/, lib/ e nei flussi di lavoro. Quando crei un nuovo file, usa l’estensione del motore che vuoi usare.

File database

Questi file vengono creati automaticamente al primo uso dell’API corrispondente:

store.db — database LiteDB per le operazioni g.store.*. I documenti sono organizzati in raccolte nominate.
queue.db — database SQLite per le operazioni g.queue.* basate su StratQueue. Supporta code con priorità, strategie di estrazione personalizzate, lavoro estratto e code degli scarti.
workflow-ledger.db — database SQLite per esecuzioni, elementi, eventi, risultati collegati, prese in carico, tentativi e cronologia di ripristino dei flussi di lavoro.
search-index/ — cartella dell’indice Lucene.NET per le operazioni g.search.*.

Tutti i dati sono locali allo spazio di lavoro e viaggiano insieme alla cartella.

Usa File > Backup dello spazio di lavoro… (File > Backup Workspace...) per creare un archivio con timestamp dell’intero spazio di lavoro, oppure File > Backup dei file operativi dello spazio di lavoro… (File > Backup Managed Workspace Files...) per archiviare solo i dati operativi creati da Guida, come store.db, istantanee di code e registro, e search-index/. Vedi Backup dello spazio di lavoro.

File di configurazione

`events.json` — Generazione di eventi

Esegui automaticamente script quando si verificano eventi del browser:

{
  "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"
    }
  ]
}

Tipi di generazione di eventi:

Evento	Pattern	Scatta quando
`url-match`	Pattern glob (`*` = qualsiasi carattere)	La navigazione termina su un URL corrispondente
`page-loaded`	—	Una pagina termina il caricamento
`tab-created`	—	Viene creata una nuova scheda
`tab-closed`	—	Una scheda viene chiusa
`tab-activated`	—	Una scheda diventa attiva
`dom-mutation`	Selettori CSS	Un elemento DOM osservato cambia (testo, attributi o figli)
`external-queue`	—	Uno script di interrogazione periodica restituisce dati (intervallo configurabile)

Se lo stesso script è già in esecuzione, non viene attivato di nuovo.

dom-mutation — osservazione reattiva del DOM tramite MutationObserver. Ideale per dati in tempo reale come prezzi di azioni, quote di scommessa o metriche di dashboard:

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

selector — selettore CSS da osservare (o selectors per un array di selettori)
attributes — elenco opzionale di nomi di attributi specifici da osservare
debounce — millisecondi di debounce per elemento (predefinito: 0)
strategy — strategia di gestione della pressione: "exhaust" (predefinita: salta se lo script è in esecuzione), "buffer" (accumula le modifiche in un array), "sample" (mantiene solo la modifica più recente)

external-queue — interroga una sorgente dati esterna a intervallo configurabile:

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

Lo script source viene eseguito a ogni interrogazione periodica: restituisce dati se c’è lavoro disponibile, oppure null se non c’è nulla da elaborare. Quando vengono restituiti dati, viene eseguito il gestore script, che può accedervi tramite g.trigger.getContext().

Contesto del generatore di eventi — tutti gli script lanciati da generatori di eventi possono chiamare g.trigger.getContext() per accedere ai metadati dell’evento (tipo di evento, ID scheda, URL, timestamp e campi specifici del generatore di eventi, come i dettagli della mutazione).

`tools.json` — Strumenti MCP personalizzati

Definisci strumenti che agenti IA esterni possono invocare. Vedi Strumenti personalizzati.

`queues.json` — Pool di processi di lavoro

Definisci pool dichiarativi di processi di lavoro per l’elaborazione in blocco. Vedi Processi di lavoro delle code.

`domains.json` — Elenco dei domini autorizzati

Controlla verso quali domini può navigare il server MCP. Vedi Integrazione MCP.

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

Servizi legati allo spazio di lavoro

Queste API richiedono uno spazio di lavoro aperto e restituiscono un errore in caso contrario:

API	Descrizione
`g.store.*`	Archiviazione persistente di documenti
`g.queue.*`	Code di lavoro transazionali
`g.search.*`	Indice di ricerca testuale
`g.workers.*`	Pool di processi di lavoro delle code
`g.workflows.*`	Ispezione e cambio dei flussi di lavoro

Le API principali come g.dom.click, g.nav.navigateToUrl e g.tabs.getTabs funzionano anche senza uno spazio di lavoro.

Passi successivi

Scripting: una panoramica — impara l’API g.*
Estrarre e salvare dati da una pagina — usa l’archiviazione locale allo spazio di lavoro in uno script di estrazione reale
Mettere URL in coda ed elaborarli — usa le code dello spazio di lavoro per automazione del browser in blocco
Flussi di lavoro — organizza più flussi di automazione in un unico spazio di lavoro
Backup dello spazio di lavoro — archivia in sicurezza spazi di lavoro completi o i file operativi di Guida
Strumenti personalizzati — esponi script dello spazio di lavoro agli agenti IA tramite MCP
Processi di lavoro delle code — elaborazione in blocco con schede del browser concorrenti