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 的账户。
不要运行设置、展示命令手册、提出账户方案或文件夹分类法,也不要为宽泛的探索性问题加载所有参考文档。等待用户回答,然后仅加载相关的路径。当请求已经指定了具体结果时,跳过这一探索步骤,直接处理该结果。
从官方的 Box CLI OAuth 应用开始常规的 CLI 工作。它涵盖了普通的内容操作和 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、容器或云虚拟机)上运行?” 仅在“同一台计算机”路径下使用正常的
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 开发 |
| Webhooks 或 Events API | Webhooks 与事件 |
| 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 并且用户不希望创建,则通过搜索或元数据缩小一次性请求的范围。不要将 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 成功不算验证。报告缺失、规范化或拒绝的值。对于一次性设置检查,创建一个烟雾测试文件夹,验证它,然后仅在用户授权清理时删除它。