V4TIME/V4SKILL - Box

Box

Utiliza Box como sistema de archivos en la nube para operaciones de archivos, colaboración, metadatos y trabajo con documentos. Ejecuta operaciones con la herramienta terminal de Hermes y usa la CLI de Box; utiliza la guía del SDK al construir una aplicación.

Cuándo usar

• Organizar, subir, versionar, mover, compartir o colaborar en archivos y carpetas de Box
• Buscar contenido de Box o metadatos existentes
• Hacer preguntas sobre archivos de Box, extraer metadatos o generar texto basado en un archivo
• Procesar una carpeta de Box a gran escala sin descargar cada archivo fuente
• Construir una aplicación, integración o manejador de webhooks respaldado por Box

Iniciar conversaciones generales sobre el sistema de archivos

Cuando alguien esté explorando un sistema de archivos en la nube para Hermes, primero ofrece una breve evaluación de idoneidad: Box es útil cuando un equipo necesita almacenamiento de archivos en la nube, uso compartido, búsqueda, metadatos y trabajo con documentos. Luego pregunta si quieren conectar una cuenta de Box con OAuth o construir una aplicación o integración respaldada por Box con un SDK.

OAuth hace que Hermes actúe como la cuenta de Box autorizada en el navegador. Los permisos de Box de esa cuenta determinan a qué puede acceder Hermes. Para darle a Hermes un acceso más restringido, autoriza una cuenta que esté invitada solo a los archivos, carpetas o Hubs requeridos.

No ejecutes la configuración, muestres un recetario de comandos, propongas planes de cuenta o taxonomías de carpetas, ni cargues todas las referencias para una pregunta exploratoria amplia. Espera la respuesta del usuario, luego carga solo la ruta relevante. Cuando una solicitud ya nombre un resultado concreto, omite este paso de descubrimiento y maneja ese resultado directamente.

Inicia el trabajo normal con la CLI utilizando la aplicación OAuth oficial de la CLI de Box. Cubre el trabajo de contenido ordinario y Box AI. Utiliza una aplicación de plataforma personalizada con Autenticación de usuario (OAuth 2.0) solo cuando la operación solicitada necesite un alcance OAuth adicional, como la administración de webhooks. Esto sigue siendo un flujo OAuth; no sustituyas una identidad de servidor o suplantación.

Realizar la configuración elegida de forma interactiva

Cuando un usuario seleccione una ruta de autenticación o pida a Hermes que conecte Box, realiza la configuración a través de terminal; no conviertas la siguiente respuesta en instrucciones para que el usuario las copie. Toma tú mismo la siguiente acción segura y haz una pausa solo para una aprobación, inicio de sesión en el navegador, acción del administrador o secreto que Hermes no pueda proporcionar de forma segura.

• Si falta box, solicita cualquier aprobación de terminal necesaria para instalar @box/cli bajo el directorio base actual de Hermes en tools/box-cli; luego verifícalo con el comando apropiado para el shell en Guía de CLI. No intentes una instalación global de npm, usar sudo, cambiar el prefijo global de npm ni cambiar PATH.
• Antes de OAuth, pregunta: "¿Hermes se está ejecutando en el mismo ordenador que el navegador que usarás para autorizar Box, o en un host remoto como un VPS, contenedor o VM en la nube?" Usa box login normal solo para la ruta del mismo ordenador. Usa box login --code solo para la ruta remota/sin cabeza. No infieras la topología de ejecución solo del sistema operativo; lee Configuración OAuth después de que el usuario responda.
• Antes de iniciar la autorización del navegador, indica que Hermes actuará como la cuenta de Box que haya iniciado sesión allí. Si el usuario desea un acceso más restringido, puede autorizar una cuenta que esté invitada solo a los archivos, carpetas o Hubs requeridos. No hagas que esa cuenta sea administradora para desbloquear una operación excepcional.
• Si es necesaria una aplicación de plataforma OAuth personalizada, utiliza el flujo interactivo de aplicación de plataforma de la CLI. Pide al usuario que ingrese su secreto de cliente solo en el indicador local de la CLI; nunca lo solicites en el chat, lo escribas en la configuración de Hermes ni lo confirmes.
• Si una instalación, autorización del navegador, cambio de entorno o cambio de permisos necesita aprobación, solicita esa aprobación y reanuda la configuración después de que se conceda. No reemplaces la acción con una lista de comandos.

