FoloToy/folotoy-toy-role-config-skill

Configuración de Personaje FoloToy

Configura de forma segura un personaje FoloToy y verifica el resultado en el dispositivo real.

Lee references/api-workflow.md antes de realizar llamadas a la API. Lee references/examples.md cuando el usuario necesite ayuda para diseñar un personaje o una frase de inicio.

Tareas soportadas

• Iniciar sesión con un número de teléfono y un código SMS de un solo uso.
• Verificar si un dispositivo autorizado ya está emparejado.
• Emparejar un dispositivo no emparejado usando su SN y clave de emparejamiento.
• Leer el dispositivo actual, el personaje activo y los modelos de voz disponibles.
• Cambiar el personaje, la frase de inicio y la voz.
• Leer el personaje guardado y guiar una prueba en el dispositivo físico.

No utilices esta habilidad para desemparejar un dispositivo, borrar la memoria, restablecer la red, eliminar una cuenta, comprar servicios o controlar un dispositivo que el usuario no posea o no tenga autorización explícita para gestionar.

Modelo de seguridad

Los secretos identifican una cuenta o un dispositivo físico. Mantenlos fuera de los mensajes, archivos fuente, capturas de pantalla, URLs, registros persistentes e informes finales.

1. Solicita el número de teléfono, código SMS, SN y clave de emparejamiento solo cuando cada valor sea necesario.
2. No muestres un número de teléfono completo, código SMS, clave de emparejamiento o token de acceso.
3. Conserva el token de acceso solo para la tarea actual. Prefiere una variable en memoria o una sesión temporal protegida y elimínalo al finalizar.
4. Detente cuando la propiedad no esté clara o el dispositivo esté emparejado a otra cuenta.
5. Muestra un diff legible para humanos y obtén confirmación explícita antes de la solicitud de actualización.
6. Cambia solo los campos aprobados. Conserva los IDs de modelo actuales y todos los demás campos obligatorios.
7. Lee el personaje de nuevo después de guardar. Una respuesta de escritura exitosa por sí sola no es verificación suficiente.

Flujo de trabajo

1. Establecer región y consentimiento

Pregunta si la cuenta utiliza el servicio de China continental o el internacional:

• China continental: https://webapp.folotoy.cn
• Internacional: https://webapp.folotoy.com

Explica que el flujo de trabajo envía un SMS y cambia la configuración de un dispositivo físico. Confirma que el usuario posee el dispositivo o está autorizado a gestionarlo.

2. Iniciar sesión

Solicita el número de teléfono, incluido el código de país. Envía el código de verificación utilizando la solicitud documentada en la referencia de la API.

Pausa y solicita el código de seis dígitos. No lo adivines, no lo recuperes de otra fuente ni continúes antes de que el usuario lo proporcione.

Inicia sesión y conserva el token bearer devuelto solo para esta tarea. Si la autenticación falla, verifica el código de país y la vigencia del código. No envíes mensajes SMS repetidamente.

3. Resolver el dispositivo objetivo

Solicita el SN del dispositivo y verifica su estado de emparejamiento.

• Si ya está emparejado con la cuenta actual, continúa.
• Si no está emparejado, solicita la clave de emparejamiento y obtén confirmación antes de emparejar.
• Si está emparejado en otro lugar, detente y explica que el propietario actual debe desemparejarlo a través del flujo de producto soportado.

Lee los dispositivos de la cuenta e identifica el objetivo exacto por SN. Nunca selecciones un dispositivo solo porque su nombre mostrado parezca familiar.

4. Leer antes de diseñar

Lee los detalles del dispositivo, estado en línea, ID del producto, personaje activo y el objeto completo del personaje actual. Obtén los modelos TTS disponibles para el producto y asigna los IDs a nombres de voz legibles.

Pregunta por la audiencia prevista, escenario, personalidad, tono, longitud de respuesta, reglas de comportamiento, límites de seguridad y preferencia de voz. Si el usuario solo tiene una idea aproximada, propón un borrador conciso en lugar de bloquear.

5. Vista previa del cambio

Muestra esta vista previa compacta:

Dispositivo: [SN y nombre mostrado enmascarados]
Personaje: [nombre]

Persona:     actual -> propuesta
Frase de inicio: actual -> propuesta
Voz:          nombre actual -> nombre propuesto

Sin cambios: modelo STT, modelo LLM, memoria, red, emparejamiento y todos los demás campos

Pregunta: ¿Aplicar este cambio al dispositivo FoloToy indicado?

Continúa solo después de una confirmación explícita.

6. Aplicar de forma segura

Parte del objeto completo del personaje devuelto por el servicio. Fusiona solo la persona, frase de inicio e ID de voz aprobados. Conserva los valores obligatorios existentes como speech_to_text_id, language_model_id y todos los demás campos específicos del producto.

Envía el objeto fusionado completo al endpoint de actualización de personaje. No envíes una carga útil adivinada o mínima cuando el servicio espera la configuración completa.

7. Verificar y probar

Lee la lista de personajes nuevamente y compara los campos custom_ability, start_text y text_to_speech_id devueltos con la propuesta aprobada. Asigna el ID de voz a su nombre legible.

Verifica que el dispositivo esté en línea. Pide al usuario que inicie una nueva conversación y pruebe:

1. La frase de inicio.
2. Un escenario normal dentro del personaje.
3. Un límite de seguridad o incertidumbre.

Si la configuración guardada es correcta pero el comportamiento no ha cambiado, verifica el personaje activo e inicia una conversación nueva antes de cambiar más campos.

8. Informar y limpiar

Informa el nombre del personaje, la frase de inicio final, el nombre de voz final, el estado de lectura de vuelta, el estado de la prueba física y una siguiente iteración sugerida. Enmascara la identidad del dispositivo y elimina los datos de autorización temporales.

Manejo de fallos

• SMS no recibido: verifica el código de país, espera el temporizador de reenvío y evita envíos repetidos.
• 401 o 403: trata la sesión como expirada e inicia sesión de nuevo. No reutilices el token anterior.
• Emparejamiento rechazado: verifica el SN y la clave de emparejamiento; detente si el dispositivo pertenece a otra cuenta.
• Ruta de voz no encontrada: usa el endpoint de modelo de producto con mod_type=tts; no confíes en rutas heredadas /v1/voices.
• Error de revisión de contenido como 10500: acorta y simplifica el personaje o la frase de inicio. Mantén la configuración actual intacta hasta que se apruebe un nuevo borrador.
• Guardado pero no audible: verifica el personaje activo, el estado en línea del dispositivo y una conversación recién iniciada.

Criterios de finalización

La tarea está completa solo cuando:

• El dispositivo objetivo fue autorizado y resuelto por SN.
• Ningún secreto fue incrustado o mostrado sin enmascarar.
• El usuario aprobó explícitamente el diff mostrado.
• Solo cambiaron los campos aprobados.
• La lectura de vuelta de la API coincide con la propuesta.
• El usuario recibió un guion de prueba física, incluso si el dispositivo está temporalmente fuera de línea.