Volver a la wiki

Tabla D1 `bib_tours` — Cache de tours pedagógicos del Bibliotecario

Tabla D1 bib_tours

Creada en migration 0034_bib_tours.sql · s79 (22-05-2026, PR#60).

Almacena los tours pedagógicos generados por bib_generate_tour. Actúa como cache con TTL de 24 horas: si existe un tour vigente para (app, focus), se devuelve directamente sin invocar Haiku (coste $0).

Schema

CREATE TABLE bib_tours (
  id             INTEGER PRIMARY KEY AUTOINCREMENT,
  app            TEXT NOT NULL,
  focus          TEXT,                             -- NULL = tour general
  title          TEXT NOT NULL,
  summary        TEXT,
  steps_json     TEXT NOT NULL,                    -- JSON array de pasos
  step_count     INTEGER DEFAULT 0,
  cost_usd       REAL DEFAULT 0,
  input_tokens   INTEGER DEFAULT 0,
  output_tokens  INTEGER DEFAULT 0,
  created_at     TEXT DEFAULT (datetime('now')),
  expires_at     TEXT DEFAULT (datetime('now', '+24 hours'))
);

(Schema exacto en migrations/0034_bib_tours.sql — diff truncado en el PR; confirmado por descripción y handler.)

Estructura de steps_json

Array de objetos con el siguiente shape:

interface TourStep {
  order: number;           // 1-based, orden topológico
  title: string;           // Máx 80 chars, castellano técnico
  description: string;     // Explicación del paso
  node_qnames: string[];   // 1-3 qualified_names del grafo
  why_now: string;         // Justificación del orden (1 frase)
}

Lógica de cache

  1. bib_generate_tour(app, focus, use_cache=true) busca en bib_tours un registro con app = ? AND COALESCE(focus,'') = COALESCE(?,'') AND expires_at > datetime('now').
  2. Cache hit: devuelve el tour con cached: true. Coste: $0.
  3. Cache miss: genera con Haiku, persiste con expires_at = now + 24h, devuelve con cached: false.
  4. use_cache=false fuerza regeneración incluso si existe registro vigente.

Tours expirados no se borran automáticamente; quedan accesibles vía bib_list_tours(include_expired=true) para auditoría histórica.

Tools que usan esta tabla

Tool MCPOperación
bib_generate_tourSELECT (cache check) + INSERT (persist nuevo tour)
bib_list_toursSELECT con filtro expires_at > now (default)

Casos de uso

Véase también

Subir