企业官网建设流程全解析

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进度快照，并在最后产出SyncReport
• sync_pages()与async_sync_pages()支持on_progress观察器
• 页面同步取消操作能够真正传递到执行中的工作
• 工作流函数步骤可在StepOutput前产出StepProgress(content=..., data=...)
• StepProgress会作为原生StepProgressEvent发出
• 进度事件使用现有工作流运行和步骤标识
• AgentOS 通过现有工作流 REST 与 SSE 路由流式传输这些事件
• AgentOSClient.run_workflow_stream()可以解析工作流进度事件
• SyncReport新增failed_paths
• failed_paths用于记录发布或删除失败的站点页面路径
• failed_paths最多返回前 20 条路径
• 失败数量保持完整统计
• failed_paths默认值为()
• 现有调用方和已存储报告不会因该字段受到影响
• 日志会输出失败页面路径和原因链
• 页面删除失败时会输出新的删除失败警告
• 针对连接重置等瞬态页面抓取错误增加带退避的重试
• 每次抓取尝试使用有边界的超时，避免单次尝试耗尽完整 30 秒期限
• 修复重试时间过短的问题
• 修复大型 Mintlify 风格站点即使页面均已索引仍被判定为部分完成的问题
• 修复后，非页面文件链接不会干扰页面发现
• .json、.yaml、.xml、.csv、.pdf会被跳过
• 图片、音频、视频、压缩包和字体会被跳过
• .js与.css仍可作为有效页面名称保留
• 支持处理嵌套索引
• 支持处理 MDX 代码块
• 支持处理重定向别名
• 站外页面链接仍然会阻止裁剪，此行为保持不变
• 修复错误部分完成导致裁剪跳过、已删除页面持续可搜索的问题

十六、结语

代码地址：github.com/agno-agi/agno

agno v3.1.1 的核心价值，在于让 Knowledge 页面同步从“只关注最终结果”进一步升级为“过程可追踪、任务可取消、失败可定位、复杂站点可完整同步”。

实时进度、工作流进度事件、AgentOS 流式传输和客户端解析能力，使同步过程拥有更完整的可观测链路。失败路径和原因链让问题排查更加直接。针对瞬态连接错误的重试优化，提高了大规模页面同步的稳定性。Mintlify 风格站点同步问题的修复，则进一步避免了部分完成状态导致旧页面无法裁剪、长期残留在搜索结果中的问题。

对于依赖文档站点构建知识库的场景，v3.1.1 是一次围绕同步可靠性、同步完整性与同步可观测性的集中更新。