核心用法
OneDrive Skill 是 Maton 平台提供的 OneDrive API 代理服务，基于 Microsoft Graph 实现托管式 OAuth 认证。用户无需直接处理微软 OAuth 流程，通过 Maton API Key 即可调用完整的 OneDrive 文件管理能力。
主要功能覆盖：
- 文件/文件夹管理：列出、创建、重命名、移动、复制、删除 DriveItem
- 上传下载：支持 4MB 以下单文件上传，大文件自动启用分片续传（resumable upload）
- 路径寻址：通过
:语法（如/root:/Documents/report.pdf）支持直观的路径操作 - 分享协作：创建匿名/组织内分享链接，向指定用户发送邀请并分配读写权限
- 搜索与特殊文件夹：全文搜索、访问文档/照片/音乐等特殊目录，获取最近文件与他人分享文件
调用方式：CLI（maton one-drive 系列命令）、直接 HTTP API、Python/Node.js SDK。所有请求需携带 MATON_API_KEY，多账号场景可通过 Maton-Connection 头部指定连接。
---
显著优点
1. OAuth 托管免维护：微软 Graph OAuth 的 token 刷新、权限范围、过期处理由 Maton 自动代理，用户仅管理单一 API Key
2. RESTful 接口标准化：直接映射 Microsoft Graph 端点，熟悉微软生态的开发者零学习成本迁移
3. 多语言支持完善：提供 CLI、Python、JavaScript 示例，支持 --jq 过滤、--paginate 自动分页等便利功能
4. 大文件上传优化：>4MB 文件自动触发分片上传会话，避免网关超时
5. 细粒度权限控制：分享时可指定 view/edit/embed 类型及 anonymous/organization 范围，符合企业合规需求
---
潜在缺点与局限性
1. 双重依赖风险：服务可用性同时受 Maton 平台与 Microsoft Graph 影响，任一链路故障将导致服务中断
2. 文件大小限制：简单上传硬限 4MB，超大文件需额外实现分片管理逻辑（虽 CLI 自动处理，但原生 API 调用需手动）
3. 个人账号限制：个人版 OneDrive 中，除 me/drive 外，b!... 前缀的其他 drive ID 直接访问会返回 HTTP 400
4. 下载 URL 时效性：@microsoft.graph.downloadUrl 为短期预认证链接，需即时消费，不适合长期存档
5. 地域与合规：数据流经 Maton 代理服务器，对数据驻留有严格要求的场景需评估第三方中间人风险
---
适合人群
- 自动化运维工程师：需批量同步、备份 OneDrive 文件到本地或其他云存储
- SaaS 集成开发者：构建需读写用户 OneDrive 的第三方应用，规避自建 OAuth 服务的复杂度
- 企业 IT 管理员：统一管控团队 OneDrive 访问权限，审计文件分享行为
- 数据管道工程师：将 OneDrive 作为数据源/目的地，集成至 ETL 或 RPA 工作流
---
常规风险
| 风险类别 | 说明 |
|---------|------|
| **密钥泄露** | `MATON_API_KEY` 泄露将导致账户内所有 OneDrive 连接被滥用，需严格保管环境变量 |
| **误操作覆盖** | 重命名/移动/删除操作不可逆，API 未提供回收站恢复接口，生产环境务必加确认交互 |
| **分享链扩散** | 匿名分享链接一旦生成，无法通过 API 追踪实际访问者，敏感文档建议仅用组织内范围 |
| **Rate Limit** | 微软 Graph 返回 429 时需遵守 `Retry-After`，高频批量操作建议加入指数退避 |
| **连接状态漂移** | OAuth 连接可能因用户 revoke 或微软策略变更而失效，需定期调用 `connection list` 巡检 |