sureai v1.9.0

v1.9.0 — 标准与生态（Standards & Ecosystem）

平台补全（16 → 23）

• 新增 MiniMax / 阶跃星辰 StepFun / 百川 / 01.AI / 硅基流动 / 腾讯混元 / 讯飞星火（OpenAI 兼容协议族，独立模块）
• Azure Realtime（GA 端点）+ Gemini Live v1beta 接入
• MODERATION 能力声明精确化：Doubao/Qwen/Zhipu 对照官方文档核实无 /moderations → 移除声明（调用前快速失败）；OpenAI/Azure 保留

OpenTelemetry GenAI 桥接（sure-ai-otel）

• gen_ai.* 语义约定（semconv v1.44.0）：operation.duration 直方图、usage tokens、provider/error 属性
• provided 隔离：不引入 OTel SDK 时零依赖无感降级，trace 可直接进 Langfuse/Jaeger/Tempo

全链路异步 / 虚拟线程

• AiClient.chatAsync/chatStreamAsync 等 default 方法（20+ 平台零改动即获异步）
• AsyncExecutors 虚拟线程单例 + 5 装饰器 + AsyncClients 工厂

Quarkus Extension（sure-ai-quarkus-extension）

• runtime + deployment 双模块，sure.ai 配置映射
• BuildStep 为配置 api-key 的 22 平台注册 Singleton Bean

规模：1235 测试（新增 121）· core 87.05% / otel 88.15% 覆盖率 · 全量 verify BUILD SUCCESS

sureai v1.8.0

v1.8.0 — RAG 深化（RAG Deepening）

全部落在 sure-ai-rag，零新运行期依赖（仅 io.github.tasure:sure-core:0.2.0）。

高级检索策略

• HyDE：HydeRetriever —— LLM 生成假设文档，仅用假设文档向量检索，异常回退原 query
• Multi-Query：MultiQueryRetriever —— 查询改写拆多子查询，RRF（Σ1/(60+rank)）融合去重
• CRAG/Self-RAG：CorrectiveRetriever —— LLM 逐文档相关性自检，相关精炼；全不相关走 WebSearch 兜底或放大候选重检（crag_degraded）
• 父子分块：ParentChildSplitter + ParentChildRetriever —— 小块命中、按 parentId 聚合返回父块全文
• 语义分块：SemanticTextSplitter —— embedding 相邻相似度断点（均值−标准差），异常降级固定分块

GraphRAG

KnowledgeGraph 实体关系抽取（三元组容错解析）→ 标签传播社区发现 → LLM 社区摘要 → 社区检索

多模态 RAG

MultimodalDocument（MessagePart 图文混合）→ 文本向量入库 + 可插拔 ImageEmbedder 图片向量化

RAG 评估（RAGAS 风格）

RagTrace/TraceStore/TraceReplay + LlmJudge；Faithfulness / Context Precision / Context Recall / Answer Relevancy 四指标 + 阈值断言

向量库扩充（累计 9 个外部库）

Qdrant / Pinecone / Weaviate（REST）· Elasticsearch / OpenSearch（REST）· Redis（RESP over JDK Socket）——全部 JDK 原生，零依赖

可移植 metadata filter

FilterExpression 密封表达式（Eq/Ne/In/Gt/Gte/Lt/Lte/And/Or/Not）+ 6 方言翻译器；VectorStore SPI 带 filter 的 default 重载（二进制兼容）

规模：1114 测试（新增 129）· rag 覆盖率 86.3% · checkstyle/spotbugs/license 零违规 · 全量 mvn clean verify BUILD SUCCESS

v1.7.0 - Production-grade Agent

sureai v1.7.0 — 生产级 Agent

Agent 从「可编排」升级到「生产可用」：状态可持久化、动作可审批、过程可观测、知识跨会话。31 模块、985 测试 0 失败。

🆕 Added（sure-ai-agent）

• 检查点持久化：CheckpointStore SPI（InMemory/File，路径穿越防护）+ 序列化 + 重放恢复；run 开头/每轮/结束自动快照
• HITL 审批：ApprovalPolicy（AllTools/ToolName/HighRisk）× ApprovalHandler（AutoApproval/AutoReject/Console/Timeout）解耦；拒绝/超时不执行工具，拒绝文本回灌模型
• 流式事件：AgentEvent 8 种事件 + 广播器（订阅者异常隔离）+ SSE 写出器（event:/data: 帧）；桥接既有 AgentListener，ReActAgent 零改动
• 长期记忆：MemoryStore SPI + 余弦 Top-K 向量存储 + 三策略（Embedder/Summarizer/Extractor）；run 前 recall 注入 system，run 后自动沉淀

