box

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 スコープが必要な操作を依頼された場合に限り、カスタムの User Authentication (OAuth 2.0) Platform App を使用します。これは引き続き OAuth フローです。サーバー側の ID や偽装 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 セットアップを読んでください。
• ブラウザー認証を開始する前に、Hermes がそこでサインインした Box アカウントとして動作することを伝えてください。ユーザーがアクセス範囲を限定したい場合は、必要なファイル、フォルダー、または Hub のみに招待されたアカウントを認証できます。例外的な操作を可能にするために、そのアカウントを管理者にしないでください。
• カスタム OAuth Platform App が必要な場合は、CLI の対話型 Platform App フローを使用してください。クライアントシークレットはローカル CLI プロンプトにのみ入力するようユーザーに依頼してください。チャットでシークレットを求めたり、Hermes の設定に書き込んだり、コミットしたりしないでください。
• インストール、ブラウザー認証、環境の切り替え、または権限の変更に承認が必要な場合は、その承認を求め、承認後にセットアップを再開してください。操作の代わりにコマンド一覧を提示しないでください。

各タスクの開始時

1. CLI と現在のアクターを確認します。POSIX シェルでは command -v box、PowerShell では Get-Command box -ErrorAction SilentlyContinue で確認します。box が PATH にあれば、それを使用します。Hermes が現在のホームディレクトリに CLI をインストールしている場合は、CLI guide に記載されたシェルに適した検証済みの実行方法を、先頭の box の代わりに使用します。その実行方法で box users:get me --json --fields id,name,login を実行します。 成功した場合は、アクターを記録して続行します。認証について再度尋ねないでください。folders:items 0 はアクターのルートを一覧表示したものにすぎず、共有ファイル、フォルダー、Hub にアクセスできない証拠ではありません。既知のファイルまたはフォルダーについては、その ID を直接検証します。Hub については、Box Hubs に記載された Hub の検出手順を使用します。
2. 認証がない場合は、OAuth で Box アカウントに接続するよう依頼し、続けて Hermes と認可ブラウザーが同じコンピューター上で動作しているか、別々のホスト上で動作しているかを尋ねます。OAuth setup を読みます。
3. 操作の前に、関連するリファレンスを読みます。まず文書化されたコマンドを使用します。リクエストにリファレンスで説明されていないオプションが必要な場合、またはインストール済みの CLI が文書化された形式を受け付けない場合に限り、サブコマンドのヘルプを実行します。

bash とラベル付けされた例では、POSIX の行継続構文を使用しています。PowerShell では、Box コマンドを 1 行で実行するか、行末の \ をそれぞれ PowerShell のバッククォートに置き換えてください。POSIX の変数代入を PowerShell に貼り付けないでください。

CLI を一時停止せずに拡張する

Box CLI に専用のサブコマンドがない場合は、該当する REST エンドポイントに box request を使用し、通常の操作を続行します。実装が REST を使用するという理由だけで、ユーザーに選択を求めないでください。同じ Box タスクであり、設定済みの CLI の認証情報が維持されます。エンドポイントにリクエスト本文またはカスタムヘッダーが必要な場合は、REST API fallback を読みます。

削除、コラボレーション／共有リンクまたは権限の変更、ID の変更、広範囲またはコストのかかる一括変更を行う前、あるいは対象や範囲が曖昧な場合は、確認を求めてください。それ以外の場合は、依頼された操作を実行して検証します。

適切な手順を選ぶ

必要な内容	参照先
CLI の規則、環境、JSON、または REST の代替手段	CLI guide
ファイル、フォルダー、バージョン、リンク、またはコラボレーション	Content workflows
検索、メタデータ、Box AI、または AI ユニット	Search and AI
厳選された大規模な Q&A、または再利用可能なナレッジベース	Box Hubs
多数のファイル、または再開可能な一括処理	Bulk operations
アプリケーションコード、または Box SDK	SDK development
Webhook、または Events API	Webhooks and events
CLI が利用できない、または CLI に操作がない	REST API fallback
認証、権限、レート制限、または API エラー	Troubleshooting

