box

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Box

Overview

概述

Implement Box content workflows in application code. Reuse the repository's existing auth and HTTP or SDK stack whenever possible, identify the acting Box identity before coding, and make the smallest end-to-end path work before layering on sharing, metadata, webhooks, or AI.

在应用代码中实现Box内容工作流。尽可能复用仓库中现有的认证、HTTP或SDK栈，在编码前确定要使用的Box身份，先实现最小的端到端路径，再逐步添加共享、元数据、Webhook或AI功能。

Route The Request

路由请求

If the user needs...	Primary object	Read first	Pair with	Minimal verification
Local verification, manual smoke tests, or quick inspection from the agent without app code changes	Current CLI environment	`references/box-cli.md`	`references/auth-and-setup.md`	`scripts/box_cli_smoke.py check-auth` then a read command
Uploads, folders, listings, downloads, shared links, collaborations, or metadata	File or folder	`references/content-workflows.md`	`references/auth-and-setup.md`	Read-after-write call using the same actor
Organizing, reorganizing, or batch-moving files across folders; bulk metadata tagging; migrating folder structures	File set or folder tree	`references/bulk-operations.md`	`references/auth-and-setup.md` , `references/content-workflows.md` , `references/ai-and-retrieval.md`	Inventory source, verify move count matches plan
Event-driven ingestion, new-file triggers, or webhook debugging	Webhook or events feed	`references/webhooks-and-events.md`	`references/auth-and-setup.md` , `references/troubleshooting.md`	Signature check plus duplicate-delivery test
Search, document retrieval, summarization, extraction, or Box AI	Search result set or file content	`references/ai-and-retrieval.md`	`references/auth-and-setup.md`	Retrieval-quality check before answer formatting
401, 403, 404, 409, 429, missing content, or wrong-actor bugs	Existing request path	`references/troubleshooting.md`	`references/auth-and-setup.md`	Reproduce with the exact actor, object ID, and endpoint
Unsure which workflow applies	Unknown	`references/workflows.md`	`references/auth-and-setup.md`	Choose the smallest Box object/action pair first

如果用户需要...	核心对象	优先阅读	搭配阅读	最小化验证
本地验证、手动冒烟测试，或无需修改应用代码的Agent快速检查	当前CLI环境	`references/box-cli.md`	`references/auth-and-setup.md`	先执行 `scripts/box_cli_smoke.py check-auth` ，再执行读取命令
上传、文件夹、列表、下载、共享链接、协作或元数据操作	文件或文件夹	`references/content-workflows.md`	`references/auth-and-setup.md`	使用同一执行者执行写后读取调用
跨文件夹整理、重组或批量移动文件；批量元数据标记；迁移文件夹结构	文件集或文件夹树	`references/bulk-operations.md`	`references/auth-and-setup.md` , `references/content-workflows.md` , `references/ai-and-retrieval.md`	清点源文件，验证移动数量与计划一致
事件驱动采集、新文件触发或Webhook调试	Webhook或事件流	`references/webhooks-and-events.md`	`references/auth-and-setup.md` , `references/troubleshooting.md`	签名检查加上重复交付测试
搜索、文档检索、摘要、提取或Box AI相关操作	搜索结果集或文件内容	`references/ai-and-retrieval.md`	`references/auth-and-setup.md`	在格式化答案前先检查检索质量
401、403、404、409、429错误，内容缺失或执行者错误问题	现有请求路径	`references/troubleshooting.md`	`references/auth-and-setup.md`	使用完全相同的执行者、对象ID和端点复现问题
不确定适用哪种工作流	未知	`references/workflows.md`	`references/auth-and-setup.md`	先选择最小的Box对象/操作组合

Workflow

工作流

Follow these steps in order when coding against Box.

