Endpoint /api/help/ask — proxy Help Widget → MCP workspace
Endpoint /api/help/ask — proxy Help Widget → MCP workspace
Identificación
| Campo | Valor |
|---|---|
| Ruta | /api/help/ask |
| Método | POST |
| Handler | core.api_help.help_ask (operation: core_api_help_help_ask) |
| Auth | Sesión de usuario (mismo dominio) |
| App | core |
Responsabilidad
Actúa como proxy thin entre el Help Widget del frontend (Alpine.js) y el MCP workspace (bib_ask). Normaliza el modo (help | tutor), propaga el historial conversacional cuando corresponde, y devuelve la respuesta renderizada en HTML (_md_to_html).
No accede directamente a la base de datos ni al vector store — toda la lógica de recuperación vive en el workspace MCP.
Payload de entrada
{
"question": "string (requerido)",
"mode": "'tutor' | null",
"source_type": "string | null",
"app": "string | null",
"history": [
{ "role": "user | assistant", "content": "string" }
]
}| Campo | Descripción |
|---|---|
question | Pregunta del usuario en texto plano |
mode | "tutor" activa IT Tutor; cualquier otro valor → modo help |
source_type | Filtro opcional de tipo de fuente (modo help) |
app | App Django activa inferida desde la URL (modo help, context-aware) |
history | Turnos previos del chat — solo reenviado si mode=tutor (s55). El cliente envía máx. 10 turnos. |
Lógica de enrutamiento por modo
mode = "tutor" if payload.get("mode") == "tutor" else "help"
history = payload.get("history") if mode == "tutor" else None- Modo
help: búsqueda vectorial en la wiki de la app, filtrada porappysource_type. Sin historial. - Modo
tutor: conocimiento general de IT (el workspace skipea el vector search). Con historial multi-turn (desde s55). El campoappno se envía en este modo.
Ambos modos incluyen "archive": False — el archivado lo gestiona el cron diario del Curator, no el flujo del usuario final.
Respuesta
{
"answer": "<p>HTML renderizado desde markdown</p>",
"mode": "help | tutor",
"sources": [ ... ]
}El HTML lo genera _md_to_html en el proxy antes de devolver la respuesta. El frontend inyecta resp.answer directamente en el DOM via innerHTML (patrón CSP del proyecto).
Historial del endpoint
| Sprint | Cambio |
|---|---|
| s52 | Context-aware retrieval: campo app inferido desde URL |
| s53 | Toggle mode=tutor: IT Tutor mode (skip vector search) |
| s55 | Multi-turn: campo history propagado al workspace cuando mode=tutor |
Endpoints relacionados del módulo core.api_help
| Endpoint | Operación | Propósito |
|---|---|---|
/api/help/wiki | core_api_help_help_wiki | Browse de secciones y artículos de la wiki |
/api/help/article | core_api_help_help_article | Lectura de artículo individual |
Véase también
- [[feature—help—chat-tutor-multi-turn]]
- [[feature—help—it-tutor-mode]]
- [[concept—help—help-widget]]
- [[entity—core—endpoint—help-wiki]]
- [[entity—core—endpoint—help-article]]