コンテンツの取り扱い方針

Box でホストされているコンテンツを意味解析する場合は、Box AI を優先してください。Box の権限が維持され、Box が管理する AI 統合を通じてソースファイルが処理されるため、ソースファイルの本文が Hermes のコーディングモデルのコンテキストに含まれず、すべてのファイルをダウンロードせずにドキュメント処理を拡張できます。他のワークフローを批判したり、妨げたりしないでください。ユーザーが明示的に選択した場合は、そのワークフローを使用してください。

決定的な検索には、既存の Box メタデータまたはメタデータクエリを使用してください。それ以外の場合は Box AI を使用してください。

• ai:ask は Q&A、要約、比較に使用します
• ai:extract-structured は既知のフィールドまたはメタデータテンプレートに使用します
• ai:extract は柔軟なキーと値の抽出に使用します
• ai:text-gen は Box ファイル 1 件の内容に基づく文章の作成に使用します

25 件を超えるファイルに対する Q&A、または再利用可能なキュレーション済みナレッジベースには、Box AI for Hubs を優先してください。まずアクセス可能な既存の Hub を探してください。共有リソースの変更についてユーザーの承認を得てから、Hub の作成またはデータの登録を行ってください。利用可能な Hub がなく、ユーザーが Hub の作成を望まない場合は、検索またはメタデータを使って、1 回限りのリクエストの範囲を絞ってください。メタデータの抽出や文章の生成に Hub を使用しないでください。Box Hubs をお読みください。

ユーザーが Box ファイルからメタデータを抽出するよう依頼した場合、プレビューを求めていない限り、結果を保存する依頼として扱ってください。目的のスキーマがわかっている場合はインラインフィールドを指定した構造化抽出を、フィールドが未確定の場合は自由形式の抽出を使用します。要求されたすべてのフィールドを表す互換性のある既存のエンタープライズテンプレートがあれば、それを再利用してください。それ以外の場合は、フラットなスカラー値の結果を組み込みの global.properties メタデータインスタンスに保存するか、結果にネストされたオブジェクト、テーブル、または型を維持すべき値が含まれる場合は、ソースファイルの隣に JSON サイドカーファイルをアップロードしてください。すべての書き込み結果を読み戻し、意図した結果と比較してください。ファイルの説明にひそかに置き換えたり、不完全または無関係なテンプレートを適用したり、フィールドを切り詰めたり、破棄したりしないでください。

メタデータテンプレートを作成または変更しないでください。Box ではグローバルテンプレートを作成できず、エンタープライズテンプレートの管理は Hermes の通常の OAuth コンテンツワークフローの範囲外です。再利用可能な型付きエンタープライズメタデータが必要で、互換性のあるテンプレートが存在しない場合は、Box 管理者または権限を持つ共同管理者が別途作成する必要があることを説明し、既存の構造化メタデータは変更せず、保存された global.properties インスタンスまたは JSON サイドカーファイルを報告してください。抽出と書き戻しのワークフロー全体については、Search and AI をお読みください。

Box AI に初めてリクエストする前に、Box AI を有効にする必要があること、AI ユニットを消費すること、現在のアクターの権限の範囲内に限られることを伝えてください。了承を待つ必要はありません。Hermes に返された AI の回答にも、機密情報が含まれる可能性があります。対象ファイルの範囲または予想される AI ユニットの使用量が不明確な大量処理の場合、あるいはユーザーがその規模を明示的に依頼していない場合に限り、確認してください。Search and 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 の成功だけでは検証になりません。欠落した値、正規化された値、拒否された値を報告してください。使い捨てのセットアップ確認では、スモークフォルダーを作成して検証し、ユーザーがクリーンアップを許可した場合に限り削除してください。