Davidypy/Habilidades

Explicación de Código C51 y Visualización Didáctica

Convierte el programa C51 completo enviado por el usuario en material didáctico para principiantes del curso "Tecnología de Aplicación de Microcontroladores" en escuelas técnicas superiores. La integridad y legibilidad del código fuente son más importantes que la estética gráfica; se explica el comportamiento basado en las declaraciones reales, sin tratar comentarios, nombres de archivos o circuitos comunes como hechos.

Entrada y Alcance de Entrega

• De forma predeterminada, se entrega una infografía PNG en chino, de 1814×867 píxeles, horizontal, con fondo blanco, adecuada para colocarse debajo del título de una diapositiva PPT. Por defecto, se intenta hacer 1 imagen, se aumenta el número de páginas según la legibilidad; cuando el usuario especifica explícitamente el número de imágenes o el diseño, se prioriza su solicitud.
• Cuando el usuario solo solicita análisis, indicaciones o planificación, se completa solo ese alcance. La creación de esta habilidad en sí misma no implica la generación de imágenes; si no hay código real, no se tratan ejemplos o texto de marcador de posición como un programa.
• Se lee el código completo, el nombre del programa (si lo hay), la cantidad de imágenes, el diseño y las condiciones conocidas del circuito. Si falta el código, se debe solicitar; para otros parámetros que se pueden inferir razonablemente, se explican los valores predeterminados directamente y se avanza. Cuando se desconoce el nivel efectivo, se puede proporcionar un análisis con suposiciones explícitas, o simplemente mostrar el estado de los bits del puerto.
• El nombre del archivo se basará en lo dado por el usuario o indicado explícitamente en el código fuente; si no se puede identificar, se usa "programa_sin_nombre.c" y se explica que es un nombre de visualización, sin pretender que es el nombre del archivo original.
• La salida se escribe por defecto en un directorio de resultados independiente de la tarea actual, no se escriben trabajos de usuario en el directorio de la habilidad.

Base Inmutable del Código Fuente

1. Guarda el archivo fuente en bytes originales. Para código en el chat, extrae solo el texto dentro de los delimitadores de bloque de código, manteniendo líneas en blanco, sangría y saltos de línea al final, estableciendo una línea base después de guardar. Diferentes codificaciones deben decodificarse explícitamente, está prohibido usar caracteres de reemplazo para ocultar errores.
2. Registra el nombre del archivo, la codificación, SHA-256, el número de líneas físicas, el contenido de cada línea y el recuento de caracteres de paréntesis. El recuento de paréntesis, incluso cuando incluye comentarios/cadenas, es solo una auditoría de caracteres, no equivale a una verificación gramatical.
3. No reescribe identificadores, constantes, comentarios, operadores, paréntesis ni declaraciones duplicadas. No optimiza el código ni completa automáticamente paréntesis. No añade puntos suspensivos en la región del código fuente. Si se encuentran errores, se explican fuera de la imagen.
4. Por defecto, mantiene el orden de línea original y la sangría. Los números de línea y el coloreado de sintaxis pertenecen a la capa de visualización y no se pueden escribir de nuevo en el texto fuente. Las tabulaciones se pueden expandir para la visualización según tabulaciones explícitas, pero los caracteres originales se conservan para su verificación.
5. La paginación o el código en dos columnas debe cubrir cada línea del archivo fuente una y solo una vez, numeradas consecutivamente en el orden original. La re-referencia de fragmentos de código en el área de explicación no cuenta como duplicación de paginación del código fuente, pero debe distinguirse claramente.

Establecimiento de Explicaciones Didácticas Basadas en el Programa

Durante el análisis, lee references/c51-analysis.md y organiza según el programa real:

• Pines de entrada/salida, tipos, valores iniciales de variables y responsabilidades de funciones.
• La relación real entre inicialización, bucle principal, bifurcación condicional, bucle de bloqueo e interrupciones.
• Orden de evaluación de expresiones, número de iteraciones de bucle, desplazamiento/desplazamiento circular, valores de puerto y cambios de estado.
• Detección de pulsaciones de botones, eliminación de rebotes, confirmación posterior, si realmente existe la espera de liberación y si una pulsación puede desencadenar repetidamente.
• Hechos conocidos del circuito, suposiciones necesarias y partes que no pueden determinarse solo a partir del código fuente.

Cada explicación clave utiliza el formato "declaración citada directamente del código fuente → función de la declaración → efecto real". Selecciona solo de 3 a 6 puntos de conocimiento relevantes para la página actual; el resumen de funciones suele ser de 2 a 4 elementos. No agregues puntos de conocimiento que no existen en el código fuente solo para completar la cantidad.

