Ir al contenido
DevLab

Qué contiene el kit de un protocolo, dónde está en DevLab, qué es cada fichero y cada variable, dónde está la URL de Engine y cómo ejecutar un starter.

En esta página
  1. Dónde encontrarlo
  2. Los ficheros del kit
  3. Las versiones del SDK
  4. Las variables del .env
  5. neuro.config.json
  6. Dónde está la URL de Engine
  7. Dónde está mi key
  8. Los starters
  9. Qué trae el zip
  10. Ejecútalo
  11. Incluir mi key
  12. Si algo no funciona

Tu kit es el conjunto de ficheros que DevLab prepara para un protocolo de tu organización: la configuración del cliente, el entorno de tu backend y dos guías. Ya trae todo lo que DevLab sabe (la URL de Engine de tu entorno, el protocolo, las decisiones que Neurologyca fijó para tu organización), así que solo añades lo que es tuyo: la key y, en el starter de grabación, una dirección pública.

  1. Entra y abre Tu integración en la cabecera. Se abre en Protocolos.
  2. Elige un protocolo de la lista.
  3. Arriba del protocolo, junto a Protocolo, elige Kit.

La ruta es Tu integración › Protocolos › un protocolo › Kit. Cada vista tiene su propia dirección, así que puedes guardarla en favoritos.

Cuándo no hay Kit:

  • Sin key activa. Si la key de tu equipo está revocada o no existe, los protocolos se ven en solo lectura («Protocolos de tu organización, solo lectura») y no tienen kit hasta que tu equipo vuelva a tener key. Consulta Tu cuenta de DevLab.
  • Baseline. No tiene kit («Baseline no tiene kit: va antes de cualquier protocolo»).
  • Un protocolo cuyo contexto DevLab no puede resolver («Sin kit: su contexto no está resuelto»). Pídeselo a Neurologyca si lo necesitas.

El mapa de todas las pantallas está en Dónde está cada cosa.

La pestaña Kit muestra una pestaña por fichero, cada una con Copiar y un botón para descargarlo. El kit no lleva nunca tu key. Los navegadores quitan el punto inicial del nombre al guardar un fichero, así que el botón guarda .env.example como env.example y .npmrc como npmrc, y dice a qué renombrar cada uno (.env y .npmrc, en tu proyecto).

