box

Box

概述

这是处理任何 Box 任务的基础技能。它会将请求路由到合适的工具（MCP、CLI 或 REST）和相应的领域参考文档。使用它可以：

• 清点可用的 Box 工具（MCP → CLI → REST），并设置缺少的工具。
• 使用下方的工具选择表，为操作选择合适的工具。
• 确定哪个参考文件涵盖用户所需的领域。
• 诊断常见的 Box 错误（401/403/404/409/429、内容缺失、操作者错误）。

对于明确要求使用 CLI 的请求，如果已安装 box-cli，则使用它。否则，请使用下方的工具选择和领域路由。

路由请求

工具选择

对于未指定工具的请求，请检查工具是否可用，并使用此表：

操作类型	优先使用	原因
大多数 Agent 工作流（搜索、AI、内容管理、元数据、中心）	MCP	结构化输入输出，支持并发安全，涵盖常见场景
批量操作（批量移动、文件夹树、批量元数据）	CLI	输出精简，可用 --fields 筛选，无需手动进行 REST 身份验证即可使用完整 API
验证和冒烟测试	CLI	可复现，用户可以复制粘贴命令
MCP 范围之外的操作	CLI	覆盖完整 API
MCP 不可用且 CLI 不可用或不适用时的最后手段	直接使用 REST	仅在用户明确确认并获得 REST 身份验证设置指导后使用
构建应用程序代码（SDK/REST 端点、webhook 处理程序）	在代码中使用 SDK 或 REST	这不是 Agent 工具——应编写由用户发布的代码

对于明确要求使用 CLI 的请求，请检查 CLI 是否可用并按照 CLI 设置步骤操作。对于其他请求，请先指导用户设置 MCP，再设置 CLI。只有在用户明确确认可以使用备用方案后，才直接使用 REST。

领域路由

根据用户需求选择要阅读的参考文件：

如果用户需要……	首先阅读	配合阅读	最低限度的验证
上传、文件夹、列表、下载、预览、移动或元数据	references/content-workflows.md	references/auth-and-setup.md	使用同一操作者执行写入后读取
共享、协作（用户/群组）或共享链接	references/collaboration.md	references/content-workflows.md、references/auth-and-setup.md	在更改前后列出协作
查找文件或文件夹（关键词、文件夹名称、元数据搜索）	references/mcp-search.md	references/auth-and-setup.md	操作前确认项目详情
Box AI 问答、摘要、提取或文档检索	references/ai-and-retrieval.md	references/auth-and-setup.md	格式化答案前检查检索质量
Box Hubs——创建、整理或查询中心	references/mcp-hubs.md	references/ai-and-retrieval.md、references/auth-and-setup.md	更改后确认中心项目
从模板生成文档（Doc Gen）	references/mcp-doc-gen.md	references/content-workflows.md、references/auth-and-setup.md	批量操作前确认模板和目标位置
整理、重新整理或跨文件夹批量移动文件；批量添加元数据标签；迁移文件夹结构	references/bulk-operations.md	references/content-workflows.md、references/auth-and-setup.md、references/ai-and-retrieval.md	清点源内容，并确认移动数量与计划一致
事件驱动的内容导入、新文件触发器或 webhook 调试	references/webhooks-and-events.md	references/auth-and-setup.md、references/troubleshooting.md	检查签名，并测试重复投递
401、403、404、409、429、内容缺失或操作者错误	references/troubleshooting.md	references/auth-and-setup.md	使用准确的操作者、对象 ID 和端点复现
不确定适用哪种工作流	references/workflows.md	references/auth-and-setup.md	首先选择最精简的 Box 对象与操作组合

MCP

Box MCP 服务是 Agent 工作流的默认工具。它提供结构化 I/O，支持并发安全，并涵盖常见用例（搜索、Box AI、内容管理、元数据、中心）。请参阅上方的工具选择表，了解何时应优先使用它，而非 CLI 或 REST。

可用性检查

• 调用 who_am_i。如果失败，请完成客户端提供的 MCP OAuth 流程，然后重试。
• 如果身份验证仍然失败，请阅读 references/auth-and-setup.md，了解 MCP 设置步骤，并先引导用户完成设置，再考虑使用其他工具。
• 记录 MCP 是否可用。

工具可用性和文档

Box MCP 工具的最新维护列表见 https://docs.box.com/en/box-mcp/tools。如果缺少预期工具或工具不可用，请参阅 references/troubleshooting.md（MCP tool missing 部分），了解诊断步骤和管理控制台启用方法。

通用指南

• 列出文件夹内容时，如有需要请分页，并对较大的目录进行总结，而不是打印每个项目。
• 对文件执行操作前，优先使用 get_file_details 查看文件详情，以确认文件存在并了解当前状态。
• 对于探索性或演示用途，优先在专用文件夹中操作，而不是对用户的整个 Box 账户执行操作。
• 避免授予或假定拥有广泛的企业级访问权限。默认遵循最小权限原则——仅访问任务所需的文件夹和文件。