Inspect the repository for existing Box auth, SDK or HTTP client, env vars, webhook handlers, Box ID persistence, and tests.
Determine the acting identity before choosing endpoints: connected user, enterprise service account, app user, or platform-provided token.
Identify the primary Box object and choose the matching reference from the routing table above.
Confirm whether the task changes access or data exposure. Shared links, collaborations, auth changes, large-scale downloads, and broad AI retrieval all need explicit user confirmation before widening access or scope.
Read only the matching reference files:
- Auth setup, actor selection, SDK vs REST:
```
references/auth-and-setup.md
```
- Box CLI local verification:
```
references/box-cli.md
```
- Workflow router:
```
references/workflows.md
```
- Content operations:
```
references/content-workflows.md
```
- Bulk file organization, batch moves, folder restructuring:
```
references/bulk-operations.md
```
- Webhooks and events:
```
references/webhooks-and-events.md
```
- AI and retrieval:
```
references/ai-and-retrieval.md
```
- Debugging and failure modes:
```
references/troubleshooting.md
```
Implement the smallest end-to-end flow that proves the integration works.
Add a runnable verification step. Prefer the repository's tests first; otherwise use
```
scripts/box_cli_smoke.py
```
when Box CLI is available and authenticated, and
```
scripts/box_rest.py
```
as a fallback.
Summarize the deliverable with auth context, Box IDs, env vars or config, and the exact verification command or test.

编码实现Box集成时，请遵循以下步骤：

检查仓库中现有的Box认证、SDK或HTTP客户端、环境变量、Webhook处理器、Box ID持久化机制以及测试用例。
在选择端点前确定执行者身份：关联用户、企业服务账号、应用用户或平台提供的令牌。
确定核心Box对象，并选择上述路由表中对应的参考文档。
确认任务是否会更改访问权限或数据暴露范围。共享链接、协作、认证变更、大规模下载以及大范围AI检索操作，在扩大访问权限或范围前都需要用户明确确认。
仅阅读对应的参考文件：
- 认证设置、执行者选择、SDK与REST对比：
```
references/auth-and-setup.md
```
- Box CLI本地验证：
```
references/box-cli.md
```
- 工作流路由：
```
references/workflows.md
```
- 内容操作：
```
references/content-workflows.md
```
- 批量文件整理、批量移动、文件夹重组：
```
references/bulk-operations.md
```
- Webhook与事件：
```
references/webhooks-and-events.md
```
- AI与检索：
```
references/ai-and-retrieval.md
```
- 调试与故障排查：
```
references/troubleshooting.md
```
实现能证明集成有效的最小端到端流程。
添加可运行的验证步骤。优先使用仓库中的现有测试；若不可用，当Box CLI已安装并认证时使用
```
scripts/box_cli_smoke.py
```
， fallback方案为
```
scripts/box_rest.py
```
。
总结交付成果，包括认证上下文、Box ID、环境变量或配置，以及具体的验证命令或测试用例。

Guardrails

约束规则

Preserve the existing Box auth model unless the user explicitly asks to change it.
Check the current official Box docs before introducing a new auth path, changing auth scope, or changing Box AI behavior.
Prefer an official Box SDK when the codebase already uses one or the target language has a maintained SDK. Otherwise use direct REST calls with explicit request and response handling.
Keep access tokens, client secrets, private keys, and webhook secrets in env vars or the project's secret manager.
Distinguish file IDs, folder IDs, shared links, metadata template identifiers, and collaboration IDs.
Treat shared links, collaborations, and metadata writes as permission-sensitive changes. Confirm audience, scope, and least privilege before coding or applying them.
Require explicit confirmation before widening external access, switching the acting identity, or retrieving more document content than the task truly needs.
When a task requires understanding document content — classification, extraction, categorization — use Box AI (Q&A, extract) as the first method attempted. Box AI operates server-side and does not require downloading file bodies. Fall back to metadata inspection, previews, or local analysis only if Box AI is unavailable, not authorized, or returns an error on the first attempt.
Pace Box AI calls at least 1–2 seconds apart. For content-based classification of many files, classify a small sample first to validate the prompt and discover whether cheaper signals (filename, extension, metadata) can sort the remaining files without additional AI calls.
Avoid downloading file bodies or routing content through external AI pipelines when Box-native methods (Box AI, search, metadata, previews) can answer the question server-side.
Request only the fields the application actually needs, and persist returned Box IDs instead of reconstructing paths later.
Run Box CLI commands strictly one at a time. The CLI does not support concurrent invocations and parallel calls cause auth conflicts and dropped operations. For bulk work (organizing, batch moves, batch metadata), default to REST over CLI.
Make webhook and event consumers idempotent. Box delivery and retry paths can produce duplicates.
Keep AI retrieval narrow for search and Q&A tasks. Search and filter first, then retrieve only the files needed for the answer. This does not apply to Box AI classification — when classifying documents, Box AI should be tried first per the content-understanding guardrail above.
Do not use
```
box configure:environments:get --current
```
as a routine auth check because it can print sensitive environment details.

