Microsoft OneDrive

核心用法

OneDrive Skill 提供完整的 Microsoft OneDrive API 封装，通过 Maton 平台实现托管式 OAuth 认证，开发者无需处理复杂的 Microsoft Identity 流程即可调用文件管理接口。

认证流程：用户通过 maton login 或网页获取 API key，创建 OneDrive 连接后完成 OAuth 授权，后续请求自动携带有效令牌。

主要功能覆盖：

• 文件操作：上传（支持 4MB 以下直传及大文件分片续传）、下载、重命名、移动、复制、删除
• 文件夹管理：创建、遍历、按路径或 ID 查询
• 高级功能：搜索、最近文件、共享文件查看、生成分享链接、指定用户邀请
• 特殊目录：快速访问文档、照片、音乐等系统文件夹

调用方式：CLI (maton one-drive ...)、直接 HTTP API、Python/JavaScript SDK。

显著优点

1. 零 OAuth 维护负担：Maton 自动处理 token 刷新、过期续期，开发者只需管理单一 API key
2. 完整 Graph API 能力：非简化封装，支持 OData 查询参数（$select、$filter、$orderby 等）、分页、冲突处理策略
3. 多连接管理：支持同一用户绑定多个 OneDrive 账户，通过 --connection 参数切换
4. 大文件友好：自动检测文件大小，>4MB 自动启用可续传上传会话
5. 预签名下载 URL：通过 @microsoft.graph.downloadUrl 获取短期免认证直链，便于 CDN 加速或临时分发

潜在缺点与局限性

• 供应商锁定：依赖 Maton 代理层（api.maton.ai），非直连 Microsoft Graph，平台可用性影响服务稳定性
• 权限粒度受限于 Graph：无法超越 Microsoft 授权的 OAuth scope，企业级复杂权限场景需额外配置
• 个人账户限制：个人版 OneDrive 的某些 drive ID 返回 HTTP 400，需改用 me/drive 端点
• 写操作需确认：规范要求所有创建、更新、删除操作前必须显式用户确认，可能增加交互步骤
• 费率与配额：未公开披露具体 rate limit，429 错误需自行处理退避

适合人群

• 自动化开发者：需要将文件同步、备份、归档流程代码化的 DevOps/数据工程师
• SaaS 集成商：构建需读写客户 OneDrive 的第三方应用，避免自建 OAuth 服务
• 个人高级用户：偏好命令行管理云端文件，替代网页端繁琐操作
• AI/LLM 工作流：为 Agent 提供结构化云存储能力，存储中间产物或最终输出

常规风险

| 风险类型 | 说明 |

|---------|------|

| **Token 泄露** | `MATON_API_KEY` 一旦泄露，攻击者可访问绑定 OneDrive 的全部文件；需严格遵循密钥管理最佳实践 |

| **误操作覆盖** | `conflictBehavior: replace` 或删除操作不可逆，生产环境建议先用 `rename` 策略并备份 |

| **分享链接扩散** | `anonymous`  scope 生成的链接可被任意转发，敏感文件建议使用 `organization` 或特定用户邀请 |

| **OAuth 撤回延迟** | 用户 revoke Microsoft 端授权后，Maton 缓存令牌可能短期仍有效 |

| **依赖单点故障** | Maton 服务中断将导致全部 OneDrive 接口不可用，关键业务需设计降级方案 |

核心用法

OneDrive Skill 是一款纯文档型 API 集成工具，通过 Maton 代理服务（api.maton.ai）对接 Microsoft Graph API，实现 OneDrive 文件的完整生命周期管理。用户需先获取 Maton API Key 并设置 MATON_API_KEY 环境变量，随后通过 CLI（maton）或 HTTP 请求调用 API。

主要功能覆盖：

• 驱动器管理：获取用户默认驱动器、列出所有驱动器
• 文件/文件夹操作：按 ID 或路径访问、创建文件夹、上传（支持≤4MB 简单上传和>4MB 断点续传）、下载、重命名/移动、复制、删除
• 特殊文件夹：快速访问文档、照片、音乐等已知文件夹
• 共享功能：生成匿名/组织内部分享链接，邀请特定用户并设置权限
• 搜索与筛选：支持 OData 查询参数（$select、$filter、$orderby等）

认证流程：使用 Maton CLI 登录或手动设置环境变量 → 创建 OneDrive 连接（OAuth 授权）→ 指定连接 ID 执行操作。多账户用户需显式指定 --connection 参数。

显著优点

1. 代理简化：Maton 自动处理 Microsoft Graph 的 OAuth Token 注入，用户仅需管理单一 API Key
2. 多语言示例：提供 CLI、Python、JavaScript、curl 等完整代码示例，降低接入门槛
3. 大文件支持：自动检测文件大小并切换至断点续传模式（>4MB）
4. 路径友好：支持 : 语法的路径寻址（如 /root:/Documents/report.pdf），无需预先获取 item ID
5. 安全提示完善：文档明确标注写操作需用户确认，并说明个人/企业账户差异（b!... 驱动器 ID 限制）

潜在缺点与局限性

1. 供应商锁定：完全依赖 Maton 代理服务（api.maton.ai），若服务不可用则功能中断
2. 企业账户限制：个人 OneDrive 的 drive list 返回的 b!... 前缀 ID 无法直接访问，需使用 me/drive 端点
3. 无离线能力：纯网络依赖，无法本地缓存或离线操作
4. 调试复杂度：curl 需注意 -g 参数禁用 glob，管道至 jq 时环境变量可能不展开
5. 隐私中转：所有文件元数据和内容请求均经过 Maton 服务器，非直接连接 Microsoft

适合人群

• 开发者：需要快速集成 OneDrive 功能的自动化脚本或应用
• DevOps/系统管理员：批量文件同步、备份或迁移场景
• 技术型用户：偏好命令行工具管理个人云存储
• 多账户用户：需要同时管理多个 OneDrive 账户

常规风险

| 风险类别 | 说明 | 缓解措施 |

|---------|------|---------|

| 密钥泄露 | `MATON_API_KEY` 若暴露在日志或代码库中 | 使用环境变量，定期轮换密钥 |

| 误操作删除 | 写操作可能导致数据丢失 | 文档已要求显式确认，建议操作前备份 |

| 中间人攻击 | 依赖 Maton 代理，存在信任链条 | 验证 TLS 证书，关注 Maton 安全公告 |

| 权限过度授权 | OAuth 可能请求超出需求的权限 | 仔细审阅授权页面，仅授予必要范围 |

| 服务中断 | Maton 或 Microsoft Graph API 故障 | 实现重试逻辑，关注状态码 429/5xx |

依赖服务状态：Microsoft Graph API 稳定性、Maton 服务可用性、用户网络连接质量均影响实际体验。