Candidatos semánticos en wiki_enrich_related (PR4-b)

Descripción

Mejora del subsistema de candidatos de backlinks en wiki_enrich_related (handler MCP). Reemplaza el algoritmo v1 (basado en tag/type) por un sistema semántico que aprovecha Vectorize (Workers AI) para embedding de textos.

Cambio de estrategia

Antes (v1):

• Candidatos extraídos por coincidencia de tags o tipo de página
• Relevancia débil: relaciones tangenciales frecuentes (ej: “widget de salud de red” → “endpoint MCP”)

Ahora (v2):

• embedTexts(title) → genera vector semántico del título de la página
• searchChunks(sourceType: 'doc') → busca chunks similares en la base de knowledge (Vectorize)
• Extrae slugs únicos de las páginas coincidentes, en orden de relevancia semántica
• Haiku elige 2-4 candidatos con mejor score
• Grounding: valida que cada slug tenga una página wiki activa antes de incluirlo

Mecanismo técnico

// Flujo simplificado (functions/api/mcp/handlers/wiki.ts)
const [vec] = await embedTexts(env.AI, [t.title]);
const matches = await searchChunks(env, vec, 18, { sourceType: 'doc' });
// Extrae slugs únicos de wiki/*.md de los matches
const candSlugs = matches
  .map(m => m.sourcePath.match(/wiki\/(.+?)\.md$/)[1])
  .filter(slug => !seen.has(slug) && slugHasActivePage(slug));
// Recupera títulos de bib_wiki_pages para context a Haiku
const candidates = candSlugs.map(slug => ({ slug, title: DB[slug] }));

Cambios de código

• Eliminado: función safeJsonArray() (helper de fallback tag/type, ya no usado)
• Eliminado: lógica de búsqueda por tags (LIKE "%tag%") y fallback por type
• Requerimiento nuevo: env.AI (Workers AI binding para Vectorize) debe estar configurado. Si no, retorna error 'Workers AI binding not configured (semantic candidates)'
• Seguridad: mantiene dry_run=true por defecto (no escribe en D1 hasta validación manual post-deploy)

Calidad esperada

v1 producía sugerencias similares a: “healthcheck endpoint” → “network widget gadget”, típicamente falsos positivos.

v2 aprovecha embeddings de semántica real: dos páginas sobre “monitoreo de recursos” quedarán relacionadas aunque no compartan tags/palabras exactas.

El autor (@Esquembri) planea comparar outputs en dry-run post-deploy.

Impacto

• Afecta: wiki_enrich_related handler (MCP), subsistema de backlink candidates
• No breaking: cambio completamente interno, backwards-compatible desde el PoV del caller
• Dependencia nueva: Workers AI (Vectorize) — requiere binding en env.AI
• Coste: embeddings pequeños (títulos) vía Haiku embedding model (barato)

Véase también

• [[feature—workspace—tools-hub]]
• [[feature—supercontext—enrichment-agent-blueprint]]