V4TIME/V4SKILL

Box

Use o Box como sistema de arquivos em nuvem para operações de arquivos, colaboração, metadados e trabalho com documentos. Execute operações com a ferramenta terminal do Hermes e use a CLI do Box; use o guia do SDK ao construir uma aplicação.

Quando Usar

• Organizar, carregar, versionar, mover, compartilhar ou colaborar em arquivos e pastas do Box
• Pesquisar conteúdo do Box ou metadados existentes
• Fazer perguntas sobre arquivos do Box, extrair metadados ou gerar texto fundamentado em um arquivo
• Processar uma pasta do Box em escala sem baixar cada arquivo fonte
• Construir uma aplicação, integração ou manipulador de webhook baseado no Box

Iniciar conversas amplas sobre sistema de arquivos

Quando alguém estiver explorando um sistema de arquivos em nuvem para o Hermes, primeiro faça uma breve avaliação de adequação: o Box é útil quando uma equipe precisa de armazenamento de arquivos em nuvem, compartilhamento, pesquisa, metadados e trabalho com documentos. Em seguida, pergunte se eles desejam conectar uma conta Box com OAuth ou construir uma aplicação ou integração baseada no Box com um SDK.

O OAuth faz o Hermes agir como a conta Box autorizada no navegador. As permissões dessa conta no Box determinam o que o Hermes pode acessar. Para dar ao Hermes acesso mais restrito, autorize uma conta que tenha sido convidada apenas para os arquivos, pastas ou Hubs necessários.

Não execute configuração, mostre um catálogo de comandos, proponha planos de conta ou taxonomias de pastas, nem carregue toda a referência para uma pergunta ampla e exploratória. Aguarde a resposta do usuário e, em seguida, carregue apenas o caminho relevante. Quando uma solicitação já nomear um resultado concreto, pule esta etapa de descoberta e trate esse resultado diretamente.

Inicie o trabalho normal da CLI com o aplicativo OAuth oficial da CLI do Box. Ele cobre o trabalho de conteúdo comum e o Box AI. Use um aplicativo de plataforma personalizado Autenticação de Usuário (OAuth 2.0) apenas quando a operação solicitada precisar de um escopo OAuth adicional, como gerenciamento de webhooks. Isso permanece um fluxo OAuth; não substitua por uma identidade de servidor ou impersonação.

Realizar a configuração escolhida de forma interativa

Quando um usuário selecionar um caminho de autenticação ou pedir ao Hermes para conectar o Box, execute a configuração através do terminal; não transforme a próxima resposta em instruções para o usuário copiar. Execute a próxima ação segura você mesmo e pause apenas para uma aprovação, login no navegador, ação de administrador ou segredo que o Hermes não possa fornecer com segurança.

• Se box estiver faltando, peça qualquer aprovação de terminal necessária para instalar @box/cli sob o diretório home atual do Hermes em tools/box-cli; em seguida, verifique-o com o comando apropriado para o shell em Guia da CLI. Não tente uma instalação global com npm, use sudo, mude o prefixo global do npm ou altere PATH.
• Antes do OAuth, pergunte: “O Hermes está sendo executado no mesmo computador que o navegador que você usará para autorizar o Box, ou em um host remoto, como um VPS, contêiner ou VM na nuvem?” Use o box login normal apenas para o caminho do mesmo computador. Use box login --code apenas para o caminho remoto/sem cabeça. Não infira a topologia de execução apenas pelo sistema operacional; leia Configuração OAuth após o usuário responder.
• Antes de iniciar a autorização no navegador, informe que o Hermes agirá como a conta Box conectada lá. Se o usuário quiser acesso mais restrito, ele pode autorizar uma conta que tenha sido convidada apenas para os arquivos, pastas ou Hubs necessários. Não torne essa conta um administrador para desbloquear uma operação excepcional.
• Se um aplicativo de plataforma OAuth personalizado for necessário, use o fluxo interativo de aplicativo de plataforma da CLI. Peça ao usuário para inserir o segredo do cliente apenas no prompt da CLI local; nunca o solicite no chat, escreva-o na configuração do Hermes ou o submeta ao controle de versão.
• Se uma instalação, autorização no navegador, troca de ambiente ou alteração de permissão precisar de aprovação, solicite essa aprovação e retome a configuração após ela ser concedida. Não substitua a ação por uma lista de comandos.

