pengmn23/sketchnote-diagram

Ilustraciones con estilo de notas dibujadas a mano (sketchnote) – Código para dibujar

Una imagen = un archivo JSON. scripts/render.py abre scripts/sketchnote.html sin interfaz gráfica usando Google Chrome (o Microsoft Edge) local, dibuja según el JSON y captura la pantalla. Todo el texto proviene del JSON, por lo que no hay errores tipográficos; a cambio, el resultado es más estructurado que el de modelos generativos.

Requiere: fuentes macOS «手札体» (Hannotate SC) y «翩翩体» (HanziPen SC), Google Chrome, Python 3 (solo biblioteca estándar).

Archivos

Ubicación	Qué es	Cuándo leerlo
scripts/render.py	Línea de comandos: crear, verificar, generar, abrir editor	Cada vez
scripts/sketchnote.html y editor.js	Programa de dibujo y editor en navegador	No es necesario leerlos, render.py los invoca
scripts/模板/*.json	5 plantillas para crear nuevas imágenes	--list-templates para ver descripciones
scripts/templates.js	Plantillas empaquetadas para el editor, generadas automáticamente; no se modifican a mano	Ejecutar --templates después de cambiar las plantillas
references/json-format.md	Cada campo, sección, icono, doodle, nombre de color, limitaciones conocidas	Antes de modificar el JSON
references/style.md	Normas de estilo: distribución de secciones, combinación de colores, significado de las formas, límite de caracteres, qué no dibujar, comprobaciones posteriores	Primera vez que se dibuja, al definir tipos de nodos y número de caracteres
references/editor.md	Cómo usar el editor en navegador	Cuando se va a entregar al usuario para ajustes manuales
assets/示例/	Un ejemplo vertical 3:4 y uno horizontal 16:9 (JSON + PNG)	Para referencia cuando no se tiene claro el diseño

En los comandos siguientes, R se refiere a scripts/render.py (llamado con ruta absoluta). El JSON y la imagen generada de cada diagrama se colocan en el proyecto del usuario, no en esta skill.

Comandos

python3 R --list-templates                          # Ver qué plantillas hay
python3 R --new 03_02_字段顺序 --from 1              # Crear specs/03_02_字段顺序.json desde la plantilla 1 (specs en la carpeta actual)
python3 R --new 封面 --dir specs --output ../图片/封面.png   # Especificar dónde guardar JSON y la imagen
python3 R --check specs/03_02_字段顺序.json          # Solo verificar diseño (superposición, fuera del lienzo), tarda segundos; código de salida 1 si hay advertencias
python3 R specs/03_02_字段顺序.json --scale 1        # Generar imagen reducida al 1x para vista previa (1600×900)
python3 R specs/03_*.json                           # Generar imágenes oficiales al 2x (3200×1800), guarda según output de cada una
python3 R specs/xxx.json --svg                      # Generar también una copia SVG
python3 R --edit specs/xxx.json                     # Abrir editor en Chrome para que el usuario ajuste arrastrando
python3 R --templates                               # Reempaquetar después de modificar scripts/模板/

• Si el nombre en --new tiene el formato <capítulo>_<figura>_<contenido>, buscará automáticamente archivos de notas <capítulo>_*.md en directorios superiores y establecerá output en la carpeta del mismo nombre junto a esas notas, con el nombre <figura>.png. Si no lo encuentra, no lo establece; se debe añadir output o --output antes de generar la imagen.
• output es una ruta relativa al archivo JSON.

Flujo para dibujar una imagen

1. Determinar qué tema cubre la imagen y dónde se colocará en el texto. El texto de la imagen solo usa palabras del texto principal, no añade nuevas afirmaciones. Para imágenes con mucho texto, primero acordar el contenido con el usuario en la conversación, luego escribir el JSON.
2. Seleccionar plantilla: --list-templates, elegir la más parecida en estructura (bucle cerrado de proceso, comparación arriba/abajo, ciclo de cuatro pasos, horizontal en blanco, vertical 3:4), crear con --new.
3. Modificar JSON: Seguir references/json-format.md para cambiar texto y coordenadas (las coordenadas se estiman sobre 1600×900; los nodos tienen x, y como centro). Seguir la sección 5 de references/style.md para determinar el tipo de cada nodo:
   • input círculo azul: datos, ideas, inspiración, fuentes
   • produce rectángulo naranja: resultados, acciones
   • feedback hexágono verde: revisión, reflexión, consolidación En la misma imagen, elementos del mismo tipo usan la misma forma; incluir una leyenda explicativa.
4. Ejecutar --check hasta que no haya advertencias, luego generar la vista previa reducida al 1x, abrirla para revisar visualmente: dirección de flechas, texto bloqueado, espacios en blanco uniformes, número de caracteres según la sección 6 de style.md. Si el diseño es difícil de ajustar, usar --edit para que el usuario lo mueva en el navegador; guardar con ⌘S y luego generar la imagen.
5. Generar la imagen oficial al 2x, guardarla en output.
6. Informar al usuario dónde se coloca: detrás de qué oración del texto principal y cómo incrustarla.

Notas

• El chino no se ajusta automáticamente: en JSON usar \n; en el editor, hacer doble clic para modificar texto y usar «/» para saltos de línea.
• Al intercambiar entre 16:9 y 3:4, las posiciones de los elementos no se convierten automáticamente; hay que reordenar según las advertencias de --check.
• La firma no se dibuja por defecto. Si el usuario la desea, añadir en JSON: "signature": { "text": "Firma", "x": 40, "y": 862 }; preguntar una vez al usuario qué texto quiere; las imágenes posteriores lo mantendrán.
• Si se cambian colores en references/style.md, también hay que modificar las constantes de color en scripts/sketchnote.html.