🔧 兼容性

• ReActAgent 保持 final，新增构造器重载 + 内部埋点 + 只读访问器；未注入新能力时行为与 v1.6.0 完全一致（有测试覆盖）
• 运行期第三方依赖仍有且仅有 sure-core:0.2.0

📊 质量

• 985 测试 0 失败（+48）；agent 模块行覆盖率 81.9%
• checkstyle / spotbugs / license / jacoco 门禁全绿
• 新文档 docs/agent-advanced.md；CHANGELOG [1.7.0]

Full Changelog: v1.6.0...v1.7.0

v1.6.0 - AI Gateway & Cost & OpenAI-compatible Proxy

sureai v1.6.0 — AI Gateway

本版本让 sureai 成为「Java 世界的 LiteLLM」：统一多平台网关 + 成本计量 + OpenAI 兼容独立代理。29 模块、937 测试 0 失败。

🆕 Added

• sure-ai-gateway（多供应商统一网关）
  • GatewayClient 实现 core 的 AiClient 接口，对调用方完全透明；只依赖 core，不硬依赖任何平台模块；
  • 6 种路由策略：显式指定 / 能力匹配 / 轮询 / 加权 / 最低延迟 / 最低成本（可组合）；
  • 自动故障转移：5xx / 超时 / 连接错误切换候选，4xx 不转移，熔断健康摘除 + FailoverListener 事件；
  • 虚拟密钥 + 租户限流 + 成本预算（超限抛 AiBudgetExceededException）。
• 成本计量（core）：PriceCatalog（18 个主流模型价格，官方定价核实）+ CostCalculator（输入/输出/缓存读/缓存写分别计价）+ CostAggregator（租户/模型/时间窗汇总）。
• 密钥池（core）：ApiKeyProvider + KeyRotatingClientDecorator，401/429 自动换 key 重试（坏 key 冷却）。
• sure-ai-proxy（OpenAI 兼容独立代理）：JDK 内置 HttpServer 启动，/v1/chat/completions（非流式 + SSE）、/v1/embeddings、/v1/models，虚拟密钥鉴权，任意应用改 baseUrl 即可接入全部平台（LiteLLM proxy 模式）。

📊 质量

• 937 测试 0 失败（+82）；core 87.2%、gateway 87.2%、proxy 81.2%
• checkstyle / spotbugs / license 门禁全绿；运行期第三方依赖仍有且仅有 sure-core:0.2.0
• 文档 docs/gateway.md、docs/cost.md、docs/proxy.md；示例 GatewayDemo / ProxyDemo

Full Changelog: v1.5.0...v1.6.0

v1.5.0 - Bidirectional MCP & JSON Schema

sureai v1.5.0 — MCP 双向能力

本版本让 sureai 从"MCP 客户端"升级为双向 MCP：新增 MCP Server，可把统一的多平台能力反向暴露给任何 MCP 客户端。27 模块、855 测试 0 失败。

🆕 Added

• MCP Server（sure-ai-mcp-server）：一个 MCP 连接即可调用 sureai 背后的全部平台能力。
  • 双协议自适应：有状态 2025-06-18（initialize 握手）与无状态 2026-07-28（_meta 携带协议版本、server/discover 能力广告、工具 ttlMs/cacheScope）；
  • 双传输零依赖：stdio（NDJSON，64MB 帧上限）与 Streamable HTTP（JDK 内置 HttpServer，JSON/SSE 双形态、CORS）；
  • 注册式工具：McpServerTool 按需挂载，预置 SureAiTools 工厂（chat / embed / image），支持单 AiClient 与多客户端 Map 路由；server 核心不硬依赖任何平台模块，保持平台隔离；
  • 已通过 sureai 自有 McpClient 的端到端回环验证（initialize → tools/list → tools/call）。
• JsonSchemaGenerator（core）：纯 JDK 反射零依赖生成 JSON Schema（Draft 2020-12），覆盖 POJO/record/嵌套/集合泛型/枚举/时间类型/循环引用；同时为 MCP 工具自动生成 inputSchema。