Los ficheros que genera tu kit
FicheroDónde apareceQué es
neuro.config.jsonSiempre.La configuración del cliente de tu protocolo: pásala a defineTenantConfig(json).
.env.exampleEl kit de tu consola.El entorno de tu backend, sin tu key: cópialo a .env y rellénalo. No subas nunca .env a git.
.envEl zip del starter (en vivo o grabación).El entorno de tu backend. La key va vacía salvo que descargaras el starter con «Incluir mi key». No lo subas nunca a git.
.npmrcSiempre.Apunta @neurologyca a GitHub Packages y lee NODE_AUTH_TOKEN de tu entorno; no lleva ningún secreto. Sin él, npm install responde 404 para @neurologyca/*.
KIT.mdSiempre.El kit en prosa: las versiones del SDK para las que está hecho (con el comando para comprobar las tuyas y el changelog), el enlace a los indicadores que te da tu contexto (Tu integración › Protocolos), orden de arranque, el aviso que das a las personas que mides (con el texto modelo del Anexo biométrico y, en el starter de grabación, el consentimiento previo y por escrito que pide una grabación en diferido donde la ley lo exija), lo pendiente, audiencias, opciones de preguntas y enlaces a la doc.
AGENTS.mdSiempre.Las reglas y el índice de la doc para tu agente de código; pégalo en tu AGENTS.md o CLAUDE.md. Va en inglés a propósito.

Junto a los ficheros, la pestaña Kit lista lo pendiente (una decisión que Neurologyca aún no ha fijado para tu organización: «Pídeselo a Neurologyca») y lo opcional (puedes capturar sin ello; por ejemplo, sin subcontexto Engine aplica el de la mecánica, constellationSubcontextId, o si no el por defecto del contexto). KIT.md lleva la misma información en prosa, con el orden de arranque, lo que no debes hacer nunca (poner la key en código de navegador, subir una credencial a git, confundir la key de Engine con el token del registro), el aviso que das a cada persona que mides antes de cualquier captura (con el enlace al texto modelo de aviso y consentimiento, sección 14 del Anexo biométrico), las audiencias de interpretación del contexto del protocolo y las opciones de pregunta de cada step. Enlaza también los indicadores que te da tu contexto, sin lista: la lista al día es Indicadores que recibes en este contexto, en el protocolo, en Tu integración › Protocolos (qué enseña).

Bajo Vías, la pestaña Kit tiene Versiones: las versiones de @neurologyca/capture y @neurologyca/capture-server para las que está hecho el kit, las que DevLab instala y verifica y las que instalan los starters. DevLab no ve tu proyecto, así que no sabe qué versión tienes: compara con la fecha de publicación del changelog y te da el comando para comprobar la tuya, npm ls @neurologyca/capture @neurologyca/capture-server, con Copiar. Durante 30 días desde que se publica una versión, su fila lleva un chip, uno por paquete:

  • Nueva · fecha: una versión compatible. Si tu proyecto usa una anterior, actualiza con el comando npm i que enseña el bloque; no hace falta cambiar nada más. El enlace dice qué cambia en esa versión.
  • Incompatible · fecha: una versión publicada en esos 30 días, hasta la del kit, es incompatible (también si después salió una compatible; la fecha es la de la incompatible). Con una anterior, tu proyecto puede dejar de funcionar: sigue la guía de migración antes de actualizar.

KIT.md, en el kit y en los starters, dice lo mismo bajo su línea DevLab:: las versiones para las que está hecho y su fecha, el mismo comando y el enlace al changelog. El script doctor de la skill lee el mismo changelog publicado y sí mira tu node_modules (Integrar con tu agente de código).

.env.example del kit y el .env de un zip de starter llevan las mismas variables: copia .env.example a .env y rellena lo que es tuyo. Las variables de grabación aparecen solo donde dice la tabla.

Las variables del .env de tu backend
VariableDónde apareceQué esQuién la rellena
ENGINE_BASESiempre.La URL del Engine de tu entorno, ya rellena desde tu kit. La usa tu backend; el navegador nunca.Ya la rellena tu kit.
ENGINE_API_KEYSiempre.La key de tu equipo, solo para tu backend. Va vacía en el kit: descarga el starter con «Incluir mi key» o revélala en Tu cuenta. Nunca en código de navegador ni en git.Secreto. Vacía en el kit. Un starter descargado con Incluir mi key la rellena (los valores del procesador piden Incluir mi key y las credenciales del procesador).
PROTOCOL_IDSiempre.El id del protocolo al que pertenece este kit.Ya la rellena tu kit.
ROLEProtocolos de contexto (no Measurement).Rol opcional que se fija en cada persona que crea tu backend. El kit lo rellena solo si Neurologyca fijó uno para ti, así que suele ir vacío y vale; si lo pones, ha de ser uno que Engine conozca. Hoy no tiene efecto.El kit la rellena solo si Neurologyca fijó un valor para ti.
NARRATIVE_LANGUAGEProtocolos de contexto (no Measurement).El idioma de la interpretación (en o es), que se fija en cada persona que crea tu backend. Sin él, Engine escribe en inglés.Ya la rellena tu kit.
PORTSiempre.El puerto en el que escucha tu backend (3000 por defecto).—
PROCESSOR_URLEl starter de grabación (diferido); en el kit de la consola, solo si tu organización tiene el servicio de procesado.La URL del servicio de procesado de Neurologyca para las capturas en diferido. Vacía si tu organización no lo tiene dado de alta.Ya la rellena tu kit.
PROCESSOR_API_KEYEl starter de grabación (diferido); en el kit de la consola, solo si tu organización tiene el servicio de procesado.La key del servicio de procesado, una sola pareja para toda tu organización. Se rellena solo al descargar el starter de grabación con «Incluir mi key y las credenciales del procesador». Queda vacía si el servicio de procesado está apagado o aún sin alta para tu organización.Secreto. Vacía en el kit. Un starter descargado con Incluir mi key la rellena (los valores del procesador piden Incluir mi key y las credenciales del procesador).
PROCESSOR_SECRETEl starter de grabación (diferido); en el kit de la consola, solo si tu organización tiene el servicio de procesado.El secreto con el que el servicio de procesado firma sus webhooks; verificar la firma es obligatorio. Se rellena junto con PROCESSOR_API_KEY y queda vacío en los mismos casos (servicio apagado o sin alta).Secreto. Vacía en el kit. Un starter descargado con Incluir mi key la rellena (los valores del procesador piden Incluir mi key y las credenciales del procesador).
PUBLIC_BASE_URLEl starter de grabación (diferido); en el kit de la consola, solo si tu organización tiene el servicio de procesado.El origen HTTPS público de tu backend. El servicio de procesado llama ahí a tres rutas (vídeo, token y webhook); nunca llama a localhost, así que para probar en local usa un túnel HTTPS público.La pones tú.
UPLOAD_URL_SECRETEl starter de grabación (diferido); en el kit de la consola, solo si tu organización tiene el servicio de procesado.Solo tuyo: firma las URL de tus vídeos y es distinto de PROCESSOR_SECRET. Cada descarga del starter de grabación lleva un valor aleatorio nuevo (una descarga nueva lo cambia e invalida las URL ya firmadas). En el kit de la consola (.env.example) va vacío: genera tú una cadena hex aleatoria de 32 bytes.Secreto. Un valor aleatorio nuevo en cada descarga del starter de grabación.

La configuración del cliente de tu protocolo: pásala a defineTenantConfig(json). La lee el código de tu navegador; no lleva ningún secreto.

Las claves de neuro.config.json
ClaveDónde apareceQué es
engineBaseUrlSiempre.La ruta de tu propio proxy hacia Engine ('/engine'), no el host de Engine. El navegador llama a tu proxy y tu backend añade la key.
taxonomy.contextIdSiempre.El contexto en el que se mide la captura. Con Measurement es siempre "measurement".
taxonomy.hciIdProtocolos de contexto que fijan un HCI objetivo.El HCI objetivo del contexto, cuando el protocolo fija uno.
taxonomy.subcontextByMechanicProtocolos de contexto con el subcontexto de cada mecánica fijado.El subcontexto elegido para cada mecánica, por nombre de mecánica. Sin él, Engine aplica el de la mecánica o el de por defecto del contexto.
triggerAnalysisSolo Measurement.Una clave de tu aplicación, no del SDK: tu código la pasa a la captura (client.capture() o captureProtocol). false porque Measurement no interpreta.
transcribeMeasurement (siempre, como false); protocolos de contexto con la transcripción encendida, que es lo habitual.La transcripción: false, o { "language": "en" | "es" } sin región. Abre también el micrófono. El idioma es el que habla la persona: se fuerza, nunca se detecta.
mediaProtocolos de contexto donde algún step ofrece varias preguntas.La pregunta de cada step: { "<mecánica>": { "<orden del step>": "<mediaPid>" } }. Por defecto, la primera que no usa un step anterior.
processing.languageSolo el starter de grabación.El idioma que tu backend manda con cada trabajo diferido (en o es); el servicio de procesado lo exige.
processing.transcribeStepsSolo el starter de grabación.Los tipos de step que transcribe el servicio de procesado. Ponla a [] para apagar la transcripción en este starter (ignora "transcribe").

La URL de Engine de tu entorno está en Tu integración › Protocolos › un protocolo › Kit › .env.example, en la línea ENGINE_BASE. Es también la línea ENGINE_BASE del .env que va dentro del zip de un starter.

La documentación nunca imprime el valor, porque es el de tu entorno (pruebas o producción): los ejemplos la llaman $ENGINE, y ENGINE_BASE es el mismo valor en el entorno de tu backend. Solo la usa tu backend. El navegador llama a tu proxy, y por eso engineBaseUrl de neuro.config.json es la ruta de tu proxy (/engine) y no la dirección de Engine.

Si tu equipo no tiene key activa no hay kit, y por tanto tampoco .env.example: mira dónde encontrarlo.

El kit no la lleva: ENGINE_API_KEY va vacía en .env.example. Tienes dos formas de conseguirla:

  • Revelarla en Tu cuenta, en Keys de Engine, con tu contraseña (Revela la key de tu equipo).
  • Descargar un starter con Incluir mi key: el servidor escribe la key en el .env del zip. Mira abajo.

Un starter es un proyecto pequeño y completo, listo para ejecutar, con tu kit ya dentro. Abajo en la pestaña Kit, Starters ofrece dos:

  • Starter en el dispositivo (tiempo real): la página captura en el navegador y tu backend hace de proxy hacia Engine. Elígelo para ver la integración funcionando de extremo a extremo y como base de una captura en vivo.
  • Starter de grabación (diferido, en servidor) (Preview): la página graba y sube, y tu backend recibe el aviso del servicio de procesado. Elígelo solo si vas a procesar grabaciones en un servidor (Diferido). Si tu organización aún no tiene el servicio de procesado, su tarjeta lo dice y el starter no arranca (npm start se para con el mismo mensaje): pídeselo al admin de tu organización o a Neurologyca.

Elige Descargar .zip. Si la descarga no empieza, púlsalo de nuevo (la página lo dice pasados unos segundos). El playground tiene la misma descarga en Playground › SDK y API, sin tu key.

En su raíz:

Los ficheros de la raíz de un zip de starter
FicheroQué es
neuro.config.jsonLa configuración del cliente de tu protocolo, el mismo fichero que en tu kit.
.envEl entorno de tu backend. La key va vacía salvo que elijas Incluir mi key.
.npmrcApunta los paquetes @neurologyca al registro privado y lee el token de NODE_AUTH_TOKEN; nunca contiene el token.
.gitignoreDeja .env, node_modules y los ficheros locales fuera de git.
KIT.mdEl kit en prosa, el mismo fichero que en tu kit.
AGENTS.mdLas reglas y el índice de la doc para tu agente de código, el mismo fichero que en tu kit.
README.mdLa guía propia del starter: requisitos, los tres comandos y qué hace cada fichero del código.

Además, el código propio del starter: un servidor pequeño, la página y los módulos que ejecuta el playground. El zip del starter de grabación trae también los scripts para simular el aviso.

Necesitas Node.js 20.6 o posterior (los starters usan node --env-file) y el token del registro que Neurologyca te da con la invitación en NODE_AUTH_TOKEN (no es tu key de Engine; consulta Instalación). Sin Incluir mi key, pon antes tu key en .env (ENGINE_API_KEY; dónde).

Shell
export NODE_AUTH_TOKEN=... # PowerShell: $env:NODE_AUTH_TOKEN="..."
npm install && npm start

Después abre http://127.0.0.1:3000 (la variable PORT lo cambia). Si npm start se para con bad option: --env-file, tu Node es anterior a 20.6. Si se para con Missing in .env: …, nombra cada variable que falta y de dónde sale. Dos starters pueden correr a la vez con PORT distintos.

npm test comprueba el arranque en Chrome con un vídeo sintético como cámara (sin cara, así que en el starter en el dispositivo pasa cuando el arranque llega a la comprobación de la cara; su README dice cómo comprobar hasta la captura con un vídeo tuyo) y borra la persona de prueba en Engine. Sin tu key en .env (o, en el starter en diferido, sin el servicio de procesado) esa comprobación se salta y dice por qué; el resto de npm test corre igual.

La key nunca va en la página. Para tenerla en el zip, marca Incluir mi key y pulsa Descargar .zip: DevLab te pide la contraseña en un diálogo y el servidor escribe la key en el .env del zip. Si cancelas o cierras el diálogo, no se envía nada.

  • Cuenta como un revelado: 5 por hora y cuenta, compartidos con Revelar en Tu cuenta y con las credenciales del procesador; una contraseña incorrecta también cuenta, y cada descarga queda registrada.
  • En el starter de grabación la opción es Incluir mi key y las credenciales del procesador: escribe también PROCESSOR_API_KEY y PROCESSOR_SECRET, la pareja de toda tu organización (la vigente, nunca una pendiente). Si el servicio de procesado está apagado o tu organización aún no tiene alta, esas dos líneas salen vacías con el motivo. Consulta Credenciales del procesado en diferido.
  • Mientras tu organización no acepte los Términos de DevLab, Incluir mi key está deshabilitada y dice por qué (el mismo aviso de Tu cuenta): el starter sin la key se sigue descargando.
  • Cada zip de grabación lleva un UPLOAD_URL_SECRET aleatorio nuevo: descargar otra vez lo cambia e invalida las URL de vídeo firmadas con el anterior.
  • PUBLIC_BASE_URL lo pones tú: la dirección HTTPS pública de tu backend. El servicio de procesado nunca llama a localhost, así que para probarlo en tu máquina usa un túnel HTTPS público (Servicio de procesado).
Ves Qué significa Qué hacer
La descarga no empieza, o «Si la descarga no empieza, inténtalo de nuevo» El navegador no recibió el zip Pulsa Descargar .zip de nuevo
«Contraseña incorrecta: no se ha descargado nada» La contraseña de Incluir mi key no es la de tu cuenta de DevLab Tecléala de nuevo; el intento cuenta para los 5 por hora
«Has llegado al límite de 5 por hora (compartido con Revelar)» Has gastado tus 5 revelados de esta hora Espera a que pase la hora
«El starter no está disponible en este entorno» (tenant.starter_unavailable) Este DevLab no ofrece starters Copia los ficheros de la pestaña Kit
«Tu equipo no tiene key activa» (tenant.team_unavailable) La key se rotó o se revocó con la página abierta Recarga; si el equipo sigue sin key, pídeselo a Neurologyca
«Tu organización aún no ha aceptado los Términos de DevLab, así que el starter no puede llevar tu key» (legal.org_terms_required) La persona admin de tu organización no ha aceptado los términos Descárgalo sin la key o pide a la persona admin de tu organización que los acepte
npm install no descarga @neurologyca/... Falta NODE_AUTH_TOKEN o es incorrecto Ponlo en tu shell (Instalación)
npm start se para con bad option: --env-file Node anterior a 20.6 Actualiza Node