RocketRide 的 Excel 工具节点(tool_excel):用 Microsoft Graph 让 Agent 读写 OneDrive 工作簿

原创2026-09-25 16:12:461,992 阅读
文章标签:人工智能AI 应用大模型RAGAI AgentAgent 框架多智能体MCP 服务数据集成数据工程流程编排后端前端计算机视觉语音多模态本地部署开发工具

RocketRide 的 Excel 工具节点(tool_excel):用 Microsoft Graph 让 Agent 读写 OneDrive 工作簿

本篇技术指南围绕 RocketRide 仓库中的 Excel 工具节点(tool_excel)展开,它把微软 Graph 的 workbook API 封装为一组可供 Agent 按需调用的 excel_* 工具函数:列举工作表与表格、读写/清空单元格区域、新增工作表/表格/表格行/图表、全量重算公式以及创建全新工作簿。读完本文,你将掌握该节点的配置字段与两种认证方式、全部 14 个工具的参数与调用语义、其在管道(pipe)中的接线方式,以及源码级的实现原理(URL 寻址、响应清洗、重试退避与安全校验),从而在自己的 Agent 工作流中直接编排 OneDrive 上的 .xlsx 文件。

节点定位:Agent 可调用的工具,而非数据流节点

tool_excel 是 RocketRide 节点体系中典型的 tool 类节点,与普通的数据流节点有本质区别:

  • 没有数据流经 lane:数据不通过管道的输入/输出端口流动,所有操作都以 @tool_function 形式暴露,由 Agent 在推理过程中按需调用。
  • 操作目标永远来自调用参数:文件路径/ID、工作表、区域(range)、表格等操作目标都是工具调用时的参数,绝不放进节点配置。这意味着同一个节点实例可以操作任意 OneDrive 路径下的文件,无需为每个文件单独配置。
  • 无状态(sessionless):每次调用都不打开也不关闭持久化的 workbook session(workbook-session-id)。Graph 完全支持这种无会话调用;代价是相比持有会话,每次调用多一次公式重算的往返,目前节点不做会话管理,等实际用量证明需要时再引入。

从源码看,工具函数的定义集中在 IInstance.py,全部以 @tool_function 装饰器声明,并带有完整的 input_schema JSON Schema,Agent 可据此获得准确的参数提示。

节点配置与字段说明

节点配置在管道文件的节点 config 块中,字段如下(与 services.excel.json 中声明的表单字段一致):

字段 必填 说明
microsoft.authType 是 service(Entra 应用,客户端凭据流)或 user(用户 OAuth)。
microsoft.tenantId / microsoft.clientId / microsoft.clientSecret service 时必填 Entra 应用注册的凭据。
microsoft.userPrincipalName service 时必填 代理操作的目标用户 UPN;应用专用(app-only)调用会定向到 /users/{upn}。
microsoft.oAuthButton / microsoft.userToken user 时 点击登录按钮后由 OAuth broker 填充访问令牌。
excel.access 否 readonly 或 write(默认 write)。由 core/microsoft_access.py 中共享的 EXCEL AccessSpec 解析,作用域(scope)从不手填。

services.excel.json 的 preconfig 给出了默认配置骨架:authType: "service"、access: "write",其余凭据字段为空待填;excel.access 在 UI 中以 Read-only / Read/write 两个枚举选项呈现,默认 write。

访问层级 → 作用域映射

层级 作用域 能力
readonly Files.ReadWrite 仅读取工作表、区域、表格(写操作在节点侧被拒绝)
write Files.ReadWrite 完整读写(默认)

两个层级都请求 Files.ReadWrite,这是 Graph workbook API 文档化的最小权限作用域——包含读操作在内(Files.Read 不被接受),且官方明确列出应用程序权限(application permissions)不受支持。因此 readonly 不是通过缩小作用域实现的,而是在节点侧由 require_write 门控:调用写工具时抛出 MicrosoftAccessError。这一设计在 microsoft_access.py 的 EXCEL AccessSpec 中有明确注释,且 MicrosoftAccess.require_write()(microsoft_access.py)是所有写工具的第一道检查。

与兄弟服务对比可见:WORD、ONEDRIVE 的 readonly 层级使用 Files.Read,而 Excel 因 Graph API 约束只能对两个层级都用 Files.ReadWrite。

