Agno v3.1.1 发布：知识页面同步的进度、取消与失败排查改进

本次变化

根据来源的更新日志，Agno v3.1.1 主要围绕知识页面同步（page sync）做了以下改动：

• 实时进度与取消：Knowledge.stream_sync_pages() / astream_sync_pages() 可产出带类型的 PageSyncProgress 快照，并最终给出一个 SyncReport；sync_pages / async_sync_pages 支持传入 on_progress 观察者。工作流函数步骤可在 StepOutput 之前 yield StepProgress(content=..., data=...)，以原生 StepProgressEvent 形式在既有 workflow 运行/步骤 ID 下发出，AgentOS 通过既有 workflow REST/SSE 路由推送，AgentOSClient.run_workflow_stream() 可解析。取消同步会真正传递到执行中的工作，而不再只是等待其自然结束。
• 失败页面报告：SyncReport.failed_paths 列出发布或删除失败的页面站点路径（与 errors 一样最多前 20 条，failed 保留完整计数，默认值为 () 以不影响现有调用方与已存报告）。日志会给出页面名及原因链，删除路径上也新增失败告警。
• 重试瞬时抓取失败：针对大批量语料（如约 3,913 页的站点）每次运行出现 1–2 个随机页面连接重置的问题，改为每次尝试有界超时并配合退避。
• Mintlify 风格站点同步补全：此前即使所有页面都已索引，大型站点仍可能标记为 partial，而 partial 会跳过清理，导致已删除页面一直可被检索。现在发现阶段会跳过非页面文件链接，并处理嵌套索引、MDX 代码块和重定向别名。来源说明，指向站外的页面链接仍会阻止清理，这是有意设计。

适用场景

使用 Agno 对文档站点做知识同步、需要观察同步进度或在失败时定位具体页面、以及管理大型 Mintlify 风格文档站的用户。

限制与待核实

以上为对发布说明的转述，未在本地或生产环境运行验证。来源未给出性能数据；每个尝试的超时与退避具体参数、failed_paths 截断行为之外的实现细节，需以实际代码或文档为准。来源标注的发布时间为 2026-10-02，不代表当前时间。