企业官网建设流程全解析

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 接口。它把五个"无 lane（no-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诊断。

Excel（14 个工具）

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）作为新文件内容，不克隆任何现有文件或模板。

OneDrive（19 个工具）

上传与删除的细节值得注意：onedrive_upload对大于 4 MB 的文件走 Graph 可恢复上传会话，按 Graph 推荐的分块大小每次 PUT 5 MiB（见 onedrive/client.py 的 upload 实现）；onedrive_copy在 Graph 侧异步执行，工具在"复制请求被接受"即返回，而非复制完成时。

Outlook Calendar（12 个工具）

Outlook Mail（18 个工具）

Word（6 个工具）

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，默认service：

• service（应用认证，默认）：Entra 应用使用 client-credentials（客户端凭据）流，配置microsoft.tenantId/microsoft.clientId/microsoft.clientSecret，以microsoft.userPrincipalName指定的用户身份行动——app-only 调用以/users/{upn}为寻址前缀。应用（service）权限总是需要管理员同意。
• user（委托认证）：通过 RocketRide broker 的 OAuth：microsoft.oAuthButton登录后填充microsoft.userToken，broker 自动刷新该 token。寻址前缀为/me。

从源码看，寻址切换由 graph_client.py 的user_base()完成：authType == 'user'返回/me；否则要求userPrincipalName非空并返回/users/{upn}。build_auth()（graph_client.py）根据auth_type选择BrokerUserAuth（broker 签发的用户 token）或AppOnlyAuth（client-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.py：AccessSpec声明"层级 → Graph scopes"映射、默认层级与生效的安全门；MicrosoftAccess提供require_write()（只读节点调用写操作时抛MicrosoftAccessError）与require_flag()（未开启的破坏性门控操作抛MicrosoftAccessError）。

Excel（默认write）

Excel 的readonly在节点侧直接拒绝变更类工具。两个层级都申请同一个委托Files.ReadWritescope——Graph 的 workbook API 不接受更窄的 scope，且官方文档记录 application-only token 不受支持，所以用户 OAuth 是文档化的认证路径，尽管service认证也可配置。Excel 没有破坏性门控 flag。

OneDrive（默认write）

Outlook Calendar（默认write）

日历没有破坏性门控 flag——与 Outlook Mail 的硬删除 flag 不同，删除事件只需write层级。

Outlook Mail（默认modify）

Word（默认write）

Word 没有破坏性门控 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追加），否则抛ValueError（resolve_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_auth（IGlobal.py 在配置期就发出缺 scope 的 warning），三处判断共用同一函数，不可能漂移。其中：

• 空 grant 是 fail-open（老 token 可能没有 scope 字段，缺证据不阻塞校验）；
• 覆盖判断走 nodes/core/microsoft_access.py 的_scope_satisfied()，理解 Graph 的超集语义：<Family>.ReadWrite超集<Family>.Read，<scope>.All超集同名 scope，<Family>.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/4s；429对所有方法重试（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：_AuthStrippingRedirectHandler（graph_client.py）在 302 跳转到其他主机（如 OneDrive CDN 下载域）时剥掉Authorization头——这些主机拒绝携带外来 bearer token 的请求（在word_read_text实测发现）；同主机跳转保留；
• 绝对 URL 白名单：调用方提供的 deltaLink/nextLink 等绝对地址必须是https且主机为graph.microsoft.com，bearer token 绝不发往陌生主机；
• 二进制返回：binary=True时返回原始字节（下载内容），否则解析 JSON（空体返回{}）。

各服务使用要点与排错

Excel

• 无会话调用：每个调用都是无状态的——不打开也不关闭持久化 workbook session（workbook-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确认名称。

OneDrive

• onedrive_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 Calendar

• outlook_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-only（client-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 Mail

• outlook_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值不会重复计数（例如 find=foo、replace=foobar不会把新写入的foobar再匹配一次）；零匹配段落完全不动；至少一个匹配的段落把新文本写进第一个 run、其余 run 清空——第一个 run 的格式决定整段合并文本的格式。
• word_replace_text返回 0 时跳过上传——无操作不会 bump 文件的 eTag/mtime。
• word_export_pdf依赖 Graph 服务端格式转换（?format=pdf）；超大或罕见文档可能转换更慢或在上游失败。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）。
• 服务 schema：services.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.py（Graph 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 覆盖，再按本文的安全门说明选择最窄的访问层级。