Communitygithub.com

V4TIME/V4SKILL

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

V4SKILL 是什么?

此技能将 Box 深度集成到 Hermes 环境中,使其能够作为 AI 代理的云端文件系统,处理文件操作、协作、元数据和文档工作。它支持通过 OAuth 连接 Box 账户,或使用 Box SDK 构建应用。技能核心遵循“先确认、再行动”的原则,通过 Hermes 的 `terminal` 工具调用 Box CLI,在每一步操作前明确当前认证身份,避免重复认证。对于 CLI 不支持的特定操作,技能会自动使用 `box request` 命令调用对应的 REST API 作为备选方案,保持工作流程的连续性。该技能优先使用 Box AI 进行语义分析(如问答、摘要和元数据提取),以利用其权限控制和安全处理能力。所有写入操作(如文件上传、元数据修改)都会执行读取验证,对比结果以确保数据一致性。它还提供了一套完整的 Box Hub 功能,用于构建可复用的知识库。该技能支持主流的 AI 代理平台(如 Claude Code、Coder、Codex 等),特别适合需要以编程方式、安全且大规模管理 Box 内容的团队。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/V4TIME/V4SKILL/tree/HEAD/productivity/box

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 配置或进行提交。
  • 如果安装、浏览器授权、环境切换或权限更改需要批准,请求该批准,并在获得批准后恢复设置。不要用命令列表替换该操作。

启动每个任务

  1. 确认 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 发现路径。
  2. 如果缺少认证,要求通过 OAuth 连接一个 Box 账户,然后询问 Hermes 和授权浏览器是在同一台计算机上运行还是在不同的主机上运行。阅读 OAuth 设置。
  3. 在操作之前阅读相关参考。优先使用文档化的命令;仅当请求需要参考文档未涵盖的选项,或已安装的 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 SDKSDK 开发
Webhooks 或 Events APIWebhooks 与事件
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 成功不算验证。报告缺失、规范化或拒绝的值。对于一次性设置检查,创建一个烟雾测试文件夹,验证它,然后仅在用户授权清理时删除它。

Individual skills in this repo

This repo contains 12 individual skills — each has its own dedicated page.

相关技能