locivan3win/luu-media

Armazenar mídia

O repositório guarda conhecimento e links, Cloudinary guarda arquivos pesados. Cada salvamento gera um link acessível e uma linha em kho-media.md.

Ordem de prioridade: fala do usuário na sessão, depois arquivo de regras do repositório, depois esta skill.

Instalação inicial (executar apenas se o repositório ainda não tiver kho-media.md)

1. Pergunte ao usuário se já possui conta no Cloudinary. Se não, instrua: acesse cloudinary.com, cadastre-se no plano gratuito, vá em API Keys para obter Cloud name, API Key e API Secret.

2. As chaves ficam no arquivo .env na raiz do repositório. Se o repositório não tiver .env, crie com as 3 linhas abaixo; se já tiver, adicione as linhas faltantes sem alterar as demais. Se a máquina já tiver outro arquivo contendo essas 3 chaves e o usuário quiser usá-lo, informe o caminho desse arquivo no lugar de .env.

   CLOUDINARY_CLOUD_NAME=
   CLOUDINARY_API_KEY=
   CLOUDINARY_API_SECRET=
   

3. Se o repositório usa Git, execute git check-ignore -q .env. Se não estiver ignorado, adicione .env ao .gitignore antes de prosseguir. Se .env já foi versionado no Git, pare e avise o usuário.

4. Abra .env para o usuário: Windows notepad .env, Mac open -e .env. Peça que colem manualmente as chaves após o sinal =, sem espaços ou aspas, depois salvem, sem colar no chat. O API Secret é como a chave do cofre. Quem o tiver pode apagar ou alterar todas as imagens.

5. Quando o usuário confirmar, verifique se as 3 linhas têm valor, mas apenas verifique se estão preenchidas ou vazias, sem imprimir os valores.

6. Crie kho-media.md conforme o modelo no final deste arquivo, escreva o nome do arquivo de chaves, não o valor. Adicione uma linha em index.md.

7. Peça ao usuário uma imagem de teste, execute o fluxo abaixo e envie o link. Se abrir, está pronto.

Fluxo de salvamento

1. Precisa ir para a nuvem?

Pergunte onde a imagem será usada, se não estiver claro.

• Precisa de link público (postagem, email, bot, documento, site hospedado em outra plataforma): continue.
• O site já tem uma pasta de imagens e está carregando imagens de lá: não envie para a nuvem, pois haveria duas versões divergentes. Sugira copiar para a pasta de imagens do site com um nome limpo; copie somente se o usuário concordar. Pare aqui.
• Rascunho, teste, captura de tela temporária: mantenha na máquina, explique o motivo. Se houver dúvida, pergunte: "Você vai usar isso para quê?"

2. Há duplicata?

Procure o nome e o propósito em kho-media.md. Se já existir, forneça o link antigo e pergunte se o usuário deseja enviar uma nova versão. Se o usuário só pediu para encontrar um link, responda a partir daqui e pare.

3. Há exposição de informações privadas?

Links públicos são visíveis para qualquer pessoa que os tenha e difíceis de revogar após compartilhados. Observe o conteúdo da imagem. Se houver rostos ou nomes de clientes, crianças, números de telefone, números de conta, documentos ou mensagens privadas, informe claramente o que foi visto e pergunte se o usuário tem certeza de querer publicar.

4. Organizar em pastas e nomear

Pasta	O que contém	Onde registrar o link
kho-media/thuong-hieu	Logotipos, retratos, capas, identidade visual	Página da marca ou perfil
kho-media/san-pham/<ten-san-pham>	Imagens de produto, mockups, vídeos de apresentação	Página do respectivo produto
kho-media/noi-dung/<yyyy-MM>	Imagens de postagens, banners, thumbnails, vídeos curtos	Página do plano de conteúdo
kho-media/bang-chung	Feedbacks, antes/depois, certificações, imprensa	Página do produto relacionado
kho-media/su-kien/<ten-su-kien>	Fotos e vídeos de eventos, aulas	Página do respectivo evento

Nome do arquivo e da pasta: sem acentos, minúsculo, separado por -, autoexplicativo, ex: feedback-khach-lan-a. Se não tiver certeza da pasta, faça uma pergunta com 2 opções numeradas. Múltiplos arquivos: apresente uma tabela com nomes e pastas de uma vez, revise e envie sequencialmente; arquivos com erro registre e prossiga com os demais.

5. Enviar para a nuvem