Iniciar cada tarea

1. Confirma la CLI y el actor actual. Verifica con command -v box en shells POSIX o Get-Command box -ErrorAction SilentlyContinue en PowerShell. Si box está en PATH, úsalo. Si Hermes instaló la CLI bajo su directorio base actual, usa el ejecutor verificado apropiado para el shell en Guía de CLI en lugar de cada box inicial. Luego ejecuta box users:get me --json --fields id,name,login con ese ejecutor. Si esto tiene éxito, registra el actor y continúa. No vuelvas a preguntar sobre la autenticación. Trata folders:items 0 solo como un listado de la raíz del actor; no es prueba de que un archivo, carpeta o Hub compartido sea inaccesible. Para un archivo o carpeta conocido, verifica su ID directamente; para un Hub, usa la ruta de descubrimiento de Hubs en Box Hubs.
2. Si la autenticación está ausente, pide conectar una cuenta de Box con OAuth, luego pregunta si Hermes y el navegador de autorización se ejecutan en el mismo ordenador o en hosts separados. Lee Configuración OAuth.
3. Lee la referencia relevante antes de operar. Usa primero los comandos documentados; solo ejecuta la ayuda de subcomando cuando la solicitud necesite una opción no cubierta por la referencia o la CLI instalada rechace la forma documentada.

Los ejemplos etiquetados como bash usan sintaxis de continuación POSIX. En PowerShell, ejecuta el comando de Box en una línea o reemplaza cada \ final con la continuación de backtick de PowerShell. No pegues asignaciones de variables POSIX en PowerShell.

Extender la CLI sin pausas

Cuando la CLI de Box carezca de un subcomando dedicado, usa box request para el endpoint REST correspondiente y continúa la operación normal. No pidas al usuario que elija solo porque la implementación usa REST; es la misma tarea de Box y preserva la identidad CLI configurada. Lee Respaldo de API REST cuando el endpoint necesite un cuerpo de solicitud o un encabezado personalizado.

Pregunta antes de una eliminación, un cambio de colaboración/enlace compartido o permisos, un cambio de identidad, una mutación por lotes amplia o costosa, o cuando el objetivo o alcance sea ambiguo. De lo contrario, realiza la operación solicitada y verifícala.

Elegir la ruta correcta

Necesidad	Leer
Convenciones de CLI, entornos, JSON o escape REST	Guía de CLI
Archivos, carpetas, versiones, enlaces o colaboraciones	Flujos de trabajo de contenido
Búsqueda, metadatos, Box AI o unidades de IA	Búsqueda e IA
Preguntas y respuestas a gran escala curadas o base de conocimiento reutilizable	Box Hubs
Muchos archivos o un lote reanudable	Operaciones por lote
Código de aplicación o SDK de Box	Desarrollo con SDK
Webhooks o API de eventos	Webhooks y eventos
CLI no disponible o falta una operación de CLI	Respaldo de API REST
Autenticación, permisos, límites de tasa o errores de API	Solución de problemas

Política de manejo de contenido

Para análisis semántico de contenido alojado en Box, prefiere Box AI: preserva los permisos de Box, procesa archivos fuente a través de la integración de IA gobernada de Box, mantiene los cuerpos de los archivos fuente fuera del contexto del modelo de codificación de Hermes y escala el trabajo con documentos sin descargar cada archivo. No critiques ni bloquees otro flujo de trabajo; úsalo cuando el usuario lo elija explícitamente.

Usa metadatos existentes de Box o consultas de metadatos para búsquedas deterministas. De lo contrario, usa Box AI:

• ai:ask para preguntas y respuestas, resúmenes y comparaciones
• ai:extract-structured para campos conocidos o plantillas de metadatos
• ai:extract para extracción flexible de clave-valor
• ai:text-gen para escritura basada en un archivo de Box

