Box
ファイル操作、コラボレーション、メタデータ、文書作業のためにBoxをクラウドファイルシステムとして使用します。HermesのterminalツールでBox CLIを使って操作を実行し、アプリケーションを構築する場合はSDKガイドを使用します。
使用するタイミング
- Boxのファイルやフォルダを整理、アップロード、バージョン管理、移動、共有、またはコラボレーションする場合
- Boxのコンテンツや既存のメタデータを検索する場合
- Boxファイルに関する質問、メタデータの抽出、ファイルに基づいたテキスト生成を行う場合
- すべてのソースファイルをダウンロードせずにBoxフォルダを大規模に処理する場合
- Boxをバックエンドとするアプリケーション、統合、またはWebhookハンドラを構築する場合
ファイルシステムに関する幅広い会話を始める
誰かがHermesのクラウドファイルシステムを探索している場合、最初に簡単な適合性評価を行います。Boxは、チームがクラウドファイルストレージ、共有、検索、メタデータ、文書作業を必要とする場合に便利です。その後、OAuthを使用してBoxアカウントを接続するか、SDKを使用してBoxをバックエンドとするアプリケーションまたは統合を構築するかを尋ねます。
Oauthを使用すると、Hermesはブラウザで承認されたBoxアカウントとして動作します。そのアカウントのBox権限によって、Hermesがアクセスできるものが決まります。Hermesにより狭いアクセス権限を与えるには、必要なファイル、フォルダ、またはHubにのみ招待されているアカウントを承認します。
セットアップを実行したり、コマンドのクックブックを表示したり、アカウントプランやフォルダの分類を提案したり、幅広い探索的な質問に対してすべてのリファレンスをロードしたりしないでください。ユーザーの回答を待ち、関連するパスのみをロードします。リクエストに具体的な成果物がすでに指定されている場合は、この発見ステップをスキップし、その成果物を直接処理します。
通常のCLI作業は、公式のBox CLI OAuthアプリで開始します。これにより、通常のコンテンツ作業とBox AIがカバーされます。Webhook管理など、リクエストされた操作に追加のOAuthスコープが必要な場合にのみ、カスタムのユーザー認証(OAuth 2.0) プラットフォームアプリを使用します。これは依然としてOAuthフローです。サーバーサイドやインパーソネーションIDに置き換えないでください。
選択したセットアップを対話的に実行する
ユーザーが認証パスを選択した場合、またはHermesにBoxを接続するように依頼した場合は、terminalを介してセットアップを実行します。次の応答をユーザーがコピーするための指示にしないでください。自分で次の安全なアクションを実行し、承認、ブラウザサインイン、管理者アクション、またはHermesが安全に提供できないシークレットのためにのみ一時停止します。
boxが欠落している場合は、現在のHermesホームのtools/box-cliに@box/cliをインストールするために必要なターミナル承認を求めます。その後、CLIガイドのシェルに適したコマンドで確認します。グローバルなnpmインストール、sudoの使用、npmのグローバルプレフィックスの変更、またはPATHの変更は試みないでください。- OAuthの前に、「HermesはBoxを承認するために使用するブラウザと同じコンピュータで実行されていますか、それともVPS、コンテナ、クラウドVMなどのリモートホストで実行されていますか?」 と尋ねます。同じコンピュータパスには通常の
box loginのみを使用します。リモート/ヘッドレスパスにはbox login --codeのみを使用します。オペレーティングシステムだけでランタイムトポロジを推測しないでください。ユーザーが回答した後、OAuth setupを読んでください。 - ブラウザ認証を開始する前に、HermesはそこでサインインしたBoxアカウントとして動作することを明記します。ユーザーがより狭いアクセス権限を希望する場合は、必要なファイル、フォルダ、またはHubにのみ招待されているアカウントを承認できます。特別な操作を許可するためにそのアカウントを管理者にしないでください。
- カスタムOAuthプラットフォームアプリが必要な場合は、CLIのインタラクティブなプラットフォームアプリフローを使用します。ユーザーに、ローカルのCLIプロンプトでのみクライアントシークレットを入力するように依頼します。チャットで要求したり、Hermes設定に書き込んだり、コミットしたりしないでください。
- インストール、ブラウザ認証、環境の切り替え、または権限変更に承認が必要な場合は、その承認を要求し、承認が付与された後にセットアップを再開します。アクションをコマンドリストに置き換えないでください。
各タスクを開始する
- CLIと現在のアクターを確認します。POSIXシェルでは
command -v box、PowerShellではGet-Command box -ErrorAction SilentlyContinueでプローブします。boxがPATHにある場合はそれを使用します。HermesがCLIを現在のホームの下にインストールした場合は、すべての先頭のboxの代わりに、CLIガイドのシェルに適した検証済みランナーを使用します。次に、そのランナーでbox users:get me --json --fields id,name,loginを実行します。 成功した場合は、アクターを記録して続行します。認証について再度尋ねないでください。folders:items 0はアクターのルートのリストとしてのみ扱います。共有ファイル、フォルダ、またはHubにアクセスできないことの証明にはなりません。既知のファイルまたはフォルダの場合は、そのIDを直接確認します。Hubの場合は、Box HubsのHubs発見パスを使用します。 - 認証がない場合は、OAuthでBoxアカウントを接続するように依頼し、次にHermesと承認ブラウザが同じコンピュータで実行されているか、別々のホストで実行されているかを尋ねます。OAuth setupを読んでください。
- 操作する前に関連するリファレンスを読んでください。最初に文書化されたコマンドを使用します。リクエストにリファレンスでカバーされていないオプションが必要な場合、またはインストールされたCLIが文書化された形式を拒否した場合にのみ、サブコマンドのヘルプを実行します。
bashとラベル付けされた例はPOSIXの継続構文を使用しています。PowerShellでは、Boxコマンドを1行で実行するか、各末尾の をPowerShellのバックティック継続に置き換えます。POSIX変数代入をPowerShellに貼り付けないでください。
`をPowerShellのバックティック継続に置き換えます。POSIX変数代入をPowerShellに貼り付けないでください。
一時停止せずにCLIを拡張する
Box CLIに専用のサブコマンドがない場合は、一致するRESTエンドポイントにbox requestを使用し、通常の操作を続行します。実装がRESTを使用しているという理由だけでユーザーに選択を求めないでください。それは同じBoxタスクであり、構成されたCLI IDを保持します。エンドポイントにリクエストボディまたはカスタムヘッダーが必要な場合は、REST API fallbackを読んでください。
削除、コラボレーション/共有リンクまたは権限変更、ID変更、広範囲またはコストのかかるバッチ変更、またはターゲットやスコープが不明確な場合には、事前に確認してください。それ以外の場合は、要求された操作を実行して確認します。
適切なパスを選択する
| ニーズ | 読むドキュメント |
|---|---|
| CLI規則、環境、JSON、またはRESTエスケープハッチ | CLIガイド |
| ファイル、フォルダ、バージョン、リンク、コラボレーション | コンテンツワークフロー |
| 検索、メタデータ、Box AI、AIユニット | 検索とAI |
| 厳選された大規模Q&Aまたは再利用可能なナレッジベース | Box Hubs |
| 多数のファイルまたは再開可能なバッチ | 一括操作 |
| アプリケーションコードまたはBox SDK | SDK開発 |
| WebhookまたはイベントAPI | Webhookとイベント |
| CLIが利用できない、またはCLI操作がない場合 | REST APIフォールバック |
| 認証、権限、レート制限、APIエラー | トラブルシューティング |
コンテンツ処理ポリシー
Boxホストコンテンツのセマンティック分析には、Box AIを優先します。Box AIはBoxの権限を保持し、BoxのガバナンスされたAI統合を介してソースファイルを処理し、ソースファイルの本文をHermesのコーディングモデルコンテキストから遠ざけ、すべてのファイルをダウンロードせずに文書作業をスケーリングします。他のワークフローを批判したりブロックしたりしないでください。ユーザーが明示的にそれを選択した場合に使用します。
決定論的なルックアップには、既存のBoxメタデータまたはメタデータクエリを使用します。それ以外の場合はBox AIを使用します:
- Q&A、要約、比較には
ai:ask - 既知のフィールドまたはメタデータテンプレートには
ai:extract-structured - 柔軟なキーと値の抽出には
ai:extract - 1つのBoxファイルに基づいたライティングには
ai:text-gen
25ファイル以上、または再利用可能な厳選されたナレッジベースに対するQ&Aには、Box AI for Hubsを優先します。まずアクセス可能な既存のHubを発見します。ユーザーが共有リソースの変更を承認した後にのみ、Hubを作成または設定します。Hubが利用できず、ユーザーが作成を希望しない場合は、検索またはメタデータを使用して1回限りのリクエストを絞り込みます。メタデータ抽出やテキスト生成にHubを使用しないでください。Box Hubsを読んでください。
ユーザーがBoxファイルからメタデータを抽出するように要求した場合、プレビューを要求しない限り、結果を永続化するリクエストとして扱います。必要なスキーマがわかっている場合はインラインフィールドを使用した構造化抽出を使用し、フィールドが探索的な場合は自由形式抽出を使用します。要求されたすべてのフィールドを表す互換性のある既存のエンタープライズテンプレートがある場合はそれを再利用します。それ以外の場合は、組み込みのglobal.propertiesメタデータインスタンスにフラットなスカラー結果を保存するか、結果にネストされたオブジェクト、テーブル、または型を保持する必要がある値が含まれている場合は、ソースファイルの横にJSONサイドカーをアップロードします。すべての書き戻しを読み取り、意図した結果と比較します。ファイルの説明を静かに置き換えたり、部分的または無関係なテンプレートを添付したり、フィールドを切り詰めたり、フィールドを破棄したりしないでください。
メタデータテンプレートを作成または変更しないでください。Boxではグローバルテンプレートの作成は許可されておらず、エンタープライズテンプレートの管理はHermesの通常のOAuthコンテンツワークフローの範囲外です。ユーザーが再利用可能な型付きエンタープライズメタデータを必要としており、互換性のあるテンプレートが存在しない場合は、Box管理者または承認された共同管理者が個別に作成する必要があることを説明し、既存の構造化メタデータを変更せずにそのままにし、永続化されたglobal.propertiesインスタンスまたはJSONサイドカーを報告します。完全な抽出と書き戻しのワークフローについては、検索とAIを読んでください。
最初のBox AIリクエストの前に、Box AIが有効である必要があり、AIユニットを消費し、現在のアクターの権限に制限されることを述べます。確認を待たないでください。Hermesに返されたAI応答には、依然として機密情報が含まれている可能性があります。重要なバッチのファイル範囲または予想されるAIユニット使用量が不明確な場合、またはユーザーがその規模を明示的に要求していない場合にのみ確認します。検索とAIを参照してください。
安全に操作する
- パスよりもIDを優先し、欠落しているファイルを診断する前に現在のアクターを確認します。
- 出力を小さく保つために
--jsonと--fieldsを使用します。変更の場合は、最初にインベントリを作成し、不明確または大規模なスコープを確認してから、結果を読み返します。 - 進捗状況とリカバリが明確になるように、順序付けられたCLI変更を直列に実行します。スケーラブルな作業には、文書化されたバルク入力サポートまたは制限付きSDK同時実行を使用します。
- ナビゲーションを提供するためだけに共有リンクを作成しないでください。共有リンクはアクセスを変更し、明示的な確認が必要です。
- シークレットをチャット、コマンド出力、ソース管理、またはログに入れないでください。
結果を報告する
個別に報告されるすべてのBoxアイテムについて、そのIDとクリック可能なナビゲーションリンクを含めます:
- ファイル:
https://app.box.com/file/<FILE_ID> - フォルダ:
https://app.box.com/folder/<FOLDER_ID> - Hub:
https://app.box.com/hubs/<HUB_ID>
大規模なバッチの場合は、何百ものアイテムをリストする代わりに、ソースと宛先のフォルダ、および例外をリンクします。人間は接続されたBoxアカウントにのみ表示されるコンテンツを開くことができない場合があります。そのことを明確に述べてください。すべての書き込みサマリーにアクターと実行された検証を含めます。
検証
書き込み後、同じアクターでファイルまたはフォルダをフェッチするか、その親をリストし、返されたIDと名前を確認します。メタデータ書き込みの場合は、メタデータインスタンスを取得し、返されたすべてのフィールドを意図した値と比較します。HTTP成功だけでは検証になりません。欠落、正規化、または拒否された値を報告します。使い捨てのセットアップチェックの場合は、スモークフォルダを作成し、検証してから、ユーザーがクリーンアップを承認した場合にのみ削除します。