yokingma/flow-diagram

Diagrama de Flujo

El Diagrama de Flujo es la habilidad de autoría para diagramas ejecutables de sistemas y procesos: autorice una vez, luego reproduzca, incruste, inspeccione y exporte el resultado.

Convierta descripciones y material fuente en explicaciones visuales: diagramas estáticos o animados que hacen claras las estructuras, relaciones y procesos. El objetivo es preservar el significado de la fuente y ayudar a los lectores a comprender cómo se organizan, conectan y cambian las cosas con el tiempo.

Elija la tarea

Esta habilidad produce activos de diagrama; los archivos PPTX y las formas nativas de PowerPoint están fuera de su alcance.

Identifique el tipo de tarea, la entrada a utilizar y dónde ingresar o reanudar el proceso.

Solicitud	Punto de inicio
Nuevo diagrama o importación JSON que se autorizará o revisará	Complete la verificación previa de preferencias, luego siga los cinco pasos. Preserve los bytes importados sin cambios cuando sea necesario.
Importación JSON sin cambios para exportación o inspección	Utilice el punto de entrada de exportación o diagnóstico; omita la verificación previa de preferencias y mantenga el diseño de entrada.
Revisar un diagrama finalizado	Lea el diagrama existente y el informe final. Establezca los cambios y el alcance solicitados, complete la verificación previa de preferencias, luego siga el proceso de cinco pasos, reutilizando las decisiones de diseño que sigan siendo válidas. Continúe con los formatos solicitados a menos que el usuario los cambie.
Agregar solo formatos de exportación	Ingrese en el paso 3 con el diagrama existente sin cambios. Omita los cambios de borrador, estilo, medición y diseño, luego inspeccione y finalice los archivos solicitados.
Continuar una tarea inconclusa	Lea los registros de la tarea y seleccione la revisión guardada para continuar. Reanude en los pasos inconclusos o aquellos afectados por los cambios.
Solo validación o diagnóstico	Use validate para comprobaciones estructurales. Si se solicita un diagnóstico visual, siga los flujos de trabajo de inspección aplicables en el paso 4. Informe las comprobaciones realizadas, sus límites y los problemas descubiertos, luego deténgase.

Para solicitudes independientes de guardado, cambio o restablecimiento, siga las preferencias del proyecto e informe la operación sin crear un diagrama.

Para importaciones, revisiones o exportaciones de diagramas existentes, lea selección de entrada y padre. Antes de crear archivos de tarea, lea requisitos del espacio de trabajo de la tarea; para comandos de validación y estados de informe, lea contratos de tiempo de ejecución y resultado.

Proceda cuando la entrada, los cambios autorizados y el punto de entrada del proceso estén claros.

Proceso

0. Inicializar preferencias de diseño

Para borradores nuevos y revisados, siga preferencias del proyecto antes del paso 1. Complete su verificación previa resolviendo las opciones visuales relevantes y registrando sus fuentes; finalice cualquier guardado solicitado o revele su fallo. Las solicitudes independientes de gestión de preferencias usan esa referencia y se detienen después de informar la operación. Las tareas de exportación, validación y diagnóstico puras mantienen sus puntos de entrada existentes. Reanude las tareas inconclusas con sus decisiones registradas, revisando la verificación previa solo cuando una opción relevante cambie.

1. Definir el objetivo de la explicación

Comience con la pregunta del lector: ¿qué debería entender el lector después de ver el diagrama? Use esta pregunta para guiar las decisiones posteriores de contenido, diseño y animación.

• Defina la pregunta. Identifique el tema y lo que el lector debería entender de la solicitud del usuario.

• Establezca los hechos. Lea las fuentes designadas por el usuario o el diagrama existente dentro del alcance autorizado. Identifique objetos, relaciones, procesos y cambios de estado relevantes. Distinga los hechos conocidos de la información que necesita aclaración y registre las fuentes a través de metadatos de fuente.

  Para investigaciones amplias, como explorar un repositorio de código, genere un subagente para investigar las partes relevantes para la pregunta del lector. Dé al subagente la pregunta y el alcance de fuente autorizado. Solicite objetos, relaciones, procesos y cambios de estado relevantes, con ubicaciones de fuente y preguntas sin resolver. Use esos hallazgos para establecer los hechos necesarios para la explicación.

  Para unos pocos artículos, un conjunto pequeño de materiales de referencia o una solicitud breve como "Explique el flujo de trabajo RAG con un diagrama de flujo", establezca los hechos en la sesión actual.

• Registre los requisitos. Capture la audiencia, el contexto de uso y los requisitos de entrega ya especificados por el usuario. Siga contexto de entrega faltante para reutilizar opciones conocidas, recopile las brechas relevantes una vez y registre las suposiciones adoptadas antes de elegir la geometría.

Proceda cuando pueda expresar la pregunta del lector en una oración e identificar los hechos que respaldan su respuesta. Aclare las brechas de información que cambiarían el significado del diagrama antes de redactar. Si el SDK no puede expresar la solicitud fielmente, explique el límite y espere la elección del usuario.

