Box
Verwende Box als Cloud-Dateisystem für Dateioperationen, Zusammenarbeit, Metadaten und Dokumentenarbeit. Führe Operationen mit Hermes' terminal-Werkzeug aus und verwende die Box-CLI; nutze den SDK-Leitfaden beim Erstellen einer Anwendung.
Wann verwenden
- Organisieren, Hochladen, Versionieren, Verschieben, Freigeben oder Zusammenarbeiten an Box-Dateien und -Ordnern
- Durchsuchen von Box-Inhalten oder vorhandenen Metadaten
- Fragen zu Box-Dateien stellen, Metadaten extrahieren oder Text generieren, der in einer Datei verankert ist
- Einen Box-Ordner in großem Maßstab verarbeiten, ohne jede Quelldatei herunterzuladen
- Erstellen einer Box-gestützten Anwendung, Integration oder eines Webhook-Handlers
Beginnen Sie breite Dateisystem-Gespräche
Wenn jemand ein Cloud-Dateisystem für Hermes erkundet, geben Sie zunächst eine kurze Eignungseinschätzung: Box ist nützlich, wenn ein Team Cloud-Dateispeicher, Freigaben, Suche, Metadaten und Dokumentenarbeit benötigt. Fragen Sie dann, ob sie ein Box-Konto mit OAuth verbinden oder eine Box-gestützte Anwendung oder Integration mit einem SDK erstellen möchten.
OAuth lässt Hermes als das im Browser autorisierte Box-Konto agieren. Die Box-Berechtigungen dieses Kontos bestimmen, worauf Hermes zugreifen kann. Um Hermes engeren Zugriff zu gewähren, autorisieren Sie ein Konto, das nur zu den erforderlichen Dateien, Ordnern oder Hubs eingeladen ist.
Führen Sie keine Einrichtung durch, zeigen Sie keine Befehlsübersicht an, schlagen Sie keine Kontopläne oder Ordner-Taxonomien vor und laden Sie nicht jede Referenz für eine breite explorative Frage. Warten Sie auf die Antwort des Benutzers, und laden Sie dann nur den relevanten Pfad. Wenn eine Anfrage bereits ein konkretes Ergebnis nennt, überspringen Sie diesen Erkennungsschritt und bearbeiten Sie dieses Ergebnis direkt.
Beginnen Sie die normale CLI-Arbeit mit der offiziellen Box-CLI-OAuth-App. Sie deckt die normale Inhaltsarbeit und Box AI ab. Verwenden Sie eine benutzerdefinierte Benutzerauthentifizierung (OAuth 2.0)-Plattform-App nur, wenn die angeforderte Operation einen zusätzlichen OAuth-Bereich benötigt, wie z. B. Webhook-Verwaltung. Dies bleibt ein OAuth-Fluss; ersetzen Sie ihn nicht durch eine Server-seitige oder Impersonations-Identität.
Führen Sie die gewählte Einrichtung interaktiv durch
Wenn ein Benutzer einen Authentifizierungspfad auswählt oder Hermes bittet, Box zu verbinden, führen Sie die Einrichtung über terminal durch; machen Sie die nächste Antwort nicht zu einer Anleitung zum Kopieren für den Benutzer. Führen Sie selbst den nächsten sicheren Schritt aus, und pausieren Sie nur für eine Genehmigung, einen Browser-Login, eine Administrator-Aktion oder ein Geheimnis, das Hermes nicht sicher bereitstellen kann.
- Wenn
boxfehlt, bitten Sie um eine terminal-Genehmigung für die Installation von@box/cliim aktuellen Hermes-Home untertools/box-cli; überprüfen Sie es dann mit dem shell-entsprechenden Befehl im CLI-Leitfaden. Versuchen Sie keine globale npm-Installation, verwenden Sie keinsudo, ändern Sie nicht npm's globales Präfix oderPATH. - Fragen Sie vor OAuth: „Läuft Hermes auf demselben Computer wie der Browser, den Sie zur Autorisierung von Box verwenden werden, oder auf einem entfernten Host wie einem VPS, Container oder einer Cloud-VM?” Verwenden Sie normales
box loginnur für den selben-Computer-Pfad. Verwenden Siebox login --codenur für den entfernten/headless-Pfad. Leiten Sie die Laufzeit-Topologie nicht allein aus dem Betriebssystem ab; lesen Sie OAuth-Einrichtung nach der Antwort des Benutzers. - Geben Sie vor dem Start der Browser-Autorisierung an, dass Hermes als das dort angemeldete Box-Konto agieren wird. Wenn der Benutzer engeren Zugriff wünscht, kann er ein Konto autorisieren, das nur zu den erforderlichen Dateien, Ordnern oder Hubs eingeladen ist. Machen Sie dieses Konto nicht zu einem Administrator, um eine außergewöhnliche Operation freizuschalten.
- Wenn eine benutzerdefinierte OAuth-Plattform-App erforderlich ist, verwenden Sie den interaktiven Plattform-App-Flow der CLI. Bitten Sie den Benutzer, sein Client-Geheimnis nur in der lokalen CLI-Eingabeaufforderung einzugeben; fordern Sie es niemals im Chat an, schreiben Sie es nicht in die Hermes-Konfiguration und committen Sie es nicht.
- Wenn eine Installation, Browser-Autorisierung, Umgebungswechsel oder Berechtigungsänderung eine Genehmigung benötigt, fordern Sie diese Genehmigung an und setzen Sie die Einrichtung nach deren Erteilung fort. Ersetzen Sie die Aktion nicht durch eine Befehlsliste.
Starten Sie jede Aufgabe
- Bestätigen Sie die CLI und den aktuellen Akteur. Überprüfen Sie mit
command -v boxauf POSIX-Shells oderGet-Command box -ErrorAction SilentlyContinuein PowerShell. WennboxinPATHist, verwenden Sie es. Wenn Hermes die CLI unter seinem aktuellen Home installiert hat, verwenden Sie den shell-entsprechenden verifizierten Runner im CLI-Leitfaden anstelle jedes führendenbox. Führen Sie dannbox users:get me --json --fields id,name,loginmit diesem Runner aus. Wenn dies erfolgreich ist, notieren Sie den Akteur und fahren Sie fort. Fragen Sie nicht erneut nach der Authentifizierung. Behandeln Siefolders:items 0nur als eine Auflistung des Stamms des Akteurs; es ist kein Beweis dafür, dass eine freigegebene Datei, ein Ordner oder Hub unzugänglich ist. Überprüfen Sie für eine bekannte Datei oder einen bekannten Ordner direkt deren ID; für einen Hub verwenden Sie den Hubs-Erkennungspfad in Box Hubs. - Wenn die Authentifizierung fehlt, bitten Sie, ein Box-Konto mit OAuth zu verbinden, und fragen Sie dann, ob Hermes und der Autorisierungsbrowser auf demselben Computer oder auf verschiedenen Hosts laufen. Lesen Sie OAuth-Einrichtung.
- Lesen Sie die relevante Referenz, bevor Sie operieren. Verwenden Sie zuerst dokumentierte Befehle; führen Sie die Subcommand-Hilfe nur aus, wenn die Anfrage eine Option benötigt, die nicht von der Referenz abgedeckt wird, oder wenn die installierte CLI die dokumentierte Form ablehnt.
Mit bash gekennzeichnete Beispiele verwenden POSIX-Fortsetzungssyntax. Führen Sie in PowerShell den Box-Befehl in einer Zeile aus oder ersetzen Sie jedes nachgestellte \ durch die PowerShell-Backtick-Fortsetzung. Fügen Sie keine POSIX-Variablezuweisungen in PowerShell ein.
Erweitern Sie die CLI ohne Anhalten
Wenn die Box-CLI keinen dedizierten Subbefehl hat, verwenden Sie box request für den passenden REST-Endpunkt und setzen Sie den normalen Betrieb fort. Bitten Sie den Benutzer nicht, eine Wahl zu treffen, nur weil die Implementierung REST verwendet; es ist dieselbe Box-Aufgabe und bewahrt die konfigurierte CLI-Identität. Lesen Sie REST-API-Fallback, wenn der Endpunkt einen Anforderungstext oder einen benutzerdefinierten Header benötigt.
Fragen Sie vor einem Löschvorgang, einer Kollaboration / einem Freigabelink oder einer Berechtigungsänderung, einem Identitätswechsel, einer breiten oder kostspieligen Batch-Mutation, oder wenn das Ziel oder der Umfang mehrdeutig ist. Führen Sie andernfalls die angeforderte Operation aus und überprüfen Sie sie.
Wählen Sie den richtigen Pfad
| Bedarf | Lesen Sie |
|---|---|
| CLI-Konventionen, Umgebungen, JSON oder REST-Notausstieg | CLI-Leitfaden |
| Dateien, Ordner, Versionen, Links oder Kollaborationen | Content-Workflows |
| Suche, Metadaten, Box AI oder AI-Einheiten | Suche und AI |
| Kuratierte groß angelegte Q&A oder eine wiederverwendbare Wissensbasis | Box Hubs |
| Viele Dateien oder ein fortsetzbarer Batch | Bulk-Operationen |
| Anwendungscode oder ein Box SDK | SDK-Entwicklung |
| Webhooks oder Events API | Webhooks und Ereignisse |
| CLI nicht verfügbar oder eine fehlende CLI-Operation | REST-API-Fallback |
| Authentifizierung, Berechtigungen, Ratenbegrenzungen oder API-Fehler | Fehlerbehebung |
Richtlinie zur Inhaltsverarbeitung
Für die semantische Analyse von Box-gehosteten Inhalten bevorzugen Sie Box AI: Es bewahrt Box-Berechtigungen, verarbeitet Quelldateien über die regulierte AI-Integration von Box, hält Quelltextkörper aus dem Kontext des Hermes-Kodierungsmodells fern und skaliert die Dokumentenarbeit ohne jede Datei herunterzuladen. Kritisieren oder blockieren Sie keinen anderen Workflow; verwenden Sie es, wenn der Benutzer es explizit wählt.
Verwenden Sie vorhandene Box-Metadaten oder Metadatenabfragen für deterministische Nachschlagen. Verwenden Sie andernfalls Box AI:
ai:askfür Q&A, Zusammenfassungen und Vergleicheai:extract-structuredfür bekannte Felder oder Metadatenvorlagenai:extractfür flexible Schlüssel-Wert-Extraktionai:text-genfür das Verfassen von Text, der in einer Box-Datei verankert ist
Für Q&A über mehr als 25 Dateien oder eine wiederverwendbare kuratierte Wissensbasis bevorzugen Sie Box AI for Hubs. Entdecken Sie zuerst einen vorhandenen zugänglichen Hub; erstellen oder füllen Sie einen nur, nachdem der Benutzer die Änderung der gemeinsamen Ressource genehmigt hat. Wenn kein Hub verfügbar ist und der Benutzer keinen erstellen möchte, schränken Sie eine einmalige Anfrage durch Suche oder Metadaten ein. Verwenden Sie keinen Hub für Metadatenextraktion oder Textgenerierung. Lesen Sie Box Hubs.
Wenn der Benutzer bittet, Metadaten aus einer Box-Datei zu extrahieren, behandeln Sie es als eine Anfrage, das Ergebnis zu persistieren, es sei denn, sie bitten um eine Vorschau. Verwenden Sie strukturierte Extraktion mit Inline-Feldern, wenn das gewünschte Schema bekannt ist, und freie Extraktion, wenn die Felder explorativ sind. Verwenden Sie eine kompatible vorhandene Unternehmensvorlage wieder, wenn sie jedes angeforderte Feld repräsentiert. Speichern Sie andernfalls flache skalare Ergebnisse in der integrierten global.properties-Metadateninstanz oder laden Sie einen JSON-Sidecar neben die Quelldatei hoch, wenn das Ergebnis verschachtelte Objekte, Tabellen oder Werte enthält, die ihre Typen behalten müssen. Lesen Sie jeden Rückschreibevorgang und vergleichen Sie ihn mit dem beabsichtigten Ergebnis. Ersetzen Sie niemals stillschweigend eine Dateibeschreibung, hängen Sie eine teilweise oder nicht verwandte Vorlage an, kürzen Sie Felder oder verwerfen Sie Felder.
Erstellen oder ändern Sie keine Metadatenvorlagen. Box erlaubt keine Erstellung globaler Vorlagen, und die Verwaltung von Unternehmensvorlagen liegt außerhalb des normalen OAuth-Inhaltsworkflows von Hermes. Wenn der Benutzer wiederverwendbare typisierte Unternehmensmetadaten benötigt und keine kompatible Vorlage existiert, erklären Sie, dass ein Box-Administrator oder ein autorisierter Co-Administrator sie separat erstellen muss, lassen Sie vorhandene strukturierte Metadaten unverändert und melden Sie die persistierte global.properties-Instanz oder den JSON-Sidecar. Lesen Sie Suche und AI für den vollständigen Extraktions- und Rückschreibeworkflow.
Geben Sie vor der ersten Box-AI-Anfrage an, dass Box AI aktiviert sein muss, AI-Einheiten verbraucht und auf die Berechtigungen des aktuellen Akteurs beschränkt bleibt; warten Sie nicht auf eine Bestätigung. Eine an Hermes zurückgegebene AI-Antwort kann dennoch sensible Informationen enthalten. Bestätigen Sie nur, wenn der Dateiumfang oder die erwartete Nutzung von AI-Einheiten eines wesentlichen Batches mehrdeutig ist oder der Benutzer diesen Umfang nicht explizit angefordert hat. Siehe Suche und AI.
Sicher arbeiten
- Bevorzugen Sie IDs gegenüber Pfaden und überprüfen Sie den aktuellen Akteur, bevor Sie eine fehlende Datei diagnostizieren.
- Verwenden Sie
--jsonund--fields, um die Ausgabe klein zu halten. Erfassen Sie bei Mutationen zuerst den Bestand, bestätigen Sie mehrdeutigen oder großen Umfang, lesen Sie dann das Ergebnis zurück. - Führen Sie geordnete CLI-Mutationen seriell aus, sodass Fortschritt und Wiederherstellung eindeutig sind. Verwenden Sie dokumentierte Batch-Eingabeunterstützung oder begrenzte SDK-Nebenläufigkeit für skalierbare Arbeit.
- Erstellen Sie keinen Freigabelink nur zur Navigation. Freigabelinks ändern den Zugriff und erfordern eine explizite Bestätigung.
- Geben Sie Geheimnisse nicht im Chat, in der Befehlsausgabe, in der Versionskontrolle oder in Protokollen preis.
Ergebnisse melden
Für jedes einzeln gemeldete Box-Element geben Sie dessen ID und einen klickbaren Navigationslink an:
- Datei:
https://app.box.com/file/<DATEI_ID> - Ordner:
https://app.box.com/folder/<ORDNER_ID> - Hub:
https://app.box.com/hubs/<HUB_ID>
Für große Batches verlinken Sie die Quell- und Zielordner sowie Ausnahmen anstatt hunderte von Elementen aufzulisten. Ein Mensch kann möglicherweise keine Inhalte öffnen, die nur für das verbundene Box-Konto sichtbar sind; geben Sie dies klar an. Fügen Sie den Akteur und die durchgeführte Überprüfung in jede Zusammenfassung eines Schreibvorgangs ein.
Überprüfen
Nach jedem Schreibvorgang, rufen Sie die Datei oder den Ordner mit demselben Akteur ab oder listen Sie dessen übergeordnetes Element auf und bestätigen Sie die zurückgegebene ID und den Namen. Für einen Metadaten-Schreibvorgang, rufen Sie die Metadateninstanz ab und vergleichen Sie jedes zurückgegebene Feld mit dem beabsichtigten Wert; ein HTTP-Erfolg allein ist keine Überprüfung. Melden Sie fehlende, normalisierte oder abgelehnte Werte. Erstellen Sie für eine einmalige Einrichtungsprüfung einen Testordner, überprüfen Sie ihn und löschen Sie ihn dann nur, wenn der Benutzer die Bereinigung autorisiert hat.