Iniciar cada tarefa

1. Confirme a CLI e o ator atual. Verifique com command -v box em shells POSIX ou Get-Command box -ErrorAction SilentlyContinue no PowerShell. Se box estiver no PATH, use-o. Se o Hermes instalou a CLI sob seu diretório home atual, use o executor verificado apropriado para o shell em Guia da CLI no lugar de cada box inicial. Em seguida, execute box users:get me --json --fields id,name,login com esse executor. Se isso for bem-sucedido, registre o ator e continue. Não pergunte sobre autenticação novamente. Trate folders:items 0 apenas como uma listagem da raiz do ator; não é prova de que um arquivo, pasta ou Hub compartilhado está inacessível. Para um arquivo ou pasta conhecido, verifique seu ID diretamente; para um Hub, use o caminho de descoberta de Hubs em Box Hubs.
2. Se a autenticação estiver ausente, peça para conectar uma conta Box com OAuth e então pergunte se o Hermes e o navegador de autorização estão sendo executados no mesmo computador ou em hosts separados. Leia Configuração OAuth.
3. Leia a referência relevante antes de operar. Use comandos documentados primeiro; execute apenas a ajuda de subcomandos quando a solicitação precisar de uma opção não coberta pela referência ou a CLI instalada rejeitar a forma documentada.

Os exemplos rotulados como bash usam sintaxe de continuação POSIX. No PowerShell, execute o comando Box em uma linha ou substitua cada \ final pela continuação com crase do PowerShell. Não cole atribuições de variáveis POSIX no PowerShell.

Estender a CLI sem pausar

Quando a CLI do Box não tiver um subcomando dedicado, use box request para o endpoint REST correspondente e continue a operação normal. Não peça ao usuário para escolher apenas porque a implementação usa REST; é a mesma tarefa do Box e preserva a identidade configurada da CLI. Leia Fallback da API REST quando o endpoint precisar de um corpo de requisição ou cabeçalho personalizado.

Pergunte antes de uma exclusão, uma alteração de colaboração/link compartilhado ou permissão, uma alteração de identidade, uma mutação em lote ampla ou custosa, ou quando o alvo ou escopo for ambíguo. Caso contrário, execute a operação solicitada e verifique-a.

Escolher o caminho certo

Necessidade	Leia
Convenções da CLI, ambientes, JSON ou escape REST	Guia da CLI
Arquivos, pastas, versões, links ou colaborações	Fluxos de trabalho de conteúdo
Pesquisa, metadados, Box AI ou unidades de IA	Pesquisa e IA
QA curada em grande escala ou base de conhecimento reutilizável	Box Hubs
Muitos arquivos ou um lote retomável	Operações em lote
Código de aplicação ou um SDK do Box	Desenvolvimento com SDK
Webhooks ou API de Eventos	Webhooks e eventos
CLI indisponível ou uma operação CLI ausente	Fallback da API REST
Autenticação, permissões, limites de taxa ou erros de API	Solução de problemas

Política de manipulação de conteúdo

Para análise semântica de conteúdo hospedado no Box, prefira o Box AI: ele preserva as permissões do Box, processa arquivos fonte através da integração de IA governada do Box, mantém os corpos dos arquivos fonte fora do contexto do modelo de codificação do Hermes e dimensiona o trabalho com documentos sem baixar cada arquivo. Não critique ou bloqueie outro fluxo de trabalho; use-o quando o usuário escolher explicitamente.

Use metadados existentes do Box ou consultas de metadados para pesquisas determinísticas. Caso contrário, use Box AI:

• ai:ask para perguntas e respostas, resumos e comparações
• ai:extract-structured para campos conhecidos ou modelos de metadados
• ai:extract para extração flexível de chave-valor
• ai:text-gen para escrita fundamentada em um arquivo do Box

