chorned/heb-mcp.skill

heb-mcp.skill (TikTok-2-HEB) — Skill para Agente

Gerencie carrinhos de compras ao vivo do H-E-B, resolva produtos domésticos preferidos com base no histórico de compras, recorte cupons e transforme URLs de vídeos de culinária em carrinhos de compras H-E-B escalados e auditados pela despensa, com substituições determinísticas para itens fora de estoque.

---

🎯 Condições de Ativação

Ative esta skill sempre que:

1. Um usuário pedir para pesquisar no H-E-B, verificar o carrinho, alterar sua loja preferida ou método de entrega (Curbside vs. Delivery), recortar cupons, ou adicionar/remover itens no carrinho do H-E-B (ex.: "Adicione leite integral e tortilhas de manteiga ao meu carrinho do H-E-B").
2. Um usuário autorizado compartilhar uma URL de culinária ou receita do TikTok (tiktok.com, vm.tiktok.com), Instagram Reels (instagram.com/reel/) ou YouTube Shorts (youtube.com/shorts/).
3. Um usuário pedir para converter, escalar ou encomendar ingredientes de um vídeo de receita (ex.: "Peça os ingredientes desta receita no H-E-B", "Coloque este jantar do TikTok no meu carrinho").
4. Um usuário responder a um tópico de revisão de compras já montado com ajustes pós-montagem (ex.: "adicione molho de soja", "troque salmão comum por salmão selvagem sockeye", "faça essa troca permanente").
5. Um usuário pedir para configurar ou ajustar o heb-mcp.skill (TikTok-2-HEB) pela primeira vez.

---

🚀 Configuração Inicial (Onboarding guiado pelo agente)

Quando um usuário pedir para configurar este projeto, execute as etapas técnicas e faça apenas perguntas breves e em linguagem natural:

1. Instalar ambiente e binários:

   uv venv --python 3.11 .venv && source .venv/bin/activate && uv pip install -r requirements.txt
   playwright install chromium
   cp -n .env.example .env
   cp -n config/household.example.yaml config/household.yaml
   cp -n config/pantry_staples.example.json config/pantry_staples.json
   

2. Faça perguntas rápidas de configuração:
   • Loja H-E-B preferida e método de entrega: Pergunte em qual loja H-E-B o usuário faz compras (atualize HEB_STORE_ID no .env e store no config/household.yaml, e ajude a trocar a loja ativa ou alternar entre Curbside Pickup e Home Delivery sempre que solicitado).
   • Tamanho da família: Pergunte quantos adultos/crianças o usuário cozinha (atualize config/household.yaml).
3. Coletar sessão e sincronizar pedidos anteriores: Peça ao usuário para garantir que está logado no heb.com no Safari ou Chrome, depois execute:

   python scripts/heb_client.py --harvest
   python scripts/cache_manager.py update-preferred-skus
   python tests/test_skill_setup.py
   

4. Configurar tarefa cron automática de renovação diária de token: Recomende fortemente que o usuário permita instalar uma tarefa cron recorrente de 24 horas (0 9 * * * cd <CAMINHO_DO_REPO> && .venv/bin/python scripts/heb_client.py --harvest >/dev/null 2>&1) para que a sessão do H-E-B permaneça ativa automaticamente.

---

🔒 Invariantes Operacionais e Barreiras de Segurança

1. Portão de finalização de compra com supervisão humana obrigatória:
   • O agente monta itens no carrinho e recorta cupons digitais.
   • O agente NUNCA DEVE submeter pagamentos, agendar janelas de entrega/retirada ou finalizar o pedido.
   • A revisão final e a finalização da compra ficam sempre nas mãos do usuário dentro do aplicativo oficial My H-E-B.
2. Extração sem autenticação:
   • Sempre invoque scripts/extract_recipe_media.py sem exigir logins pessoais no TikTok/Instagram ou cookies de sessão.
3. Invariante contra envenenamento de cache:
   • Substituições por falta de estoque (Nível 2/3/4) devem permanecer estritamente efêmeras para aquele pedido específico.
   • NUNCA sobrescreva primary_sku em cache/recipes/<slug>.yaml a menos que o usuário ordene explicitamente: "faça essa troca permanente" ou "use sempre esta marca".
4. Separação de preparo para crianças:
   • Quando kid_friendly_split estiver ativado, separe ingredientes picantes/ardidos (sriracha, flocos de pimenta, cayena, jalapeños) da panela base. Mantenha o prato principal suave, sirva a porção da criança primeiro e tempere as porções dos adultos no final.
   • Adicione lembretes para cortar proteínas e alimentos que apresentam risco de asfixia em cubos de 1,27 cm.
5. Renovação automática de token (tarefa cron diária recomendada):
   • Embora o token de acesso de sessão curta (sat) do H-E-B gire a cada 30 minutos, o heb_graphql.py o renova automaticamente sob demanda usando o token de sessão longa (sst).
   • Durante a configuração inicial ou após coletar/renovar uma sessão, incentive proativamente o usuário a permitir a instalação de uma tarefa cron automática de 24 horas que mantenha a sessão H-E-B subjacente e o token anti-bot (reese84) validados em segundo plano, evitando que ele precise fazer login manualmente novamente antes das compras.

