Biblioteca: cherry-pick Understand-Anything — bib_explain_node, layers y tours (s79)

Biblioteca: cherry-pick Understand-Anything — bib_explain_node, layers y tours (s79)

Sesión: s79 · Fecha: 2026-05-22 · Commit: c0984be ADR de referencia: decision--20260522--evaluacion-understand-anything-vs-bibliotecario

Integración de 3 de las 5 ideas evaluadas en el experimento Understand-Anything al Bibliotecario de producción. El objetivo es enriquecer las capacidades de comprensión del grafo sin duplicar el context window del agente principal.

Motivación

El experimento Understand-Anything identificó patrones de comprensión de código que son ortogonales al grafo topológico existente:

1. Explicación semántica de un nodo individual en castellano llano (PR review / onboarding rápido).
2. Capas arquitectónicas nombradas por LLM (conceptualmente distintas de las bib_communities de Louvain, que son clustering topológico sin nombre).
3. Tours pedagógicos ordenados por dependencia, para llevar a un dev de “no sé nada” a “entiendo el módulo”.

Cherry-pick #3 — bib_explain_node

Qué hace

Deep-dive en castellano de un nodo o archivo. Combina:

• bib_get_node (metadata + edges) desde D1
• Excerpt del source code vía GitHub API (centrado en line_number si disponible, ±100 líneas)
• Síntesis estructurada de Haiku 4.5

Output

JSON estructurado con keys: que_hace, para_que_se_usa, entradas_salidas, dependencias_clave, quien_depende, complejidad, gotchas.

Args del tool MCP

Coste estimado

~$0.05 por invocación (Haiku 4.5, prompt caching activo).

Mapeo app → repo

workspace      → CreaRackSL-workspace
claude-method  → claude-method
<resto>        → CreaRack-Pro  (fallback)

Cherry-pick #1 — Layers arquitectónicas (bib_assign_layers / bib_list_layers)

Nueva tabla D1: bib_layers

CREATE TABLE bib_layers (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL UNIQUE,
  description TEXT,
  color TEXT,
  app_scope TEXT,
  node_count INTEGER DEFAULT 0,
  created_at TEXT,
  updated_at TEXT
);
-- + columna layer_id en bib_nodes (FK nullable → SET NULL on delete)
-- + idx_bib_nodes_layer_id
-- + idx_bib_layers_app_scope

Migración aplicada: migrations/0033_bib_layers.sql

Diferencia vs bib_communities

Tools MCP

bib_assign_layers

Procesa nodos container (module, js_module, endpoint, model, doc, schema) en batches de 80 → Haiku propone capas → persiste con UPSERT en bib_layers + UPDATE bib_nodes.layer_id.

• dry_run=true: preview sin persistir.
• Coste: ~$0.05 por app · ~$0.20 corpus completo.

bib_list_layers

Lista capas con node_count. Opcional include_nodes=true para sample de hasta 50 nodos por capa.

Ejemplos de capas esperadas

API · HTTP endpoints, Service · Business Logic, Data · Persistence, UI · Frontend, Infrastructure · Deploy & Config, Utility · Shared Helpers, Integration · External Services, Observability · Monitoring & Logging

Cherry-pick #2 — Tours pedagógicos (bib_generate_tour / bib_list_tours)

Nueva tabla D1: bib_tours

Cache de tours generados con TTL de 24h. Campos clave: app, focus, title, summary, steps_json, step_count, cost_usd, expires_at.

Migración aplicada: migrations/0034_bib_tours.sql

Tool MCP bib_generate_tour

Flujo:

1. Cache hit en bib_tours → devuelve inmediatamente (cached: true).
2. Cache miss → recopila nodos container + edges top → Haiku genera tour de 5-15 pasos.
3. Persiste en bib_tours con expires_at = now + 24h.

Coste estimado: ~$0.10-0.30 por tour (según tamaño del app).

Output por paso: { order, title, description, node_qnames, why_now }.

Tool MCP bib_list_tours

Lista tours vigentes. include_expired=true para ver todos (útil para debug o comparar versiones).

Refactor: extracción de _lib/anthropic.ts

Como prerequisito, callAnthropicHaiku, haikuCostUsd y parseJsonFromLLM se extrajeron de wiki.ts al nuevo módulo functions/_lib/anthropic.ts. Ambos handlers (wiki.ts y biblioteca.ts) importan desde _lib. Reducción neta en wiki.ts: -65 LOC.

Ver: [[entity—workspace—service—anthropic-lib]]

Resumen de cambios en D1

Véase también

• [[entity—workspace—service—anthropic-lib]]
• [[entity—workspace—handler—biblioteca]]
• [[entity—workspace—handler—wiki]]