Excel 节点没有破坏性操作门控标志(如 OneDrive 的 allowHardDelete),EXCEL AccessSpec 的 flags 为空元组。

认证:两种方式与安全边界

节点的完整认证机制由 graph_client.py 统一实现,Excel、Word、OneDrive、Outlook Mail、Outlook Calendar 五个服务共享同一份凭据与请求机制。

方式一:Entra 应用(authType: service,客户端凭据流)

填写 microsoft.tenantId / microsoft.clientId / microsoft.clientSecret / microsoft.userPrincipalName 四个字段。AppOnlyAuth(graph_client.py)向 https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token 发起 client_credentials 请求,令牌在进程内缓存,直到过期前 60 秒才重新获取。

不过需要特别指出:Excel 节点实际只支持用户 OAuth。Graph 的 workbook API 只接受委派(delegated)的 Files.ReadWrite,且文档声明应用程序令牌不受支持。因此尽管配置层面 service 字段存在,Excel 节点走 app-only 路径时会被 Microsoft 拒绝;用户 OAuth 才是被文档支持的路径(详见 microsoft-oauth.md 中的明确警告)。

方式二:用户 OAuth(authType: user)

点击节点配置面板中的 "Login with Microsoft" 按钮。由于微软同意页无法在 VS Code webview 内渲染,扩展会打开系统浏览器,通过 deep link 回调接收令牌。完整流程、host/webview 消息契约与 saved config 形态见 microsoft-oauth.md。令牌以 userToken(JSON 字符串)形式保存,运行时由 BrokerUserAuth(graph_client.py)负责刷新。

源码中有两个值得注意的安全细节:

  • 刷新 URL 白名单:resolve_refresh_url 只允许 https 且 host 属于内置 broker 白名单(oauth2.rocketride.ai、oauth.rocketride.ai,可用环境变量 RR_OAUTH_BROKER_URL 扩充自托管部署)的刷新地址,防止被篡改的令牌把 refresh_token 发往攻击者主机(graph_client.py)。
  • 令牌端点白名单:resolve_token_uri 只接受 host 为 login.microsoftonline.com 的 https 端点(graph_client.py)。
  • 跨主机重定向剥离 Authorization:Graph 的 /content 下载会 302 到预授权下载主机,_AuthStrippingRedirectHandler 在跨主机跳转时移除 Bearer 头,避免凭据泄露给第三方(graph_client.py)。

建立认证的完整链路

IGlobal.beginGlobal()(IGlobal.py)依次:加载共享 requirements.txt → 用 resolve_microsoft_access(cfg, EXCEL) 解析访问层级 → 用 build_auth 依据 authType 构建 GraphAuth 凭据对象。validateConfig()(IGlobal.py)在配置阶段就警告缺失的凭据或作用域不匹配,避免运行时才报错。

工具全集:14 个 excel_* 工具

下表汇总了全部工具及其对应的 Graph 调用(与 doc.md 的对照表一致,源码实现见 IInstance.py):

工具 Graph 调用 用途 源码位置
excel_list_worksheets GET /workbook/worksheets 列出工作簿的所有工作表(标签页) IInstance.py
excel_read_range GET .../range(address=...) 读取一个 A1 区域的数值与公式 IInstance.py
excel_read_used_range GET .../usedRange 读取工作表的有数据区域 IInstance.py
excel_update_range PATCH .../range(address=...) 将二维数组覆写进一个 A1 区域 IInstance.py
excel_clear_range POST .../range(address=...)/clear 清空一个 A1 区域的内容(保留格式) IInstance.py
excel_add_worksheet POST /workbook/worksheets/add 新增工作表 IInstance.py
excel_list_tables GET /workbook/tables 列出工作簿中的表格 IInstance.py
excel_read_table GET /workbook/tables/{table}/rows 读取表格的全部行 IInstance.py
excel_add_table POST .../tables/add 在 A1 区域上创建表格 IInstance.py
excel_add_table_rows POST /workbook/tables/{table}/rows 向表格追加行 IInstance.py
excel_add_chart POST .../charts/add 基于源区域新增图表 IInstance.py
excel_calculate POST /workbook/application/calculate 工作簿全量重算 IInstance.py
excel_create_workbook PUT /drive/root:/{path}:/content 在 OneDrive 路径创建全新空 .xlsx IInstance.py
excel_check_connection GET /drive + 作用域报告 诊断:连接与作用域覆盖检查 IInstance.py