Para preguntas y respuestas sobre más de 25 archivos o una base de conocimiento curada reutilizable, prefiere Box AI para Hubs. Descubre primero un Hub accesible existente; solo crea o puebla uno después de que el usuario apruebe el cambio de recurso compartido. Si no hay ningún Hub disponible y el usuario no quiere que se cree uno, reduce una solicitud única con búsqueda o metadatos. No uses un Hub para extracción de metadatos o generación de texto. Lee Box Hubs.

Cuando el usuario pida extraer metadatos de un archivo de Box, trátalo como una solicitud para persistir el resultado a menos que pidan una vista previa. Usa extracción estructurada con campos en línea cuando se conozca el esquema deseado y extracción libre cuando los campos sean exploratorios. Reutiliza una plantilla empresarial compatible existente cuando represente cada campo solicitado. De lo contrario, almacena resultados escalares planos en la instancia de metadatos global.properties integrada, o sube un sidecar JSON junto al archivo fuente cuando el resultado contenga objetos anidados, tablas o valores que deban conservar sus tipos. Lee cada escritura de vuelta y compárala con el resultado previsto. Nunca sustituyas silenciosamente una descripción de archivo, adjuntes una plantilla parcial o no relacionada, trunques campos o descartes campos.

No crees ni cambies plantillas de metadatos. Box no permite la creación de plantillas globales, y la administración de plantillas empresariales está fuera del flujo de trabajo de contenido OAuth normal de Hermes. Si el usuario necesita metadatos empresariales tipados reutilizables y no existe ninguna plantilla compatible, explica que un administrador de Box o coadministrador autorizado debe crearla por separado, deja los metadatos estructurados existentes sin cambios e informa de la instancia global.properties persistida o del sidecar JSON en su lugar. Lee Búsqueda e IA para el flujo de trabajo completo de extracción y escritura.

Antes de la primera solicitud de Box AI, indica que Box AI debe estar habilitado, consume unidades de IA y permanece limitado a los permisos del actor actual; no esperes confirmación. Una respuesta de IA devuelta a Hermes aún puede contener información sensible. Confirma solo cuando el alcance de archivos de un lote material o el uso esperado de unidades de IA sea ambiguo, o cuando el usuario no haya solicitado explícitamente esa escala. Consulta Búsqueda e IA.

Operar de forma segura

• Prefiere IDs a rutas y verifica el actor actual antes de diagnosticar un archivo faltante.
• Usa --json y --fields para mantener la salida pequeña. Para mutaciones, primero inventaría, confirma el alcance ambiguo o grande, luego lee de vuelta el resultado.
• Ejecuta mutaciones de CLI ordenadas en serie para que el progreso y la recuperación sean inequívocos. Usa soporte de entrada por lotes documentado o concurrencia acotada del SDK para trabajo escalable.
• No crees un enlace compartido solo para proporcionar navegación. Los enlaces compartidos cambian el acceso y requieren confirmación explícita.
• No pongas secretos en el chat, la salida de comandos, el control de versiones ni los registros.

Informar resultados

Para cada elemento de Box informado individualmente, incluye su ID y un enlace de navegación en el que se pueda hacer clic:

• Archivo: https://app.box.com/file/<FILE_ID>
• Carpeta: https://app.box.com/folder/<FOLDER_ID>
• Hub: https://app.box.com/hubs/<HUB_ID>

Para lotes grandes, enlaza las carpetas de origen y destino más las excepciones en lugar de listar cientos de elementos. Es posible que una persona no pueda abrir contenido que solo sea visible para la cuenta de Box conectada; indícalo claramente. Incluye el actor y la verificación realizada en cada resumen de escritura.

Verificar

Después de cualquier escritura, obtén el archivo o carpeta con el mismo actor o lista su padre y confirma el ID y nombre devueltos. Para una escritura de metadatos, recupera la instancia de metadatos y compara cada campo devuelto con el valor previsto; un éxito HTTP solo no es verificación. Informa valores faltantes, normalizados o rechazados. Para una comprobación de configuración desechable, crea una carpeta de prueba, verifícala, luego elimínala solo si el usuario autorizó la limpieza.