RocketRide 服务端 OneDrive 工具节点:基于 Microsoft Graph drive API 的 Agent 文件操作能力全解析
RocketRide 服务端 OneDrive 工具节点:基于 Microsoft Graph drive API 的 Agent 文件操作能力全解析
本篇技术指南围绕 RocketRide 服务端(rocketride-server)中的 tool_onedrive 工具节点展开,讲解如何通过该节点把 Microsoft OneDrive 的文件与共享能力以 Agent 工具(onedrive_*)的形式暴露给 LLM Agent。读完本文,你将掌握:OneDrive 工具节点的寻址规则(路径与 item id)、17 个 Agent 工具对应的 Graph 调用、service(Entra 应用)与 user(OAuth)两种认证模式的配置方法、访问层级与安全门控参数的作用,以及源码层面的分块上传、重试、凭据校验与故障排查机制。
节点定位:什么是 OneDrive 工具节点
tool_onedrive 是 RocketRide 服务端 tool_microsoft_365 工具族中的一员,与 Excel、Word、Outlook Mail、Outlook Calendar 并列(参见 工具族 README)。它把 Microsoft Graph 的 drive API 封装为 Agent 可调用的工具,操作对象是当前行为者(acting user)的 OneDrive:列出与搜索文件/文件夹、读取元数据、下载与上传内容、创建文件夹、复制/移动/重命名、回收站与还原、以及共享管理(分享链接、权限授予与撤销)。
该节点的官方说明文档位于 onedrive/doc.md,节点元数据与字段定义位于 services.onedrive.json(protocol: tool_onedrive://,classType: ["tool"],node: python,实现路径 nodes.tool_microsoft_365.onedrive)。
从实现结构看,节点由三个 Python 文件组成,职责清晰:
- onedrive/IGlobal.py:全局生命周期状态,继承共享的
MicrosoftToolGlobalBase,声明SERVICE与SPEC_NAME = 'ONEDRIVE',在beginGlobal中解析访问规格并构建 Graph 认证对象; - onedrive/IInstance.py:全部 17 个
@tool_function工具函数的实现,以及分块上传、邀请接收者目录校验等私有辅助方法; - onedrive/client.py:服务绑定(
GraphService档案)、寻址辅助函数(looks_like_item_id/it/parent_ref)、响应清洗函数(clean_item/clean_permission)与分块上传实现。
节点遵循"操作目标永远是调用时参数、绝不是节点配置"的设计原则——文件路径/ id、文件夹、权限 id 都由 Agent 在每次工具调用时传入。
寻址规则:路径还是 item id
OneDrive 工具统一用驱动器相对路径(如 'Reports/q3.pdf')或 drive item id 来定位条目,两者都接受。判别规则由 client.py 的 looks_like_item_id() 与 it() 实现:
- 字面量
root,或 - 长度 15 个字符以上且只由
[A-Za-z0-9!]组成的值(即 Graph item id 的形状,例如01BYE5RZ6QN3ZWBTUFOFD3GSPGOHDJD36K)
被当作 item id 处理;其余任何值——包括裸的根级文件名如 report.pdf——一律被当作驱动器根目录下的路径处理。
it() 的实现细节(client.py)值得注意:路径的每一段会先做百分号编码(safe='/' 保留分隔符),再拼入 root:/{path}: 寻址形式——未编码的空格会触发 http.client.InvalidURL,未编码的 # 会截断路径导致静默寻址到错误条目。item id 则通过 _seg 做单段 URL 转义。首尾分隔符会被去除,因此 ''、'/'、'root' 三者都寻址驱动器根(root://: 不是合法 Graph 路径)。
实战提示:工具调用中如果传入 Docs/a.pdf 这类含 / 的值,它一定是路径;而无 / 的值会被当作 item id 而不是根级文件名——这一点在"条目未找到"的排查中尤其关键(详见后文故障排查)。
Agent 工具一览:17 个工具与对应的 Graph 调用
工具节点不承载数据流(no-lane),Agent 按需调用以下 onedrive_* 函数。下表完整覆盖 doc.md 中的工具清单,并补充了每个工具的关键行为细节:
| 工具 | Graph 调用 | 用途与要点 |
|---|---|---|
onedrive_list_items |
GET /drive/root(:/{folder}:)/children |
列出文件夹内条目(默认驱动器根),返回 id、name、size、webUrl、folder/file 标记、lastModifiedDateTime。 |
onedrive_search |
GET /drive/root/search(q=...) |
按名称/内容搜索文件与文件夹,query 为必填参数。 |
onedrive_get_metadata |
GET /drive/items/{item} |
读取单个条目元数据,额外含父路径。 |
onedrive_download |
GET .../content |
下载内容:≤ 1 MiB 内联返回 {name, content_base64};更大的文件返回 downloadUrl(短期有效、预授权 URL,由调用方直接抓取,避免字节经 Agent 中转)。 |
onedrive_upload |
PUT .../content 或 POST .../createUploadSession |
上传/覆盖文件:≤ 4 MB 单请求 PUT;更大文件走分块可恢复上传会话。需 write 层级。 |
onedrive_create_folder |
POST .../children |
在父文件夹内新建文件夹,同名已存在则失败(conflictBehavior: 'fail')。需 write 层级。 |
onedrive_copy |
POST .../copy |
复制文件或文件夹(Graph 侧异步执行,工具在"复制被接受"时即返回,不代表复制完成),可选 new_name。需 write 层级。 |
onedrive_move |
PATCH /drive/items/{item} |
将条目移动到另一文件夹,parentReference 为请求体。需 write 层级。 |
onedrive_rename |
PATCH /drive/items/{item} |
原地重命名条目。需 write 层级。 |
onedrive_trash |
DELETE /drive/items/{item} |
移入回收站(可恢复的删除方式)。需 write 层级。 |
onedrive_restore |
POST /drive/items/{item}/restore |
还原回收站条目。仅 OneDrive Personal 支持(Graph 限制):service 认证下前置拒绝;工作/学校账号透出 Graph 自身错误。需 write 层级。 |
onedrive_permanently_delete |
POST .../permanentDelete |
永久删除(绕过回收站,不可逆),受 allowHardDelete 门控。需 write 层级。 |
onedrive_create_sharing_link |
POST .../createLink |
创建查看/编辑分享链接,link_type 支持 view(默认)/edit/embed,scope 支持 organization(默认)/anonymous/users;anonymous 需 allowPublicSharing 门控。需 write 层级。 |
onedrive_list_permissions |
GET .../permissions |
列出条目上的共享权限(链接与用户/组授权),只读。 |
onedrive_invite |
POST .../invite |
按邮箱邀请人员;allowPublicSharing 关闭时,每个接收者都须解析为目录中的个人用户(分发列表、无法解析的地址、查询权限错误一律拒绝),任一失败则整个邀请被拒。需 write 层级。 |
onedrive_delete_permission |
DELETE .../permissions/{id} |
撤销条目的某个共享权限。需 write 层级。 |
onedrive_check_connection |
GET /drive + scope 报告 |
诊断工具:验证连接是否可用、已授权 OAuth scopes 是否覆盖配置的访问层级。 |
所有工具的输出都是清洗后的形状(id、name、size、webUrl、folder/file、lastModifiedDateTime、parentReference.path 等,见 client.py 的 clean_item),而不是原始 Graph JSON;权限对象则由 clean_permission 精简为 id、roles、link、grantedToV2、grantedToIdentitiesV2。
接线方式:把 OneDrive 工具挂到 Agent 上
这是一个 tool 类节点:通过 control(classType: "tool")与 Agent 节点(如 agent_rocketride)相连,并连同 Agent 必需的 memory 节点一起使用。配置示例(摘自 doc.md):
{
"id": "tool_onedrive_1",
"provider": "tool_onedrive",
"config": { "type": "tool_onedrive" },
"control": [{ "classType": "tool", "from": "agent_rocketride_1" }]
}
Agent 发现 onedrive_* 工具后,会按其指令在需要时调用这些工具。注意:节点类型/协议在 services.onedrive.json 中声明为 protocol: "tool_onedrive://"、register: "filter",无需数据通道(lanes: {})。
配置参数详解
doc.md 给出的配置字段如下,全部字段类型与默认值可对照 services.onedrive.json 的 fields 定义:
| 字段 | 必填 | 说明 |
|---|---|---|
microsoft.authType |
是 | service(Entra 应用,client credentials)或 user(OAuth)。 |
microsoft.tenantId / microsoft.clientId / microsoft.clientSecret |
service 模式必填 |
Entra 应用注册凭据。 |
microsoft.userPrincipalName |
service 模式必填 |
行为者的 UPN——应用专用调用以 /users/{upn} 为目标。 |
microsoft.userToken |
user 模式 |
由登录按钮填充,broker 自动刷新。 |
onedrive.access |
否 | readonly 或 write(默认)。由共享的 ONEDRIVE 访问规格解析——scopes 从不手工填写。 |
onedrive.allowPublicSharing |
否 | 默认关闭;门控匿名分享链接与对非个人接收者的邀请。 |
onedrive.allowHardDelete |
否 | 默认关闭;门控 onedrive_permanently_delete。 |
认证模式:service 与 user
service(应用专用 / client credentials):使用 Entra 应用注册的tenantId/clientId/clientSecret,以userPrincipalName指定行为者,应用专用调用指向/users/{upn}。应用权限总是需要管理员同意(admin consent)。user(用户 OAuth):通过 RocketRide 的 OAuth broker 登录(节点配置面板的"Login with Microsoft"按钮),登录结果填充microsoft.userToken,broker 负责自动刷新。完整的登录流程与深链机制参见 microsoft-oauth.md。
从 IGlobal.py 可以看到节点生命周期逻辑:beginGlobal 中先解析配置(完整传入 config,使 allowPublicSharing、allowHardDelete 等门控标志能抵达标志解析),随后 build_auth 依据 authType 构建 Graph 认证对象;validateConfig 则校验必填字段并对缺失 scope 的 token 给出警告(缺失时会提示"disconnect and reconnect your Microsoft account")。
访问层级 → Graph scopes
onedrive.access 的可选值在 services.onedrive.json 中定义为 readonly 与 write(默认 write),对应的 Graph 权限按认证模式不同而不同:
| 认证模式 | 层级 | Graph 权限 | 邀请目录查询(allowPublicSharing 关闭时) |
|---|---|---|---|
| User OAuth(delegated) | readonly |
Files.Read |
User.ReadBasic.All(登录时请求;个人账号无法授予) |
| User OAuth(delegated) | write |
Files.ReadWrite |
User.ReadBasic.All |
| Entra 应用(application,需管理员同意) | readonly |
Files.Read.All |
User.Read.All |
| Entra 应用(application,需管理员同意) | write |
Files.ReadWrite.All |
User.Read.All |
引擎通过 missing_scopes(nodes/core/microsoft_access.py)校验 token 已授权权限是否覆盖层级所需 scopes:家族 .ReadWrite(或 .ReadWrite.All)scope 可覆盖同名 .Read scope,.All scope 可覆盖不带 .All 的同名 scope。
安全门控标志
两个"默认关闭、显式开启"的标志是 OneDrive 节点安全设计的核心:
onedrive.allowPublicSharing(默认 false):关闭时,onedrive_create_sharing_link拒绝scope="anonymous"的匿名链接;onedrive_invite会对每个接收者做目录查询(GET /users/{email}),要求解析为个人目录用户——分发列表与无法解析的地址都被拒绝。采用**失败关闭(fail closed)**策略:查询权限错误与"非用户地址"同等对待。若需要无限制邀请,可开启此标志跳过查询。onedrive.allowHardDelete(默认 false):关闭时onedrive_permanently_delete被拒绝;onedrive_trash(可恢复的回收站删除)始终可用。
在 IInstance.py 中可以看到这些门控的落点:onedrive_permanently_delete 调用 self.IGlobal.access.require_flag('allowHardDelete', ...);onedrive_create_sharing_link 在 scope == 'anonymous' 时调用 require_flag('allowPublicSharing', ...);onedrive_invite 在标志关闭时对每个邮箱调用 _require_individual_directory_user。_require_individual_directory_user(IInstance.py)只选取 $select=id(属于 User.ReadBasic.All 属性集,userType 不属于该属性集且会让查询在低权限下 403),404/403/其他任何失败都拒绝邀请并给出可操作的提示(补目录读权限,或开启 allowPublicSharing)。
获取凭据:Entra 应用注册与授权
在 Entra 管理中心(entra.microsoft.com → App registrations)注册应用,按认证模式与层级授予对应的 Graph 权限,然后进行管理员同意:
- User OAuth(delegated):
Files.Read(readonly)或Files.ReadWrite(write);allowPublicSharing关闭时使用onedrive_invite还需要User.ReadBasic.All做目录查询(个人账号不可用)。 - Entra 应用(application,需管理员同意):
Files.Read.All(readonly)或Files.ReadWrite.All(write);allowPublicSharing关闭时的邀请目录查询还需要User.Read.All。
完整的 Entra 应用注册 walkthrough(含分步操作与各服务/层级权限对照表)由所有 Microsoft 365 工具服务(excel、word、onedrive、outlook mail、outlook calendar)共享,见 microsoft-oauth.md 的"App authentication (client credentials)"一节。注意:Excel 是仅用户 OAuth 的例外(Graph workbook API 不接受应用权限),但 OneDrive 的 service 路径不依赖 broker、当下即可用。
安全提示(原文档强调):切勿提交凭据——使用节点配置(加密存储)或 Entra 应用密钥轮换。
源码级纵深:上传、重试与凭据安全
上传的两段式策略与分块实现
onedrive_upload(IInstance.py)先做 base64 校验(b64decode(validate=True)),随后按大小分流,两个阈值定义在 client.py:
SIMPLE_UPLOAD_LIMIT = 4 * 1024 * 1024:≤ 4 MB 时单次PUT /drive/root:/{path}:/content;CHUNK_SIZE = 5 * 1024 * 1024:> 4 MB 时POST .../createUploadSession(请求体含@microsoft.graph.conflictBehavior: 'replace'),然后按 5 MiB 分块 PUT——这是 Graph 官方建议的分块大小(320 KiB 的整数倍)。
分块上传实现 upload_chunk(client.py)有几个值得注意的设计点:
- 会话返回的
uploadUrl是预授权的、位于非 Graph 主机,因此分块 PUT 不能携带 bearer token——实现直接通过 urllib 发送,而不是走会自动附加 token 的graph_client.request(); - 分块 PUT 以
Content-Range保证幂等,因此对瞬时失败(429/5xx 与连接错误)采用与普通请求相同的有界指数退避重试:最多 4 次,间隔 1s、2s、4s(或封顶的数字型Retry-After,上限_MAX_RETRY_AFTER = 30.0); - 它复用
graph_client._urlopen——模块唯一的 HTTP 接缝——测试可以在一处 monkeypatch 所有 Graph 调用(分块与非分块)。
共享请求机制的四个安全边界
所有 Microsoft 365 服务共享 graph_client.py 这一份凭据与请求实现,其中包含多个防御性边界:
- token 端点校验:token_uri 只接受 Microsoft 自己的 Entra ID(Azure AD)主机
login.microsoftonline.com,篡改的 token 无法把凭据重定向到他处; - broker 刷新 URL 校验:只接受
https且主机为可信 broker(oauth2.rocketride.ai/oauth.rocketride.ai),自托管部署可用RR_OAUTH_BROKER_URL环境变量增加自己的 broker 主机;broker 刷新在 HTTP 拒绝、连接错误、畸形响应体、以及 200 但无 access token 的情况下大声失败,并清除过期 expiry 避免每次调用重复刷新; - 重试策略:
429/5xx指数退避重试,其中5xx只对幂等方法(GET/HEAD/PUT/DELETE)重放——重放 POST 可能重复发消息/创建事件或 drive 条目;权限类401/403与其他错误快速失败并返回 Agent 可读信息; - 重定向去认证:
_AuthStrippingRedirectHandler在重定向离开原主机时剥离Authorization头——Graph 对/content下载返回 302 到 OneDrive CDN,这些主机拒绝携带外部 bearer token 的请求(在 word_read_text 上实测发现)。
诊断工具:onedrive_check_connection
onedrive_check_connection 通过共享的 _check_connection_impl(IInstance.py)实现:报告 connection_ok、当前 access 层级、requiredScopes、authType;对 user 模式会解析 token 的已授权 scopes 并对比所需 scopes,缺失时给出 missingScopes;若实时探测调用(GET /drive)失败或 token 数据畸形,connection_ok 翻转为 false 并附错误摘要。scope 诊断(token_scope_report)同时支撑 validateConfig、check_connection 与 build_auth 三处检查,三者不会漂移。
限制与边界(原文档明确说明)
onedrive_copy是异步的:Graph 侧异步执行,工具返回只代表复制请求被接受,不代表复制完成。onedrive_restore仅 OneDrive Personal:Microsoft Graph 不支持工作/学校账号的POST /drive/items/{id}/restore。service(应用专用)认证下工具前置拒绝(代码中先检查self._base() != '/me'即抛错,见 IInstance.py);工作/学校账号的用户 OAuth 则透出 Graph 自身的错误。此类情况请改用 OneDrive 网页版回收站还原。- 速率限制:按 Entra 应用/租户计,节点对
429/5xx指数退避重试(分块上传 PUT 同样重试,因Content-Range幂等)。
故障排查速查
- Scope / 403 错误:调用
onedrive_check_connection;若 scopes 缺失,user 认证下断开并重新连接 Microsoft 账号,service 认证下在 Entra 应用中授予/同意对应层级的权限。 access为 readonly 时写工具被拒:写工具会抛MicrosoftAccessError;把onedrive.access提升到write。- 共享/邀请被拒:匿名链接,以及任何未解析为个人目录用户的接收者邀请(含查询权限错误),需要开启
onedrive.allowPublicSharing;永久删除需要开启onedrive.allowHardDelete。 - 条目未找到:确认调用方意图是路径还是 item id——无
/的值总是被当作 item id,绝不会被当作裸根级文件名。
典型调用示例
以下来自 onedrive/README.md 的示例展示 Agent 如何上传报表再邀请同事共享:
onedrive_upload { "path": "Reports/q3.pdf", "content_base64": "..." }
onedrive_invite { "item": "Reports/q3.pdf", "emails": ["alex@contoso.com"],
"role": "read" }
第一个调用把内容上传到 Reports/q3.pdf(需 write 层级);第二个调用以 read 角色邀请 alex@contoso.com 访问该文件——allowPublicSharing 默认关闭时,alex 必须能在目录中解析为个人用户。
进一步阅读
- 节点官方文档:nodes/src/nodes/tool_microsoft_365/onedrive/doc.md
- 节点详细 README(含访问层级→scope 对照表与限制说明):nodes/src/nodes/tool_microsoft_365/onedrive/README.md
- 工具实现源码:nodes/src/nodes/tool_microsoft_365/onedrive/IInstance.py
- 寻址与分块上传实现:nodes/src/nodes/tool_microsoft_365/onedrive/client.py
- 共享凭据与请求机制:nodes/src/nodes/tool_microsoft_365/graph_client.py
- 节点 schema(字段与默认值):nodes/src/nodes/tool_microsoft_365/services.onedrive.json
- Microsoft 账号登录与 Entra 应用注册 walkthrough:docs/docusaurus/apps/vscode/microsoft-oauth.md
- 五个 Microsoft 365 工具服务总览:nodes/src/nodes/tool_microsoft_365/README.md