Obtenha o nome do arquivo de chaves de kho-media.md, use o caminho completo. Se o repositório usa Git, execute git check-ignore -q <caminho-do-arquivo-de-chaves> antes: se não estiver ignorado, pare e avise o usuário. Copie o comando exato conforme o sistema operacional, apenas substitua os 4 valores no início. Não imprima as chaves na tela, nem copie para respostas, páginas ou outros arquivos. O comando copia o arquivo para um nome temporário sem acentos, pois caminhos com acentos ou espaços podem causar erros no upload.

Windows (PowerShell):

$tep='<caminho-do-arquivo>'; $ngan='<pasta>'; $ten='<nome-sem-extensao>'; $fileMa='<caminho-do-arquivo-de-chaves>'
$m=@{}; Get-Content -LiteralPath $fileMa | ForEach-Object { if($_ -match '^\s*(?:CLOUDINARY_)?(CLOUD_NAME|API_KEY|API_SECRET)\s*=\s*(.+?)\s*$'){ $m[$Matches[1]]=$Matches[2] } }
$ts=[DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
$bam=[Security.Cryptography.SHA1]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes("folder=$ngan&overwrite=false&public_id=$ten&timestamp=$ts$($m.API_SECRET)"))
$ky=-join($bam | ForEach-Object { $_.ToString('x2') })
$tenTam="luu-media-$ts"+[IO.Path]::GetExtension($tep); Copy-Item -LiteralPath $tep -Destination (Join-Path $env:TEMP $tenTam)
Push-Location $env:TEMP
try { curl.exe -sS -X POST "https://api.cloudinary.com/v1_1/$($m.CLOUD_NAME)/auto/upload" -F "file=@$tenTam" -F "api_key=$($m.API_KEY)" -F "timestamp=$ts" -F "folder=$ngan" -F "overwrite=false" -F "public_id=$ten" -F "signature=$ky" }
finally { Remove-Item -LiteralPath $tenTam -ErrorAction SilentlyContinue; Pop-Location }

Mac, Linux (bash):

TEP='<caminho-do-arquivo>'; NGAN='<pasta>'; TEN='<nome-sem-extensao>'; FILE_MA='<caminho-do-arquivo-de-chaves>'
lay() { sed -n -E "s/^[[:space:]]*(CLOUDINARY_)?$1[[:space:]]*=[[:space:]]*//p" "$FILE_MA" | tr -d '\r' | sed -E 's/[[:space:]]+$//' | head -n 1; }
TS=$(date +%s)
KY=$(printf '%s' "folder=$NGAN&overwrite=false&public_id=$TEN&timestamp=$TS$(lay API_SECRET)" | { if command -v shasum >/dev/null; then shasum -a 1; else sha1sum; fi; } | cut -d' ' -f1)
curl -sS -X POST "https://api.cloudinary.com/v1_1/$(lay CLOUD_NAME)/auto/upload" -F "file=@$TEP" -F "api_key=$(lay API_KEY)" -F "timestamp=$TS" -F "folder=$NGAN" -F "overwrite=false" -F "public_id=$TEN" -F "signature=$KY"

O resultado retorna em JSON: obtenha secure_url. Se houver error, informe o conteúdo exato do erro e pare, não reescreva a mensagem. Se o arquivo for muito grande para o plano atual, avise o usuário para compactá-lo. O comando usa overwrite=false para não sobrescrever arquivos com o mesmo nome: se a extensão ou o conteúdo retornado diferir do arquivo enviado, renomeie e envie novamente.

6. Verificar e registrar no cérebro

1. Abra o link para testar, verifique se retorna sucesso.
2. Adicione uma linha em kho-media.md, data/hora obtida da máquina.
3. Adicione o link na seção Media da página relacionada, conforme a última coluna da tabela de pastas. Se a página ainda não existir, registre apenas em kho-media.md e informe.

7. Informar

Forneça o link, a pasta e as 2 páginas onde foi registrado. Para imagens usadas em sites ou artigos, forneça também uma versão de carregamento rápido inserindo o seguinte trecho imediatamente após /upload/: f_auto,q_auto,w_1200/. O Cloudinary escolherá automaticamente o formato, a qualidade e a largura máxima de 1200 px.

Não fazer

• Não apagar ou alterar arquivos no Cloudinary. O usuário deve fazer isso na Media Library, ou solicitar instrução específica e confirmar.
• Não colocar arquivos de imagem ou vídeo no repositório Git.
• As chaves ficam apenas no arquivo de chaves informado. Não as escreva em páginas, logs, skills ou no chat. Antes de compartilhar a pasta do repositório com outras pessoas, lembre o usuário de remover .env.

Modelo de kho-media.md

# Repositório de mídia - índice

Nuvem: Cloudinary. Arquivo de chaves: `.env` na raiz do repositório, não vai para o GitHub.

| Data/hora | Nome do arquivo | Pasta | Link | Usado para |
|---|---|---|---|---|