Jupiter 的开源贡献

问题与影响#

Mem0 的普通 OpenAI provider 和官方文档已经使用标准环境变量 OPENAI_BASE_URL，但 OpenAIStructuredLLM 仍读取已废弃的 OPENAI_API_BASE。

这会导致一种很隐蔽的配置失效：用户明明通过 OPENAI_BASE_URL 配置了私有网关或 OpenAI-compatible endpoint，普通请求能够正确路由，structured-output 请求却可能静默回退到 https://api.openai.com/v1。问题不会在初始化时明确报错，而是在不同 provider 路径之间产生不一致行为。

根因定位#

通过直接对比两个 provider 的配置解析路径，定位到 structured provider 的 fallback 仍停留在旧变量：

1
OpenAILLM:           explicit config -> OPENAI_BASE_URL -> default endpoint
2
OpenAIStructuredLLM: explicit config -> OPENAI_API_BASE -> default endpoint

项目早期在 #2384 中已经统一到 OPENAI_BASE_URL，但 structured provider 没有被迁移覆盖。维护者在 Issue triage 中确认了复现、代码差异和根因。

修复方案#

修复将 structured provider 的配置优先级统一为：

1
显式 openai_base_url 配置
2
        ↓
3
OPENAI_BASE_URL 环境变量
4
        ↓
5
默认 OpenAI endpoint

同时移除旧环境变量在该路径中的 fallback，避免标准变量与遗留变量同时存在时继续出现歧义。

回归验证#

新增 mock 回归测试，在不进行真实网络请求的情况下：

• 同时设置标准变量和遗留变量；
• 实例化 OpenAIStructuredLLM；
• 验证传入 OpenAI SDK 的 base_url 使用标准 OPENAI_BASE_URL；
• 保留显式 openai_base_url 配置的最高优先级。

最终变更只涉及 2 个文件、+12/-1，保持了修复范围的集中性。维护者在 Issue 中确认根因，在 PR 中完成批准后直接合并。

工程价值#

• 能从“配置看起来正确但请求走错 endpoint”的现象追到不同 provider 的分支差异；
• 能把代码、历史迁移记录和官方配置文档组合成完整证据链；
• 通过 mock 精确验证 SDK 构造参数，不依赖外部网络或付费 API；
• 完成了本人提 Issue、响应维护者问题、补充文档依据、提交修复并被合并的完整闭环。

问题与影响#

Hermes Agent 使用 future.result(timeout=...) 轮询 MCP loop 中的异步任务。当 MCP 内层操作真正抛出 TimeoutError 时，Future 已经完成并保存了这个异常；但旧代码仍把它当成“这一次轮询等待超时”，直接进入下一次循环。

完成态 Future 的 result() 会立即再次抛出同一个异常，循环中又没有等待，于是形成高频自旋：

• 持续占用 CPU；
• 不断扩展异常 traceback；
• 原 Issue 报告者的复现记录显示 traceback 约以 108 MB/s 增长；
• 最终可能让 gateway OOM；
• 真实的内层错误还会被外层通用超时信息掩盖。

根因定位#

难点不在于“增加一个 timeout”，而在于 Python 异常类型别名：

1
concurrent.futures.TimeoutError is TimeoutError

在 Hermes 支持的 Python 版本中，下面两种情况会进入同一个 except：

1. Future 仍在运行，result(timeout=...) 的等待时间到期；
2. Future 已经完成，但内部协程保存并重新抛出了真实 TimeoutError。

如果只按异常类型判断，就无法知道应该继续轮询还是立即传播真实结果。

修复方案#

捕获异常后增加 Future 状态判断：

1
try:
2
    return future.result(timeout=wait_timeout)
3
except concurrent.futures.TimeoutError:
4
    if future.done():
5
        return future.result()
6
    continue

• Future 未完成：保留原来的轮询逻辑；
• Future 已完成：不带 timeout 解析一次，传播它保存的真实结果或异常；
• 同时正确处理“轮询刚超时，Future 恰好完成”的成功竞态。

确定性测试设计#

修复不仅验证了异常路径，还专门锁定两类竞态语义：

• 完成态异常：构造已经保存真实 TimeoutError 的 Future，验证同一个异常对象被传播，并且调用序列严格为“一次 timed poll + 一次 untimed resolve”；
• poll timeout 与成功完成竞态：第一次 timed result() 触发轮询超时的同时完成 Future，验证第二次调用使用 timeout=None 并返回成功结果。

这种测试不依赖不稳定的 wall-clock sleep，能精确证明新分支确实执行，也能避免把普通 pending poll 误当作覆盖了竞态。

上游结果#

维护者将提交 cherry-pick 到 #67183，并在其基础上增加 live-loop 集成测试。维护者给出的评价是：

“Of the four PRs that landed on this bug, yours had the cleanest, most deterministic tests … so it’s the base.” — 维护者评论

