用 Microsoft Graph 统一驾驭 Office 全家桶：RocketRide tool_microsoft_365 工具族实战指南

【免费下载链接】rocketride-serverHigh-performance AI pipeline engine with a C core and 50 Python-extensible nodes. Build, debug, and scale LLM workflows with 13 model providers, 8 vector databases, and agent orchestration, all from your IDE. Includes VS Code extension, TypeScript/Python SDKs, and Docker deployment.项目地址https://gitcode.com/gh_mirrors/ro/rocketride-server点击查看免费下载RocketRide 的tool_microsoft_365是一个将 Excel、OneDrive、Outlook Calendar、Outlook Mail、Word 五大 Microsoft 365 服务封装为 Agent 工具的函数族全部基于统一的 Microsoft Graph 认证与请求机制实现。本文以 tool_microsoft_365 的 README 为骨架结合仓库源码完整讲解五个服务的全部工具函数、配置层级、安全门与排错方法读完即可按最小权限原则在 RocketRide 管道中接入真实的 Microsoft 365 数据操作。为什么按服务选工具而不是用一个通用 HTTP 工具Microsoft 365 是微软的云生产力套件把 Word、Excel、Outlook 与 Exchange、SharePoint 打包在一个订阅下承载文档编写、电子表格、邮件、日历与文件存储并通过 Microsoft Graph API 在一套认证与权限模型下暴露全部服务。tool_microsoft_365的定位是按 Agent 需要访问的资源所属服务来选用工具而不是让 Agent 拿通用 HTTP 工具直接打 Graph REST 接口。它把五个无 laneno-lane工具服务——Excel、OneDrive、Outlook Calendar、Outlook Mail、Word——组织在一个父节点下共享 graph_client.py 里的凭据与请求机制每个服务只构建自己的 Graph client并以service_*前缀注册 Agent 工具。三个设计要点贯穿全部服务操作目标永远走工具调用参数文件路径/ID、消息 ID、事件 ID 等都是每次调用的入参绝不放进节点配置节点配置只放认证与权限信息输出是清洗过的形状每个工具返回精简后的字段集合如 Excel 的address/values/formulas/rowCount/columnCount而不是原始 Graph JSON便于 Agent 直接消费按资源选服务需要哪个 Microsoft 365 资源就选对应服务而不是笼统的 HTTP 工具。从源码看每个服务子包excel/、onedrive/、outlook_calendar/、outlook_mail/、word/只保留各自的工具函数与响应清洗器通过functools.partial绑定共享机制参见 excel/client.py 与 word/client.py 中SERVICE、token_scope_report、request的绑定方式父包根目录__init__.py只承载共享的 client 机制与基类。工具函数全景每个服务注册的函数有固定前缀且全部以service_check_connection结尾——它专门检查该服务配置的访问与连接是否可用。每个函数的参数与返回结构都暴露在各自注册的 schema 中Agent 可通过 schema 获知具体参数。写、删与共享类调用可能被配置的访问层级access tier或显式安全门safety flags拒绝连接失败与 Graph API 错误会通过工具调用面传出遇到 scope 或权限错误时调用对应的check_connection诊断。Excel14 个工具函数说明excel_list_worksheets列出一个工作簿的工作表标签页。excel_read_range读取一个 A1 区域的值/公式。excel_read_used_range读取工作表的已使用区域。excel_update_range覆盖写入一个 A1 区域的值。excel_clear_range清空一个 A1 区域的内容。excel_add_worksheet新增一个工作表标签页。excel_list_tables列出一个工作簿的表格。excel_read_table读取表格的每一行。excel_add_table在一个 A1 区域上创建表格。excel_add_table_rows向表格追加行。excel_add_chart添加一个绘制源区域的图表。excel_calculate工作簿全量重算。excel_create_workbook新建空白.xlsx工作簿。excel_check_connection诊断——连接与 scope 覆盖情况。Excel 的操作目标文件路径或 item id通过 excel/client.py 的wb()助手换算成 Graph workbook 寻址形如Reports/q3.xlsx的多段路径按root:/{path}:/workbook形式逐段百分号编码形如[A-Za-z0-9!]{15,}的 token 则按 item id 走/drive/items/{id}/workbook。excel_create_workbook用导入期构建的最小合法 OOXML 包EMPTY_XLSX仅一个空 Sheet1见 excel/client.py作为新文件内容不克隆任何现有文件或模板。OneDrive19 个工具函数说明onedrive_list_items列出一个文件夹的项目默认根目录。onedrive_search按名称/内容搜索文件和文件夹。onedrive_get_metadata读取一个项目的元数据。onedrive_download下载内容≤1 MiB 内联 base64否则返回downloadUrl。onedrive_upload上传/覆盖文件4 MB 分块上传。onedrive_create_folder在父文件夹内创建文件夹。onedrive_copy复制文件或文件夹异步。onedrive_move移动项目到另一个文件夹。onedrive_rename原地重命名项目。onedrive_trash将项目移入回收站。onedrive_restore恢复已回收项目。仅 OneDrive Personal 支持Graph 限制service认证下直接拒绝工作/学校账号收到 Graph 自身的错误。onedrive_permanently_delete永久删除项目受门控。onedrive_create_sharing_link创建查看/编辑共享链接匿名 scope 受门控。onedrive_list_permissions列出一个项目上的共享权限。onedrive_invite按邮箱邀请人员非个人收件人经目录查询受门控。onedrive_delete_permission撤销一个共享权限。onedrive_check_connection诊断——连接与 scope 覆盖情况。上传与删除的细节值得注意onedrive_upload对大于 4 MB 的文件走 Graph 可恢复上传会话按 Graph 推荐的分块大小每次 PUT 5 MiB见 onedrive/client.py 的 upload 实现onedrive_copy在 Graph 侧异步执行工具在复制请求被接受即返回而非复制完成时。Outlook Calendar12 个工具函数说明outlook_calendar_list_events列出一个时间窗口内的事件循环系列展开。outlook_calendar_get_event按 id 获取单个事件。outlook_calendar_create_event创建事件可选邀请与会者write 层级。outlook_calendar_update_event更新事件——只改提供的字段write 层级。outlook_calendar_delete_event删除事件write 层级。outlook_calendar_respond响应会议邀请write 层级。outlook_calendar_find_meeting_times为一组与会者推荐会议时间。outlook_calendar_get_schedule获取邮箱的忙/闲日程信息。outlook_calendar_list_calendars列出邮箱的日历。outlook_calendar_create_calendar新建日历write 层级。outlook_calendar_delta_sync通过调用方提供的 delta link 增量同步日历视图。outlook_calendar_check_connection诊断——连接与 scope 覆盖情况。Outlook Mail18 个工具函数说明outlook_mail_list_messages列出一个文件夹的消息默认收件箱支持搜索或 OData 过滤。outlook_mail_get_message获取一条消息及其完整正文HTML 转为可读文本。outlook_mail_send_message立即发送邮件send/modify 层级。outlook_mail_create_draft创建草稿消息modify 层级。outlook_mail_reply仅回复发件人send/modify 层级。outlook_mail_reply_all回复所有收件人send/modify 层级。outlook_mail_forward转发给新收件人send/modify 层级。outlook_mail_move_message移动消息到另一个文件夹modify 层级。outlook_mail_set_read标记消息已读/未读modify 层级。outlook_mail_set_categories替换消息的分类标签modify 层级。outlook_mail_delete_message软删除——移入 Deleted Itemsmodify 层级。outlook_mail_permanently_delete永久删除modify 层级 allowHardDelete门。outlook_mail_list_folders列出邮箱的邮件文件夹。outlook_mail_create_folder创建邮件文件夹modify 层级。outlook_mail_list_attachments列出消息上的附件元数据。outlook_mail_get_attachment下载附件内容base64。outlook_mail_add_attachment给草稿消息附加文件modify 层级。outlook_mail_check_connection诊断——连接与 scope 覆盖情况。Word6 个工具函数说明word_read_text读取文档的段落与表格单元格文本换行拼接。word_create_document从段落文本列表新建.docx。word_append_text在文档末尾追加段落。word_replace_text跨段落与表格单元格查找/替换文本返回替换次数。word_export_pdf转 PDF 并上传到源文件旁边。word_check_connection诊断——连接与 scope 覆盖情况。Word 的每次写操作都是一个下载 → 用 python-docx 在进程内编辑 → 带If-Match重新上传的往返round-trip由 word/client.py 的download_docx/upload_docx完成下载时先取元数据拿到 eTag再取二进制内容上传时把 eTag 作为If-Match前置条件发回文件被他人改动时 Graph 返回 409/412工具不会静默覆盖详见下文 Word 一节。配置指南认证模式与访问层级配置原则一句话为每个服务选择认证模式以及恰好够用的最窄访问层级。五个服务相互独立配置——把一个服务设成高层级不会扩大另一个服务的权限。Microsoft 认证service与user两种模式每个服务都暴露microsoft.authType默认serviceservice应用认证默认Entra 应用使用 client-credentials客户端凭据流配置microsoft.tenantId/microsoft.clientId/microsoft.clientSecret以microsoft.userPrincipalName指定的用户身份行动——app-only 调用以/users/{upn}为寻址前缀。应用service权限总是需要管理员同意。user委托认证通过 RocketRide broker 的 OAuthmicrosoft.oAuthButton登录后填充microsoft.userTokenbroker 自动刷新该 token。寻址前缀为/me。从源码看寻址切换由 graph_client.py 的user_base()完成authType user返回/me否则要求userPrincipalName非空并返回/users/{upn}。build_auth()graph_client.py根据auth_type选择BrokerUserAuthbroker 签发的用户 token或AppOnlyAuthclient-credentials token进程内缓存到过期前 60 秒。各服务的访问层级与安全门每个服务的 schema 都定义在独立的services.svc.json中与 services.excel.json、services.onedrive.json、services.outlook_calendar.json、services.outlook_mail.json、services.word.json 一一对应。层级解析与门控的单一实现在 nodes/core/microsoft_access.pyAccessSpec声明层级 → Graph scopes映射、默认层级与生效的安全门MicrosoftAccess提供require_write()只读节点调用写操作时抛MicrosoftAccessError与require_flag()未开启的破坏性门控操作抛MicrosoftAccessError。Excel默认write字段类型说明默认excel.accessstring访问层级。readonly只读工作表、区域与表格。write完整读写更新区域、增删工作表/表格/图表、创建工作簿。writeExcel 的readonly在节点侧直接拒绝变更类工具。两个层级都申请同一个委托Files.ReadWritescope——Graph 的 workbook API 不接受更窄的 scope且官方文档记录 application-only token 不受支持所以用户 OAuth 是文档化的认证路径尽管service认证也可配置。Excel 没有破坏性门控 flag。OneDrive默认write字段类型说明默认onedrive.accessstring访问层级。readonly只支持列目录、搜索、读元数据与下载。write完整读写上传、建文件夹、复制/移动/重命名、回收/恢复、共享。writeonedrive.allowHardDeleteboolean允许永久删除。默认关关闭时只能用 trash/restore永久删除被拒绝。falseonedrive.allowPublicSharingboolean允许公开/组织级共享。默认关关闭时create_sharing_link拒绝anonymous链接invite只接受能解析为目录中单个用户的收件人通讯组与无法解析的地址均被拒绝。开启后允许公开链接与不受限邀请。falseOutlook Calendar默认write字段类型说明默认outlook_calendar.accessstring访问层级。readonly只允许事件/日历读取、会议时间推荐、忙/闲日程与 delta-sync。write默认完整读写——创建/更新/删除事件、响应邀请、创建日历。write日历没有破坏性门控 flag——与 Outlook Mail 的硬删除 flag 不同删除事件只需write层级。Outlook Mail默认modify字段类型说明默认outlook_mail.accessstring访问层级。readonly只读消息/文件夹/附件可列、搜索、读。sendreadonly 发信、回复、转发。modify默认完整读写——草稿、移动、整理、附件以及开启allowHardDelete时永久删除并包含 send。modifyoutlook_mail.allowHardDeleteboolean允许永久删除。默认关关闭时删除仍会把消息移入 Deleted Items永久删除被拒绝。开启后允许永久删除。falseWord默认write字段类型说明默认word.accessstring访问层级。readonly只能读文档文本。write完整读写创建、追加、替换文本、导出 PDF。writeWord 没有破坏性门控 flag——每次写都是读-改-写往返由 Graph 自身的If-Match前置条件守护而不是节点侧门。注册 Entra 应用在 Entra 管理中心的 App registrations 中注册应用并按上文每个服务的 Configuration 小节授予对应 Graph 权限应用service权限需要管理员同意。App-only 认证client-credentials的权限是应用角色无法用userToken体现check_connection通过一次真实探测调用来验证见下文。认证与请求机制graph_client.py 源码级解析五个服务的认证与请求都收敛到唯一一份共享机制 graph_client.py所有安全相关的凭据与请求守卫都在这一个文件里。理解它就理解了整个工具族的行为边界。凭据构造与 token 端点校验Microsoft token 端点白名单token_uri默认https://login.microsoftonline.com/common/oauth2/v2.0/token任何现存值必须是https且主机为login.microsoftonline.com_MS_TOKEN_HOSTS否则抛ValueError——被篡改的已存 token 不可能把凭据重定向到别处resolve_token_uri。broker 刷新 URL 白名单broker 刷新地址必须满足https 受信 broker 主机内置oauth2.rocketride.ai/oauth.rocketride.ai自托管可经RR_OAUTH_BROKER_URL追加否则抛ValueErrorresolve_refresh_url。凭据解码serviceKey/userToken支持原始字符串或data:base64 数据 URL统一由_decode_blob()解码graph_client.py。broker 刷新fail-loud 契约BrokerUserAuth的刷新契约graph_client.py向 broker POST{refresh_token: ...}期望 200 返回{access_token: ..., expiry_date: 毫秒}。以下情况全部 fail-loud 抛ValueError提示重连 Microsoft 账号HTTP 拒绝401/500 等——报告为 rejected by the broker而不是误报为不可达连接错误、broker 不可达、超时响应体畸形JSON 解析失败200 但没有access_token——契约违规保留陈旧 token 只会继续失败expiry_date非法——在提交新 token之前校验避免新 token 陈旧过期时间的半更新状态。特别地刷新成功后如果缺少expiry_date会清掉旧的过期时间None表示不过期否则新鲜 token 会看起来已过期、每次调用都重复 POST broker。scope 诊断三处检查不会漂移token_scope_report()graph_client.py是 scope 诊断的唯一事实来源解码配置里的userToken返回(granted, covered, missing)。它同时支撑IGlobal.validateConfig、IInstance.check_connection与build_authIGlobal.py 在配置期就发出缺 scope 的 warning三处判断共用同一函数不可能漂移。其中空 grant 是 fail-open老 token 可能没有 scope 字段缺证据不阻塞校验覆盖判断走 nodes/core/microsoft_access.py 的_scope_satisfied()理解 Graph 的超集语义Family.ReadWrite超集Family.Readscope.All超集同名 scopeFamily.ReadWrite.All超集该家族读写 scope但不覆盖Mail.Send这类 action scope。每个服务的check_connection由共享的_check_connection_impl()IInstance.py实现报告connection_ok、accesstier、requiredScopes可选执行一次廉价真实探测调用如 Word 的GET /drive见 word/IInstance.py并输出缺失 scope 列表——这正是 scope/403 排错的入口。请求执行重试、快速失败与跨主机重定向request()graph_client.py统一执行 Graph 请求规则值得单独列出重试策略最多 4 次尝试指数退避 1s/2s/4s429对所有方法重试Graph 未处理该请求可安全重放5xx只对幂等方法GET/HEAD/PUT/DELETE重试——POST 可能在报错前已被应用重放会重复发信或重复建事件/文件Retry-After尊重服务端提供的数值优先但夹到 0~30 秒_MAX_RETRY_AFTER防止 Graph 节流时的大 delta-seconds 把线程钉住数分钟HTTP-date 格式则回退到指数退避快速失败401/403 立即抛GraphError消息点名同意修复AADSTS65001 意味着需要同意409/412陈旧的If-Match立即抛冲突消息提示重读后重试其他 HTTP 错误带上状态码与 Graph 错误细节网络错误与 5xx 同一预算只对幂等方法重试避免 POST 已生效后链路中断造成重复跨主机重定向剥离 Authorization_AuthStrippingRedirectHandlergraph_client.py在 302 跳转到其他主机如 OneDrive CDN 下载域时剥掉Authorization头——这些主机拒绝携带外来 bearer token 的请求在word_read_text实测发现同主机跳转保留绝对 URL 白名单调用方提供的 deltaLink/nextLink 等绝对地址必须是https且主机为graph.microsoft.combearer token 绝不发往陌生主机二进制返回binaryTrue时返回原始字节下载内容否则解析 JSON空体返回{}。各服务使用要点与排错Excel无会话调用每个调用都是无状态的——不打开也不关闭持久化 workbook sessionworkbook-session-id。Graph 完全支持无会话调用代价是相比有会话每次调用多一次重算往返文档注明暂缓引入会话直到用量证明需要。excel_create_workbook写入最小空白工作簿一个空 Sheet1不克隆现有文件或模板。区域/表格操作用 A1 记法与 Graph workbook 函数寻址超大读取应按区域分页。排错scope/403 错误先调excel_check_connection缺 scope 时重连 Microsoft 账号用户认证或授予/同意 Entra 应用权限应用认证。access是只读时写工具抛MicrosoftAccessError把excel.access提到write。空values——区域可能在已用区域之外或文件路径/工作表名不精确匹配调excel_list_worksheets确认名称。OneDriveonedrive_copy在 Graph 侧异步执行工具在复制被接受时即返回。onedrive_upload用可恢复上传会话每 PUT 5 MiB符合 Graph 推荐分块大小。onedrive_restore仅 OneDrive Personal——Graph 不支持工作/学校账号恢复Entra 应用service认证下工具前置拒绝工作/学校用户 OAuth 账号会收到 Graph 自身的错误。建议改用 OneDrive 网页端回收站。排错scope/403 先调onedrive_check_connection。共享/邀请被拒——匿名链接、以及任何解析不到目录中单个用户的收件人含查询权限错误都需要开启onedrive.allowPublicSharing永久删除需要开启onedrive.allowHardDelete。项目找不到——确认调用方意图是路径还是 item id不含/的值一律按 item id 处理绝不当作根目录下的裸文件名。Outlook Calendaroutlook_calendar_create_event/outlook_calendar_update_event的start/end两种写法普通YYYY-MM-DDTHH:MM:SS字符串按 UTC 包装或已成形对象{dateTime, timeZone}。与会者邀请由 Graph 在创建/更新事件时自己发出——write层级门控的是 Graph 调用本身不是单独的发送步骤。outlook_calendar_find_meeting_times在微软侧需要委托登录用户上下文app-onlyclient-credentials认证下可能不受支持。outlook_calendar_delta_sync首次调用传start/end之后把返回的delta_link传回只拉取变更。排错scope/403 先调outlook_calendar_check_connection。access为readonly时所有写工具抛MicrosoftAccessError把outlook_calendar.access提到write。find_meeting_times在 app-only 下失败——该端点需要委托上下文改用用户 OAuth 或换outlook_calendar_get_schedule。Outlook Mailoutlook_mail_list_messages的query参数看起来像 OData 过滤表达式含eq、ne、gt、lt、ge、le、startswith(或contains(时作为$filter透传否则按全文$search词处理。outlook_mail_add_attachment只对草稿有效——先outlook_mail_create_draft。排错scope/403 先调outlook_mail_check_connection。access为readonly时所有写/发工具抛MicrosoftAccessError把outlook_mail.access提到send或modify。access为send但草稿/移动/附件被拒——send层级缺少Mail.ReadWrite把outlook_mail.access提到modify。永久删除被拒——需要开启outlook_mail.allowHardDelete软删除outlook_mail_delete_message移入 Deleted Items在modify层级始终可用。Word并发往返编辑word_append_text、word_replace_text用If-Match下载后被他人改动会以点明冲突的GraphError浮出409/412。工具不自动重试——用word_read_text重读后重试。word_create_document不发If-Match——新文件本无冲突对象。word_replace_text对每个段落的原始、未变更文本恰好扫描一次见 word/IInstance.py 的_replace_in_paragraph含find的replace值不会重复计数例如 findfoo、replacefoobar不会把新写入的foobar再匹配一次零匹配段落完全不动至少一个匹配的段落把新文本写进第一个 run、其余 run 清空——第一个 run 的格式决定整段合并文本的格式。word_replace_text返回 0 时跳过上传——无操作不会 bump 文件的 eTag/mtime。word_export_pdf依赖 Graph 服务端格式转换?formatpdf超大或罕见文档可能转换更慢或在上游失败。PDF 上传到源文件旁同名去.docx加.pdf返回的是 PDF 的元数据而非字节——避免把几 MB 内容塞回工具通道。python-docx在每个工具方法内惰性导入不是模块顶部依赖经 requirements.txt 在beginGlobal的depends()运行时安装惰性导入保证未安装环境下测试收集不崩word/IInstance.py。排错scope/403 先调word_check_connection。access只读——把word.access提到write。冲突/409/412——文件自下载后已变更word_read_text取当前内容后重试。word_replace_text返回 0——确认文本精确一致find是字面大小写敏感子串匹配不是正则。限速五个服务都受每个 Entra 应用/租户的 Graph 限速约束节点对429/5xx响应按指数退避重试具体机制见上文请求执行一节。依赖与源码导航唯一 Python 依赖python-docx见 requirements.txt。服务 schemaservices.excel.json、services.onedrive.json、services.outlook_calendar.json、services.outlook_mail.json、services.word.json均在nodes/src/nodes/tool_microsoft_365/下。共享机制认证与请求在 graph_client.py全局生命周期基类在 IGlobal.py实例基类与check_connection实现在 IInstance.py访问层级解析与门控在 nodes/core/microsoft_access.py。各服务实现excel/、onedrive/、outlook_calendar/、outlook_mail/、word/五个子包各自含client.pyGraph client 绑定与响应清洗、IGlobal.py、IInstance.py、doc.md与 README。值得对照的官方上游资料主题包括Microsoft Graph Excel API 与 workbook range/table 资源、OneDrive DriveItem 与大文件上传会话、共享链接创建、Calendar 与 Event 资源、Find meeting times 与 Get schedule、事件 delta 查询、Mail API 概览与 Message 资源、发信与消息搜索参数、drive content 下载与格式转换以及 python-docx 文档。实际接入前建议先用各服务的check_connection验证 scope 覆盖再按本文的安全门说明选择最窄的访问层级。赞分享【免费下载链接】rocketride-serverHigh-performance AI pipeline engine with a C core and 50 Python-extensible nodes. Build, debug, and scale LLM workflows with 13 model providers, 8 vector databases, and agent orchestration, all from your IDE. Includes VS Code extension, TypeScript/Python SDKs, and Docker deployment.项目地址https://gitcode.com/gh_mirrors/ro/rocketride-server点击查看免费下载相关推荐用 Oumi 全流程驾驭 Qwen3 模型家族SFT 训练、评估与推理配置实战指南用 Oumi 全流程驾驭 Qwen3 模型家族SFT 训练、评估与推理配置实战指南 导读 本指南以 configs/recipes/qwen3/README.人工智能大模型预训练微调强化学习模型推理服务模型评测MCP 服务分布式训练模型量化RocketRide 的 Outlook Calendar 工具节点基于 Microsoft Graph 的智能体日历编排实战指南RocketRide 的 Outlook Calendar 工具节点基于 Microsoft Graph 的智能体日历编排实战指南 本指南围绕 RocketR如何将通用 MCP 客户端通过 Streamable HTTP 连接到 MCP Toolbox 的 /mcp 端点如何将通用 MCP 客户端通过 Streamable HTTP 连接到 MCP Toolbox 的 /mcp 端点 如果你的 MCP 客户端Claude De上一篇immudb多租户架构终极指南如何实现数据库实例的完美隔离方案下一篇CANN算子测试工具op_tester创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考