diagrama-de-pila

¿Qué hace diagrama-de-pila?

Integración con Hermes

Resuelve <skill> al directorio que contiene este SKILL.md, no al directorio de trabajo del proyecto. Ejecuta los scripts empaquetados con terminal a través de Python usando rutas absolutas entre comillas. Usa read_file para plantillas/referencias y write_file/patch para artefactos. Prefiere un entorno Python aislado para Playwright; una importación por sí sola no demuestra que su controlador de navegador funcione.

Para solicitudes basadas en repositorios, registra la evidencia de nodos y bordes primero. Las dependencias no establecen la topología de ejecución. Mantén las relaciones inferidas etiquetadas como suposiciones; pregunta cuando la ambigüedad cambiaría la arquitectura. La topología explícita proporcionada por el usuario es evidencia. Nunca leas secretos ni archivos no relacionados para descubrir una pila.

Entrega archivos locales usando MEDIA:/ruta/absoluta/hacia/out.html y MEDIA:/ruta/absoluta/hacia/out.png (más el PNG oscuro); usa vision_analyze para inspeccionar ambos temas renderizados. HTML es la única fuente visual de verdad; los PNG provienen de Chromium, no de un renderizador SVG/PIL independiente. No marques un archivo como entregado antes de que exista. Esta habilidad no llama ni modifica brag. Usa stack-video solo cuando se solicite un video; es un hermano independiente, no un paso requerido.

Los scripts/recursos ascendentes se preservan de caru-ini/stack-diagram; consulta UPSTREAM.md de este paquete. Las instrucciones opcionales de la galería a continuación aún requieren su propio consentimiento explícito; instalar o publicar este paquete no es consentimiento para la galería.

Produce diagramas de arquitectura de estilo dibujo de ingeniería: íconos reales sobre mosaicos blancos, cuadros de grupo etiquetados (como los diagramas VPC de proveedores de nube), flechas ortogonales con etiquetas monoespaciadas, sobre un fondo de papel cuadriculado frío. Un archivo HTML autocontenido es la fuente de verdad; PNG / TSX / artefacto se derivan de él.

Requisitos

• Python 3.9+ (solo biblioteca estándar para fetch_icons.py, build.py y share.py)
• Acceso de red a las fuentes de íconos (svgl.app, raw.githubusercontent.com, cdn.jsdelivr.net, aws.amazon.com y d1.awsstatic.com para íconos AWS, services.google.com para íconos Google Cloud, learn.microsoft.com y arch-center.azureedge.net para íconos Azure, además del sitio o repositorio propio de la marca para nombre=URL) al obtener íconos
• Playwright + Chromium para render_png.py: pip install playwright && python3 -m playwright install --with-deps chromium

Flujo de trabajo

1. Definir el contenido (nodos, grupos, bordes)
2. Obtener íconos — scripts/fetch_icons.py
3. Planificar coordenadas — leer references/geometry.md
4. Construir el HTML desde assets/template.html — scripts/build.py
5. Renderizar un PNG y observarlo antes de entregar
6. Entregar en el/los formato(s) solicitado(s)
7. Opcionalmente, compartirlo en la galería pública

Paso 1 — Contenido

A partir de la lista de tecnologías/servicios del usuario, decide:

• Nodos: cada tecnología = un nodo (nombre + un rol corto en minúsculas como servidor http, bd sqlite)
• Grupos: dibuja un cuadro alrededor de cosas que comparten un entorno de ejecución, proveedor o repositorio (p. ej., un cuadro de proveedor de nube que contiene un cuadro de entorno de ejecución; un cuadro de monorepo para herramientas). Anidar un nivel de profundidad está bien; más profundo se vuelve ruidoso. Escribe las etiquetas de grupo en la propia escritura de la marca (GitHub, npm); la plantilla las muestra tal como se escriben.
• Bordes, tres tipos:
  • sólido con color de acento = el flujo principal de solicitud/datos (un camino continuo se lee mejor)
  • sólido neutro = conexiones internas secundarias
  • discontinuo neutro = relaciones de tiempo de desarrollo/despliegue (CI, hooks de git, despliegue de IaC)