2. Diseñar la explicación visual

Elija cómo presentar el tema para que el lector pueda responder la pregunta definida en el paso 1.

Para borradores nuevos o revisados, lea contextos de entrega antes de elegir el lienzo y la densidad, incluso cuando el propósito sea desconocido. Use la tabla de selección por pregunta del lector para inventarios de capacidades, responsabilidades, estado de recursos, solicitudes y respuestas, transiciones de estado, procesamiento de datos o arquitectura.

• Seleccione el contenido. Elija los objetos, relaciones, procesos y estados necesarios para la explicación. Antes de omitir o agregar contenido, o decidir cómo presentar información de fuente desconocida, lea fidelidad de fuente y opciones de información. Preserve el significado de la fuente en estas elecciones.
• Asigne contenido a su superficie. Antes de la geometría del diagrama, siga asignación de contenido para asignar introducciones de página, etiquetas vinculadas al diagrama, leyendas y prosa de apoyo. Registre la asignación y el contexto requerido por cada formato solicitado.
• Organice la estructura. Defina grupos, jerarquía y orden de lectura para que el lector pueda identificar los puntos principales y seguir sus relaciones.
• Establezca la dirección visual. Siga diseño visual para seleccionar una dirección para el contexto de uso. Para estructuras en capas con una barra lateral, procesos con ramificaciones o retornos, o tarjetas repetidas con contenido más largo, seleccione una receta de composición aplicable. Registre las opciones concretas requeridas para la producción.
• Elija diagramas estáticos o animación. Use diseño estático para explicar estructuras y relaciones. Para animación, distinga flujo de relación persistente, atención y cambio por etapas; una solicitud de líneas fluidas puede mantener todo el diagrama visible.
• Planifique la narrativa de animación. Al usar animación, siga ritmo de animación y continuidad visual para definir el objetivo de explicación de cada etapa, cambios de estado, transiciones y pausas de lectura.

Proceda cuando el plan registre el contenido seleccionado, sus superficies portadoras, grupos, orden de lectura, opciones visuales y presentación estática o animada. Para animación, incluya el plan de etapas.

3. Crear el diagrama

Implemente el diseño del paso 2 y genere los artefactos necesarios para la inspección en el paso 4.

Use Node 20+ y npm. Ejecute node <directorio-de-habilidad>/scripts/flowsvg.mjs desde el directorio de trabajo elegido por el usuario, con rutas entrecomilladas cuando sea necesario. Resuelva herramientas y recursos de tarea dentro de esta habilidad instalada. La CLI prepara su propio tiempo de ejecución SDK fijo sin cambiar las dependencias de la aplicación.

• Lea la guía de autoría relevante. Para borradores nuevos o revisados, lea el modelo de documento y guía de diseño, e implemente las recetas de diseño seleccionadas. Antes de organizar la geometría, consulte problemas comunes de renderizado para rutas cortas con etiquetas largas, barras laterales, texto sin bordes, tarjetas estrechas o riesgos de ajuste en cualquier idioma, alineación óptica de etiquetas cortas, bordes de lectura compartidos o tamaños de contenido cambiados. Para animación, lea también escenas, estado heredado y temporización. Para archivos SVG, PNG o GIF solicitados, lea opciones y límites de exportación.
• Construya el documento del diagrama. Para borradores nuevos o revisados, implemente los objetos, grupos, conexiones, texto y etapas de animación planificados. Preserve el idioma de la fuente y la dirección visual seleccionada. Para un nuevo diagrama sin una dirección especificada, comience con un tema claro y grupos redondeados. Mida el texto en el borrador completo y siga el flujo de trabajo del plan de diseño cuando la geometría repetida necesite un plan. Compare cada objeto, dirección de relación, límite principal y cambio de estado con las fuentes. Guarde los cambios autorizados en un nuevo borrador del espacio de trabajo; para una importación o exportación sin cambios, use los bytes de entrada seleccionados directamente.
• Valide y corrija. Use validate (solo lectura) durante la iteración y lea cada diagnóstico. Devuelve la identidad exacta de la entrada y comprobaciones finitas sin crear una revisión del diagrama; mantenga el borrador de trabajo. Aplique correcciones dentro de la autorización actual, siguiendo decisiones de diagnóstico y revisión. Aclare las correcciones que cambiarían el significado de la explicación con el usuario.
• Componga la página HTML. Para explicaciones HTML nuevas o revisadas, escriba el HTML/CSS de la página para el contenido asignado fuera del diagrama y envíelo a través de páginas HTML editables. Para un resultado existente, siga continuación de página para preservar su diseño y sincronizar explícitamente los cambios de diagrama previstos. Reutilice el iniciador instalado para páginas nuevas cuando sea útil; preserve la región del reproductor gestionada y mantenga la página completa en el espacio de trabajo de la tarea.
• Genere artefactos de inspección. Antes de la captura del navegador o de elegir un recuento de muestras de vista previa, lea preparación del navegador y muestreo. Use author para producir el HTML sin conexión requerido, las vistas previas necesarias y los archivos de exportación solicitados. Use author --browser none cuando solo se necesite HTML intermedio. Para varios estados estáticos nombrados, siga exportaciones por lotes nombradas; confirme los tiempos seleccionados a partir de los tiempos reales compilados con el usuario antes de vincular el manifiesto. Siga los contratos de tiempo de ejecución y resultado para la configuración, compatibilidad SDK y campos de informe; use --help de la CLI para opciones de comando.

