Portfolio One Shot

O que Portfolio One Shot faz?

Propósito

Transforme um diretório de trabalhos reais em um portfólio que pode ser aberto, lido por máquinas e verificado de forma independente — sem que o modelo escreva uma única linha de texto ficcional de projeto.

Os três invariantes, em ordem de prioridade:

1. Zero fabricação. Cada fato exibido deve ser rastreável até um arquivo, um trecho de README ou um valor fornecido pelo usuário. Campos ausentes são renderizados como lacunas visíveis. Nunca invente nomes de projetos, cargos, métricas, clientes, citações, resultados ou imagens.
2. Verificação independente. Execute o verificador na saída antes de relatar sucesso. Liste as falhas primeiro, os sucessos depois. Nunca apresente uma lista verde de critérios como prova de que o portfólio tem boa aparência — o julgamento visual pertence ao usuário, a olho nu.
3. Um comando. all executa varredura → configuração → construção → verificação. Um segundo comando é um defeito, não um fluxo de trabalho.

Quando usar

• O usuário diz '一键生成作品集' / '做个作品集' / '把我的项目做成作品集' / 'build a portfolio from this folder'.
• O usuário entrega um diretório de imagens, vídeos ou pastas de projetos e deseja que sejam apresentados.
• O usuário quer regenerar um portfólio após adicionar ou remover trabalhos.
• O usuário quer verificar se um portfólio existente possui evidências faltantes.

Não use quando o usuário deseja um site de demonstração decorativo com conteúdo inventado, um estilo visual específico com direção de arte ou integração com uma plataforma hospedada. Esses são trabalhos diferentes. Não mude silenciosamente para as regras de zero fabricação desta skill nesse caso — diga a diferença em voz alta.

O comando único

python scripts/portfolio.py all <DIRETORIO_ORIGEM> --out <DIRETORIO_SAIDA> --mode <case_study|gallery>

Exemplo:

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

O comando escreve index.html, portfolio.txt, portfolio.md, projects.json, assets/, build-report.json e verify-report.md no diretório de saída e, em seguida, imprime o veredito do verificador. Abra index.html para o usuário com a ferramenta de apresentação de arquivos. Coloque a entrega visual primeiro na lista.

Para reconstruir após o usuário editar projects.json, execute apenas build e verify:

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

Fluxo de trabalho

Fase 0 · Decida o modo, não adivinhe silenciosamente

Existem dois modos porque a pesquisa de origem descobriu que os dois domínios exigem coisas opostas (veja references/content-spec.md §Divisão de domínio).

Modo	Para	Densidade de texto	Layout
case_study	UX, produto, design, engenharia, pesquisa	Narrativa longa; sete grupos de campos obrigatórios	Um projeto por seção, imagens intercaladas
gallery	Arte de jogo, ilustração, arte conceitual, fotografia, animação	Mínimo de palavras; deixe o trabalho falar	Grade com foco em imagens, lightbox ao clicar

Se o usuário não escolheu, infira a partir do material e diga a inferência em uma frase antes de executar — então deixe uma palavra do usuário substituí-la. Nunca codifique um padrão no portfólio de alguém.

Fase 1 · Digitalize o material real

scan enumera subdiretórios como projetos. Para cada projeto, registra:

• Nome do diretório como candidato a título do projeto (um fato, não uma invenção).
• Cada arquivo de imagem e vídeo com tamanho em bytes, prefixo SHA-256 e dimensões em pixels.
• O primeiro parágrafo de README.md / project.md / about.md como um candidato a summary literal, com uma entrada _sources nomeando o arquivo e o intervalo de linhas.
• Uma lista missing de campos que nenhum arquivo pôde fornecer.

Arquivos com extensões desconhecidas permanecem em manifest.json como unclassified em vez de serem descartados. Nunca delete, renomeie, mova ou redimensione arquivos de origem. Escreva apenas no diretório de saída.

Fase 2 · Construção

build lê projects.json (esquema em references/config-schema.md) e renderiza:

• index.html — tema claro, responsivo, pilha de fontes do sistema, sem dependências de CDN, sem template chamativo. Cada <img> carrega alt, width, height, loading="lazy". Imagens usam caminhos relativos em assets/.
• portfolio.txt — resumo do projeto em texto puro para análise ATS e copiar/colar em um currículo.
• portfolio.md — os mesmos fatos em Markdown para README ou e-mail.
• Um banner de aviso visível informando exatamente quantos campos estão ausentes, para que um esqueleto nunca seja confundido com um portfólio finalizado.

Quando --embed está definido, incorpore apenas imagens com menos de 10 KB como base64 e mantenha as maiores como externas; imprima um aviso para cada arquivo que excederia o limite. O payload base64 cresce cerca de 33% e não pode ser carregado com lazy load — veja references/content-spec.md §Política de imagem.

