yizhiyanhua-ai/fireworks-open-eli5

Fireworks Open ELI5

Convierte un sistema difícil en una historia visual veraz. Produce primero una especificación JSON portátil y luego un explicador HTML determinista y autocontenido.

Límite innegociable

• La evidencia va antes que el pulido visual. Etiqueta cada elemento de evidencia como verified, inferred o analogy.
• Nunca hagas que una analogía parezca una verdad de implementación.
• Un archivo HTML local generado es solo generated. No está published, subido, enviado ni verificado como destino.
• No publiques, subas, envíes ni cambies el acceso sin la solicitud explícita del usuario y la verificación del flujo de trabajo de destino.
• El renderizado no realiza llamadas de red. Una URL citada es un enlace para el lector, no una dependencia en tiempo de ejecución. La acción opcional de Pages nativa solo puede llamar al ayudante empaquetado del mismo origen en 127.0.0.1; nunca debe contactar un servicio remoto.
• El historial local del navegador, los favoritos y las anotaciones están deshabilitados hasta que el lector los acepte. Son estado de conveniencia, no evidencia, y nunca modifican la especificación fuente ni el artefacto generado.
• Describe el historial con precisión como explicadores del mismo origen previamente abiertos en ese navegador. Nunca afirmes que enumera todos los archivos generados.
• La exportación a PDF invoca el diálogo de impresión del navegador. PNG exporta una escena; PPTX y DOCX compatible con Pages exportan una escena por diapositiva o página. La salida nativa .pages solo se permite después de que la aplicación Pages instalada realmente la guarde; nunca renombres un DOCX a .pages. Las descargas generadas son solo artefactos locales.

Flujo de trabajo

1. Identifica la audiencia, la pregunta, el idioma y una cosa que debe viajar a través de la historia: una solicitud, paquete, decisión, evento o acción del usuario.

2. Elige exactamente una gramática de historia:

   • concepto: intuición → mecanismo → límite.
   • módulo: punto de entrada → transformaciones → salidas/dependencias.
   • compensación: objetivo compartido → opciones en competencia → consecuencias/regla de decisión.
   • incidente: camino normal → ruptura y propagación → detección/recuperación.

3. Recolecta evidencia. Para trabajo con repositorios, inspecciona los archivos reales y usa rutas locales. Para afirmaciones externas, usa fuentes autorizadas cuando estén disponibles. Registra la incertidumbre explícitamente.

4. Crea una especificación JSON versión 1 siguiendo references/spec-contract.md. Usa 3–7 escenas, 2–6 nodos por escena, una escala de veracidad completa, traza, glosario, comprobación didáctica, mapa de evidencia y los modeData requeridos específicos del modo. Agrega información de fallo a los nodos que lo requieran.

5. Valida antes de renderizar:

   node scripts/validate.mjs path/to/spec.json
   

6. Renderiza a un nuevo archivo local:

   node scripts/render.mjs path/to/spec.json path/to/explainer.html
   

   El renderizador rechaza una ruta existente. Solo cuando el usuario quiere explícitamente reemplazar un archivo regular conocido, añade --force. El renderizado forzado usa un reemplazo atómico y aún rechaza enlaces simbólicos y rutas que no sean archivos.

7. Valida la especificación y el artefacto juntos:

   node scripts/validate.mjs path/to/spec.json path/to/explainer.html
   

8. Cuando el acceso al navegador esté disponible, inspecciona el artefacto local con ancho de escritorio y 390px. Confirma un h1, etiquetas legibles, sin desbordamiento horizontal, foco de teclado, tablists independientes, reproducción global y por escena, seguimiento del viewport, sincronización activa entre el borde real y la tarjeta de evidencia, fases de animación de entrada/mantener/salida, lente de fallo, revelación de respuestas y cero solicitudes de recursos remotos. Cada tarjeta de evidencia de escena debe exponer su estado, base central concisa, alcance de soporte y una URL o límite explícito de "sin localizador".

9. Ejercita el espacio de trabajo del lector: abre y cierra el cajón modal con ratón y teclado; confirma el retorno del foco; habilita la biblioteca intencionalmente; recarga y verifica favoritos y una anotación de texto plano; y confirma que el historial contiene solo explicadores del mismo origen que se abrieron realmente. Usa una anotación con forma de marcado para verificar que permanece como texto inerte.