用法

Box MCP 功能记录在针对具体领域的参考文件中。请使用上方的领域路由表，为任务选择合适的参考文件：

MCP 类别	参考文件
文件、文件夹、上传、下载、预览、元数据	references/content-workflows.md
搜索（关键词、文件夹、元数据）	references/mcp-search.md
协作（用户/群组）和共享链接	references/collaboration.md
Box AI 问答、提取、结构化元数据提取和 Agent	references/ai-and-retrieval.md
Box Hubs 创建、项目管理和中心级问答	references/mcp-hubs.md
Box Doc Gen 模板和文档生成批次	references/mcp-doc-gen.md

CLI / REST API

上方的工具选择表决定了何时使用 CLI 或直接调用 REST。对于未指定工具的请求，优先使用 MCP，其次是 CLI；只有在用户明确确认后，才将直接调用 REST 作为最后的备用方案。

CLI

可用性检查

• 运行 box users:get me --json。记录 CLI 是否可用。
• 如果 CLI 不可用，请引导用户完成 CLI 设置，然后重试 box users:get me --json。

用法

• 阅读 references/box-cli.md，了解 CLI 优先的身份验证方式、冒烟测试命令、安全的验证模式和并发注意事项。

REST API

根据工具选择表，直接调用 REST 是最后的备用方案——仅当 MCP 和 CLI 均不可用或用户拒绝使用时才采用。

构建用户将要发布的应用代码（SDK/REST 端点、Webhook 处理程序）属于另一种情况——这是你编写的代码，而非 Agent 工具。若代码库中已存在官方 Box SDK，或目标语言有相应 SDK，请优先使用。

对于 SDK 应用代码，如果已安装独立的 box-sdk-development 技能，请使用它；该技能涵盖特定版本的调用、传输方式选择、批量任务、重试和可观测性。

确认和设置

• 绝不可在未告知用户的情况下使用直接 REST 备用方案。继续之前，必须征得用户明确确认。
• 发出请求前，引导用户设置令牌（BOX_ACCESS_TOKEN）并安全处理身份验证信息。
• 将访问令牌、客户端密钥、私钥和 Webhook 密钥保存在环境变量或项目的密钥管理器中。

用法

• 阅读 references/rest-calls.md，了解直接调用 REST 的备用方案模式、身份验证设置和安全的请求模板。

工作流

对接 Box 编写代码时，请按顺序执行以下步骤。

0. 对于明确要求使用 CLI 的请求，请检查 CLI 是否可用：若已安装，请使用 box-cli；否则请参考 references/box-cli.md。对于其他请求，请使用上文 MCP 和 CLI / REST API 部分中的可用性检查，盘点可用的 Box 工具：先检查 MCP（使用 who_am_i，必要时完成客户端提供的 OAuth），再检查 CLI（使用 box users:get me --json），并记录哪些工具可用。缺少工具时，请遵循 Route The Request 中的升级顺序（设置 MCP → 设置 CLI → 经明确确认后使用 REST）。如果任务是构建应用代码（添加 SDK 端点、webhook 处理程序），则工具可用性次要——继续执行步骤 1。
1. 检查代码库中现有的 Box 身份验证、SDK 或 HTTP 客户端、环境变量、webhook 处理程序、Box ID 持久化方式和测试。
2. 在选择端点之前，确定执行操作的身份：已连接的用户、企业服务账号、应用用户或平台提供的令牌。
3. 使用工具选择表选择工具，并通过上文的域路由表确定域参考文档。
4. 确认任务是否会改变访问权限或数据暴露范围。共享链接、协作、身份验证变更、大规模下载和广泛的 AI 检索，在扩大访问权限或范围之前都需要用户明确确认。
5. 阅读所选工具（MCP、CLI 或 REST）的参考文档，以及通过上文的工具选择表和域路由表确定的域参考文档。每个文件涵盖内容的完整注释列表，请参阅本文末尾的 References 部分。
6. 实现最小的端到端流程，以验证集成有效。
7. 添加可运行的验证步骤。优先使用代码库中的测试；否则，如果 CLI 可用且已完成身份验证，请使用原生 Box CLI 命令。只有在用户明确确认后，才将直接使用 Box REST 进行验证作为最后手段。
8. 总结交付内容，包括身份验证上下文、Box ID、环境变量或配置，以及确切的验证命令或测试。

防护措施

每次会话都要阅读并遵循 references/guardrails.md。 其中涵盖破坏性操作的确认关卡、中心修改、文件评论、Doc Gen 输出位置、对外共享文件夹、内容显示偏好设置以及 Box AI 治理。

