Portfolio One Shot

¿Qué hace Portfolio One Shot?

Propósito

Convertir un directorio de trabajo real en un portafolio que se pueda abrir, leer por máquinas y verificar de forma independiente, sin que el modelo escriba una sola línea de texto ficticio de proyecto.

Los tres invariantes, en orden de prioridad:

1. Cero fabricación. Cada hecho mostrado debe remontarse a un archivo, un extracto de README o un valor proporcionado por el usuario. Los campos faltantes se renderizan como espacios visibles. Nunca inventes nombres de proyectos, roles, métricas, clientes, citas, resultados o imágenes.
2. Verificación independiente. Ejecuta el verificador en el resultado antes de informar éxito. Enumera primero los fallos, luego los aciertos. Nunca presentes una lista de criterios verdes como prueba de que el portafolio se ve bien: el juicio visual pertenece al usuario, a ojo.
3. Un solo comando. all realiza escaneo → configuración → construcción → verificación. Un segundo comando es un defecto, no un flujo de trabajo.

Cuándo usarlo

• El usuario dice 一键生成作品集 / 做个作品集 / 把我的项目做成作品集 / build a portfolio from this folder.
• El usuario entrega un directorio de imágenes, videos o carpetas de proyectos y quiere que se presenten.
• El usuario quiere regenerar un portafolio después de agregar o eliminar trabajo.
• El usuario quiere verificar si un portafolio existente tiene evidencia faltante.

No lo uses cuando el usuario quiera un sitio de demostración decorativo con contenido inventado, un estilo visual específico dirigido por arte, o una integración con una plataforma alojada. Esos son trabajos diferentes. No cambies silenciosamente a las reglas de cero fabricación de esta habilidad en ese caso: di la diferencia en voz alta.

El único comando

python scripts/portfolio.py all <SOURCE_DIR> --out <OUTPUT_DIR> --mode <case_study|gallery>

Ejemplo:

python scripts/portfolio.py all "C:/work/mis-proyectos" --out "C:/work/portfolio-dist" --mode gallery

El comando escribe index.html, portfolio.txt, portfolio.md, projects.json, assets/, build-report.json y verify-report.md en el directorio de salida, y luego imprime el veredicto del verificador. Abre index.html para el usuario con la herramienta de presentación de archivos. Pon el entregable visual primero en la lista.

Para reconstruir después de que el usuario edite projects.json, ejecuta solo build y verify:

python scripts/portfolio.py build <OUTPUT_DIR>/projects.json --out <OUTPUT_DIR> --mode gallery
python scripts/portfolio.py verify <OUTPUT_DIR>

Flujo de trabajo

Fase 0 · Decidir el modo, no adivinar en silencio

Existen dos modos porque la investigación de origen encontró que los dos dominios demandan lo opuesto (ver references/content-spec.md §División de dominio).

Modo	Para	Densidad de texto	Diseño
case_study	UX, producto, diseño, ingeniería, investigación	Narrativa larga; siete grupos de campos obligatorios	Un proyecto por sección, imágenes intercaladas
gallery	Arte de juegos, ilustración, arte conceptual, fotografía, animación	Mínimo de palabras; deja que el trabajo hable	Cuadrícula centrada en imágenes, lightbox al hacer clic

Si el usuario no ha elegido, infiere a partir del material y di la inferencia en una frase antes de ejecutar, luego deja que una palabra del usuario la anule. Nunca fijes un valor predeterminado en el portafolio de alguien.

Fase 1 · Escanear material real

scan enumera los subdirectorios como proyectos. Para cada proyecto registra:

• El nombre del directorio como candidato a título del proyecto (un hecho, no una invención).
• Cada archivo de imagen y video con tamaño en bytes, prefijo SHA-256 y dimensiones en píxeles.
• El primer párrafo de README.md / project.md / about.md como candidato de summary textual, con una entrada _sources que nombra el archivo y el rango de líneas.
• Una lista missing de campos que ningún archivo pudo proporcionar.

Los archivos con extensiones desconocidas permanecen en manifest.json como unclassified en lugar de ser eliminados. Nunca borres, renombres, muevas o redimensiones archivos fuente. Escribe solo en el directorio de salida.

Fase 2 · Construir

build lee projects.json (esquema en references/config-schema.md) y renderiza:

• index.html — tema claro, adaptable, pila de fuentes del sistema, sin dependencias de CDN, sin plantilla llamativa. Cada <img> lleva alt, width, height, loading="lazy". Las imágenes usan rutas relativas bajo assets/.
• portfolio.txt — resumen de proyecto en texto plano para análisis ATS y copia a un currículum.
• portfolio.md — los mismos hechos en Markdown para README o correo electrónico.
• Un banner de advertencia visible que indique exactamente cuántos campos faltan, para que un esqueleto nunca pueda confundirse con un portafolio terminado.