Si el usuario solo dio una lista plana de herramientas, infiere grupos y flujos sensatos a partir de lo que son las herramientas; solo pregunta cuando una herramienta es lo suficientemente ambigua como para que el diagrama sea incorrecto en cualquier caso.

Paso 2 — Íconos

python3 scripts/fetch_icons.py <directorio-íconos> tanstack hono drizzle "betterauth:better-auth" "orpc=https://orpc.unnoq.com/logo.webp"
python3 scripts/fetch_icons.py <directorio-íconos> "aws:aws/AWS-Cloud-logo" "vpc:aws/vpc" "fargate:aws/fargate" "s3:aws/s3"
python3 scripts/fetch_icons.py <directorio-íconos> "gcp:google-cloud" "run:gcp/cloud-run" "lb:gcp/load-balancing" "sql:gcp/cloud-sql"
python3 scripts/fetch_icons.py <directorio-íconos> "azure:azure/Azure-A" "app:azure/app-service" "vnet:azure/vnet" "sql:azure/sql-database"

Formas de especificación: nombre (nombre usado como slug), nombre:slug (slug diferente), nombre=URL (URL explícita), nombre:aws/<Nombre> (ícono oficial AWS), nombre:gcp/<Producto> (ícono oficial Google Cloud), nombre:azure/<Nombre> (ícono oficial Azure). El script intenta, en orden: svgl → devicon → gilbarbara/logos, escribe archivos más manifest.json, y marca los íconos cuyo relleno es blanco. svgl (svgl.app) es primero porque tiene las marcas oficiales actuales para marcas de desarrollo modernas (TanStack, Better Auth, Hono...). Cuando un logo tiene versiones clara/oscura, la clara se convierte en <nombre> (los mosaicos son blancos en ambos temas) y la oscura se guarda como <nombre>_oscuro para las etiquetas de grupo. svgl se compara solo por título exacto, así que un fallo simplemente pasa. Su API también expone variantes wordmark — ocasionalmente útiles para una etiqueta de grupo ancha, nunca para mosaicos.

Reglas que importan más que la mecánica:

