springbootAI 2.3.10__tar.gz → 2.3.12__tar.gz

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

@@ -1,5 +1,44 @@
 # 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 尾部条件位置错误，写操作和字段权限现在失败关闭，动态租户值必须使用绑定参数。
+- 修复事务提交前监听器异常被吞掉及 `REQUIRES_NEW`/`NOT_SUPPORTED` 同步上下文错误，提交否决会触发回滚并恢复外层上下文。
+- 修复 Spring Cloud Bus RabbitMQ API 调用错误和缺失消费者，增加 Broker 确认、广播消费者、去重、消息大小限制及明确的失败状态。
+- 加固 MCP/AI 工具边界：限制 HTTP 响应、队列、集合和 Schema 深度，拒绝压缩炸弹及高风险正则表达式。
+- 修复 Prometheus Summary 创建失败、Tracer 已结束 Span 无界增长以及 Actuator/启动日志暴露原始异常的问题。
+- 修复 CI 在 AI 测试切片后提前执行总覆盖率门槛的问题，覆盖率阈值现在只在全部测试切片完成后统一校验。
+- 修复 LangChain 完整演示未声明文档加载根目录的问题，并为临时文件自动清理及 Windows 重定向控制台增加 UTF-8 输出兼容。
+
 ## [2.3.10] - 2026-08-29
 
 - 修复 AI 代理上下游消息被 SQL 注入检测误报：`#{...}` 绑定值始终按数据处理，不再扫描消息内容；`${...}` 原始替换仍默认拒绝，只有配置允许且值完整匹配严格白名单时才能使用。

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 2.3.10
+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
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Topic :: Database
 Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
-Requires-Python: >=3.10
+Requires-Python: <3.13,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastapi==0.141.1
@@ -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
@@ -120,6 +122,7 @@ Requires-Dist: psutil==6.1.1; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest==9.1.1; extra == "dev"
 Requires-Dist: pytest-cov==7.1.0; extra == "dev"
+Requires-Dist: mypy==1.18.2; extra == "dev"
 Requires-Dist: redis==8.1.0; extra == "dev"
 Requires-Dist: sqlglot==27.28.1; extra == "dev"
 Provides-Extra: full
@@ -129,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"
@@ -218,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.10`；支持 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)
 
@@ -349,10 +353,10 @@ SpringBootAI 是一个 **Python Web 框架**。它把 Java Spring Boot 的"注
 
 | 组件 | 当前版本 |
 |------|----------|
-| `springbootai` 框架 API | 2.3.10 |
-| `springbootai.orm.pymybatis` | 2.3.10 |
-| `springbootai.ai` AI 模块 | 2.3.10 |
-| `springbootai.langchain` LangChain 模块 | 2.3.10 |
+| `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 适合什么场景
@@ -1326,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` 至少应能容纳并发的外层和内层连接。
@@ -1487,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]`。
@@ -1992,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.10 → 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.10`；支持 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.10 |
-| `springbootai.orm.pymybatis` | 2.3.10 |
-| `springbootai.ai` AI 模块 | 2.3.10 |
-| `springbootai.langchain` LangChain 模块 | 2.3.10 |
+| `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.10 → 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.10"
+version = "2.3.12"
 description = "Spring-style Python framework with Web, ORM, Cloud and AI integrations"
 readme = "README.md"
 license = "MIT"