除非用户明确要求更改，否则保留现有的Box认证模型。
在引入新的认证路径、更改认证范围或修改Box AI行为前，查阅当前官方Box文档。
若代码库已使用官方Box SDK，或目标语言有维护中的SDK，优先使用官方Box SDK。否则使用直接REST调用，并显式处理请求与响应。
将访问令牌、客户端密钥、私钥和Webhook密钥存储在环境变量或项目的密钥管理器中。
区分文件ID、文件夹ID、共享链接、元数据模板标识符和协作ID。
将共享链接、协作和元数据写入视为权限敏感操作。在编码或应用前确认受众、范围和最小权限原则。
在扩大外部访问权限、切换执行者身份，或检索超出任务实际需求的文档内容前，需要用户明确确认。
当任务需要理解文档内容（分类、提取、归类）时，优先尝试使用Box AI（问答、提取）。Box AI在服务器端运行，无需下载文件主体。仅当Box AI不可用、未授权或首次尝试返回错误时，才 fallback到元数据检查、预览或本地分析。
Box AI调用的间隔至少为1-2秒。对于多文件的基于内容的分类，先对小样本进行分类以验证提示词，并确认是否可以通过更经济的信号（文件名、扩展名、元数据）对剩余文件进行分类，无需额外AI调用。
当Box原生方法（Box AI、搜索、元数据、预览）可在服务器端解决问题时，避免下载文件主体或将内容路由到外部AI管道。
仅请求应用实际需要的字段，持久化返回的Box ID，而非后续重新构建路径。
严格逐个执行Box CLI命令。CLI不支持并发调用，并行调用会导致认证冲突和操作失败。对于批量工作（整理、批量移动、批量元数据操作），默认使用REST而非CLI。
确保Webhook和事件消费者具有幂等性。Box的交付与重试机制可能会产生重复数据。
对于搜索和问答任务，缩小AI检索范围。先进行搜索和过滤，再仅检索回答所需的文件。此规则不适用于Box AI分类——根据内容理解约束规则，分类时应优先尝试Box AI。
不要将
```
box configure:environments:get --current
```
作为常规认证检查，因为它会打印敏感环境信息。

Verification

验证

Prefer the repository's existing tests, scripts, or app flows when they already cover the changed Box behavior.
If no better verification path exists, prefer
```
scripts/box_cli_smoke.py
```
when
```
box
```
is installed and authenticated. Fall back to
```
scripts/box_rest.py
```
with
```
BOX_ACCESS_TOKEN
```
when CLI auth is unavailable or the task specifically needs direct bearer-token verification.

Confirm CLI auth with

box users:get me --json

scripts/box_cli_smoke.py check-auth

Verify mutations with a read-after-write call using the same actor, and record the object ID.
For webhooks, test the minimal happy path, duplicate delivery, and signature failure handling.
For AI flows, test retrieval quality separately from answer formatting.

Example smoke checks. Please note that scripts live under the skill root (skills/box/scripts/):

bash

