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 更有限的存取權限，請授權一個僅被邀請存取所需檔案、資料夾或 Hubs 的帳戶。
對於一個廣泛的探索性問題，請不要執行設定、顯示指令手冊、提出帳戶方案或資料夾分類法，或載入所有參考資料。請等待使用者的回答，然後僅載入相關的路徑。當請求已明確指定具體結果時，請跳過此探索步驟，直接處理該結果。
開始一般 CLI 工作時，請使用官方的 Box CLI OAuth 應用程式。它能涵蓋一般的內容操作和 Box AI。僅在要求的操作需要額外的 OAuth 範圍（例如 Webhook 管理）時，才使用自訂的使用者驗證 (OAuth 2.0) 平台應用程式。這仍然是 OAuth 流程；請勿改用伺服器端或模擬身分。
以互動方式執行所選的設定
當使用者選擇了一條驗證路徑或要求 Hermes 連接 Box 時，請透過 terminal 執行設定；請勿將下一個回應變成供使用者複製的指令。請自行採取下一個安全的操作，並且僅在需要批准、瀏覽器登入、管理員操作或 Hermes 無法安全提供的機密時才暫停。
- 如果缺少
box，請請求任何必要的終端機批准，以便在 Hermes 當前家目錄下的tools/box-cli安裝@box/cli；然後根據 CLI 指南 中適用於該 shell 的指令進行驗證。請勿嘗試全域 npm 安裝、使用sudo、變更 npm 的全域前綴或變更PATH。 - 在 OAuth 之前，請詢問：「Hermes 是與您授權 Box 的瀏覽器執行在同一台電腦上，還是執行在遠端主機（例如 VPS、容器或雲端 VM）上？」 僅在相同電腦的路徑下使用一般的
box login。僅在使用者回答遠端/無頭路徑時，才使用box login --code。請勿僅從作業系統推斷執行階段拓撲；在使用者回答後，請閱讀 OAuth 設定。 - 在開始瀏覽器授權之前，請說明 Hermes 將以在該處登入的 Box 帳戶身分執行操作。如果使用者想要更有限的存取權限，他們可以授權一個僅被邀請存取所需檔案、資料夾或 Hubs 的帳戶。請勿為了執行特殊操作而讓該帳戶成為管理員。
- 如果需要自訂 OAuth 平台應用程式，請使用 CLI 的互動式平台應用程式流程。要求使用者僅在本機 CLI 提示字元中輸入其客戶端密碼；絕不要在聊天中要求、將其寫入 Hermes 設定或提交它。
- 如果安裝、瀏覽器授權、環境切換或權限變更需要批准，請請求該批准，並在批准後繼續設定。請勿用指令清單取代該操作。
開始每個任務
- 確認 CLI 和當前操作者。在 POSIX shell 中使用
command -v box探測，或在 PowerShell 中使用Get-Command box -ErrorAction SilentlyContinue。如果box在PATH中，直接使用它。如果 Hermes 在其當前家目錄下安裝了 CLI，則使用 CLI 指南 中適用於該 shell 的經驗證執行器，來取代每次開頭的box。然後使用該執行器執行box users:get me --json --fields id,name,login。 如果成功，記錄操作者並繼續。不要再詢問驗證問題。僅將folders:items 0視為操作者根目錄的列表；它並不能證明共享的檔案、資料夾或 Hub 無法存取。對於已知的檔案或資料夾，請直接驗證其 ID；對於 Hub，請使用 Box Hubs 中的 Hubs 探索路徑。 - 如果缺少驗證，請要求連接一個帶有 OAuth 的 Box 帳戶，然後詢問 Hermes 和授權瀏覽器是執行在同一台電腦還是不同的主機上。閱讀 OAuth 設定。
- 在操作之前，請閱讀相關的參考資料。優先使用有文件說明的指令；僅在請求需要參考資料未涵蓋的選項，或已安裝的 CLI 拒絕了文件說明的格式時，才執行子命令的幫助訊息。
標記為 bash 的範例使用 POSIX 的續行語法。在 PowerShell 中，請將 Box 指令執行在一行上，或將每個結尾的 \ 替換為 PowerShell 的反引號續行符。請勿將 POSIX 變數賦值貼上到 PowerShell 中。
在不中斷的情況下擴展 CLI
當 Box CLI 缺少專用的子命令時，請使用 box request 呼叫對應的 REST 端點，並繼續一般的操作。請不要僅僅因為實作使用了 REST 就要求使用者做選擇；這仍然是同一個 Box 任務，並且會保留已設定的 CLI 身分。當端點需要請求主體或自訂標頭時，請閱讀 REST API 備援方案。
在執行刪除、協作/共享連結或權限變更、身分變更、廣泛或成本高昂的批次變更，或者目標或範圍不明確之前，請先詢問。否則，請執行請求的操作並進行驗證。
選擇正確的路徑
| 需求 | 閱讀此處 |
|---|---|
| CLI 慣例、環境、JSON 或 REST 逃生門 | CLI 指南 |
| 檔案、資料夾、版本、連結或協作 | 內容工作流程 |
| 搜尋、元資料、Box AI 或 AI 單位 | 搜尋與 AI |
| 策展的大規模問答或可重複使用的知識庫 | Box Hubs |
| 許多檔案或可恢復的批次 | 批次操作 |
| 應用程式程式碼或 Box SDK | SDK 開發 |
| Webhook 或 Events API | Webhook 與事件 |
| CLI 不可用或缺少 CLI 操作 | REST API 備援方案 |
| 驗證、權限、速率限制或 API 錯誤 | 疑難排解 |
內容處理政策
對於 Box 上託管內容的語義分析，優先使用 Box AI：它能維護 Box 權限、透過 Box 受治理的 AI 整合處理原始檔案、避免將原始檔案主體載入到 Hermes 的編碼模型上下文中，並能擴展文件工作而無需下載每個檔案。請勿批評或阻止其他工作流程；在使用者明確選擇時才使用它。
使用現有的 Box 元資料或元資料查詢來進行確定性查找。否則，請使用 Box AI：
ai:ask用於問答、摘要和比較ai:extract-structured用於已知欄位或元資料範本ai:extract用於靈活的鍵值提取ai:text-gen用於根據一個 Box 檔案產生文字
對於超過 25 個檔案的問答，或一個可重複使用的策展知識庫，優先使用 Box AI for Hubs。首先探索現有的可存取 Hub；只有在使用者批准共享資源變更後，才建立或填充一個新的。如果沒有可用的 Hub 且使用者不希望建立一個，則透過搜尋或元資料來縮小一次性請求的範圍。請勿將 Hub 用於元資料提取或文字生成。閱讀 Box Hubs。
當使用者要求從 Box 檔案中提取元資料時，除非他們要求預覽，否則將其視為要求保留結果。當所需模式已知時，使用帶有內聯欄位的結構化提取；當欄位屬於探索性質時，使用自由格式提取。當現有的企業範本能代表所有請求的欄位時，重複使用相容的現有範本。否則，將扁平標量結果儲存在內建的 global.properties 元資料實例中，或者當結果包含巢狀物件、表格或必須保留其類型的值時，將 JSON 側車檔案上傳到原始檔案旁。讀取每次寫回操作，並與預期結果進行比較。切勿在沒有提示的情況下替換檔案描述、附加部分或不相關的範本、截斷欄位或丟棄欄位。
請勿建立或變更元資料範本。Box 不允許建立全域範本，而企業範本的管理超出了 Hermes 一般 OAuth 內容工作流程的範圍。如果使用者需要可重複使用的類型化企業元資料，且沒有相容的範本存在，請解釋 Box 管理員或授權的共同管理員必須單獨建立它，保持現有結構化元資料不變，並改為報告已保留的 global.properties 實例或 JSON 側車檔案。閱讀 搜尋與 AI 以獲得完整的提取和寫回工作流程。
在首次 Box AI 請求之前，請說明 Box AI 必須啟用、會消耗 AI 單位，並且仍然受限於當前操作者的權限；無需等待確認。返回給 Hermes 的 AI 回應仍可能包含敏感資訊。僅在 Material 批次（material batch）的檔案範圍或預期的 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 成功並非驗證。報告遺失、標準化或拒絕的值。對於一次性設定檢查，請建立一個測試資料夾，驗證它，然後僅在使用者授權清理時才刪除它。