Espacios de trabajo

Un espacio de trabajo es una carpeta que Guida abre para organizar su proyecto de automatización. Abrir un espacio de trabajo habilita almacenamiento persistente (g.store), colas de trabajo (g.queue), búsqueda de texto completo (g.search), disparadores de eventos y herramientas MCP personalizadas.

Abrir un espacio de trabajo

Use File > Open Workspace o el botón de la barra de herramientas para seleccionar una carpeta. Guida creará la estructura predeterminada si no existe.

Estructura de carpetas

my-workspace/
├── scripts/          # Your automation scripts (*.js, *.lua, *.janet)
├── lib/              # Shared libraries for JS, Lua, and Janet
├── views/            # Queue view configurations
├── events.json       # Event trigger config
├── tools.json        # Custom MCP tool definitions
├── queues.json       # Worker pool definitions
├── domains.json      # Dominios autorizados para MCP
├── workflows/        # Named automation pipelines (optional)
├── store.db          # Persistent storage (auto-created)
├── queue.db          # Work queue data (auto-created)
├── workflow-ledger.db # Workflow run/item history (auto-created)
└── search-index/     # Full-text search index (auto-created)

El panel Workspace de Guida lista automáticamente todos los archivos .js, .lua y .janet encontrados en scripts/, lib/ y las carpetas de flujo de trabajo. Al crear un archivo nuevo, use la extensión del motor que quiere usar.

Archivos de base de datos

Se crean automáticamente la primera vez que usa la API correspondiente:

• store.db — base LiteDB para operaciones g.store.*. Los documentos se organizan en colecciones con nombre.
• queue.db — base SQLite para operaciones g.queue.* respaldadas por StratQueue. Admite colas con prioridad, estrategias de extracción personalizadas, trabajo tomado y colas de rechazos.
• workflow-ledger.db — base SQLite para ejecuciones de flujos de trabajo, elementos, eventos, resultados vinculados, reservas, reintentos e historial de recuperación.
• search-index/ — directorio de índice Lucene.NET para operaciones g.search.*.

Todos los datos son locales al espacio de trabajo y viajan con la carpeta.

Use File > Backup Workspace… para crear un archivo con marca temporal de todo el espacio de trabajo, o File > Backup Managed Workspace Files… para archivar solo los datos operativos de Guida, como store.db, instantáneas de colas/registro y search-index/. Vea Copias de seguridad del espacio de trabajo.

Archivos de configuración

events.json — disparadores de eventos

Ejecute scripts automáticamente cuando ocurran eventos del navegador:

{
  "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 disparador:

Evento	Patrón	Se dispara cuando
url-match	Patrón glob (* = cualquier carácter)	La navegación termina en una URL coincidente
page-loaded	—	Cualquier página termina de cargar
tab-created	—	Se crea una pestaña nueva
tab-closed	—	Se cierra una pestaña
tab-activated	—	Una pestaña pasa a estar activa
dom-mutation	Selectores CSS	Un elemento DOM observado cambia en texto, atributos o hijos
external-queue	—	Un script de sondeo devuelve datos con intervalo configurable

Si el mismo script ya está ejecutándose, no se vuelve a disparar.

dom-mutation — observación DOM reactiva con MutationObserver. Ideal para datos en vivo como precios de acciones, cuotas de apuestas o métricas de panel:

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

• selector — selector CSS que observar, o selectors para un array de selectores
• attributes — lista opcional de nombres de atributo específicos que observar
• debounce — milisegundos de debounce por elemento; predeterminado 0
• strategy — estrategia de contrapresión: "exhaust" predeterminada, omite si el script está en ejecución; "buffer" reúne cambios en un array; "sample" conserva solo el cambio más reciente

external-queue — sondee una fuente de datos externa con intervalo configurable:

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

El script source se ejecuta en cada sondeo: devuelve datos si hay trabajo disponible, o null si no hay nada. Cuando devuelve datos, se ejecuta el manejador script y puede acceder a ellos mediante g.trigger.getContext().

Contexto de disparador — todos los scripts disparados pueden llamar a g.trigger.getContext() para acceder a metadatos del evento: tipo, ID de pestaña, URL, marca temporal y campos específicos como detalles de mutación.

tools.json — herramientas MCP personalizadas

Defina herramientas que agentes externos de IA pueden invocar. Vea Herramientas personalizadas.

queues.json — pools de procesos de trabajo

Defina pools declarativos de procesos de trabajo para procesamiento por lotes. Vea Procesos de trabajo de cola.

domains.json — dominios autorizados

Controle a qué dominios puede navegar el servidor MCP. Vea Integración MCP.

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

Servicios limitados al espacio de trabajo

Estas API requieren un espacio de trabajo abierto y devuelven error en caso contrario:

API	Descripción
g.store.*	Almacenamiento persistente de documentos
g.queue.*	Colas de trabajo transaccionales
g.search.*	Índice de búsqueda de texto completo
g.workers.*	Pools de procesos de trabajo de cola
g.workflows.*	Inspección y cambio de flujos de trabajo

Las API centrales como g.dom.click, g.nav.navigateToUrl y g.tabs.getTabs funcionan sin espacio de trabajo.

Siguientes pasos

• Visión general del scripting — aprender la API g.*
• Extraer y almacenar datos de una página — usar almacenamiento local al espacio de trabajo en un script real de extracción
• Poner URL en cola y procesarlas — usar colas del espacio de trabajo para automatización por lotes del navegador
• Flujos de trabajo — organizar múltiples canalizaciones de automatización en un espacio de trabajo
• Copias de seguridad del espacio de trabajo — archivar de forma segura espacios completos o datos operativos de Guida
• Herramientas personalizadas — exponer scripts del espacio de trabajo a agentes de IA mediante MCP
• Procesos de trabajo de cola — procesamiento por lotes con pestañas de navegador concurrentes