Volver a la wiki

Biblioteca — Grafo + Archivo Maestro + Wiki Supercontexto

Biblioteca — Grafo + Archivo Maestro + Wiki Supercontexto

Qué es

Sistema de conocimiento vivo de CreaRack Pro y del workspace. Combina 3 capas complementarias: grafo de código estructurado en Cloudflare D1, Archivo Maestro semántico basado en Workers AI + Vectorize, y Wiki Supercontexto de 6 tipos de páginas mantenida por agentes LLM. Las 3 se exponen como tools MCP via Cloudflare Workers y comparten tablas bib_* en D1 como fuente de estado persistente.

Por qué existe

El codebase de CreaRack Pro crece continuamente con múltiples apps Django, endpoints TypeScript, migraciones y decisiones arquitectónicas que ningún humano retiene íntegramente. La Biblioteca resuelve 3 problemas:

  1. Perder rastro de qué código existe y cómo se relaciona — grafo lo resuelve.
  2. No poder responder preguntas en lenguaje natural sobre docs — Archivo Maestro con búsqueda vectorial + síntesis Gemini 2.5 Flash.
  3. Wiki manual queda obsoleta y llena de contradicciones — Wiki Supercontexto convierte escritura y mantenimiento en responsabilidad de agentes LLM auditables.

Componentes

Grafo D1 (biblioteca.ts)

handleBiblioteca implementa +20 tools MCP sobre bib_nodes, bib_edges, bib_docs, bib_endpoints, bib_agents, bib_communities, bib_index_runs, bib_change_log. Cada artefacto de código (modelo, endpoint, servicio, componente, handler MCP) es un nodo con qualified_name único. Relaciones (imports, herencia, llamadas, documentación) son edges tipados con confidence_score. Helper bfsImpact hace traversal BFS bidireccional con chunking seguro de 90 params por consulta (límite D1). bib_impact_query evalúa alcance de un cambio antes de que ocurra.

Extracción AST (bib_ast.py)

Script en CreaRack-Pro usa módulo ast nativo sin dependencias externas. Visitor CreaRackVisitor recorre los 7 apps configurados y extrae módulos, clases con herencia, métodos, funciones standalone, imports. Genera edges imports, inherits, contains, calls. Detecta y excluye imports bajo TYPE_CHECKING e imports lazy dentro de funciones para evitar edges espurios. Salida JSON compatible con bib_index_ast. Soporta modo incremental (solo archivos con hash cambiado), filtro por apps y envío con --push.

Archivo Maestro (archivo.ts)

handleArchivo implementa 3 tools: bib_search_semantic (vectorial pura, chunks rankeados sin síntesis), bib_ask (NL → búsqueda vectorial + síntesis Gemini 2.5 Flash via GOOGLE_AI_API_KEY), bib_index_chunks (indexación batch con embeddings Workers AI). Chunks en bib_chunks con embedding_b64 (Float32Array en base64), sincronizados con Cloudflare Vectorize si env.VECTORIZE disponible. SHA-256 del contenido detecta cambios. Batch embedding máx 50 chunks; topK máx 20.

Wiki Supercontexto (wiki.ts)

handleWiki expone 5 tools MCP capa de memoria viva (Supercontexto Fase 1, DESIGN.md §§ 5, 7, 8): wiki_create_page, wiki_update_page, wiki_archive_page, wiki_log_event, wiki_lint_check. Páginas almacenadas en src/content/wiki/ del repo workspace rama main via GitHub Contents API (PUT con env.GH_PAT). bib_wiki_pages mantiene metadata sincronizada (slug, tipo, status, tags, sources, related, content_hash SHA-256, community_id). wiki_lint_check verifica que sources code sigan existiendo en GitHub, calcula antigüedad (stale si last_verified >60d), detecta orphans via backlinks en bib_edges con edge_type='documents', registra evento en bib_wiki_utility. 6 tipos válidos: entity_page, concept_page, feature_page, decision_page, incident_page, runbook_page.

Flujos

Reindex AST incremental: bib_ast.py --incremental --push sobre CreaRack-Pro detecta archivos modificados por hash, visita AST, genera JSON nodos/edges, llama bib_index_ast. MCP upserta nodos en bib_nodes y crea edges. bib_index_runs registra duración y cuentos.

bib_ask (pregunta semántica): agente llama bib_ask(question="..."). Handler embedde pregunta con Workers AI (@cf/baai/bge-base-en-v1.5), busca 8 chunks cercanos en Vectorize o bib_chunks, y si hay matches llama Gemini 2.5 Flash con chunks como contexto para sintetizar respuesta con fuentes. Si falta GOOGLE_AI_API_KEY, error explícito.

wiki_create_page (Bibliotecario-Ingest Fase 3): Ingest detecta nueva entidad pública tras PR mergeado, llama wiki_create_page con tipo, slug, front-matter, contenido. Handler valida slug (kebab lowercase), verifica ausencia de duplicados, genera front-matter YAML, escribe archivo via GitHub API con mensaje wiki(create): <slug> [skip ci], inserta fila en bib_wiki_pages, registra evento en bib_wiki_log. Si falta GH_PAT, omite write al repo pero mantiene D1.

Ingest post-merge (Fase 3 futuro): GitHub Action dispara Bibliotecario-Ingest (Claude Sonnet 4.6) al cerrar PR. Lee diff, clasifica entidades via bib_impact_query, crea/actualiza páginas wiki, actualiza cross-refs, llama wiki_log_event("ingest"). Tiempo esperado: 30-90s por PR.

Véase también

Subir