核心功能与用法
Box Skill 是 Maton 平台提供的 Box API 网关封装，通过托管式 OAuth 认证让用户无需自行维护令牌刷新逻辑，即可调用完整的 Box 云存储能力。核心用法围绕 https://gateway.maton.ai/box/2.0 代理端点展开，所有请求仅需携带 Authorization: Bearer $MATON_API_KEY 头部。
文件管理：支持标准 CRUD 操作，包括创建/更新/删除文件夹（根目录 ID 为 0）、上传文件（直接上传上限 50 MB，分块上传支持至 50 GB）、版本控制与恢复。分块上传需创建 session 后逐片上传并校验 SHA-1 摘要，最后提交 commit。
协作与共享：可生成共享链接（开放/企业内/协作者三级权限）、管理文件夹协作者（editor/viewer/co-owner 等七种角色）、设置密码保护与过期时间。
高级功能：支持全文搜索（带类型/扩展名/祖先文件夹过滤）、事件流监听（用于同步或审计）、收藏夹管理、Webhook 订阅（需企业权限）、以及回收站恢复。
多连接管理：通过 ctrl.maton.ai 控制面板可创建多个 Box OAuth 连接，使用 Maton-Connection 头部指定特定连接，适用于多租户或多企业账号场景。
显著优点
1. 零 OAuth 维护成本：Maton 自动处理 access token 获取与刷新，开发者只需关注业务逻辑
2. 统一网关入口：单端点代理自动路由至 api.box.com 或 upload.box.com，无需区分域名
3. 大文件友好：内置分块上传 SDK 级示例，支持 50 GB 文件断点续传
4. 企业级协作：完整的权限角色体系与共享策略，满足合规要求
5. 多语言示例：提供 JavaScript、Python（含分块上传完整代码）可直接复制使用
局限与注意事项
- 企业权限门槛：用户列表查询、Webhook 创建等功能需 Box 企业管理员授权
- 50 MB 直接上传限制：大文件必须实现分块逻辑，增加集成复杂度
- 速率限制：Box API 存在 429 限流，高频场景需实现退避重试
- 环境变量依赖：
MATON_API_KEY必须在运行时可用，无密钥则完全不可用 - 网关单点：所有流量经过 Maton 网关，若其服务中断将影响可用性
适合人群
- 需要将 Box 文件操作集成到自动化工作流（CI/CD、数据同步、备份脚本）的开发者
- 使用多 Box 账号（如代管客户企业账号）的 SaaS 服务商
- 希望避免 OAuth 2.0 授权码流程维护负担的小团队
常规风险
数据隐私：文件内容流经 Maton 网关，虽文档声称仅代理，但敏感数据需评估第三方信任边界。密钥泄露：MATON_API_KEY 若泄露，攻击者可访问用户全部 Box 连接，需严格保管。权限扩散：open 共享链接一旦外泄难以追溯，建议默认使用 company 或 collaborators 级别。