最终 #67183 已 Merged，作者 commit 3df8bd3 中保留 Jupiter363 署名；维护者随后也给出 最终落地确认。修复代码和确定性测试作为 P0 汇总修复的基线进入上游。

工程价值#

• 能处理同步 Future 与异步协程交界处的异常传播和竞态；
• 能从 Python 标准库类型别名追到生产级 crash loop/OOM；
• 能设计确定性并发回归测试，而不是只依赖时间窗口；
• 能在存在多个竞争修复时，用更强的根因解释和测试精度获得维护者采纳。

Spring AI Alibaba：修复 Bailian 已有知识库增量入库空跑#

证据：上游 Issue #4766 · Merged PR #286

DashScopeCloudStore.add() 向已有 pipeline 追加文档时，文件上传和解析能够成功，接口也可能返回 200，但百炼后台文档列表没有增加。排查发现旧实现混合了“创建 pipeline”和“向已有 pipeline 追加文档”两种语义。

第一轮修复绕开了重复创建，但真实云端验证进一步发现：已有 pipeline 调用 managed_ingest 虽返回 COMPLETED，任务却可能是 total_count=0, rows=[] 的成功空跑。最终方案将已有 pipeline 切换到正确的 /documents 增量 API，并补充创建失败后的回查路径、HTTP 层测试和服务级回归测试。

该 PR 的价值在于没有停在“HTTP 200”或“任务 completed”，而是继续追踪异步任务和最终业务状态，直至真实百炼环境中确认新文档进入知识库并完成索引。PR #286 已直接合并。

Spring AI 2.0：DashScope embedding 兼容修复被维护者采纳#

证据：原 PR #283 · 上游 commit b894e83

最初从主仓库 admin 模块的工具初始化异常入手，但继续追踪后确认，真正问题位于 spring-ai-extensions 对 Spring AI 2.0 的 API/nullability 适配。于是主动关闭了 admin 层局部规避 PR #4784，把修复移到正确模块。

最终被维护者采用的是 DashScopeEmbeddingModel 修复：显式处理 ResponseEntity#getBody() 的 nullable 返回，避免 retry callback 返回空值。维护者 rebase 后以本人为 author 合入 commit b894e83。

AgentScope：长对话 WebUI 回到底部能力#

证据：Issue #2096 · Merged PR #2106

为长对话增加可访问的浮动回到底部按钮。实现区分按钮显示阈值和自动滚动阈值，处理消息内容动态增长但没有原生 scroll 事件的情况，并把按钮放在消息区域内以避免遮挡 footer 与输入框。PR 获批准并直接合并，改动集中在 1 个文件（+61/-26）。

DashScope 多模态文档：跨三个仓库统一语义#

证据：主仓库 PR #4755 · Extensions PR #269 · Website PR #277

multiModel 的历史命名容易被理解为“多个模型”或模型编排，但它的真实运行语义是选择 DashScope multimodal generation endpoint。贡献同步修正了：

• 主仓库多模态示例中的配置键、默认值与用途；
• DashScopeChatOptions.multiModel 的 Javadoc；
• 官网配置属性说明。

3 个 PR 均直接合并，形成 Java API、示例配置和官网文档之间的跨仓库一致性闭环。

1. Agent Runtime 与并发可靠性#

• Future / coroutine 异常传播、轮询语义和完成竞态；
• 流式执行取消后的 checkpoint 恢复与消息序列一致性；
• shared agent 场景中的多用户状态与工作目录隔离；
• 事件流终止、失败恢复和 WebUI 状态收敛。

2. MCP 与 LLM Gateway#

• MCP tools/list cursor pagination；
• 大请求 routing peek 的 UTF-8 边界与 ASGI body replay；
• binary blob/text resource 类型保持；
• passthrough 认证头隔离与代理凭据边界；
• provider 特殊响应在日志与转换路径中的兼容。

3. Spring AI / DashScope / RAG#

• Spring AI 2.0 API 与 nullability 迁移；
• DashScope multimodal endpoint 配置语义；
• Bailian pipeline 创建、增量文档 API 与异步任务终态；
• graph/checkpoint 中二进制模型元数据与工具消息序列。

4. 安全与数据边界#

• 敏感信息 span-based 脱敏与重叠优先级；
• Kanban 附件 provenance、路径 containment 和回滚清理；
• 不可信 JSON 导入、非有限数、整数/时间范围和持久化边界；
• 对问题影响保持准确措辞，明确区分安全漏洞、数据完整性缺陷和普通兼容性 bug。

5. 跨语言贡献能力#

• Python：Hermes Agent、Mem0、LiteLLM、Agno、browser-use；
• TypeScript / Web：Mem0 TS OSS、AgentScope WebUI；
• Java：Spring AI Alibaba、DashScope integration；
• 协议与系统边界：MCP、ASGI、LLM gateway、RAG ingestion、checkpoint persistence。