---

🛠️ Fluxo de Execução Passo a Passo

Passo 1: Consulta de Cache de Pré-Voo

Antes de realizar extração de mídia ou chamadas de API, verifique se o vídeo já foi processado e armazenado em cache:

python scripts/cache_manager.py lookup --query "<URL_OU_ID_DO_VIDEO>"

• ACERTO: Carregue o YAML da receita em cache. Vá diretamente para o Passo 4 (Montagem do Carrinho) usando as definições de primary_sku em cache.
• ERRO: Prossiga para o Passo 2 (Extração de Mídia).

Passo 2: Extração Multimodal sem Autenticação (3 passes)

Execute o pipeline de extração de 3 passes:

python scripts/extract_recipe_media.py "<URL_DO_VIDEO>"

1. Passo 1: Captura título, descrição, uploader e legendas automáticas do vídeo.
2. Passo 2: Limpa as falas das legendas, remove timestamps e deduplica repetições de legendas rolantes.
3. Passo 3: Se a transcrição for esparsa (< 3 tokens de medida culinária), extrai automaticamente o fluxo de áudio ou quadros-chave.

Passo 3: Processamento da Receita, Escalonamento Familiar e Auditoria da Despensa

1. Escalonamento Familiar: Escalone as quantidades dos ingredientes do rendimento original (ex.: 4 porções) para as porções desejadas (padrão 2.5 para 2 adultos + 1 criança) usando o HouseholdScaler.
2. Dedução da Despensa: Verifique os ingredientes em relação a config/pantry_staples.json usando o PantryComparator. Mova itens correspondentes (sal, pimenta, óleo de cozinha, molho de soja, alho em pó) para pantry_staples_skipped.
3. Lembretes de Preparo para Crianças: Gere adaptações adequadas para crianças se ingredientes picantes ou proteínas inteiras forem detectadas.

Passo 4: Correspondência com o Catálogo H-E-B e Cascata de Fallback de 5 Níveis

Para cada ingrediente em ingredients_to_buy (ou solicitações avulsas do usuário), faça a correspondência com o catálogo da loja H-E-B local usando scripts/heb_client.py:

• Nível 0 (Resolução de SKU Preferido e Escalonamento de Tamanho de Embalagem): Correspondência com cache/preferred_skus.json (chaves canônicas e arrays de aliases) populado a partir de pedidos anteriores e fixações manuais. Calcula automaticamente quantidades inteiras de embalagens (ex.: volume da receita de 1,36 L / embalagem de 946 mL -> 2 embalagens). Se estiver em estoque, adiciona diretamente como Nível 0. Se estiver fora de estoque, faz a cascata suavemente para o Nível 1.
• Nível 1 (Correspondência Exata de SKU): Adiciona o SKU primário existente da receita se estiver em estoque.
• Nível 2 (Hierarquia de Marcas): Se o SKU primário estiver fora de estoque, substitui usando a brand_hierarchy (H-E-B → H-E-B Organics → Central Market → Mi Tienda → Hill Country Fare → Marca Nacional).
• Nível 3 (Troca Orgânico ↔ Convencional): Troca orgânico por convencional (ou vice-versa) se a loja tiver apenas um deles em estoque.
• Nível 4 (Ajuste de Tamanho / Escalonamento Humano): Ajusta quantidades ou sinaliza falha total da categoria como ⚠️ FORA DE ESTOQUE (NECESSITA INTERVENÇÃO HUMANA).

Passo 5: Montagem Direta do Carrinho via GraphQL e Recorte de Cupons (Sem Cliques Lentos em UI)

Adicione itens ao carrinho e recorte cupons diretamente por meio de operações GraphQL autenticadas (consultas persistidas cartEstimated, cartItemV2, CouponClip obtidas de texas-grocery-mcp) usando tokens de sessão do Chrome CDP coletados (127.0.0.1:9222) / rookiepy:

# 1. Coletar ou renovar tokens de sessão ativos
python scripts/heb_client.py --harvest

# 2. Sincronizar SKUs preferidos de pedidos anteriores e "Compre Novamente"
python scripts/cache_manager.py update-preferred-skus

# 3. Fixar manualmente um produto favorito como SKU preferido (protegido contra sincronização automática)
python scripts/cache_manager.py pin-preferred-sku \
  --ingredient "leite integral" \
  --sku "4122012345" \
  --product "123456" \
  --name "H-E-B Organics Whole Milk" \
  --package-size "1 gal"

# 4. Resolver um ingrediente avulso ou testar tamanho de embalagem
python scripts/heb_client.py --resolve-sku "1,36 L caldo de carne"

# 5. Adicionar itens candidatos (requer --confirm para supervisão humana)
python scripts/heb_client.py --stage-sku "1,36 L caldo de carne" --confirm
# ou diretamente pelo ID do produto:
python scripts/heb_client.py --cart-add <ID_DO_PRODUTO> [--sku <ID_DO_SKU>] [--qty <N>] --confirm

# 6. Inspecionar o carrinho atual
python scripts/heb_client.py --cart-get

