Biblioteca s79: Cherry-picks Understand-Anything (bib_explain_node · layers · tours)

Biblioteca s79: Cherry-picks Understand-Anything

PR#60 · 22-05-2026 · @Esquembri · ADR de referencia

Tres capacidades nuevas incorporadas al servidor MCP Bibliotecario, cherry-picked de la evaluación comparativa Understand-Anything vs Bibliotecario (sesión s79). Todos los cambios son aditivos — sin breaking changes en tools existentes ni queries vivas.

Cherry-pick #3 · bib_explain_node

Propósito

Deep-dive en castellano llano de cualquier archivo o nodo del grafo de conocimiento. Combina:

1. bib_get_node + edges desde D1.
2. Source code real desde GitHub (via GH_PAT + API application/vnd.github.raw).
3. Síntesis estructurada por Claude Haiku 4.5.

Útil para PR review y onboarding sin consumir context window del agente principal.

Parámetros

Exactamente uno de qualified_name, node_id o file_path es necesario.

Output

{
  "node": { "id": 42, "qualified_name": "...", "node_type": "...", "app": "...", "file_path": "..." },
  "explanation": {
    "que_hace": "...",
    "para_que_se_usa": "...",
    "entradas_salidas": "...",
    "dependencias_clave": "...",
    "quien_depende": "...",
    "complejidad": "simple | moderado | complejo",
    "gotchas": "..."
  },
  "source_info": { "from_line": 1, "to_line": 200, "total_lines": 350 },
  "cost": { "input_tokens": 800, "output_tokens": 400, "usd": 0.002240 }
}

Coste estimado

~$0.05/llamada (Haiku 4.5). El excerpt se centra en line_number del nodo (±100 líneas), recortando a máx 200 líneas.

Dependencias de entorno

• ANTHROPIC_API_KEY — obligatorio.
• GH_PAT — opcional; sin él no se incluye source excerpt.

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

Propósito

Asigna a cada nodo “container” (module, js_module, endpoint, model, doc, schema) una capa arquitectónica semántica nombrada por Haiku 4.5. Capas típicas: API, Service, Data, UI, Infrastructure, Utility, Integration, Observability.

Diferencia vs bib_communities (Louvain)

bib_assign_layers

Procesa en batches de 80 nodos. Por defecto scope global; app restringe a una app concreta. dry_run=true devuelve preview sin persistir.

Persistencia: UPSERT en bib_layers + UPDATE bib_nodes SET layer_id. Refresca node_count tras cada run.

bib_list_layers

Devuelve todas las layers con name, description, app_scope, node_count. Con include_nodes=true añade sample de hasta 50 nodos por layer.

Coste estimado

~$0.05–$0.20 por run completo según número de nodos.

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

Propósito

Genera un walkthrough de 5–15 pasos ordenados topológicamente para enseñar la arquitectura de una app a un dev recién llegado. Orientado a onboarding de Dani/Txell o devs externos.

Algoritmo

1. Recopila nodos container del app (≤200) + layers asignadas.
2. Toma top edges (imports, calls, contains, documents), máx 150, ponderados por weight.
3. Llama a Haiku 4.5 con prompt de “educador técnico senior”.
4. Persiste en bib_tours con cache de 24h.

bib_generate_tour

bib_list_tours

Lista tours en cache. Por defecto solo los vigentes (<24h). include_expired=true para ver todos.

Output de un tour

{
  "cached": false,
  "tour_id": 7,
  "app": "monitoring",
  "title": "Tour Monitoring · Polling SNMP y alertas",
  "summary": "Módulo de monitoreo activo...",
  "steps": [
    {
      "order": 1,
      "title": "Entrypoint HTTP: MonitoringViewSet",
      "description": "...",
      "node_qnames": ["monitoring.views.MonitoringViewSet"],
      "why_now": "Lo ves primero porque es la puerta de entrada de las peticiones HTTP"
    }
  ],
  "step_count": 9,
  "cost": { "usd": 0.018 },
  "expires_at": "2026-05-23T08:20:24Z"
}

Coste estimado

~$0.10–$0.30 por tour generado. Con cache activo el coste se reduce a $0 en reutilizaciones.

Refactor lateral: extracción _lib/anthropic.ts

callAnthropicHaiku, haikuCostUsd y parseJsonFromLLM fueron extraídas de wiki.ts (donde vivían inline desde s60) al nuevo módulo functions/_lib/anthropic.ts.

• wiki.ts pierde ~65 LOC; ahora importa desde _lib/anthropic.
• biblioteca.ts importa los mismos helpers para los 3 nuevos handlers.
• No hay cambio de comportamiento — misma lógica, mismos precios ($0.0008/1K input, $0.004/1K output Haiku 4.5).

Ver [[entity—workspace—service—anthropic-lib]] para detalle del módulo.

Migrations aplicadas

Backup pre-cambio: d1-pre-cherrypick-20260522.sql (local + Hetzner STAGE).

Tools MCP registradas (5 nuevas)

Véase también

• [[decision—20260522—evaluacion-understand-anything-vs-bibliotecario]]
• [[entity—workspace—service—anthropic-lib]]
• [[entity—workspace—table—bib-layers]]
• [[entity—workspace—table—bib-tours]]