【免费下载链接】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_word节点nodes/src/nodes/tool_microsoft_365/word/README.md它把 Microsoft Graph drive content API 与python-docx封装成一组 Agent 可调用的工具函数读取文档文本、从段落列表新建.docx、追加文本、查找替换、导出 PDF。读完本文你将掌握该节点的配置方式Entra 应用 / 用户 OAuth 两种认证、六个word_*工具的调用语义以及它基于If-MatcheTag 的并发安全往返机制与单遍文本替换算法可直接在自己的 RocketRide 管道中接线使用。节点定位无 lane 的 Agent 工具节点tool_word是一个典型的tool 节点——数据不经过任何 lane数据流通道流动每个操作都是注册给 Agent 的tool_function由 Agent 按需调用word/IInstance.py 中的装饰器即注册入口。它操作的.docx文件位于“acting user”执行主体用户的 OneDrive 中。两个关键设计约束贯穿全部工具操作目标是调用参数不是节点配置文件路径 / item id、新建文档的目标路径永远由 Agent 在每次调用时传入节点配置中不存任何文件地址IInstance.py。输出是清洗后的形状不是原始 Graph JSON工具只返回id、name、webUrl、文本等字段绝不把原始 docx/PDF 字节塞回工具通道word/client.py 的clean_item实现。核心机制无持久会话的 docx 往返round-trip该节点没有持久的 Word Online 编辑会话。每一次写操作都是完整的“下载—本地编辑—回传”往返GET获取文件元数据拿到当前 eTagGET .../content下载二进制 docx在进程内用python-docx编辑PUT .../content整体回传请求头携带If-Match: eTag。client.py中的两个辅助函数精确实现了这一模式download_docx(auth, base, file) - (bytes, etag)先取元数据拿 eTag再取二进制内容client.pyupload_docx(auth, base, file, blob, etag)携带If-Match回传eTag 为空时例如全新文件省略该头client.py。并发冲突是显式失败而非静默覆盖如果下载与回传之间文件被他人修改Graph 会返回409/412graph_client.request将其包装成GraphError错误信息明确指出冲突提示调用方“re-read and retry”而不是 last-writer-wins 覆盖别人的编辑graph_client.py。冲突后的标准处理是先用word_read_text重新读取再重试编辑。值得注意的细节word_replace_text在零匹配时会跳过上传IInstance.py这样一次无操作替换不会无谓地推进 item 的 eTag / mtime——这是源码层面的一个微妙优化。配置与访问层级Access Tier节点字段字段说明microsoft.authTypeserviceEntra 应用客户端凭据流或user用户 OAuth默认servicemicrosoft.tenantId/microsoft.clientId/microsoft.clientSecretservice认证用的 Entra 应用凭据microsoft.userPrincipalNameservice认证下“acting user”的 UPN应用专用调用以/users/{upn}为目标microsoft.oAuthButton/microsoft.userToken用户 OAuth点击登录以填充访问令牌由 broker 自动刷新word.accessreadonly或write默认由core/microsoft_access.py中共享的WORD规范解析scope 从不手工填写字段模式定义见 services.word.json其预置配置preconfig默认authType: service、access: write。访问层级 → Graph Scopes层级Scope能力readonlyFiles.Read仅读取文档文本writeFiles.ReadWrite完整读写默认WORD规范定义在 nodes/src/nodes/core/microsoft_access.pyscopes{readonly: [Files.Read], write: [Files.ReadWrite]}, defaultwrite。节点的validateConfig、check_connection工具与build_auth三个检查点共用同一个token_scope_report判定保证三处不会漂移graph_client.py。readonly层级的写工具调用会在运行时抛出MicrosoftAccessErrormicrosoft_access.py 的require_write。注意本节点没有破坏性操作的门控开关destructive gate flags——所有写操作都由 Graph 自身的If-Match前置条件守护而非节点侧的安全开关。六个 Agent 工具工具对应 Graph 调用用途word_read_textGET .../content读取文档正文段落与表格单元格文本换行拼接word_create_documentPUT /drive/root:/{path}:/content从段落文本列表新建.docxword_append_textGET/PUT .../contentIf-Match在文档末尾追加段落word_replace_textGET/PUT .../contentIf-Match跨正文段落与表格单元格查找替换返回替换计数word_export_pdfGET .../content?formatpdf、PUT .../content服务端转 PDF上传到源文件旁word_check_connectionGET /drive scope 报告诊断连接与 scope 覆盖情况各工具的实现要点word_read_text下载 docx →docx.Document(BytesIO(content))在内存解析 → 依次收集doc.paragraphs的正文段落再遍历doc.tables中每个单元格的段落文本最后以\n.join(parts)返回{text}IInstance.py。word_create_document用doc.add_paragraph(text)逐段建文档后直接PUT /drive/root:/{path}:/content不带If-Match——新建文件尚无 eTag 可匹配且本义就是创建或有意覆盖文件而非合并旧版本IInstance.py。word_append_text先download_docx取内容与 eTag → 追加段落 →upload_docx带If-Match回传IInstance.py。word_export_pdfGET {item}/content?formatpdf拿服务端转换的 PDF 字节 → 以“源文件名去掉.docx加.pdf”命名上传到源文件所在目录返回的是新 PDF 的元数据而非字节——避免把数 MB 内容塞回工具通道IInstance.py。word_check_connection以GET {base}/drive探测连接并复用共享的 scope 报告逻辑确认已授予的 OAuth scope 覆盖配置的访问层级IInstance.py。文件寻址路径与 item id 的智能区分工具接受两种文件参数OneDrive 路径如Docs/report.docx或 drive item id。it()辅助函数用正则[A-Za-z0-9!]{15,}$判断形如 item id或root别名的走/drive/items/{id}其余按root:/{path}:形式寻址并对路径逐段做百分号编码safe/保留分隔符——未编码的空格会触发http.client.InvalidURL未编码的#会截断路径导致寻址到错误文件client.py。底层共享机制graph_client.pyWord 与 Excel、OneDrive、Outlook Mail、Outlook Calendar 共用同一份 Graph 凭据与请求机制graph_client.py各服务client.py通过functools.partial绑定word 服务在其第 38-41 行声明GraphService(productWord, superset_scopes{Files.ReadWrite.All})凭据安全token 端点仅允许login.microsoftonline.combroker 刷新 URL 仅允许https且 host 在信任名单oauth2.rocketride.ai/oauth.rocketride.ai自托管可用环境变量RR_OAUTH_BROKER_URL追加篡改的存储 token 无法把凭据重定向到第三方主机graph_client.py两种认证实现AppOnlyAuthclient_credentials进程内缓存至过期前 60 秒与BrokerUserAuthbroker 刷新非 200 拒绝、200 无 access_token 视为契约违规、过期前 60 秒刷新graph_client.py重试策略429/5xx指数退避重试退避序列 1s/2s/4s最多 4 次尝试Retry-After被钳制在 0–30s429对所有方法重试5xx仅对幂等方法GET/HEAD/PUT/DELETE重试避免重放 POST 造成重复副作用graph_client.py错误语义401/403快速失败并给出可读的授权修复提示如AADSTS65001表示需要管理员同意409/412快速失败并提示“re-read and retry”graph_client.py。还有一个对 Word 至关重要的实现细节Graph 对/content下载常返回 302 跳转到预授权的下载 CDN 主机_AuthStrippingRedirectHandler会在跨主机跳转时剥离Authorization头——否则外域 CDN 会以 401 拒绝携带陌生 bearer token 的请求graph_client.py注释明确记录该问题“found live on word_read_text”。word_replace_text的单遍替换算法替换发生在两个层面正文段落与表格单元格。_iter_all_paragraphs先产出doc.paragraphs再遍历每个表格的每行每单元格的段落IInstance.py。每个段落的处理由_replace_in_paragraph完成IInstance.py核心原则是单遍扫描、基于原始文本计算original paragraph.text该段落所有 run 文本的拼接只扫描一次替换计数与替换结果都从这个永不改变的原串计算这正是为了避免“先 run 后段落”双遍扫描的缺陷若replace值本身包含find如findfoo、replacefoobar作用于foo is here双遍扫描第一遍会替换成foobar is here第二遍又在新写入的foobar里再找到foo最终错误计数为 2 且文本被破坏成foobarbar is here零匹配的段落完全不动——任何 run 与格式都不受扰动至少一个匹配的段落新文本写入第一个 run该段落其余 run 清空。第一个 run 的格式对整个合并文本生效——多 run 段落一旦命中替换段内的格式边界粗体/斜体跨度等会丢失。这是朴素 read-modify-write 文本替换的已知取舍并非真实 Word 编辑会话的替代品。接线方式这是tool节点通过controlclassType: tool接到 Agent 旁边同时 Agent 需要自己的memory节点{ id: tool_word_1, provider: tool_word, config: { type: tool_word }, control: [{ classType: tool, from: agent_rocketride_1 }] }Agent 会自行发现word_*工具并按指令调用。在数据流层面services.word.json的lanes为空对象确认了该节点纯工具属性。认证设置两种模式与所需 Graph 权限认证方式二选一Entra 应用service填microsoft.tenantId/microsoft.clientId/microsoft.clientSecret/microsoft.userPrincipalName走 client-credentials 流用户 OAuthuser点击登录按钮填充microsoft.userToken由 broker 自动刷新。完整的 Entra 应用 / 授权设置见 docs/docusaurus/apps/vscode/microsoft-oauth.md所有 Microsoft 365 工具服务共用。应用所需 Graph 权限取决于认证模式认证模式层级Graph 权限用户 OAuth委派readonlyFiles.Read用户 OAuth委派writeFiles.ReadWriteEntra 应用application需管理员同意readonlyFiles.Read.AllEntra 应用application需管理员同意writeFiles.ReadWrite.All应用权限application permissions一律需要管理员同意。与 Excel workbook API 不同其 API 不接受 application-only tokenWord 的 drive-item 下载/上传/转换调用支持 app-only 模式因此两种认证模式都被完整支持。service模式下所有 Graph 调用以/users/{userPrincipalName}为目标user_base的实现见 graph_client.pyUPN 即选定凭据作用的数据归属用户。限制与边界并发word_append_text、word_replace_text是往返编辑依赖If-MatcheTag 过期下载期间文件被他人改动会以命名冲突的GraphError形式暴露。工具不会自动重试——先用word_read_text重读再重试编辑。PDF 导出word_export_pdf依赖 Graph 服务端格式转换?formatpdf超大或非常规文档可能转换更久甚至上游转换失败。格式坍缩word_replace_text将匹配段落的文本写入首 run 并清空其余 run段内格式坍缩为首 run 样式——适合纯文本编辑不能替代真实 Word 编辑会话未匹配段落不受影响。限流限流按 Entra 应用 / 租户维度计数节点对429/5xx响应以指数退避重试。端到端示例一个 Agent 创建报告随后查找替换占位符word_create_document { path: Docs/report.docx, paragraphs: [Q3 Report, Status: DRAFT] } word_replace_text { file: Docs/report.docx, find: DRAFT, replace: FINAL }word_create_document在Docs/report.docx生成两段文本的新文档并返回{id, name, webUrl}word_replace_text将DRAFT替换为FINAL带If-Match回传返回{replacements: 1}。若期间文件被他人修改第二次调用会收到 409/412 冲突的GraphError此时先调用word_read_text获取最新内容再重试即可。故障排查速查表Scope / 403 错误调用word_check_connection若 scope 缺失——用户认证下断开并重新连接 Microsoft 账户服务认证下按所需层级授予 / 同意 Entra 应用权限。access为只读写工具抛出MicrosoftAccessError把word.access提升到write。冲突 / 409 / 412 错误文件在下载后发生了变化他人编辑或前一次调用的上传已推进 eTag。调用word_read_text获取当前内容后重试编辑。word_replace_text返回 0确认目标文本精确匹配——find是字面量区分大小写子串匹配不是正则。赞分享【免费下载链接】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点击查看免费下载相关推荐如何将通用 MCP 客户端通过 Streamable HTTP 连接到 MCP Toolbox 的 /mcp 端点如何将通用 MCP 客户端通过 Streamable HTTP 连接到 MCP Toolbox 的 /mcp 端点 如果你的 MCP 客户端Claude DeRocketRide tool_excel 节点基于 Microsoft Graph 的 Excel 工作簿 Agent 工具深度指南RocketRide tool_excel 节点基于 Microsoft Graph 的 Excel 工作簿 Agent 工具深度指南 本篇技术指南围绕 RoSmartDNS 3步本地DNS部署教程让家里所有设备自动访问最快IPSmartDNS 3步本地DNS部署教程让家里所有设备自动访问最快IP 你有没有觉得明明宽带是300兆打开某些网页还是要转好几秒很多时候锅不在带宽而在上一篇NettyRPC 项目使用教程下一篇Vite 8 解析Rolldown 驱动的新一代前端构建工具链如何落地创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考