Diseño y Generación

Antes de generar la imagen, lee references/rendering.md, que contiene comandos de herramientas de renderizado, formato JSON de enseñanza y reglas de paginación.

• Fondo blanco, bordes finos, tarjetas de esquinas redondeadas, márgenes de seguridad de 20 a 30 píxeles en los cuatro lados. Tema azul para el código; verde para explicaciones clave; naranja para efectos de ejecución; cian para el flujo. Si no hay imágenes históricas, se crean según esta especificación, no se afirma que coinciden con trabajos históricos no vistos.
• No se añaden títulos de curso adicionales generales. El título de la tarjeta de código muestra el nombre real del archivo, con la etiqueta "C (Microcontrolador 51)" y el número de página a la derecha.
• El área de código izquierda generalmente ocupa el 55% al 65%, utiliza una fuente monoespaciada y una fuente de respaldo que admita chino. Los comentarios son verdes, las palabras clave azules/moradas y los valores numéricos naranjas. El código y los comentarios no deben desbordarse, recortarse o forzarse con tamaños de letra muy pequeños.
• El lado derecho coloca funciones del programa, declaraciones clave, efectos de hardware y flujo real según el contenido; cuando hay varias páginas, se distribuyen a las páginas relacionadas, no se requiere repetir todos los módulos en cada página. Cuando el código es demasiado largo, se pueden usar páginas dedicadas al código más páginas dedicadas a la explicación.
• Prioriza la ejecución del script scripts/render_infographic.py de esta habilidad para renderizar de manera determinista el PNG completo. Es responsable de leer el código fuente línea por línea, paginación, números de línea, resaltado, tarjetas didácticas, LED de puerto y nodos de flujo con líneas de conexión; el contenido didáctico lo escribes tú en JSON después del análisis, la herramienta no infiere la semántica.
• Cuando el script rechaza debido a restricciones de ancho de línea, capacidad de texto o diseño, ajusta la paginación o el diseño, si es necesario, utiliza herramientas programáticas como SVG/HTML para lograr la misma base de código fuente y verificación de cobertura. No trunques ni reduzcas el texto en secreto para evitar fallos.
• Las tarjetas ordinarias, pines, LED, displays de 7 segmentos y flechas deben dibujarse mediante programación, sin necesidad de modelos de imagen. Utiliza la habilidad imagegen disponible solo cuando el usuario lo desee o cuando el contenido realmente requiera ilustraciones de mapa de bits; solo puede ser responsable de materiales que no sean código. No permitas que los modelos de imagen redibujen el código fuente y luego afirmen que es preciso.
• Cuando el número de imágenes especificado por el usuario no puede satisfacer simultáneamente la integridad y la legibilidad, explica el número de páginas necesario y la razón, y propone opciones de diseño claras; no elimines el código fuente arbitrariamente. En el modo de número automático, utiliza directamente una paginación clara y legible.

Verificación y Entrega

1. Reconstruye el texto de todas las páginas de código fuente, compáralo carácter por carácter con la línea base, verifica números de línea consecutivos, sin duplicados ni omisiones, paréntesis de cierre originales y saltos de línea al final. Conserva la lista de resultados.
2. Verifica la explicación del programa, las condiciones de bifurcación, el comportamiento de los botones y el estado del hardware; el nivel lógico de los LED, el orden de bits y la dirección deben ser consistentes con el cableado conocido o las suposiciones marcadas.
3. Abre cada PNG final, verifica que el código, los comentarios en chino, los nodos de flujo y el texto explicativo sean claros, sin superposiciones, caracteres faltantes, recortes o desalineaciones; confirma las dimensiones reales de cada imagen.
4. Distingue el alcance de la verificación: la comparación del código fuente demuestra la consistencia de la entrada de diseño; la legibilidad de los píxeles finales aún requiere una inspección visual. No trates el hash del código fuente o el hash del PNG como prueba de OCR o corrección semántica.
5. Entrega las imágenes y una breve descripción: número de imágenes, números de línea de código fuente y contenido principal de explicación por página, dimensiones reales, alcance de verificación completado, problemas encontrados en el programa fuente y suposiciones de hardware. Proporciona enlaces a la línea base del código fuente y al manifest.json para una fácil revisión.
6. Si solo se obtienen indicaciones, un panel de código o un boceto no verificado, indica claramente el estado de entrega, no lo llames infografía didáctica completa. Cuando las herramientas estén limitadas, explica las limitaciones reales y el trabajo completado.