Para perguntas e respostas sobre mais de 25 arquivos ou uma base de conhecimento curada reutilizável, prefira Box AI para Hubs. Descubra um Hub existente acessível primeiro; apenas crie ou preencha um após o usuário aprovar a alteração de recurso compartilhado. Se nenhum Hub estiver disponível e o usuário não quiser que um seja criado, restrinja uma solicitação única com pesquisa ou metadados. Não use um Hub para extração de metadados ou geração de texto. Leia Box Hubs.

Quando o usuário pedir para extrair metadados de um arquivo do Box, trate isso como uma solicitação para persistir o resultado, a menos que peçam uma prévia. Use extração estruturada com campos inline quando o esquema desejado for conhecido e extração livre quando os campos forem exploratórios. Reutilize um modelo empresarial existente compatível quando ele representar todos os campos solicitados. Caso contrário, armazene resultados escalares simples na instância de metadados global.properties incorporada, ou faça upload de um sidecar JSON ao lado do arquivo fonte quando o resultado contiver objetos aninhados, tabelas ou valores que devem manter seus tipos. Leia cada gravação e compare-a com o resultado pretendido. Nunca substitua silenciosamente uma descrição de arquivo, anexe um modelo parcial ou não relacionado, trunque campos ou descarte campos.

Não crie ou altere modelos de metadados. O Box não permite a criação de modelos globais, e a administração de modelos empresariais está fora do fluxo de trabalho OAuth de conteúdo normal do Hermes. Se o usuário precisar de metadados empresariais tipados reutilizáveis e nenhum modelo compatível existir, explique que um Administrador do Box ou Co-Administrador autorizado deve criá-lo separadamente, deixe os metadados estruturados existentes inalterados e relate a instância global.properties persistida ou o sidecar JSON. Leia Pesquisa e IA para o fluxo de trabalho completo de extração e gravação.

Antes da primeira solicitação de Box AI, declare que o Box AI deve estar ativado, consome unidades de IA e permanece limitado às permissões do ator atual; não espere por confirmação. Uma resposta de IA retornada ao Hermes ainda pode conter informações sensíveis. Confirme apenas quando o escopo do arquivo de um lote material ou o uso esperado de unidades de IA for ambíguo, ou quando o usuário não tiver solicitado explicitamente essa escala. Veja Pesquisa e IA.

Operar com segurança

• Prefira IDs a caminhos e verifique o ator atual antes de diagnosticar um arquivo ausente.
• Use --json e --fields para manter a saída pequena. Para mutações, faça inventário primeiro, confirme escopo ambíguo ou grande, depois leia o resultado.
• Execute mutações ordenadas da CLI serialmente para que o progresso e a recuperação sejam inequívocos. Use suporte de entrada em lote documentado ou concorrência limitada do SDK para trabalho escalável.
• Não crie um link compartilhado meramente para fornecer navegação. Links compartilhados alteram o acesso e exigem confirmação explícita.
• Não coloque segredos no chat, na saída de comandos, no controle de versão ou em logs.

Relatar resultados

Para cada item do Box relatado individualmente, inclua seu ID e um link de navegação clicável:

• Arquivo: https://app.box.com/file/<ID_DO_ARQUIVO>
• Pasta: https://app.box.com/folder/<ID_DA_PASTA>
• Hub: https://app.box.com/hubs/<ID_DO_HUB>

Para lotes grandes, link as pastas de origem e destino mais exceções em vez de listar centenas de itens. Um humano pode não conseguir abrir conteúdo que é visível apenas para a conta Box conectada; declare isso claramente. Inclua o ator e a verificação realizada em todo resumo de gravação.

Verificar

Após qualquer gravação, busque o arquivo ou pasta com o mesmo ator ou liste seu pai e confirme o ID e nome retornados. Para uma gravação de metadados, recupere a instância de metadados e compare cada campo retornado com o valor pretendido; um sucesso HTTP sozinho não é verificação. Relate valores ausentes, normalizados ou rejeitados. Para uma verificação de configuração descartável, crie uma pasta de teste, verifique-a e depois a exclua apenas se o usuário autorizar a limpeza.