springbootAI 2.3.11__tar.gz → 2.3.12__tar.gz

{springbootai-2.3.11 → springbootai-2.3.12}/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [Unreleased]
+
+## [2.3.12] - 2026-10-08
+
+- 修复 Python 3.10 类型解析将默认值为 None 的 dict 参数包装为 Optional 后误识别为查询参数的问题；可空及带类型参数的 dict 统一按 JSON 请求体绑定，保留原始校验类型。
+- 修复压测 Compose 和脚本仍引用旧 `tests_performance` 目录的问题，统一为仓库实际的 `tests/performance` 路径，恢复压测构建、k6 挂载和基准模块启动。
+- 修复显式空扫描包列表仍回退扫描整个入口包的问题；`scan_base_packages=[]` / `base_packages=[]` 现在禁用扫描，避免测试切片导入无关集成测试后被意外跳过，未指定列表时仍自动扫描入口包。
+- 修复 Docker 集成环境中 Kafka 发布 `localhost` 地址导致客户端尝试不可达 IPv6 地址的问题，统一公布测试客户端使用的 `127.0.0.1` 地址。
+- 新增订单查询 Agent + MCP 完整案例：自动启动 stdio 子进程或连接独立 HTTP 服务，发现查询工具、根据订单返回值查物流并汇总；提供离线固定步骤模型、真实 Provider 入口、生命周期关闭和集成测试。
+- 校正文档与源码行为的差异：修复示例导入、组件注册、路由前缀、Excel 类型声明、事务示例、重复 YAML 键及章节链接；明确 AI 元数据注解的实现范围、记忆身份要求、RAG 数据发送范围、Redis 故障行为、异步取消限制及迁移回滚语义。
+- 同步 2.3.12 的 AI 便捷功能说明，移除无法据当前验证记录支持的真实 API 全部验证承诺，并修正 Fake 模型、ETL 切片和工具 Schema 示例。
+- 应用显式启用 AI 时，在 Service 创建前自动装配默认组件并注册到 BeanFactory；已有自定义 `aiChatClient` 时保留其配置，省去手工 Configuration/Bean 注册。
+- 修复构造器延迟类型注解导致按类型注入失败的问题；解析原始构造器的类型命名空间，并支持已解析的 BeanDefinition 依赖信息。
+- 新增 `ChatClient.chat/achat/stream_text/astream_text` 快捷入口，复用默认 Advisor/工具配置并自动传递安全上下文身份和会话；关闭异步文本流会向底层流传播关闭请求，同步网络调用仍受其超时控制。
+- 简化 `@Prompt` / `@RAG`：方法体可写 `...`，无模板时自动选择明确的输入；具体 Pydantic 返回类型自动提示 JSON Schema 并绑定、校验输出，显式 `@StructuredOutput` 优先。
+- 修复 `@Prompt` 模板与 `@RAG` 组合时检索被跳过的问题，同步和异步路径均执行检索并保留 system 提示。
+- 修复 `@AiCache` 跨用户/租户共享缓存和进行中请求的问题，自定义 key 也自动包含可信身份与会话作用域。
+- 修复基础 `ChatModel.acall` 取消后过早释放并发名额及 LangGraph 异步排队取消后泄漏名额的问题。
+- 补充 AI 简化用法文档、可运行示例及回归测试。
+- 修复依赖审计发现的 PyJWT、urllib3、multidict 已知漏洞，分别升级至 `2.15.0`、`2.8.0`、`6.9.1`，同步核心/可选依赖声明与锁文件。
+- 修复安全上下文更新时修改父/兄弟协程共享对象的问题；认证信息和角色、权限列表现在复制后绑定到当前上下文。
+- 修复 JWT 字符串角色、权限按子串匹配的问题（例如 `ADMIN` 错误匹配 `SUPERADMIN`）；字符串按单个完整权限处理，非法集合返回认证失败。
+- 修复 `@PathVariable(name=...)` 别名未传给 FastAPI 的问题，URL 占位符名称与 Python 参数名可以不同。
+- 修复 Controller 延迟类型注解在 Web 适配器的模块中解析失败的问题；请求模型现在使用原始方法的命名空间解析，包括 AOP 包装的方法。
+- 支持 Controller 和异常 Advice 返回原生 `Response`（含 JSON、文件与 SSE 流式响应），保留状态码、响应头和响应体；显式 `HTTPException` 交给 FastAPI 处理。
+- 修复 `@Transactional` 配置异常筛选时取消任务仍提交数据的问题；取消和进程控制信号始终回滚，普通业务异常的筛选规则保持生效。
+- 修复 SqlSession 提交失败后遗留物理事务的问题；提交失败立即回滚，回滚失败交由连接池清理，关闭会话时仍能释放失效连接。
+- 新增请求绑定、安全上下文及数据库故障路径回归测试。
+
 ## [2.3.11] - 2026-09-01
 
 - 修复 PyMyBatis 访问控制仅覆盖查询、行级条件直接拼接及 SQL 尾部条件位置错误，写操作和字段权限现在失败关闭，动态租户值必须使用绑定参数。