⚙️ Changed

• 平台能力精确声明：Azure / Doubao / Qwen / Zhipu 的 capabilities() 从全量兜底收口为实际能力（独立 Video/TTS/STT Client 承载的能力不再由主 Client 声明），调用未声明能力立即抛 AiException；无法核实的 MODERATION 等保守保留。

📊 质量

• 855 测试 0 失败（+43）；core 覆盖率 86.7%、mcp-server 78.5%
• checkstyle / spotbugs / license 门禁全绿；运行期第三方依赖仍有且仅有 sure-core:0.2.0
• 文档 docs/mcp-server.md（含 Claude Desktop 配置示例），新增 McpServerDemo / McpHttpServerDemo

说明：无状态规范的 MRTR / subscriptions / OAuth 扩展面为实验性（规范仍在 draft），已在文档注明。

Full Changelog: v1.4.0...v1.5.0

v1.4.0 - Maintainability Refactor

sureai v1.4.0 — 可维护性重构版本

完成 v1.2.0 全维度团队检视报告的最后一版整改。本版本为纯内部重构，公共 API 行为签名零变更，全工程 812 测试 0 失败。

♻️ Refactor

• AbstractAiClient 拆分（682 → 368 行，−46%）：抽出 RetryExecutor（重试/熔断/限流/指标/错误映射）、RequestBuilder（请求构建+签名钩子链）、MultipartBodyBuilder（multipart 拼装）三个包内协作类；18 个 protected/public 成员签名逐字不变，全部子类零修改。
• OpenAiCompatClient 拆分（841 → 340 行，−60%）：抽出 10 个能力域策略类（Chat/Stream/Image/Video/Audio/Embedding/Moderation/FineTune 等），10 个平台 Client 零修改。
• Util 单例样板抽取：新增通用 SingletonHolder（DCL 容器），17 个平台 Util 迁移，主源码净减 341 行。
• 删除 10 处平台 Client 重复的 applyDefaultBaseUrl 方法（−108 行），统一委托 AiConfig.withBaseUrlIfAbsent。

🆕 Added

• Client 能力面收口：新增 Capability 枚举（14 项）与 guard 机制；DeepSeek/Grok/Mistral/LlamaCpp/Moonshot 逐平台审计声明能力，调用不支持的方法时立即快速失败并给出清晰 AiException（此前要等上游 4xx）。
• 测试分类：JUnit4 @category（Unit/Slow/E2e）+ -Pfast Maven profile，快速回归 801 测试。
• CI 治理：OS 矩阵（ubuntu/macos/windows）、tag 触发的发布 workflow、benchmark 月度/手动 workflow。

📊 质量

• 812 测试 0 失败（+13：SingletonHolder 8 + CapabilityGuard 5）；core 覆盖率 86.6%
• checkstyle / spotbugs / license 门禁全绿；运行期第三方依赖仍有且仅有 sure-core:0.2.0

说明：OpenAI/Azure/Doubao/Qwen/Zhipu 五平台本轮保守保留全量能力声明（其能力边界需对照官方文档逐项核实，贸然缩减有误伤风险），列入后续迭代。

Full Changelog: v1.3.0...v1.4.0

v1.3.0 - Architecture Hardening

sureai v1.3.0 — 架构整改版本

完成 v1.2.0 全维度团队检视报告中的架构整改任务：P0 问题全部清零。全工程 26 模块、799 测试 0 失败。

🔒 Security

• 百度凭证不再出现在 URL：OAuth 获取 access_token 改为 POST body 提交 client_id/client_secret，业务 API（含图像）改为 Authorization: Bearer 头，避免凭证进入代理日志与 access log。

⚙️ Changed

• P0-2 Bedrock 全面接入客户端基类：BedrockClient 改继承 AbstractAiClient，自动获得重试 / 熔断 / 限流 / 指标 / 缓存 / 代理 / 超时能力（此前 Bedrock 自建 HttpClient，全部可靠性能力缺失）。core 新增通用 signRequest() 签名钩子（默认 no-op，非 Bedrock 专属开洞）。BedrockUtil 静态入口与其余平台对齐。
• Spring Boot Starter 补全 5 平台：新增 grok / mistral / llamacpp / cohere / bedrock 自动装配；PlatformProperties 与 AiConfig 字段对齐（代理/限流/熔断/缓存等可在 yml 配置）；百度 secretKey 可正常注入。

