Espaços de trabalho

Um espaço de trabalho é uma pasta que o Guida abre para organizar seu projeto de automação. Abrir um espaço de trabalho libera armazenamento persistente (g.store), filas de trabalho (g.queue), pesquisa de texto completo (g.search), gatilhos de eventos e ferramentas MCP personalizadas.

Abrir um espaço de trabalho

Use File > Open Workspace ou o botão da barra de ferramentas para selecionar uma pasta. O Guida cria a estrutura padrão se ela ainda não existir.

Estrutura de pastas

my-workspace/
├── scripts/          # Seus scripts de automação (*.js, *.lua, *.janet)
├── lib/              # Bibliotecas compartilhadas para JS, Lua e Janet
├── views/            # Configurações de visão de fila
├── events.json       # Configuração de gatilhos de evento
├── tools.json        # Definições de ferramentas MCP personalizadas
├── queues.json       # Definições de grupos de processos de trabalho
├── domains.json      # Lista de domínios permitidos para MCP
├── workflows/        # Fluxos de automação nomeados (opcional)
├── store.db          # Armazenamento persistente (criado automaticamente)
├── queue.db          # Dados de fila de trabalho (criado automaticamente)
├── workflow-ledger.db # Histórico de execuções/itens de fluxo (criado automaticamente)
└── search-index/     # Índice de pesquisa de texto completo (criado automaticamente)

O painel Workspace do Guida lista automaticamente todos os arquivos .js, .lua e .janet encontrados em scripts/, lib/ e pastas de fluxo de trabalho. Ao criar um novo arquivo, use a extensão do mecanismo desejado.

Arquivos de banco de dados

Eles são criados automaticamente na primeira vez que você usa a API correspondente:

store.db — banco LiteDB para operações g.store.*. Documentos ficam organizados em coleções nomeadas.
queue.db — banco SQLite para operações g.queue.* baseadas em StratQueue. Suporta filas com prioridade, estratégias de retirada personalizadas, trabalho retirado e filas de rejeitos.
workflow-ledger.db — banco SQLite para execuções, itens, eventos, saídas vinculadas, reservas de execução, novas tentativas e histórico de recuperação de fluxos de trabalho.
search-index/ — diretório de índice Lucene.NET para operações g.search.*.

Todos os dados são locais ao espaço de trabalho e viajam com a pasta.

Use File > Backup Workspace… para criar um arquivo com timestamp de todo o espaço de trabalho, ou File > Backup Managed Workspace Files… para arquivar apenas dados gerenciados pelo Guida, como store.db, instantâneos de fila/registro e search-index/. Veja Cópias de segurança do espaço de trabalho.

Arquivos de configuração

`events.json` — gatilhos de evento

Execute scripts automaticamente quando eventos do navegador ocorrerem:

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

Tipos de gatilho:

Evento	Padrão	Dispara quando
`url-match`	Padrão glob (`*` = quaisquer caracteres)	A navegação conclui em uma URL correspondente
`page-loaded`	—	Qualquer página termina de carregar
`tab-created`	—	Uma nova guia é criada
`tab-closed`	—	Uma guia é fechada
`tab-activated`	—	Uma guia se torna ativa
`dom-mutation`	Seletor(es) CSS	Um elemento DOM observado muda (texto, atributos ou filhos)
`external-queue`	—	Um script de polling retorna dados em intervalo configurável

Se o mesmo script já estiver rodando, ele não será disparado novamente.

dom-mutation — observação reativa do DOM com MutationObserver. Ideal para dados vivos como preços de ações, odds de apostas ou métricas de painel:

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

selector — seletor CSS a observar, ou selectors para um array de seletores
attributes — lista opcional de nomes de atributos específicos a observar
debounce — milissegundos de debounce por elemento (padrão: 0)
strategy — estratégia de backpressure: "exhaust" (padrão, ignora se o script estiver rodando), "buffer" (coleta mudanças em array), "sample" (mantém apenas a última mudança)

external-queue — consulta uma fonte de dados externa em intervalo configurável:

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

O script source roda em cada polling: retorne dados se houver trabalho disponível ou null se estiver vazio. Quando há dados, o script handler roda e pode acessá-los via g.trigger.getContext().

Contexto de gatilho — todos os scripts de gatilho podem chamar g.trigger.getContext() para acessar metadados do evento (tipo, ID da guia, URL, timestamp e campos específicos, como detalhes de mutação).

`tools.json` — ferramentas MCP personalizadas

Defina ferramentas que agentes de IA externos podem invocar. Veja Ferramentas personalizadas.

`queues.json` — grupos de processos de trabalho

Defina grupos declarativos de processos de trabalho para processamento em lote. Veja Processos de trabalho das filas.

`domains.json` — lista de domínios permitidos

Controle para quais domínios o servidor MCP pode navegar. Veja Integração MCP.

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

Serviços com escopo de espaço de trabalho

Estas APIs exigem um espaço de trabalho aberto e retornam erro caso contrário:

API	Descrição
`g.store.*`	Armazenamento persistente de documentos
`g.queue.*`	Filas transacionais de trabalho
`g.search.*`	Índice de pesquisa de texto completo
`g.workers.*`	Grupos de processos de trabalho das filas
`g.workflows.*`	Inspeção e troca de fluxos de trabalho

APIs centrais como g.dom.click, g.nav.navigateToUrl e g.tabs.getTabs funcionam sem um espaço de trabalho.

Próximos passos

Visão geral da automação por scripts — aprenda a API g.*
Extrair e armazenar dados de página — use armazenamento local ao espaço de trabalho em um script real de extração
Enfileirar URLs e processá-las — use filas do espaço de trabalho para automação de navegador em lote
Fluxos de trabalho — organize vários fluxos de automação em um espaço de trabalho
Cópias de segurança do espaço de trabalho — arquive espaços de trabalho completos ou dados gerenciados pelo Guida com segurança
Ferramentas personalizadas — exponha scripts do espaço de trabalho a agentes de IA via MCP
Processos de trabalho das filas — processamento em lote com guias de navegador concorrentes