@@ -32,7 +32,7 @@ classifiers = [
     "Topic :: Database",
     "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.10,<3.13"
 
 # ========================================
 # 核心依赖——类似 Spring Boot Starter Web/Core
@@ -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
@@ -199,6 +200,7 @@ all = [
 dev = [
     "pytest==9.1.1",
     "pytest-cov==7.1.0",
+    "mypy==1.18.2",
     "redis==8.1.0",
     "sqlglot==27.28.1",
 ]
@@ -215,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",
@@ -278,6 +281,43 @@ markers = [
     "seata_integration: requires a compatible Seata SDK and real Seata Server",
 ]
 
+[tool.coverage.run]
+branch = true
+source = ["springbootai"]
+
+[tool.coverage.report]
+fail_under = 68
+show_missing = true
+
+[tool.mypy]
+python_version = "3.10"
+files = [
+    "springbootai/ai/annotation_runtime.py",
+    "springbootai/ai/advisors.py",
+    "springbootai/ai/vectorstore.py",
+    "springbootai/cloud/gateway.py",
+    "springbootai/websocket/router.py",
+    "springbootai/messaging/kafka.py",
+    "springbootai/messaging/rabbitmq.py",
+    "springbootai/data/repository.py",
+    "springbootai/retry/retry_decorator.py",
+    "springbootai/ai/tools.py",
+    "springbootai/cloud/bus.py",
+    "springbootai/cloud/tracer.py",
+    "springbootai/mcp/client.py",
+    "springbootai/mcp/config.py",
+    "springbootai/monitoring/prometheus.py",
+    "springbootai/orm/pymybatis/core/sql_session.py",
+    "springbootai/orm/pymybatis/security/access_control.py",
+    "springbootai/tx/synchronization.py",
+]
+ignore_missing_imports = true
+follow_imports = "skip"
+allow_untyped_defs = true
+allow_incomplete_defs = true
+check_untyped_defs = true
+show_error_codes = true
+
 [project.urls]
 Homepage = "https://github.com/YUCONGGEN/springbootAI"
 Repository = "https://github.com/YUCONGGEN/springbootAI.git"
@@ -296,4 +336,4 @@ include = ["springbootai*"]
 namespaces = false
 
 [tool.setuptools.package-data]
-springbootai = ["*.py", "**/*.py", "**/*.xml", "**/*.yml", "**/*.yaml"]
+springbootai = ["*.py", "py.typed", "**/*.py", "**/*.xml", "**/*.yml", "**/*.yaml"]

springbootai-2.3.12/requirements-ai.txt

@@ -0,0 +1,44 @@
+# ========================================
+# SpringBootAI optional AI/LangChain dependencies (exact versions)
+# ========================================
+# The AI module uses optional dependencies with a built-in fallback:
+#   - Without this file, native HTTP providers and FakeChatModel remain usable.
+#   - Installing it enables LangChain adapters detected by ai/providers.py.
+#
+# Install examples:
+#   pip install -r requirements-ai.txt
+#   pip install langchain-openai==1.4.2
+#
+# Recommended Python: 3.10+ (CI covers 3.10, 3.11 and 3.12).
+# Every pinned version is covered by tests and dependency auditing.
+# Keep this file ASCII-only: pip-audit may use the Windows system encoding.
+# ========================================
+
+# LangChain core (BaseChatModel, Embeddings and Runnable APIs).
+langchain-core==1.5.4
+
+# Classic APIs including LLMChain, ConversationChain and initialize_agent.
+langchain-classic==1.0.8
+
+# OpenAI-compatible providers (OpenAI, Azure, DeepSeek and Moonshot).
+langchain-openai==1.4.2
+
+# RecursiveCharacterTextSplitter and CharacterTextSplitter.
+langchain-text-splitters==1.1.2
+
+# Community integrations including FAISS, Chroma, DuckDuckGo and Wikipedia.
+langchain-community==0.4.2
+
+# Vector similarity calculations; 2.2.6 retains Python 3.10 compatibility.
+numpy==2.2.6
+
+# Pydantic v2 for validation and structured output parsing.
+pydantic==2.13.4
+
+# ========================================
+# Additional optional packages (install only when needed)
+# ========================================
+
+# Vector database: faiss-cpu
+# PDF document loading: pypdf
+# HTML parsing: beautifulsoup4

{springbootai-2.3.10 → 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
@@ -56,8 +58,3 @@ pydantic==2.13.4
 pytest==9.1.1
 pytest-cov==7.1.0
 openpyxl==3.1.5
-
-bcrypt
-springbootai
-springbootai
-springbootai

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 2.3.10
+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
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Topic :: Database
 Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
-Requires-Python: >=3.10
+Requires-Python: <3.13,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastapi==0.141.1
@@ -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
@@ -120,6 +122,7 @@ Requires-Dist: psutil==6.1.1; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest==9.1.1; extra == "dev"
 Requires-Dist: pytest-cov==7.1.0; extra == "dev"
+Requires-Dist: mypy==1.18.2; extra == "dev"
 Requires-Dist: redis==8.1.0; extra == "dev"
 Requires-Dist: sqlglot==27.28.1; extra == "dev"
 Provides-Extra: full
@@ -129,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"
@@ -218,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.10`；支持 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)
 
@@ -349,10 +353,10 @@ SpringBootAI 是一个 **Python Web 框架**。它把 Java Spring Boot 的"注
 
 | 组件 | 当前版本 |
 |------|----------|
-| `springbootai` 框架 API | 2.3.10 |
-| `springbootai.orm.pymybatis` | 2.3.10 |
-| `springbootai.ai` AI 模块 | 2.3.10 |
-| `springbootai.langchain` LangChain 模块 | 2.3.10 |
+| `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 适合什么场景
@@ -1326,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` 至少应能容纳并发的外层和内层连接。
@@ -1487,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]`。
@@ -1992,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.10 → springbootai-2.3.12}/springbootAI.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ springbootAI.egg-info/top_level.txt
 springbootai/__init__.py
 springbootai/devtools.py
 springbootai/main.py
+springbootai/py.typed
 springbootai/ai/__init__.py
 springbootai/ai/advisors.py
 springbootai/ai/annotation_runtime.py
@@ -266,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
@@ -306,6 +308,9 @@ tests/test_devtools_lifecycle_hardening.py
 tests/test_di_config_event_full.py
 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
@@ -317,8 +322,10 @@ tests/test_langchain_ext.py
 tests/test_langchain_module.py
 tests/test_langgraph_comprehensive.py
 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
@@ -328,9 +335,11 @@ tests/test_new_features.py
 tests/test_oauth2.py
 tests/test_optional_component_timeouts.py
 tests/test_orm_pymybatis_full.py
+tests/test_post_audit_enterprise_fixes.py
 tests/test_production_readiness.py
 tests/test_pymybatis_configuration_hardening.py
 tests/test_pymybatis_contract.py
+tests/test_remaining_enterprise_hardening.py
 tests/test_request_metrics.py
 tests/test_retry.py
 tests/test_runtime_configuration_fixes.py

{springbootai-2.3.10 → 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
 
@@ -50,6 +51,7 @@ httpx==0.28.1
 [dev]
 pytest==9.1.1
 pytest-cov==7.1.0
+mypy==1.18.2
 redis==8.1.0
 sqlglot==27.28.1
 
@@ -63,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
@@ -133,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.10 → 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.10"
+__version__ = "2.3.12"
 __author__ = "yuconggen"
 __license__ = "MIT"