🆕 Added

• Cohere Rerank：新增 CohereRerankClient 对接 Cohere v2 /rerank（rerank-v3.5），接入 RAG 精排 SPI，与 Qwen Rerank 可互换。

🐛 Fixed

• DeepSeek 等不支持能力统一抛 AiException（此前抛 UnsupportedOperationException，自破异常体系）；
• 11 处路径参数 URL encode；Realtime Connector 复用并可关闭 HttpClient；AgentOrchestrator 实现 AutoCloseable 关闭线程池；
• CI 覆盖率上传改通配路径覆盖全部模块；零断言测试全部补实质断言；新增 4 平台 Demo、SSE 五类边界测试；时序型 flaky 测试改为可控同步。

📊 质量

• 799 测试 0 失败（+29）；core 覆盖率 86.0%，checkstyle / spotbugs / license 门禁全绿
• 运行期第三方依赖有且仅有 sure-core:0.2.0

Full Changelog: v1.2.1...v1.3.0

v1.2.1 - Hotfix (config retention / SSRF / Milvus injection / MCP hardening)

sureai v1.2.1 — 热修复版本

针对 v1.2.0 全维度团队检视发现的正确性与安全问题发布的热修复版本。770 个测试 0 失败，无新功能，建议所有 1.2.0 用户升级。

🐛 Fixed

• P0-1 配置字段静默丢失：补默认 baseUrl 时重建 AiConfig 会丢弃 metrics / 重试监听器 / 限流 / 缓存 / 熔断等字段。新增 AiConfig.withBaseUrl() 全字段拷贝，替换 19 处平台样板；新增逐字段回归测试。
• P1-4/5 MCP 健壮性：NDJSON 帧增加 64MB 上限（防恶意 server OOM）；子进程关闭改为 destroy → 5s 等待 → destroyForcibly（防 close 永久阻塞）；补超时 / EOF 断连 / 超大帧 / 吞 TERM 强杀测试。

🔒 Security

• P0-3 Milvus filter 注入：删除条件中 id 未转义，构造恶意 id 可误删整个集合。id 已转义并增加注入测试。
• P1-1 HttpTool SSRF：原仅校验 scheme，可访问内网/云元数据地址；响应全量入内存可致 OOM。新增 SSRFGuard（回环/私有段/链路本地/多播/IPv4 映射等 7 类拒绝 + DNS 解析全 IP 校验 + 重定向复检），响应体改流式限长。

📝 Docs

• P2-1：中英文 README 与 11 个平台文档的 Maven Central 徽章、依赖片段从过期的 0.1.0 更新为 1.2.1。

📊 质量

• 全工程 770 测试 0 失败（+27）；core 覆盖率 86.4%、rag 88.4%、agent 82.5%、mcp 81.0%
• checkstyle / spotbugs / license 门禁全绿；运行期第三方依赖仍有且仅有 sure-core:0.2.0

Full Changelog: v1.2.0...v1.2.1

v1.2.0 - MCP Client & AWS Bedrock

sureai v1.2.0 — MCP 客户端 & AWS Bedrock

本次迭代新增两个模块：MCP 协议客户端（接入 MCP 工具生态）与 AWS Bedrock 平台（纯 JDK SigV4 + 统一 Converse API）。平台总数达到 16 个，全工程 26 模块、743 测试全绿。

🆕 sure-ai-mcp（MCP 客户端）

• Model Context Protocol JSON-RPC 2.0 客户端：initialize 握手（协议版本 2025-06-18）、request/notification 消息层
• 双传输：Stdio（子进程 stdin/stdout NDJSON）与 Streamable HTTP（单端点，JSON/SSE 双响应形态，Mcp-Session-Id）
• 能力 API：tools/list·tools/call、resources/list·resources/read、prompts/list·prompts/get
• McpToolAdapter：MCP 工具一键包装为 ToolHandler 并批量注册进 ToolRegistry，与 ReActAgent / PlanExecuteAgent 无缝组合
• 20 测试（含子进程端到端回环），行覆盖率 80.4%

🆕 sure-ai-bedrock（AWS Bedrock）

• 纯 JDK 实现 AWS SigV4 签名（通过 AWS 官方测试向量校验，零 AWS SDK 依赖）
• 对接 Bedrock 统一 Converse API：非流式 + 流式（messageStart/contentBlockDelta/messageStop/metadata 事件）
• 凭证：显式传入 / AWS 标准环境变量 / SURE_AI_BEDROCK_* 覆盖
• 22 测试，行覆盖率 89.5%