10. Ejercita la exportación: confirma la hoja de estilo de impresión, la firma y dimensiones PNG, las firmas ZIP de PPTX y DOCX y las partes OOXML requeridas, y el enlace de descarga de respaldo cuando las descargas automáticas están suprimidas. Confirma visualmente que el artefacto de la escena incluye un pie de página de evidencia con estado, base central y localizador de fuente o límite. Cuando Pages nativo esté en alcance, ejecuta scripts/serve.mjs, verifica que el paquete .pages contenga Index/Document.iwa, luego vuelve a abrirlo en Pages. Arregla la especificación o plantilla y vuelve a ejecutar ambos validadores después de cualquier cambio.

Idioma del informe

• Escribe el informe final de QA, estado, entrega y artefacto generado en el idioma de la última solicitud sustantiva del usuario por defecto.
• Una solicitud explícita de idioma del informe anula ese valor por defecto.
• spec.language controla solo la interfaz del explicador generado; no fuerza el idioma del informe de la conversación.
• En conversaciones multilingües, ignora los acuses de recibo cortos al elegir el idioma del informe. Conserva el código, comandos, rutas, identificadores, errores exactos y títulos de fuentes cuando la traducción reduciría la precisión.

Lee references/reporting.md para el contrato completo de selección de idioma y entrega de informes.

Reglas de construcción de historias

• Escribe el título como una promesa concreta, no como una etiqueta de categoría.
• Mantén el resumen en una oración y cada nodo en una responsabilidad.
• Prefiere 3–5 escenas. Usa 6–7 solo cuando omitir una etapa distorsionaría la causalidad.
• Las aristas son relaciones o acciones. Usa verbos cortos en las etiquetas.
• La traza debe visitar IDs de nodos reales en un orden significativo.
• Usa datos de fallo solo cuando se conozcan el impacto, el síntoma visible y la alternativa.
• Mantén la capa simple lo suficientemente precisa como para que sobreviva a la capa técnica.
• Pon las limitaciones en truthLadder.caveat, no en pequeños descargos.
• Usa IDs de fuentes en las escenas o nodos que respaldan.
• No cites una fuente solo porque está adyacente a la afirmación.

Lee references/story-grammars.md para patrones de modo, references/evidence-rules.md para límites de afirmaciones, y references/visual-system.md antes de cambiar el lenguaje visual del renderizador. Lee references/library-and-export.md antes de cambiar el comportamiento de persistencia, navegación, reproducción o exportación.

Puerta de calidad

El trabajo está listo como artefacto local solo cuando:

• el validador devuelve ok: true para la especificación y el HTML renderizado;
• todos los IDs y referencias se resuelven;
• cada sección interactiva requerida tiene contenido;
• el modo de historia seleccionado pasa su propio contrato semántico;
• el HTML es determinista y lleva la meta etiqueta SHA-256 de la especificación;
• el artefacto coincide byte a byte con la especificación suministrada y usa hashes CSP de confianza;
• el artefacto no tiene recursos externos, APIs de tiempo de ejecución inseguras ni fuentes remotas;
• el estado persistido del lector es optativo, con espacios de nombres, acotado, del mismo origen y se mantiene fuera del hash determinista de la especificación;
• las anotaciones se renderizan solo como texto y no pueden crear marcado ejecutable;
• la reproducción global y local comparten una máquina de estados y nunca se ejecutan juntas;
• cada paso de la traza activa la ruta de relación saliente real (o la ruta entrante de un sumidero), mantiene la etiqueta y la flecha alineadas, y resalta solo la evidencia que respalda ese paso;
• las tarjetas de evidencia de escena preservan los límites de verificado/inferido/analogía y exponen texto central más un localizador accionable sin obtener vistas previas remotas;
• los paquetes PNG, PPTX y DOCX de la escena tienen las firmas y estructura esperadas y contienen su pie de evidencia; una exportación nativa de Pages reclamada también se ha vuelto a abrir en Pages;
• la versión móvil usa el flujo apilado en lugar de reducir el SVG de escritorio;
• el informe final sigue el idioma de interacción actual del usuario, nombra las rutas de la especificación y el HTML generados, y dice si se ejecutaron las pruebas de QA de escritorio, móvil, persistencia, reproducción, evidencia y exportación en el navegador.

Si la evidencia está incompleta, genera solo cuando el mapa de evidencia y la advertencia hagan la brecha inconfundible. De lo contrario, detente y reporta la evidencia faltante.