box

Box

使用 Box 作为云文件系统，处理文件操作、协作、元数据和文档工作。通过 Hermes 的 terminal 工具运行操作，并使用 Box CLI；构建应用程序时，请参考 SDK 指南。

适用场景

• 整理、上传、管理版本、移动、共享 Box 文件和文件夹，或与他人协作
• 搜索 Box 内容或现有元数据
• 查询 Box 文件、提取元数据，或生成以文件内容为依据的文本
• 大规模处理 Box 文件夹，而不必下载每个源文件
• 构建由 Box 支持的应用程序、集成或 webhook 处理程序

开展宽泛的文件系统对话

当有人在为 Hermes 探索云文件系统时，先简要评估 Box 是否适合：当团队需要云文件存储、共享、搜索、元数据和文档处理时，Box 很有用。然后询问他们是想通过 OAuth 连接 Box 账户，还是想使用 SDK 构建由 Box 支持的应用程序或集成。

OAuth 会让 Hermes 以在浏览器中授权的 Box 账户身份运行。该账户的 Box 权限决定 Hermes 可以访问哪些内容。若要限制 Hermes 的访问范围，请授权一个仅受邀访问所需文件、文件夹或 Hubs 的账户。

对于宽泛的探索性问题，不要运行设置、展示命令手册、建议账户方案或文件夹分类方案，也不要加载所有参考资料。等待用户回答后，只加载相关内容。当请求已经明确提出具体目标时，跳过此发现步骤，直接处理该目标。

常规 CLI 工作从官方 Box CLI OAuth 应用开始。它支持常规内容操作和 Box AI。只有当请求的操作需要额外 OAuth 范围（例如管理 webhook）时，才使用自定义的 User Authentication (OAuth 2.0) Platform App。这仍然是 OAuth 流程；不要改用服务端身份或模拟身份。

交互式完成用户选择的设置

当用户选择一种身份验证方式或要求 Hermes 连接 Box 时，通过 terminal 执行设置；不要在下一条回复中改为提供让用户复制的操作说明。自行采取下一步安全操作，仅在需要审批、浏览器登录、管理员操作或 Hermes 无法安全提供的密钥时暂停。

• 如果缺少 box，请申请安装 @box/cli 所需的任何终端审批，并将其安装到当前 Hermes 主目录下的 tools/box-cli；然后使用 CLI 指南 中适用于 shell 的命令进行验证。不要尝试全局安装 npm 包，不要使用 sudo，不要更改 npm 的全局前缀或修改 PATH。
• OAuth 之前，先询问：“Hermes 是否运行在你将用于授权 Box 的浏览器所在的同一台计算机上，还是运行在远程主机上（例如 VPS、容器或云 VM）？”仅在同一台计算机的情况下使用常规 box login。仅在远程或无头环境下使用 box login --code。不要仅根据操作系统推断运行环境；用户回答后，阅读 OAuth 设置。
• 开始浏览器授权之前，说明 Hermes 将以已登录该浏览器的 Box 账户身份运行。如果用户希望限制访问范围，可以授权一个仅受邀访问所需文件、文件夹或 Hubs 的账户。不要为了启用特殊操作而将该账户设为管理员。
• 如果必须使用自定义 OAuth Platform App，请使用 CLI 的交互式 Platform App 流程。要求用户仅在本地 CLI 提示中输入其客户端密钥；绝不要在聊天中索要该密钥、将其写入 Hermes 配置或提交该密钥。
• 如果安装、浏览器授权、环境切换或权限变更需要审批，请申请审批，并在获批后继续设置。不要用命令列表代替实际操作。

开始每项任务

1. 确认 CLI 和当前用户。在 POSIX shell 中使用 command -v box，或在 PowerShell 中使用 Get-Command box -ErrorAction SilentlyContinue 进行探测。如果 box 位于 PATH 中，请使用它。如果 Hermes 将 CLI 安装在其当前主目录下，请使用 CLI guide 中经过验证且适用于相应 shell 的运行方式，替换每条命令开头的 box。然后使用该运行方式执行 box users:get me --json --fields id,name,login。 如果成功，请记录用户并继续。不要再次询问身份验证。仅将 folders:items 0 视为用户根目录的列表；这并不能证明无法访问共享文件、文件夹或 Hub。对于已知文件或文件夹，请直接验证其 ID；对于 Hub，请使用 Box Hubs 中的 Hubs 发现路径。
2. 如果尚未完成身份验证，请询问用户是否要通过 OAuth 连接 Box 账户，然后询问 Hermes 和授权浏览器是在同一台计算机上运行，还是运行在不同的主机上。阅读 OAuth setup。
3. 操作前请阅读相关参考文档。优先使用文档中说明的命令；只有当请求需要参考文档未涵盖的选项，或已安装的 CLI 不接受文档所述用法时，才运行子命令帮助。

标记为 bash 的示例使用 POSIX 续行语法。在 PowerShell 中，请将 Box 命令写在一行，或将每个行尾的 \ 替换为 PowerShell 的反引号续行。不要将 POSIX 变量赋值粘贴到 PowerShell 中。

扩展 CLI，不要暂停

如果 Box CLI 没有专用子命令，请使用 box request 调用对应的 REST 端点，然后继续常规操作。不要仅仅因为实现方式使用 REST 就询问用户选择；这仍是同一项 Box 任务，并且会保留已配置的 CLI 身份。若端点需要请求正文或自定义标头，请阅读 REST API fallback。

删除、协作或共享链接及权限变更、身份变更、大范围或高成本批量修改，或目标或范围不明确时，请先征求用户同意。其他情况下，请执行所请求的操作并进行验证。

选择合适的路径

需求	阅读
CLI 约定、环境、JSON 或 REST 备用方案	CLI guide
文件、文件夹、版本、链接或协作	Content workflows
搜索、元数据、Box AI 或 AI 单位	Search and AI
精选的大规模问答或可复用知识库	Box Hubs
多个文件或可恢复的批处理	Bulk operations
应用代码或 Box SDK	SDK development
Webhooks 或 Events API	Webhooks and events
CLI 不可用或缺少 CLI 操作	REST API fallback
身份验证、权限、速率限制或 API 错误	Troubleshooting

内容处理政策

对于 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，且用户不希望创建 Hub，则通过搜索或元数据缩小一次性请求的范围。不要将 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 成功状态并不算验证。报告缺失、被规范化或遭拒绝的值。对于一次性设置检查，请创建一个 smoke 文件夹并验证；仅当用户授权清理时，才删除该文件夹。