读取类工具

excel_list_worksheets 参数仅需 file(OneDrive 中的路径,如 Reports/q3.xlsx,或 drive item id)。返回每个工作表的 id、name、position、visibility。

excel_read_range 参数:file、sheet(工作表名或 id)、range(A1 记法,如 A1:C10)。返回 {address, values, formulas, rowCount, columnCount}。

excel_read_used_range 参数:file、sheet。返回最小的包含数据或格式的区域,适合在不知道边界时先探测工作表的填充区域。

excel_list_tables 参数仅需 file。返回每个表格的 id、name、showHeaders、showTotals。

excel_read_table 参数:file、table(表格名或 id,来自 excel_list_tables)。返回 {rows},为行值数组列表(不含表头行)。实现上会跟随 @odata.nextLink 分页游标,确保"每一行"在大表场景下成立(IInstance.py);每行的 values 是单行二维数组 [[a, b, c]],源码会解包为文档承诺的行值数组。

写范围类工具

excel_update_range 参数:file、sheet、range、values(非空二维数组,即"行列表的列表",由 _values_arg 校验,非法输入抛 ValueError)。执行 PATCH 覆写区域,返回更新后的区域。

excel_clear_range 参数:file、sheet、range。发送 POST .../clear,请求体 {'applyTo': 'Contents'} —— 只清内容、保留格式,返回 {cleared: rng}。

结构类写工具

excel_add_worksheet 参数:file、name。返回新工作表属性。

excel_add_table 参数:file、sheet、range(含表头的 A1 区域)、has_headers(可选布尔,默认 true)。请求体 {'address': rng, 'hasHeaders': has_headers},返回新表格属性。

excel_add_table_rows 参数:file、table、rows(非空二维数组)。返回 {added: <追加行数>}。

excel_add_chart 参数:file、sheet、chart_type(Graph 图表类型,如 ColumnClustered、Line、Pie、BarClustered)、source_range(图表取数的 A1 区域)。请求体 {'type': chart_type, 'sourceData': source_range, 'seriesBy': 'Auto'},返回新图表的 id 和 name。

工作簿级写工具

excel_calculate 参数仅需 file。发送 {'calculationType': 'Full'} 执行全量重算——写入公式依赖的数值后,需要拿到最新计算结果时调用。返回 {calculated: True}。

excel_create_workbook 参数为 path(OneDrive 目标路径,如 Reports/new.xlsx),注意该工具的参数名是 path 而非 file。通过 PUT /drive/root:/{path}:/content 上传一个内置的最小空工作簿,覆盖同名已存在文件,返回新文件的 id、name、webUrl。

诊断工具

excel_check_connection 无需参数。执行一次 GET /drive 探测,并对照节点配置的访问层级做作用域覆盖检查。返回 connection_ok、access(当前层级)、requiredScopes,作用域缺失时附带 missingScopes。其实现委托给共享的 _check_connection_impl(IInstance.py),与 validateConfig、build_auth 共用同一个 token_scope_report,保证三处判断不会漂移。

响应清洗:给 Agent 干净的形状

节点不会把原始 Graph JSON 直接抛给 Agent,而是在 client.py 中做白名单字段清洗:

  • clean_range:仅保留 address、values、formulas、rowCount、columnCount;
  • clean_worksheet:仅保留 id、name、position、visibility;
  • clean_table:仅保留 id、name、showHeaders、showTotals。

这保证了工具返回结构的稳定与精简,利于 Agent 理解与后续复用。

源码实现细节:寻址、空工作簿与重试

工作簿 URL 寻址

wb()(client.py)依据 file 参数生成工作簿 URL 前缀:

  • 若值形如 item id(正则 [A-Za-z0-9!]{15,} 全匹配,或 root 别名),走 drive/items/{id}/workbook;
  • 否则按路径处理:drive/root:/{path}:/workbook,其中每个路径段做百分号编码(safe='/' 保留分隔符)。注释明确解释了原因:未编码的空格会抛 http.client.InvalidURL,未编码的 # 会截断路径、静默寻址到错误的 item。

工作表名与区域名通过 _seg() 做安全编码(名称可能含空格)。

