box-automation

通过 Rube MCP 自动化 Box

通过 Composio 的 Box 工具包自动执行 Box 操作，包括上传和下载文件、搜索内容、管理文件夹、协作、查询元数据以及请求签名。

先决条件

• 必须已连接 Rube MCP（RUBE_SEARCH_TOOLS 可用）
• 通过工具包为 box 的 RUBE_MANAGE_CONNECTIONS 建立有效的 Box 连接
• 始终先调用 RUBE_SEARCH_TOOLS，以获取当前工具架构

设置

使用现有的已批准 Rube 连接。仅设置端点并不能对 Box 进行身份验证；请在请求的范围内使用受支持的主机身份验证流程。

1. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 可用
2. 使用工具包 box 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请按照返回的身份验证链接完成 Box OAuth
4. 确认连接状态显示为 ACTIVE，然后再运行任何工作流

请将这些 slug/默认值视为历史示例；操作应以发现的架构为准。执行请求的写入操作前，请核实具体的企业/账户、文件/文件夹/版本、目标位置和共享可见性。协作变更和签名请求可能会通知他人或改变义务；执行这些操作前必须确认其范围。默认避免使用公开链接，妥善保护下载 URL，并在重试前核查结果不确定的变更。

核心工作流

1. 上传和下载文件

适用场景：用户想要将文件上传到 Box，或从 Box 下载文件

工具调用顺序：

1. BOX_SEARCH_FOR_CONTENT - 如果路径未知，则查找目标文件夹【前置条件】
2. BOX_GET_FOLDER_INFORMATION - 验证文件夹存在并获取 folder_id【前置条件】
3. BOX_LIST_ITEMS_IN_FOLDER - 浏览文件夹内容并查找文件 ID【可选】
4. BOX_UPLOAD_FILE - 将文件上传到指定文件夹【上传时必需】
5. BOX_DOWNLOAD_FILE - 通过 file_id 下载文件【下载时必需】
6. BOX_CREATE_ZIP_DOWNLOAD - 将多个文件/文件夹打包为 zip【可选】

关键参数：

• parent_id：上传目标文件夹的 ID（根文件夹使用 "0"）
• file：用于上传的 FileUploadable 对象，包含 s3key、mimetype 和 name
• file_id：文件的唯一标识符，用于下载
• version：可选的文件版本 ID，用于下载指定版本
• fields：以逗号分隔的属性列表，用于指定要返回的内容

注意事项：

• 上传到已有同名文件的文件夹可能会触发冲突处理；请确定是覆盖还是重命名
• 超过 50MB 的文件应使用分块上传 API（标准工具不提供此功能）
• 上传内容中的 attributes 部分必须位于 file 部分之前，否则会因 metadata_after_file_contents 返回 HTTP 400
• 文件 ID 和文件夹 ID 是可从 Box 网页应用 URL 中提取的数字字符串（例如，https://*.app.box.com/files/123 中的 file_id 为 "123"）

2. 搜索和浏览内容

适用场景：用户希望按名称、内容或元数据查找文件、文件夹或网页链接

工具调用顺序：

1. BOX_SEARCH_FOR_CONTENT - 对文件、文件夹和网页链接进行全文搜索【必需】
2. BOX_LIST_ITEMS_IN_FOLDER - 浏览指定文件夹的内容【可选】
3. BOX_GET_FILE_INFORMATION - 获取指定文件的详细元数据【可选】
4. BOX_GET_FOLDER_INFORMATION - 获取指定文件夹的详细元数据【可选】
5. BOX_QUERY_FILES_FOLDERS_BY_METADATA - 按元数据模板值搜索【可选】
6. BOX_LIST_RECENTLY_ACCESSED_ITEMS - 列出最近访问的项目【可选】

关键参数：

• query：支持运算符的搜索字符串（"" 精确匹配，AND、OR、NOT——仅限大写）
• type：按 "file"、"folder" 或 "web_link" 筛选
• ancestor_folder_ids：将搜索范围限制在指定文件夹（以逗号分隔的 ID）
• file_extensions：按文件类型筛选（以逗号分隔，不带点号）
• content_types：在 "name"、"description"、"file_content"、"comments"、"tags" 中搜索
• created_at_range / updated_at_range：按日期筛选，使用以逗号分隔的 RFC3339 时间戳
• limit：每页结果数（默认值为 30）
• offset：分页偏移量（最大为 10000）
• folder_id：用于 LIST_ITEMS_IN_FOLDER（根目录使用 "0"）

注意事项：