Cuando --embed está activado, incrusta solo imágenes de menos de 10 KB como base64 y mantiene las más grandes externas; imprime una advertencia por cada archivo que habría superado el umbral. Base64 aumenta el payload aproximadamente un 33% y no se puede cargar de forma diferida — ver references/content-spec.md §Política de imágenes.

Fase 3 · Verificar antes de informar

verify comprueba la integridad de los campos, la existencia y decodificabilidad de las imágenes, el texto alternativo significativo, la ausencia de hosts de imágenes placeholder, la forma de los enlaces, la estructura HTML y la paridad del texto plano. Escribe verify-report.md con Fallos primero, Aciertos después, luego Limitaciones / no verificado.

El código de salida 1 significa que existen elementos rojos. Infórmalo honestamente. No edites los criterios para que pasen, no reintentes un canal de generación fallido y no ocultes una limitación.

Para un control positivo/negativo, ejecuta python scripts/portfolio.py verify <dir> --self-test — construye un proyecto deliberadamente roto y un proyecto completo en memoria y confirma que el verificador marca el primero y aprueba el segundo. Si el control negativo pasa verde, el verificador está roto; arregla el verificador, no el simulacro.

Fase 4 · Entrega

Presenta index.html primero para que el usuario pueda abrirlo, luego verify-report.md, luego projects.json. En la respuesta de texto: da el veredicto, el número exacto de campos faltantes y la siguiente acción única (rellenar projects.json). No afirmes que el portafolio se ve bien. No afirmes que está listo para enviar mientras el banner de advertencia esté presente.

Contrato de cero fabricación

Reglas estrictas, todas derivadas de modos de fallo documentados en references/content-spec.md:

• Nunca escribas prosa de proyecto, leyendas, roles, métricas, resultados, créditos o nombres de clientes que estén ausentes de la entrada. Un campo faltante se renderiza como [FALTANTE: campo] — conspicuo, nunca en blanco en silencio, nunca parafraseado en una oración plausible.
• Nunca uses hosts de imágenes placeholder (picsum.photos, placehold.co, lorem, URLs de stock) como sustitutos de trabajo real. Un proyecto sin imágenes renderiza un bloque explícito de medios vacío.
• Nunca cites una métrica sin una entrada _sources. Si el usuario proporciona una métrica, registra source: "user-supplied"; no la actualices a "verificada".
• Nunca inventes un nombre de estudio, biografía personal o datos de contacto. Déjalos vacíos y enuméralos como fallos.
• Cuando se use un README, copia el párrafo textualmente y registra su archivo y rango de líneas. No lo pulas, acortes o reescribas.
• No presentes texto asistido por IA como la propia toma de decisiones del usuario. Los campos de proceso y reflexión permanecen vacíos hasta que el usuario los proporcione.

Salida multiversión

El mismo projects.json admite versiones específicas. Agrega una lista select de IDs de proyectos, o pasa --only id1,id2 a build, para producir una versión dirigida a una audiencia. La reordenación es un cambio de configuración, nunca una reescritura automática. Esto sigue la división documentada entre un sitio web para descubrimiento y un PDF o presentación para aplicaciones.

Errores comunes

• No juzgues a partir de un fragmento. Lee todo el README, todo el projects.json y todo el informe del verificador antes de concluir que algo está completo o roto.
• Que los criterios pasen no es calidad. Un verificador verde significa que la estructura del archivo es sólida. La estética requiere los ojos del usuario.
• No rellenes lagunas para que la página parezca terminada. Una página visiblemente incompleta es el resultado correcto cuando el usuario no ha proporcionado los hechos.
• No toques directorios personales. Scan es de solo lectura en la fuente. Todas las escrituras van al directorio de salida.
• No amplíes el alcance a generación de PDF, alojamiento o acceso a la API de GitHub. Esos necesitan una decisión explícita del usuario.
• Las dimensiones de las imágenes importan. Emitir width y height evita el desplazamiento del diseño. Si Pillow no está disponible, recurre al análisis de cabeceras e imprime una advertencia visible; nunca degrade en silencio.
• Una carpeta es un proyecto. Si el material del usuario es plano, pide una agrupación o usa --flat para hacer un proyecto que contenga todos los medios. No inventes agrupaciones.

Recursos

Ruta	Rol
scripts/portfolio.py	CLI único: scan, build, verify, all, --self-test. Biblioteca estándar más Pillow opcional.
references/content-spec.md	Reglas de contenido respaldadas por investigación, división de dominio, política de imágenes y URLs de origen. Cárgalo antes de cambiar definiciones de campos o plantillas.
references/config-schema.md	Esquema completo de projects.json, significados de los campos y qué cuenta como fuente.
assets/template.html	Plantilla receptiva de tema claro con ambos modos. Reemplaza solo los marcadores {{TOKEN}}; no reescribas el CSS para perseguir un estilo.
assets/projects.sample.json	Una configuración DEMO claramente etiquetada. Nunca la envíes como el portafolio real del usuario.