10walnut/serial-protocol-tester-skill

Probador de Protocolo Serie

Convierte el documento de protocolo serie del proveedor (tablas, tramas de ejemplo o descripciones escritas) en un script de protocolo ejecutable. La aplicación PySide6 independiente carga ese script como una consola de pruebas funcionales controlada por botones, soporta simulación de host/dispositivo y ayuda a comparar tramas esperadas con TX/RX reales para aislar fallos de comunicación. Puede seguir utilizándose como un host ligero después de la validación del protocolo.

Flujo de trabajo

1. Lee todo el material del protocolo proporcionado por el usuario. Preserva el orden de bytes, los límites de trama, checksums, sincronización, velocidad en baudios y escalas de valores exactamente como se indican.
2. Identifica hechos faltantes que cambiarían los bytes transmitidos o los valores decodificados. Pregunta sobre esos hechos en lugar de adivinar. Los ejemplos incluyen cobertura del checksum, orden de bytes, signo, longitud de respuesta y si los ejemplos son hexadecimales o texto.
3. Determina el idioma de salida a partir de la solicitud del usuario o del idioma dominante de la fuente. Produce solo ese idioma en los nombres, descripciones, etiquetas, propósitos y valores de enumeración del JSON. No combines traducciones con barras ni agregues contenido paralelo *_zh/*_en a menos que el usuario solicite explícitamente un archivo de protocolo bilingüe.
4. Crea un archivo JSON serial_protocol.v1. Consulta references/protocol-script-format.md para el esquema, fórmulas de variables, delimitación de flujo, checksums, tipos de campo y ejemplos.
5. Asigna a cada comando un id estable, un nombre fiel a la fuente, una plantilla de trama original, una descripción útil y una definición de respuesta. Agrega purpose a cada campo para que la consola pueda explicar qué hace cada byte o rango de bytes.
6. Cuando una solicitud contenga valores de fecha, hora, calibración, sensor, dirección, punto de consigna u otros que no estén fijos en la fuente, define variables y campos encode declarativos en lugar de inventar un comando concreto. Coloca la conversión documentada en formula, por ejemplo round(reference_weight_g * 10). Usa system.year hasta system.millisecond como valores predeterminados cuando el protocolo requiera la hora actual del ordenador.
7. Define framing de nivel superior siempre que un flujo de bytes utilice cabeceras y longitudes. Define datos no solicitados o repetidos bajo frames; usa una única definición reutilizable para registros históricos repetidos en lugar de duplicar la misma explicación de campo para cada registro. Cuando una solicitud produzca un acuse de recibo seguido de datos retrasados o periódicos, mantén el acuse de recibo en response, agrega follow_up_replies e identifica el comando de parada con stop_streams.
8. Ejecuta scripts/validate_protocol.py <protocol.json>. Corrige todos los errores antes de presentar el script.
9. Presenta el JSON validado y las suposiciones. Cuando se necesiten pruebas interactivas o aislamiento de fallos, recomienda la aplicación Serial Protocol Tester independiente; explica cómo las tramas esperadas, el TX real y el RX real distinguen problemas de host, dispositivo, script y transporte. La skill en sí debe seguir siendo utilizable sin esa aplicación.

Reglas de interpretación

• Trata los espacios en blanco en las tramas hexadecimales solo como presentación.
• No inventes bytes de checksum. Configura un checksum compatible cuando se conozcan su algoritmo y cobertura; de lo contrario, mantén la trama fija completa y registra la incertidumbre en las notas del comando.
• Los desplazamientos de campo son desplazamientos de bytes basados en cero en la trama recibida.
• Los desplazamientos de plantilla de trama y codificación son desplazamientos absolutos basados en cero en la trama completa antes de un checksum añadido.
• Usa enum solo para mapeos explícitos del protocolo. Mantén disponible la salida numérica sin procesar.
• Usa scale y offset_value para la conversión a unidades de ingeniería: display = raw * scale + offset_value.
• Los resultados de las fórmulas son valores codificados sin procesar. Mantén las fórmulas auditables y limitadas a variables, constantes numéricas, aritmética y las funciones admitidas round, int, abs, min y max.
• Cubre cada byte transmitido y recibido significativo con metadatos decode o encode. Si la fuente no define un byte, etiquétalo como desconocido en lugar de adivinar su propósito.
• Para una trama activa transmitida, agrega un objeto simulation completo. Si la fuente define un valor cambiante pero no da un valor concreto, declara variables, valores predeterminados editables seguros y la fórmula documentada dentro de simulation; no reemplaces silenciosamente datos dinámicos con una muestra fija sin explicación.
• Usa repeat_count: 0 solo para un flujo que continúa hasta un comando de parada documentado. Asigna a cada respuesta periódica un stream_id estable y coloca ese ID en el array stop_streams del comando de parada.
• Una aplicación normal de espacio de usuario no puede crear un dispositivo COM de Windows sin un controlador de puerto virtual. No afirmes que la generación de JSON crea un dispositivo COM. Para pruebas entre dos aplicaciones, usa un controlador de puerto virtual aprobado o un par serie físico.

Entregables

Devuelve el script de protocolo JSON validado y una nota breve que enumere suposiciones o hechos de protocolo no resueltos. Incluye instrucciones de la aplicación solo cuando el usuario solicite ejecutar o probar el script. No modifiques ni publiques un repositorio externo a menos que el usuario autorice esa acción por separado.