{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Box

Box 管理云端文件、分享、搜索和元数据。

Skill 元数据

参考：完整 SKILL.md

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 的账户。

不要为一个宽泛的探索性问题直接运行安装、展示命令手册、提议账户套餐或文件夹分类法，或加载全部参考。等待用户回答，然后只加载相关路径。当请求已点名具体结果时，跳过这一步发现，直接处理该结果。

用官方 Box CLI OAuth 应用开始常规 CLI 工作。它覆盖普通内容工作和 Box AI。仅当请求的操作需要额外 OAuth scope（如 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 账户。若用户想要更窄访问，可授权一个只被邀请到所需文件、文件夹或 Hub 的账户。不要为解锁某个例外操作而把该账户设为管理员。
• 若需要自定义 OAuth 平台应用，使用 CLI 的交互式平台应用流程。只让用户在本地 CLI 提示中输入其 client secret；绝不在聊天中索要、写入 Hermes 配置或提交它。
• 若安装、浏览器授权、环境切换或权限变更需要审批，请求该审批并在批准后继续安装。不要用命令列表替换动作。

开始每个任务

1. 确认 CLI 和当前 actor。在 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。 若成功，记录 actor 并继续。不要再问认证。把 folders:items 0 仅视为 actor 根目录的一次列表；它不证明共享文件、文件夹或 Hub 不可达。对已知文件或文件夹，直接验证其 ID；对 Hub，用 Box Hubs 中的 Hubs 发现路径。
2. 若缺认证，请求用 OAuth 连接 Box 账户，然后问 Hermes 和授权浏览器运行在同一台电脑还是不同主机。阅读 OAuth 设置。
3. 操作前阅读相关参考。先用文档化命令；仅当请求需要参考未覆盖的选项、或已装 CLI 拒绝文档化形式时，才运行子命令帮助。

标为 bash 的示例用 POSIX 续行语法。在 PowerShell 中，把 Box 命令写成一行，或把每个结尾 \ 替换为 PowerShell 的反引号续行。不要把 POSIX 变量赋值粘进 PowerShell。

不暂停地扩展 CLI

当 Box CLI 缺专用子命令时，用 box request 命中对应 REST endpoint 并继续常规操作。不要仅因实现用 REST 就让用户选择；这是同一个 Box 任务，并保留已配置的 CLI 身份。当 endpoint 需要请求体或自定义 header 时，阅读 REST API 回退。

删除、协作者/共享链接或权限变更、身份变更、大范围或高成本批量变更前先询问；目标或作用域模糊时也先询问。否则执行请求的操作并验证。

选对路径

内容处理策略

对 Box 托管内容的语义分析，优先用 Box AI：它保留 Box 权限、通过 Box 受治理的 AI 集成处理源文件、把源文件正文挡在 Hermes 编码模型上下文之外，并在不下载每个文件的情况下扩展文档工作。不要批评或阻断另一工作流；在用户明确选择它时使用。

确定性查询用既有 Box 元数据或元数据查询。否则用 Box AI：

• ai:ask 用于 Q&A、摘要和比较
• ai:extract-structured 用于已知字段或元数据模板
• ai:extract 用于灵活键值提取
• ai:text-gen 用于基于一个 Box 文件的写作

对超过 25 个文件的 Q&A 或可复用精选知识库，优先用面向 Hub 的 Box AI。先发现一个可访问的既有 Hub；仅在用户批准共享资源变更后才创建或填充。若无 Hub 可用且用户不想创建，则用搜索或元数据收窄一次性请求。不要为元数据提取或文本生成使用 Hub。阅读 Box Hubs。

当用户要求从 Box 文件提取元数据时，视为持久化结果的请求，除非他们只要预览。已知 schema 时用带内联字段的结构化提取，字段探索性时用自由提取。当既有企业模板能表示每个请求字段时，复用兼容的既有模板。否则把扁平标量结果存到内置 global.properties 元数据实例；当结果含嵌套对象、表或须保留类型的值时，在源文件旁上传 JSON sidecar。读回每次写入并与预期结果比较。绝不静默替换文件描述、附带部分或无关模板、截断字段或丢弃字段。

不要创建或更改元数据模板。Box 不允许创建全局模板，企业模板管理超出 Hermes 常规 OAuth 内容工作流。若用户需要可复用的类型化企业元数据而无兼容模板存在，说明须由 Box Admin 或授权 Co-Admin 单独创建，保持既有结构化元数据不变，并改为报告持久化的 global.properties 实例或 JSON sidecar。完整提取与回写工作流见 搜索与 AI。

首次 Box AI 请求前，说明 Box AI 必须启用、消耗 AI 单元，且仍限于当前 actor 的权限；不要等待确认。返回给 Hermes 的 AI 响应仍可能含敏感信息。仅当一个实质批次的文件范围或预期 AI 单元用量模糊、或用户未明确要求该规模时才确认。见 搜索与 AI。

安全操作

• 优先用 ID 而非路径，诊断缺失文件前验证当前 actor。
• 用 --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 账户可见的内容；请清楚说明。每次写入摘要都包含 actor 和所做验证。

验证

任何写入后，用同一 actor 拉取文件或文件夹，或列出其父目录，确认返回的 ID 和名称。元数据写入则取回元数据实例，把每个返回字段与预期值比较；仅 HTTP 成功不算验证。报告缺失、规范化或被拒的值。一次性安装检查可建一个冒烟文件夹，验证后仅在用户授权清理时才删除它。