【免费下载链接】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工具节点的完整能力它如何把 Microsoft Word 文档操作暴露为 Agent 可调用的工具在用户 OneDrive 中以下载—内存编辑—回传的会话无关模式完成文本读取、建文、追加、查找替换与 PDF 导出并通过If-Match前置条件保障并发编辑的安全性。读完本文你将掌握该节点的工具清单、接线方式、认证配置、底层实现原理与排查方法可直接在自己的管道中启用 Word 能力。功能定位无持久编辑会话的 .docx 工具节点tool_word是 tool_microsoft_365 工具家族的一员与 Excel、OneDrive、Outlook Mail、Outlook Calendar 共享同一套 Microsoft Graph 凭据与请求机制。它面向tool_microsoft_365/word/doc.md所描述的三个技术支柱Microsoft Graph drive content API负责与 OneDrive 中的.docx文件做上传/下载交互对应GET .../content、PUT .../content等端点python-docx在内存中对.docx进行段落级编辑读取、追加、查找替换代理用户身份所有操作都作用于acting user的 OneDrive即登录用户的/me或 Entra 应用模式下的/users/{upn}。需要特别强调的设计原则是这里不存在任何持久化的 Word Online 编辑会话。每一次写操作都是完整的读-改-写往返——先下载当前.docx二进制用python-docx在进程内编辑再把整个文件重新上传并用If-Match携带下载时拿到的 eTag 作为前置条件。如果文件在此期间被其他人改过Graph 会返回409/412冲突而不是静默地后写覆盖先写last-writer-wins。这一原则贯穿全部写工具的实现也是本节点与真实 Word 在线编辑器的本质区别——它适合自动化文本加工不是富文本排版工具。Agent 工具一览节点注册了 6 个word_*工具全部由 word/IInstance.py 中的tool_function装饰方法暴露给 Agent工具Graph 调用用途word_read_textGET .../content读取文档正文段落与表格单元格文本按换行符拼接返回word_create_documentPUT /drive/root:/{path}:/content由段落文本列表创建新的.docxword_append_textGET/PUT .../content带If-Match向文档末尾追加段落word_replace_textGET/PUT .../content带If-Match在段落与表格单元格中查找替换文本返回替换次数word_export_pdfGET .../content?formatpdf、PUT .../content服务端转换为 PDF 并上传到源文件旁边word_check_connectionGET /drive scope 报告诊断——连接与 scope 覆盖情况各工具的输入与返回word_read_text必填参数fileOneDrive 路径如Docs/report.docx或 drive item id。返回{text: string}其中正文段落与每个表格单元格的文本按顺序以换行符连接。从源码 IInstance.py 的word_read_text可以看到实现download_docx拿到二进制后交给docx.Document(BytesIO(content))解析收集doc.paragraphs与doc.tables的逐行逐格文本。word_create_document必填参数path与paragraphs字符串数组。它用docx.Document()新建文档并逐个add_paragraph直接 PUT 到目标路径不发送If-Match——因为这是新建或有意覆盖文件不存在需要匹配的历史版本。返回新文件的id、name、webUrl由clean_item裁剪。word_append_text必填file与paragraphs。先download_docx拿到(content, etag)追加段落保存后经upload_docx上传自动附带If-Match: etag。word_replace_text必填file、find、replace。对文档正文与所有表格单元格做字面量区分大小写子串替换返回{replacements: count}。若替换数为 0不会触发上传——避免无操作改写文件导致 eTag/mtime 被刷新对应 test_word.py 的回归测试。word_export_pdf必填file。通过 Graph 服务端格式转换GET {item}/content?formatpdf获取 PDF 字节再上传到源文件同目录命名为源文件名去掉.docx后加.pdf。工具只返回上传后的 PDF 文件元数据不把 PDF 字节回传避免在工具通道里搬运数 MB 内容。word_check_connection无需参数。先探测GET /drive确认连接可用再结合 graph_client.py 的token_scope_report报告已授权 scope 是否覆盖节点配置的访问层级返回connection_ok、access、requiredScopes缺失时给出missingScopes。核心机制读-改-写往返与 If-Match 并发控制这是本节点最值得理解的部分。word/doc.md 明确说明word_append_text和word_replace_text都是 read-modify-write 往返共享同一套底层助手download_docx(auth, base, file)先GET元数据拿 eTag再GET .../content拿二进制返回(bytes, etag)见 word/client.py 的download_docxupload_docx(auth, base, file, blob, etag)PUT .../content当 etag 非空时在extra_headers中携带If-Match见 word/client.py 的upload_docx。etag 为空例如全新文件则省略该头。冲突时Graph 返回409Precondition Failed 相关的冲突语义或412。共享请求层 graph_client.py 的request会把这类状态码转成GraphError错误消息直接点名文件在编辑期间被修改请重新读取后重试——不会自动重试也不会覆盖他人修改。word_create_document不发送If-Match因为它的语义是创建/覆盖而非与历史版本合并。查找替换的格式化边界已知取舍word_replace_text对每个段落只扫描原始文本一次_replace_in_paragraph见 IInstance.py 的实现因此当replace本身包含find时不会被二次匹配、重复计数例如findfoo, replacefoobar段落foo is here只会计数 1 次并得到foobar is here而不会变成foobarbar is here——这是测试 test_replace_where_replacement_contains_find_does_not_double_count_or_corrupt 验证的回归场景匹配跨 run 边界也能命中——即使TODO被 Word 拆成TODO两个 run仍能整体替换见 test_replace_across_a_run_boundary无匹配的段落完全不动run 与格式保持不变有匹配的段落新文本写入第一个 run、其余 run 清空因此多 run 段落的段内格式加粗/斜体边界会在替换时丢失。这是纯文本替换模式的已知、已文档化的取舍并非真正的 Word 编辑会话的替代品。在管道中接线tool_word是一个tool类节点通过control接到 Agentclasstool并配合 Agent 必需的memory节点。原文档给出的接线示例{ id: tool_word_1, provider: tool_word, config: { type: tool_word }, control: [{ classType: tool, from: agent_rocketride_1 }] }Agent 会自动发现word_*工具并按自己的指令调用它们。服务注册描述位于 services.word.jsonnode: python、path: nodes.tool_microsoft_365.word、prefix: word、capabilities: [invoke]tile 会动态显示Word (${parameters.word.access})。五个 Microsoft 365 服务各自独立配置一个服务调高访问层级不会扩大另一个服务的权限。配置详解节点配置字段如下与 services.word.json 的 schema 一致字段必填说明microsoft.authType是serviceEntra 应用客户端凭据流或userOAuth 用户登录microsoft.tenantId/microsoft.clientId/microsoft.clientSecretservice模式必填Entra 应用注册凭据microsoft.userPrincipalNameservice模式必填代理用户的 UPN——应用模式调用目标为/users/{upn}microsoft.userTokenuser模式由使用 Microsoft 登录按钮填充broker 自动刷新word.access否readonly或write默认write。由共享的WORD访问规范解析scope 从不手工填写word.access默认值是write可选readonly仅允许word_read_text与write建文、追加、替换、导出 PDF。readonly层级下所有写工具会在触碰任何文档内容之前于节点侧抛出MicrosoftAccessError——测试 TestReadonlyBlocksWrite 验证了这一点且这些拦截在python-docx未安装时也能运行。配置如何在引擎中生效从 word/IGlobal.py 与共享基类 tool_microsoft_365/IGlobal.py 可以看到生命周期beginGlobal通过depends(...)按需安装 requirements.txt内容仅python-docx一行resolve_microsoft_access(cfg, WORD)依据word.access解析出访问描述符层级与所需 scopesbuild_auth依据authType构建AppOnlyAuthclient credentials或BrokerUserAuthuser OAuthvalidateConfig与check_connection共用token_scope_report判断 scope 覆盖三处检查不会漂移。一个关键工程细节python-docx是在每个工具方法内部惰性导入的而非模块顶层导入——因为依赖在运行时才由requirements.txt安装顶层导入会在依赖未就绪的测试环境中破坏测试收集见 IInstance.py 的模块 docstring。凭据获取与两种认证模式在 Entra 中注册应用在Entra 管理中心entra.microsoft.com→ App registrations注册应用并授予与认证模式匹配的 Graph 权限userOAuth 委托权限授予Files.Readreadonly或Files.ReadWritewriteserviceEntra 应用应用程序权限授予Files.Read.Allreadonly或Files.ReadWrite.Allwrite必须管理员同意application permissions 是租户级的应用无法自行同意。应用模式下的 Word 权限对应关系在 microsoft-oauth.md 中有完整表格Wordreadonly→Files.Read.AllWordwrite→Files.ReadWrite.All。user模式下的委托 scope 在 services.word.json 中已固定登录按钮按所选层级请求最小权限。完整设置流程被五个 Microsoft 365 工具服务共享excel、word、onedrive、outlook mail、outlook calendar请参见 Microsoft 账号登录指南其中包含 broker 登录流程、宿主与 webview 契约、scope 与访问层级对照表以及应用权限的收窄方案Exchange ApplicationAccessPolicy、Sites.Selected 模式。安全边界绝不把凭据提交进版本库使用节点配置加密存储或 Entra 应用密钥轮换凭据构造会校验 token 端点只能指向 Microsoft 自身的login.microsoftonline.combroker 刷新 URL 必须是https且 host 属于受信 broker 列表oauth2.rocketride.ai/oauth.rocketride.ai自托管可用RR_OAUTH_BROKER_URL追加——篡改的存储 token 无法把凭据重定向到攻击者主机见 graph_client.py 的resolve_refresh_url/resolve_token_uri请求层只允许向graph.microsoft.com发送 Bearer token且跨主机重定向时会剥离Authorization头Graph 的/content下载会 302 到预授权的 CDN 下载主机带外部 bearer token 会被拒绝——这是 graph_client.py 的_AuthStrippingRedirectHandler处理的真实线上问题。底层实现地址解析、请求重试与响应裁剪文件地址解析word/client.py 的it()决定一个file参数是路径还是 item id形如Docs/report.docx含/按drive/root:/{path}:形式处理每个路径段做百分号编码未编码的空格会触发http.client.InvalidURL未编码的#会截断路径导致寻址到错误文件若值匹配[A-Za-z0-9!]{15,}形态的 item id 或root别名则按drive/items/{id}处理。请求重试策略共享的 graph_client.pyrequest提供429限流与500/502/503/504指数退避重试最多 4 次延迟 1s/2s/4s尊重Retry-After头并钳制在 0–30 秒5xx 与网络错误仅对幂等方法GET/HEAD/PUT/DELETE重试——重放的 POST 可能造成消息/事件/drive item 被创建两次401/403快速失败并给出可读的授权修复提示如AADSTS65001表示需要同意409/412快速失败并提示重新读取后重试。响应裁剪每个工具返回的都是clean_item裁剪过的形状id、name、webUrl、eTag、lastModifiedDateTime而非原始 Graph JSON——避免把 Graph 的庞大负载原样塞回工具通道。测试验证行为如何被保障Word 服务有一组聚焦的测试nodes/test/tool_microsoft_365/test_word.py 只 mock HTTP 层graph_client._urlopen真实调用IInstance方法可验证readonly 拦截写操作4 个写工具在 readonly 层级全部抛MicrosoftAccessError无需 python-docx 也能跑建文合法性PUT 请求的 Content-Type 正确、目标 URL 为/drive/root:/Docs/new.docx:/content、上传字节能被 python-docx 读回且段落一致、新文件不带If-Match替换计数与上传行为段落与表格单元格同时计数、零匹配不上传、替换文本包含查找文本不重复计数、跨 run 边界可替换、单段落多匹配全部计数追加与 eTagPUT 请求带If-Match: xyz追加段落位于文档末尾冲突语义412 响应被转成GraphError消息含conflict测试test_append_text_conflict_surfaces_as_graph_error精确复现了并发冲突路径。这些测试印证了本文前述的所有行为承诺是理解节点边界的最佳入口。排查指南与已知限制scope/403 错误调用word_check_connection若缺失 scopeuser模式重连 Microsoft 账号service模式授予/同意 Entra 应用权限word.access为 readonly 但调用了写工具会抛MicrosoftAccessError将word.access提升为write409/412 冲突文件在下载后被他人修改先调用word_read_text获取最新内容再重试编辑工具不会自动重试word_replace_text返回 0确认查找文本完全一致——find是字面量、区分大小写的子串匹配不是正则word_export_pdf依赖 Graph 服务端格式转换超大或特殊文档可能转换更慢或在上游失败无持久编辑会话替换会丢失多 run 段落的段内格式边界这是设计使然复杂排版请回退到真实 Word 客户端。综上tool_word是 RocketRide 中以最小权限、会话无关方式让 Agent 读写 OneDrive.docx的可靠入口六个工具覆盖读、建、增、改、导出与诊断全流程If-Match前置条件 共享 Graph 请求层限流退避、跨主机剥离认证头、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点击查看免费下载相关推荐RocketRide tool_word 节点详解用 Microsoft Graph 与 python-docx 为 Agent 打造 OneDrive docx 读写工具RocketRide tool_word 节点详解用 Microsoft Graph 与 python docx 为 Agent 打造 OneDrive do如何将 Sourcetrail 接入 Sublime Text用 Package Control 安装插件并发送光标位置如何将 Sourcetrail 接入 Sublime Text用 Package Control 安装插件并发送光标位置 Sourcetrail 通过本地 TRocketRide 服务端 OneDrive 工具节点基于 Microsoft Graph drive API 的 Agent 文件操作能力全解析RocketRide 服务端 OneDrive 工具节点基于 Microsoft Graph drive API 的 Agent 文件操作能力全解析 本篇技术上一篇Rufus免费启动盘制作工具5分钟搞定Windows安装的终极指南下一篇终极指南如何用DZNEmptyDataSet优雅处理iOS应用中的空数据状态创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