Fase 3 · Verifique antes de relatar

verify verifica a completude dos campos, existência e decodificação de imagens, texto alternativo significativo, ausência de hosts de imagens placeholder, formato de links, estrutura HTML e paridade de texto puro. Escreve verify-report.md com Falhas primeiro, Sucessos depois, depois Limitações / não verificado.

Código de saída 1 significa que existem itens vermelhos. Relate isso honestamente. Não edite os critérios para fazê-los passar, não tente novamente um canal de geração com falha e não esconda uma limitação.

Para um controle positivo/negativo, execute python scripts/portfolio.py verify <dir> --self-test — ele constrói um projeto deliberadamente quebrado e um projeto completo em memória e confirma que o verificador sinaliza o primeiro e aprova o segundo. Se o controle negativo passar verde, o verificador está quebrado; corrija o verificador, não o cenário de teste.

Fase 4 · Entrega

Apresente index.html primeiro para que o usuário possa abri-lo, depois verify-report.md, depois projects.json. Na resposta em texto: dê o veredito, o número exato de campos ausentes e a próxima ação única (preencher projects.json). Não afirme que o portfólio tem boa aparência. Não afirme que está pronto para enviar enquanto o banner de aviso estiver presente.

Contrato de zero fabricação

Regras rígidas, todas derivadas de modos de falha documentados em references/content-spec.md:

• Nunca escreva prosa de projeto, legendas, cargos, métricas, resultados, créditos ou nomes de clientes que estejam ausentes da entrada. Um campo ausente é renderizado como [MISSING: campo] — evidente, nunca silenciosamente em branco, nunca parafraseado em uma frase plausível.
• Nunca use hosts de imagem placeholder (picsum.photos, placehold.co, lorem, URLs de stock) como substitutos para trabalhos reais. Um projeto sem imagens renderiza um bloco de mídia vazio explícito.
• Nunca cite uma métrica sem uma entrada _sources. Se o usuário fornecer uma métrica, registre source: "fornecido-pelo-usuario"; não a atualize para "verificada".
• Nunca invente um nome de estúdio, biografia pessoal ou detalhes de contato. Deixe-os vazios e liste-os como falhas.
• Quando um README for usado, copie o parágrafo literalmente e registre seu arquivo e intervalo de linhas. Não polia, encurte ou reescreva.
• Não apresente texto auxiliado por IA como a própria decisão do usuário. Os campos de processo e reflexão permanecem vazios até que o usuário os forneça.

Saída com múltiplas versões

O mesmo projects.json suporta versões direcionadas. Adicione uma lista select de IDs de projetos, ou passe --only id1,id2 para build, para produzir uma versão voltada para um público. A reordenação é uma alteração de configuração, nunca uma reescrita automática. Isso segue a divisão documentada entre um site para descoberta e um PDF ou deck para candidaturas.

Armadilhas

• Não julgue a partir de um fragmento. Leia o README inteiro, o projects.json inteiro e o relatório do verificador inteiro antes de concluir que algo está completo ou quebrado.
• Critérios aprovados não são qualidade. Um verificador verde significa que a estrutura do arquivo é sólida. A estética exige os olhos do usuário.
• Não preencha lacunas para fazer a página parecer finalizada. Uma página visivelmente incompleta é a saída correta quando o usuário não forneceu os fatos.
• Não toque em diretórios pessoais. A varredura é somente leitura na origem. Todas as gravações vão para o diretório de saída.
• Não aumente o escopo para geração de PDF, hospedagem ou acesso à API do GitHub. Isso requer uma decisão explícita do usuário.
• Dimensões de imagem importam. Emitir width e height evita mudanças de layout. Se o Pillow não estiver disponível, recorra à análise de cabeçalho e imprima um aviso visível; nunca degrade silenciosamente.
• Uma pasta é um projeto. Se o material do usuário estiver plano, peça um agrupamento ou use --flat para fazer um projeto contendo toda a mídia. Não invente agrupamentos.

Recursos

Caminho	Função
scripts/portfolio.py	CLI única: scan, build, verify, all, --self-test. Biblioteca padrão mais Pillow opcional.
references/content-spec.md	Regras de conteúdo baseadas em pesquisa, divisão de domínio, política de imagem e URLs de origem. Carregue antes de alterar definições de campo ou modelos.
references/config-schema.md	Esquema completo de projects.json, significados dos campos e o que conta como fonte.
assets/template.html	Template responsivo de tema claro com ambos os modos. Substitua apenas os placeholders {{TOKEN}}; não reescreva o CSS para buscar uma aparência.
assets/projects.sample.json	Um config DEMO claramente rotulado. Nunca o envie como o portfólio real do usuário.