• offset 大于 10000 的查询会被拒绝，并返回 HTTP 400
• BOX_SEARCH_FOR_CONTENT 必须提供 query 或 mdfilters 参数
• 配置错误的筛选条件可能会悄然遗漏预期项目；请先使用小型测试查询进行验证
• 布尔运算符（AND、OR、NOT）必须使用大写
• BOX_LIST_ITEMS_IN_FOLDER 需要通过 marker 或 offset/usemarker 进行分页；只获取到部分列表的情况很常见
• 标准文件夹先按类型排序（文件夹在文件之前，文件在网页链接之前）

3. 管理文件夹

适用场景：用户希望创建、更新、移动、复制或删除文件夹

工具调用顺序：

1. BOX_GET_FOLDER_INFORMATION - 确认文件夹存在并检查权限【前置条件】
2. BOX_CREATE_FOLDER - 创建新文件夹【创建时必需】
3. BOX_UPDATE_FOLDER - 重命名、移动文件夹或更新其设置【更新时必需】
4. BOX_COPY_FOLDER - 将文件夹复制到新位置【可选】
5. BOX_DELETE_FOLDER - 将文件夹移至回收站【删除时必需】
6. BOX_PERMANENTLY_REMOVE_FOLDER - 永久删除已移至回收站的文件夹【可选】

关键参数：

• name：文件夹名称（不能包含 /、\、末尾空格或 ./..）
• parent__id：父文件夹 ID（根目录使用 "0"）
• folder_id：操作目标文件夹的 ID
• parent.id：通过 BOX_UPDATE_FOLDER 移动文件夹时的目标文件夹 ID
• recursive：设置为 true 以删除非空文件夹
• shared_link：用于为文件夹创建共享链接的对象，包含 access、password、permissions
• description、tags：可选元数据字段

注意事项：

• BOX_DELETE_FOLDER 默认会将文件夹移至回收站；如需永久删除，请使用 BOX_PERMANENTLY_REMOVE_FOLDER
• 删除非空文件夹时需要设置 recursive: true
• 根文件夹（ID "0"）无法复制或删除
• 文件夹名称不能包含 /、\、不可打印的 ASCII 字符或末尾空格
• 移动文件夹时，需要通过 BOX_UPDATE_FOLDER 设置 parent.id

4. 共享文件和管理协作

适用场景：用户希望共享文件、管理访问权限或处理协作事项

工具调用顺序：

1. BOX_GET_FILE_INFORMATION - 获取文件详情和当前共享状态【前置条件】
2. BOX_LIST_FILE_COLLABORATIONS - 列出有权访问文件的人员【必需】
3. BOX_UPDATE_COLLABORATION - 更改访问级别，或接受／拒绝邀请【必需】
4. BOX_GET_COLLABORATION - 获取特定协作的详情【可选】
5. BOX_UPDATE_FILE - 创建共享链接、锁定文件或更新权限【可选】
6. BOX_UPDATE_FOLDER - 为文件夹创建共享链接【可选】

关键参数：

• collaboration_id：唯一的协作标识符
• role：访问级别（"editor"、"viewer"、"co-owner"、"owner"、"previewer"、"uploader"、"viewer uploader"、"previewer uploader"）
• status：协作邀请的状态，可以是 "accepted"、"pending" 或 "rejected"
• file_id：要共享或管理的文件
• lock__access：设为 "lock" 以锁定文件
• 检查当前 schema 中的下载权限；"company"／"open" 等访问级别不能与布尔值 can_download 权限互换

注意事项：

• 只有特定角色可以邀请协作者；权限不足会导致授权错误
• can_view_path 会增加受邀者打开“All Files”页面的加载时间；每位用户最多限制为 1000 项
• 协作过期功能需要启用企业管理员设置
• 嵌套参数名称使用双下划线（例如，lock__access、parent__id）

5. Box Sign 请求

适用场景：用户希望管理文档签名请求

工具调用顺序：

1. BOX_LIST_BOX_SIGN_REQUESTS - 列出所有签名请求【必需】
2. BOX_GET_BOX_SIGN_REQUEST_BY_ID - 获取特定签名请求的详情【可选】
3. BOX_CANCEL_BOX_SIGN_REQUEST - 取消待处理的签名请求【可选】

关键参数：

• sign_request_id：签名请求的 UUID
• shared_requests：设为 true，以包含用户作为协作者（而非所有者）的请求
• senders：按发件人邮箱筛选（需要 shared_requests: true）
• limit / marker：分页参数

注意事项：

• 需要为企业账户启用 Box Sign
• 删除签名文件或父文件夹会导致请求不出现在列表中
• 只有创建者可以取消签名请求
• 签名请求状态包括：converting、created、sent、viewed、signed、declined、cancelled、expired、error_converting、error_sending