• Nunca cambies el color de un logo. Los usuarios lo notan. Si un logo es blanco o demasiado claro para un mosaico blanco, colócalo sobre un mosaico oscuro (clase tile dark) en lugar de tocar su relleno. La bandera white_fill del manifiesto es una heurística — un relleno blanco puede ser un detalle interno en una marca de color (tRPC, Ubuntu), así que echa un vistazo al SVG antes de recurrir al mosaico oscuro.
• Solo marcas oficiales. simple-icons no es intencionalmente una fuente: sus glifos son redibujos monocromáticos, y los usuarios los detectan como incorrectos de inmediato. Cuando todas las fuentes fallan (FAIL), encuentra el archivo oficial y pásalo como nombre=URL — busca en el repositorio del proyecto (raíz logo*.svg, docs/, assets/, public/) y en su sitio (/logo.svg, /favicon.svg, /images/logo.svg). Algunas marcas viven solo en el repositorio (la de Lefthook es logo_sign.svg en la raíz de evilmartians/lefthook).
• Los conceptos abstractos obtienen pictogramas, no texto. Un nodo como "entorno de desarrollo", "cron", "cola", "caché" o "receptor de webhook" no tiene marca — recurre a un ícono de línea de Lucide mediante nombre:lucide/<ícono> (p. ej., devenv:lucide/terminal, cron:lucide/clock; navega en lucide.dev/icons). Sin texto en un mosaico, sin emoji.
• Subproductos de proveedores (Cloudflare D1/R2/KV...) generalmente no tienen un logo distinto: simplemente reutiliza el logo del proveedor en el mosaico y deja que el nombre del nodo lleve la distinción ("Cloudflare D1" / "bd sqlite").
• AWS usa sus propios íconos. Cada servicio tiene uno: obténlo con nombre:aws/<Nombre>, leído del paquete oficial de íconos de AWS en tiempo de ejecución (p. ej., lambda:aws/lambda, aws:aws/AWS-Cloud-logo, s3:aws/s3). El prefijo AWS- / Amazon- es opcional, los acrónimos comunes funcionan (s3, sqs, sns, ses, ecs, eks, ecr, elb, alb, nlb, iam, kms, msk, vpc), y un fallo imprime cada nombre. Los slugs aws, amazonwebservices y aws-* van al mismo paquete, y lo que no lleva FAIL en lugar de recurrir a una copia de terceros. Siempre escribe el prefijo aws/ para un servicio: un dynamodb desnudo aún pasa por la cadena de terceros. Mantén el paquete y los archivos de íconos sueltos fuera de los repositorios: AWS permite los íconos en diagramas, y la redistribución no está confirmada.
• El área de AWS sigue sus propias reglas de dibujo. Los íconos de servicio llevan su propio cuadrado y funcionan sobre fondos claros y oscuros, así que usa tile bare: un mosaico blanco solo duplica el marco. Las personas y los nodos genéricos dentro de él usan los íconos generales de AWS (user:aws/General-User; también General-Users, General-Client, General-Internet, General-Server) en tile bare res con el par lt/dk de la plantilla. Los grupos usan el group aws de la plantilla para AWS Cloud (con aws:aws/AWS-Cloud-logo en la etiqueta), más region, az, vpc, private o public para el resto: esquinas cuadradas, solo contorno, etiqueta en tinta, sin matiz de proveedor, y un ícono de 30px en la esquina en lugar del de 14px. Dentro de una VPC, muestra subredes públicas y privadas cuando sepas o puedas inferir la división de manera segura (un balanceador de carga orientado a internet en pública; servidores de aplicaciones y bases de datos en privada): una VPC plana es lo primero que notan las personas de AWS. Los bordes dentro de ella usan un color y una punta de flecha abierta: <path class="aws" ... marker-end="url(#open)"/>, aws dash para desarrollo/despliegue, etiquetas .el simples, y sin leyenda para ellos. Nombra los nodos Amazon S3 / AWS Fargate, no un S3 / Fargate desnudo; una forma corta como ALB va en la línea de rol, debajo del nombre completo (Elastic Load Balancing). Los nombres pueden ocupar dos líneas, pero Amazon / AWS deben permanecer en la línea de la primera palabra: si se ajustaría justo después del prefijo, ensancha ese nodo (left:<centroX-76>px; width:152px).
• Google Cloud usa sus propios íconos. Obténlos con nombre:gcp/<Producto>, leídos de los paquetes oficiales de Google en tiempo de ejecución (p. ej., run:gcp/cloud-run, lb:gcp/load-balancing, memorystore:gcp/memorystore). Solo los productos principales tienen su propio ícono (Cloud Run, Cloud SQL, Cloud Storage, BigQuery, GKE, Compute Engine, Vertex AI...). Cada otro producto usa el ícono de su categoría, como especifica la guía de Google: Cloud Load Balancing y Cloud CDN obtienen ambos Redes, Memorystore y Firestore obtienen ambos Bases de datos. Escribe el nombre del producto y el script elige el ícono. El prefijo Cloud / Google es opcional, algunas formas cortas funcionan (vpc, iam, kms, iap, gce, gcs), y un fallo imprime cada nombre. gcp/storage es la categoría Storage; Cloud Storage es gcp/cloud-storage. Los slugs gcp-* y google-cloud-* van a los mismos paquetes, y lo que no llevan FAIL en lugar de recurrir a una copia de terceros: esas copias son los íconos hexagonales retirados, que Google dice que no se usen. Siempre escribe el prefijo gcp/ para un producto: un bigquery desnudo aún pasa por la cadena de terceros. gcp:google-cloud es la marca Google Cloud para la etiqueta de grupo. Gemini y Firebase no están en los paquetes: usa el gemini y firebase desnudos. Mantén los paquetes y los archivos de íconos sueltos fuera de los repositorios: Google ofrece los íconos para diagramas y documentación, y la redistribución no está confirmada.
• Los diagramas de Google Cloud mantienen el estilo normal, con los grupos de Google. Los diagramas propios de Google (panel azul sólido, tarjetas horizontales) no se copian intencionalmente: los íconos van sobre el mosaico blanco normal, y los bordes y la leyenda se mantienen como de costumbre. Los grupos usan el group gcp de la plantilla para Google Cloud (con gcp:google-cloud en la etiqueta), más vpc, region, subnet o zone. Una VPC es global y una subred es regional, así que coloca la región dentro de la VPC, nunca la VPC dentro de una región. Los servicios globales y serverless (un balanceador de carga externo, Cloud Storage, Cloud Run) permanecen fuera de la VPC. Debido a que los íconos se comparten, escribe siempre el nombre completo del producto (Cloud Load Balancing, no LB), y ensancha un nodo cuyo nombre se ajustaría (left:<centroX-76>px; width:152px).
• Azure usa los íconos propios de Microsoft. Cada servicio tiene uno: obténlo con nombre:azure/<Nombre>, leído del paquete oficial de Microsoft en tiempo de ejecución (p. ej., app:azure/app-service, azure:azure/Azure-A, vault:azure/key-vault). El prefijo Azure- / Microsoft- y una s plural son opcionales, las formas cortas comunes funcionan (aks, vm, vnet, nsg, waf, blob, cosmos, redis, postgres, functions, front-door, apim, ai-search), y un fallo imprime cada nombre. Los slugs azure, microsoft-azure y azure-* van al mismo paquete, y lo que no lleva FAIL en lugar de recurrir a una copia de terceros. Siempre escribe el prefijo azure/ para un servicio: un cosmos desnudo aún pasa por la cadena de terceros. Microsoft Entra ID tiene un conjunto de íconos separado: pasa su archivo oficial como nombre=URL. Microsoft permite estos íconos solo en diagramas de arquitectura, materiales de capacitación y documentación. Nunca recortes, voltee, gire o cambie la forma de uno, úsalo solo para el servicio de Microsoft que representa, y mantén el paquete y los archivos de íconos sueltos fuera de los repositorios.
• Los diagramas de Azure mantienen el estilo normal, con los colores de grupo de Microsoft. Los diagramas propios de Microsoft no se copian intencionalmente: los íconos van sobre el mosaico blanco normal, y los bordes y la leyenda se mantienen como de costumbre. Los grupos usan el group azure de la plantilla para Azure (con azure:azure/Azure-A en la etiqueta), más rg, region, vnet, subnet o zone, y una etiqueta vnet o subnet lleva su ícono (vnet:azure/vnet, subnet:azure/subnet). Una VNet pertenece a una región, así que va dentro de la región. Los servicios globales como Front Door permanecen fuera de la región. App Service se sienta fuera de la VNet a menos que se ejecute en un App Service Environment, y un servicio PaaS al que se accede a través de un punto de conexión privado puede sentarse dentro de ella con private endpoint como su rol. Microsoft solicita el nombre completo del servicio junto a cada ícono (Azure SQL Database, no SQL), así que ensancha un nodo cuyo nombre se ajustaría (left:<centroX-76>px; width:152px).
• Las reglas de un proveedor cubren solo su propia área. Las reglas de AWS, Google Cloud y Azure aplican solo dentro del grupo de ese proveedor, incluso cuando el diagrama no muestra nada más. Todo lo que está fuera de él, como un usuario al lado o un borde que cruza hacia él, mantiene los mosaicos, grupos, bordes y leyenda normales.
• Nodos sin marca (usuario, navegador, internet, dispositivos, servidor físico): copia un glifo de assets/generic/ al directorio de íconos bajo el nombre del nodo, o usa nombre:lucide/<ícono> — no uses emoji. Estos no son logotipos de marca, así que teñirlos con el color de tinta del diagrama está bien (el script de obtención lo hace automáticamente para Lucide).
• Los íconos de etiqueta de grupo se renderizan a 14px — necesitan una marca de glifo cuadrado. Las marcas de palabra y las composiciones anchas se convierten en barro a ese tamaño; si el ícono principal es una marca de palabra, obtén el ícono cuadrado de la marca por separado para la etiqueta (svgl generalmente lo tiene; de lo contrario, el propio ícono del proyecto o el archivo favicon).
• Las etiquetas de grupo se asientan sobre el matiz del grupo, no sobre un mosaico blanco, así que en el tema oscuro una marca con partes negras desaparece allí. Si fetch_icons.py guardó <nombre>_oscuro, usa el par lt/dk de la plantilla en la etiqueta; si no hay variante oscura y la marca tiene partes negras, agrega la clase plate al <img> de la etiqueta (respaldo blanco, solo tema oscuro).
• Los logotipos rasterizados (png/webp) están bien; la interfaz de usuario aún los coloca y escala como SVG.