# 7. Remover item do carrinho se houve troca
python scripts/heb_client.py --cart-remove <ID_DO_PRODUTO> [--sku <ID_DO_SKU>] --confirm

# 8. Recortar cupons digitais
python scripts/heb_client.py --coupon-clip <ID_DO_CUPOM> --confirm

[!IMPORTANT] Portão de finalização com supervisão humana: É estritamente proibido que o agente execute mutações de finalização de compra, pagamento ou agendamento de janela de entrega/retirada. Apenas montagem de carrinho e recorte de cupons; Carl sempre revisa e finaliza a compra no aplicativo My H-E-B.

⏱️ Tarefa Cron Recomendada em Segundo Plano (Renovação Diária da Sessão)

Embora o token de curta duração sat do H-E-B gire a cada 30 minutos e seja renovado automaticamente sob demanda via sst, incentive o usuário a ter uma tarefa cron diária (macOS/Linux) ou Scheduled Task (schtasks no Windows) que renove e valide a sessão uma vez a cada 24 horas. Ofereça-se para instalá-la no crontab do usuário:

0 9 * * * cd /caminho/para/heb-mcp.skill && .venv/bin/python scripts/heb_client.py --harvest >/dev/null 2>&1

(Ou use scripts/cron_refresh_heb_auth.py / scripts/cron_refresh_heb_auth.sh se notificações no Slack forem desejadas.)

Passo 6: Persistência do Cache da Receita

Persista a receita processada para garantir que execuções futuras utilizem o Caminho Rápido:

python scripts/cache_manager.py save --file <DADOS_DA_RECEITA_YAML>

Passo 7: Resumo para Revisão no Celular (iMessage / Slack)

Formate o resumo para leitura limpa em telas de celular (evite tabelas Markdown, use formatação limpa com emojis):

🛒 Carrinho H-E-B Montado: Salmão Crocante com Mel e Alho
Escalonado para 2 Adultos + 1 Criança (~2,5 porções)

👶 Nota de Preparo Infantil:
• Reserve a 1 colher de sopa de sriracha da cobertura principal da frigideira. Sirva a porção da criança primeiro e depois misture a sriracha nas porções dos adultos.
• Corte o salmão da criança em cubos de 1,27 cm.

✅ Adicionado ao Carrinho H-E-B (4 itens):
• 1x Filé de Salmão Fresco do Atlântico H-E-B (~570 g) — R$ 71,68
• 1x Mel Puro H-E-B (340 g) — R$ 24,92
• 1x Cebolinha Fresca (1 maço) — R$ 4,90
• 1x Arroz Jasmine H-E-B (907 g) — R$ 15,29

🔄 Substituído Automaticamente (Fora de Estoque na Loja):
• 2x Floretes de Brócolis H-E-B (saco de 283 g) — R$ 25,39
  (Cabeças Orgânicas de 454 g estavam OOS; substituído por 2x sacos de 283 g apenas para este pedido)

🎟️ Cupons Recortados:
• R$ 5,57 de desconto em Bandeja de Frutos do Mar Frescos H-E-B

🏠 Verificação da Despensa (Pulado — responda para adicionar):
• Molho de soja (3 colheres de sopa), Alho (4 dentes), Amido de milho (2 colheres de sopa), Óleo de gergelim (1 colher de chá)

📱 Próximo Passo:
Responda se quiser adicionar um item da despensa (ex.: "adicione molho de soja") ou trocar uma marca. Caso contrário, abra o aplicativo My H-E-B para revisar e finalizar a compra!

---

🔄 Comandos de Resposta Pós-Montagem

Quando o usuário responder ao tópico de revisão da compra montada:

1. "Adicione [item da despensa]" (ex.: "estamos sem molho de soja, adicione-o"):
   • Resolva através do mecanismo de SKU preferido de Nível 0 e adicione ao carrinho: python scripts/heb_client.py --stage-sku "molho de soja" --confirm
   • Confirme com uma resposta breve: "Adicionado 1x Molho de Soja com Baixo Teor de Sódio H-E-B ao seu carrinho."
2. "Troque [item] por [preferência]" (ex.: "troque salmão comum por salmão selvagem sockeye"):
   • Remova o SKU antigo do carrinho e adicione o SKU preferido.
   • Pergunte: "Trocado por salmão sockeye selvagem para este pedido. Gostaria que eu tornasse esta troca permanente para futuros pedidos desta receita?"
3. "Faça essa troca permanente":
   • Execute python scripts/cache_manager.py promote-sku ... para atualizar primary_sku em cache/recipes/<slug>.yaml e fixá-lo em cache/preferred_skus.json com source: "manual_override".
   • Confirme: "Cache da receita atualizado: Central Market Wild Sockeye agora é seu SKU primário para esta receita e fixado como seu SKU preferido."
4. "Troque a loja preferida para [Loja]" / "Mude para Curbside ou Delivery":
   • Atualize HEB_STORE_ID no .env e store no config/household.yaml, ou atualize a loja ativa/modo de entrega na sessão H-E-B, e reverifique a disponibilidade dos itens do carrinho na nova loja.