Microsoft OneDrive

核心用法

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` 巡检 |

核心用法

one-drive 是一个纯文档型 Skill，通过 Maton 平台代理调用 Microsoft Graph API，实现 OneDrive 云存储的完整操作。用户需先在 maton.ai 注册获取 MATON_API_KEY，完成 OAuth 授权后即可执行文件管理操作。

主要功能模块：

• 驱动器管理：获取用户默认 Drive、列举多个 Drive、查看 Drive 元数据
• 文件/文件夹操作：通过 ID 或路径（:/path: 语法）访问项目、创建文件夹、列出子项
• 上传下载：≤4MB 文件单 PUT 上传，大文件自动启用可恢复上传会话；下载通过预认证临时 URL
• 移动复制重命名：PATCH 更新元数据、POST 复制、DELETE 删除
• 共享功能：生成匿名/组织内分享链接、邀请特定用户并设置读写权限
• 高级查询：支持 OData $select、$filter、$orderby、$expand 参数

三种调用方式：
1. CLI：maton one-drive item list、maton api /one-drive/v1.0/...
2. 直接 HTTP：向 https://api.maton.ai/one-drive/v1.0/ 发送请求，Header 携带 Authorization: Bearer $MATON_API_KEY
3. 编程语言：文档提供 Python、JavaScript 完整示例

多账户管理：通过 maton connection create one-drive 创建多个 OAuth 连接，使用 --connection {id} 或 Maton-Connection Header 指定目标账户。

显著优点

1. 零代码集成：纯文档 Skill 无本地依赖，无需安装 Microsoft SDK 或处理复杂的 OAuth 流程，Maton 自动管理 Token 刷新
2. 企业级安全：所有传输 TLS 1.2+ 加密，API Key 通过环境变量注入，无硬编码凭证风险
3. 完整功能覆盖：支持 Microsoft Graph OneDrive API 的全部核心操作，包括大文件分片上传、分享权限精细控制
4. 多语言示例：提供 CLI、Python、JavaScript 三种调用范式，降低接入门槛
5. 来源可信：发布于 clawhub.ai T2 级别平台，MIT-0 开源协议，作者 byungkyu 经过平台认证

潜在缺点与局限性

1. 代理依赖：必须依赖 Maton 服务可用性，无法直连 Microsoft Graph，存在额外的网络跳转和潜在单点故障
2. API Key 成本：需注册 Maton 账户并获取 API Key，可能涉及平台使用费用（文档未明确免费额度）
3. 个人 OneDrive 限制：文档特别说明个人版 OneDrive 中，除 me/drive 外的其他 Drive ID（如 b!... 前缀）可能返回 HTTP 400
4. 大文件上传复杂度：>4MB 文件需手动处理分片上传流程，虽然 CLI 自动处理，但直接 HTTP 调用需自行实现
5. 下载 URL 临时性：@microsoft.graph.downloadUrl 为短期预认证链接，不适合长期存储或分发
6. 无可执行代码：作为 T-MD 纯文档 Skill，实际执行依赖外部 CLI 或用户自行实现的 HTTP 客户端，无内置重试、缓存等机制

适合人群

• 开发者/运维工程师：需要自动化 OneDrive 文件同步、备份、迁移脚本
• AI Agent 构建者：为 Claude、GPT 等 AI 助手扩展云存储能力，实现"保存到网盘"、"读取用户文档"等功能
• 低代码/无代码用户：通过 Maton CLI 快速完成文件管理，无需编写复杂代码
• 企业用户：需要安全、托管的 OAuth 方案，避免自行维护 Microsoft Graph 集成基础设施

常规风险

| 风险类型 | 等级 | 说明 |

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

| **OAuth Token 泄露** | 中 | 连接管理 URL 包含 `session_token`，需在安全环境打开，避免截图或日志泄露 |

| **误操作数据丢失** | 中 | 文档已声明"所有写操作需用户明确批准"，但仍需注意 `delete`、`replace` 等操作的不可逆性 |

| **API Key 泄露** | 低 | 若 `MATON_API_KEY` 环境变量被其他进程读取或意外提交到代码仓库，可能导致账户被滥用 |

| **Rate Limit** | 低 | Microsoft Graph 存在限流（429 错误），高频批量操作需实现退避重试 |

| **依赖服务变更** | 低 | Microsoft Graph API 版本升级或 Maton 平台调整可能影响兼容性 |