Proceda cuando el borrador implemente el plan, o se preserve una entrada sin cambios, los errores bloqueantes estén resueltos, los diagnósticos restantes tengan decisiones de manejo registradas y todos los archivos requeridos para la inspección estén completos. En caso de fallo de exportación, siga las reglas de recuperación a continuación e informe los archivos completados y no completados por separado.

4. Inspeccionar el resultado

Para SVG/PNG entregado, siga evidencia de artefacto bajo demanda: ejecute evidence contra el sujeto guardado explícito, luego vea y revise independientemente sus imágenes. Las condiciones válidas existentes se reutilizan; las condiciones nuevas permanecen sin ver hasta que se inspeccionen.

Vea el diagrama generado y confirme que explica el tema de manera precisa y clara.

• Verifique la precisión semántica. Compare objetos, direcciones de relación, límites de grupo y cambios de estado con las fuentes. Confirme que las omisiones y agregaciones preserven el significado de la fuente.
• Verifique la legibilidad visual. Vea las imágenes renderizadas reales al tamaño de pantalla previsto. Inspeccione texto, espaciado, oclusión y orden de lectura. Trace cada conexión relevante desde su fuente a través de curvas y cruces hasta su punta de flecha; verifique puertos, etiquetas y espacio libre de nodos no relacionados.
• Evalúe el diseño visual. Siga inspección de diseño visual para identificar defectos visibles y registrar observaciones para el juicio de diseño final del usuario.
• Verifique la explicación de animación. Para animación, inspeccione el estado inicial, los cambios clave y el estado final contra el plan de etapas. Siga inspección de vista previa para estados muestreados. Use la reproducción real al evaluar el ritmo; informe la inspección solo de muestras como limitada a los estados vistos.
• Verifique los archivos entregados. Haga que la herramienta abra el HTML sin conexión guardado real y verifique su estado de pausa inicial, controles, solicitudes sin conexión y estados de reproducción relevantes. Vea sus imágenes capturadas a través del flujo de trabajo de inspección HTML. Inspeccione los archivos de exportación solicitados tal como se entregaron; use inspección de artefacto de tamaño objetivo para archivos SVG/PNG finales.

Antes de enviar revisiones, lea los contratos de entrada de revisión completos y el flujo de trabajo de plantilla. Genere un formulario no visto con review-template a partir del sujeto de diagrama explícito y, para evidencia formal separada, --evidence-from, luego use review independiente para observaciones HTML, de vista previa y SVG/PNG formales y registre los IDs, hashes, observaciones y problemas solo para las imágenes realmente vistas. El envío repetido de revisión no requiere otra versión del diagrama. Cuando un navegador o visor de imágenes no esté disponible, registre las comprobaciones no realizadas y su impacto explícitamente.

Para problemas descubiertos, regrese al paso 3 para aplicar correcciones autorizadas, regenerar los artefactos e inspeccionar los archivos afectados y estados nuevamente. Siga decisiones de diagnóstico y revisión al registrar problemas o aclarar medidas.

5. Finalizar

Cree el informe final y entregue los archivos solicitados.

• Escriba el informe. Prepare el informe de explicación final para el diagrama resultante. Siga la plantilla de informe de explicación y complete todos los campos. Cuando la inspección se basó en artefactos de vista previa en lugar de archivos finales, incluya esa limitación.
• Organice los archivos de salida. Dentro del directorio de entrega, coloque el informe final, el diagrama del documento de origen (el archivo .flow.json generado), la página HTML completamente renderizada y todos los archivos de exportación solicitados. Los nombres de archivo y rutas se definen en contratos de salida.
• Informe las exportaciones fallidas. Si alguna(s) exportación(es) fallaron, siga las reglas a continuación: intente la exportación fallida con una CLI diferente; si falla, informe las exportaciones fallidas, el error y el estado de los archivos existentes.
• Cierre la tarea. Asegúrese de que todos los artefactos de la tarea estén dentro del directorio de entrega antes de informar el trabajo completado. Cuando la tarea continúa para una revisión, informe al usuario el estado actual y los pasos restantes. Cuando el usuario solicite un cambio o actualización, siga los pasos de revisión en la tabla de selección de tareas al comienzo de este documento.

Proceda cuando el informe final esté listo y todos los archivos requeridos estén organizados en el directorio de entrega con el estado de exportación informado.

[truncated for translation]