2026 年 10 月 8 日agno 发布 v3.1.1 版本。本次更新围绕知识库页面同步能力进行了集中增强重点覆盖同步过程可观测性、任务取消、失败定位、瞬态网络错误重试以及 Mintlify 风格文档站点的完整同步问题。对于依赖 Knowledge 页面同步构建知识库的场景来说v3.1.1 的变化非常直接同步不再只是等待最终结果而是可以实时获取进度取消操作可以真正传递到正在执行的工作同步失败时可以看到具体失败页面路径和原因链面对大规模文档站点中偶发的网络连接重置问题系统会通过受限的单次超时和退避机制进行重试面对 Mintlify 风格站点过去“所有页面看起来都已索引但同步结果仍被判定为部分完成”的问题也得到了修复。一、版本信息概览版本v3.1.1发布日期2026 年 10 月 8 日本次版本主要包含以下几个方向页面同步支持实时进度反馈与真正取消页面同步报告可以列出失败页面路径日志能够输出失败页面及其完整原因链针对瞬态页面抓取失败增加带退避的重试机制完善 Mintlify 风格文档站点的页面发现与完整同步能力AgentOS 增加 Knowledge 页面同步的生命周期支持工作流函数步骤可以在最终输出前推送进度事件二、页面同步终于支持实时进度不再只能等待最终结果在 v3.1.1 之前页面同步通常以最终结果为核心任务启动后调用方往往需要等待同步结束才能知道整体是否成功、失败数量是多少、是否存在部分完成等情况。v3.1.1 为页面同步增加了实时进度能力。Knowledge 相关接口新增了流式同步能力Knowledge.stream_sync_pages()以及异步版本Knowledge.astream_sync_pages()这两个接口会持续产出带类型的PageSyncProgress进度快照并在同步结束后产出一个最终的SyncReport。也就是说页面同步过程不再只有“开始”和“结束”两个状态。调用方现在可以在同步仍在执行时持续获得同步进展信息并在任务完成后接收最终报告。这种设计使页面同步的状态更加透明。对于页面数量较多的知识库而言同步通常不是一个瞬间完成的操作。实时进度信息能够让调用方知道同步工作仍在进行而不是只能在长时间等待中判断任务是否卡住、是否仍在运行。除了流式接口外同步接口也支持进度观察器。同步方法sync_pages()异步同步方法async_sync_pages()现在均可以接收on_progress观察器。这意味着即使调用方不直接使用流式迭代接口也可以通过进度回调接收页面同步过程中的状态更新。流式模式与观察器模式共同提供了更灵活的接入方式前者适合直接消费同步事件后者适合将进度信息整合进已有的任务逻辑或界面逻辑中。三、取消同步不再只是“停止等待”而是真正到达执行中的工作本次更新中一个非常关键的改进是页面同步取消机制的修复。此前取消同步可能无法真正作用于正在执行的同步任务而更像是调用侧不再继续等待结果。同步内部工作仍可能持续执行直到结束也就是取消请求没有有效传递到实际工作中。v3.1.1 明确修复了这一问题现在取消同步会真正到达正在执行的工作而不是继续将任务执行到最后。这项改进的意义在于页面同步是一个涉及页面发现、抓取、发布、删除以及结果汇总的过程。对于较大规模的站点如果同步任务已经不再需要继续执行能够真正停止执行中的工作就避免了无意义地继续消耗时间和处理资源。从使用体验看取消操作终于具备了与用户预期一致的语义不只是停止接收同步结果不只是停止等待任务完成而是将取消意图传递给实际执行中的同步工作使同步任务能够响应取消而不是一直执行到结尾四、工作流支持中间进度事件最终输出前也能持续反馈v3.1.1 不仅增强了 Knowledge 页面同步本身也将实时进度能力延伸到了工作流执行过程。现在一个工作流函数步骤可以在产生最终StepOutput之前先产出进度对象StepProgress(content...,data...)这意味着工作流步骤不再只能在最后一次性给出结果。在执行过程中步骤可以先向外部推送阶段性进展再在最终完成时输出正式结果。这些进度信息会以原生StepProgressEvent的形式被发出并且会使用现有工作流运行和步骤标识。这点非常重要因为它说明进度事件并不是独立于原有工作流体系之外的一套机制而是直接复用既有的工作流运行和步骤标识进行传递。这样外部系统在消费进度事件时可以将事件准确关联到对应的工作流运行以及对应步骤。在 AgentOS 侧这些事件会通过既有的工作流 REST 和 SSE 路由进行流式传输。也就是说AgentOS 不需要额外引入一套全新的工作流进度传输通道。已有的 REST 与 SSE 工作流流式路由即可承载新的步骤进度事件。客户端方面AgentOSClient.run_workflow_stream()也已经支持解析这些进度事件。从完整链路来看本次能力覆盖了以下环节工作流函数步骤生成StepProgress系统将其发出为原生StepProgressEvent事件保留现有工作流运行和步骤标识AgentOS 通过原有工作流 REST 与 SSE 路由进行流式传输客户端通过AgentOSClient.run_workflow_stream()解析事件这使得页面同步、工作流步骤和 AgentOS 流式调用之间形成了更完整的实时反馈链路。五、同步报告新增失败页面路径不仅知道失败数量还能知道失败的是谁页面同步的结果报告在 v3.1.1 中得到了增强。SyncReport新增了failed_paths该字段用于列出发布或删除失败的站点页面路径。在过去如果同步中发生页面失败调用方可能只能从错误数量或整体同步状态中知道存在异常却难以直接从报告中确认是哪些具体页面发布失败或哪些页面删除失败。新增failed_paths后报告能够直接提供失败页面的站点路径从而提高同步结果的可定位性。需要注意的是failed_paths的行为有明确限制只保留前 20 个失败页面路径这一上限与错误信息的展示上限一致失败总数仍然会保留完整统计因此即使失败页面超过 20 个调用方仍能知道实际失败总数量默认值为()这一默认设计确保已有调用方以及已经存储的历史报告不受影响也就是说v3.1.1 在增加失败页面列表的同时没有破坏既有调用方式和已有报告数据的兼容性。可以将这一设计理解为两个层次的信息failed_paths提供一部分具体失败页面便于快速定位失败数量保留完整值确保整体统计不会因路径展示数量限制而失真对于同步规模较大的站点来说这种设计兼顾了诊断便利性与报告规模控制。六、日志现在会明确指出失败页面并输出原因链除了同步报告增加失败路径日志能力也得到了改进。v3.1.1 中页面同步失败日志会明确记录失败页面以及对应原因链。日志格式示例为Page sync failed for /guides/setup.md并且会附带类似以下结构的原因链SyncFailed: sync_failed - ConnectError: [Errno 104] Connection reset by peer这类信息能够清晰表达三个层次发生失败的是哪一个页面路径同步层面最终被标识为什么类型的失败底层导致失败的具体原因是什么示例中失败页面为/guides/setup.md同步层错误为SyncFailed: sync_failed底层原因则是ConnectError: [Errno 104] Connection reset by peer也就是连接被对端重置。相比只记录笼统的同步失败信息带有页面路径和原因链的日志更适合用于排查问题。调用方可以直接从日志中判断到底是哪一个页面抓取或同步失败以及问题是来自连接、发布、删除还是其他链路。本次更新还专门增加了页面清理路径上的失败警告。当执行裁剪操作时如果页面删除失败日志会输出新的警告信息Page delete failed for …这意味着发布失败和删除失败都能在日志中被明确区分。对于知识库同步而言页面删除同样非常重要。因为同步不仅是把新页面写入知识库也涉及清理已经不再存在的旧页面。如果删除阶段失败而没有明确提示旧页面就可能继续存在于可检索内容中。因此对页面删除失败单独增加警告有助于及时识别清理环节的问题。七、修复瞬态页面抓取失败连接重置不再轻易导致页面同步失败v3.1.1 修复了大规模页面同步中可能出现的瞬态页面抓取失败问题。在大型语料库场景中例如包含 3,913 个页面的文档站点同步过程中每次运行可能随机出现 1 到 2 个页面失败。典型错误是Connection reset by peer即对端重置连接。这类问题的难点在于它并不一定意味着某个页面永久不可访问而可能只是抓取过程中的临时连接异常。如果没有足够合理的重试机制那么少量随机失败就会影响一次同步的完整性。更新说明指出此前存在两个问题。第一个问题是每次尝试会消耗完整的 30 秒抓取截止时间。这会带来一个直接后果当第一次请求已经用掉几乎全部 30 秒时间时后续即使存在重试机制也没有足够的时间空间完成有效重试。第二个问题是重试等待时间过短。当网络连接暂时不稳定时过短的重试间隔可能不足以避开短暂故障导致重复尝试仍然快速失败。v3.1.1 对这两个问题都进行了修复。新的策略包括使用有边界的单次尝试超时使用退避机制进行重试有边界的单次尝试超时意味着每一次抓取尝试不会消耗掉整个总抓取期限从而为后续重试留下时间。退避机制则意味着失败后不会以过短间隔立刻重复请求而是通过更合理的等待节奏进行再次尝试。这一改动的目标十分明确在大规模文档同步中面对偶发性的连接重置等瞬态失败时提高页面最终抓取成功的可能性避免少数随机失败导致整体同步出现缺页或部分完成结果。八、修复 Mintlify 风格站点同步不完整所有页面已索引却仍被判定为部分完成的问题得到解决本次更新的另一个重点是完善 Mintlify 风格文档站点的同步能力。此前大型 Mintlify 风格站点可能出现一种特殊情况所有页面看起来都已经被索引但最终同步结果依然被标记为部分完成。这会导致一个后续问题部分完成的同步结果会跳过裁剪操作。而裁剪操作被跳过后已经从站点中移除的页面就无法被同步清理旧页面会持续保留在可搜索内容中。因此这不是简单的“同步结果状态不够准确”问题而是会直接影响知识库内容的新鲜度。已经被站点删除的内容因为裁剪没有执行仍然可能继续被检索到。v3.1.1 修复了这一问题使 Mintlify 风格站点能够完成更完整的页面同步。本次修复涉及多个页面发现与解析场景。九、页面发现会跳过非页面文件链接在文档站点中链接不一定都指向需要作为知识页面同步的内容。Mintlify 风格站点中可能包含许多指向非页面文件的链接例如配置文件、数据文件、图片、音频、视频、压缩包和字体文件等。如果这些链接被错误识别为页面链接就可能影响页面发现结果进而让同步流程被判定为不完整。v3.1.1 现在会跳过以下类型的非页面文件链接.json .yaml .xml .csv .pdf同时也会跳过以下类别的资源图片音频视频压缩包字体文件这些内容不再被作为普通页面参与页面发现。这一过滤规则的意义在于页面同步应当聚焦于可作为页面内容进行抓取和索引的链接而不是把各种附件、静态资源、数据文件和媒体资源都纳入页面同步范围。如果这些非页面链接被纳入页面发现流程就可能产生无效抓取、页面失败、同步不完整等问题。通过明确跳过它们系统能够更准确地识别真正的站点页面。十、保留 .js 与 .css 页面名不是所有带扩展名的链接都应排除本次更新在过滤非页面文件时也特别保留了.js与.css作为有效页面名称的情况。例如/guides/node.js仍然会被视为有效页面名称而不会因为路径以.js结尾就被误判为静态脚本资源。同样.css也被保留为可能有效的页面名称。这项细节非常关键。因为文档站点的页面路由可以使用看起来像文件扩展名的路径名称。如果系统采取过于简单的扩展名过滤策略就可能错误跳过真实存在的文档页面。因此v3.1.1 的行为不是简单地“过滤所有带扩展名的链接”而是对明确的非页面文件类型进行跳过同时保留.js、.css这类可能属于页面路径的情况。这使页面发现规则在准确性上更加平衡非页面资源不会干扰同步有特殊命名的真实页面不会被错误丢弃十一、处理嵌套索引、MDX 代码块与重定向别名除了非页面链接过滤外v3.1.1 还处理了多个会影响 Mintlify 风格站点页面发现完整性的细节。包括嵌套索引MDX 代码块重定向别名这些情况都可能让页面发现逻辑出现偏差。嵌套索引意味着站点中可能存在层级化的索引结构。如果发现逻辑不能正确处理嵌套关系就可能遗漏位于更深层级中的页面入口。MDX 代码块也是需要特别处理的场景。文档内容中的代码块可能包含看起来像链接、路径或文件名的内容但这些内容并不一定代表站点页面链接。如果不能正确识别 MDX 代码块边界页面发现过程可能把代码示例中的内容误认为真实页面链接。重定向别名则涉及同一内容可能存在多个入口路径的情况。对于站点同步而言重定向和别名处理不当可能影响页面发现、页面状态判断以及同步完整性判定。v3.1.1 对这些情况进行了完善处理使大型 Mintlify 风格站点在页面发现时能够更准确地区分真正的页面链接、代码内容、索引结构以及重定向别名。最终目标是避免同步被错误地判定为部分完成从而确保后续裁剪流程能够在适当条件下执行。十二、站外页面链接依然会阻止裁剪这是设计行为本次修复虽然改善了 Mintlify 风格站点的完整同步但有一项行为保持不变站外页面链接仍然会阻止裁剪。这是有意保留的设计行为。也就是说当页面发现过程中存在指向站点外部页面的链接时系统仍然不会执行裁剪操作。更新内容明确说明这一行为是按设计保留的而不是未修复的问题。结合本次修复可以看到v3.1.1 区分了两类情况对于明确属于非页面文件的链接例如数据文件、图片、媒体、压缩包和字体等系统会跳过避免其影响同步完整性判断对于站外页面链接系统仍然保留阻止裁剪的行为这种区分确保了同步流程不会因为明显不应抓取的资源链接而陷入部分完成状态同时也不会在存在站外页面链接的情况下贸然进行裁剪。十三、为什么“部分完成会跳过裁剪”值得重点关注本次 Mintlify 同步修复中最值得关注的影响是裁剪问题。当同步被判定为部分完成时裁剪会被跳过。裁剪被跳过意味着什么意味着已经从文档站点移除的页面无法在这次同步中被删除。即使站点当前已经没有这些页面它们此前写入知识库的内容仍然可能存在并继续处于可搜索状态。因此如果一个站点每次同步都因为页面发现误判、非页面资源链接、嵌套索引、MDX 代码块或重定向别名等原因而成为部分完成那么历史遗留页面就可能长期无法清理。v3.1.1 通过改进 Mintlify 风格站点的页面发现能力使同步结果能够更准确地达到完整状态。同步能够完整完成后裁剪流程就不会因错误的部分完成状态而被跳过。这对于需要保持知识库内容与文档站点当前状态一致的场景非常重要。十四、v3.1.1 的页面同步能力变化总结从本次更新可以看到agno 的页面同步能力在四个方面得到了增强。第一过程可见。通过stream_sync_pages()、astream_sync_pages()和on_progress页面同步过程可以持续提供PageSyncProgress信息而不是只能等待最终结果。第二取消有效。取消请求现在能够到达执行中的同步工作不再只是调用端停止等待。第三失败可定位。SyncReport.failed_paths能够给出发布或删除失败的页面路径日志能够输出失败页面和完整原因链删除失败也会有独立警告。第四大规模站点同步更稳定、更完整。针对随机连接重置等瞬态抓取失败系统使用有边界的单次超时与退避重试针对 Mintlify 风格站点系统改进非页面链接过滤、嵌套索引处理、MDX 代码块处理和重定向别名处理避免错误部分完成导致裁剪跳过。十五、完整更新点回顾v3.1.1 的更新内容可归纳如下Knowledge.stream_sync_pages()和Knowledge.astream_sync_pages()支持持续产出PageSyncProgress进度快照并在最后产出SyncReportsync_pages()与async_sync_pages()支持on_progress观察器页面同步取消操作能够真正传递到执行中的工作工作流函数步骤可在StepOutput前产出StepProgress(content..., data...)StepProgress会作为原生StepProgressEvent发出进度事件使用现有工作流运行和步骤标识AgentOS 通过现有工作流 REST 与 SSE 路由流式传输这些事件AgentOSClient.run_workflow_stream()可以解析工作流进度事件SyncReport新增failed_pathsfailed_paths用于记录发布或删除失败的站点页面路径failed_paths最多返回前 20 条路径失败数量保持完整统计failed_paths默认值为()现有调用方和已存储报告不会因该字段受到影响日志会输出失败页面路径和原因链页面删除失败时会输出新的删除失败警告针对连接重置等瞬态页面抓取错误增加带退避的重试每次抓取尝试使用有边界的超时避免单次尝试耗尽完整 30 秒期限修复重试时间过短的问题修复大型 Mintlify 风格站点即使页面均已索引仍被判定为部分完成的问题修复后非页面文件链接不会干扰页面发现.json、.yaml、.xml、.csv、.pdf会被跳过图片、音频、视频、压缩包和字体会被跳过.js与.css仍可作为有效页面名称保留支持处理嵌套索引支持处理 MDX 代码块支持处理重定向别名站外页面链接仍然会阻止裁剪此行为保持不变修复错误部分完成导致裁剪跳过、已删除页面持续可搜索的问题十六、结语代码地址github.com/agno-agi/agnoagno v3.1.1 的核心价值在于让 Knowledge 页面同步从“只关注最终结果”进一步升级为“过程可追踪、任务可取消、失败可定位、复杂站点可完整同步”。实时进度、工作流进度事件、AgentOS 流式传输和客户端解析能力使同步过程拥有更完整的可观测链路。失败路径和原因链让问题排查更加直接。针对瞬态连接错误的重试优化提高了大规模页面同步的稳定性。Mintlify 风格站点同步问题的修复则进一步避免了部分完成状态导致旧页面无法裁剪、长期残留在搜索结果中的问题。对于依赖文档站点构建知识库的场景v3.1.1 是一次围绕同步可靠性、同步完整性与同步可观测性的集中更新。