{springbootai-2.3.11/springbootAI.egg-info → springbootai-2.3.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 2.3.11
+Version: 2.3.12
 Summary: Spring-style Python framework with Web, ORM, Cloud and AI integrations
 Author-email: YuConggen <1516933915@qq.com>
 License-Expression: MIT
@@ -30,9 +30,10 @@ Requires-Dist: python-dotenv==1.2.2
 Requires-Dist: DBUtils==3.1.2
 Requires-Dist: cryptography==50.0.0
 Requires-Dist: bcrypt==5.0.0
-Requires-Dist: pyjwt==2.13.0
+Requires-Dist: pyjwt==2.15.0
 Requires-Dist: pydantic==2.13.4
 Requires-Dist: requests==2.34.2
+Requires-Dist: urllib3==2.8.0
 Requires-Dist: httpx==0.28.1
 Requires-Dist: defusedxml==0.7.1
 Provides-Extra: mysql
@@ -49,6 +50,7 @@ Provides-Extra: kafka
 Requires-Dist: kafka-python==2.0.2; extra == "kafka"
 Provides-Extra: nacos
 Requires-Dist: nacos-sdk-python==2.0.11; extra == "nacos"
+Requires-Dist: multidict==6.9.1; extra == "nacos"
 Provides-Extra: prometheus
 Requires-Dist: prometheus-client==0.26.0; extra == "prometheus"
 Provides-Extra: logging
@@ -130,6 +132,7 @@ Requires-Dist: sqlalchemy==2.0.40; extra == "full"
 Requires-Dist: redis==8.1.0; extra == "full"
 Requires-Dist: pika==1.4.4; extra == "full"
 Requires-Dist: nacos-sdk-python==2.0.11; extra == "full"
+Requires-Dist: multidict==6.9.1; extra == "full"
 Requires-Dist: prometheus-client==0.26.0; extra == "full"
 Requires-Dist: loguru==0.7.3; extra == "full"
 Requires-Dist: sqlglot==27.28.1; extra == "full"
@@ -219,7 +222,7 @@ SpringBootAI 是一个采用 Spring 风格注解和分层结构的 Python 应用
 | AI 与编排 | 模型调用、Tools、RAG、Chain、状态图、MCP client/server | LangChain / LangGraph / 官方 MCP SDK |
 | 生产治理 | 健康检查、Prometheus、限流熔断、追踪、Swagger | prometheus-client / OpenTelemetry / OpenAPI |
 
-当前版本是 `2.3.11`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 是无 TC 全局锁的单进程受限补偿模式，不应当作跨服务强一致方案。
+当前版本是 `2.3.12`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 是无 TC 全局锁的单进程受限补偿模式，不应当作跨服务强一致方案。
 
 [新手指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | [全部文档](https://github.com/YUCONGGEN/springbootAI/tree/master/doc) | [变更日志](https://github.com/YUCONGGEN/springbootAI/blob/master/CHANGELOG.md) | [安全报告](https://github.com/YUCONGGEN/springbootAI/blob/master/SECURITY.md) | [发布检查](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/RELEASE_CHECKLIST.md)
 
@@ -350,10 +353,10 @@ SpringBootAI 是一个 **Python Web 框架**。它把 Java Spring Boot 的"注
 
 | 组件 | 当前版本 |
 |------|----------|
-| `springbootai` 框架 API | 2.3.11 |
-| `springbootai.orm.pymybatis` | 2.3.11 |
-| `springbootai.ai` AI 模块 | 2.3.11 |
-| `springbootai.langchain` LangChain 模块 | 2.3.11 |
+| `springbootai` 框架 API | 2.3.12 |
+| `springbootai.orm.pymybatis` | 2.3.12 |
+| `springbootai.ai` AI 模块 | 2.3.12 |
+| `springbootai.langchain` LangChain 模块 | 2.3.12 |
 | Python | 3.10+ |
 
 ### 1.4 适合什么场景
@@ -1327,7 +1330,12 @@ class RegistrationService:
 
 ```python
 @Transactional(propagation="REQUIRED")
+def required_operation():
+    ...
+
 @Transactional(propagation="NESTED")
+def nested_operation():
+    ...
 ```
 
 `NESTED` 在已有事务中创建 savepoint；`REQUIRES_NEW` 使用独立 Session/连接，连接池 `max_size` 至少应能容纳并发的外层和内层连接。
@@ -1488,6 +1496,26 @@ class CleanupJob:
 >
 > 提供 ChatClient（链式对话）、Advisor（对话顾问）、Tools（工具调用）、RAG（知识库检索增强生成）、Function Calling 等能力。支持 OpenAI / Ollama / DeepSeek / Moonshot 等多家大模型。
 
+以下便捷功能自 **2.3.12** 起提供，安装时运行 `pip install -U "springbootAI[ai]>=2.3.12"`。普通聊天只需 `client.chat("你好")`，异步使用 `await client.achat("你好")`；文本流使用 `client.stream_text(...)` / `client.astream_text(...)`。
+
+容器管理的 Service 可以只写提示词和签名：
+
+```python
+from springbootai.annotations import Prompt, RAG, Service
+
+@Service
+class Assistant:
+    @Prompt("用三句话总结：{text}")
+    def summarize(self, text: str) -> str:
+        ...
+
+    @RAG(top_k=3)
+    def answer(self, question: str) -> str:
+        ...
+```
+
+应用显式设置 `spring.ai.enabled: true` 并配置 Provider 后，框架自动调用模型、执行检索；RAG 数据先用向量库的 `add_texts(...)` 入库。返回类型声明为 Pydantic 模型时，自动生成 JSON 格式要求并校验结果，无需另写 `@StructuredOutput`。详见 [最少代码用法](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AI_MODULE.md#常用功能最少代码写法)。
+
 ### 12.2 LangChain 模块
 
 > 完整文档：[LANGCHAIN_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGCHAIN_MODULE.md)。安装：`pip install springbootAI[langchain]`。
@@ -1993,4 +2021,6 @@ pip install springbootAI[mcp]
 
 完整配置、FastAPI 挂载、stdio、认证、白名单、Spring AI/LangChain/LangGraph 组合方式和测试命令见 [MCP_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/MCP_MODULE.md)。
 
+可运行的 [Agent 调用 MCP 案例](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/MCP_AGENT_EXAMPLE.md) 演示订单与物流查询，支持一条命令启动本地 MCP 服务、连接 HTTP 服务和切换真实模型。
+
 LangChain 也支持 `@LangChainClient` + `@LangChainCall`，LangGraph 支持 `@LangGraph` + `@GraphNode` + `@GraphEdge` + `@GraphRoute` + `@GraphInvoke`。这些注解复用现有运行时，不会重新实现 LangChain、LangGraph 或 MCP 协议。

{springbootai-2.3.11 → springbootai-2.3.12}/README.md

@@ -56,7 +56,7 @@ SpringBootAI 是一个采用 Spring 风格注解和分层结构的 Python 应用
 | AI 与编排 | 模型调用、Tools、RAG、Chain、状态图、MCP client/server | LangChain / LangGraph / 官方 MCP SDK |
 | 生产治理 | 健康检查、Prometheus、限流熔断、追踪、Swagger | prometheus-client / OpenTelemetry / OpenAPI |
 
-当前版本是 `2.3.11`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 是无 TC 全局锁的单进程受限补偿模式，不应当作跨服务强一致方案。
+当前版本是 `2.3.12`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 是无 TC 全局锁的单进程受限补偿模式，不应当作跨服务强一致方案。
 
 [新手指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | [全部文档](https://github.com/YUCONGGEN/springbootAI/tree/master/doc) | [变更日志](https://github.com/YUCONGGEN/springbootAI/blob/master/CHANGELOG.md) | [安全报告](https://github.com/YUCONGGEN/springbootAI/blob/master/SECURITY.md) | [发布检查](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/RELEASE_CHECKLIST.md)
 
@@ -187,10 +187,10 @@ SpringBootAI 是一个 **Python Web 框架**。它把 Java Spring Boot 的"注
 
 | 组件 | 当前版本 |
 |------|----------|
-| `springbootai` 框架 API | 2.3.11 |
-| `springbootai.orm.pymybatis` | 2.3.11 |
-| `springbootai.ai` AI 模块 | 2.3.11 |
-| `springbootai.langchain` LangChain 模块 | 2.3.11 |
+| `springbootai` 框架 API | 2.3.12 |
+| `springbootai.orm.pymybatis` | 2.3.12 |
+| `springbootai.ai` AI 模块 | 2.3.12 |
+| `springbootai.langchain` LangChain 模块 | 2.3.12 |
 | Python | 3.10+ |
 
 ### 1.4 适合什么场景
@@ -1164,7 +1164,12 @@ class RegistrationService:
 
 ```python
 @Transactional(propagation="REQUIRED")
+def required_operation():
+    ...
+
 @Transactional(propagation="NESTED")
+def nested_operation():
+    ...
 ```
 
 `NESTED` 在已有事务中创建 savepoint；`REQUIRES_NEW` 使用独立 Session/连接，连接池 `max_size` 至少应能容纳并发的外层和内层连接。
@@ -1325,6 +1330,26 @@ class CleanupJob:
 >
 > 提供 ChatClient（链式对话）、Advisor（对话顾问）、Tools（工具调用）、RAG（知识库检索增强生成）、Function Calling 等能力。支持 OpenAI / Ollama / DeepSeek / Moonshot 等多家大模型。
 
+以下便捷功能自 **2.3.12** 起提供，安装时运行 `pip install -U "springbootAI[ai]>=2.3.12"`。普通聊天只需 `client.chat("你好")`，异步使用 `await client.achat("你好")`；文本流使用 `client.stream_text(...)` / `client.astream_text(...)`。
+
+容器管理的 Service 可以只写提示词和签名：
+
+```python
+from springbootai.annotations import Prompt, RAG, Service
+
+@Service
+class Assistant:
+    @Prompt("用三句话总结：{text}")
+    def summarize(self, text: str) -> str:
+        ...
+
+    @RAG(top_k=3)
+    def answer(self, question: str) -> str:
+        ...
+```
+
+应用显式设置 `spring.ai.enabled: true` 并配置 Provider 后，框架自动调用模型、执行检索；RAG 数据先用向量库的 `add_texts(...)` 入库。返回类型声明为 Pydantic 模型时，自动生成 JSON 格式要求并校验结果，无需另写 `@StructuredOutput`。详见 [最少代码用法](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AI_MODULE.md#常用功能最少代码写法)。
+
 ### 12.2 LangChain 模块
 
 > 完整文档：[LANGCHAIN_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGCHAIN_MODULE.md)。安装：`pip install springbootAI[langchain]`。
@@ -1830,4 +1855,6 @@ pip install springbootAI[mcp]
 
 完整配置、FastAPI 挂载、stdio、认证、白名单、Spring AI/LangChain/LangGraph 组合方式和测试命令见 [MCP_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/MCP_MODULE.md)。
 
+可运行的 [Agent 调用 MCP 案例](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/MCP_AGENT_EXAMPLE.md) 演示订单与物流查询，支持一条命令启动本地 MCP 服务、连接 HTTP 服务和切换真实模型。
+
 LangChain 也支持 `@LangChainClient` + `@LangChainCall`，LangGraph 支持 `@LangGraph` + `@GraphNode` + `@GraphEdge` + `@GraphRoute` + `@GraphInvoke`。这些注解复用现有运行时，不会重新实现 LangChain、LangGraph 或 MCP 协议。

{springbootai-2.3.11 → springbootai-2.3.12}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 [project]
 # Distribution name: springbootAI (pip install springbootAI); import package: springbootai.
 name = "springbootAI"
-version = "2.3.11"
+version = "2.3.12"
 description = "Spring-style Python framework with Web, ORM, Cloud and AI integrations"
 readme = "README.md"
 license = "MIT"
@@ -47,9 +47,10 @@ dependencies = [
     "DBUtils==3.1.2",
     "cryptography==50.0.0",
     "bcrypt==5.0.0",
-    "pyjwt==2.13.0",
+    "pyjwt==2.15.0",
     "pydantic==2.13.4",
     "requests==2.34.2",
+    "urllib3==2.8.0",
     "httpx==0.28.1",
     "defusedxml==0.7.1",
 ]
@@ -76,7 +77,7 @@ kafka = ["kafka-python==2.0.2"]
 # ========================================
 # 服务发现——类似 Spring Cloud Alibaba Nacos
 # ========================================
-nacos = ["nacos-sdk-python==2.0.11"]
+nacos = ["nacos-sdk-python==2.0.11", "multidict==6.9.1"]
 
 # ========================================
 # 监控和日志——类似 Spring Boot Actuator + Micrometer
@@ -216,6 +217,7 @@ full = [
     "redis==8.1.0",
     "pika==1.4.4",
     "nacos-sdk-python==2.0.11",
+    "multidict==6.9.1",
     # 监控 / 日志 / 安全
     "prometheus-client==0.26.0",
     "loguru==0.7.3",

{springbootai-2.3.11 → springbootai-2.3.12}/requirements.txt

@@ -29,7 +29,7 @@ sqlglot==27.28.1
 defusedxml==0.7.1
 
 # 认证授权
-pyjwt==2.13.0
+pyjwt==2.15.0
 cryptography==50.0.0
 bcrypt==5.0.0
 
@@ -41,6 +41,7 @@ loguru==0.7.3
 
 # HTTP 客户端（Feign）
 requests==2.34.2
+urllib3==2.8.0
 httpx==0.28.1
 
 # RabbitMQ 消息队列
@@ -48,6 +49,7 @@ pika==1.4.4
 
 # Nacos 服务注册发现
 nacos-sdk-python==2.0.11
+multidict==6.9.1
 
 # 参数校验
 pydantic==2.13.4
@@ -55,4 +57,4 @@ pydantic==2.13.4
 # 测试依赖
 pytest==9.1.1
 pytest-cov==7.1.0
-openpyxl==3.1.5
+openpyxl==3.1.5

{springbootai-2.3.11 → springbootai-2.3.12/springbootAI.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 2.3.11
+Version: 2.3.12
 Summary: Spring-style Python framework with Web, ORM, Cloud and AI integrations
 Author-email: YuConggen <1516933915@qq.com>
 License-Expression: MIT
@@ -30,9 +30,10 @@ Requires-Dist: python-dotenv==1.2.2
 Requires-Dist: DBUtils==3.1.2
 Requires-Dist: cryptography==50.0.0
 Requires-Dist: bcrypt==5.0.0
-Requires-Dist: pyjwt==2.13.0
+Requires-Dist: pyjwt==2.15.0
 Requires-Dist: pydantic==2.13.4
 Requires-Dist: requests==2.34.2
+Requires-Dist: urllib3==2.8.0
 Requires-Dist: httpx==0.28.1
 Requires-Dist: defusedxml==0.7.1
 Provides-Extra: mysql
@@ -49,6 +50,7 @@ Provides-Extra: kafka
 Requires-Dist: kafka-python==2.0.2; extra == "kafka"
 Provides-Extra: nacos
 Requires-Dist: nacos-sdk-python==2.0.11; extra == "nacos"
+Requires-Dist: multidict==6.9.1; extra == "nacos"
 Provides-Extra: prometheus
 Requires-Dist: prometheus-client==0.26.0; extra == "prometheus"
 Provides-Extra: logging
@@ -130,6 +132,7 @@ Requires-Dist: sqlalchemy==2.0.40; extra == "full"
 Requires-Dist: redis==8.1.0; extra == "full"
 Requires-Dist: pika==1.4.4; extra == "full"
 Requires-Dist: nacos-sdk-python==2.0.11; extra == "full"
+Requires-Dist: multidict==6.9.1; extra == "full"
 Requires-Dist: prometheus-client==0.26.0; extra == "full"
 Requires-Dist: loguru==0.7.3; extra == "full"
 Requires-Dist: sqlglot==27.28.1; extra == "full"
@@ -219,7 +222,7 @@ SpringBootAI 是一个采用 Spring 风格注解和分层结构的 Python 应用
 | AI 与编排 | 模型调用、Tools、RAG、Chain、状态图、MCP client/server | LangChain / LangGraph / 官方 MCP SDK |
 | 生产治理 | 健康检查、Prometheus、限流熔断、追踪、Swagger | prometheus-client / OpenTelemetry / OpenAPI |
 
-当前版本是 `2.3.11`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 是无 TC 全局锁的单进程受限补偿模式，不应当作跨服务强一致方案。
+当前版本是 `2.3.12`；支持 Python 3.10、3.11 和 3.12，许可证为 MIT。项目仍标记为 Beta。用于公网高并发、合规敏感或支付/订单/库存等核心系统前，必须完成目标数据库、流量模型、故障恢复和安全基线验证。内嵌 Gateway 适合内部路由，不替代公网 Nginx/Kong/WAF；Seata `distributed` 对接官方 TC + TCC 回调；`at` 是无 TC 全局锁的单进程受限补偿模式，不应当作跨服务强一致方案。
 
 [新手指南](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/BEGINNER_GUIDE.md) | [全部文档](https://github.com/YUCONGGEN/springbootAI/tree/master/doc) | [变更日志](https://github.com/YUCONGGEN/springbootAI/blob/master/CHANGELOG.md) | [安全报告](https://github.com/YUCONGGEN/springbootAI/blob/master/SECURITY.md) | [发布检查](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/RELEASE_CHECKLIST.md)
 
@@ -350,10 +353,10 @@ SpringBootAI 是一个 **Python Web 框架**。它把 Java Spring Boot 的"注
 
 | 组件 | 当前版本 |
 |------|----------|
-| `springbootai` 框架 API | 2.3.11 |
-| `springbootai.orm.pymybatis` | 2.3.11 |
-| `springbootai.ai` AI 模块 | 2.3.11 |
-| `springbootai.langchain` LangChain 模块 | 2.3.11 |
+| `springbootai` 框架 API | 2.3.12 |
+| `springbootai.orm.pymybatis` | 2.3.12 |
+| `springbootai.ai` AI 模块 | 2.3.12 |
+| `springbootai.langchain` LangChain 模块 | 2.3.12 |
 | Python | 3.10+ |
 
 ### 1.4 适合什么场景
@@ -1327,7 +1330,12 @@ class RegistrationService:
 
 ```python
 @Transactional(propagation="REQUIRED")
+def required_operation():
+    ...
+
 @Transactional(propagation="NESTED")
+def nested_operation():
+    ...
 ```
 
 `NESTED` 在已有事务中创建 savepoint；`REQUIRES_NEW` 使用独立 Session/连接，连接池 `max_size` 至少应能容纳并发的外层和内层连接。
@@ -1488,6 +1496,26 @@ class CleanupJob:
 >
 > 提供 ChatClient（链式对话）、Advisor（对话顾问）、Tools（工具调用）、RAG（知识库检索增强生成）、Function Calling 等能力。支持 OpenAI / Ollama / DeepSeek / Moonshot 等多家大模型。
 
+以下便捷功能自 **2.3.12** 起提供，安装时运行 `pip install -U "springbootAI[ai]>=2.3.12"`。普通聊天只需 `client.chat("你好")`，异步使用 `await client.achat("你好")`；文本流使用 `client.stream_text(...)` / `client.astream_text(...)`。
+
+容器管理的 Service 可以只写提示词和签名：
+
+```python
+from springbootai.annotations import Prompt, RAG, Service
+
+@Service
+class Assistant:
+    @Prompt("用三句话总结：{text}")
+    def summarize(self, text: str) -> str:
+        ...
+
+    @RAG(top_k=3)
+    def answer(self, question: str) -> str:
+        ...
+```
+
+应用显式设置 `spring.ai.enabled: true` 并配置 Provider 后，框架自动调用模型、执行检索；RAG 数据先用向量库的 `add_texts(...)` 入库。返回类型声明为 Pydantic 模型时，自动生成 JSON 格式要求并校验结果，无需另写 `@StructuredOutput`。详见 [最少代码用法](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/AI_MODULE.md#常用功能最少代码写法)。
+
 ### 12.2 LangChain 模块
 
 > 完整文档：[LANGCHAIN_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/LANGCHAIN_MODULE.md)。安装：`pip install springbootAI[langchain]`。
@@ -1993,4 +2021,6 @@ pip install springbootAI[mcp]
 
 完整配置、FastAPI 挂载、stdio、认证、白名单、Spring AI/LangChain/LangGraph 组合方式和测试命令见 [MCP_MODULE.md](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/MCP_MODULE.md)。
 
+可运行的 [Agent 调用 MCP 案例](https://github.com/YUCONGGEN/springbootAI/blob/master/doc/MCP_AGENT_EXAMPLE.md) 演示订单与物流查询，支持一条命令启动本地 MCP 服务、连接 HTTP 服务和切换真实模型。
+
 LangChain 也支持 `@LangChainClient` + `@LangChainCall`，LangGraph 支持 `@LangGraph` + `@GraphNode` + `@GraphEdge` + `@GraphRoute` + `@GraphInvoke`。这些注解复用现有运行时，不会重新实现 LangChain、LangGraph 或 MCP 协议。

{springbootai-2.3.11 → springbootai-2.3.12}/springbootAI.egg-info/SOURCES.txt

@@ -267,6 +267,7 @@ tests/test_actuator.py
 tests/test_actuator_prometheus_admin.py
 tests/test_ai_annotations.py
 tests/test_ai_comprehensive.py
+tests/test_ai_convenience.py
 tests/test_ai_declarative_annotations.py
 tests/test_ai_enterprise_hardening.py
 tests/test_ai_module.py
@@ -309,6 +310,7 @@ tests/test_enterprise_safety_regressions.py
 tests/test_excel_module.py
 tests/test_final_enterprise_hardening.py
 tests/test_followup_enterprise_fixes.py
+tests/test_framework_audit_regressions.py
 tests/test_hateoas.py
 tests/test_i18n_module.py
 tests/test_io_http_logging_hardening.py
@@ -323,6 +325,7 @@ tests/test_langgraph_module.py
 tests/test_latest_enterprise_audit_fixes.py
 tests/test_logging_config.py
 tests/test_lombok_annotations.py
+tests/test_mcp_agent_example.py
 tests/test_mcp_module.py
 tests/test_metadata.py
 tests/test_migration.py

{springbootai-2.3.11 → springbootai-2.3.12}/springbootAI.egg-info/requires.txt

@@ -6,9 +6,10 @@ python-dotenv==1.2.2
 DBUtils==3.1.2
 cryptography==50.0.0
 bcrypt==5.0.0
-pyjwt==2.13.0
+pyjwt==2.15.0
 pydantic==2.13.4
 requests==2.34.2
+urllib3==2.8.0
 httpx==0.28.1
 defusedxml==0.7.1
 
@@ -64,6 +65,7 @@ sqlalchemy==2.0.40
 redis==8.1.0
 pika==1.4.4
 nacos-sdk-python==2.0.11
+multidict==6.9.1
 prometheus-client==0.26.0
 loguru==0.7.3
 sqlglot==27.28.1
@@ -134,6 +136,7 @@ PyMySQL==1.2.0
 
 [nacos]
 nacos-sdk-python==2.0.11
+multidict==6.9.1
 
 [postgresql]
 psycopg2-binary==2.9.12

{springbootai-2.3.11 → springbootai-2.3.12}/springbootai/__init__.py

@@ -19,7 +19,7 @@ from .config import *
 from .utils import *
 from .main import create_app, run, SpringApplication, run_cli
 
-__version__ = "2.3.11"
+__version__ = "2.3.12"
 __author__ = "yuconggen"
 __license__ = "MIT"
 

{springbootai-2.3.11 → springbootai-2.3.12}/springbootai/ai/__init__.py

@@ -58,7 +58,7 @@ from springbootai.ai.observability import AIMetrics, ai_metrics
 from springbootai.ai.autoconfig import AIProperties, bind_ai_config, configure_ai
 from springbootai.ai.annotation_runtime import ContentModerationError
 
-__version__ = "2.3.11"
+__version__ = "2.3.12"
 
 __all__ = [
     # core