python3 scripts/box_cli_smoke.py check-auth
python3 scripts/box_cli_smoke.py get-folder 0 --fields id name item_collection
python3 scripts/box_cli_smoke.py list-folder-items 0 --max-items 20
python3 scripts/box_cli_smoke.py search "invoice" --limit 10
python3 scripts/box_rest.py get-item --item-type folder --item-id 0 --fields id name item_collection

若仓库中已有覆盖Box变更行为的测试用例、脚本或应用流程，优先使用它们。
若无更好的验证路径，当
```
box
```
已安装并认证时优先使用
```
scripts/box_cli_smoke.py
```
。若CLI认证不可用，或任务明确需要直接使用Bearer令牌验证，fallback到带
```
BOX_ACCESS_TOKEN
```
的
```
scripts/box_rest.py
```
。

使用

box users:get me --json

或

scripts/box_cli_smoke.py check-auth

确认CLI认证状态。

使用同一执行者执行写后读取调用，验证变更操作，并记录对象ID。
对于Webhook，测试最小化正常路径、重复交付和签名失败处理。
对于AI流程，将检索质量检查与答案格式检查分开进行。

示例冒烟检查。请注意脚本位于技能根目录下（skills/box/scripts/）：

bash

python3 scripts/box_cli_smoke.py check-auth
python3 scripts/box_cli_smoke.py get-folder 0 --fields id name item_collection
python3 scripts/box_cli_smoke.py list-folder-items 0 --max-items 20
python3 scripts/box_cli_smoke.py search "invoice" --limit 10
python3 scripts/box_rest.py get-item --item-type folder --item-id 0 --fields id name item_collection

Deliverable

交付成果

The final answer should include:

Acting auth context used for the change
Box object type and IDs touched
Env vars, secrets, or config expected by the integration
Files or endpoints added or changed
Exact verification command, script, or test path
Any permission-sensitive assumptions that still need confirmation

最终答案应包含：

变更所使用的执行者认证上下文
涉及的Box对象类型和ID
集成所需的环境变量、密钥或配置
添加或修改的文件或端点
具体的验证命令、脚本或测试路径
任何仍需确认的权限敏感假设

References

参考文档

```
references/auth-and-setup.md
```
: auth path selection, SDK vs REST choice, existing-codebase inspection, and current Box doc anchors
```
references/box-cli.md
```
: CLI-first local auth, smoke-test commands, and safe verification patterns
```
references/workflows.md
```
: quick workflow router when the task is ambiguous
```
references/content-workflows.md
```
: uploads, folders, listings, downloads, shared links, collaborations, metadata, and file moves
```
references/bulk-operations.md
```
: organizing files at scale, batch moves, folder hierarchy creation, serial execution, and rate-limit handling
```
references/webhooks-and-events.md
```
: webhook setup, event-feed usage, idempotency, and verification
```
references/ai-and-retrieval.md
```
: search-first retrieval, Box AI usage, and external AI guardrails
```
references/troubleshooting.md
```
: common failure modes and a debugging checklist
```
examples/box-prompts.md
```
: example prompts for realistic use cases

```
references/auth-and-setup.md
```
：认证路径选择、SDK与REST的选择、现有代码库检查以及官方Box文档锚点
```
references/box-cli.md
```
：基于CLI的本地认证、冒烟测试命令以及安全验证模式
```
references/workflows.md
```
：任务不明确时的快速工作流路由
```
references/content-workflows.md
```
：上传、文件夹、列表、下载、共享链接、协作、元数据以及文件移动
```
references/bulk-operations.md
```
：大规模文件整理、批量移动、文件夹层级创建、串行执行以及速率限制处理
```
references/webhooks-and-events.md
```
：Webhook设置、事件流使用、幂等性以及验证
```
references/ai-and-retrieval.md
```
：优先搜索的检索方式、Box AI使用以及外部AI约束规则
```
references/troubleshooting.md
```
：常见故障模式与调试清单
```
examples/box-prompts.md
```
：真实场景的示例提示词