• 除非用户明确要求更改，否则保留现有 Box 身份验证模型。
• 在引入新的身份验证路径、更改身份验证范围或更改 Box AI 行为之前，先查阅当前的 Box 官方文档。
• 如果代码库已使用官方 Box SDK，或目标语言有受维护的 SDK，应优先使用该 SDK。否则，使用直接 REST 调用，并明确处理请求和响应。
• 在 Agent 工作流中，如果可以配置 MCP 或 CLI，就不要直接改用 REST。提出 REST 备选方案前，先提供 MCP 配置指导，其次提供 CLI 配置指导。
• 切勿在未说明的情况下使用直接 REST 备选方案。进行 REST 调用前，必须征得用户明确确认。
• 将访问令牌、客户端密钥、私钥和 webhook 密钥保存在环境变量或项目的密钥管理器中。
• 区分文件 ID、文件夹 ID、共享链接、元数据模板标识符和协作 ID。
• 将共享链接、协作和元数据写入视为涉及权限的更改。编码或应用这些更改前，确认受众、范围和最小权限。
• 扩大外部访问范围、更改执行操作的身份，或检索超出任务实际所需的文档内容前，必须征得明确确认。
• 当任务需要理解文档内容时，首先尝试使用 Box AI——它在服务端运行，无需下载。完整的优先顺序和备选方案链请参阅 references/ai-and-retrieval.md。
• Box AI 调用间隔至少 1–2 秒。对于批量分类，请采用 references/bulk-operations.md 中的先抽样策略。
• 如果 Box 原生方法（Box AI、搜索、元数据、预览）能在服务端回答问题，就避免下载文件正文或将内容传入外部 AI 管道。
• 仅请求应用实际需要的字段，并保存返回的 Box ID，而不是稍后重新构造路径。
• 作为预防措施，按顺序执行相互依赖的 CLI 写入操作，并将共享 OAuth 环境的进程串行化——详情请参阅 references/box-cli.md。对于批量操作，默认使用 CLI；仅在尝试配置 MCP/CLI 失败或用户明确确认使用 REST 备选方案后，才使用 REST。
• 确保 webhook 和事件使用方具备幂等性。Box 的投递和重试路径可能产生重复事件。
• 对于搜索和问答任务，严格控制 AI 检索范围。先搜索和筛选，再仅检索回答所需的文件。此规则不适用于 Box AI 分类——对文档进行分类时，按照上文的内容理解防护措施，应首先尝试使用 Box AI。
• 不要将 box configure:environments:get --current 用作常规身份验证检查——它可能会输出敏感的环境详情。

验证

• 如果仓库现有的测试或应用流程已覆盖更改后的 Box 行为，应优先使用它们。
• 如果没有更合适的验证方式，且已安装并完成身份验证的 box CLI 可用，应优先使用原生 box CLI 命令。
• 只有在确认 MCP 和 CLI 均不可用或不适用，并且用户明确批准使用 REST 备选方案后，才使用直接 REST 验证。
• 对于 REST 备选方案，先指导用户设置令牌（BOX_ACCESS_TOKEN）并安全处理身份验证，再发出请求。
• 使用 box users:get me --json 确认 CLI 身份验证状态。
• 使用同一执行者发起写入后读取调用来验证变更，并记录对象 ID。
• 对于 webhook，测试最简成功路径、重复投递和签名验证失败处理。
• 对于 AI 工作流，将检索质量与答案格式分别测试。

示例冒烟检查命令请参阅 references/box-cli.md（常见验证命令）。

交付内容

最终答复应包含：

• 本次变更使用的代理身份验证上下文
• 涉及的 Box 对象类型和 ID
• 集成所需的环境变量、机密或配置
• 新增或更改的文件或端点
• 确切的验证命令、脚本或测试路径
• 仍需确认的权限敏感假设

参考资料

• references/guardrails.md：使用 Box MCP 工具时必须遵守的安全和范围约束
• references/content-workflows.md：文件和文件夹——上传、下载、预览、文件夹树、移动、元数据；MCP 工具和 CLI/REST 模式
• references/collaboration.md：共享和访问——协作者角色、共享链接、外部共享规则；MCP 工具和 CLI/REST 模式
• references/mcp-search.md：查找内容——通过 MCP 按关键字、文件夹名称和元数据搜索
• references/ai-and-retrieval.md：Box AI 和检索——问答、提取、Agent、内容理解优先顺序；MCP 工具和 CLI 命令
• references/mcp-hubs.md：Box Hubs——通过 MCP 创建、管理项目以及进行 Hub 级别的问答
• references/mcp-doc-gen.md：Box Doc Gen——通过 MCP 注册模板并生成文档
• references/bulk-operations.md：大规模整理文件——批量移动、创建文件夹层级、串行执行和速率限制处理
• references/auth-and-setup.md：选择身份验证路径、设置 MCP 服务、选择 SDK 或 REST、检查现有代码库，以及当前 Box 文档锚点
• references/box-cli.md：CLI 优先的本地身份验证、冒烟测试命令和安全验证模式
• references/rest-calls.md：直接调用 REST 的回退模式、身份验证设置和安全请求模板
• references/webhooks-and-events.md：Webhook 设置、事件 Feed 使用、幂等性和验证
• references/workflows.md：任务含糊时使用的快速工作流路由指南
• references/troubleshooting.md：常见故障模式和调试检查清单