最小空工作簿(EMPTY_XLSX)

excel_create_workbook 上传的空白文件不是调用 Graph 的创建接口,而是由 client.py 在导入时用 zipfile 现场构建的 OOXML SpreadsheetML 包:[Content_Types].xml + 包关系 + xl/workbook.xml(含一个名为 "Sheet1" 的 sheet)+ xl/worksheets/sheet1.xml(空 sheetData),无样式、无共享字符串——是 Excel/Graph 能打开的最小合法包。因此该工具不会克隆现有文件或模板,只会生成这个极简工作簿。

请求重试与限流

所有 Graph 请求经由共享的 request()(graph_client.py):

  • 429/5xx 指数退避:4 次尝试,间隔 1s、2s、4s(若响应带数字 Retry-After 则采用,钳制在 0–30s)。限流按 Entra 应用/租户计,重试可缓解;
  • 幂等性约束:429 对任何方法都重试(Graph 未处理该请求);5xx 与瞬时网络错误只对幂等方法(GET/HEAD/PUT/DELETE)重试——因为重放一个已执行的 POST 可能重复发消息或创建事件/drive item;
  • 快速失败:401/403 抛 GraphError 并给出可读的同意(consent)修复提示(如 AADSTS65001 表示需要同意);409/412(如陈旧的 If-Match)提示"文件已变更,请重读后重试";
  • 凭证不发送给非 Graph 主机:绝对 URL(如 nextLink/deltaLink)必须 https 且 host 为 graph.microsoft.com,否则抛 ValueError。

在管道中接线:一个可复用的配置示例

tool_excel 是 tool 类节点,通过 control 接到 Agent 上(Agent 还必须配有自己的 memory 节点),接线形式如下(取自 doc.md):

{
  "id": "tool_excel_1",
  "provider": "tool_excel",
  "config": { "type": "tool_excel" },
  "control": [{ "classType": "tool", "from": "agent_rocketride_1" }]
}

接线后,Agent 会自主发现 excel_* 工具并根据指令调用,无需在管道中显式编排每次操作。

使用示例:读取后追加

Agent 先读取某个工作表的 used range,再向表格追加一行(取自 README.md):

excel_read_used_range  { "file": "Reports/q3.xlsx", "sheet": "Sheet1" }
excel_add_table_rows   { "file": "Reports/q3.xlsx", "table": "Table1",
                          "rows": [["2026-07-10", "Widget", 42]] }

典型的多步编排模式:先用 excel_list_worksheets 确认工作表名 → 用 excel_read_used_range / excel_read_range 读取数据 → 计算或生成结果后,用 excel_update_range / excel_add_table_rows 写回 → 若写入的是公式依赖值,再调 excel_calculate 刷新计算结果。

限制与边界

  • A1 记法与函数寻址:区域/表格操作使用 A1 记法和 Graph 的 workbook function 寻址(range(address='...'));非常大的读取应按区域分页。
  • excel_create_workbook 只生成极简空簿:一个空白 "Sheet1",不克隆现有文件或模板。
  • 限流:按 Entra 应用/租户计,节点对 429/5xx 做指数退避重试。
  • Excel 仅支持用户 OAuth:Graph workbook API 不接受应用程序令牌(参见 microsoft-oauth.md 的警告)。
  • 无破坏性门控:该节点没有额外的破坏性操作开关,readonly 层级即节点侧唯一的写保护。

故障排查

  • Scope / 403 错误:先调 excel_check_connection。若提示缺少作用域:用户认证下断开并重新连接 Microsoft 账号;service 认证下为 Entra 应用授予/同意所需层级的权限。提升访问层级后必须重连账号,因为授予的作用域在同意时即固定(详见 microsoft-oauth.md)。
  • access 为只读时调用写工具:抛 MicrosoftAccessError;将 excel.access 提升为 write 即可。
  • 返回空 values:区域可能位于 used range 之外,或文件路径/工作表名不精确匹配——调用 excel_list_worksheets 确认名称。
  • 刷新失败:若提示 access token 已过期且无刷新路径,需在节点设置中重新连接 Microsoft 账号;自托管部署可通过 RR_OAUTH_BROKER_URL 配置自己的 broker 主机。

延伸阅读

登录后查看全文
rocketride-server