📦 安装

<dependency>
  <groupId>io.github.tasure</groupId>
  <artifactId>sure-ai-mcp</artifactId>
  <version>1.2.0</version>
</dependency>
<dependency>
  <groupId>io.github.tasure</groupId>
  <artifactId>sure-ai-bedrock</artifactId>
  <version>1.2.0</version>
</dependency>

或使用 BOM / sure-ai-all 一次引入。

📊 质量

• 全工程 743 个测试 0 失败；checkstyle / spotbugs / license 头门禁全绿
• 运行期第三方依赖有且仅有 io.github.tasure:sure-core:0.2.0（MCP、SigV4 全部纯 JDK 实现）

Full Changelog: v1.1.0...v1.2.0

sureai v1.1.0 — 集成生态 · RAG 生产化 · Agent 深化 · 可靠性+覆盖面

sureai v1.1.0

面向 Java 的 AI 大模型基础设施包：每个主流平台一个独立 Maven 模块 + 独立入口工具类，互相隔离零依赖，一行坐标接入 15 家平台；核心能力层（RAG / Agent / 可靠性 / 可观测）与 Spring Boot 集成齐备。运行期第三方依赖有且仅有 io.github.tasure:sure-core:0.2.0。

本版本新增（4 轮迭代）

1.1.0 · 集成生态

• Spring Boot Starter（sure-ai-spring-boot-starter）：sure.ai.<platform>.api-key 属性绑定 → 自动装配 11 平台 AiClient 为 Bean；条件装配缺 key 不启动；core/平台模块零 Spring 依赖
• 响应缓存（core）：CacheStore SPI + LRU 内置实现（TTL/容量可配）+ 请求归一化 SHA-256；命中直返不发网络；默认关闭向后兼容

1.2.0 · RAG 生产化

• 外部向量库：MilvusVectorStore / ChromaVectorStore（REST 直调零新依赖，可注入 HttpClient 便于测试）；pgvector JDBC 文档示例
• PromptTemplate（{var}/默认值/严格模式/classpath）+ ChatTemplate（few-shot 多消息组装）
• QueryRewriter + ModelQueryRewriter（多查询扩展，不注入默认链路，向后兼容）

1.3.0 · Agent 深化

• PlanExecuteAgent 完整实现：规划→逐步执行→汇总，三级计划解析兜底，maxSteps+超时双防护
• 多 Agent 编排：AgentOrchestrator + 子任务拆分 + 结果聚合，并行执行、失败隔离
• 内置工具包：HttpTool / DateTimeTool / CalculatorTool（自研递归下降解析器，零 eval/反射）
• 会话记忆：ConversationMemory + 环形窗口实现，ReAct/Plan 可选注入

1.4.0 · 可靠性+覆盖面

• 熔断器（core）：CLOSED→OPEN→HALF_OPEN 三态状态机，OPEN 快速失败不发网络；默认关闭
• JMH Benchmark（sure-ai-benchmark，test scope 不进运行期链）：JSON/请求体/SSE 热点微基准
• 新平台 4 个：Grok (xAI) · Mistral · Cohere (v2 原生协议) · llama.cpp（本地 OpenAI 兼容）

质量

• 701 测试 / 0 失败，全部本地 mock（HttpServer），零真实网络依赖
• 24 个 Maven 子模块；jacoco / checkstyle / spotbugs / license 门禁全程全绿
• 运行期依赖红线：仅 sure-core 0.2.0；spring / jmh 均隔离于独立模块且不进 sure-ai-all

安装

<dependency>
  <groupId>io.github.tasure</groupId>
  <artifactId>sure-ai-core</artifactId>
  <version>1.1.0</version>
</dependency>
<!-- 平台模块：sure-ai-openai / sure-ai-gemini / sure-ai-grok / sure-ai-cohere ... 或 sure-ai-all 聚合 -->

文档

docs/ 下 27+ 篇：spring-boot / cache / vector-stores / prompt-template / agent / observability / circuit-breaker / benchmark / rag / images / video / audio / 各平台接入…… 详见仓库 README。

历史版本：v1.0.1 / v1.0.0 / v0.2.0 / v0.1.0（Maven Central 均已发布）。