El puente del Help Widget (api_help)

El puente del Help Widget (core/api_help.py)

El Help es un WIDGET, no una página: llama a su propia API puente contra el workspace — por eso puede averiarse sin que ninguna página dé error (estuvo caído 4 semanas en junio, y sirvió un JSON de error como artículo 9 semanas — task #254). Esta página fija el mapa que a la Biblioteca le faltaba.

Piezas

• 4 endpoints (core/api_help.py, router /api/help):
  • POST /ask — proxy a bib_ask del workspace vía MCP (_mcp_call).
  • POST /ask-stream — variante SSE (generador asíncrono obligatorio: bajo Daphne un iterador síncrono se BUFFERIZA entero).
  • GET /wiki — lista de artículos (/biblioteca/wiki del workspace, filtrada a product=crearack); el workspace la sirve desde D1 bib_wiki_pages con las etiquetas de CATEGORY_LABELS (functions/api/biblioteca/wiki.ts).
  • GET /article — contenido de un artículo (read_guide → fichero del repo).
• Informante del estado (help_intent.py + help_state.py): regex local que detecta preguntas operativas (“¿hay alertas?”) e inyecta contexto vivo SEPARADO de la pregunta (no desvía el embedding del retrieval).
• Frontend: panel Alpine en static/js/alpine-components.js (categorías con orden explícito — ups/wireless/settings incluidos desde v1.82.1).

La capa de idioma (i18n F3b) — reglas de honestidad

• El corpus canónico es EN (src/content/wiki/crearack--*); el ES vive en wiki-es/ con el mapa de títulos wiki-es/titles.json.
• _apply_language reescribe la ruta a wiki-es/ SOLO si el título del artículo está en el mapa — un artículo sin traducir se sirve en inglés (degradación elegante). La simetría EN/ES NO está garantizada (así se rompió 9 semanas: dos páginas EN nacieron tras congelar la traducción y el rewrite ciego servía el 404 del workspace como artículo).
• _mcp_call aplica la Regla 15: el workspace contesta HTTP 200 con {"error": ...} cuando la tool falla — eso se convierte en excepción → 502 honesto (“Error loading article”), nunca contenido.
• Guardas de paridad: test test/help-corpus-parity.test.ts en el CI del workspace (toda entrada de titles.json tiene su fichero; toda categoría tiene etiqueta) + tests/api/test_help.py en Pro.

Trampas conocidas

• El frontmatter de una página puede PERDERSE (footgun histórico de wiki_update_content pre-s185): una página sin frontmatter desaparece del título/mapa y rompe la paridad — restaurar del historial git (víctimas ya restauradas: crearack--racks--filas-row, crearack--network--auto-provision-wizard).
• read_guide NO llama al modelo (leer un artículo es gratis); lo que cuesta es bib_ask (/api/help/ask).
• El timeout del puente es 60 s (respuestas largas de Gemma tardan 12-45 s).

Véase también

• [[incident—20260823—help-es-json-error-como-articulo]]