常见模式

ID 解析

Box 文件／文件夹 ID 是数字字符串；其他实体（包括 Sign 请求）可能使用 UUID。请保留每个返回的标识符：

• 根文件夹：ID 始终为 "0"
• 从 URL 获取文件 ID：https://*.app.box.com/files/123 对应的 file_id 为 "123"
• 从 URL 获取文件夹 ID：https://*.app.box.com/folder/123 对应的 folder_id 为 "123"
• 通过搜索获取 ID：使用 BOX_SEARCH_FOR_CONTENT 查找项目，然后从结果中提取 ID
• ETag：使用文件的 ETag 填入 if_match，以安全地执行并发删除操作

分页

Box 支持两种分页方式：

• 基于偏移量：使用 offset + limit（offset 最大为 10000）
• 基于标记：设置 usemarker: true，并使用响应中的 marker 继续分页（处理大型数据集时优先使用）
• 始终分页至完成，避免结果不完整

嵌套参数

Box 工具使用双下划线表示嵌套对象：

• parent__id：父文件夹引用
• lock__access、lock__expires__at、lock__is__download__prevented：文件锁参数
• permissions__can__download：下载权限

已知注意事项

ID 格式

• 文件／文件夹 ID 是数字字符串；不要将其他实体的 ID 转换为数字
• 根文件夹始终为 "0"
• 可以从 Box Web 应用的 URL 中提取文件和文件夹 ID

速率限制

• Box API 对每个端点都设置了速率限制
• 搜索和列表操作应合理使用分页
• 批量操作应在请求之间加入延迟

参数注意事项

• fields 参数会改变响应结构：指定后，只返回精简表示和请求的字段
• 搜索必须提供 query 或 mdfilters；二者可单独省略，但至少要提供一个
• 将 lock 设置为 null 的 BOX_UPDATE_FILE 操作会移除锁定（仅限原始 API）
• 元数据查询的 from 字段格式：enterprise_{enterprise_id}.templateKey 或 global.templateKey

权限

• 权限不足时，删除操作会失败；务必处理错误响应
• 协作角色决定允许执行哪些操作
• 企业设置可能会限制某些共享选项

快速参考

任务	工具标识	关键参数
搜索内容	BOX_SEARCH_FOR_CONTENT	query、type、ancestor_folder_ids
列出文件夹项目	BOX_LIST_ITEMS_IN_FOLDER	folder_id、limit、marker
获取文件信息	BOX_GET_FILE_INFORMATION	file_id、fields
获取文件夹信息	BOX_GET_FOLDER_INFORMATION	folder_id、fields
上传文件	BOX_UPLOAD_FILE	file、parent_id
下载文件	BOX_DOWNLOAD_FILE	file_id
创建文件夹	BOX_CREATE_FOLDER	name、parent__id
更新文件夹	BOX_UPDATE_FOLDER	folder_id、name、parent
复制文件夹	BOX_COPY_FOLDER	folder_id、parent__id
删除文件夹	BOX_DELETE_FOLDER	folder_id、recursive
永久删除文件夹	BOX_PERMANENTLY_REMOVE_FOLDER	folder_id
更新文件	BOX_UPDATE_FILE	file_id、name、parent__id
删除文件	BOX_DELETE_FILE	file_id、if_match
列出协作	BOX_LIST_FILE_COLLABORATIONS	file_id
更新协作	BOX_UPDATE_COLLABORATION	collaboration_id、role
获取协作信息	BOX_GET_COLLABORATION	collaboration_id
按元数据查询	BOX_QUERY_FILES_FOLDERS_BY_METADATA	from、ancestor_folder_id、query
列出集合	BOX_LIST_ALL_COLLECTIONS	（无）
列出集合项目	BOX_LIST_COLLECTION_ITEMS	collection_id
列出签名请求	BOX_LIST_BOX_SIGN_REQUESTS	limit、marker
获取签名请求	BOX_GET_BOX_SIGN_REQUEST_BY_ID	sign_request_id
取消签名请求	BOX_CANCEL_BOX_SIGN_REQUEST	sign_request_id
最近访问的项目	BOX_LIST_RECENTLY_ACCESSED_ITEMS	（无）
创建 ZIP 下载	BOX_CREATE_ZIP_DOWNLOAD	项目 ID

适用场景

当任务符合概述中描述的工作流或操作时，可使用此技能。

示例

用户请求：

通过 Composio 的 Box 工具包自动执行 Box 操作，包括文件上传/下载、内容搜索、文件夹管理、协作、元数据查询和签名请求。

限制

• 仅当任务明确符合上述范围时才使用此技能。
• 请勿将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。