Merge c36c161b0e into c839b44256

- 【新功能】
  - 新增标签定向广播功能，支持通过 `-t <标签名>` 或 `广播到 <标签名>` 命令向指定标签的群组发送消息
  - 引入广播强制发送模式，允许绕过群组的任务阻断设置
  - 实现广播并发控制，通过配置限制同时发送任务数量，避免API速率限制
  - 优化视频消息处理，支持从URL下载视频内容并作为原始数据发送，提高跨平台兼容性
- 【配置】
  - 添加 `DEFAULT_BROADCAST` 配置项，用于设置群组进群时广播功能的默认开关状态
  - 添加 `BROADCAST_CONCURRENCY_LIMIT` 配置项，用于控制广播时的最大并发任务数

.github/workflows/codeql.yml

@@ -45,9 +45,12 @@ jobs:
         include:
           - language: python
             build-mode: none
+          - language: javascript-typescript
+            build-mode: none
         # CodeQL supports the following values keywords for 'language': 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'swift'
         # Use `c-cpp` to analyze code written in C, C++ or both
         # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
         # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
         # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
         # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how

envs/pydantic-v1/pyproject.toml

@@ -36,6 +36,7 @@ feedparser = "^6.0.11"
 imagehash = "^4.3.1"
 cn2an = "^0.5.22"
 dateparser = "^1.2.0"
+bilireq = ">=0.2.10"
 python-jose = { extras = ["cryptography"], version = "^3.3.0" }
 python-multipart = "^0.0.9"
 aiocache = {extras = ["redis"], version = "^0.12.3"}
@@ -46,10 +47,10 @@ nonebot-plugin-uninfo = ">=0.7.3"
 nonebot-plugin-waiter = "^0.8.1"
 multidict = ">=6.0.0,!=6.3.2"
 pydantic = ">=1.0.0, <2.0.0"
+
 redis = { version = ">=5", optional = true }
 asyncpg = { version = ">=0.20.0", optional = true }
 alibabacloud-devops20210625 = "^5.0.2"
-json_repair = "^0.54.0"
 
 [tool.poetry.group.dev.dependencies]
 nonebug = "^0.4"

envs/pydantic-v2/pyproject.toml

@@ -36,6 +36,7 @@ feedparser = "^6.0.11"
 imagehash = "^4.3.1"
 cn2an = "^0.5.22"
 dateparser = "^1.2.0"
+bilireq = ">=0.2.10"
 python-jose = { extras = ["cryptography"], version = "^3.3.0" }
 python-multipart = "^0.0.9"
 aiocache = {extras = ["redis"], version = "^0.12.3"}
@@ -46,10 +47,10 @@ nonebot-plugin-uninfo = ">=0.7.3"
 nonebot-plugin-waiter = "^0.8.1"
 multidict = ">=6.0.0,!=6.3.2"
 pydantic = ">=2.0.0, <3.0.0"
+
 redis = { version = ">=5", optional = true }
 asyncpg = { version = ">=0.20.0", optional = true }
 alibabacloud-devops20210625 = "^5.0.2"
-json_repair = "^0.54.0"
 
 [tool.poetry.group.dev.dependencies]
 nonebug = "^0.4"

plan.md

@@ -1,356 +0,0 @@
-# 权限检查系统优化方案
-
-## 项目概述
-
-优化 `zhenxun_bot` 的权限检查系统，将每条消息的数据库/缓存查询次数从 **6-10 次** 降低到 **1-2 次**。
-
----
-
-## 当前问题分析
-
-### 现有查询流程
-
-每条消息进入时，权限检查系统执行以下查询：
-
-| 阶段            | 查询内容                              | 次数   |
-| --------------- | ------------------------------------- | ------ |
-| `_load_context` | PluginInfo, UserConsole, GroupConsole | 3 次   |
-| `auth_ban`      | BanConsole                            | 1-2 次 |
-| `auth_bot`      | BotConsole                            | 1 次   |
-| `auth_admin`    | LevelUser (全局+群组)                 | 1-2 次 |
-| `auth_limit`    | PluginLimit (如果不在内存)            | 0-1 次 |
-
-**总计：6-10 次查询**
-
-### 问题根源
-
-1. 数据分散在多个表：`user_console`, `group_console`, `ban_console`, `bot_console`, `level_user`, `plugin_info`
-2. 每个检查模块独立查询，缺乏数据共享
-3. 即使有 Redis 缓存，也需要多次网络往返
-
----
-
-## 优化方案：预聚合权限快照 (Permission Snapshot)
-
-### 核心思想
-
-**用一个 Hash 结构存储权限检查所需的所有数据**，消息到达时只需 1-2 次查询。
-
-### 数据结构设计
-
-#### 1. 权限快照 (AuthSnapshot)
-
-```
-缓存键格式: AUTH_SNAPSHOT:{user_id}:{group_id}:{bot_id}
-
-Hash 结构:
-{
-    # === 用户信息 ===
-    "user_gold": 100,                  # 用户金币
-    "user_banned": 0,                  # 0=未ban, -1=永久ban, >0=ban结束时间戳
-    "user_ban_duration": 0,            # ban时长（用于计算剩余时间）
-
-    # === 用户权限等级 ===
-    "user_level_global": 0,            # 全局权限等级
-    "user_level_group": 0,             # 群组权限等级
-
-    # === 群组信息 ===
-    "group_status": 1,                 # 群组状态 (1=开启, 0=休眠)
-    "group_level": 5,                  # 群组等级
-    "group_is_super": 0,               # 是否超级群组
-    "group_block_plugins": "",         # 禁用插件列表 "<plugin1,<plugin2,"
-    "group_superuser_block_plugins": "", # 超级用户禁用插件列表
-    "group_banned": 0,                 # 群组是否被ban
-
-    # === Bot信息 ===
-    "bot_status": 1,                   # Bot状态
-    "bot_block_plugins": "",           # Bot禁用插件列表
-
-    # === 元数据 ===
-    "version": 1,                      # 快照版本（用于失效判断）
-    "created_at": 1703859600           # 创建时间戳
-}
-```
-
-#### 2. 插件信息缓存 (PluginSnapshot)
-
-插件是全局的，变化较少，可以使用本地内存缓存 + Redis 双层缓存：
-
-```
-缓存键格式: PLUGIN_SNAPSHOT:{module}
-
-结构:
-{
-    "status": true,                    # 全局开关状态
-    "block_type": null,                # 禁用类型 (PRIVATE/GROUP/ALL/null)
-    "admin_level": 0,                  # 调用所需权限等级
-    "cost_gold": 0,                    # 调用所需金币
-    "level": 5,                        # 所需群权限等级
-    "limit_superuser": false,          # 是否限制超级用户
-    "plugin_type": "NORMAL",           # 插件类型
-    "ignore_prompt": false             # 是否忽略阻断提示
-}
-```
-
-### 工作流程
-
-```
-消息到达
-    │
-    ▼
-┌──────────────────────────────────────────────────────┐
-│  1. 第一次查询：获取权限快照                           │
-│     AUTH_SNAPSHOT:{user_id}:{group_id}:{bot_id}      │
-│                                                      │
-│     - 如果存在且未过期 → 直接使用                      │
-│     - 如果不存在 → 触发快照构建（异步）                 │
-└──────────────────────────────────────────────────────┘
-    │
-    ▼
-┌──────────────────────────────────────────────────────┐
-│  2. 第二次查询：获取插件信息                           │
-│     PLUGIN_SNAPSHOT:{module}                          │
-│                                                      │
-│     - 优先从本地内存缓存获取                           │
-│     - 未命中时从 Redis 获取                            │
-│     - 仍未命中时从 DB 加载并缓存                        │
-└──────────────────────────────────────────────────────┘
-    │
-    ▼
-┌──────────────────────────────────────────────────────┐
-│  3. 执行权限检查（纯内存计算，无 I/O）                  │
-│                                                      │
-│     - ban 检查                                        │
-│     - bot 状态检查                                    │
-│     - 插件状态检查                                    │
-│     - 群组状态检查                                    │
-│     - 权限等级检查                                    │
-│     - 金币检查                                        │
-└──────────────────────────────────────────────────────┘
-    │
-    ▼
- 权限检查完成
-```
-
-### 缓存失效策略
-
-#### 主动失效（事件驱动）
-
-| 事件             | 失效范围                                  |
-| ---------------- | ----------------------------------------- |
-| 用户金币变化     | `AUTH_SNAPSHOT:{user_id}:*:*`             |
-| 用户被 ban/unban | `AUTH_SNAPSHOT:{user_id}:*:*`             |
-| 群组设置变更     | `AUTH_SNAPSHOT:*:{group_id}:*`            |
-| Bot 配置变更     | `AUTH_SNAPSHOT:*:*:{bot_id}`              |
-| 插件配置变更     | `PLUGIN_SNAPSHOT:{module}` + 本地内存缓存 |
-| 用户权限变更     | `AUTH_SNAPSHOT:{user_id}:{group_id}:*`    |
-
-#### 被动失效（TTL）
-
-- 权限快照 TTL：**60 秒**（权衡实时性和性能）
-- 插件快照 TTL：**300 秒**（插件配置变化较少）
-- 本地内存缓存 TTL：**30 秒**
-
----
-
-## 实现计划
-
-### Phase 1: 基础设施 ✅ [已完成]
-
-- [x] 新增 `CacheType.AUTH_SNAPSHOT` 和 `CacheType.PLUGIN_SNAPSHOT`
-- [x] 创建 `AuthSnapshot` Pydantic 模型
-- [x] 创建 `PluginSnapshot` Pydantic 模型
-- [x] 实现快照构建器 `SnapshotBuilder`
-
-### Phase 2: 快照服务 ✅ [已完成]
-
-- [x] 创建 `AuthSnapshotService` 类
-
-  - [x] `get_snapshot(user_id, group_id, bot_id)` - 获取权限快照
-  - [x] `build_snapshot(user_id, group_id, bot_id)` - 构建权限快照
-  - [x] `invalidate_user(user_id)` - 失效用户相关快照
-  - [x] `invalidate_group(group_id)` - 失效群组相关快照
-  - [x] `invalidate_bot(bot_id)` - 失效 Bot 相关快照
-
-- [x] 创建 `PluginSnapshotService` 类
-  - [x] `get_plugin(module)` - 获取插件信息（本地缓存优先）
-  - [x] `invalidate_plugin(module)` - 失效插件缓存
-  - [x] `warmup()` - 预热所有插件缓存
-
-### Phase 3: 权限检查器重构 ✅ [已完成]
-
-- [x] 创建新的 `OptimizedAuthChecker` 类
-- [x] 基于快照数据的权限检查逻辑
-- [x] 无 I/O 的纯内存计算
-- [x] 保持与现有系统的兼容性
-
-### Phase 4: 缓存失效集成 ⏳ [可选优化]
-
-> 注：当前实现使用 TTL 自动过期机制，以下为可选的主动失效优化
-
-- [ ] 在 `UserConsole` 的写操作中添加失效逻辑
-- [ ] 在 `GroupConsole` 的写操作中添加失效逻辑
-- [ ] 在 `BanConsole` 的写操作中添加失效逻辑
-- [ ] 在 `BotConsole` 的写操作中添加失效逻辑
-- [ ] 在 `LevelUser` 的写操作中添加失效逻辑
-- [ ] 在 `PluginInfo` 的写操作中添加失效逻辑
-
-### Phase 5: 测试与验证 ⏳ [待测试]
-
-- [ ] 单元测试
-- [ ] 性能对比测试
-- [ ] 边界情况测试
-
----
-
-## 文件结构
-
-```
-zhenxun/
-├── services/
-│   └── auth_snapshot/
-│       ├── __init__.py
-│       ├── models.py          # AuthSnapshot, PluginSnapshot 模型
-│       ├── builder.py         # 快照构建器
-│       ├── service.py         # 快照服务
-│       └── checker.py         # 优化后的权限检查器
-└── builtin_plugins/
-    └── hooks/
-        └── auth_checker_v2.py # 新版权限检查入口
-```
-
----
-
-## 性能预期
-
-| 指标           | 优化前  | 优化后     | 提升     |
-| -------------- | ------- | ---------- | -------- |
-| DB 查询次数    | 6-10 次 | **1-3 次** | 70-85%↓  |
-| 平均延迟       | ~50ms   | ~10ms      | 80%↓     |
-| Redis 连接压力 | 高      | 低         | 显著降低 |
-
-### 查询优化详情
-
-**优化前（5-7 次 DB 查询）：**
-
-1. UserConsole - 用户金币
-2. LevelUser (全局) - 全局权限等级
-3. LevelUser (群组) - 群组权限等级
-4. BanConsole (用户全局)
-5. BanConsole (用户群组)
-6. BanConsole (群组)
-7. GroupConsole - 群组信息
-8. BotConsole - Bot 信息
-
-**优化后（1-3 次 DB 查询）：**
-
-1. **单条复合 SQL** - 使用 UNION ALL 合并 UserConsole + LevelUser + BanConsole（1 次）
-   - ✅ 支持 **MySQL** (使用 `%s` 占位符)
-   - ✅ 支持 **PostgreSQL** (使用 `$1, $2...` 占位符)
-   - ✅ 支持 **SQLite** (使用 `?` 占位符)
-   - ✅ 使用**参数化查询**防止 SQL 注入
-2. GroupConsole - **内存缓存 60s**，变化时失效（0-1 次）
-3. BotConsole - **内存缓存 300s**，变化时失效（0-1 次）
-
-**最优情况**：缓存命中时只需 1 次 DB 查询
-**最差情况**：3 次 DB 查询（全部未命中缓存）
-
----
-
-## 风险与缓解
-
-| 风险             | 缓解措施                                     |
-| ---------------- | -------------------------------------------- |
-| 快照数据过期     | 合理的 TTL + 主动失效机制                    |
-| 快照构建延迟     | 异步构建 + 首次访问降级到旧流程              |
-| 内存占用增加     | 监控内存使用 + 合理的缓存清理                |
-| 数据一致性       | 写操作后立即失效缓存                         |
-| **DB 过载风险**  | **全局 Semaphore 限制并发构建数量 (50)**     |
-| **并发构建重复** | **按 cache_key 的 asyncio.Lock**             |
-| **构建等待超时** | **3 秒超时后返回默认快照，允许请求继续处理** |
-
-### 并发控制机制
-
-```
-大量消息同时进入时:
-
-1. 同一 user:group:bot 组合
-   - 使用 asyncio.Lock 保证只构建一次
-   - 其他等待的协程复用同一个 Future 结果
-
-2. 不同 user:group:bot 组合
-   - 使用全局 Semaphore 限制最多 50 个并发构建
-   - 超过限制的请求排队等待（最多 3 秒）
-   - 等待超时则返回默认快照，避免请求阻塞
-
-这样即使 1000 个不同用户同时发消息:
-- 最多只有 50 个并发 DB 查询
-- 每个构建 5-7 次查询 = 最多 350 次并发 DB 查询
-- 远低于直接查询的 6000 次
-```
-
----
-
----
-
-## 使用方式
-
-### 方式一：替换原有权限检查器（推荐）
-
-修改 `zhenxun/builtin_plugins/hooks/__init__.py`，将 `auth_checker` 替换为 `auth_checker_v2`：
-
-```python
-# 原来的导入
-# from . import auth_checker
-
-# 替换为
-from . import auth_checker_v2
-```
-
-### 方式二：并行测试
-
-同时加载两个版本，通过日志对比性能：
-
-```python
-from . import auth_checker      # 原版本
-from . import auth_checker_v2   # 优化版本（会覆盖原版本的 run_preprocessor）
-```
-
-### API 使用示例
-
-```python
-from zhenxun.services.auth_snapshot import (
-    AuthSnapshotService,
-    PluginSnapshotService,
-    AuthSnapshot,
-    PluginSnapshot,
-)
-
-# 获取权限快照
-snapshot = await AuthSnapshotService.get_snapshot(
-    user_id="123456",
-    group_id="789012",
-    bot_id="bot_001"
-)
-
-# 检查用户是否被ban
-if snapshot.is_user_banned():
-    print(f"用户被ban，剩余时间: {snapshot.get_user_ban_remaining()}秒")
-
-# 获取插件快照
-plugin = await PluginSnapshotService.get_plugin("example_plugin")
-if plugin and plugin.cost_gold > 0:
-    print(f"此插件需要 {plugin.cost_gold} 金币")
-
-# 手动失效缓存（数据更新时调用）
-await AuthSnapshotService.invalidate_user("123456")
-await PluginSnapshotService.invalidate_plugin("example_plugin")
-```
-
----
-
-## 进度追踪
-
-- 开始日期：2025-12-29
-- 当前阶段：核心功能已完成
-- 状态：✅ 基础功能完成，待测试验证

pyproject.toml

@@ -36,6 +36,7 @@ feedparser = "^6.0.11"
 imagehash = "^4.3.1"
 cn2an = "^0.5.22"
 dateparser = "^1.2.0"
+bilireq = ">=0.2.10"
 python-jose = { extras = ["cryptography"], version = "^3.3.0" }
 python-multipart = "^0.0.9"
 aiocache = {extras = ["redis"], version = "^0.12.3"}
@@ -45,7 +46,6 @@ tenacity = "^9.0.0"
 nonebot-plugin-uninfo = ">=0.7.3"
 nonebot-plugin-waiter = "^0.8.1"
 multidict = ">=6.0.0,!=6.3.2"
-json_repair = "^0.54.0"
 
 redis = { version = ">=5", optional = true }
 asyncpg = { version = ">=0.20.0", optional = true }

requirements.txt

@@ -21,6 +21,7 @@ feedparser>=6.0.11,<7.0.0
 ImageHash>=4.3.1,<5.0.0
 cn2an>=0.5.22,<0.6.0
 dateparser>=1.2.0,<2.0.0
+bilireq>=0.2.10
 python-jose[cryptography]>=3.3.0,<4.0.0
 python-multipart>=0.0.9,<0.1.0
 aiocache[redis]>=0.12.3,<0.13.0
@@ -31,6 +32,6 @@ nonebot-plugin-uninfo>=0.7.3
 nonebot-plugin-waiter>=0.8.1,<0.9.0
 multidict>=6.0.0,<7.0.0,!=6.3.2
 alibabacloud-devops20210625>=5.0.2,<6.0.0
-json_repair>=0.54.0,<0.55.0
+
 redis>=5
 asyncpg>=0.20.0

zhenxun/builtin_plugins/hooks/auth/auth_admin.py

@@ -6,13 +6,13 @@ from nonebot_plugin_uninfo import Uninfo
 
 from zhenxun.models.level_user import LevelUser
 from zhenxun.models.plugin_info import PluginInfo
-from zhenxun.services.auth_snapshot.exception import SkipPluginException
 from zhenxun.services.data_access import DataAccess
 from zhenxun.services.db_context import DB_TIMEOUT_SECONDS
 from zhenxun.services.log import logger
 from zhenxun.utils.utils import get_entity_ids
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD
+from .exception import SkipPluginException
 from .utils import send_message
 
 

zhenxun/builtin_plugins/hooks/auth/auth_ban.py

@@ -9,13 +9,14 @@ from nonebot_plugin_uninfo import Uninfo
 from zhenxun.configs.config import Config
 from zhenxun.models.ban_console import BanConsole
 from zhenxun.models.plugin_info import PluginInfo
-from zhenxun.services.auth_snapshot.exception import SkipPluginException
+from zhenxun.services.data_access import DataAccess
 from zhenxun.services.db_context import DB_TIMEOUT_SECONDS
 from zhenxun.services.log import logger
 from zhenxun.utils.enum import PluginType
 from zhenxun.utils.utils import EntityIDs, get_entity_ids
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD
+from .exception import SkipPluginException
 from .utils import freq, send_message
 
 Config.add_plugin_config(
@@ -48,6 +49,89 @@ async def calculate_ban_time(ban_record: BanConsole | None) -> int:
     return 0
 
 
+async def is_ban(user_id: str | None, group_id: str | None) -> int:
+    """检查用户或群组是否被ban
+
+    参数:
+        user_id: 用户ID
+        group_id: 群组ID
+
+    返回:
+        int: ban的剩余时间，0表示未被ban
+    """
+    if not user_id and not group_id:
+        return 0
+
+    start_time = time.time()
+    ban_dao = DataAccess(BanConsole)
+
+    # 分别获取用户在群组中的ban记录和全局ban记录
+    group_user = None
+    user = None
+
+    try:
+        # 并行查询用户和群组的 ban 记录
+        tasks = []
+        if user_id and group_id:
+            tasks.append(ban_dao.safe_get_or_none(user_id=user_id, group_id=group_id))
+        if user_id:
+            tasks.append(
+                ban_dao.safe_get_or_none(user_id=user_id, group_id__isnull=True)
+            )
+
+        # 等待所有查询完成，添加超时控制
+        if tasks:
+            try:
+                ban_records = await asyncio.wait_for(
+                    asyncio.gather(*tasks), timeout=DB_TIMEOUT_SECONDS
+                )
+                if len(tasks) == 2:
+                    group_user, user = ban_records
+                elif user_id and group_id:
+                    group_user = ban_records[0]
+                else:
+                    user = ban_records[0]
+            except asyncio.TimeoutError:
+                logger.error(
+                    f"查询ban记录超时: user_id={user_id}, group_id={group_id}",
+                    LOGGER_COMMAND,
+                )
+                return 0
+
+        # 检查记录并计算ban时间
+        results = []
+        if group_user:
+            results.append(group_user)
+        if user:
+            results.append(user)
+
+        # 如果没有找到记录，返回0
+        if not results:
+            return 0
+
+        logger.debug(f"查询到的ban记录: {results}", LOGGER_COMMAND)
+        # 检查所有记录，找出最严格的ban（时间最长的）
+        max_ban_time: int = 0
+        for result in results:
+            if result.duration > 0 or result.duration == -1:
+                # 直接计算ban时间，避免再次查询数据库
+                ban_time = await calculate_ban_time(result)
+                if ban_time == -1 or ban_time > max_ban_time:
+                    max_ban_time = ban_time
+
+        return max_ban_time
+    finally:
+        # 记录执行时间
+        elapsed = time.time() - start_time
+        if elapsed > WARNING_THRESHOLD:  # 记录耗时超过500ms的检查
+            logger.warning(
+                f"is_ban 耗时: {elapsed:.3f}s",
+                LOGGER_COMMAND,
+                session=user_id,
+                group_id=group_id,
+            )
+
+
 def check_plugin_type(matcher: Matcher) -> bool:
     """判断插件类型是否是隐藏插件
 
@@ -90,22 +174,45 @@ def format_time(time_val: float) -> str:
     return time_str
 
 
-async def user_handle(
+async def group_handle(group_id: str) -> None:
-    plugin: PluginInfo, entity: EntityIDs, session: Uninfo, time_val: int
+    """群组ban检查
-) -> None:
+
+    参数:
+        group_id: 群组id
+
+    异常:
+        SkipPluginException: 群组处于黑名单
+    """
+    start_time = time.time()
+    try:
+        if await is_ban(None, group_id):
+            raise SkipPluginException("群组处于黑名单中...")
+    finally:
+        # 记录执行时间
+        elapsed = time.time() - start_time
+        if elapsed > WARNING_THRESHOLD:  # 记录耗时超过500ms的检查
+            logger.warning(
+                f"group_handle 耗时: {elapsed:.3f}s",
+                LOGGER_COMMAND,
+                group_id=group_id,
+            )
+
+
+async def user_handle(plugin: PluginInfo, entity: EntityIDs, session: Uninfo) -> None:
     """用户ban检查
 
     参数:
         module: 插件模块名
         entity: 实体ID信息
         session: Uninfo
-        time_val: 剩余ban时间
+
     异常:
         SkipPluginException: 用户处于黑名单
     """
     start_time = time.time()
     try:
         ban_result = Config.get_config("hook", "BAN_RESULT")
+        time_val = await is_ban(entity.user_id, entity.group_id)
         if not time_val:
             return
         time_str = format_time(time_val)
@@ -161,25 +268,24 @@ async def auth_ban(
         entity = get_entity_ids(session)
         if entity.user_id in bot.config.superusers:
             return
-
+        if entity.group_id:
-        results = await BanConsole.is_ban_cached(entity.user_id, entity.group_id)
+            try:
-        if not results:
+                await asyncio.wait_for(
-            return
+                    group_handle(entity.group_id), timeout=DB_TIMEOUT_SECONDS
-
-        for result in results:
-            if not result.user_id and result.group_id:
-                logger.debug(
-                    f"群组{result.group_id}被ban: {result}",
-                    target=f"{result.group_id}:{entity.user_id}",
                 )
-                raise SkipPluginException(f"群组: {result.group_id} 处于黑名单中...")
+            except asyncio.TimeoutError:
-            if result.user_id:
+                logger.error(f"群组ban检查超时: {entity.group_id}", LOGGER_COMMAND)
-                logger.debug(
+                # 超时时不阻塞，继续执行
-                    f"用户{result.user_id}被ban: {result}",
-                    target=f"{result.group_id}:{entity.user_id}",
-                )
-                await user_handle(plugin, entity, session, result.duration)
 
+        if entity.user_id:
+            try:
+                await asyncio.wait_for(
+                    user_handle(plugin, entity, session),
+                    timeout=DB_TIMEOUT_SECONDS,
+                )
+            except asyncio.TimeoutError:
+                logger.error(f"用户ban检查超时: {entity.user_id}", LOGGER_COMMAND)
+                # 超时时不阻塞，继续执行
     finally:
         # 记录总执行时间
         elapsed = time.time() - start_time

zhenxun/builtin_plugins/hooks/auth/auth_bot.py

@@ -3,13 +3,13 @@ import time
 
 from zhenxun.models.bot_console import BotConsole
 from zhenxun.models.plugin_info import PluginInfo
-from zhenxun.services.auth_snapshot.exception import SkipPluginException
 from zhenxun.services.data_access import DataAccess
 from zhenxun.services.db_context import DB_TIMEOUT_SECONDS
 from zhenxun.services.log import logger
 from zhenxun.utils.common_utils import CommonUtils
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD
+from .exception import SkipPluginException
 
 
 async def auth_bot(plugin: PluginInfo, bot_id: str):

zhenxun/builtin_plugins/hooks/auth/auth_cost.py

@@ -4,10 +4,10 @@ from nonebot_plugin_uninfo import Uninfo
 
 from zhenxun.models.plugin_info import PluginInfo
 from zhenxun.models.user_console import UserConsole
-from zhenxun.services.auth_snapshot.exception import SkipPluginException
 from zhenxun.services.log import logger
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD
+from .exception import SkipPluginException
 from .utils import send_message
 
 

zhenxun/builtin_plugins/hooks/auth/auth_group.py

@@ -4,10 +4,10 @@ from nonebot_plugin_alconna import UniMsg
 
 from zhenxun.models.group_console import GroupConsole
 from zhenxun.models.plugin_info import PluginInfo
-from zhenxun.services.auth_snapshot.exception import SkipPluginException
 from zhenxun.services.log import logger
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD, SwitchEnum
+from .exception import SkipPluginException
 
 
 async def auth_group(

zhenxun/builtin_plugins/hooks/auth/auth_limit.py

@@ -8,7 +8,6 @@ from pydantic import BaseModel
 
 from zhenxun.models.plugin_info import PluginInfo
 from zhenxun.models.plugin_limit import PluginLimit
-from zhenxun.services.auth_snapshot.exception import SkipPluginException
 from zhenxun.services.db_context import DB_TIMEOUT_SECONDS
 from zhenxun.services.log import logger
 from zhenxun.utils.enum import LimitWatchType, PluginLimitType
@@ -19,6 +18,7 @@ from zhenxun.utils.time_utils import TimeUtils
 from zhenxun.utils.utils import get_entity_ids
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD
+from .exception import SkipPluginException
 
 driver = nonebot.get_driver()
 

zhenxun/builtin_plugins/hooks/auth/auth_plugin.py

@@ -6,16 +6,13 @@ from nonebot_plugin_uninfo import Uninfo
 
 from zhenxun.models.group_console import GroupConsole
 from zhenxun.models.plugin_info import PluginInfo
-from zhenxun.services.auth_snapshot.exception import (
-    IsSuperuserException,
-    SkipPluginException,
-)
 from zhenxun.services.db_context import DB_TIMEOUT_SECONDS
 from zhenxun.services.log import logger
 from zhenxun.utils.common_utils import CommonUtils
 from zhenxun.utils.enum import BlockType
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD
+from .exception import IsSuperuserException, SkipPluginException
 from .utils import freq, is_poke, send_message
 
 

zhenxun/builtin_plugins/hooks/auth/bot_filter.py

@@ -2,7 +2,8 @@ import nonebot
 from nonebot_plugin_uninfo import Uninfo
 
 from zhenxun.configs.config import Config
-from zhenxun.services.auth_snapshot.exception import SkipPluginException
+
+from .exception import SkipPluginException
 
 Config.add_plugin_config(
     "hook",

zhenxun/builtin_plugins/hooks/auth_checker.py

@@ -0,0 +1,457 @@
+import asyncio
+import time
+
+from nonebot.adapters import Bot, Event
+from nonebot.exception import IgnoredException
+from nonebot.matcher import Matcher
+from nonebot_plugin_alconna import UniMsg
+from nonebot_plugin_uninfo import Uninfo
+from tortoise.exceptions import IntegrityError
+
+from zhenxun.models.group_console import GroupConsole
+from zhenxun.models.plugin_info import PluginInfo
+from zhenxun.models.user_console import UserConsole
+from zhenxun.services.data_access import DataAccess
+from zhenxun.services.log import logger
+from zhenxun.utils.enum import GoldHandle, PluginType
+from zhenxun.utils.exception import InsufficientGold
+from zhenxun.utils.platform import PlatformUtils
+from zhenxun.utils.utils import get_entity_ids
+
+from .auth.auth_admin import auth_admin
+from .auth.auth_ban import auth_ban
+from .auth.auth_bot import auth_bot
+from .auth.auth_cost import auth_cost
+from .auth.auth_group import auth_group
+from .auth.auth_limit import LimitManager, auth_limit
+from .auth.auth_plugin import auth_plugin
+from .auth.bot_filter import bot_filter
+from .auth.config import LOGGER_COMMAND, WARNING_THRESHOLD
+from .auth.exception import (
+    IsSuperuserException,
+    PermissionExemption,
+    SkipPluginException,
+)
+from .auth.utils import base_config
+
+# 超时设置（秒）
+TIMEOUT_SECONDS = 5.0
+# 熔断计数器
+CIRCUIT_BREAKERS = {
+    "auth_ban": {"failures": 0, "threshold": 3, "active": False, "reset_time": 0},
+    "auth_bot": {"failures": 0, "threshold": 3, "active": False, "reset_time": 0},
+    "auth_group": {"failures": 0, "threshold": 3, "active": False, "reset_time": 0},
+    "auth_admin": {"failures": 0, "threshold": 3, "active": False, "reset_time": 0},
+    "auth_plugin": {"failures": 0, "threshold": 3, "active": False, "reset_time": 0},
+    "auth_limit": {"failures": 0, "threshold": 3, "active": False, "reset_time": 0},
+}
+# 熔断重置时间（秒）
+CIRCUIT_RESET_TIME = 300  # 5分钟
+
+# 并发控制：限制同时进入 hooks 并行检查的协程数
+
+# 默认为 6，可通过环境变量 AUTH_HOOKS_CONCURRENCY_LIMIT 调整
+HOOKS_CONCURRENCY_LIMIT = base_config.get("AUTH_HOOKS_CONCURRENCY_LIMIT")
+
+# 全局信号量与计数器
+HOOKS_SEMAPHORE = asyncio.Semaphore(HOOKS_CONCURRENCY_LIMIT)
+HOOKS_ACTIVE_COUNT = 0
+HOOKS_ACTIVE_LOCK = asyncio.Lock()
+
+
+# 超时装饰器
+async def with_timeout(coro, timeout=TIMEOUT_SECONDS, name=None):
+    """带超时控制的协程执行
+
+    参数:
+        coro: 要执行的协程
+        timeout: 超时时间（秒）
+        name: 操作名称，用于日志记录
+
+    返回:
+        协程的返回值，或者在超时时抛出 TimeoutError
+    """
+    try:
+        return await asyncio.wait_for(coro, timeout=timeout)
+    except asyncio.TimeoutError:
+        if name:
+            logger.error(f"{name} 操作超时 (>{timeout}s)", LOGGER_COMMAND)
+            # 更新熔断计数器
+            if name in CIRCUIT_BREAKERS:
+                CIRCUIT_BREAKERS[name]["failures"] += 1
+                if (
+                    CIRCUIT_BREAKERS[name]["failures"]
+                    >= CIRCUIT_BREAKERS[name]["threshold"]
+                    and not CIRCUIT_BREAKERS[name]["active"]
+                ):
+                    CIRCUIT_BREAKERS[name]["active"] = True
+                    CIRCUIT_BREAKERS[name]["reset_time"] = (
+                        time.time() + CIRCUIT_RESET_TIME
+                    )
+                    logger.warning(
+                        f"{name} 熔断器已激活，将在 {CIRCUIT_RESET_TIME} 秒后重置",
+                        LOGGER_COMMAND,
+                    )
+        raise
+
+
+# 检查熔断状态
+def check_circuit_breaker(name):
+    """检查熔断器状态
+
+    参数:
+        name: 操作名称
+
+    返回:
+        bool: 是否已熔断
+    """
+    if name not in CIRCUIT_BREAKERS:
+        return False
+
+    # 检查是否需要重置熔断器
+    if (
+        CIRCUIT_BREAKERS[name]["active"]
+        and time.time() > CIRCUIT_BREAKERS[name]["reset_time"]
+    ):
+        CIRCUIT_BREAKERS[name]["active"] = False
+        CIRCUIT_BREAKERS[name]["failures"] = 0
+        logger.info(f"{name} 熔断器已重置", LOGGER_COMMAND)
+
+    return CIRCUIT_BREAKERS[name]["active"]
+
+
+async def get_plugin_and_user(
+    module: str, user_id: str
+) -> tuple[PluginInfo, UserConsole]:
+    """获取用户数据和插件信息
+
+    参数:
+        module: 模块名
+        user_id: 用户id
+
+    异常:
+        PermissionExemption: 插件数据不存在
+        PermissionExemption: 插件类型为HIDDEN
+        PermissionExemption: 重复创建用户
+        PermissionExemption: 用户数据不存在
+
+    返回:
+        tuple[PluginInfo, UserConsole]: 插件信息，用户信息
+    """
+    user_dao = DataAccess(UserConsole)
+    plugin_dao = DataAccess(PluginInfo)
+
+    # 并行查询插件和用户数据
+    plugin_task = plugin_dao.safe_get_or_none(module=module)
+    user_task = user_dao.get_by_func_or_none(
+        UserConsole.get_user, False, user_id=user_id
+    )
+
+    try:
+        plugin, user = await with_timeout(
+            asyncio.gather(plugin_task, user_task), name="get_plugin_and_user"
+        )
+    except asyncio.TimeoutError:
+        # 如果并行查询超时，尝试串行查询
+        logger.warning("并行查询超时，尝试串行查询", LOGGER_COMMAND)
+        plugin = await with_timeout(
+            plugin_dao.safe_get_or_none(module=module), name="get_plugin"
+        )
+        user = await with_timeout(
+            user_dao.safe_get_or_none(user_id=user_id), name="get_user"
+        )
+    except IntegrityError:
+        await asyncio.sleep(0.5)
+        plugin_task = plugin_dao.safe_get_or_none(module=module)
+        user_task = user_dao.get_by_func_or_none(
+            UserConsole.get_user, False, user_id=user_id
+        )
+        plugin, user = await with_timeout(
+            asyncio.gather(plugin_task, user_task), name="get_plugin_and_user"
+        )
+
+    if not plugin:
+        raise PermissionExemption(f"插件:{module} 数据不存在，已跳过权限检查...")
+    if plugin.plugin_type == PluginType.HIDDEN:
+        raise PermissionExemption(
+            f"插件: {plugin.name}:{plugin.module} 为HIDDEN，已跳过权限检查..."
+        )
+    user = None
+    try:
+        user = await user_dao.get_by_func_or_none(
+            UserConsole.get_user, False, user_id=user_id
+        )
+    except IntegrityError as e:
+        raise PermissionExemption("重复创建用户，已跳过该次权限检查...") from e
+    if not user:
+        raise PermissionExemption("用户数据不存在，已跳过权限检查...")
+    return plugin, user
+
+
+async def get_plugin_cost(
+    bot: Bot, user: UserConsole, plugin: PluginInfo, session: Uninfo
+) -> int:
+    """获取插件费用
+
+    参数:
+        bot: Bot
+        user: 用户数据
+        plugin: 插件数据
+        session: Uninfo
+
+    异常:
+        IsSuperuserException: 超级用户
+        IsSuperuserException: 超级用户
+
+    返回:
+        int: 调用插件金币费用
+    """
+    cost_gold = await with_timeout(auth_cost(user, plugin, session), name="auth_cost")
+    if session.user.id in bot.config.superusers:
+        if plugin.plugin_type == PluginType.SUPERUSER:
+            raise IsSuperuserException()
+        if not plugin.limit_superuser:
+            raise IsSuperuserException()
+    return cost_gold
+
+
+async def reduce_gold(user_id: str, module: str, cost_gold: int, session: Uninfo):
+    """扣除用户金币
+
+    参数:
+        user_id: 用户id
+        module: 插件模块名称
+        cost_gold: 消耗金币
+        session: Uninfo
+    """
+    user_dao = DataAccess(UserConsole)
+    try:
+        await with_timeout(
+            UserConsole.reduce_gold(
+                user_id,
+                cost_gold,
+                GoldHandle.PLUGIN,
+                module,
+                PlatformUtils.get_platform(session),
+            ),
+            name="reduce_gold",
+        )
+    except InsufficientGold:
+        if u := await UserConsole.get_user(user_id):
+            u.gold = 0
+            await u.save(update_fields=["gold"])
+    except asyncio.TimeoutError:
+        logger.error(
+            f"扣除金币超时，用户: {user_id}, 金币: {cost_gold}",
+            LOGGER_COMMAND,
+            session=session,
+        )
+
+    # 清除缓存，使下次查询时从数据库获取最新数据
+    await user_dao.clear_cache(user_id=user_id)
+    logger.debug(f"调用功能花费金币: {cost_gold}", LOGGER_COMMAND, session=session)
+
+
+# 辅助函数，用于记录每个 hook 的执行时间
+async def time_hook(coro, name, time_dict):
+    start = time.time()
+    try:
+        # 检查熔断状态
+        if check_circuit_breaker(name):
+            logger.info(f"{name} 熔断器激活中，跳过执行", LOGGER_COMMAND)
+            time_dict[name] = "熔断跳过"
+            return
+
+        # 添加超时控制
+        return await with_timeout(coro, name=name)
+    except asyncio.TimeoutError:
+        time_dict[name] = f"超时 (>{TIMEOUT_SECONDS}s)"
+    finally:
+        if name not in time_dict:
+            time_dict[name] = f"{time.time() - start:.3f}s"
+
+
+async def _enter_hooks_section():
+    """尝试获取全局信号量并更新计数器，超时则抛出 PermissionExemption。"""
+    global HOOKS_ACTIVE_COUNT
+    # 队列模式：如果达到上限，协程将排队等待直到获取到信号量
+    await HOOKS_SEMAPHORE.acquire()
+    async with HOOKS_ACTIVE_LOCK:
+        HOOKS_ACTIVE_COUNT += 1
+        logger.debug(f"当前并发权限检查数量: {HOOKS_ACTIVE_COUNT}", LOGGER_COMMAND)
+
+
+async def _leave_hooks_section():
+    """释放信号量并更新计数器。"""
+    global HOOKS_ACTIVE_COUNT
+    from contextlib import suppress
+
+    with suppress(Exception):
+        HOOKS_SEMAPHORE.release()
+    async with HOOKS_ACTIVE_LOCK:
+        HOOKS_ACTIVE_COUNT -= 1
+        # 保证计数不为负
+        HOOKS_ACTIVE_COUNT = max(HOOKS_ACTIVE_COUNT, 0)
+        logger.debug(f"当前并发权限检查数量: {HOOKS_ACTIVE_COUNT}", LOGGER_COMMAND)
+
+
+async def auth(
+    matcher: Matcher,
+    event: Event,
+    bot: Bot,
+    session: Uninfo,
+    message: UniMsg,
+):
+    """权限检查
+
+    参数:
+        matcher: matcher
+        event: Event
+        bot: bot
+        session: Uninfo
+        message: UniMsg
+    """
+    start_time = time.time()
+    cost_gold = 0
+    ignore_flag = False
+    entity = get_entity_ids(session)
+    module = matcher.plugin_name or ""
+
+    # 用于记录各个 hook 的执行时间
+    hook_times = {}
+    hooks_time = 0  # 初始化 hooks_time 变量
+
+    # 记录是否已进入 hooks 区域（用于 finally 中释放）
+    entered_hooks = False
+
+    try:
+        if not module:
+            raise PermissionExemption("Matcher插件名称不存在...")
+
+        # 获取插件和用户数据
+        plugin_user_start = time.time()
+        try:
+            plugin, user = await with_timeout(
+                get_plugin_and_user(module, entity.user_id), name="get_plugin_and_user"
+            )
+            hook_times["get_plugin_user"] = f"{time.time() - plugin_user_start:.3f}s"
+        except asyncio.TimeoutError:
+            logger.error(
+                f"获取插件和用户数据超时，模块: {module}",
+                LOGGER_COMMAND,
+                session=session,
+            )
+            raise PermissionExemption("获取插件和用户数据超时，请稍后再试...")
+
+        # 进入 hooks 并行检查区域（会在高并发时排队）
+        await _enter_hooks_section()
+        entered_hooks = True
+
+        # 获取插件费用
+        cost_start = time.time()
+        try:
+            cost_gold = await with_timeout(
+                get_plugin_cost(bot, user, plugin, session), name="get_plugin_cost"
+            )
+            hook_times["cost_gold"] = f"{time.time() - cost_start:.3f}s"
+        except asyncio.TimeoutError:
+            logger.error(
+                f"获取插件费用超时，模块: {module}", LOGGER_COMMAND, session=session
+            )
+            # 继续执行，不阻止权限检查
+
+        # 执行 bot_filter
+        bot_filter(session)
+
+        group = None
+        if entity.group_id:
+            group_dao = DataAccess(GroupConsole)
+            group = await with_timeout(
+                group_dao.safe_get_or_none(
+                    group_id=entity.group_id, channel_id__isnull=True
+                ),
+                name="get_group",
+            )
+
+        # 并行执行所有 hook 检查，并记录执行时间
+        hooks_start = time.time()
+
+        # 创建所有 hook 任务
+        hook_tasks = [
+            time_hook(auth_ban(matcher, bot, session, plugin), "auth_ban", hook_times),
+            time_hook(auth_bot(plugin, bot.self_id), "auth_bot", hook_times),
+            time_hook(
+                auth_group(plugin, group, message, entity.group_id),
+                "auth_group",
+                hook_times,
+            ),
+            time_hook(auth_admin(plugin, session), "auth_admin", hook_times),
+            time_hook(
+                auth_plugin(plugin, group, session, event), "auth_plugin", hook_times
+            ),
+            time_hook(auth_limit(plugin, session), "auth_limit", hook_times),
+        ]
+
+        # 使用 gather 并行执行所有 hook，但添加总体超时控制
+        try:
+            await with_timeout(
+                asyncio.gather(*hook_tasks),
+                timeout=TIMEOUT_SECONDS * 2,  # 给总体执行更多时间
+                name="auth_hooks_gather",
+            )
+        except asyncio.TimeoutError:
+            logger.error(
+                f"权限检查 hooks 总体执行超时，模块: {module}",
+                LOGGER_COMMAND,
+                session=session,
+            )
+            # 不抛出异常，允许继续执行
+
+        hooks_time = time.time() - hooks_start
+
+    except SkipPluginException as e:
+        LimitManager.unblock(module, entity.user_id, entity.group_id, entity.channel_id)
+        logger.info(str(e), LOGGER_COMMAND, session=session)
+        ignore_flag = True
+    except IsSuperuserException:
+        logger.debug("超级用户跳过权限检测...", LOGGER_COMMAND, session=session)
+    except PermissionExemption as e:
+        logger.info(str(e), LOGGER_COMMAND, session=session)
+    finally:
+        # 如果进入过 hooks 区域，确保释放信号量（即使上层处理抛出了异常）
+        if entered_hooks:
+            try:
+                await _leave_hooks_section()
+            except Exception:
+                logger.error(
+                    "释放 hooks 信号量时出错",
+                    LOGGER_COMMAND,
+                    session=session,
+                )
+    # 扣除金币
+    if not ignore_flag and cost_gold > 0:
+        gold_start = time.time()
+        try:
+            await with_timeout(
+                reduce_gold(entity.user_id, module, cost_gold, session),
+                name="reduce_gold",
+            )
+            hook_times["reduce_gold"] = f"{time.time() - gold_start:.3f}s"
+        except asyncio.TimeoutError:
+            logger.error(
+                f"扣除金币超时，模块: {module}", LOGGER_COMMAND, session=session
+            )
+
+    # 记录总执行时间
+    total_time = time.time() - start_time
+    if total_time > WARNING_THRESHOLD:  # 如果总时间超过500ms，记录详细信息
+        logger.warning(
+            f"权限检查耗时过长: {total_time:.3f}s, 模块: {module}, "
+            f"hooks时间: {hooks_time:.3f}s, "
+            f"详情: {hook_times}",
+            LOGGER_COMMAND,
+            session=session,
+        )
+
+    if ignore_flag:
+        raise IgnoredException("权限检测 ignore")

zhenxun/builtin_plugins/hooks/auth_checker_v2.py

@@ -1,45 +0,0 @@
-"""
-优化后的权限检查系统入口 (V2)
-
-主要改进：
-1. 使用预聚合的权限快照，将查询次数从6-10次降低到1-2次
-2. 本地内存缓存 + Redis缓存双层结构
-3. 所有权限检查基于内存数据，无额外I/O
-
-使用方式：
-1. 在 hooks/__init__.py 中将 auth_checker 替换为 auth_checker_v2
-2. 或者通过配置开关选择使用哪个版本
-
-性能对比：
-- 原版本：6-10次查询，平均延迟~50ms
-- V2版本：1-2次查询，平均延迟~10ms
-"""
-
-import nonebot
-
-from zhenxun.services.auth_snapshot import (
-    AuthSnapshotService,
-    PluginSnapshotService,
-)
-from zhenxun.services.log import logger
-from zhenxun.utils.manager.priority_manager import PriorityLifecycle
-
-driver = nonebot.get_driver()
-
-
-# 启动时预热插件缓存
-@PriorityLifecycle.on_startup(priority=10)
-async def _warmup_plugin_cache():
-    """预热插件快照缓存"""
-    logger.info("开始预热插件快照缓存...", "auth_checker_v2")
-    await PluginSnapshotService.warmup()
-    logger.info("插件快照缓存预热完成", "auth_checker_v2")
-
-
-# 关闭时清理缓存
-@driver.on_shutdown
-async def _cleanup_cache():
-    """清理快照缓存"""
-    AuthSnapshotService.clear_all_cache()
-    PluginSnapshotService.clear_all_cache()
-    logger.info("快照缓存已清理", "auth_checker_v2")

zhenxun/builtin_plugins/hooks/auth_hook.py

@@ -1,47 +1,28 @@
 import time
 
 from nonebot.adapters import Bot, Event
-from nonebot.exception import IgnoredException
 from nonebot.matcher import Matcher
 from nonebot.message import run_postprocessor, run_preprocessor
 from nonebot_plugin_alconna import UniMsg
 from nonebot_plugin_uninfo import Uninfo
 
-from zhenxun.services.auth_snapshot.checker import optimized_auth_checker
-from zhenxun.services.auth_snapshot.exception import (
-    PermissionExemption,
-    SkipPluginException,
-)
 from zhenxun.services.log import logger
 
-from .auth.auth_limit import LimitManager
 from .auth.config import LOGGER_COMMAND
+from .auth_checker import LimitManager, auth
 
 
 # # 权限检测
 @run_preprocessor
 async def _(matcher: Matcher, event: Event, bot: Bot, session: Uninfo, message: UniMsg):
     start_time = time.time()
-    # await _auth_checker.check(
+    await auth(
-    #     matcher,
+        matcher,
-    #     event,
+        event,
-    #     bot,
+        bot,
-    #     session,
+        session,
-    #     message,
+        message,
-    # )
+    )
-    try:
-        await optimized_auth_checker.check(matcher, event, bot, session, message)
-    except SkipPluginException as e:
-        logger.info(str(e), LOGGER_COMMAND, session=session)
-        raise IgnoredException(str(e))
-    except PermissionExemption as e:
-        logger.info(
-            str(e) or "超级用户跳过权限检测...", LOGGER_COMMAND, session=session
-        )
-        raise IgnoredException(str(e))
-    except Exception as e:
-        logger.error(f"权限检测异常: {e}", LOGGER_COMMAND, session=session, e=e)
-        raise SkipPluginException("权限检测异常") from e
     logger.debug(f"权限检测耗时：{time.time() - start_time}秒", LOGGER_COMMAND)
 
 

zhenxun/builtin_plugins/init/__init_cache.py

@@ -7,11 +7,9 @@
 from zhenxun.models.ban_console import BanConsole
 from zhenxun.models.bot_console import BotConsole
 from zhenxun.models.group_console import GroupConsole
-from zhenxun.models.group_plugin_setting import GroupPluginSetting
 from zhenxun.models.level_user import LevelUser
 from zhenxun.models.plugin_info import PluginInfo
 from zhenxun.models.user_console import UserConsole
-from zhenxun.services.auth_snapshot import AuthSnapshot, PluginSnapshot
 from zhenxun.services.cache import CacheRegistry, cache_config
 from zhenxun.services.cache.config import CacheMode
 from zhenxun.services.log import logger
@@ -25,18 +23,10 @@ def register_cache_types():
     CacheRegistry.register(CacheType.GROUPS, GroupConsole)
     CacheRegistry.register(CacheType.BOT, BotConsole)
     CacheRegistry.register(CacheType.USERS, UserConsole)
-    CacheRegistry.register(
-        CacheType.GROUP_PLUGIN_SETTINGS,
-        GroupPluginSetting,
-        key_format="{group_id}_{plugin_name}_{key}",
-    )
     CacheRegistry.register(
         CacheType.LEVEL, LevelUser, key_format="{user_id}_{group_id}"
     )
     CacheRegistry.register(CacheType.BAN, BanConsole, key_format="{user_id}_{group_id}")
-    CacheRegistry.register(CacheType.TEMP, None, 3600)
-    CacheRegistry.register(CacheType.AUTH_SNAPSHOT, AuthSnapshot)
-    CacheRegistry.register(CacheType.PLUGIN_SNAPSHOT, PluginSnapshot)
 
     if cache_config.cache_mode == CacheMode.NONE:
         logger.info("缓存功能已禁用，将直接从数据库获取数据")

zhenxun/builtin_plugins/mmm.py

@@ -1,59 +0,0 @@
-import asyncio
-import random
-
-from arclet.alconna import Args
-from nonebot import get_driver
-from nonebot.adapters.onebot.v11 import (
-    Bot,
-    Event,
-    GroupMessageEvent,
-    Message,
-    PrivateMessageEvent,
-)
-from nonebot.compat import model_dump, type_validate_python
-from nonebot_plugin_alconna import Alconna, on_alconna
-
-from zhenxun.services.log import logger
-
-tasks: set["asyncio.Task"] = set()
-
-
-@get_driver().on_shutdown
-async def cancel_tasks():
-    for task in tasks:
-        if not task.done():
-            task.cancel()
-
-    await asyncio.gather(
-        *(asyncio.wait_for(task, timeout=10) for task in tasks),
-        return_exceptions=True,
-    )
-
-
-def push_event(bot: Bot, event: PrivateMessageEvent | GroupMessageEvent):
-    event.message = Message("签到")
-    event.user_id = random.randint(1, 99999999999) + random.randint(1, 99999999999)
-    task = asyncio.create_task(bot.handle_event(event))
-    task.add_done_callback(tasks.discard)
-    tasks.add(task)
-    logger.info(f"发送消息 --> {event.user_id} {event.message}")
-    return event
-
-
-_matcher = on_alconna(
-    Alconna("test", Args["n", int]), priority=5, block=True, temp=True
-)
-
-
-@_matcher.handle()
-async def handle_event(event: Event, bot: Bot, n: int):
-    for _ in range(n):
-        data = model_dump(event)
-        if data.get("message_type") == "private":
-            data["post_type"] = "message"
-            push_event(bot, type_validate_python(PrivateMessageEvent, data))
-        elif data.get("message_type") == "group":
-            data["post_type"] = "message"
-            push_event(bot, type_validate_python(GroupMessageEvent, data))
-        await asyncio.sleep(0.1)
-        logger.info(f"发送消息次数 --> {_ + 1}")

zhenxun/builtin_plugins/platform/qq/group_handle/__init__.py

@@ -17,8 +17,6 @@ from zhenxun.configs.utils import PluginExtraData, RegisterConfig, Task
 from zhenxun.models.event_log import EventLog
 from zhenxun.models.group_console import GroupConsole
 from zhenxun.services.cache import CacheRoot
-from zhenxun.services.log import logger
-from zhenxun.services.tags import tag_manager
 from zhenxun.utils.common_utils import CommonUtils
 from zhenxun.utils.enum import EventLogType, PluginType
 from zhenxun.utils.platform import PlatformUtils
@@ -137,11 +135,6 @@ async def _(
         await EventLog.create(
             user_id=user_id, group_id=group_id, event_type=EventLogType.KICK_BOT
         )
-        await tag_manager.remove_group_from_all_tags(group_id)
-        logger.info(
-            f"机器人被移出群聊，已自动从所有静态标签中移除群组 {group_id}",
-            "群组标签管理",
-        )
     elif event.sub_type in ["leave", "kick"]:
         if event.sub_type == "leave":
             """主动退群"""

zhenxun/builtin_plugins/scheduler/auto_update_group.py

@@ -2,7 +2,6 @@ import nonebot
 from nonebot_plugin_apscheduler import scheduler
 
 from zhenxun.services.log import logger
-from zhenxun.services.tags import tag_manager
 from zhenxun.utils.platform import PlatformUtils
 
 
@@ -38,20 +37,3 @@ async def _():
                 f"Bot: {bot.self_id} 自动更新好友信息错误", "自动更新好友", e=e
             )
     logger.info("自动更新好友信息成功...")
-
-
-# 自动清理静态标签中的无效群组
-@scheduler.scheduled_job(
-    "cron",
-    hour=23,
-    minute=30,
-)
-async def _prune_stale_tags():
-    deleted_count = await tag_manager.prune_stale_group_links()
-    if deleted_count > 0:
-        logger.info(
-            f"定时任务：成功清理了 {deleted_count} 个无效的群组标签" f"关联。",
-            "群组标签管理",
-        )
-    else:
-        logger.debug("定时任务：未发现无效的群组标签关联。", "群组标签管理")

zhenxun/builtin_plugins/superuser/bot_manage/__init__.py

@@ -3,7 +3,6 @@ from typing import cast
 import nonebot
 from nonebot.adapters import Bot
 from nonebot.plugin import PluginMetadata
-from tortoise.exceptions import IntegrityError
 
 from zhenxun.configs.utils import PluginExtraData
 from zhenxun.models.bot_console import BotConsole
@@ -73,17 +72,9 @@ async def init_bot_console(bot: Bot):
         list[str], await TaskInfo.filter(status=True).values_list("module", flat=True)
     )
     platform = PlatformUtils.get_platform(bot)
-
+    bot_data, created = await BotConsole.get_or_create(
-    try:
+        bot_id=bot.self_id, platform=platform
-        bot_data = await BotConsole.create(
+    )
-            bot_id=bot.self_id,
-            platform=platform,
-        )
-        created = True
-
-    except IntegrityError:
-        bot_data = await BotConsole.get(bot_id=bot.self_id)
-        created = False
 
     if not created:
         task_list = await _filter_blocked_items(

zhenxun/builtin_plugins/superuser/plugin_config_manager.py

@@ -1,581 +0,0 @@
-from typing import Any
-
-from arclet.alconna.typing import KeyWordVar
-import nonebot
-from nonebot.adapters import Bot, Event
-from nonebot.compat import model_fields
-from nonebot.exception import SkippedException
-from nonebot.permission import SUPERUSER
-from nonebot.plugin import PluginMetadata
-from nonebot_plugin_alconna import (
-    Alconna,
-    Args,
-    Arparma,
-    Match,
-    MultiVar,
-    Option,
-    Subcommand,
-    on_alconna,
-    store_true,
-)
-from nonebot_plugin_session import EventSession
-from pydantic import BaseModel, ValidationError
-
-from zhenxun.configs.config import Config
-from zhenxun.configs.utils import PluginExtraData, RegisterConfig
-from zhenxun.services import group_settings_service, renderer_service
-from zhenxun.services.log import logger
-from zhenxun.services.tags import tag_manager
-from zhenxun.ui import builders as ui
-from zhenxun.utils.enum import PluginType
-from zhenxun.utils.message import MessageUtils
-from zhenxun.utils.platform import PlatformUtils
-from zhenxun.utils.pydantic_compat import parse_as
-from zhenxun.utils.rules import admin_check
-
-__plugin_meta__ = PluginMetadata(
-    name="插件配置管理",
-    description="一个统一的命令，用于管理所有插件的分群配置",
-    usage="""
-### ⚙️ 插件配置管理 (pconf)
----
-一个统一的命令，用于管理所有插件的分群或全局配置。
-
-#### **📖 命令格式**
-`pconf <子命令> [参数] [选项]`
-
-#### **🎯 目标选项 (互斥)**
--   `-g, --group <群号...>`: 指定一个或多个群组ID **(SUPERUSER)**
--   `-t, --tag <标签名>`: 指定一个群组标签 **(SUPERUSER)**
--   `--all`: 对当前Bot所在的所有群组执行操作 **(SUPERUSER)**
--   `--global`: 操作全局配置 (config.yaml) **(SUPERUSER)**
--   **(无)**: 在群聊中操作时，默认目标为当前群。
-
-#### **📋 子命令列表**
-*   **`list` (或 `ls`)**: 查看列表
-    *   `pconf list`: 查看所有支持分群配置的插件。
-    *   `pconf list -p <插件名>`: 查看指定插件的所有分群可配置项。
-    *   `pconf list -p <插件名> --all`: 查看所有群组对该插件的配置。
-    *   `pconf list -p <插件名> --global`: 查看指定插件的全局可配置项。
-
-*   **`get <配置项>`**: 获取配置值
-    *   `pconf get <配置项> -p <插件名>`: 获取当前群的配置值。
-    *   `pconf get <配置项> -p <插件名> -g <群号>`: 获取指定群的配置值。
-
-*   **`set <key=value...>`**: 设置一个或多个配置值
-    *   `pconf set key1=value1 key2=value2 -p <插件名>`
-
-*   **`reset [配置项]`**: 重置配置为默认值
-    *   `pconf reset -p <插件名>`: 重置当前群该插件的所有配置。
-    *   `pconf reset <配置项> -p <插件名>`: 重置当前群该插件的指定配置项。
-    """,
-    extra=PluginExtraData(
-        author="HibiKier",
-        version="1.0",
-        plugin_type=PluginType.SUPERUSER,
-        configs=[
-            RegisterConfig(
-                module="plugin_config_manager",
-                key="PCONF_ADMIN_LEVEL",
-                value=5,
-                help="管理分群配置的基础权限等级",
-                default_value=5,
-                type=int,
-            ),
-            RegisterConfig(
-                module="plugin_config_manager",
-                key="SHOW_DEFAULT_CONFIG_IN_ALL",
-                value=False,
-                help="在使用 --all 查询时，是否显示配置为默认值的群组",
-                default_value=False,
-                type=bool,
-            ),
-        ],
-    ).to_dict(),
-)
-
-
-pconf_cmd = on_alconna(
-    Alconna(
-        "pconf",
-        Subcommand(
-            "list",
-            alias=["ls"],
-            help_text="查看插件或配置项列表",
-        ),
-        Subcommand(
-            "get",
-            Args["key", str],
-            help_text="获取配置值",
-        ),
-        Subcommand(
-            "set",
-            Args["settings", MultiVar(KeyWordVar(Any))],
-            help_text="设置配置值",
-        ),
-        Subcommand(
-            "reset",
-            Args["key?", str],
-            help_text="重置配置",
-        ),
-        Option("-p|--plugin", Args["plugin_name", str], help_text="指定插件名"),
-        Option("-g|--group", Args["group_ids", MultiVar(str)], help_text="指定群组ID"),
-        Option("-t|--tag", Args["tag_name", str], help_text="指定群组标签"),
-        Option("--all", action=store_true, help_text="操作所有群组"),
-        Option("--global", action=store_true, help_text="操作全局配置"),
-    ),
-    rule=admin_check("plugin_config_manager", "PCONF_ADMIN_LEVEL"),
-    priority=5,
-    block=True,
-)
-
-
-async def get_plugin_config_model(plugin_name: str) -> type[BaseModel] | None:
-    """通过插件名查找其注册的分群配置模型"""
-    for p in nonebot.get_loaded_plugins():
-        if p.name == plugin_name and p.metadata and p.metadata.extra:
-            extra = PluginExtraData(**p.metadata.extra)
-            if extra.group_config_model:
-                return extra.group_config_model
-    return None
-
-
-def truncate_text(text: str, max_len: int) -> str:
-    """截断文本，过长时添加省略号"""
-    if len(text) > max_len:
-        return text[: max_len - 3] + "..."
-    return text
-
-
-async def GetTargets(
-    bot: Bot, event: Event, session: EventSession, arp: Arparma
-) -> list[str]:
-    """
-    依赖注入，根据 -g, -t, --all 或当前会话解析目标群组ID列表，并进行权限检查。
-    """
-    is_superuser = await SUPERUSER(bot, event)
-
-    if group_ids_match := arp.query[list[str]]("group.group_ids"):
-        if not is_superuser:
-            logger.warning(f"非超级用户 {session.id1} 尝试使用 -g 参数。")
-            raise SkippedException("权限不足")
-        return group_ids_match
-
-    if tag_name_match := arp.query[str]("tag.tag_name"):
-        if not is_superuser:
-            logger.warning(f"非超级用户 {session.id1} 尝试使用 -t 参数。")
-            raise SkippedException("权限不足")
-
-        resolved_groups = await tag_manager.resolve_tag_to_group_ids(
-            tag_name_match, bot=bot
-        )
-        if not resolved_groups:
-            await pconf_cmd.finish(f"标签 '{tag_name_match}' 没有匹配到任何群组。")
-        return resolved_groups
-
-    if arp.find("all"):
-        if not is_superuser:
-            logger.warning(f"非超级用户 {session.id1} 尝试使用 --all 参数。")
-            raise SkippedException("权限不足")
-        from zhenxun.utils.platform import PlatformUtils
-
-        all_groups, _ = await PlatformUtils.get_group_list(bot)
-        return [g.group_id for g in all_groups]
-
-    if gid := session.id3 or session.id2:
-        return [gid]
-
-    if not is_superuser:
-        logger.warning(f"管理员 {session.id1} 尝试在私聊中操作分群配置。")
-        raise SkippedException("权限不足")
-
-    await pconf_cmd.finish(
-        "超级用户在私聊中操作时，必须使用 -g <群号>、-t <标签名> 或 --all 指定目标群组"
-    )
-
-
-@pconf_cmd.assign("list")
-async def handle_list(arp: Arparma, bot: Bot, event: Event):
-    """处理 list 子命令"""
-    plugin_name_str = None
-    is_superuser = await SUPERUSER(bot, event)
-    if arp.find("plugin"):
-        plugin_name_str = arp.query[str]("plugin.plugin_name")
-
-    if plugin_name_str:
-        is_global = arp.find("global")
-        is_all_groups = arp.find("all")
-
-        if is_all_groups and not is_global:
-            if not is_superuser:
-                await MessageUtils.build_message(
-                    "只有超级用户才能查看所有群的配置。"
-                ).finish()
-
-            model = await get_plugin_config_model(plugin_name_str)
-            model_fields_list = model_fields(model) if model else []
-            if not model_fields_list:
-                await MessageUtils.build_message(
-                    f"插件 '{plugin_name_str}' 不支持分群配置。"
-                ).finish()
-
-            all_groups, _ = await PlatformUtils.get_group_list(bot)
-            if not all_groups:
-                await MessageUtils.build_message("机器人未加入任何群组。").finish()
-
-            model_fields_dict = {field.name: field for field in model_fields_list}
-            config_keys = list(model_fields_dict.keys())
-            headers = ["群号", "群名称", *config_keys]
-            rows = []
-
-            for group in all_groups:
-                settings_dict = await group_settings_service.get_all_for_plugin(
-                    group.group_id, plugin_name_str
-                )
-                row_data = [group.group_id, truncate_text(group.group_name, 10)]
-                for key in config_keys:
-                    value = settings_dict.get(key)
-                    default_value = model_fields_dict[key].field_info.default
-
-                    if value == default_value:
-                        value_str = "默认"
-                    else:
-                        value_str = str(value) if value is not None else "N/A"
-
-                    row_data.append(truncate_text(value_str, 20))
-
-                show_default = Config.get_config(
-                    "plugin_config_manager", "SHOW_DEFAULT_CONFIG_IN_ALL", False
-                )
-                if not show_default:
-                    is_all_default = all(val == "默认" for val in row_data[2:])
-                    if is_all_default:
-                        continue
-
-                rows.append(row_data)
-
-            builder = ui.TableBuilder(
-                title=f"插件 '{plugin_name_str}' 全群配置",
-                tip=f"共查询 {len(rows)} 个群组",
-            )
-            builder.set_headers(headers).add_rows(rows)
-
-            viewport_width = 300 + len(config_keys) * 280
-            img = await renderer_service.render(
-                builder.build(), viewport={"width": viewport_width, "height": 10}
-            )
-            await MessageUtils.build_message(img).finish()
-
-        if is_global:
-            if not is_superuser:
-                await MessageUtils.build_message(
-                    "只有超级用户才能查看全局配置。"
-                ).finish()
-            config_group = Config.get(plugin_name_str)
-            if not config_group or not config_group.configs:
-                await MessageUtils.build_message(
-                    f"插件 '{plugin_name_str}' 没有可配置的全局项。"
-                ).finish()
-
-            builder = ui.TableBuilder(
-                title=f"插件 '{plugin_name_str}' 全局可配置项",
-                tip=(
-                    f"位于 config.yaml, 使用 pconf set <key>=<value> "
-                    f"-p {plugin_name_str} --global 进行设置"
-                ),
-            )
-            builder.set_headers(["配置项", "当前值", "类型", "描述"])
-
-            for key, config_model in config_group.configs.items():
-                type_name = getattr(
-                    config_model.type, "__name__", str(config_model.type)
-                )
-                builder.add_row(
-                    [
-                        key,
-                        truncate_text(str(config_model.value), 20),
-                        type_name,
-                        truncate_text(config_model.help or "无", 20),
-                    ]
-                )
-
-            img = await renderer_service.render(builder.build())
-            await MessageUtils.build_message(img).finish()
-        else:
-            model = await get_plugin_config_model(plugin_name_str)
-            model_fields_list = model_fields(model) if model else []
-            if not model_fields_list:
-                await MessageUtils.build_message(
-                    f"插件 '{plugin_name_str}' 不支持分群配置。"
-                ).finish()
-
-            builder = ui.TableBuilder(
-                title=f"插件 '{plugin_name_str}' 可配置项",
-                tip=f"使用 pconf set <key>=<value> -p {plugin_name_str} 进行设置",
-            )
-            builder.set_headers(["配置项", "类型", "描述", "默认值"])
-
-            for field in model_fields_list:
-                type_name = getattr(field.annotation, "__name__", str(field.annotation))
-                description = field.field_info.description or "无"
-                default_value = (
-                    str(field.get_default())
-                    if field.field_info.default is not None
-                    else "无"
-                )
-                builder.add_row([field.name, type_name, description, default_value])
-
-            img = await renderer_service.render(builder.build())
-            await MessageUtils.build_message(img).finish()
-
-    else:
-        configurable_plugins = []
-        for p in nonebot.get_loaded_plugins():
-            if p.metadata and p.metadata.extra:
-                extra = PluginExtraData(**p.metadata.extra)
-                if extra.group_config_model:
-                    configurable_plugins.append(p.name)
-
-        if not configurable_plugins:
-            await MessageUtils.build_message("当前没有插件支持分群配置。").finish()
-
-        await MessageUtils.build_message(
-            "支持分群配置的插件列表:\n"
-            + "\n".join(f"- {name}" for name in configurable_plugins)
-        ).finish()
-
-
-@pconf_cmd.assign("get")
-async def handle_get(
-    arp: Arparma,
-    key: Match[str],
-    bot: Bot,
-    event: Event,
-    session: EventSession,
-):
-    if not arp.find("plugin"):
-        await pconf_cmd.finish("必须使用 -p <插件名> 指定要操作的插件。")
-    plugin_name_str = arp.query[str]("plugin.plugin_name")
-    if not plugin_name_str:
-        await pconf_cmd.finish("插件名不能为空。")
-    is_superuser = await SUPERUSER(bot, event)
-
-    if arp.find("global"):
-        if not is_superuser:
-            await MessageUtils.build_message("只有超级用户才能获取全局配置。").finish()
-        value = Config.get_config(plugin_name_str, key.result)
-        await MessageUtils.build_message(
-            f"全局配置项 '{key.result}' 的值为: {value}"
-        ).finish()
-    else:
-        target_group_ids = await GetTargets(bot, event, session, arp)
-        target_group_id = target_group_ids[0]
-        value = await group_settings_service.get(
-            target_group_id, plugin_name_str, key.result
-        )
-        await MessageUtils.build_message(
-            f"群组 {target_group_id} 的配置项 '{key.result}' 的值为: {value}"
-        ).finish()
-
-
-@pconf_cmd.assign("set")
-async def handle_set(
-    arp: Arparma,
-    settings: Match[dict],
-    bot: Bot,
-    event: Event,
-    session: EventSession,
-):
-    if not arp.find("plugin"):
-        await pconf_cmd.finish("必须使用 -p <插件名> 指定要操作的插件。")
-    plugin_name_str = arp.query[str]("plugin.plugin_name")
-    if not plugin_name_str:
-        await pconf_cmd.finish("插件名不能为空。")
-    is_superuser = await SUPERUSER(bot, event)
-
-    is_global = arp.find("global")
-
-    if is_global:
-        if not is_superuser:
-            await MessageUtils.build_message("只有超级用户才能设置全局配置。").finish()
-        config_group = Config.get(plugin_name_str)
-        if not config_group or not config_group.configs:
-            await MessageUtils.build_message(
-                f"插件 '{plugin_name_str}' 没有可配置的全局项。"
-            ).finish()
-
-        changes_made = False
-        success_messages = []
-        for key, value_str in settings.result.items():
-            config_model = config_group.configs.get(key.upper())
-            if not config_model:
-                await MessageUtils.build_message(
-                    f"❌ 全局配置项 '{key}' 不存在。"
-                ).send()
-                continue
-
-            target_type = config_model.type
-            if target_type is None:
-                if config_model.default_value is not None:
-                    target_type = type(config_model.default_value)
-                elif config_model.value is not None:
-                    target_type = type(config_model.value)
-
-            converted_value: Any = value_str
-            if target_type and value_str is not None:
-                try:
-                    converted_value = parse_as(target_type, value_str)
-                except (ValidationError, TypeError, ValueError) as e:
-                    type_name = getattr(target_type, "__name__", str(target_type))
-                    await MessageUtils.build_message(
-                        f"❌ 配置项 '{key}' 的值 '{value_str}' "
-                        f"无法转换为期望的类型 '{type_name}': {e}"
-                    ).send()
-                    continue
-
-            Config.set_config(plugin_name_str, key.upper(), converted_value)
-            success_messages.append(f"  - 配置项 '{key}' 已设置为: `{converted_value}`")
-            changes_made = True
-
-        if changes_made:
-            Config.save(save_simple_data=True)
-            response_msg = (
-                f"✅ 插件 '{plugin_name_str}' 的全局配置已更新:\n"
-                + "\n".join(success_messages)
-            )
-            await MessageUtils.build_message(response_msg).finish()
-    else:
-        model = await get_plugin_config_model(plugin_name_str)
-        if not model:
-            await MessageUtils.build_message(
-                f"插件 '{plugin_name_str}' 不支持分群配置。"
-            ).finish()
-
-        target_group_ids = await GetTargets(bot, event, session, arp)
-        model_fields_map = {field.name: field for field in model_fields(model)}
-
-        success_groups = []
-        failed_groups = []
-        update_details = []
-
-        for group_id in target_group_ids:
-            for key, value_str in settings.result.items():
-                field = model_fields_map.get(key)
-                if not field:
-                    await MessageUtils.build_message(
-                        f"配置项 '{key}' 在插件 '{plugin_name_str}' 中不存在。"
-                    ).finish()
-
-                try:
-                    validated_value = (
-                        parse_as(field.annotation, value_str)
-                        if field.annotation is not None
-                        else value_str
-                    )
-                    await group_settings_service.set_key_value(
-                        group_id, plugin_name_str, key, validated_value
-                    )
-                    if group_id not in success_groups:
-                        success_groups.append(group_id)
-
-                    if (key, validated_value) not in update_details:
-                        update_details.append((key, validated_value))
-                except (ValidationError, TypeError, ValueError) as e:
-                    failed_groups.append(
-                        (group_id, f"配置项 '{key}' 值 '{value_str}' 类型错误: {e}")
-                    )
-                except Exception as e:
-                    failed_groups.append((group_id, f"内部错误: {e}"))
-
-        if len(target_group_ids) == 1:
-            group_id = target_group_ids[0]
-            if group_id in success_groups and group_id not in [
-                g[0] for g in failed_groups
-            ]:
-                settings_summary = [
-                    f"  - '{k}' 已设置为: `{v}`" for k, v in update_details
-                ]
-                msg = (
-                    f"✅ 群组 {group_id} 插件 '{plugin_name_str}' 配置更新成功:\n"
-                    + "\n".join(settings_summary)
-                )
-            else:
-                errors = [f[1] for f in failed_groups if f[0] == group_id]
-                msg = (
-                    f"❌ 群组 {group_id} 插件 '{plugin_name_str}' 配置更新失败:\n"
-                    + "\n".join(errors)
-                )
-        else:
-            settings_count = len(settings.result)
-            msg = (
-                f"✅ 批量为 {len(success_groups)} 个群组设置了 "
-                f"{settings_count} 个配置项。"
-            )
-            if failed_groups:
-                failed_count = len({g[0] for g in failed_groups})
-                msg += f"\n❌ 其中 {failed_count} 个群组部分或全部设置失败。"
-
-        await MessageUtils.build_message(msg).finish()
-
-
-@pconf_cmd.assign("reset")
-async def handle_reset(
-    arp: Arparma,
-    key: Match[str],
-    bot: Bot,
-    event: Event,
-    session: EventSession,
-):
-    if not arp.find("plugin"):
-        await pconf_cmd.finish("必须使用 -p <插件名> 指定要操作的插件。")
-    plugin_name_str = arp.query[str]("plugin.plugin_name")
-    if not plugin_name_str:
-        await pconf_cmd.finish("插件名不能为空。")
-    is_superuser = await SUPERUSER(bot, event)
-
-    if arp.find("global"):
-        if not is_superuser:
-            await MessageUtils.build_message("只有超级用户才能重置全局配置。").finish()
-        await MessageUtils.build_message("全局配置重置功能暂未实现。").finish()
-    else:
-        target_group_ids = await GetTargets(bot, event, session, arp)
-        key_str = key.result if key.available else None
-
-        success_groups = []
-        failed_groups = []
-
-        for group_id in target_group_ids:
-            try:
-                if key_str:
-                    await group_settings_service.reset_key(
-                        group_id, plugin_name_str, key_str
-                    )
-                else:
-                    await group_settings_service.reset_all_for_plugin(
-                        group_id, plugin_name_str
-                    )
-                success_groups.append(group_id)
-            except Exception as e:
-                failed_groups.append((group_id, str(e)))
-
-        action = f"配置项 '{key_str}'" if key_str else "所有配置"
-
-        if len(target_group_ids) == 1:
-            if success_groups:
-                msg = (
-                    f"✅ 群组 {target_group_ids[0]} 中插件 '{plugin_name_str}' "
-                    f"的 {action} 已成功重置。"
-                )
-            else:
-                msg = (
-                    f"❌ 群组 {target_group_ids[0]} 中插件 '{plugin_name_str}' "
-                    f"的 {action} 重置失败: {failed_groups[0][1]}"
-                )
-        else:
-            msg = (
-                f"✅ 批量操作完成: 成功为 {len(success_groups)} 个群组重置了 {action}。"
-            )
-            if failed_groups:
-                failed_count = len({g[0] for g in failed_groups})
-                msg += f"\n❌ 其中 {failed_count} 个群组操作失败。"
-        await MessageUtils.build_message(msg).finish()

zhenxun/builtin_plugins/superuser/reload_setting.py

@@ -7,8 +7,6 @@ from nonebot_plugin_session import EventSession
 
 from zhenxun.configs.config import Config
 from zhenxun.configs.utils import PluginExtraData, RegisterConfig
-from zhenxun.services.llm.config.providers import get_llm_config
-from zhenxun.services.llm.manager import clear_model_cache
 from zhenxun.services.log import logger
 from zhenxun.utils.enum import PluginType
 from zhenxun.utils.message import MessageUtils
@@ -56,8 +54,6 @@ _matcher = on_alconna(
 @_matcher.handle()
 async def _(session: EventSession, arparma: Arparma):
     Config.reload()
-    get_llm_config.cache_clear()
-    clear_model_cache()
     logger.debug("自动重载配置文件", arparma.header_result, session=session)
     await MessageUtils.build_message("重载完成!").send(reply_to=True)
 
@@ -69,6 +65,4 @@ async def _(session: EventSession, arparma: Arparma):
 async def _():
     if Config.get_config("reload_setting", "AUTO_RELOAD"):
         Config.reload()
-        get_llm_config.cache_clear()
-        clear_model_cache()
         logger.debug("已自动重载配置文件...")

zhenxun/builtin_plugins/superuser/tag_manage.py

@@ -176,7 +176,6 @@ tag_cmd = on_alconna(
             help_text="删除标签",
         ),
         Subcommand("clear", help_text="清空所有标签"),
-        Subcommand("prune", alias=["check", "清理"], help_text="清理无效的群组关联"),
         Subcommand(
             "clone",
             Args["source_name", str]["new_name", str],
@@ -193,13 +192,6 @@ tag_cmd = on_alconna(
     block=True,
 )
 
-tag_cmd.shortcut(
-    "清理标签",
-    command="tag",
-    arguments=["prune"],
-    prefix=True,
-)
-
 
 @tag_cmd.assign("list")
 async def handle_list():
@@ -474,10 +466,3 @@ async def handle_clone(
         await MessageUtils.build_message(msg).finish()
     except (ValueError, IntegrityError) as e:
         await MessageUtils.build_message(f"克隆失败: {e}").finish()
-
-
-@tag_cmd.assign("prune")
-async def handle_prune():
-    deleted_count = await tag_manager.prune_stale_group_links()
-    msg = f"清理完成！共移除了 {deleted_count} 个无效的群组关联。"
-    await MessageUtils.build_message(msg).finish()

zhenxun/configs/utils/models.py

@@ -270,9 +270,3 @@ class PluginExtraData(BaseModel):
 
     def to_dict(self, **kwargs):
         return model_dump(self, **kwargs)
-
-    group_config_model: type[BaseModel] | None = None
-    """插件的分群配置模型"""
-
-    class Config:
-        arbitrary_types_allowed = True

zhenxun/models/ban_console.py

@@ -1,12 +1,9 @@
-import asyncio
 import time
 from typing import ClassVar
 from typing_extensions import Self
 
 from tortoise import fields
-from tortoise.expressions import Q
 
-from zhenxun.services.cache import CacheRoot
 from zhenxun.services.data_access import DataAccess
 from zhenxun.services.db_context import Model
 from zhenxun.services.log import logger
@@ -31,7 +28,6 @@ class BanConsole(Model):
     """ban时长"""
     operator = fields.CharField(255)
     """使用Ban命令的用户"""
-    _inflight: ClassVar[dict[tuple[str | None, str | None], asyncio.Future]] = {}
 
     class Meta:  # pyright: ignore [reportIncompatibleVariableOverride]
         table = "ban_console"
@@ -43,43 +39,34 @@ class BanConsole(Model):
     """缓存类型"""
     cache_key_field = ("user_id", "group_id")
     """缓存键字段"""
-    lock_fields: ClassVar[dict[DbLockType, tuple[str, str]]] = {
+    enable_lock: ClassVar[list[DbLockType]] = [DbLockType.CREATE, DbLockType.UPSERT]
-        DbLockType.CREATE: ("user_id", "group_id"),
+    """开启锁"""
-        DbLockType.UPSERT: ("user_id", "group_id"),
-    }
 
     @classmethod
     async def _get_data(cls, user_id: str | None, group_id: str | None) -> Self | None:
+        """获取数据
+
+        参数:
+            user_id: 用户id
+            group_id: 群组id
+
+        异常:
+            UserAndGroupIsNone: 用户id和群组id都为空
+
+        返回:
+            Self | None: Self
+        """
         if not user_id and not group_id:
             raise UserAndGroupIsNone()
-
+        dao = DataAccess(cls)
-        key = (user_id, group_id)
+        if user_id:
-        future = cls._inflight.get(key)
+            return (
-        if future:
+                await dao.safe_get_or_none(user_id=user_id, group_id=group_id)
-            return await future
+                if group_id
-
+                else await dao.safe_get_or_none(user_id=user_id, group_id__isnull=True)
-        loop = asyncio.get_running_loop()
+            )
-        future = loop.create_future()
+        else:
-        cls._inflight[key] = future
+            return await dao.safe_get_or_none(user_id="", group_id=group_id)
-
-        try:
-            dao = DataAccess(cls)
-            if user_id:
-                if group_id:
-                    q = Q(user_id=user_id) & Q(group_id=group_id)
-                else:
-                    q = Q(user_id=user_id) & Q(group_id__isnull=True)
-            else:
-                q = Q(user_id="") & Q(group_id=group_id)
-
-            result = await dao.safe_get_or_none(True, q)
-            future.set_result(result)
-            return result
-        except Exception as e:
-            future.set_exception(e)
-            raise
-        finally:
-            cls._inflight.pop(key, None)
 
     @classmethod
     async def check_ban_level(
@@ -130,87 +117,21 @@ class BanConsole(Model):
         return 0
 
     @classmethod
-    async def is_ban(
+    async def is_ban(cls, user_id: str | None, group_id: str | None = None) -> bool:
-        cls, user_id: str | None, group_id: str | None = None
-    ) -> list[Self]:
         """判断用户是否被ban
 
         参数:
             user_id: 用户id
-            group_id: 群组id
 
         返回:
-            bool: list[Self] | None
+            bool: 是否被ban
         """
         logger.debug("检测是否被ban", target=f"{group_id}:{user_id}")
-
+        if await cls.check_ban_time(user_id, group_id):
-        q_conditions = []
+            return True
-
+        else:
-        if user_id and group_id:
+            await cls.unban(user_id, group_id)
-            q_conditions.append(Q(user_id=user_id, group_id=group_id))
+        return False
-        if user_id:
-            q_conditions.append(Q(user_id=user_id, group_id__isnull=True))
-        if group_id:
-            q_conditions.append(Q(group_id=group_id, user_id=""))
-
-        if not q_conditions:
-            return []
-
-        q = q_conditions[0]
-        for condition in q_conditions[1:]:
-            q |= condition
-
-        users = await cls.filter(q).all()
-        if not users:
-            return []
-
-        results = []
-        for user in users:
-            # 永久封禁视为一直处于封禁中
-            if user.duration == -1:
-                results.append(user)
-                continue
-
-            _time = time.time() - (user.ban_time + user.duration)
-            # 还在封禁期内
-            if _time < 0:
-                results.append(user)
-                continue
-
-            # 已过期，删除记录并标记为不满足「全部仍在封禁」条件
-            await user.delete()
-
-        return results
-
-    @classmethod
-    async def is_ban_cached(
-        cls, user_id: str | None, group_id: str | None
-    ) -> list[Self]:
-        """带缓存的 ban 状态检查
-
-        参数:
-            user_id: 用户id
-            group_id: 群组id
-
-        返回:
-            list[Self]: ban记录列表，空列表表示未被ban
-        """
-        cache_key = f"{user_id}_{group_id}"
-
-        results = await CacheRoot.get(CacheType.BAN, cache_key)
-        if not results:
-            results = await cls.is_ban(user_id, group_id)
-            await CacheRoot.set(
-                CacheType.BAN,
-                cache_key,
-                results or DataAccess._NULL_RESULT,
-            )
-            return results
-
-        if results == DataAccess._NULL_RESULT:
-            return []
-
-        return [CacheRoot._deserialize_value(r, cls) for r in results]
 
     @classmethod
     async def ban(
@@ -222,21 +143,30 @@ class BanConsole(Model):
         duration: int,
         operator: str | None = None,
     ):
+        """ban掉目标用户
+
+        参数:
+            user_id: 用户id
+            group_id: 群组id
+            ban_level: 使用命令者的权限等级
+            duration: 时长，分钟，-1时为永久
+            operator: 操作者id
+        """
         logger.debug(
             f"封禁用户/群组，等级:{ban_level}，时长: {duration}",
             target=f"{group_id}:{user_id}",
         )
-
+        target = await cls._get_data(user_id, group_id)
-        await cls.update_or_create(
+        if target:
+            await cls.unban(user_id, group_id)
+        await cls.create(
             user_id=user_id,
             group_id=group_id,
-            defaults={
+            ban_level=ban_level,
-                "ban_level": ban_level,
+            ban_time=int(time.time()),
-                "ban_time": int(time.time()),
+            ban_reason=reason,
-                "ban_reason": reason,
+            duration=duration,
-                "duration": duration,
+            operator=operator or 0,
-                "operator": operator or 0,
-            },
         )
 
     @classmethod

zhenxun/models/group_console.py

@@ -96,10 +96,8 @@ class GroupConsole(Model):
     """缓存类型"""
     cache_key_field = ("group_id", "channel_id")
     """缓存键字段"""
-    lock_fields: ClassVar[dict[DbLockType, tuple[str, str]]] = {
+    enable_lock: ClassVar[list[DbLockType]] = [DbLockType.CREATE, DbLockType.UPSERT]
-        DbLockType.CREATE: ("group_id", "channel_id"),
+    """开启锁"""
-        DbLockType.UPSERT: ("group_id", "channel_id"),
-    }
 
     @classmethod
     async def _get_task_modules(cls, *, default_status: bool) -> list[str]:

zhenxun/models/group_plugin_setting.py

@@ -1,29 +0,0 @@
-from tortoise import fields
-
-from zhenxun.services.db_context import Model
-from zhenxun.utils.enum import CacheType
-
-
-class GroupPluginSetting(Model):
-    id = fields.IntField(pk=True, generated=True, auto_increment=True)
-    """自增ID"""
-    group_id = fields.CharField(max_length=255, indexed=True, description="群组ID")
-    """群组ID"""
-    plugin_name = fields.CharField(
-        max_length=255, indexed=True, description="插件模块名"
-    )
-    """插件模块名"""
-    settings = fields.JSONField(description="插件的完整配置 (JSON)")
-    """插件的完整配置 (JSON)"""
-    updated_at = fields.DatetimeField(auto_now=True, description="最后更新时间")
-    """最后更新时间"""
-
-    cache_type = CacheType.GROUP_PLUGIN_SETTINGS
-    """缓存类型"""
-    cache_key_field = ("group_id", "plugin_name")
-    """缓存键字段"""
-
-    class Meta:  # pyright: ignore [reportIncompatibleVariableOverride]
-        table = "group_plugin_settings"
-        table_description = "插件分群通用配置表"
-        unique_together = ("group_id", "plugin_name")

zhenxun/models/user_console.py

@@ -1,10 +1,7 @@
-from tortoise import BaseDBAsyncClient, Tortoise, fields
+from tortoise import fields
-from tortoise.exceptions import IntegrityError
 
-from zhenxun.configs.config import BotConfig
 from zhenxun.models.goods_info import GoodsInfo
 from zhenxun.services.db_context import Model
-from zhenxun.services.log import logger
 from zhenxun.utils.enum import CacheType, GoldHandle
 from zhenxun.utils.exception import GoodsNotFound, InsufficientGold
 
@@ -17,7 +14,7 @@ class UserConsole(Model):
     user_id = fields.CharField(255, unique=True, description="用户id")
     """用户id"""
     uid = fields.IntField(description="UID", unique=True)
-    """UID，用户可修改"""
+    """UID"""
     gold = fields.IntField(default=100, description="金币数量")
     """金币数量"""
     sign = fields.ReverseRelation["SignUser"]  # type: ignore
@@ -41,104 +38,35 @@ class UserConsole(Model):
 
     @classmethod
     async def get_user(cls, user_id: str, platform: str | None = None) -> "UserConsole":
-        """获取或创建用户（优化版本，使用数据库序列避免并发问题）"""
+        """获取用户
-        if user := await cls.get_or_none(user_id=user_id):
-            return user
 
-        # 使用数据库序列获取 uid，原子操作无竞争
+        参数:
-        uid = await cls._next_uid_from_sequence()
+            user_id: 用户id
-
+            platform: 平台.
-        try:
-            return await cls.create(user_id=user_id, uid=uid, platform=platform)
-        except IntegrityError:
-            # user_id 冲突（并发创建同一用户）
-            if user := await cls.get_or_none(user_id=user_id):
-                return user
-            # uid 冲突（极罕见，用户手动修改了 uid），重试
-            for _ in range(3):
-                try:
-                    uid = await cls._next_uid_from_sequence()
-                    return await cls.create(user_id=user_id, uid=uid, platform=platform)
-                except IntegrityError:
-                    if user := await cls.get_or_none(user_id=user_id):
-                        return user
-            raise
-
-    @classmethod
-    async def _next_uid_from_sequence(cls) -> int:
-        """获取下一个 UID（原子操作，支持 PostgreSQL/MySQL/SQLite）"""
-        conn = Tortoise.get_connection("default")
-        db_type = BotConfig.get_sql_type()
-
-        try:
-            if db_type == "postgresql":
-                return await cls._next_uid_postgresql(conn)
-            elif db_type == "mysql":
-                return await cls._next_uid_mysql(conn)
-            else:  # sqlite
-                return await cls._next_uid_sqlite(conn)
-        except Exception as e:
-            logger.debug(f"序列获取失败，使用备用方案: {e}")
-            return await cls._get_max_uid() + 1
-
-    @classmethod
-    async def _next_uid_postgresql(cls, conn: BaseDBAsyncClient) -> int:
-        """PostgreSQL: 使用序列"""
-        result = await conn.execute_query_dict(
-            "SELECT nextval('user_console_uid_seq') as uid"
-        )
-        return result[0]["uid"]
-
-    @classmethod
-    async def _next_uid_mysql(cls, conn: BaseDBAsyncClient) -> int:
-        """MySQL: 使用序列表实现原子自增"""
-        # 原子更新并获取新值
-        await conn.execute_query(
-            """
-            INSERT INTO user_console_sequence (id, current_value)
-            VALUES (1, 1)
-            ON DUPLICATE KEY UPDATE current_value = current_value + 1
-            """
-        )
-        result = await conn.execute_query_dict(
-            "SELECT current_value as uid FROM user_console_sequence WHERE id = 1"
-        )
-        return result[0]["uid"]
-
-    @classmethod
-    async def _next_uid_sqlite(cls, conn: BaseDBAsyncClient) -> int:
-        """SQLite: 使用序列表实现原子自增"""
-        # SQLite 使用 INSERT OR REPLACE 实现原子操作
-        await conn.execute_query(
-            """
-            INSERT OR REPLACE INTO user_console_sequence (id, current_value)
-            VALUES (1, COALESCE(
-                (SELECT current_value + 1 FROM user_console_sequence WHERE id = 1),
-                (SELECT COALESCE(MAX(uid), 0) + 1 FROM user_console)
-            ))
-            """
-        )
-        result = await conn.execute_query_dict(
-            "SELECT current_value as uid FROM user_console_sequence WHERE id = 1"
-        )
-        return result[0]["uid"]
-
-    @classmethod
-    async def _get_max_uid(cls) -> int:
-        """获取当前最大 uid（备用方案）"""
-        data: list[int] = (  # pyright: ignore[reportAssignmentType]
-            await cls.annotate().order_by("-uid").limit(1).values_list("uid", flat=True)
-        )
-        return data[0] if data else 0
-
-    @classmethod
-    async def get_user_count(cls) -> int:
-        """获取用户总数
 
         返回:
-            int: 用户总数
+            UserConsole: UserConsole
         """
-        return await cls.all().count()
+        if not await cls.exists(user_id=user_id):
+            await cls.create(
+                user_id=user_id, platform=platform, uid=await cls.get_new_uid()
+            )
+        # user, _ = await UserConsole.get_or_create(
+        #     user_id=user_id,
+        #     defaults={"platform": platform, "uid": await cls.get_new_uid()},
+        # )
+        return await cls.get(user_id=user_id)
+
+    @classmethod
+    async def get_new_uid(cls) -> int:
+        """获取最新uid
+
+        返回:
+            int: 最新uid
+        """
+        if user := await cls.annotate().order_by("-uid").first():
+            return user.uid + 1
+        return 1
 
     @classmethod
     async def add_gold(
@@ -152,7 +80,10 @@ class UserConsole(Model):
             source: 来源
             platform: 平台.
         """
-        user = await cls.get_user(user_id, platform)
+        user, _ = await cls.get_or_create(
+            user_id=user_id,
+            defaults={"platform": platform, "uid": await cls.get_new_uid()},
+        )
         user.gold += gold
         await user.save(update_fields=["gold"])
         await UserGoldLog.create(
@@ -180,7 +111,10 @@ class UserConsole(Model):
         异常:
             InsufficientGold: 金币不足
         """
-        user = await cls.get_user(user_id, platform)
+        user, _ = await cls.get_or_create(
+            user_id=user_id,
+            defaults={"platform": platform, "uid": await cls.get_new_uid()},
+        )
         if user.gold < gold:
             raise InsufficientGold()
         user.gold -= gold
@@ -201,7 +135,10 @@ class UserConsole(Model):
             num: 道具数量.
             platform: 平台.
         """
-        user = await cls.get_user(user_id, platform)
+        user, _ = await cls.get_or_create(
+            user_id=user_id,
+            defaults={"platform": platform, "uid": await cls.get_new_uid()},
+        )
         if goods_uuid not in user.props:
             user.props[goods_uuid] = 0
         user.props[goods_uuid] += num
@@ -235,7 +172,11 @@ class UserConsole(Model):
             num: 道具数量.
             platform: 平台.
         """
-        user = await cls.get_user(user_id, platform)
+        user, _ = await cls.get_or_create(
+            user_id=user_id,
+            defaults={"platform": platform, "uid": await cls.get_new_uid()},
+        )
+
         if goods_uuid not in user.props or user.props[goods_uuid] < num:
             raise GoodsNotFound("未找到商品或道具数量不足...")
         user.props[goods_uuid] -= num
@@ -261,68 +202,7 @@ class UserConsole(Model):
 
     @classmethod
     async def _run_script(cls):
-        """初始化脚本，根据数据库类型创建序列/表"""
+        return [
-        db_type = BotConfig.get_sql_type()
+            "CREATE INDEX idx_user_console_user_id ON user_console(user_id);",
-
+            "CREATE INDEX idx_user_console_uid ON user_console(uid);",
-        # 通用索引
-        scripts = [
-            "CREATE INDEX IF NOT EXISTS idx_user_console_user_id "
-            "ON user_console(user_id);",
-            "CREATE INDEX IF NOT EXISTS idx_user_console_uid ON user_console(uid);",
         ]
-
-        # 根据数据库类型添加序列初始化脚本
-        if db_type == "postgresql":
-            scripts.append(
-                """
-                DO $$
-                BEGIN
-                    IF NOT EXISTS (
-                        SELECT 1 FROM pg_sequences
-                        WHERE schemaname = 'public'
-                        AND sequencename = 'user_console_uid_seq'
-                    ) THEN
-                        CREATE SEQUENCE user_console_uid_seq;
-                        PERFORM setval(
-                            'user_console_uid_seq',
-                            COALESCE((SELECT MAX(uid) FROM user_console), 0) + 1,
-                            false
-                        );
-                    END IF;
-                END $$;
-                """
-            )
-        elif db_type == "mysql":
-            # MySQL: 创建序列表
-            scripts.extend(
-                [
-                    """
-                CREATE TABLE IF NOT EXISTS user_console_sequence (
-                    id INT PRIMARY KEY,
-                    current_value BIGINT NOT NULL DEFAULT 0
-                );
-                """,
-                    """
-                INSERT IGNORE INTO user_console_sequence (id, current_value)
-                SELECT 1, COALESCE(MAX(uid), 0) FROM user_console;
-                """,
-                ]
-            )
-        else:  # sqlite
-            # SQLite: 创建序列表
-            scripts.extend(
-                [
-                    """
-                CREATE TABLE IF NOT EXISTS user_console_sequence (
-                    id INTEGER PRIMARY KEY,
-                    current_value INTEGER NOT NULL DEFAULT 0
-                );
-                """,
-                    """
-                INSERT OR IGNORE INTO user_console_sequence (id, current_value)
-                SELECT 1, COALESCE(MAX(uid), 0) FROM user_console;
-                """,
-                ]
-            )
-
-        return scripts

zhenxun/services/__init__.py

@@ -9,9 +9,6 @@ Zhenxun Bot - 核心服务模块
 - 定时任务调度器 (scheduler): 提供持久化的、可管理的定时任务服务。
 """
 
-import asyncio
-
-import nonebot
 from nonebot import require
 
 require("nonebot_plugin_apscheduler")
@@ -23,7 +20,6 @@ require("nonebot_plugin_waiter")
 
 from .avatar_service import avatar_service
 from .db_context import Model, disconnect, with_db_timeout
-from .group_settings_service import group_settings_service
 from .llm import (
     AI,
     AIConfig,
@@ -81,7 +77,6 @@ __all__ = [
     "generate_structured",
     "get_cache_stats",
     "get_model_instance",
-    "group_settings_service",
     "list_available_models",
     "list_embedding_models",
     "logger",
@@ -91,29 +86,3 @@ __all__ = [
     "set_global_default_model_name",
     "with_db_timeout",
 ]
-
-
-async def cancel_pending_tasks():
-    loop = asyncio.get_running_loop()
-    current = asyncio.current_task(loop=loop)
-    pending = []
-    for task in asyncio.all_tasks(loop):
-        if task is current or task.done():
-            continue
-        coro = task.get_coro()
-        module = getattr(coro, "__module__", "")
-        if module.startswith("zhenxun"):
-            pending.append(task)
-
-    if not pending:
-        return
-
-    for task in pending:
-        task.cancel()
-
-    await asyncio.gather(*pending, return_exceptions=True)
-
-
-driver = nonebot.get_driver()
-# 先取消可能在跑的任务，再断开数据库，避免 pool closing 异常
-driver.on_shutdown(cancel_pending_tasks)

zhenxun/services/auth_snapshot/__init__.py

@@ -1,15 +0,0 @@
-"""
-权限快照服务模块
-
-提供预聚合的权限检查数据，将多次数据库/缓存查询优化为1-2次
-"""
-
-from .models import AuthSnapshot, PluginSnapshot
-from .service import AuthSnapshotService, PluginSnapshotService
-
-__all__ = [
-    "AuthSnapshot",
-    "AuthSnapshotService",
-    "PluginSnapshot",
-    "PluginSnapshotService",
-]

zhenxun/services/auth_snapshot/builder.py

@@ -1,500 +0,0 @@
-"""
-快照构建器
-
-负责从多个数据源聚合数据构建权限快照
-优化版：使用原始 SQL 减少查询次数
-
-支持数据库：MySQL, PostgreSQL, SQLite
-"""
-
-import time
-from typing import Any, ClassVar
-
-from tortoise import Tortoise
-
-from zhenxun.configs.config import BotConfig
-from zhenxun.models.bot_console import BotConsole
-from zhenxun.models.group_console import GroupConsole
-from zhenxun.models.plugin_info import PluginInfo
-from zhenxun.services.cache import CacheRoot
-from zhenxun.services.cache.cache_containers import CacheDict
-from zhenxun.services.log import logger
-
-from .models import AuthSnapshot, PluginSnapshot
-
-LOG_COMMAND = "auth_snapshot"
-
-# 静态数据缓存 TTL（这些数据变化不频繁）
-BOT_CACHE_TTL = 300  # Bot 缓存 5 分钟
-GROUP_CACHE_TTL = 60  # Group 缓存 1 分钟
-
-# 数据库类型
-DB_TYPE_POSTGRES = "postgres"
-DB_TYPE_MYSQL = "mysql"
-DB_TYPE_SQLITE = "sqlite"
-
-
-class SnapshotBuilder:
-    """快照构建器（优化版）
-
-    使用原始 SQL 减少查询次数：
-    - 1 次复合 SQL 获取用户相关数据（UserConsole + LevelUser + BanConsole）
-    - Bot/Group 使用内存缓存（变化不频繁）
-
-    最优情况：1 次 DB 查询
-    最差情况：3 次 DB 查询（用户数据 + Group + Bot 均未命中缓存）
-    """
-
-    # Bot 信息缓存
-    _bot_cache: ClassVar[CacheDict[dict[str, Any]] | None] = None
-    # Group 信息缓存
-    _group_cache: ClassVar[CacheDict[dict[str, Any]] | None] = None
-
-    @classmethod
-    def _get_bot_cache(cls) -> CacheDict[dict[str, Any]]:
-        """获取 Bot 缓存"""
-        if cls._bot_cache is None:
-            cls._bot_cache = CacheRoot.cache_dict(
-                "SNAPSHOT_BOT_CACHE", expire=BOT_CACHE_TTL, value_type=dict
-            )
-        return cls._bot_cache
-
-    @classmethod
-    def _get_group_cache(cls) -> CacheDict[dict[str, Any]]:
-        """获取 Group 缓存"""
-        if cls._group_cache is None:
-            cls._group_cache = CacheRoot.cache_dict(
-                "SNAPSHOT_GROUP_CACHE", expire=GROUP_CACHE_TTL, value_type=dict
-            )
-        return cls._group_cache
-
-    @classmethod
-    async def build_auth_snapshot(
-        cls,
-        user_id: str,
-        group_id: str | None,
-        bot_id: str,
-    ) -> AuthSnapshot:
-        """构建权限快照（优化版）
-
-        使用单条 SQL 获取用户相关数据，Bot/Group 使用内存缓存
-
-        参数:
-            user_id: 用户ID
-            group_id: 群组ID（可为None表示私聊）
-            bot_id: Bot ID
-
-        返回:
-            AuthSnapshot: 权限快照对象
-        """
-        start_time = time.time()
-
-        try:
-            # 1. 使用单条 SQL 获取用户相关数据
-            user_data = await cls._get_user_data_by_sql(user_id, group_id)
-
-            # 2. 获取 Bot 信息（优先缓存）
-            bot_data = await cls._get_bot_cached(bot_id)
-
-            # 3. 获取 Group 信息（优先缓存）
-            group_data = None
-            if group_id:
-                group_data = await cls._get_group_cached(group_id)
-
-            # 4. 聚合结果
-            snapshot = cls._aggregate_sql_results(
-                user_id, group_id, bot_id, user_data, bot_data, group_data
-            )
-
-            elapsed = time.time() - start_time
-            if elapsed > 0.5:
-                logger.warning(
-                    f"构建权限快照耗时较长: {elapsed:.3f}s, "
-                    f"user={user_id}, group={group_id}",
-                    LOG_COMMAND,
-                )
-
-            return snapshot
-
-        except Exception as e:
-            logger.error(
-                f"构建权限快照失败: user={user_id}, group={group_id}",
-                LOG_COMMAND,
-                e=e,
-            )
-            return AuthSnapshot(user_id=user_id, group_id=group_id, bot_id=bot_id)
-
-    @classmethod
-    async def _get_user_data_by_sql(
-        cls, user_id: str, group_id: str | None
-    ) -> dict[str, Any]:
-        """使用单条 SQL 获取用户相关数据
-
-        合并查询：UserConsole + LevelUser + BanConsole
-        支持：MySQL, PostgreSQL, SQLite
-        """
-        result: dict[str, Any] = {
-            "gold": 0,
-            "level_global": 0,
-            "level_group": 0,
-            "user_banned": 0,
-            "user_ban_duration": 0,
-            "group_banned": 0,
-        }
-
-        try:
-            db = Tortoise.get_connection("default")
-            db_type = BotConfig.get_sql_type()
-
-            # 构建复合 SQL 和参数
-            sql, params = cls._build_user_data_sql(user_id, group_id, db_type)
-
-            # 执行参数化查询
-            if db_type == DB_TYPE_POSTGRES:
-                # PostgreSQL 使用 asyncpg，参数作为位置参数
-                rows = await db.execute_query_dict(sql, params)
-            elif db_type == DB_TYPE_MYSQL:
-                # MySQL 使用 aiomysql
-                rows = await db.execute_query_dict(sql, params)
-            else:
-                # SQLite 使用 aiosqlite
-                rows = await db.execute_query_dict(sql, params)
-
-            # 解析结果
-            for row in rows:
-                query_type = row.get("query_type")
-
-                if query_type == "user":
-                    result["gold"] = row.get("gold") or 0
-
-                elif query_type == "level_global":
-                    result["level_global"] = row.get("user_level") or 0
-
-                elif query_type == "level_group":
-                    result["level_group"] = row.get("user_level") or 0
-
-                elif query_type == "ban_user_global":
-                    duration = row.get("duration")
-                    ban_time = row.get("ban_time")
-                    if duration is not None:
-                        if duration == -1:
-                            result["user_banned"] = -1
-                            result["user_ban_duration"] = -1
-                        else:
-                            result["user_banned"] = int(ban_time + duration)
-                            result["user_ban_duration"] = duration
-
-                elif query_type == "ban_user_group":
-                    duration = row.get("duration")
-                    ban_time = row.get("ban_time")
-                    if duration is not None:
-                        if duration == -1:
-                            result["user_banned"] = -1
-                            result["user_ban_duration"] = -1
-                        else:
-                            result["user_banned"] = int(ban_time + duration)
-                            result["user_ban_duration"] = duration
-
-                elif query_type == "ban_group":
-                    duration = row.get("duration")
-                    ban_time = row.get("ban_time")
-                    if duration is not None:
-                        if duration == -1:
-                            result["group_banned"] = -1
-                        else:
-                            result["group_banned"] = int(ban_time + duration)
-
-        except Exception as e:
-            logger.warning(
-                f"SQL 查询用户数据失败: user={user_id}, group={group_id}",
-                LOG_COMMAND,
-                e=e,
-            )
-
-        return result
-
-    @classmethod
-    def _get_placeholder(cls, db_type: str, index: int) -> str:
-        """获取数据库占位符
-
-        参数:
-            db_type: 数据库类型
-            index: 参数索引（从1开始）
-
-        返回:
-            str: 占位符字符串
-        """
-        if db_type == DB_TYPE_POSTGRES:
-            return f"${index}"
-        elif db_type == DB_TYPE_MYSQL:
-            return "%s"
-        else:  # sqlite
-            return "?"
-
-    @classmethod
-    def _get_null_cast(cls, db_type: str, col_type: str) -> str:
-        """获取 NULL 的类型转换语法
-
-        参数:
-            db_type: 数据库类型
-            col_type: 目标列类型 (bigint, int, etc.)
-
-        返回:
-            str: 带类型转换的 NULL
-        """
-        if db_type == DB_TYPE_POSTGRES:
-            return f"NULL::{col_type}"
-        elif db_type == DB_TYPE_MYSQL:
-            # MySQL UNION 会自动推断类型，但显式转换更安全
-            return "CAST(NULL AS SIGNED)"
-        else:  # sqlite
-            # SQLite 是动态类型，NULL 不需要转换
-            return "NULL"
-
-    @classmethod
-    def _build_user_data_sql(
-        cls, user_id: str, group_id: str | None, db_type: str
-    ) -> tuple[str, list[Any]]:
-        """构建复合 SQL 语句（支持多数据库）
-
-        使用 UNION ALL 合并多个查询，一次性获取所有用户相关数据
-        使用参数化查询防止 SQL 注入
-
-        参数:
-            user_id: 用户ID
-            group_id: 群组ID
-            db_type: 数据库类型 (postgres, mysql, sqlite)
-
-        返回:
-            tuple[str, list]: (SQL语句, 参数列表)
-        """
-        queries = []
-        params: list[Any] = []
-        param_idx = 1
-
-        def ph() -> str:
-            """获取下一个占位符"""
-            nonlocal param_idx
-            placeholder = cls._get_placeholder(db_type, param_idx)
-            param_idx += 1
-            return placeholder
-
-        # 获取类型转换的 NULL（PostgreSQL 需要显式类型）
-        null_bigint = cls._get_null_cast(db_type, "bigint")
-        null_int = cls._get_null_cast(db_type, "integer")
-
-        # 1. 用户金币
-        queries.append(f"""
-            SELECT 'user' as query_type, gold, {null_int} as user_level,
-                   {null_bigint} as ban_time, {null_int} as duration
-            FROM user_console WHERE user_id = {ph()}
-        """)
-        params.append(user_id)
-
-        # 2. 全局权限等级
-        queries.append(f"""
-            SELECT 'level_global' as query_type, {null_int} as gold, user_level,
-                   {null_bigint} as ban_time, {null_int} as duration
-            FROM level_users WHERE user_id = {ph()} AND group_id IS NULL
-        """)
-        params.append(user_id)
-
-        # 3. 群组权限等级
-        if group_id:
-            queries.append(f"""
-                SELECT 'level_group' as query_type, {null_int} as gold, user_level,
-                       {null_bigint} as ban_time, {null_int} as duration
-                FROM level_users
-                WHERE user_id = {ph()} AND group_id = {ph()}
-            """)
-            params.extend([user_id, group_id])
-
-        # 4. 用户全局 ban
-        queries.append(f"""
-            SELECT 'ban_user_global' as query_type,
-                   {null_int} as gold, {null_int} as user_level,
-                   ban_time, duration
-            FROM ban_console
-            WHERE user_id = {ph()} AND group_id IS NULL
-        """)
-        params.append(user_id)
-
-        # 5. 用户群组 ban
-        if group_id:
-            queries.append(f"""
-                SELECT 'ban_user_group' as query_type,
-                       {null_int} as gold, {null_int} as user_level,
-                       ban_time, duration
-                FROM ban_console
-                WHERE user_id = {ph()} AND group_id = {ph()}
-            """)
-            params.extend([user_id, group_id])
-
-            # 6. 群组 ban
-            queries.append(f"""
-                SELECT 'ban_group' as query_type,
-                       {null_int} as gold, {null_int} as user_level,
-                       ban_time, duration
-                FROM ban_console
-                WHERE user_id = {ph()} AND group_id = {ph()}
-            """)
-            params.extend(["", group_id])
-
-        return " UNION ALL ".join(queries), params
-
-    @classmethod
-    async def _get_bot_cached(cls, bot_id: str) -> dict[str, Any] | None:
-        """获取 Bot 信息（带缓存）"""
-        cache = cls._get_bot_cache()
-
-        # 尝试从缓存获取
-        if cached := cache.get(bot_id):
-            return cached
-
-        # 缓存未命中，查询数据库
-        try:
-            bot = await BotConsole.get_or_none(bot_id=bot_id)
-            if bot:
-                data = {
-                    "status": bot.status,
-                    "block_plugins": bot.block_plugins
-                    if hasattr(bot, "block_plugins")
-                    else None,
-                }
-                cache.set(bot_id, data)
-                return data
-        except Exception as e:
-            logger.warning(f"获取 Bot 信息失败: {bot_id}", LOG_COMMAND, e=e)
-
-        return None
-
-    @classmethod
-    async def _get_group_cached(cls, group_id: str) -> dict[str, Any] | None:
-        """获取 Group 信息（带缓存）"""
-        cache = cls._get_group_cache()
-
-        # 尝试从缓存获取
-        if cached := cache.get(group_id):
-            return cached
-
-        # 缓存未命中，查询数据库
-        try:
-            group = await GroupConsole.get_or_none(
-                group_id=group_id, channel_id__isnull=True
-            )
-            if group:
-                data = {
-                    "status": group.status,
-                    "level": group.level,
-                    "is_super": group.is_super,
-                    "block_plugin": group.block_plugin,
-                    "superuser_block_plugin": group.superuser_block_plugin,
-                }
-                cache.set(group_id, data)
-                return data
-        except Exception as e:
-            logger.warning(f"获取 Group 信息失败: {group_id}", LOG_COMMAND, e=e)
-
-        return None
-
-    @classmethod
-    def _aggregate_sql_results(
-        cls,
-        user_id: str,
-        group_id: str | None,
-        bot_id: str,
-        user_data: dict[str, Any],
-        bot_data: dict[str, Any] | None,
-        group_data: dict[str, Any] | None,
-    ) -> AuthSnapshot:
-        """聚合 SQL 查询结果为快照"""
-        snapshot = AuthSnapshot(
-            user_id=user_id,
-            group_id=group_id,
-            bot_id=bot_id,
-        )
-
-        # 用户数据
-        snapshot.user_gold = user_data.get("gold", 0)
-        snapshot.user_level_global = user_data.get("level_global", 0)
-        snapshot.user_level_group = user_data.get("level_group", 0)
-        snapshot.user_banned = user_data.get("user_banned", 0)
-        snapshot.user_ban_duration = user_data.get("user_ban_duration", 0)
-        snapshot.group_banned = user_data.get("group_banned", 0)
-
-        # Group 信息
-        if group_data:
-            snapshot.group_exists = True
-            snapshot.group_status = group_data.get("status", True)
-            snapshot.group_level = group_data.get("level", 5)
-            snapshot.group_is_super = group_data.get("is_super", False)
-            snapshot.group_block_plugins = group_data.get("block_plugin") or ""
-            snapshot.group_superuser_block_plugins = (
-                group_data.get("superuser_block_plugin") or ""
-            )
-        elif group_id:
-            snapshot.group_exists = False
-
-        # Bot 信息
-        if bot_data:
-            snapshot.bot_status = bot_data.get("status", True)
-            block_plugins = bot_data.get("block_plugins")
-            if block_plugins:
-                if isinstance(block_plugins, list):
-                    snapshot.bot_block_plugins = "".join(
-                        f"<{p}," for p in block_plugins
-                    )
-                else:
-                    snapshot.bot_block_plugins = block_plugins
-
-        return snapshot
-
-    @classmethod
-    def invalidate_bot_cache(cls, bot_id: str | None = None):
-        """失效 Bot 缓存"""
-        cache = cls._get_bot_cache()
-        if bot_id:
-            cache.delete(bot_id)
-        else:
-            cache.clear()
-
-    @classmethod
-    def invalidate_group_cache(cls, group_id: str | None = None):
-        """失效 Group 缓存"""
-        cache = cls._get_group_cache()
-        if group_id:
-            cache.delete(group_id)
-        else:
-            cache.clear()
-
-    @classmethod
-    async def build_plugin_snapshot(cls, module: str) -> PluginSnapshot | None:
-        """构建插件快照
-
-        参数:
-            module: 插件模块名
-
-        返回:
-            PluginSnapshot | None: 插件快照，不存在时返回None
-        """
-        try:
-            plugin = await PluginInfo.get_or_none(module=module)
-            if not plugin:
-                return None
-
-            return PluginSnapshot(
-                module=plugin.module,
-                name=plugin.name,
-                status=plugin.status,
-                block_type=plugin.block_type,
-                plugin_type=plugin.plugin_type,
-                admin_level=plugin.admin_level or 0,
-                cost_gold=plugin.cost_gold,
-                level=plugin.level,
-                limit_superuser=plugin.limit_superuser,
-                ignore_prompt=plugin.ignore_prompt,
-            )
-
-        except Exception as e:
-            logger.error(f"构建插件快照失败: {module}", LOG_COMMAND, e=e)
-            return None

zhenxun/services/auth_snapshot/checker.py

@@ -1,377 +0,0 @@
-"""
-优化后的权限检查器
-
-使用预聚合的权限快照进行权限检查，将查询次数从6-10次降低到1-2次
-"""
-
-import asyncio
-import time
-
-from nonebot.adapters import Bot, Event
-from nonebot.matcher import Matcher
-from nonebot_plugin_alconna import UniMsg
-from nonebot_plugin_uninfo import Uninfo
-
-from zhenxun.models.user_console import UserConsole
-from zhenxun.services.log import logger
-from zhenxun.utils.enum import BlockType, GoldHandle
-from zhenxun.utils.platform import PlatformUtils
-from zhenxun.utils.utils import get_entity_ids
-
-from .exception import IsSuperuserException, SkipPluginException
-from .models import AuthSnapshot, PluginSnapshot
-from .service import AuthSnapshotService, PluginSnapshotService
-
-LOG_COMMAND = "AuthSnapshotChecker"
-WARNING_THRESHOLD = 0.5  # 警告阈值（秒）
-
-
-class AuthCheckResult:
-    """权限检查结果"""
-
-    def __init__(self):
-        self.passed: bool = True
-        self.skip_reason: str = ""
-        self.cost_gold: int = 0
-        self.is_superuser: bool = False
-
-    def fail(self, reason: str):
-        """标记检查失败"""
-        self.passed = False
-        self.skip_reason = reason
-
-
-class OptimizedAuthChecker:
-    """优化后的权限检查器
-
-    核心优化：
-    1. 使用预聚合的权限快照，将多次查询合并为1-2次
-    2. 所有检查基于内存中的快照数据，无额外I/O
-    3. 保持与原有系统相同的检查逻辑和结果
-    """
-
-    async def check(
-        self,
-        matcher: Matcher,
-        event: Event,
-        bot: Bot,
-        session: Uninfo,
-        message: UniMsg,
-    ):
-        """执行权限检查
-
-        参数:
-            matcher: Matcher
-            event: Event
-            bot: Bot
-            session: Uninfo
-            message: UniMsg
-        """
-        start_time = time.time()
-        result = AuthCheckResult()
-        hook_times: dict[str, str] = {}
-
-        try:
-            # 1. 获取基础信息
-            entity = get_entity_ids(session)
-            module = matcher.plugin_name or ""
-
-            if not module:
-                result.fail("Matcher插件名称不存在...")
-                raise SkipPluginException(result.skip_reason)
-
-            # 2. 获取权限快照（第一次查询）
-            snapshot_start = time.time()
-            auth_snapshot = await AuthSnapshotService.get_snapshot(
-                user_id=entity.user_id,
-                group_id=entity.group_id,
-                bot_id=bot.self_id,
-            )
-            hook_times["get_auth_snapshot"] = f"{time.time() - snapshot_start:.3f}s"
-
-            # 3. 获取插件快照（第二次查询，通常命中内存缓存）
-            plugin_start = time.time()
-            plugin_snapshot = await PluginSnapshotService.get_plugin(module)
-            hook_times["get_plugin_snapshot"] = f"{time.time() - plugin_start:.3f}s"
-
-            if not plugin_snapshot:
-                result.fail(f"插件:{module} 数据不存在...")
-                raise SkipPluginException(result.skip_reason)
-
-            # 4. 检查是否为隐藏插件
-            if plugin_snapshot.is_hidden():
-                result.fail(f"插件: {plugin_snapshot.name}:{module} 为HIDDEN...")
-                return
-
-            # 5. 检查超级用户
-            is_superuser = session.user.id in bot.config.superusers
-            result.is_superuser = is_superuser
-
-            # 6. 执行所有权限检查（纯内存计算）
-            check_start = time.time()
-            await self._run_all_checks(
-                result=result,
-                auth_snapshot=auth_snapshot,
-                plugin_snapshot=plugin_snapshot,
-                message=message,
-                session=session,
-                is_superuser=is_superuser,
-            )
-            hook_times["run_checks"] = f"{time.time() - check_start:.3f}s"
-
-            # 7. 处理检查结果
-            if not result.passed:
-                logger.info(result.skip_reason, LOG_COMMAND, session=session)
-                raise SkipPluginException(result.skip_reason)
-
-            # 9. 扣除金币（如果需要）
-            if result.cost_gold > 0:
-                try:
-                    gold_start = time.time()
-                    await asyncio.wait_for(
-                        UserConsole.reduce_gold(
-                            entity.user_id,
-                            result.cost_gold,
-                            GoldHandle.PLUGIN,
-                            module,
-                            PlatformUtils.get_platform(session),
-                        ),
-                        timeout=5.0,
-                    )
-                    hook_times["reduce_gold"] = f"{time.time() - gold_start:.3f}s"
-
-                    # 扣除金币后失效用户快照缓存
-                    await AuthSnapshotService.invalidate_user(entity.user_id)
-
-                except asyncio.TimeoutError:
-                    logger.error(
-                        f"扣除金币超时，模块: {module}", LOG_COMMAND, session=session
-                    )
-        except IsSuperuserException:
-            raise
-        except SkipPluginException:
-            raise
-        except Exception as e:
-            logger.error(f"权限检查异常: {e}", LOG_COMMAND, session=session, e=e)
-            raise SkipPluginException("权限检查异常") from e
-        finally:
-            # 记录总执行时间
-            total_time = time.time() - start_time
-            if total_time > WARNING_THRESHOLD:
-                logger.warning(
-                    f"权限检查耗时过长: {total_time:.3f}s, "
-                    f"模块: {matcher.plugin_name}, 详情: {hook_times}",
-                    LOG_COMMAND,
-                    session=session,
-                )
-
-    async def _run_all_checks(
-        self,
-        result: AuthCheckResult,
-        auth_snapshot: AuthSnapshot,
-        plugin_snapshot: PluginSnapshot,
-        message: UniMsg,
-        session: Uninfo,
-        is_superuser: bool,
-    ):
-        """执行所有权限检查
-
-        所有检查都基于内存中的快照数据，无I/O操作
-        """
-        if is_superuser:
-            return
-        # 1. Ban检查（关键优先级）
-        self._check_ban(result, auth_snapshot, plugin_snapshot, is_superuser)
-        if not result.passed:
-            return
-
-        # 2. Bot状态检查（关键优先级）
-        self._check_bot_status(result, auth_snapshot, plugin_snapshot)
-        if not result.passed:
-            return
-
-        # 3. 插件全局状态检查（高优先级）
-        self._check_plugin_global_status(result, auth_snapshot, plugin_snapshot)
-        if not result.passed:
-            return
-
-        # 4. 群组状态检查（高优先级）
-        if auth_snapshot.group_id:
-            self._check_group_status(result, auth_snapshot, plugin_snapshot, message)
-            if not result.passed:
-                return
-        else:
-            # 私聊检查
-            self._check_private_status(result, plugin_snapshot)
-            if not result.passed:
-                return
-
-        # 5. 管理员权限检查（中优先级）
-        self._check_admin_level(result, auth_snapshot, plugin_snapshot)
-        if not result.passed:
-            return
-
-        # 6. 金币检查（低优先级）
-        self._check_gold(result, auth_snapshot, plugin_snapshot)
-
-    def _check_ban(
-        self,
-        result: AuthCheckResult,
-        auth_snapshot: AuthSnapshot,
-        plugin_snapshot: PluginSnapshot,
-        is_superuser: bool,
-    ):
-        """检查ban状态"""
-        # 超级用户不受ban限制
-        if is_superuser:
-            return
-
-        # 检查群组ban
-        if auth_snapshot.is_group_banned():
-            result.fail(f"群组: {auth_snapshot.group_id} 处于黑名单中...")
-            return
-
-        # 检查用户ban
-        if auth_snapshot.is_user_banned():
-            remaining = auth_snapshot.get_user_ban_remaining()
-            if remaining == -1:
-                result.fail("用户处于永久黑名单中...")
-            else:
-                result.fail(f"用户处于黑名单中，剩余 {remaining} 秒...")
-
-    def _check_bot_status(
-        self,
-        result: AuthCheckResult,
-        auth_snapshot: AuthSnapshot,
-        plugin_snapshot: PluginSnapshot,
-    ):
-        """检查Bot状态"""
-        if not auth_snapshot.bot_status:
-            result.fail("Bot不存在或休眠中阻断权限检测...")
-            return
-
-        if auth_snapshot.is_plugin_blocked_by_bot(plugin_snapshot.module):
-            result.fail(
-                f"Bot插件 {plugin_snapshot.name}({plugin_snapshot.module}) "
-                "权限检查结果为关闭..."
-            )
-
-    def _check_plugin_global_status(
-        self,
-        result: AuthCheckResult,
-        auth_snapshot: AuthSnapshot,
-        plugin_snapshot: PluginSnapshot,
-    ):
-        """检查插件全局状态"""
-        # 全局禁用检查
-        if not plugin_snapshot.status and plugin_snapshot.block_type == BlockType.ALL:
-            # 超级群组可以使用全局关闭的功能
-            if auth_snapshot.group_is_super:
-                return
-            result.fail(
-                f"{plugin_snapshot.name}({plugin_snapshot.module}) 全局未开启此功能..."
-            )
-
-    def _check_group_status(
-        self,
-        result: AuthCheckResult,
-        auth_snapshot: AuthSnapshot,
-        plugin_snapshot: PluginSnapshot,
-        message: UniMsg,
-    ):
-        """检查群组状态"""
-        # 群组不存在
-        if not auth_snapshot.group_exists:
-            result.fail("群组信息不存在...")
-            return
-
-        # 群组黑名单
-        if auth_snapshot.group_level < 0:
-            result.fail("群组黑名单, 目标群组群权限权限-1...")
-            return
-
-        # 群组休眠状态（除非是开启命令）
-        text = message.extract_plain_text().strip()
-        if text != "醒来" and not auth_snapshot.group_status:
-            result.fail("群组休眠状态...")
-            return
-
-        # 插件等级检查
-        if plugin_snapshot.level > auth_snapshot.group_level:
-            result.fail(
-                f"{plugin_snapshot.name}({plugin_snapshot.module}) 群等级限制，"
-                f"该功能需要的群等级: {plugin_snapshot.level}..."
-            )
-            return
-
-        # 超级用户禁用检查
-        if auth_snapshot.is_plugin_blocked_by_superuser(plugin_snapshot.module):
-            result.fail(
-                f"{plugin_snapshot.name}({plugin_snapshot.module}) "
-                "超级管理员禁用了该群此功能..."
-            )
-            return
-
-        # 普通禁用检查
-        if auth_snapshot.is_plugin_blocked_by_group(plugin_snapshot.module):
-            result.fail(
-                f"{plugin_snapshot.name}({plugin_snapshot.module}) 未开启此功能..."
-            )
-            return
-
-        # 群组禁用类型检查
-        if plugin_snapshot.block_type == BlockType.GROUP:
-            result.fail(
-                f"{plugin_snapshot.name}({plugin_snapshot.module}) "
-                "该插件在群组中已被禁用..."
-            )
-
-    def _check_private_status(
-        self,
-        result: AuthCheckResult,
-        plugin_snapshot: PluginSnapshot,
-    ):
-        """检查私聊状态"""
-        if plugin_snapshot.block_type == BlockType.PRIVATE:
-            result.fail(
-                f"{plugin_snapshot.name}({plugin_snapshot.module}) "
-                "该插件在私聊中已被禁用..."
-            )
-
-    def _check_admin_level(
-        self,
-        result: AuthCheckResult,
-        auth_snapshot: AuthSnapshot,
-        plugin_snapshot: PluginSnapshot,
-    ):
-        """检查管理员权限"""
-        if not plugin_snapshot.admin_level:
-            return
-
-        user_level = auth_snapshot.get_user_level()
-        if user_level < plugin_snapshot.admin_level:
-            result.fail(
-                f"{plugin_snapshot.name}({plugin_snapshot.module}) "
-                f"管理员权限不足，需要等级: {plugin_snapshot.admin_level}..."
-            )
-
-    def _check_gold(
-        self,
-        result: AuthCheckResult,
-        auth_snapshot: AuthSnapshot,
-        plugin_snapshot: PluginSnapshot,
-    ):
-        """检查金币"""
-        if plugin_snapshot.cost_gold <= 0:
-            return
-
-        if auth_snapshot.user_gold < plugin_snapshot.cost_gold:
-            result.fail(f"金币不足..该功能需要{plugin_snapshot.cost_gold}金币..")
-            return
-
-        # 记录需要扣除的金币
-        result.cost_gold = plugin_snapshot.cost_gold
-
-
-# 全局实例
-optimized_auth_checker = OptimizedAuthChecker()

zhenxun/services/auth_snapshot/models.py

@@ -1,263 +0,0 @@
-"""
-权限快照数据模型
-
-定义 AuthSnapshot 和 PluginSnapshot 的数据结构
-"""
-
-import time
-from typing import ClassVar
-
-from pydantic import BaseModel, Field
-
-from zhenxun.utils.enum import BlockType, PluginType
-
-
-class AuthSnapshot(BaseModel):
-    """权限快照数据模型
-
-    聚合了权限检查所需的所有用户、群组、Bot相关数据
-    """
-
-    # 快照标识
-    user_id: str
-    group_id: str | None = None
-    bot_id: str
-
-    # === 用户信息 ===
-    user_gold: int = 100
-    """用户金币"""
-    user_banned: int = 0
-    """0=未ban, -1=永久ban, >0=ban结束时间戳"""
-    user_ban_duration: int = 0
-    """ban时长（秒），-1为永久"""
-
-    # === 用户权限等级 ===
-    user_level_global: int = 0
-    """全局权限等级"""
-    user_level_group: int = 0
-    """群组内权限等级"""
-
-    # === 群组信息 ===
-    group_exists: bool = False
-    """群组是否存在（用于区分私聊和未知群组）"""
-    group_status: bool = True
-    """群组状态 (True=开启, False=休眠)"""
-    group_level: int = 5
-    """群组等级"""
-    group_is_super: bool = False
-    """是否超级群组（可以使用全局关闭的功能）"""
-    group_block_plugins: str = ""
-    """禁用插件列表，格式: "<plugin1,<plugin2," """
-    group_superuser_block_plugins: str = ""
-    """超级用户禁用插件列表"""
-
-    # === 群组ban状态 ===
-    group_banned: int = 0
-    """0=未ban, -1=永久ban, >0=ban结束时间戳"""
-
-    # === Bot信息 ===
-    bot_status: bool = True
-    """Bot状态"""
-    bot_block_plugins: str = ""
-    """Bot禁用插件列表，格式: "<plugin1,<plugin2," """
-
-    # === 元数据 ===
-    version: int = 1
-    """快照版本"""
-    created_at: float = Field(default_factory=time.time)
-    """创建时间戳"""
-
-    # === 类变量 ===
-    DEFAULT_TTL: ClassVar[int] = 60
-    """默认过期时间（秒）"""
-
-    def is_expired(self, ttl: int | None = None) -> bool:
-        """检查快照是否过期
-
-        参数:
-            ttl: 过期时间（秒），为None时使用默认值
-
-        返回:
-            bool: 是否过期
-        """
-        expire_ttl = ttl if ttl is not None else self.DEFAULT_TTL
-        return time.time() - self.created_at > expire_ttl
-
-    def is_user_banned(self) -> bool:
-        """检查用户是否被ban
-
-        返回:
-            bool: 用户是否被ban
-        """
-        if self.user_banned == 0:
-            return False
-        if self.user_banned == -1:
-            return True
-        # 检查ban是否过期
-        return time.time() < self.user_banned
-
-    def is_group_banned(self) -> bool:
-        """检查群组是否被ban
-
-        返回:
-            bool: 群组是否被ban
-        """
-        if self.group_banned == 0:
-            return False
-        if self.group_banned == -1:
-            return True
-        return time.time() < self.group_banned
-
-    def get_user_ban_remaining(self) -> int:
-        """获取用户ban剩余时间
-
-        返回:
-            int: 剩余时间（秒），-1表示永久，0表示未被ban
-        """
-        if self.user_banned == 0:
-            return 0
-        if self.user_banned == -1:
-            return -1
-        remaining = int(self.user_banned - time.time())
-        return max(remaining, 0)
-
-    def get_user_level(self) -> int:
-        """获取用户有效权限等级（取全局和群组的最大值）
-
-        返回:
-            int: 用户权限等级
-        """
-        return max(self.user_level_global, self.user_level_group)
-
-    def is_plugin_blocked_by_group(self, module: str) -> bool:
-        """检查插件是否被群组禁用
-
-        参数:
-            module: 插件模块名
-
-        返回:
-            bool: 是否被禁用
-        """
-        marker = f"<{module},"
-        return marker in self.group_block_plugins
-
-    def is_plugin_blocked_by_superuser(self, module: str) -> bool:
-        """检查插件是否被超级用户禁用
-
-        参数:
-            module: 插件模块名
-
-        返回:
-            bool: 是否被禁用
-        """
-        marker = f"<{module},"
-        return marker in self.group_superuser_block_plugins
-
-    def is_plugin_blocked_by_bot(self, module: str) -> bool:
-        """检查插件是否被Bot禁用
-
-        参数:
-            module: 插件模块名
-
-        返回:
-            bool: 是否被禁用
-        """
-        marker = f"<{module},"
-        return marker in self.bot_block_plugins
-
-
-class PluginSnapshot(BaseModel):
-    """插件快照数据模型
-
-    包含插件权限检查所需的所有配置信息
-    """
-
-    # 插件标识
-    module: str
-    """模块名"""
-    name: str = ""
-    """插件名称"""
-
-    # === 插件状态 ===
-    status: bool = True
-    """全局开关状态"""
-    block_type: BlockType | None = None
-    """禁用类型 (PRIVATE/GROUP/ALL/None)"""
-    plugin_type: PluginType | None = None
-    """插件类型"""
-
-    # === 权限要求 ===
-    admin_level: int = 0
-    """调用所需权限等级"""
-    cost_gold: int = 0
-    """调用所需金币"""
-    level: int = 5
-    """所需群权限等级"""
-    limit_superuser: bool = False
-    """是否限制超级用户"""
-
-    # === 显示配置 ===
-    ignore_prompt: bool = False
-    """是否忽略阻断提示"""
-
-    # === 元数据 ===
-    created_at: float = Field(default_factory=time.time)
-    """创建时间戳"""
-
-    # === 类变量 ===
-    DEFAULT_TTL: ClassVar[int] = 300
-    """默认过期时间（秒）"""
-    MEMORY_TTL: ClassVar[int] = 30
-    """本地内存缓存过期时间（秒）"""
-
-    def is_expired(self, ttl: int | None = None) -> bool:
-        """检查快照是否过期
-
-        参数:
-            ttl: 过期时间（秒），为None时使用默认值
-
-        返回:
-            bool: 是否过期
-        """
-        expire_ttl = ttl if ttl is not None else self.DEFAULT_TTL
-        return time.time() - self.created_at > expire_ttl
-
-    def is_hidden(self) -> bool:
-        """检查是否为隐藏插件
-
-        返回:
-            bool: 是否隐藏
-        """
-        return self.plugin_type == PluginType.HIDDEN
-
-    def is_superuser_plugin(self) -> bool:
-        """检查是否为超级用户插件
-
-        返回:
-            bool: 是否为超级用户插件
-        """
-        return self.plugin_type == PluginType.SUPERUSER
-
-    def is_globally_disabled(self) -> bool:
-        """检查是否全局禁用
-
-        返回:
-            bool: 是否全局禁用
-        """
-        return not self.status and self.block_type == BlockType.ALL
-
-    def is_disabled_in_group(self) -> bool:
-        """检查是否在群组中禁用
-
-        返回:
-            bool: 是否在群组中禁用
-        """
-        return self.block_type == BlockType.GROUP
-
-    def is_disabled_in_private(self) -> bool:
-        """检查是否在私聊中禁用
-
-        返回:
-            bool: 是否在私聊中禁用
-        """
-        return self.block_type == BlockType.PRIVATE

zhenxun/services/auth_snapshot/service.py

@@ -1,466 +0,0 @@
-"""
-快照服务
-
-提供权限快照的获取、缓存、失效等功能
-"""
-
-import asyncio
-from typing import ClassVar
-
-from zhenxun.services.cache import CacheRoot, cache_config
-from zhenxun.services.cache.cache_containers import CacheDict
-from zhenxun.services.cache.config import CacheMode
-from zhenxun.services.log import logger
-from zhenxun.utils.enum import CacheType
-
-from .builder import SnapshotBuilder
-from .models import AuthSnapshot, PluginSnapshot
-
-LOG_COMMAND = "auth_snapshot"
-
-# 内存缓存名称（CacheType 已提供 Redis 前缀，此处仅用于内存缓存标识）
-AUTH_MEMORY_CACHE_NAME = "AUTH_MEMORY"
-PLUGIN_MEMORY_CACHE_NAME = "PLUGIN_MEMORY"
-
-# 内存缓存TTL配置
-AUTH_MEMORY_TTL = 10  # 权限快照内存缓存TTL（秒）
-AUTH_REDIS_TTL = 60  # 权限快照Redis缓存TTL（秒）
-PLUGIN_MEMORY_TTL = 30  # 插件快照内存缓存TTL（秒）
-PLUGIN_REDIS_TTL = 300  # 插件快照Redis缓存TTL（秒）
-
-# 并发控制配置
-MAX_CONCURRENT_BUILDS = 15  # 最大同时构建数量（防止 DB 过载）
-BUILD_QUEUE_TIMEOUT = 5.0  # 等待构建队列的超时时间（秒）
-
-
-class AuthSnapshotService:
-    """权限快照服务
-
-    提供权限快照的获取、缓存和失效管理
-    """
-
-    # 本地内存缓存（使用 CacheDict，自动处理过期）
-    _memory_cache: ClassVar[CacheDict[AuthSnapshot] | None] = None
-
-    # 正在构建中的快照（防止并发重复构建）
-    _building: ClassVar[dict[str, asyncio.Future]] = {}
-
-    # per-key 锁（保护 _building 的检查和设置，防止竞态条件）
-    _build_locks: ClassVar[dict[str, asyncio.Lock]] = {}
-
-    # 全局构建并发限制（防止大量不同 key 同时构建导致 DB 过载）
-    _build_semaphore: ClassVar[asyncio.Semaphore | None] = None
-
-    @classmethod
-    def _get_build_semaphore(cls) -> asyncio.Semaphore:
-        """获取构建信号量（懒加载）"""
-        if cls._build_semaphore is None:
-            cls._build_semaphore = asyncio.Semaphore(MAX_CONCURRENT_BUILDS)
-        return cls._build_semaphore
-
-    @classmethod
-    def _get_memory_cache(cls) -> CacheDict[AuthSnapshot]:
-        """获取内存缓存实例（懒加载）"""
-        if cls._memory_cache is None:
-            cls._memory_cache = CacheRoot.cache_dict(
-                AUTH_MEMORY_CACHE_NAME,
-                expire=AUTH_MEMORY_TTL,
-                value_type=AuthSnapshot,
-            )
-        return cls._memory_cache
-
-    @classmethod
-    def _build_cache_key(cls, user_id: str, group_id: str | None, bot_id: str) -> str:
-        """构建缓存键（CacheType 已提供前缀，此处只需业务标识）"""
-        group_part = group_id or "PRIVATE"
-        return f"{user_id}:{group_part}:{bot_id}"
-
-    @classmethod
-    async def get_snapshot(
-        cls,
-        user_id: str,
-        group_id: str | None,
-        bot_id: str,
-        force_refresh: bool = False,
-    ) -> AuthSnapshot:
-        """获取权限快照
-
-        优先从缓存获取，缓存未命中时构建新快照
-
-        参数:
-            user_id: 用户ID
-            group_id: 群组ID（可为None）
-            bot_id: Bot ID
-            force_refresh: 是否强制刷新
-
-        返回:
-            AuthSnapshot: 权限快照
-        """
-        cache_key = cls._build_cache_key(user_id, group_id, bot_id)
-
-        memory_cache = cls._get_memory_cache()
-
-        # 1. 尝试从内存缓存获取（最快路径）
-        if not force_refresh:
-            if snapshot := memory_cache.get(cache_key):
-                return snapshot
-
-        # 2. 尝试从Redis获取
-        if not force_refresh and cache_config.cache_mode != CacheMode.NONE:
-            try:
-                cached = await CacheRoot.get(CacheType.AUTH_SNAPSHOT, cache_key)
-                if cached and isinstance(cached, dict):
-                    snapshot = AuthSnapshot.model_validate(cached)
-                    if not snapshot.is_expired(AUTH_REDIS_TTL):
-                        memory_cache.set(cache_key, snapshot)
-                        return snapshot
-            except Exception as e:
-                logger.debug(f"从Redis获取快照失败: {cache_key}", LOG_COMMAND, e=e)
-
-        # 3. 获取或创建 per-key 锁（使用 setdefault 保证原子性）
-        lock = cls._build_locks.setdefault(cache_key, asyncio.Lock())
-
-        # 4. 先尝试快速路径：检查是否有其他协程正在构建
-        if cache_key in cls._building:
-            try:
-                return await cls._building[cache_key]
-            except Exception:
-                pass
-
-        # 5. 获取信号量（控制总并发数，不在锁内等待）
-        semaphore = cls._get_build_semaphore()
-        try:
-            await asyncio.wait_for(semaphore.acquire(), timeout=BUILD_QUEUE_TIMEOUT)
-        except asyncio.TimeoutError:
-            logger.warning(f"获取信号量超时，使用默认快照: {cache_key}", LOG_COMMAND)
-            return AuthSnapshot(user_id=user_id, group_id=group_id, bot_id=bot_id)
-
-        need_build = False
-        future: asyncio.Future[AuthSnapshot] | None = None
-
-        try:
-            # 6. 获取 per-key 锁，只保护 _building 的检查和设置
-            async with lock:
-                # 再次检查缓存
-                if snapshot := memory_cache.get(cache_key):
-                    return snapshot
-
-                # 检查是否有其他协程正在构建
-                if cache_key in cls._building:
-                    future = cls._building[cache_key]
-                else:
-                    # 创建 future 并设置到 _building（在锁内）
-                    loop = asyncio.get_running_loop()
-                    future = loop.create_future()
-                    cls._building[cache_key] = future
-                    need_build = True
-
-            # 7. 锁外执行（构建或等待）
-            if need_build:
-                return await cls._do_build_with_future(
-                    user_id, group_id, bot_id, cache_key, future
-                )
-            else:
-                # 等待其他协程的构建结果
-                return await future  # type: ignore
-        finally:
-            semaphore.release()
-
-    @classmethod
-    async def _do_build_with_future(
-        cls,
-        user_id: str,
-        group_id: str | None,
-        bot_id: str,
-        cache_key: str,
-        future: asyncio.Future[AuthSnapshot],
-    ) -> AuthSnapshot:
-        """执行快照构建（future 已在锁内设置到 _building）"""
-        try:
-            # 构建快照
-            snapshot = await SnapshotBuilder.build_auth_snapshot(
-                user_id, group_id, bot_id
-            )
-
-            # 存入Redis缓存（异步，不阻塞）
-            if cache_config.cache_mode != CacheMode.NONE:
-                asyncio.create_task(  # noqa: RUF006
-                    cls._cache_to_redis(cache_key, snapshot)
-                )
-
-            # 存入内存缓存
-            cls._get_memory_cache().set(cache_key, snapshot)
-
-            future.set_result(snapshot)
-            return snapshot
-
-        except Exception as e:
-            future.set_exception(e)
-            raise
-        finally:
-            cls._building.pop(cache_key, None)
-
-    @classmethod
-    async def _cache_to_redis(cls, cache_key: str, snapshot: AuthSnapshot):
-        """异步存入Redis"""
-        try:
-            await CacheRoot.set(
-                CacheType.AUTH_SNAPSHOT,
-                cache_key,
-                snapshot.model_dump(),
-                expire=AUTH_REDIS_TTL,
-            )
-        except Exception as e:
-            logger.debug(f"缓存权限快照到Redis失败: {cache_key}", LOG_COMMAND, e=e)
-
-    @classmethod
-    async def invalidate_user(cls, user_id: str):
-        """失效用户相关的所有快照
-
-        参数:
-            user_id: 用户ID
-        """
-        # 清理内存缓存（遍历 CacheDict 的 keys）
-        memory_cache = cls._get_memory_cache()
-        keys_to_delete = [k for k in memory_cache.keys() if f":{user_id}:" in k]
-        for key in keys_to_delete:
-            del memory_cache[key]
-
-        logger.debug(f"已失效用户 {user_id} 的权限快照缓存", LOG_COMMAND)
-
-    @classmethod
-    async def invalidate_group(cls, group_id: str):
-        """失效群组相关的所有快照
-
-        参数:
-            group_id: 群组ID
-        """
-        # 清理内存缓存
-        memory_cache = cls._get_memory_cache()
-        keys_to_delete = [k for k in memory_cache.keys() if f":{group_id}:" in k]
-        for key in keys_to_delete:
-            del memory_cache[key]
-
-        logger.debug(f"已失效群组 {group_id} 的权限快照缓存", LOG_COMMAND)
-
-    @classmethod
-    async def invalidate_bot(cls, bot_id: str):
-        """失效Bot相关的所有快照
-
-        参数:
-            bot_id: Bot ID
-        """
-        # 清理内存缓存
-        memory_cache = cls._get_memory_cache()
-        keys_to_delete = [k for k in memory_cache.keys() if k.endswith(f":{bot_id}")]
-        for key in keys_to_delete:
-            del memory_cache[key]
-
-        logger.debug(f"已失效Bot {bot_id} 的权限快照缓存", LOG_COMMAND)
-
-    @classmethod
-    def clear_all_cache(cls):
-        """清空所有缓存"""
-        if cls._memory_cache:
-            cls._memory_cache.clear()
-        cls._building.clear()
-        cls._build_locks.clear()
-        logger.info("已清空所有权限快照缓存", LOG_COMMAND)
-
-
-class PluginSnapshotService:
-    """插件快照服务
-
-    提供插件信息的获取和缓存，支持本地内存缓存 + Redis 双层缓存
-    """
-
-    # 本地内存缓存（使用 CacheDict）
-    _memory_cache: ClassVar[CacheDict[PluginSnapshot] | None] = None
-
-    # 正在构建中的快照
-    _building: ClassVar[dict[str, asyncio.Future]] = {}
-
-    @classmethod
-    def _get_memory_cache(cls) -> CacheDict[PluginSnapshot]:
-        """获取内存缓存实例（懒加载）"""
-        if cls._memory_cache is None:
-            cls._memory_cache = CacheRoot.cache_dict(
-                PLUGIN_MEMORY_CACHE_NAME,
-                expire=PLUGIN_MEMORY_TTL,
-                value_type=PluginSnapshot,
-            )
-        return cls._memory_cache
-
-    @classmethod
-    def _build_cache_key(cls, module: str) -> str:
-        """构建缓存键（CacheType 已提供前缀，此处只需模块名）"""
-        return module
-
-    @classmethod
-    async def get_plugin(
-        cls, module: str, force_refresh: bool = False
-    ) -> PluginSnapshot | None:
-        """获取插件快照
-
-        参数:
-            module: 插件模块名
-            force_refresh: 是否强制刷新
-
-        返回:
-            PluginSnapshot | None: 插件快照，不存在时返回None
-        """
-        cache_key = cls._build_cache_key(module)
-        memory_cache = cls._get_memory_cache()
-
-        # 1. 尝试从内存缓存获取（最快路径）
-        if not force_refresh:
-            if snapshot := memory_cache.get(cache_key):
-                return snapshot
-
-        # 2. 尝试从Redis获取
-        if not force_refresh and cache_config.cache_mode != CacheMode.NONE:
-            try:
-                cached = await CacheRoot.get(CacheType.PLUGIN_SNAPSHOT, cache_key)
-                if cached and isinstance(cached, dict):
-                    snapshot = PluginSnapshot.model_validate(cached)
-                    if not snapshot.is_expired(PLUGIN_REDIS_TTL):
-                        memory_cache.set(cache_key, snapshot)
-                        return snapshot
-            except Exception as e:
-                logger.debug(f"从Redis获取插件快照失败: {module}", LOG_COMMAND, e=e)
-
-        # 3. 检查是否有其他协程正在构建
-        if cache_key in cls._building:
-            try:
-                return await cls._building[cache_key]
-            except Exception:
-                pass
-
-        # 4. 从数据库构建（插件数量有限，无需信号量）
-        return await cls._do_build(module, cache_key)
-
-    @classmethod
-    async def _do_build(cls, module: str, cache_key: str) -> PluginSnapshot | None:
-        """执行插件快照构建"""
-        loop = asyncio.get_running_loop()
-        future: asyncio.Future[PluginSnapshot | None] = loop.create_future()
-        cls._building[cache_key] = future
-
-        try:
-            snapshot = await SnapshotBuilder.build_plugin_snapshot(module)
-
-            if snapshot:
-                # 存入Redis缓存（异步）
-                if cache_config.cache_mode != CacheMode.NONE:
-                    asyncio.create_task(  # noqa: RUF006
-                        cls._cache_to_redis(cache_key, snapshot)
-                    )
-
-                # 存入内存缓存
-                cls._get_memory_cache().set(cache_key, snapshot)
-
-            future.set_result(snapshot)
-            return snapshot
-
-        except Exception as e:
-            future.set_exception(e)
-            raise
-        finally:
-            cls._building.pop(cache_key, None)
-
-    @classmethod
-    async def _cache_to_redis(cls, cache_key: str, snapshot: PluginSnapshot):
-        """异步存入Redis"""
-        try:
-            await CacheRoot.set(
-                CacheType.PLUGIN_SNAPSHOT,
-                cache_key,
-                snapshot.model_dump(),
-                expire=PLUGIN_REDIS_TTL,
-            )
-        except Exception as e:
-            logger.debug(f"缓存插件快照到Redis失败: {cache_key}", LOG_COMMAND, e=e)
-
-    @classmethod
-    async def invalidate_plugin(cls, module: str):
-        """失效指定插件的缓存
-
-        参数:
-            module: 插件模块名
-        """
-        cache_key = cls._build_cache_key(module)
-
-        # 清理内存缓存
-        memory_cache = cls._get_memory_cache()
-        if cache_key in memory_cache.keys():
-            del memory_cache[cache_key]
-
-        # 清理Redis缓存
-        if cache_config.cache_mode != CacheMode.NONE:
-            try:
-                await CacheRoot.delete(CacheType.PLUGIN_SNAPSHOT, cache_key)
-            except Exception:
-                pass
-
-        logger.debug(f"已失效插件 {module} 的快照缓存", LOG_COMMAND)
-
-    @classmethod
-    async def warmup(cls):
-        """预热所有插件缓存
-
-        在启动时调用，预加载所有插件信息到缓存
-        同时写入内存缓存和 Redis 缓存
-        """
-        from zhenxun.models.plugin_info import PluginInfo
-
-        memory_cache = cls._get_memory_cache()
-
-        try:
-            plugins = await PluginInfo.filter(load_status=True).all()
-            count = 0
-
-            for plugin in plugins:
-                snapshot = PluginSnapshot(
-                    module=plugin.module,
-                    name=plugin.name,
-                    status=plugin.status,
-                    block_type=plugin.block_type,
-                    plugin_type=plugin.plugin_type,
-                    admin_level=plugin.admin_level or 0,
-                    cost_gold=plugin.cost_gold,
-                    level=plugin.level,
-                    limit_superuser=plugin.limit_superuser,
-                    ignore_prompt=plugin.ignore_prompt,
-                )
-
-                cache_key = cls._build_cache_key(plugin.module)
-
-                # 存入内存缓存（最快访问路径）
-                memory_cache.set(cache_key, snapshot)
-
-                # 同时存入 Redis 缓存（跨进程共享）
-                if cache_config.cache_mode != CacheMode.NONE:
-                    try:
-                        await CacheRoot.set(
-                            CacheType.PLUGIN_SNAPSHOT,
-                            cache_key,
-                            snapshot,
-                            expire=PLUGIN_REDIS_TTL,
-                        )
-                    except Exception:
-                        pass  # Redis 写入失败不影响预热
-
-                count += 1
-
-            logger.info(f"已预热 {count} 个插件的快照缓存", LOG_COMMAND)
-
-        except Exception as e:
-            logger.error("预热插件缓存失败", LOG_COMMAND, e=e)
-
-    @classmethod
-    def clear_all_cache(cls):
-        """清空所有缓存"""
-        if cls._memory_cache:
-            cls._memory_cache.clear()
-        cls._building.clear()
-        logger.info("已清空所有插件快照缓存", LOG_COMMAND)

zhenxun/services/cache/__init__.py

@@ -599,6 +599,8 @@ class CacheManager:
         返回:
             bool: 是否成功
         """
+        from zhenxun.services.db_context import DB_TIMEOUT_SECONDS
+
         # 如果缓存被禁用或缓存模式为NONE，直接返回False
         if not self.enabled or cache_config.cache_mode == CacheMode.NONE:
             return False
@@ -613,17 +615,14 @@ class CacheManager:
             # 设置过期时间
             ttl = expire if expire is not None else model.expire
 
-            # 设置缓存（使用较短的超时时间，避免阻塞主流程）
+            # 设置缓存
             await asyncio.wait_for(
                 self.cache_backend.set(cache_key, serialized_value, ttl=ttl),  # type: ignore
-                timeout=min(CACHE_TIMEOUT, 2.0),  # 最多2秒，避免阻塞太久
+                timeout=DB_TIMEOUT_SECONDS,
             )
             return True
         except asyncio.TimeoutError:
-            logger.warning(
+            logger.error(f"设置缓存 {cache_type}:{cache_key} 超时", LOG_COMMAND)
-                f"设置缓存 {cache_type}:{cache_key} 超时（已跳过，不影响主流程）",
-                LOG_COMMAND,
-            )
             return False
         except Exception as e:
             logger.error(f"设置缓存 {cache_type} 失败", LOG_COMMAND, e=e)
@@ -708,7 +707,7 @@ class CacheManager:
         if self._cache_backend:
             try:
                 await self._cache_backend.close()  # type: ignore
-            except Exception as e:
+            except (AttributeError, Exception) as e:
                 logger.warning(f"关闭缓存连接失败: {e}", LOG_COMMAND)
             self._cache_backend = None
 

zhenxun/services/cache/cache_containers.py

@@ -138,15 +138,6 @@ class CacheDict(Generic[T]):
 
         return data.value
 
-    def delete(self, key: str) -> None:
-        """删除字典项
-
-        参数:
-            key: 字典键
-        """
-        if key in self._data:
-            del self._data[key]
-
     def clear(self) -> None:
         """清空字典"""
         self._data.clear()

zhenxun/services/data_access.py

@@ -1,4 +1,3 @@
-import asyncio
 from typing import Any, ClassVar, Generic, TypeVar, cast
 
 from zhenxun.services.cache import Cache, CacheRoot, cache_config
@@ -213,13 +212,9 @@ class DataAccess(Generic[T]):
         except Exception as e:
             logger.error(f"{self.model_cls.__name__} 从缓存获取数据失败: {kwargs}", e=e)
 
-        # 如果缓存中没有，从数据库获取（使用超时控制）
+        # 如果缓存中没有，从数据库获取
         logger.debug(f"{self.model_cls.__name__} 从数据库获取数据: {kwargs}")
-        data = await with_db_timeout(
+        data = await db_query_func(*args, **kwargs)
-            db_query_func(*args, **kwargs),
-            operation=f"{self.model_cls.__name__}.{db_query_func.__name__}",
-            source="DataAccess._get_with_cache",
-        )
 
         # 如果获取到数据，存入缓存
         if data:
@@ -227,48 +222,31 @@ class DataAccess(Generic[T]):
                 # 生成缓存键
                 cache_key = self._build_cache_key_for_item(data)
                 if cache_key is not None:
-                    # 存入缓存（失败不影响主流程）
+                    # 存入缓存
-                    try:
+                    await self.cache.set(cache_key, data)
-                        # 使用较短的超时时间，避免阻塞
+                    self._cache_stats[self.cache_type]["sets"] += 1
-                        await asyncio.wait_for(
+                    logger.debug(
-                            self.cache.set(cache_key, data), timeout=1.0
+                        f"{self.model_cls.__name__} 数据已存入缓存: {cache_key}"
-                        )
+                    )
-                        self._cache_stats[self.cache_type]["sets"] += 1
-                        logger.debug(
-                            f"{self.model_cls.__name__} 数据已存入缓存: {cache_key}"
-                        )
-                    except (asyncio.TimeoutError, Exception) as cache_err:
-                        # 缓存设置失败不影响数据返回，只记录警告
-                        logger.warning(
-                            f"{self.model_cls.__name__} 存入缓存失败（超时或异常），"
-                            f"参数: {kwargs}",
-                            e=cache_err,
-                        )
             except Exception as e:
                 logger.error(
                     f"{self.model_cls.__name__} 存入缓存失败，参数: {kwargs}", e=e
                 )
         elif cache_key is not None:
-            # 如果没有获取到数据，缓存空结果（失败不影响主流程）
+            # 如果没有获取到数据，缓存空结果
             try:
-                # 存入空结果缓存，使用较短的过期时间和超时时间
+                # 存入空结果缓存，使用较短的过期时间
-                await asyncio.wait_for(
+                await self.cache.set(
-                    self.cache.set(
+                    cache_key, self._NULL_RESULT, expire=self._NULL_RESULT_TTL
-                        cache_key, self._NULL_RESULT, expire=self._NULL_RESULT_TTL
-                    ),
-                    timeout=1.0,
                 )
                 self._cache_stats[self.cache_type]["null_sets"] += 1
                 logger.debug(
                     f"{self.model_cls.__name__} 空结果已存入缓存: {cache_key},"
                     f" TTL={self._NULL_RESULT_TTL}秒"
                 )
-            except (asyncio.TimeoutError, Exception) as cache_err:
+            except Exception as e:
-                # 空结果缓存设置失败不影响数据返回，只记录警告
+                logger.error(
-                logger.warning(
+                    f"{self.model_cls.__name__} 存入空结果缓存失败，参数: {kwargs}", e=e
-                    f"{self.model_cls.__name__} 存入空结果缓存失败（超时或异常），"
-                    f"参数: {kwargs}",
-                    e=cache_err,
                 )
 
         return data

zhenxun/services/db_context/base_model.py

@@ -7,6 +7,7 @@ from typing_extensions import Self
 from tortoise.backends.base.client import BaseDBAsyncClient
 from tortoise.exceptions import IntegrityError, MultipleObjectsReturned
 from tortoise.models import Model as TortoiseModel
+from tortoise.transactions import in_transaction
 
 from zhenxun.services.cache import CacheRoot
 from zhenxun.services.log import logger
@@ -21,13 +22,8 @@ class Model(TortoiseModel):
     增强的ORM基类，解决锁嵌套问题
     """
 
-    # sem_data[cls][lock_type] 可以是 Semaphore（全局）
+    sem_data: ClassVar[dict[str, dict[str, asyncio.Semaphore]]] = {}
-    # 或 dict[key, Semaphore]（按键）
+    _current_locks: ClassVar[dict[int, DbLockType]] = {}  # 跟踪当前协程持有的锁
-    sem_data: ClassVar[dict[type["Model"], dict[DbLockType, Any]]] = {}
-    # 跟踪当前协程持有的锁集合 {(cls, lock_type, lock_key), ...}
-    _current_locks: ClassVar[
-        dict[int, set[tuple[type["Model"], DbLockType, Any | None]]]
-    ] = {}
 
     def __init_subclass__(cls, **kwargs):
         super().__init_subclass__(**kwargs)
@@ -81,100 +77,44 @@ class Model(TortoiseModel):
         return None
 
     @classmethod
-    def get_semaphore(cls, lock_type: DbLockType, lock_key: Any | None = None):
+    def get_semaphore(cls, lock_type: DbLockType):
-        """
+        enable_lock = getattr(cls, "enable_lock", None)
-        获取信号量
+        if not enable_lock or lock_type not in enable_lock:
-
-        设计约定（弃用 enable_lock，仅通过 lock_fields 控制是否启用锁）:
-        - 如果未配置 lock_fields，或其中不存在对应 lock_type，则不加锁
-        - 如果 lock_fields[lock_type] 配置了按字段的锁（如 tuple[str, ...]），
-          则调用处按字段值生成 lock_key，在此为不同 lock_key
-          分配不同信号量，实现「按键」互斥
-        - 如仅需全局锁，可在 lock_fields 中声明该 lock_type，
-          且在 _lock_context 传入 lock_key=None
-        """
-        lock_fields: dict[DbLockType, Any] = getattr(cls, "lock_fields", {}) or {}
-        # 未在 lock_fields 中声明的 lock_type 不加锁
-        if lock_type not in lock_fields:
             return None
 
-        cls_sem = cls.sem_data.setdefault(cls, {})
+        if cls.__name__ not in cls.sem_data:
-
+            cls.sem_data[cls.__name__] = {}
-        # 配置了按字段的锁并且提供了具体的 lock_key 时，使用「按键」锁
+        if lock_type not in cls.sem_data[cls.__name__]:
-        if lock_key is not None:
+            cls.sem_data[cls.__name__][lock_type] = asyncio.Semaphore(1)
-            keyed = cls_sem.setdefault(lock_type, {})
+        return cls.sem_data[cls.__name__][lock_type]
-            if not isinstance(keyed, dict):
-                # 兼容历史数据，重置为按键字典
-                keyed = {}
-                cls_sem[lock_type] = keyed
-            if lock_key not in keyed:
-                keyed[lock_key] = asyncio.Semaphore(1)
-            return keyed[lock_key]
-
-        # 默认全局锁
-        sem = cls_sem.get(lock_type)
-        if not isinstance(sem, asyncio.Semaphore):
-            sem = asyncio.Semaphore(1)
-            cls_sem[lock_type] = sem
-        return sem
 
     @classmethod
-    def _require_lock(cls, lock_type: DbLockType, lock_key: Any | None) -> bool:
+    def _require_lock(cls, lock_type: DbLockType) -> bool:
         """检查是否需要真正加锁"""
         task_id = id(asyncio.current_task())
-        held = cls._current_locks.get(task_id)
+        return cls._current_locks.get(task_id) != lock_type
-        if not held:
-            return True
-        # 同一协程内，如果已经持有完全相同的一把锁
-        # （同一模型 + 同一 lock_type + 同一 lock_key），视为重入，
-        # 不再重复加锁，避免自锁
-        return (cls, lock_type, lock_key) not in held
 
     @classmethod
     @contextlib.asynccontextmanager
-    async def _lock_context(cls, lock_type: DbLockType, lock_key: Any | None = None):
+    async def _lock_context(cls, lock_type: DbLockType):
         """带重入检查的锁上下文"""
         task_id = id(asyncio.current_task())
-        need_lock = cls._require_lock(lock_type, lock_key)
+        need_lock = cls._require_lock(lock_type)
 
-        if not need_lock:
+        if need_lock and (sem := cls.get_semaphore(lock_type)):
-            # 已经持有这把锁，直接透传，支持可重入
+            cls._current_locks[task_id] = lock_type
-            yield
-            return
-
-        sem = cls.get_semaphore(lock_type, lock_key)
-        if not sem:
-            # 对于未启用锁的场景，直接继续执行
-            yield
-            return
-
-        lock_id = (cls, lock_type, lock_key)
-        held = cls._current_locks.setdefault(task_id, set())
-        held.add(lock_id)
-        try:
             async with sem:
                 yield
-        finally:
+            cls._current_locks.pop(task_id, None)
-            # 安全移除当前锁记录
+        else:
-            held.discard(lock_id)
+            yield
-            if not held:
-                cls._current_locks.pop(task_id, None)
 
     @classmethod
     async def create(
         cls, using_db: BaseDBAsyncClient | None = None, **kwargs: Any
     ) -> Self:
         """创建数据（使用CREATE锁）"""
-        lock_fields: dict[DbLockType, Any] = getattr(cls, "lock_fields", {}) or {}
+        async with cls._lock_context(DbLockType.CREATE):
-        lock_key = None
-        if field := lock_fields.get(DbLockType.CREATE):
-            if isinstance(field, tuple):
-                key_tuple = tuple(kwargs.get(f) for f in field)
-                lock_key = key_tuple if any(v is not None for v in key_tuple) else None
-            else:
-                lock_key = kwargs.get(field)
-
-        async with cls._lock_context(DbLockType.CREATE, lock_key):
             # 直接调用父类的_create方法避免触发save的锁
             result = await super().create(using_db=using_db, **kwargs)
             if cache_type := cls.get_cache_type():
@@ -203,51 +143,24 @@ class Model(TortoiseModel):
         using_db: BaseDBAsyncClient | None = None,
         **kwargs: Any,
     ) -> tuple[Self, bool]:
-        """更新或创建数据（优化版本，减少锁等待）"""
+        """更新或创建数据（使用UPSERT锁）"""
-        lock_fields: dict[DbLockType, Any] = getattr(cls, "lock_fields", {}) or {}
+        async with cls._lock_context(DbLockType.UPSERT):
-        lock_key = None
-        if field := lock_fields.get(DbLockType.UPSERT):
-            if isinstance(field, tuple):
-                key_tuple = tuple(kwargs.get(f) for f in field)
-                lock_key = key_tuple if any(v is not None for v in key_tuple) else None
-            else:
-                lock_key = kwargs.get(field)
-
-        async with cls._lock_context(DbLockType.UPSERT, lock_key):
             try:
-                # 优化：先尝试无锁查询，大部分情况数据已存在
+                # 先尝试更新（带行锁）
-                if obj := await cls.get_or_none(**kwargs):
+                async with in_transaction():
-                    if defaults:
+                    if obj := await cls.filter(**kwargs).select_for_update().first():
-                        await obj.update_from_dict(defaults)
+                        await obj.update_from_dict(defaults or {})
-                        # 只更新指定字段，减少写操作
+                        await obj.save()
-                        await obj.save(update_fields=list(defaults.keys()))
+                        result = (obj, False)
-                    if cache_type := cls.get_cache_type():
+                    else:
-                        await CacheRoot.invalidate_cache(
+                        # 创建时不重复加锁
-                            cache_type, cls.get_cache_key(obj)
+                        result = await cls.create(**kwargs, **(defaults or {})), True
-                        )
-                    return obj, False
 
-                # 数据不存在，尝试创建（依赖数据库唯一约束）
+                if cache_type := cls.get_cache_type():
-                try:
+                    await CacheRoot.invalidate_cache(
-                    obj = await super().create(
+                        cache_type, cls.get_cache_key(result[0])
-                        using_db=using_db, **kwargs, **(defaults or {})
                     )
-                    if cache_type := cls.get_cache_type():
+                return result
-                        await CacheRoot.invalidate_cache(
-                            cache_type, cls.get_cache_key(obj)
-                        )
-                    return obj, True
-                except IntegrityError:
-                    # 并发创建冲突，重新获取并更新
-                    obj = await cls.get(**kwargs)
-                    if defaults:
-                        await obj.update_from_dict(defaults)
-                        await obj.save(update_fields=list(defaults.keys()))
-                    if cache_type := cls.get_cache_type():
-                        await CacheRoot.invalidate_cache(
-                            cache_type, cls.get_cache_key(obj)
-                        )
-                    return obj, False
             except IntegrityError:
                 # 处理极端情况下的唯一约束冲突
                 obj = await cls.get(**kwargs)

zhenxun/services/db_context/config.py

@@ -3,7 +3,7 @@ from collections.abc import Callable
 from pydantic import BaseModel
 
 # 数据库操作超时设置（秒）
-DB_TIMEOUT_SECONDS = 5.0
+DB_TIMEOUT_SECONDS = 3.0
 
 # 性能监控阈值（秒）
 SLOW_QUERY_THRESHOLD = 0.5

zhenxun/services/group_settings_service.py

@@ -1,223 +0,0 @@
-from typing import Any, TypeVar, overload
-
-from pydantic import BaseModel, ValidationError
-import ujson as json
-
-from zhenxun.configs.config import Config
-from zhenxun.models.group_plugin_setting import GroupPluginSetting
-from zhenxun.services.cache import Cache
-from zhenxun.services.data_access import DataAccess
-from zhenxun.services.log import logger
-from zhenxun.utils.pydantic_compat import model_dump, model_validate, parse_as
-
-T = TypeVar("T", bound=BaseModel)
-
-
-class GroupSettingsService:
-    """
-    一个用于管理插件分群配置的服务。
-    集成了聚合缓存、批量操作和版本迁移功能。
-    """
-
-    def __init__(self):
-        self.dao = DataAccess(GroupPluginSetting)
-        self._cache = Cache[dict]("group_plugin_settings")
-
-    async def set(
-        self, group_id: str, plugin_name: str, settings_model: BaseModel
-    ) -> None:
-        """
-        为一个插件在指定群组中设置完整的配置模型。
-
-        参数:
-            group_id: 目标群组ID。
-            plugin_name: 插件的模块名。
-            settings_model: 包含完整配置的Pydantic模型实例。
-        """
-        settings_dict = model_dump(settings_model)
-        json_value = json.dumps(settings_dict, ensure_ascii=False)
-
-        await self.dao.update_or_create(
-            defaults={"settings": json_value},  # type: ignore
-            group_id=group_id,
-            plugin_name=plugin_name,
-        )
-
-        await self.dao.clear_cache(group_id=group_id, plugin_name=plugin_name)
-
-    async def set_key_value(
-        self, group_id: str, plugin_name: str, key: str, value: Any
-    ) -> None:
-        """为一个插件在指定群组中设置单个配置项的值。"""
-        setting_entry, _ = await GroupPluginSetting.get_or_create(
-            defaults={"settings": {}},
-            group_id=group_id,
-            plugin_name=plugin_name,
-        )
-
-        if not isinstance(setting_entry.settings, dict):
-            setting_entry.settings = {}
-
-        setting_entry.settings[key] = value
-        await setting_entry.save(update_fields=["settings"])
-        await self.dao.clear_cache(group_id=group_id, plugin_name=plugin_name)
-
-    async def reset_key(self, group_id: str, plugin_name: str, key: str) -> bool:
-        """重置单个配置项"""
-        setting = await self.dao.get_or_none(group_id=group_id, plugin_name=plugin_name)
-        if setting and isinstance(setting.settings, dict) and key in setting.settings:
-            del setting.settings[key]
-            if not setting.settings:
-                await setting.delete()
-            else:
-                await setting.save(update_fields=["settings"])
-            await self.dao.clear_cache(group_id=group_id, plugin_name=plugin_name)
-            return True
-        return False
-
-    async def get(
-        self, group_id: str, plugin_name: str, key: str, default: Any = None
-    ) -> Any:
-        """
-        获取一个分群配置项的值，如果群组未单独设置，则回退到全局默认值。
-
-        参数:
-            group_id: 目标群组ID。
-            plugin_name: 插件的模块名。
-            key: 配置项的键。
-            default: 如果找不到配置项，返回的默认值。
-
-        返回:
-            配置项的值。
-        """
-        full_settings = await self.get_all_for_plugin(group_id, plugin_name)
-        return full_settings.get(key, default)
-
-    async def reset_all_for_plugin(self, group_id: str, plugin_name: str) -> bool:
-        """
-        重置一个插件在指定群组的配置，使其回退到全局默认值。
-        这通过删除数据库中的对应记录来实现。
-
-        参数:
-            group_id: 目标群组ID。
-            plugin_name: 插件的模块名。
-
-        返回:
-            bool: 如果成功删除了一个条目，则返回 True，否则返回 False。
-        """
-        deleted_count = await self.dao.delete(
-            group_id=group_id, plugin_name=plugin_name
-        )
-
-        if deleted_count > 0:
-            await self.dao.clear_cache(group_id=group_id, plugin_name=plugin_name)
-            logger.debug(f"已重置插件 '{plugin_name}' 在群组 '{group_id}' 的配置。")
-            return True
-
-        return False
-
-    @overload
-    async def get_all_for_plugin(
-        self, group_id: str, plugin_name: str, *, parse_model: type[T]
-    ) -> T: ...
-
-    @overload
-    async def get_all_for_plugin(
-        self, group_id: str, plugin_name: str, *, parse_model: None = None
-    ) -> dict[str, Any]: ...
-
-    async def get_all_for_plugin(
-        self, group_id: str, plugin_name: str, *, parse_model: type[T] | None = None
-    ) -> T | dict[str, Any]:
-        """
-        获取一个插件在指定群组中的完整配置，应用了“继承与覆盖”逻辑。
-        它首先获取全局默认配置，然后用数据库中存储的群组特定配置覆盖它。
-
-        参数:
-            group_id: 目标群组ID。
-            plugin_name: 插件的模块名。
-            parse_model: (可选) Pydantic模型，用于解析和验证配置。
-        """
-        cache_key = f"{group_id}:{plugin_name}"
-        cached_settings = await self._cache.get(cache_key)
-        if cached_settings is not None:
-            logger.debug(f"缓存命中: {cache_key}")
-            if parse_model:
-                try:
-                    return parse_as(parse_model, cached_settings)
-                except (ValidationError, TypeError) as e:
-                    logger.warning(
-                        f"缓存数据 '{cache_key}' 与模型 '{parse_model.__name__}' "
-                        f"不匹配: {e}。将从数据库重新加载。"
-                    )
-            else:
-                return cached_settings
-
-        logger.debug(f"缓存未命中: {cache_key}，从数据库加载。")
-
-        global_config_group = Config.get(plugin_name)
-        final_settings_dict = {
-            key: global_config_group.get(key, build_model=False)
-            for key in global_config_group.configs.keys()
-        }
-
-        group_setting_entry = await self.dao.get_or_none(
-            group_id=group_id, plugin_name=plugin_name
-        )
-        if group_setting_entry:
-            try:
-                group_specific_settings = group_setting_entry.settings
-                if isinstance(group_specific_settings, dict):
-                    final_settings_dict.update(group_specific_settings)
-                else:
-                    logger.warning(
-                        f"群组 {group_id} 插件 '{plugin_name}' 的配置格式不正确"
-                        f"（不是字典），已忽略。"
-                    )
-            except Exception as e:
-                logger.warning(
-                    f"加载群组 {group_id} 插件 '{plugin_name}' 的特定配置时出错: {e}"
-                )
-
-        await self._cache.set(cache_key, final_settings_dict)
-
-        if parse_model:
-            try:
-                return parse_as(parse_model, final_settings_dict)
-            except (ValidationError, TypeError) as e:
-                logger.warning(
-                    f"插件 '{plugin_name}' 的配置无法解析为 '{parse_model.__name__}'。"
-                    f"值: {final_settings_dict}, 错误: {e}。将返回一个默认模型实例。"
-                )
-                return parse_as(parse_model, {})
-
-        return final_settings_dict
-
-    async def set_bulk(
-        self, group_ids: list[str], plugin_name: str, key: str, value: Any
-    ) -> tuple[int, int]:
-        """
-        为多个群组批量设置同一个配置项。
-
-        参数:
-            group_ids: 目标群组ID列表。
-            plugin_name: 插件模块名。
-            key: 配置项的键。
-            value: 要设置的值。
-
-        返回:
-            一个元组 (updated_count, created_count)。
-        """
-        if not group_ids:
-            return 0, 0
-
-        for group_id in group_ids:
-            current_settings = await self.get_all_for_plugin(group_id, plugin_name)
-            current_settings[key] = value
-            await self.set(
-                group_id, plugin_name, model_validate(BaseModel, current_settings)
-            )
-        return len(group_ids), 0
-
-
-group_settings_service = GroupSettingsService()

zhenxun/services/llm/__init__.py

@@ -9,15 +9,13 @@ from .api import (
     code,
     create_image,
     embed,
-    embed_documents,
-    embed_query,
     generate,
     generate_structured,
+    run_with_tools,
     search,
 )
 from .config import (
     CommonOverrides,
-    GenConfigBuilder,
     LLMGenerationConfig,
     register_llm_configs,
 )
@@ -34,14 +32,8 @@ from .manager import (
     list_model_identifiers,
     set_global_default_model_name,
 )
-from .memory import (
+from .session import AI, AIConfig
-    AIConfig,
+from .tools import function_tool, tool_provider_manager
-    BaseMemory,
-    MemoryProcessor,
-    set_default_memory_backend,
-)
-from .session import AI
-from .tools import RunContext, ToolInvoker, function_tool, tool_provider_manager
 from .types import (
     EmbeddingTaskType,
     LLMContentPart,
@@ -58,39 +50,26 @@ from .types import (
     ToolMetadata,
     UsageInfo,
 )
-from .types.models import (
-    GeminiCodeExecution,
-    GeminiGoogleSearch,
-    GeminiUrlContext,
-)
 from .utils import create_multimodal_message, message_to_unimessage, unimsg_to_llm_parts
 
 __all__ = [
     "AI",
     "AIConfig",
-    "BaseMemory",
     "CommonOverrides",
     "EmbeddingTaskType",
-    "GeminiCodeExecution",
-    "GeminiGoogleSearch",
-    "GeminiUrlContext",
-    "GenConfigBuilder",
     "LLMContentPart",
     "LLMErrorCode",
     "LLMException",
     "LLMGenerationConfig",
     "LLMMessage",
     "LLMResponse",
-    "MemoryProcessor",
     "ModelDetail",
     "ModelInfo",
     "ModelName",
     "ModelProvider",
     "ResponseFormat",
-    "RunContext",
     "TaskType",
     "ToolCategory",
-    "ToolInvoker",
     "ToolMetadata",
     "UsageInfo",
     "chat",
@@ -99,8 +78,6 @@ __all__ = [
     "create_image",
     "create_multimodal_message",
     "embed",
-    "embed_documents",
-    "embed_query",
     "function_tool",
     "generate",
     "generate_structured",
@@ -112,8 +89,8 @@ __all__ = [
     "list_model_identifiers",
     "message_to_unimessage",
     "register_llm_configs",
+    "run_with_tools",
     "search",
-    "set_default_memory_backend",
     "set_global_default_model_name",
     "tool_provider_manager",
     "unimsg_to_llm_parts",

zhenxun/services/llm/adapters/__init__.py

@@ -7,18 +7,16 @@ LLM 适配器模块
 from .base import BaseAdapter, OpenAICompatAdapter, RequestData, ResponseData
 from .factory import LLMAdapterFactory, get_adapter_for_api_type, register_adapter
 from .gemini import GeminiAdapter
-from .openai import DeepSeekAdapter, OpenAIAdapter, OpenAIImageAdapter
+from .openai import OpenAIAdapter
 
 LLMAdapterFactory.initialize()
 
 __all__ = [
     "BaseAdapter",
-    "DeepSeekAdapter",
     "GeminiAdapter",
     "LLMAdapterFactory",
     "OpenAIAdapter",
     "OpenAICompatAdapter",
-    "OpenAIImageAdapter",
     "RequestData",
     "ResponseData",
     "get_adapter_for_api_type",

zhenxun/services/llm/adapters/base.py

@@ -3,26 +3,24 @@ LLM 适配器基类和通用数据结构
 """
 
 from abc import ABC, abstractmethod
+import base64
+import binascii
 import json
-from pathlib import Path
 from typing import TYPE_CHECKING, Any
-import uuid
 
-import httpx
 from pydantic import BaseModel
 
-from zhenxun.configs.path_config import TEMP_PATH
 from zhenxun.services.log import logger
 
-from ..types import LLMContentPart
 from ..types.exceptions import LLMErrorCode, LLMException
 from ..types.models import LLMToolCall
 
 if TYPE_CHECKING:
-    from ..config.generation import LLMEmbeddingConfig, LLMGenerationConfig
+    from ..config.generation import LLMGenerationConfig
     from ..service import LLMModel
-    from ..types import LLMMessage
+    from ..types.content import LLMMessage
-    from ..types.models import ToolChoice
+    from ..types.enums import EmbeddingTaskType
+    from ..types.protocols import ToolExecutable
 
 
 class RequestData(BaseModel):
@@ -31,23 +29,19 @@ class RequestData(BaseModel):
     url: str
     headers: dict[str, str]
     body: dict[str, Any]
-    files: dict[str, Any] | list[tuple[str, Any]] | None = None
 
 
 class ResponseData(BaseModel):
     """响应数据封装 - 支持所有高级功能"""
 
     text: str
-    content_parts: list[LLMContentPart] | None = None
+    images: list[bytes] | None = None
-    images: list[bytes | Path] | None = None
     usage_info: dict[str, Any] | None = None
     raw_response: dict[str, Any] | None = None
     tool_calls: list[LLMToolCall] | None = None
     code_executions: list[Any] | None = None
     grounding_metadata: Any | None = None
     cache_info: Any | None = None
-    thought_text: str | None = None
-    thought_signature: str | None = None
 
     code_execution_results: list[dict[str, Any]] | None = None
     search_results: list[dict[str, Any]] | None = None
@@ -56,33 +50,9 @@ class ResponseData(BaseModel):
     citations: list[dict[str, Any]] | None = None
 
 
-def process_image_data(image_data: bytes) -> bytes | Path:
-    """
-    处理图片数据：若超过 2MB 则保存到临时目录，避免占用内存。
-    """
-    max_inline_size = 2 * 1024 * 1024
-    if len(image_data) > max_inline_size:
-        save_dir = TEMP_PATH / "llm"
-        save_dir.mkdir(parents=True, exist_ok=True)
-        file_name = f"{uuid.uuid4()}.png"
-        file_path = save_dir / file_name
-        file_path.write_bytes(image_data)
-        logger.info(
-            f"图片数据过大 ({len(image_data)} bytes)，已保存到临时文件: {file_path}",
-            "LLMAdapter",
-        )
-        return file_path.resolve()
-    return image_data
-
-
 class BaseAdapter(ABC):
     """LLM API适配器基类"""
 
-    @property
-    def log_sanitization_context(self) -> str:
-        """用于日志清洗的上下文名称，默认 'default'"""
-        return "default"
-
     @property
     @abstractmethod
     def api_type(self) -> str:
@@ -107,7 +77,7 @@ class BaseAdapter(ABC):
         默认实现：将简单请求转换为高级请求格式
         子类可以重写此方法以提供特定的优化实现
         """
-        from ..types import LLMMessage
+        from ..types.content import LLMMessage
 
         messages: list[LLMMessage] = []
 
@@ -137,8 +107,8 @@ class BaseAdapter(ABC):
         api_key: str,
         messages: list["LLMMessage"],
         config: "LLMGenerationConfig | None" = None,
-        tools: list[Any] | None = None,
+        tools: dict[str, "ToolExecutable"] | None = None,
-        tool_choice: "str | dict[str, Any] | ToolChoice | None" = None,
+        tool_choice: str | dict[str, Any] | None = None,
     ) -> RequestData:
         """准备高级请求"""
         pass
@@ -159,7 +129,8 @@ class BaseAdapter(ABC):
         model: "LLMModel",
         api_key: str,
         texts: list[str],
-        config: "LLMEmbeddingConfig",
+        task_type: "EmbeddingTaskType | str",
+        **kwargs: Any,
     ) -> RequestData:
         """准备文本嵌入请求"""
         pass
@@ -171,16 +142,9 @@ class BaseAdapter(ABC):
         """解析文本嵌入响应"""
         pass
 
-    @abstractmethod
-    def convert_generation_config(
-        self, config: "LLMGenerationConfig", model: "LLMModel"
-    ) -> dict[str, Any]:
-        """将通用生成配置转换为特定API的参数字典"""
-        pass
-
     def validate_embedding_response(self, response_json: dict[str, Any]) -> None:
         """验证嵌入API响应"""
-        if response_json.get("error"):
+        if "error" in response_json:
             error_info = response_json["error"]
             msg = (
                 error_info.get("message", str(error_info))
@@ -215,9 +179,158 @@ class BaseAdapter(ABC):
         )
         return headers
 
+    def convert_messages_to_openai_format(
+        self, messages: list["LLMMessage"]
+    ) -> list[dict[str, Any]]:
+        """将LLMMessage转换为OpenAI格式 - 通用方法"""
+        openai_messages: list[dict[str, Any]] = []
+        for msg in messages:
+            openai_msg: dict[str, Any] = {"role": msg.role}
+
+            if msg.role == "tool":
+                openai_msg["tool_call_id"] = msg.tool_call_id
+                openai_msg["name"] = msg.name
+                openai_msg["content"] = msg.content
+            else:
+                if isinstance(msg.content, str):
+                    openai_msg["content"] = msg.content
+                else:
+                    content_parts = []
+                    for part in msg.content:
+                        if part.type == "text":
+                            content_parts.append({"type": "text", "text": part.text})
+                        elif part.type == "image":
+                            content_parts.append(
+                                {
+                                    "type": "image_url",
+                                    "image_url": {"url": part.image_source},
+                                }
+                            )
+                    openai_msg["content"] = content_parts
+
+            if msg.role == "assistant" and msg.tool_calls:
+                assistant_tool_calls = []
+                for call in msg.tool_calls:
+                    assistant_tool_calls.append(
+                        {
+                            "id": call.id,
+                            "type": "function",
+                            "function": {
+                                "name": call.function.name,
+                                "arguments": call.function.arguments,
+                            },
+                        }
+                    )
+                openai_msg["tool_calls"] = assistant_tool_calls
+
+            if msg.name and msg.role != "tool":
+                openai_msg["name"] = msg.name
+
+            openai_messages.append(openai_msg)
+        return openai_messages
+
+    def parse_openai_response(self, response_json: dict[str, Any]) -> ResponseData:
+        """解析OpenAI格式的响应 - 通用方法"""
+        self.validate_response(response_json)
+
+        try:
+            choices = response_json.get("choices", [])
+            if not choices:
+                logger.debug("OpenAI响应中没有choices，可能为空回复或流结束。")
+                return ResponseData(text="", raw_response=response_json)
+
+            choice = choices[0]
+            message = choice.get("message", {})
+            content = message.get("content", "")
+
+            if content:
+                content = content.strip()
+
+            images_bytes: list[bytes] = []
+            if content and content.startswith("{") and content.endswith("}"):
+                try:
+                    content_json = json.loads(content)
+                    if "b64_json" in content_json:
+                        images_bytes.append(base64.b64decode(content_json["b64_json"]))
+                        content = "[图片已生成]"
+                    elif "data" in content_json and isinstance(
+                        content_json["data"], str
+                    ):
+                        images_bytes.append(base64.b64decode(content_json["data"]))
+                        content = "[图片已生成]"
+
+                except (json.JSONDecodeError, KeyError, binascii.Error):
+                    pass
+            elif (
+                "images" in message
+                and isinstance(message["images"], list)
+                and message["images"]
+            ):
+                image_info = message["images"][0]
+                if image_info.get("type") == "image_url":
+                    image_url_obj = image_info.get("image_url", {})
+                    url_str = image_url_obj.get("url", "")
+                    if url_str.startswith("data:image/png;base64,"):
+                        try:
+                            b64_data = url_str.split(",", 1)[1]
+                            images_bytes.append(base64.b64decode(b64_data))
+                            content = content if content else "[图片已生成]"
+                        except (IndexError, binascii.Error) as e:
+                            logger.warning(f"解析OpenRouter Base64图片数据失败: {e}")
+
+            parsed_tool_calls: list[LLMToolCall] | None = None
+            if message_tool_calls := message.get("tool_calls"):
+                from ..types.models import LLMToolFunction
+
+                parsed_tool_calls = []
+                for tc_data in message_tool_calls:
+                    try:
+                        if tc_data.get("type") == "function":
+                            parsed_tool_calls.append(
+                                LLMToolCall(
+                                    id=tc_data["id"],
+                                    function=LLMToolFunction(
+                                        name=tc_data["function"]["name"],
+                                        arguments=tc_data["function"]["arguments"],
+                                    ),
+                                )
+                            )
+                    except KeyError as e:
+                        logger.warning(
+                            f"解析OpenAI工具调用数据时缺少键: {tc_data}, 错误: {e}"
+                        )
+                    except Exception as e:
+                        logger.warning(
+                            f"解析OpenAI工具调用数据时出错: {tc_data}, 错误: {e}"
+                        )
+                if not parsed_tool_calls:
+                    parsed_tool_calls = None
+
+            final_text = content if content is not None else ""
+            if not final_text and parsed_tool_calls:
+                final_text = f"请求调用 {len(parsed_tool_calls)} 个工具。"
+
+            usage_info = response_json.get("usage")
+
+            return ResponseData(
+                text=final_text,
+                tool_calls=parsed_tool_calls,
+                usage_info=usage_info,
+                images=images_bytes if images_bytes else None,
+                raw_response=response_json,
+            )
+
+        except Exception as e:
+            logger.error(f"解析OpenAI格式响应失败: {e}", e=e)
+            raise LLMException(
+                f"解析API响应失败: {e}",
+                code=LLMErrorCode.RESPONSE_PARSE_ERROR,
+                cause=e,
+            )
+
     def validate_response(self, response_json: dict[str, Any]) -> None:
         """验证API响应，解析不同API的错误结构"""
-        if response_json.get("error"):
+        if "error" in response_json:
             error_info = response_json["error"]
 
             if isinstance(error_info, dict):
@@ -228,15 +341,12 @@ class BaseAdapter(ABC):
                 error_code_mapping = {
                     "invalid_api_key": LLMErrorCode.API_KEY_INVALID,
                     "authentication_failed": LLMErrorCode.API_KEY_INVALID,
-                    "insufficient_quota": LLMErrorCode.API_QUOTA_EXCEEDED,
                     "rate_limit_exceeded": LLMErrorCode.API_RATE_LIMITED,
                     "quota_exceeded": LLMErrorCode.API_RATE_LIMITED,
                     "model_not_found": LLMErrorCode.MODEL_NOT_FOUND,
                     "invalid_model": LLMErrorCode.MODEL_NOT_FOUND,
                     "context_length_exceeded": LLMErrorCode.CONTEXT_LENGTH_EXCEEDED,
                     "max_tokens_exceeded": LLMErrorCode.CONTEXT_LENGTH_EXCEEDED,
-                    "invalid_request_error": LLMErrorCode.INVALID_PARAMETER,
-                    "invalid_parameter": LLMErrorCode.INVALID_PARAMETER,
                 }
 
                 llm_error_code = error_code_mapping.get(
@@ -295,12 +405,23 @@ class BaseAdapter(ABC):
     ) -> dict[str, Any]:
         """通用的配置应用逻辑"""
         if config is not None:
-            return self.convert_generation_config(config, model)
+            return config.to_api_params(model.api_type, model.model_name)
 
-        if model._generation_config:
+        if model._generation_config is not None:
-            return self.convert_generation_config(model._generation_config, model)
+            return model._generation_config.to_api_params(
+                model.api_type, model.model_name
+            )
 
-        return {}
+        base_config = {}
+        if model.temperature is not None:
+            base_config["temperature"] = model.temperature
+        if model.max_tokens is not None:
+            if model.api_type == "gemini":
+                base_config["maxOutputTokens"] = model.max_tokens
+            else:
+                base_config["max_tokens"] = model.max_tokens
+
+        return base_config
 
     def apply_config_override(
         self,
@@ -313,96 +434,12 @@ class BaseAdapter(ABC):
         body.update(config_params)
         return body
 
-    def handle_http_error(self, response: httpx.Response) -> LLMException | None:
-        """
-        处理 HTTP 错误响应。
-        如果响应状态码表示成功 (200)，返回 None；否则构造 LLMException 供外部捕获。
-        """
-        if response.status_code == 200:
-            return None
-
-        error_text = response.content.decode("utf-8", errors="ignore")
-        error_status = ""
-        error_msg = error_text
-        try:
-            error_json = json.loads(error_text)
-            if isinstance(error_json, dict) and "error" in error_json:
-                error_info = error_json["error"]
-                if isinstance(error_info, dict):
-                    error_msg = error_info.get("message", error_msg)
-                    raw_status = error_info.get("status") or error_info.get("code")
-                    error_status = str(raw_status) if raw_status is not None else ""
-                elif error_info is not None:
-                    error_msg = str(error_info)
-                    error_status = error_msg
-        except Exception:
-            pass
-
-        status_upper = error_status.upper() if error_status else ""
-        text_upper = error_text.upper()
-
-        error_code = LLMErrorCode.API_REQUEST_FAILED
-        if response.status_code == 400:
-            if (
-                "FAILED_PRECONDITION" in status_upper
-                or "LOCATION IS NOT SUPPORTED" in text_upper
-            ):
-                error_code = LLMErrorCode.USER_LOCATION_NOT_SUPPORTED
-            elif "INVALID_ARGUMENT" in status_upper:
-                error_code = LLMErrorCode.INVALID_PARAMETER
-            elif "API_KEY_INVALID" in text_upper or "API KEY NOT VALID" in text_upper:
-                error_code = LLMErrorCode.API_KEY_INVALID
-            else:
-                error_code = LLMErrorCode.INVALID_PARAMETER
-        elif response.status_code in [401, 403]:
-            if error_msg and (
-                "country" in error_msg.lower()
-                or "region" in error_msg.lower()
-                or "unsupported" in error_msg.lower()
-            ):
-                error_code = LLMErrorCode.USER_LOCATION_NOT_SUPPORTED
-            elif "PERMISSION_DENIED" in status_upper:
-                error_code = LLMErrorCode.API_KEY_INVALID
-            else:
-                error_code = LLMErrorCode.API_KEY_INVALID
-        elif response.status_code == 404:
-            error_code = LLMErrorCode.MODEL_NOT_FOUND
-        elif response.status_code == 429:
-            if (
-                "RESOURCE_EXHAUSTED" in status_upper
-                or "INSUFFICIENT_QUOTA" in status_upper
-                or ("quota" in error_msg.lower() if error_msg else False)
-            ):
-                error_code = LLMErrorCode.API_QUOTA_EXCEEDED
-            else:
-                error_code = LLMErrorCode.API_RATE_LIMITED
-        elif response.status_code in [402, 413]:
-            error_code = LLMErrorCode.API_QUOTA_EXCEEDED
-        elif response.status_code == 422:
-            error_code = LLMErrorCode.GENERATION_FAILED
-        elif response.status_code >= 500:
-            error_code = LLMErrorCode.API_TIMEOUT
-
-        return LLMException(
-            f"HTTP请求失败: {response.status_code} ({error_status or 'Unknown'})",
-            code=error_code,
-            details={
-                "status_code": response.status_code,
-                "api_status": error_status,
-                "response": error_text,
-            },
-        )
-
 
 class OpenAICompatAdapter(BaseAdapter):
     """
     处理所有 OpenAI 兼容 API 的通用适配器。
     """
 
-    @property
-    def log_sanitization_context(self) -> str:
-        return "openai_request"
-
     @abstractmethod
     def get_chat_endpoint(self, model: "LLMModel") -> str:
         """子类必须实现，返回 chat completions 的端点"""
@@ -444,8 +481,8 @@ class OpenAICompatAdapter(BaseAdapter):
         api_key: str,
         messages: list["LLMMessage"],
         config: "LLMGenerationConfig | None" = None,
-        tools: list[Any] | None = None,
+        tools: dict[str, "ToolExecutable"] | None = None,
-        tool_choice: "str | dict[str, Any] | ToolChoice | None" = None,
+        tool_choice: str | dict[str, Any] | None = None,
     ) -> RequestData:
         """准备高级请求 - OpenAI兼容格式"""
         url = self.get_api_url(model, self.get_chat_endpoint(model))
@@ -457,44 +494,28 @@ class OpenAICompatAdapter(BaseAdapter):
                     "X-Title": "Zhenxun Bot",
                 }
             )
-        from .components.openai_components import OpenAIMessageConverter
+        openai_messages = self.convert_messages_to_openai_format(messages)
-
-        converter = OpenAIMessageConverter()
-        openai_messages = converter.convert_messages(messages)
 
         body = {
             "model": model.model_name,
             "messages": openai_messages,
         }
 
-        openai_tools: list[dict[str, Any]] | None = None
-        executables: list[Any] = []
         if tools:
-            for tool in tools:
-                if hasattr(tool, "get_definition"):
-                    executables.append(tool)
-
-        if executables:
             import asyncio
 
             from zhenxun.utils.pydantic_compat import model_dump
 
             definition_tasks = [
-                executable.get_definition() for executable in executables
+                executable.get_definition() for executable in tools.values()
             ]
-            tool_defs = []
+            openai_tools = await asyncio.gather(*definition_tasks)
-            if definition_tasks:
+            if openai_tools:
-                tool_defs = await asyncio.gather(*definition_tasks)
+                body["tools"] = [
-
-            if tool_defs:
-                openai_tools = [
                     {"type": "function", "function": model_dump(tool)}
-                    for tool in tool_defs
+                    for tool in openai_tools
                 ]
 
-        if openai_tools:
-            body["tools"] = openai_tools
-
         if tool_choice:
             body["tool_choice"] = tool_choice
 
@@ -507,21 +528,20 @@ class OpenAICompatAdapter(BaseAdapter):
         response_json: dict[str, Any],
         is_advanced: bool = False,
     ) -> ResponseData:
-        """解析响应 - 直接使用组件化 ResponseParser"""
+        """解析响应 - 直接使用基类的 OpenAI 格式解析"""
         _ = model, is_advanced
-        from .components.openai_components import OpenAIResponseParser
+        return self.parse_openai_response(response_json)
-
-        parser = OpenAIResponseParser()
-        return parser.parse(response_json)
 
     def prepare_embedding_request(
         self,
         model: "LLMModel",
         api_key: str,
         texts: list[str],
-        config: "LLMEmbeddingConfig",
+        task_type: "EmbeddingTaskType | str",
+        **kwargs: Any,
     ) -> RequestData:
         """准备嵌入请求 - OpenAI兼容格式"""
+        _ = task_type
         url = self.get_api_url(model, self.get_embedding_endpoint(model))
         headers = self.get_base_headers(api_key)
 
@@ -530,14 +550,8 @@ class OpenAICompatAdapter(BaseAdapter):
             "input": texts,
         }
 
-        if config.output_dimensionality:
+        if kwargs:
-            body["dimensions"] = config.output_dimensionality
+            body.update(kwargs)
-
-        if config.task_type:
-            body["task"] = config.task_type
-
-        if config.encoding_format and config.encoding_format != "float":
-            body["encoding_format"] = config.encoding_format
 
         return RequestData(url=url, headers=headers, body=body)
 

zhenxun/services/llm/adapters/components/__init__.py

@@ -1 +0,0 @@
-

zhenxun/services/llm/adapters/components/gemini_components.py

@@ -1,606 +0,0 @@
-import base64
-import json
-from pathlib import Path
-from typing import Any
-
-from zhenxun.services.llm.adapters.base import ResponseData, process_image_data
-from zhenxun.services.llm.adapters.components.interfaces import (
-    ConfigMapper,
-    MessageConverter,
-    ResponseParser,
-    ToolSerializer,
-)
-from zhenxun.services.llm.config.generation import (
-    ImageAspectRatio,
-    LLMGenerationConfig,
-    ReasoningEffort,
-    ResponseFormat,
-)
-from zhenxun.services.llm.config.providers import get_gemini_safety_threshold
-from zhenxun.services.llm.types import (
-    CodeExecutionOutcome,
-    LLMContentPart,
-    LLMMessage,
-)
-from zhenxun.services.llm.types.capabilities import ModelCapabilities
-from zhenxun.services.llm.types.exceptions import LLMErrorCode, LLMException
-from zhenxun.services.llm.types.models import (
-    LLMGroundingAttribution,
-    LLMGroundingMetadata,
-    LLMToolCall,
-    LLMToolFunction,
-    ModelDetail,
-    ToolDefinition,
-)
-from zhenxun.services.llm.utils import (
-    resolve_json_schema_refs,
-    sanitize_schema_for_llm,
-)
-from zhenxun.services.log import logger
-from zhenxun.utils.http_utils import AsyncHttpx
-from zhenxun.utils.pydantic_compat import model_copy, model_dump
-
-
-class GeminiConfigMapper(ConfigMapper):
-    def map_config(
-        self,
-        config: LLMGenerationConfig,
-        model_detail: ModelDetail | None = None,
-        capabilities: ModelCapabilities | None = None,
-    ) -> dict[str, Any]:
-        params: dict[str, Any] = {}
-
-        if config.core:
-            if config.core.temperature is not None:
-                params["temperature"] = config.core.temperature
-            if config.core.max_tokens is not None:
-                params["maxOutputTokens"] = config.core.max_tokens
-            if config.core.top_k is not None:
-                params["topK"] = config.core.top_k
-            if config.core.top_p is not None:
-                params["topP"] = config.core.top_p
-
-        if config.output:
-            if config.output.response_format == ResponseFormat.JSON:
-                params["responseMimeType"] = "application/json"
-                if config.output.response_schema:
-                    params["responseJsonSchema"] = config.output.response_schema
-            elif config.output.response_mime_type is not None:
-                params["responseMimeType"] = config.output.response_mime_type
-
-            if (
-                config.output.response_schema is not None
-                and "responseJsonSchema" not in params
-            ):
-                params["responseJsonSchema"] = config.output.response_schema
-            if config.output.response_modalities:
-                params["responseModalities"] = config.output.response_modalities
-
-        if config.tool_config:
-            fc_config: dict[str, Any] = {"mode": config.tool_config.mode}
-            if (
-                config.tool_config.allowed_function_names
-                and config.tool_config.mode == "ANY"
-            ):
-                builtins = {"code_execution", "google_search", "google_map"}
-                user_funcs = [
-                    name
-                    for name in config.tool_config.allowed_function_names
-                    if name not in builtins
-                ]
-                if user_funcs:
-                    fc_config["allowedFunctionNames"] = user_funcs
-            params["toolConfig"] = {"functionCallingConfig": fc_config}
-
-        if config.reasoning:
-            thinking_config = params.setdefault("thinkingConfig", {})
-
-            if config.reasoning.budget_tokens is not None:
-                if (
-                    config.reasoning.budget_tokens <= 0
-                    or config.reasoning.budget_tokens >= 1
-                ):
-                    budget_value = int(config.reasoning.budget_tokens)
-                else:
-                    budget_value = int(config.reasoning.budget_tokens * 32768)
-                thinking_config["thinkingBudget"] = budget_value
-            elif config.reasoning.effort:
-                if config.reasoning.effort == ReasoningEffort.MEDIUM:
-                    thinking_config["thinkingLevel"] = "HIGH"
-                else:
-                    thinking_config["thinkingLevel"] = config.reasoning.effort.value
-
-            if config.reasoning.show_thoughts is not None:
-                thinking_config["includeThoughts"] = config.reasoning.show_thoughts
-            elif capabilities and capabilities.reasoning_visibility == "visible":
-                thinking_config["includeThoughts"] = True
-
-        if config.visual:
-            image_config: dict[str, Any] = {}
-
-            if config.visual.aspect_ratio is not None:
-                ar_value = (
-                    config.visual.aspect_ratio.value
-                    if isinstance(config.visual.aspect_ratio, ImageAspectRatio)
-                    else config.visual.aspect_ratio
-                )
-                image_config["aspectRatio"] = ar_value
-
-            if config.visual.resolution:
-                image_config["imageSize"] = config.visual.resolution
-
-            if image_config:
-                params["imageConfig"] = image_config
-
-            if config.visual.media_resolution:
-                media_value = config.visual.media_resolution.upper()
-                if not media_value.startswith("MEDIA_RESOLUTION_"):
-                    media_value = f"MEDIA_RESOLUTION_{media_value}"
-                params["mediaResolution"] = media_value
-
-        if config.custom_params:
-            mapped_custom = config.custom_params.copy()
-            if "max_tokens" in mapped_custom:
-                mapped_custom["maxOutputTokens"] = mapped_custom.pop("max_tokens")
-            if "top_k" in mapped_custom:
-                mapped_custom["topK"] = mapped_custom.pop("top_k")
-            if "top_p" in mapped_custom:
-                mapped_custom["topP"] = mapped_custom.pop("top_p")
-
-            for key in (
-                "code_execution_timeout",
-                "grounding_config",
-                "dynamic_threshold",
-                "user_location",
-                "reflexion_retries",
-            ):
-                mapped_custom.pop(key, None)
-
-            for unsupported in [
-                "frequency_penalty",
-                "presence_penalty",
-                "repetition_penalty",
-            ]:
-                if unsupported in mapped_custom:
-                    mapped_custom.pop(unsupported)
-
-            params.update(mapped_custom)
-
-        safety_settings: list[dict[str, Any]] = []
-        if config.safety and config.safety.safety_settings:
-            for category, threshold in config.safety.safety_settings.items():
-                safety_settings.append({"category": category, "threshold": threshold})
-        else:
-            threshold = get_gemini_safety_threshold()
-            for category in [
-                "HARM_CATEGORY_HARASSMENT",
-                "HARM_CATEGORY_HATE_SPEECH",
-                "HARM_CATEGORY_SEXUALLY_EXPLICIT",
-                "HARM_CATEGORY_DANGEROUS_CONTENT",
-            ]:
-                safety_settings.append({"category": category, "threshold": threshold})
-
-        if safety_settings:
-            params["safetySettings"] = safety_settings
-
-        return params
-
-
-class GeminiMessageConverter(MessageConverter):
-    async def convert_part(self, part: LLMContentPart) -> dict[str, Any]:
-        """将单个内容部分转换为 Gemini API 格式"""
-
-        def _get_gemini_resolution_dict() -> dict[str, Any]:
-            if part.media_resolution:
-                value = part.media_resolution.upper()
-                if not value.startswith("MEDIA_RESOLUTION_"):
-                    value = f"MEDIA_RESOLUTION_{value}"
-                return {"media_resolution": {"level": value}}
-            return {}
-
-        if part.type == "text":
-            return {"text": part.text}
-
-        if part.type == "thought":
-            return {"text": part.thought_text, "thought": True}
-
-        if part.type == "image":
-            if not part.image_source:
-                raise ValueError("图像类型的内容必须包含image_source")
-
-            if part.is_image_base64():
-                base64_info = part.get_base64_data()
-                if base64_info:
-                    mime_type, data = base64_info
-                    payload = {"inlineData": {"mimeType": mime_type, "data": data}}
-                    payload.update(_get_gemini_resolution_dict())
-                    return payload
-                raise ValueError(f"无法解析Base64图像数据: {part.image_source[:50]}...")
-            if part.is_image_url():
-                logger.debug(f"正在为Gemini下载并编码URL图片: {part.image_source}")
-                try:
-                    image_bytes = await AsyncHttpx.get_content(part.image_source)
-                    mime_type = part.mime_type or "image/jpeg"
-                    base64_data = base64.b64encode(image_bytes).decode("utf-8")
-                    payload = {
-                        "inlineData": {"mimeType": mime_type, "data": base64_data}
-                    }
-                    payload.update(_get_gemini_resolution_dict())
-                    return payload
-                except Exception as e:
-                    logger.error(f"下载或编码URL图片失败: {e}", e=e)
-                    raise ValueError(f"无法处理图片URL: {e}")
-            raise ValueError(f"不支持的图像源格式: {part.image_source[:50]}...")
-
-        if part.type == "video":
-            if not part.video_source:
-                raise ValueError("视频类型的内容必须包含video_source")
-
-            if part.video_source.startswith("data:"):
-                try:
-                    header, data = part.video_source.split(",", 1)
-                    mime_type = header.split(";")[0].replace("data:", "")
-                    payload = {"inlineData": {"mimeType": mime_type, "data": data}}
-                    payload.update(_get_gemini_resolution_dict())
-                    return payload
-                except (ValueError, IndexError):
-                    raise ValueError(
-                        f"无法解析Base64视频数据: {part.video_source[:50]}..."
-                    )
-            raise ValueError(
-                "Gemini API 的视频处理需要通过 File API 上传，不支持直接 URL"
-            )
-
-        if part.type == "audio":
-            if not part.audio_source:
-                raise ValueError("音频类型的内容必须包含audio_source")
-
-            if part.audio_source.startswith("data:"):
-                try:
-                    header, data = part.audio_source.split(",", 1)
-                    mime_type = header.split(";")[0].replace("data:", "")
-                    payload = {"inlineData": {"mimeType": mime_type, "data": data}}
-                    payload.update(_get_gemini_resolution_dict())
-                    return payload
-                except (ValueError, IndexError):
-                    raise ValueError(
-                        f"无法解析Base64音频数据: {part.audio_source[:50]}..."
-                    )
-            raise ValueError(
-                "Gemini API 的音频处理需要通过 File API 上传，不支持直接 URL"
-            )
-
-        if part.type == "file":
-            if part.file_uri:
-                payload = {
-                    "fileData": {"mimeType": part.mime_type, "fileUri": part.file_uri}
-                }
-                payload.update(_get_gemini_resolution_dict())
-                return payload
-            if part.file_source:
-                file_name = (
-                    part.metadata.get("name", "file") if part.metadata else "file"
-                )
-                return {"text": f"[文件: {file_name}]\n{part.file_source}"}
-            raise ValueError("文件类型的内容必须包含file_uri或file_source")
-
-        raise ValueError(f"不支持的内容类型: {part.type}")
-
-    async def convert_messages_async(
-        self, messages: list[LLMMessage]
-    ) -> list[dict[str, Any]]:
-        gemini_contents: list[dict[str, Any]] = []
-
-        for msg in messages:
-            current_parts: list[dict[str, Any]] = []
-            if msg.role == "system":
-                continue
-
-            elif msg.role == "user":
-                if isinstance(msg.content, str):
-                    current_parts.append({"text": msg.content})
-                elif isinstance(msg.content, list):
-                    for part_obj in msg.content:
-                        current_parts.append(await self.convert_part(part_obj))
-                gemini_contents.append({"role": "user", "parts": current_parts})
-
-            elif msg.role == "assistant" or msg.role == "model":
-                if isinstance(msg.content, str) and msg.content:
-                    current_parts.append({"text": msg.content})
-                elif isinstance(msg.content, list):
-                    for part_obj in msg.content:
-                        part_dict = await self.convert_part(part_obj)
-
-                        if "executableCode" in part_dict:
-                            part_dict["executable_code"] = part_dict.pop(
-                                "executableCode"
-                            )
-
-                        if "codeExecutionResult" in part_dict:
-                            part_dict["code_execution_result"] = part_dict.pop(
-                                "codeExecutionResult"
-                            )
-
-                        if (
-                            part_obj.metadata
-                            and "thought_signature" in part_obj.metadata
-                        ):
-                            part_dict["thoughtSignature"] = part_obj.metadata[
-                                "thought_signature"
-                            ]
-                        current_parts.append(part_dict)
-
-                if msg.tool_calls:
-                    for call in msg.tool_calls:
-                        fc_part = {
-                            "functionCall": {
-                                "name": call.function.name,
-                                "args": json.loads(call.function.arguments),
-                            }
-                        }
-                        if call.thought_signature:
-                            fc_part["thoughtSignature"] = call.thought_signature
-                        current_parts.append(fc_part)
-                if current_parts:
-                    gemini_contents.append({"role": "model", "parts": current_parts})
-
-            elif msg.role == "tool":
-                if not msg.name:
-                    raise ValueError("Gemini 工具消息必须包含 'name' 字段（函数名）。")
-
-                try:
-                    content_str = (
-                        msg.content
-                        if isinstance(msg.content, str)
-                        else str(msg.content)
-                    )
-                    tool_result_obj = json.loads(content_str)
-                except json.JSONDecodeError:
-                    content_str = (
-                        msg.content
-                        if isinstance(msg.content, str)
-                        else str(msg.content)
-                    )
-                    tool_result_obj = {"raw_output": content_str}
-
-                if isinstance(tool_result_obj, list):
-                    final_response_payload = {"result": tool_result_obj}
-                elif not isinstance(tool_result_obj, dict):
-                    final_response_payload = {"result": tool_result_obj}
-                else:
-                    final_response_payload = tool_result_obj
-
-                current_parts.append(
-                    {
-                        "functionResponse": {
-                            "name": msg.name,
-                            "response": final_response_payload,
-                        }
-                    }
-                )
-                if gemini_contents and gemini_contents[-1]["role"] == "function":
-                    gemini_contents[-1]["parts"].extend(current_parts)
-                else:
-                    gemini_contents.append({"role": "function", "parts": current_parts})
-
-        return gemini_contents
-
-    def convert_messages(self, messages: list[LLMMessage]) -> list[dict[str, Any]]:
-        raise NotImplementedError("Use convert_messages_async for Gemini")
-
-
-class GeminiToolSerializer(ToolSerializer):
-    def serialize_tools(self, tools: list[ToolDefinition]) -> list[dict[str, Any]]:
-        function_declarations: list[dict[str, Any]] = []
-        for tool_def in tools:
-            tool_copy = model_copy(tool_def)
-            tool_copy.parameters = resolve_json_schema_refs(tool_copy.parameters)
-            tool_copy.parameters = sanitize_schema_for_llm(
-                tool_copy.parameters, api_type="gemini"
-            )
-            function_declarations.append(model_dump(tool_copy))
-        return function_declarations
-
-
-class GeminiResponseParser(ResponseParser):
-    def validate_response(self, response_json: dict[str, Any]) -> None:
-        if error := response_json.get("error"):
-            code = error.get("code")
-            message = error.get("message", "")
-            status = error.get("status")
-            details = error.get("details", [])
-
-            if code == 429 or status == "RESOURCE_EXHAUSTED":
-                is_quota = any(
-                    d.get("reason") in ("QUOTA_EXCEEDED", "SERVICE_DISABLED")
-                    for d in details
-                    if isinstance(d, dict)
-                )
-                if is_quota or "quota" in message.lower():
-                    raise LLMException(
-                        f"Gemini配额耗尽: {message}",
-                        code=LLMErrorCode.API_QUOTA_EXCEEDED,
-                        details=error,
-                    )
-                raise LLMException(
-                    f"Gemini速率限制: {message}",
-                    code=LLMErrorCode.API_RATE_LIMITED,
-                    details=error,
-                )
-
-            if code == 400 or status in ("INVALID_ARGUMENT", "FAILED_PRECONDITION"):
-                raise LLMException(
-                    f"Gemini参数错误: {message}",
-                    code=LLMErrorCode.INVALID_PARAMETER,
-                    details=error,
-                    recoverable=False,
-                )
-
-        if prompt_feedback := response_json.get("promptFeedback"):
-            if block_reason := prompt_feedback.get("blockReason"):
-                raise LLMException(
-                    f"内容被安全过滤: {block_reason}",
-                    code=LLMErrorCode.CONTENT_FILTERED,
-                    details={
-                        "block_reason": block_reason,
-                        "safety_ratings": prompt_feedback.get("safetyRatings"),
-                    },
-                )
-
-    def parse(self, response_json: dict[str, Any]) -> ResponseData:
-        self.validate_response(response_json)
-
-        if "image_generation" in response_json and isinstance(
-            response_json["image_generation"], dict
-        ):
-            candidates_source = response_json["image_generation"]
-        else:
-            candidates_source = response_json
-
-        candidates = candidates_source.get("candidates", [])
-        usage_info = response_json.get("usageMetadata")
-
-        if not candidates:
-            return ResponseData(text="", raw_response=response_json)
-
-        candidate = candidates[0]
-        thought_signature: str | None = None
-
-        content_data = candidate.get("content", {})
-        parts = content_data.get("parts", [])
-
-        text_content = ""
-        images_payload: list[bytes | Path] = []
-        parsed_tool_calls: list[LLMToolCall] | None = None
-        parsed_code_executions: list[dict[str, Any]] = []
-        content_parts: list[LLMContentPart] = []
-        thought_summary_parts: list[str] = []
-        answer_parts = []
-
-        for part in parts:
-            part_signature = part.get("thoughtSignature")
-            if part_signature and thought_signature is None:
-                thought_signature = part_signature
-            part_metadata: dict[str, Any] | None = None
-            if part_signature:
-                part_metadata = {"thought_signature": part_signature}
-
-            if part.get("thought") is True:
-                t_text = part.get("text", "")
-                thought_summary_parts.append(t_text)
-                content_parts.append(LLMContentPart.thought_part(t_text))
-
-            elif "text" in part:
-                answer_parts.append(part["text"])
-                c_part = LLMContentPart(
-                    type="text", text=part["text"], metadata=part_metadata
-                )
-                content_parts.append(c_part)
-
-            elif "thoughtSummary" in part:
-                thought_summary_parts.append(part["thoughtSummary"])
-                content_parts.append(
-                    LLMContentPart.thought_part(part["thoughtSummary"])
-                )
-
-            elif "inlineData" in part:
-                inline_data = part["inlineData"]
-                if "data" in inline_data:
-                    decoded = base64.b64decode(inline_data["data"])
-                    images_payload.append(process_image_data(decoded))
-
-            elif "functionCall" in part:
-                if parsed_tool_calls is None:
-                    parsed_tool_calls = []
-                fc_data = part["functionCall"]
-                fc_sig = part_signature
-                try:
-                    call_id = f"call_gemini_{len(parsed_tool_calls)}"
-                    parsed_tool_calls.append(
-                        LLMToolCall(
-                            id=call_id,
-                            thought_signature=fc_sig,
-                            function=LLMToolFunction(
-                                name=fc_data["name"],
-                                arguments=json.dumps(fc_data["args"]),
-                            ),
-                        )
-                    )
-                except Exception as e:
-                    logger.warning(
-                        f"解析Gemini functionCall时出错: {fc_data}, 错误: {e}"
-                    )
-            elif "executableCode" in part:
-                exec_code = part["executableCode"]
-                lang = exec_code.get("language", "PYTHON")
-                code = exec_code.get("code", "")
-                content_parts.append(LLMContentPart.executable_code_part(lang, code))
-                answer_parts.append(f"\n[生成代码 ({lang})]:\n```python\n{code}\n```\n")
-
-            elif "codeExecutionResult" in part:
-                result = part["codeExecutionResult"]
-                outcome = result.get("outcome", CodeExecutionOutcome.OUTCOME_UNKNOWN)
-                output = result.get("output", "")
-
-                content_parts.append(
-                    LLMContentPart.execution_result_part(outcome, output)
-                )
-
-                parsed_code_executions.append(result)
-
-                if outcome == CodeExecutionOutcome.OUTCOME_OK:
-                    answer_parts.append(f"\n[代码执行结果]:\n```\n{output}\n```\n")
-                else:
-                    answer_parts.append(f"\n[代码执行失败 ({outcome})]:\n{output}\n")
-
-        full_answer = "".join(answer_parts).strip()
-        text_content = full_answer
-        final_thought_text = (
-            "\n\n".join(thought_summary_parts).strip()
-            if thought_summary_parts
-            else None
-        )
-
-        grounding_metadata_obj = None
-        if grounding_data := candidate.get("groundingMetadata"):
-            try:
-                sep_content = None
-                sep_field = grounding_data.get("searchEntryPoint")
-                if isinstance(sep_field, dict):
-                    sep_content = sep_field.get("renderedContent")
-
-                attributions = []
-                if chunks := grounding_data.get("groundingChunks"):
-                    for chunk in chunks:
-                        if web := chunk.get("web"):
-                            attributions.append(
-                                LLMGroundingAttribution(
-                                    title=web.get("title"),
-                                    uri=web.get("uri"),
-                                    snippet=web.get("snippet"),
-                                    confidence_score=None,
-                                )
-                            )
-
-                grounding_metadata_obj = LLMGroundingMetadata(
-                    web_search_queries=grounding_data.get("webSearchQueries"),
-                    grounding_attributions=attributions or None,
-                    search_suggestions=grounding_data.get("searchSuggestions"),
-                    search_entry_point=sep_content,
-                    map_widget_token=grounding_data.get("googleMapsWidgetContextToken"),
-                )
-            except Exception as e:
-                logger.warning(f"无法解析Grounding元数据: {grounding_data}, {e}")
-
-        return ResponseData(
-            text=text_content,
-            tool_calls=parsed_tool_calls,
-            code_executions=parsed_code_executions if parsed_code_executions else None,
-            content_parts=content_parts if content_parts else None,
-            images=images_payload if images_payload else None,
-            usage_info=usage_info,
-            raw_response=response_json,
-            grounding_metadata=grounding_metadata_obj,
-            thought_text=final_thought_text,
-            thought_signature=thought_signature,
-        )

zhenxun/services/llm/adapters/components/interfaces.py

@@ -1,43 +0,0 @@
-from abc import ABC, abstractmethod
-from typing import Any
-
-from zhenxun.services.llm.adapters.base import ResponseData
-from zhenxun.services.llm.config.generation import LLMGenerationConfig
-from zhenxun.services.llm.types import LLMMessage
-from zhenxun.services.llm.types.capabilities import ModelCapabilities
-from zhenxun.services.llm.types.models import ModelDetail, ToolDefinition
-
-
-class ConfigMapper(ABC):
-    @abstractmethod
-    def map_config(
-        self,
-        config: LLMGenerationConfig,
-        model_detail: ModelDetail | None = None,
-        capabilities: ModelCapabilities | None = None,
-    ) -> dict[str, Any]:
-        """将通用生成配置转换为特定 API 的参数字典"""
-        ...
-
-
-class MessageConverter(ABC):
-    @abstractmethod
-    def convert_messages(
-        self, messages: list[LLMMessage]
-    ) -> list[dict[str, Any]] | dict[str, Any]:
-        """将通用消息列表转换为特定 API 的消息格式"""
-        ...
-
-
-class ToolSerializer(ABC):
-    @abstractmethod
-    def serialize_tools(self, tools: list[ToolDefinition]) -> Any:
-        """将通用工具定义转换为特定 API 的工具格式"""
-        ...
-
-
-class ResponseParser(ABC):
-    @abstractmethod
-    def parse(self, response_json: dict[str, Any]) -> ResponseData:
-        """将特定 API 的响应解析为通用响应数据"""
-        ...

zhenxun/services/llm/adapters/components/openai_components.py

@@ -1,347 +0,0 @@
-import base64
-import binascii
-import json
-from pathlib import Path
-from typing import Any
-
-from zhenxun.services.llm.adapters.base import ResponseData, process_image_data
-from zhenxun.services.llm.adapters.components.interfaces import (
-    ConfigMapper,
-    MessageConverter,
-    ResponseParser,
-    ToolSerializer,
-)
-from zhenxun.services.llm.config.generation import (
-    ImageAspectRatio,
-    LLMGenerationConfig,
-    ResponseFormat,
-    StructuredOutputStrategy,
-)
-from zhenxun.services.llm.types import LLMMessage
-from zhenxun.services.llm.types.capabilities import ModelCapabilities
-from zhenxun.services.llm.types.exceptions import LLMErrorCode, LLMException
-from zhenxun.services.llm.types.models import (
-    LLMToolCall,
-    LLMToolFunction,
-    ModelDetail,
-    ToolDefinition,
-)
-from zhenxun.services.llm.utils import sanitize_schema_for_llm
-from zhenxun.services.log import logger
-from zhenxun.utils.pydantic_compat import model_dump
-
-
-class OpenAIConfigMapper(ConfigMapper):
-    def __init__(self, api_type: str = "openai"):
-        self.api_type = api_type
-
-    def map_config(
-        self,
-        config: LLMGenerationConfig,
-        model_detail: ModelDetail | None = None,
-        capabilities: ModelCapabilities | None = None,
-    ) -> dict[str, Any]:
-        params: dict[str, Any] = {}
-        strategy = config.output.structured_output_strategy if config.output else None
-        if strategy is None:
-            strategy = (
-                StructuredOutputStrategy.TOOL_CALL
-                if self.api_type == "deepseek"
-                else StructuredOutputStrategy.NATIVE
-            )
-
-        if config.core:
-            if config.core.temperature is not None:
-                params["temperature"] = config.core.temperature
-            if config.core.max_tokens is not None:
-                params["max_tokens"] = config.core.max_tokens
-            if config.core.top_k is not None:
-                params["top_k"] = config.core.top_k
-            if config.core.top_p is not None:
-                params["top_p"] = config.core.top_p
-            if config.core.frequency_penalty is not None:
-                params["frequency_penalty"] = config.core.frequency_penalty
-            if config.core.presence_penalty is not None:
-                params["presence_penalty"] = config.core.presence_penalty
-            if config.core.stop is not None:
-                params["stop"] = config.core.stop
-
-            if config.core.repetition_penalty is not None:
-                if self.api_type == "openai":
-                    logger.warning("OpenAI官方API不支持repetition_penalty参数，已忽略")
-                else:
-                    params["repetition_penalty"] = config.core.repetition_penalty
-
-        if config.reasoning and config.reasoning.effort:
-            params["reasoning_effort"] = config.reasoning.effort.value.lower()
-
-        if config.output:
-            if isinstance(config.output.response_format, dict):
-                params["response_format"] = config.output.response_format
-            elif (
-                config.output.response_format == ResponseFormat.JSON
-                and strategy == StructuredOutputStrategy.NATIVE
-            ):
-                if config.output.response_schema:
-                    sanitized = sanitize_schema_for_llm(
-                        config.output.response_schema, api_type="openai"
-                    )
-                    params["response_format"] = {
-                        "type": "json_schema",
-                        "json_schema": {
-                            "name": "structured_response",
-                            "schema": sanitized,
-                            "strict": True,
-                        },
-                    }
-                else:
-                    params["response_format"] = {"type": "json_object"}
-
-        if config.tool_config:
-            mode = config.tool_config.mode
-            if mode == "NONE":
-                params["tool_choice"] = "none"
-            elif mode == "AUTO":
-                params["tool_choice"] = "auto"
-            elif mode == "ANY":
-                params["tool_choice"] = "required"
-
-        if config.visual and config.visual.aspect_ratio:
-            size_map = {
-                ImageAspectRatio.SQUARE: "1024x1024",
-                ImageAspectRatio.LANDSCAPE_16_9: "1792x1024",
-                ImageAspectRatio.PORTRAIT_9_16: "1024x1792",
-            }
-            ar = config.visual.aspect_ratio
-            if isinstance(ar, ImageAspectRatio):
-                mapped_size = size_map.get(ar)
-                if mapped_size:
-                    params["size"] = mapped_size
-            elif isinstance(ar, str):
-                params["size"] = ar
-
-        if config.custom_params:
-            mapped_custom = config.custom_params.copy()
-            if "repetition_penalty" in mapped_custom and self.api_type == "openai":
-                mapped_custom.pop("repetition_penalty")
-
-            if "stop" in mapped_custom:
-                stop_value = mapped_custom["stop"]
-                if isinstance(stop_value, str):
-                    mapped_custom["stop"] = [stop_value]
-
-            params.update(mapped_custom)
-
-        return params
-
-
-class OpenAIMessageConverter(MessageConverter):
-    def convert_messages(self, messages: list[LLMMessage]) -> list[dict[str, Any]]:
-        openai_messages: list[dict[str, Any]] = []
-        for msg in messages:
-            openai_msg: dict[str, Any] = {"role": msg.role}
-
-            if msg.role == "tool":
-                openai_msg["tool_call_id"] = msg.tool_call_id
-                openai_msg["name"] = msg.name
-                openai_msg["content"] = msg.content
-            else:
-                if isinstance(msg.content, str):
-                    openai_msg["content"] = msg.content
-                else:
-                    content_parts = []
-                    for part in msg.content:
-                        if part.type == "text":
-                            content_parts.append({"type": "text", "text": part.text})
-                        elif part.type == "image":
-                            content_parts.append(
-                                {
-                                    "type": "image_url",
-                                    "image_url": {"url": part.image_source},
-                                }
-                            )
-                    openai_msg["content"] = content_parts
-
-            if msg.role == "assistant" and msg.tool_calls:
-                assistant_tool_calls = []
-                for call in msg.tool_calls:
-                    assistant_tool_calls.append(
-                        {
-                            "id": call.id,
-                            "type": "function",
-                            "function": {
-                                "name": call.function.name,
-                                "arguments": call.function.arguments,
-                            },
-                        }
-                    )
-                openai_msg["tool_calls"] = assistant_tool_calls
-
-            if msg.name and msg.role != "tool":
-                openai_msg["name"] = msg.name
-
-            openai_messages.append(openai_msg)
-        return openai_messages
-
-
-class OpenAIToolSerializer(ToolSerializer):
-    def serialize_tools(
-        self, tools: list[ToolDefinition]
-    ) -> list[dict[str, Any]] | None:
-        if not tools:
-            return None
-
-        openai_tools = []
-        for tool in tools:
-            tool_dict = model_dump(tool)
-            parameters = tool_dict.get("parameters")
-            if parameters:
-                tool_dict["parameters"] = sanitize_schema_for_llm(
-                    parameters, api_type="openai"
-                )
-            tool_dict["strict"] = True
-            openai_tools.append({"type": "function", "function": tool_dict})
-        return openai_tools
-
-
-class OpenAIResponseParser(ResponseParser):
-    def validate_response(self, response_json: dict[str, Any]) -> None:
-        if response_json.get("error"):
-            error_info = response_json["error"]
-            if isinstance(error_info, dict):
-                error_message = error_info.get("message", "未知错误")
-                error_code = error_info.get("code", "unknown")
-
-                error_code_mapping = {
-                    "invalid_api_key": LLMErrorCode.API_KEY_INVALID,
-                    "authentication_failed": LLMErrorCode.API_KEY_INVALID,
-                    "insufficient_quota": LLMErrorCode.API_QUOTA_EXCEEDED,
-                    "rate_limit_exceeded": LLMErrorCode.API_RATE_LIMITED,
-                    "quota_exceeded": LLMErrorCode.API_RATE_LIMITED,
-                    "model_not_found": LLMErrorCode.MODEL_NOT_FOUND,
-                    "invalid_model": LLMErrorCode.MODEL_NOT_FOUND,
-                    "context_length_exceeded": LLMErrorCode.CONTEXT_LENGTH_EXCEEDED,
-                    "max_tokens_exceeded": LLMErrorCode.CONTEXT_LENGTH_EXCEEDED,
-                    "invalid_request_error": LLMErrorCode.INVALID_PARAMETER,
-                    "invalid_parameter": LLMErrorCode.INVALID_PARAMETER,
-                }
-
-                llm_error_code = error_code_mapping.get(
-                    error_code, LLMErrorCode.API_RESPONSE_INVALID
-                )
-            else:
-                error_message = str(error_info)
-                error_code = "unknown"
-                llm_error_code = LLMErrorCode.API_RESPONSE_INVALID
-
-            raise LLMException(
-                f"API请求失败: {error_message}",
-                code=llm_error_code,
-                details={"api_error": error_info, "error_code": error_code},
-            )
-
-    def parse(self, response_json: dict[str, Any]) -> ResponseData:
-        self.validate_response(response_json)
-
-        choices = response_json.get("choices", [])
-        if not choices:
-            return ResponseData(text="", raw_response=response_json)
-
-        choice = choices[0]
-        message = choice.get("message", {})
-        content = message.get("content", "")
-        reasoning_content = message.get("reasoning_content", None)
-        refusal = message.get("refusal")
-
-        if refusal:
-            raise LLMException(
-                f"模型拒绝生成请求: {refusal}",
-                code=LLMErrorCode.CONTENT_FILTERED,
-                details={"refusal": refusal},
-                recoverable=False,
-            )
-
-        if content:
-            content = content.strip()
-
-        images_payload: list[bytes | Path] = []
-        if content and content.startswith("{") and content.endswith("}"):
-            try:
-                content_json = json.loads(content)
-                if "b64_json" in content_json:
-                    b64_str = content_json["b64_json"]
-                    if isinstance(b64_str, str) and b64_str.startswith("data:"):
-                        b64_str = b64_str.split(",", 1)[1]
-                    decoded = base64.b64decode(b64_str)
-                    images_payload.append(process_image_data(decoded))
-                    content = "[图片已生成]"
-                elif "data" in content_json and isinstance(content_json["data"], str):
-                    b64_str = content_json["data"]
-                    if b64_str.startswith("data:"):
-                        b64_str = b64_str.split(",", 1)[1]
-                    decoded = base64.b64decode(b64_str)
-                    images_payload.append(process_image_data(decoded))
-                    content = "[图片已生成]"
-
-            except (json.JSONDecodeError, KeyError, binascii.Error):
-                pass
-        elif (
-            "images" in message
-            and isinstance(message["images"], list)
-            and message["images"]
-        ):
-            for image_info in message["images"]:
-                if image_info.get("type") == "image_url":
-                    image_url_obj = image_info.get("image_url", {})
-                    url_str = image_url_obj.get("url", "")
-                    if url_str.startswith("data:image"):
-                        try:
-                            b64_data = url_str.split(",", 1)[1]
-                            decoded = base64.b64decode(b64_data)
-                            images_payload.append(process_image_data(decoded))
-                        except (IndexError, binascii.Error) as e:
-                            logger.warning(f"解析OpenRouter Base64图片数据失败: {e}")
-
-            if images_payload:
-                content = content if content else "[图片已生成]"
-
-        parsed_tool_calls: list[LLMToolCall] | None = None
-        if message_tool_calls := message.get("tool_calls"):
-            parsed_tool_calls = []
-            for tc_data in message_tool_calls:
-                try:
-                    if tc_data.get("type") == "function":
-                        parsed_tool_calls.append(
-                            LLMToolCall(
-                                id=tc_data["id"],
-                                function=LLMToolFunction(
-                                    name=tc_data["function"]["name"],
-                                    arguments=tc_data["function"]["arguments"],
-                                ),
-                            )
-                        )
-                except KeyError as e:
-                    logger.warning(
-                        f"解析OpenAI工具调用数据时缺少键: {tc_data}, 错误: {e}"
-                    )
-                except Exception as e:
-                    logger.warning(
-                        f"解析OpenAI工具调用数据时出错: {tc_data}, 错误: {e}"
-                    )
-            if not parsed_tool_calls:
-                parsed_tool_calls = None
-
-        final_text = content if content is not None else ""
-        if not final_text and parsed_tool_calls:
-            final_text = f"请求调用 {len(parsed_tool_calls)} 个工具。"
-
-        usage_info = response_json.get("usage")
-
-        return ResponseData(
-            text=final_text,
-            tool_calls=parsed_tool_calls,
-            usage_info=usage_info,
-            images=images_payload if images_payload else None,
-            raw_response=response_json,
-            thought_text=reasoning_content,
-        )

zhenxun/services/llm/adapters/factory.py

@@ -2,17 +2,10 @@
 LLM 适配器工厂类
 """
 
-import fnmatch
+from typing import ClassVar
-from typing import TYPE_CHECKING, Any, ClassVar
 
 from ..types.exceptions import LLMErrorCode, LLMException
-from ..types.models import ToolChoice
+from .base import BaseAdapter
-from .base import BaseAdapter, RequestData, ResponseData
-
-if TYPE_CHECKING:
-    from ..config.generation import LLMEmbeddingConfig, LLMGenerationConfig
-    from ..service import LLMModel
-    from ..types import LLMMessage
 
 
 class LLMAdapterFactory:
@@ -28,13 +21,10 @@ class LLMAdapterFactory:
             return
 
         from .gemini import GeminiAdapter
-        from .openai import DeepSeekAdapter, OpenAIAdapter, OpenAIImageAdapter
+        from .openai import OpenAIAdapter
 
         cls.register_adapter(OpenAIAdapter())
-        cls.register_adapter(DeepSeekAdapter())
         cls.register_adapter(GeminiAdapter())
-        cls.register_adapter(SmartAdapter())
-        cls.register_adapter(OpenAIImageAdapter())
 
     @classmethod
     def register_adapter(cls, adapter: BaseAdapter) -> None:
@@ -84,100 +74,3 @@ def get_adapter_for_api_type(api_type: str) -> BaseAdapter:
 def register_adapter(adapter: BaseAdapter) -> None:
     """注册新的适配器"""
     LLMAdapterFactory.register_adapter(adapter)
-
-
-class SmartAdapter(BaseAdapter):
-    """
-    智能路由适配器。
-    本身不处理序列化，而是根据规则委托给 OpenAIAdapter 或 GeminiAdapter。
-    """
-
-    @property
-    def log_sanitization_context(self) -> str:
-        return "openai_request"
-
-    _ROUTING_RULES: ClassVar[list[tuple[str, str]]] = [
-        ("*nano-banana*", "gemini"),
-        ("*gemini*", "gemini"),
-    ]
-    _DEFAULT_API_TYPE: ClassVar[str] = "openai"
-
-    def __init__(self):
-        self._adapter_cache: dict[str, BaseAdapter] = {}
-
-    @property
-    def api_type(self) -> str:
-        return "smart"
-
-    @property
-    def supported_api_types(self) -> list[str]:
-        return ["smart"]
-
-    def _get_delegate_adapter(self, model: "LLMModel") -> BaseAdapter:
-        """
-        核心路由逻辑：决定使用哪个适配器 (带缓存)
-        """
-        if model.model_detail.api_type:
-            return get_adapter_for_api_type(model.model_detail.api_type)
-
-        model_name = model.model_name
-        if model_name in self._adapter_cache:
-            return self._adapter_cache[model_name]
-
-        target_api_type = self._DEFAULT_API_TYPE
-        model_name_lower = model_name.lower()
-
-        for pattern, api_type in self._ROUTING_RULES:
-            if fnmatch.fnmatch(model_name_lower, pattern):
-                target_api_type = api_type
-                break
-
-        adapter = get_adapter_for_api_type(target_api_type)
-        self._adapter_cache[model_name] = adapter
-        return adapter
-
-    async def prepare_advanced_request(
-        self,
-        model: "LLMModel",
-        api_key: str,
-        messages: list["LLMMessage"],
-        config: "LLMGenerationConfig | None" = None,
-        tools: list[Any] | None = None,
-        tool_choice: "str | dict[str, Any] | ToolChoice | None" = None,
-    ) -> RequestData:
-        adapter = self._get_delegate_adapter(model)
-        return await adapter.prepare_advanced_request(
-            model, api_key, messages, config, tools, tool_choice
-        )
-
-    def parse_response(
-        self,
-        model: "LLMModel",
-        response_json: dict[str, Any],
-        is_advanced: bool = False,
-    ) -> ResponseData:
-        adapter = self._get_delegate_adapter(model)
-        return adapter.parse_response(model, response_json, is_advanced)
-
-    def prepare_embedding_request(
-        self,
-        model: "LLMModel",
-        api_key: str,
-        texts: list[str],
-        config: "LLMEmbeddingConfig",
-    ) -> RequestData:
-        adapter = self._get_delegate_adapter(model)
-        return adapter.prepare_embedding_request(model, api_key, texts, config)
-
-    def parse_embedding_response(
-        self, response_json: dict[str, Any]
-    ) -> list[list[float]]:
-        return get_adapter_for_api_type("openai").parse_embedding_response(
-            response_json
-        )
-
-    def convert_generation_config(
-        self, config: "LLMGenerationConfig", model: "LLMModel"
-    ) -> dict[str, Any]:
-        adapter = self._get_delegate_adapter(model)
-        return adapter.convert_generation_config(config, model)

zhenxun/services/llm/adapters/gemini.py

@@ -2,35 +2,27 @@
 Gemini API 适配器
 """
 
+import base64
 from typing import TYPE_CHECKING, Any
 
 from zhenxun.services.log import logger
 
-from ..config.generation import ResponseFormat
-from ..types import LLMContentPart
 from ..types.exceptions import LLMErrorCode, LLMException
-from ..types.models import BasePlatformTool, ToolChoice
+from ..utils import sanitize_schema_for_llm
 from .base import BaseAdapter, RequestData, ResponseData
-from .components.gemini_components import (
-    GeminiConfigMapper,
-    GeminiMessageConverter,
-    GeminiResponseParser,
-    GeminiToolSerializer,
-)
 
 if TYPE_CHECKING:
-    from ..config.generation import LLMEmbeddingConfig, LLMGenerationConfig
+    from ..config.generation import LLMGenerationConfig
     from ..service import LLMModel
-    from ..types import LLMMessage
+    from ..types.content import LLMMessage
+    from ..types.enums import EmbeddingTaskType
+    from ..types.models import LLMToolCall
+    from ..types.protocols import ToolExecutable
 
 
 class GeminiAdapter(BaseAdapter):
     """Gemini API 适配器"""
 
-    @property
-    def log_sanitization_context(self) -> str:
-        return "gemini_request"
-
     @property
     def api_type(self) -> str:
         return "gemini"
@@ -55,75 +47,110 @@ class GeminiAdapter(BaseAdapter):
         api_key: str,
         messages: list["LLMMessage"],
         config: "LLMGenerationConfig | None" = None,
-        tools: list[Any] | None = None,
+        tools: dict[str, "ToolExecutable"] | None = None,
-        tool_choice: str | dict[str, Any] | ToolChoice | None = None,
+        tool_choice: str | dict[str, Any] | None = None,
     ) -> RequestData:
         """准备高级请求"""
         effective_config = config if config is not None else model._generation_config
 
-        if tools:
-            from ..types.models import GeminiUrlContext
-
-            context_urls: list[str] = []
-            for tool in tools:
-                if isinstance(tool, GeminiUrlContext):
-                    context_urls.extend(tool.urls)
-
-            if context_urls and messages:
-                last_msg = messages[-1]
-                if last_msg.role == "user":
-                    url_text = "\n\n[Context URLs]:\n" + "\n".join(context_urls)
-                    if isinstance(last_msg.content, str):
-                        last_msg.content += url_text
-                    elif isinstance(last_msg.content, list):
-                        last_msg.content.append(LLMContentPart.text_part(url_text))
-
-        has_function_tools = False
-        if tools:
-            has_function_tools = any(hasattr(tool, "get_definition") for tool in tools)
-
-        is_structured = False
-        if effective_config and effective_config.output:
-            if (
-                effective_config.output.response_schema
-                or effective_config.output.response_format == ResponseFormat.JSON
-                or effective_config.output.response_mime_type == "application/json"
-            ):
-                is_structured = True
-
-        if (has_function_tools or is_structured) and effective_config:
-            if effective_config.reasoning is None:
-                from ..config.generation import ReasoningConfig
-
-                effective_config.reasoning = ReasoningConfig()
-
-            if (
-                effective_config.reasoning.budget_tokens is None
-                and effective_config.reasoning.effort is None
-            ):
-                reason_desc = "工具调用" if has_function_tools else "结构化输出"
-                logger.debug(
-                    f"检测到{reason_desc}，自动为模型 {model.model_name} 开启思维链增强"
-                )
-                effective_config.reasoning.budget_tokens = -1
-
         endpoint = self._get_gemini_endpoint(model, effective_config)
         url = self.get_api_url(model, endpoint)
         headers = self.get_base_headers(api_key)
 
-        converter = GeminiMessageConverter()
+        gemini_contents: list[dict[str, Any]] = []
         system_instruction_parts: list[dict[str, Any]] | None = None
+
         for msg in messages:
+            current_parts: list[dict[str, Any]] = []
             if msg.role == "system":
                 if isinstance(msg.content, str):
                     system_instruction_parts = [{"text": msg.content}]
                 elif isinstance(msg.content, list):
                     system_instruction_parts = [
-                        await converter.convert_part(part) for part in msg.content
+                        await part.convert_for_api_async("gemini")
+                        for part in msg.content
                     ]
                 continue
 
-        gemini_contents = await converter.convert_messages_async(messages)
+            elif msg.role == "user":
+                if isinstance(msg.content, str):
+                    current_parts.append({"text": msg.content})
+                elif isinstance(msg.content, list):
+                    for part_obj in msg.content:
+                        current_parts.append(
+                            await part_obj.convert_for_api_async("gemini")
+                        )
+                gemini_contents.append({"role": "user", "parts": current_parts})
+
+            elif msg.role == "assistant" or msg.role == "model":
+                if isinstance(msg.content, str) and msg.content:
+                    current_parts.append({"text": msg.content})
+                elif isinstance(msg.content, list):
+                    for part_obj in msg.content:
+                        current_parts.append(
+                            await part_obj.convert_for_api_async("gemini")
+                        )
+
+                if msg.tool_calls:
+                    import json
+
+                    for call in msg.tool_calls:
+                        current_parts.append(
+                            {
+                                "functionCall": {
+                                    "name": call.function.name,
+                                    "args": json.loads(call.function.arguments),
+                                }
+                            }
+                        )
+                if current_parts:
+                    gemini_contents.append({"role": "model", "parts": current_parts})
+
+            elif msg.role == "tool":
+                if not msg.name:
+                    raise ValueError("Gemini 工具消息必须包含 'name' 字段（函数名）。")
+
+                import json
+
+                try:
+                    content_str = (
+                        msg.content
+                        if isinstance(msg.content, str)
+                        else str(msg.content)
+                    )
+                    tool_result_obj = json.loads(content_str)
+                except json.JSONDecodeError:
+                    content_str = (
+                        msg.content
+                        if isinstance(msg.content, str)
+                        else str(msg.content)
+                    )
+                    logger.warning(
+                        f"工具 {msg.name} 的结果不是有效的 JSON: {content_str}. "
+                        f"包装为原始字符串。"
+                    )
+                    tool_result_obj = {"raw_output": content_str}
+
+                if isinstance(tool_result_obj, list):
+                    logger.debug(
+                        f"工具 '{msg.name}' 的返回结果是列表，"
+                        f"正在为Gemini API包装为JSON对象。"
+                    )
+                    final_response_payload = {"result": tool_result_obj}
+                elif not isinstance(tool_result_obj, dict):
+                    final_response_payload = {"result": tool_result_obj}
+                else:
+                    final_response_payload = tool_result_obj
+
+                current_parts.append(
+                    {
+                        "functionResponse": {
+                            "name": msg.name,
+                            "response": final_response_payload,
+                        }
+                    }
+                )
+                gemini_contents.append({"role": "function", "parts": current_parts})
 
         body: dict[str, Any] = {"contents": gemini_contents}
 
@@ -131,78 +158,75 @@ class GeminiAdapter(BaseAdapter):
             body["systemInstruction"] = {"parts": system_instruction_parts}
 
         all_tools_for_request = []
-        has_user_functions = False
         if tools:
-            from ..types.protocols import ToolExecutable
+            import asyncio
 
-            function_tools: list[ToolExecutable] = []
+            from zhenxun.utils.pydantic_compat import model_dump
-            gemini_tools_dict: dict[str, Any] = {}
 
-            for tool in tools:
+            definition_tasks = [
-                if isinstance(tool, BasePlatformTool):
+                executable.get_definition() for executable in tools.values()
-                    declaration = tool.get_tool_declaration()
+            ]
-                    if declaration:
+            tool_definitions = await asyncio.gather(*definition_tasks)
-                        gemini_tools_dict.update(declaration)
-                elif hasattr(tool, "get_definition"):
-                    function_tools.append(tool)
 
-            if function_tools:
+            function_declarations = []
-                import asyncio
+            for tool_def in tool_definitions:
+                tool_def.parameters = sanitize_schema_for_llm(
+                    tool_def.parameters, api_type="gemini"
+                )
+                function_declarations.append(model_dump(tool_def))
 
-                definition_tasks = [
+            if function_declarations:
-                    executable.get_definition() for executable in function_tools
+                all_tools_for_request.append(
-                ]
+                    {"functionDeclarations": function_declarations}
-                tool_definitions = await asyncio.gather(*definition_tasks)
+                )
 
-                serializer = GeminiToolSerializer()
+        if effective_config:
-                function_declarations = serializer.serialize_tools(tool_definitions)
+            if getattr(effective_config, "enable_grounding", False):
+                has_explicit_gs_tool = any(
+                    "googleSearch" in tool_item for tool_item in all_tools_for_request
+                )
+                if not has_explicit_gs_tool:
+                    all_tools_for_request.append({"googleSearch": {}})
+                    logger.debug("隐式启用 Google Search 工具进行信息来源关联。")
 
-                if function_declarations:
+            if getattr(effective_config, "enable_code_execution", False):
-                    gemini_tools_dict["functionDeclarations"] = function_declarations
+                has_explicit_ce_tool = any(
-                    has_user_functions = True
+                    "codeExecution" in tool_item for tool_item in all_tools_for_request
-
+                )
-            if gemini_tools_dict:
+                if not has_explicit_ce_tool:
-                all_tools_for_request.append(gemini_tools_dict)
+                    all_tools_for_request.append({"codeExecution": {}})
+                    logger.debug("隐式启用代码执行工具。")
 
         if all_tools_for_request:
             body["tools"] = all_tools_for_request
 
-        tool_config_updates: dict[str, Any] = {}
+        final_tool_choice = tool_choice
-        if (
+        if final_tool_choice is None and effective_config:
-            effective_config
+            final_tool_choice = getattr(effective_config, "tool_choice", None)
-            and effective_config.custom_params
-            and "user_location" in effective_config.custom_params
-        ):
-            tool_config_updates["retrievalConfig"] = {
-                "latLng": effective_config.custom_params["user_location"]
-            }
 
-        if tool_config_updates:
+        if final_tool_choice:
-            body.setdefault("toolConfig", {}).update(tool_config_updates)
+            if isinstance(final_tool_choice, str):
-
+                mode_upper = final_tool_choice.upper()
-        converted_params: dict[str, Any] = {}
+                if mode_upper in ["AUTO", "NONE", "ANY"]:
-        if effective_config:
+                    body["toolConfig"] = {"functionCallingConfig": {"mode": mode_upper}}
-            converted_params = self.convert_generation_config(effective_config, model)
+                else:
-
+                    body["toolConfig"] = self._convert_tool_choice_to_gemini(
-        if converted_params:
+                        final_tool_choice
-            if "toolConfig" in converted_params:
-                tool_config_payload = converted_params.pop("toolConfig")
-                fc_config = tool_config_payload.get("functionCallingConfig")
-                should_apply_fc = has_user_functions or (
-                    fc_config and fc_config.get("mode") == "NONE"
-                )
-                if should_apply_fc:
-                    body.setdefault("toolConfig", {}).update(tool_config_payload)
-                elif fc_config and fc_config.get("mode") != "AUTO":
-                    logger.debug(
-                        "Gemini: 忽略针对纯内置工具的 functionCallingConfig (API限制)"
                     )
+            else:
+                body["toolConfig"] = self._convert_tool_choice_to_gemini(
+                    final_tool_choice
+                )
 
-            if "safetySettings" in converted_params:
+        final_generation_config = self._build_gemini_generation_config(
-                body["safetySettings"] = converted_params.pop("safetySettings")
+            model, effective_config
+        )
+        if final_generation_config:
+            body["generationConfig"] = final_generation_config
 
-            if converted_params:
+        safety_settings = self._build_safety_settings(effective_config)
-                body["generationConfig"] = converted_params
+        if safety_settings:
+            body["safetySettings"] = safety_settings
 
         return RequestData(url=url, headers=headers, body=body)
 
@@ -218,56 +242,299 @@ class GeminiAdapter(BaseAdapter):
     def _get_gemini_endpoint(
         self, model: "LLMModel", config: "LLMGenerationConfig | None" = None
     ) -> str:
-        """返回Gemini generateContent 端点"""
+        """根据配置选择Gemini API端点"""
+        if config:
+            if getattr(config, "enable_code_execution", False):
+                return f"/v1beta/models/{model.model_name}:generateContent"
+
+            if getattr(config, "enable_grounding", False):
+                return f"/v1beta/models/{model.model_name}:generateContent"
+
         return f"/v1beta/models/{model.model_name}:generateContent"
 
+    def _convert_tool_choice_to_gemini(
+        self, tool_choice_value: str | dict[str, Any]
+    ) -> dict[str, Any]:
+        """转换工具选择策略为Gemini格式"""
+        if isinstance(tool_choice_value, str):
+            mode_upper = tool_choice_value.upper()
+            if mode_upper in ["AUTO", "NONE", "ANY"]:
+                return {"functionCallingConfig": {"mode": mode_upper}}
+            else:
+                logger.warning(
+                    f"不支持的 tool_choice 字符串值: '{tool_choice_value}'。"
+                    f"回退到 AUTO。"
+                )
+                return {"functionCallingConfig": {"mode": "AUTO"}}
+
+        elif isinstance(tool_choice_value, dict):
+            if (
+                tool_choice_value.get("type") == "function"
+                and "function" in tool_choice_value
+            ):
+                func_name = tool_choice_value["function"].get("name")
+                if func_name:
+                    return {
+                        "functionCallingConfig": {
+                            "mode": "ANY",
+                            "allowedFunctionNames": [func_name],
+                        }
+                    }
+                else:
+                    logger.warning(
+                        f"tool_choice dict 中的函数名无效: {tool_choice_value}。"
+                        f"回退到 AUTO。"
+                    )
+                    return {"functionCallingConfig": {"mode": "AUTO"}}
+
+            elif "functionCallingConfig" in tool_choice_value:
+                return {
+                    "functionCallingConfig": tool_choice_value["functionCallingConfig"]
+                }
+
+            else:
+                logger.warning(
+                    f"不支持的 tool_choice dict 值: {tool_choice_value}。回退到 AUTO。"
+                )
+                return {"functionCallingConfig": {"mode": "AUTO"}}
+
+        logger.warning(
+            f"tool_choice 的类型无效: {type(tool_choice_value)}。回退到 AUTO。"
+        )
+        return {"functionCallingConfig": {"mode": "AUTO"}}
+
+    def _build_gemini_generation_config(
+        self, model: "LLMModel", config: "LLMGenerationConfig | None" = None
+    ) -> dict[str, Any]:
+        """构建Gemini生成配置"""
+        effective_config = config if config is not None else model._generation_config
+
+        if not effective_config:
+            return {}
+
+        generation_config = effective_config.to_api_params(
+            api_type="gemini", model_name=model.model_name
+        )
+
+        if generation_config:
+            param_keys = list(generation_config.keys())
+            logger.debug(
+                f"构建Gemini生成配置完成，包含 {len(generation_config)} 个参数: "
+                f"{param_keys}"
+            )
+
+        return generation_config
+
+    def _build_safety_settings(
+        self, config: "LLMGenerationConfig | None" = None
+    ) -> list[dict[str, Any]] | None:
+        """构建安全设置"""
+        if not config:
+            return None
+
+        safety_settings = []
+
+        safety_categories = [
+            "HARM_CATEGORY_HARASSMENT",
+            "HARM_CATEGORY_HATE_SPEECH",
+            "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+            "HARM_CATEGORY_DANGEROUS_CONTENT",
+        ]
+
+        custom_safety_settings = getattr(config, "safety_settings", None)
+        if custom_safety_settings:
+            for category, threshold in custom_safety_settings.items():
+                safety_settings.append({"category": category, "threshold": threshold})
+        else:
+            from ..config.providers import get_gemini_safety_threshold
+
+            threshold = get_gemini_safety_threshold()
+            for category in safety_categories:
+                safety_settings.append({"category": category, "threshold": threshold})
+
+        return safety_settings if safety_settings else None
+
     def parse_response(
         self,
         model: "LLMModel",
         response_json: dict[str, Any],
         is_advanced: bool = False,
+    ) -> ResponseData:
+        """解析API响应"""
+        return self._parse_response(model, response_json, is_advanced)
+
+    def _parse_response(
+        self,
+        model: "LLMModel",
+        response_json: dict[str, Any],
+        is_advanced: bool = False,
     ) -> ResponseData:
         """解析 Gemini API 响应"""
-        _ = model, is_advanced
+        _ = is_advanced
-        parser = GeminiResponseParser()
+        self.validate_response(response_json)
-        return parser.parse(response_json)
+
+        try:
+            if "image_generation" in response_json and isinstance(
+                response_json["image_generation"], dict
+            ):
+                candidates_source = response_json["image_generation"]
+            else:
+                candidates_source = response_json
+
+            candidates = candidates_source.get("candidates", [])
+            usage_info = response_json.get("usageMetadata")
+
+            if not candidates:
+                logger.debug("Gemini响应中没有candidates。")
+                return ResponseData(text="", raw_response=response_json)
+
+            candidate = candidates[0]
+
+            if candidate.get("finishReason") in [
+                "RECITATION",
+                "OTHER",
+            ] and not candidate.get("content"):
+                logger.warning(
+                    f"Gemini candidate finished with reason "
+                    f"'{candidate.get('finishReason')}' and no content."
+                )
+                return ResponseData(
+                    text="",
+                    raw_response=response_json,
+                    usage_info=response_json.get("usageMetadata"),
+                )
+
+            content_data = candidate.get("content", {})
+            parts = content_data.get("parts", [])
+
+            text_content = ""
+            images_bytes: list[bytes] = []
+            parsed_tool_calls: list["LLMToolCall"] | None = None
+            thought_summary_parts = []
+            answer_parts = []
+
+            for part in parts:
+                if "text" in part:
+                    answer_parts.append(part["text"])
+                elif "thought" in part:
+                    thought_summary_parts.append(part["thought"])
+                elif "thoughtSummary" in part:
+                    thought_summary_parts.append(part["thoughtSummary"])
+                elif "inlineData" in part:
+                    inline_data = part["inlineData"]
+                    if "data" in inline_data:
+                        images_bytes.append(base64.b64decode(inline_data["data"]))
+
+                elif "functionCall" in part:
+                    if parsed_tool_calls is None:
+                        parsed_tool_calls = []
+                    fc_data = part["functionCall"]
+                    try:
+                        import json
+
+                        from ..types.models import LLMToolCall, LLMToolFunction
+
+                        call_id = f"call_{model.provider_name}_{len(parsed_tool_calls)}"
+                        parsed_tool_calls.append(
+                            LLMToolCall(
+                                id=call_id,
+                                function=LLMToolFunction(
+                                    name=fc_data["name"],
+                                    arguments=json.dumps(fc_data["args"]),
+                                ),
+                            )
+                        )
+                    except KeyError as e:
+                        logger.warning(
+                            f"解析Gemini functionCall时缺少键: {fc_data}, 错误: {e}"
+                        )
+                    except Exception as e:
+                        logger.warning(
+                            f"解析Gemini functionCall时出错: {fc_data}, 错误: {e}"
+                        )
+                elif "codeExecutionResult" in part:
+                    result = part["codeExecutionResult"]
+                    if result.get("outcome") == "OK":
+                        output = result.get("output", "")
+                        answer_parts.append(f"\n[代码执行结果]:\n```\n{output}\n```\n")
+                    else:
+                        answer_parts.append(
+                            f"\n[代码执行失败]: {result.get('outcome', 'UNKNOWN')}\n"
+                        )
+
+            if thought_summary_parts:
+                full_thought_summary = "\n".join(thought_summary_parts).strip()
+                full_answer = "".join(answer_parts).strip()
+
+                formatted_parts = []
+                if full_thought_summary:
+                    formatted_parts.append(f"🤔 **思考过程**\n\n{full_thought_summary}")
+                if full_answer:
+                    separator = "\n\n---\n\n" if full_thought_summary else ""
+                    formatted_parts.append(f"{separator}✅ **回答**\n\n{full_answer}")
+
+                text_content = "".join(formatted_parts)
+            else:
+                text_content = "".join(answer_parts)
+
+            usage_info = response_json.get("usageMetadata")
+
+            grounding_metadata_obj = None
+            if grounding_data := candidate.get("groundingMetadata"):
+                try:
+                    from ..types.models import LLMGroundingMetadata
+
+                    grounding_metadata_obj = LLMGroundingMetadata(**grounding_data)
+                except Exception as e:
+                    logger.warning(f"无法解析Grounding元数据: {grounding_data}, {e}")
+
+            return ResponseData(
+                text=text_content,
+                tool_calls=parsed_tool_calls,
+                images=images_bytes if images_bytes else None,
+                usage_info=usage_info,
+                raw_response=response_json,
+                grounding_metadata=grounding_metadata_obj,
+            )
+
+        except Exception as e:
+            logger.error(f"解析 Gemini 响应失败: {e}", e=e)
+            raise LLMException(
+                f"解析API响应失败: {e}",
+                code=LLMErrorCode.RESPONSE_PARSE_ERROR,
+                cause=e,
+            )
 
     def prepare_embedding_request(
         self,
         model: "LLMModel",
         api_key: str,
         texts: list[str],
-        config: "LLMEmbeddingConfig",
+        task_type: "EmbeddingTaskType | str",
+        **kwargs: Any,
     ) -> RequestData:
         """准备文本嵌入请求"""
         api_model_name = model.model_name
         if not api_model_name.startswith("models/"):
             api_model_name = f"models/{api_model_name}"
 
-        if not model.api_base:
+        url = self.get_api_url(model, f"/{api_model_name}:batchEmbedContents")
-            raise LLMException(
-                f"模型 {model.model_name} 的 api_base 未设置",
-                code=LLMErrorCode.CONFIGURATION_ERROR,
-            )
-
-        base_url = model.api_base.rstrip("/")
-        url = f"{base_url}/v1beta/{api_model_name}:batchEmbedContents"
         headers = self.get_base_headers(api_key)
 
         requests_payload = []
         for text_content in texts:
-            safe_text = text_content if text_content else " "
             request_item: dict[str, Any] = {
-                "model": api_model_name,
+                "content": {"parts": [{"text": text_content}]},
-                "content": {"parts": [{"text": safe_text}]},
             }
 
-            if config.task_type:
+            from ..types.enums import EmbeddingTaskType
-                request_item["task_type"] = str(config.task_type).upper()
+
-            if config.title:
+            if task_type and task_type != EmbeddingTaskType.RETRIEVAL_DOCUMENT:
-                request_item["title"] = config.title
+                request_item["task_type"] = str(task_type).upper()
-            if config.output_dimensionality:
+            if title := kwargs.get("title"):
-                request_item["output_dimensionality"] = config.output_dimensionality
+                request_item["title"] = title
+            if output_dimensionality := kwargs.get("output_dimensionality"):
+                request_item["output_dimensionality"] = output_dimensionality
 
             requests_payload.append(request_item)
 
@@ -316,9 +583,3 @@ class GeminiAdapter(BaseAdapter):
                     code=LLMErrorCode.RESPONSE_PARSE_ERROR,
                     details=response_json,
                 )
-
-    def convert_generation_config(
-        self, config: "LLMGenerationConfig", model: "LLMModel"
-    ) -> dict[str, Any]:
-        mapper = GeminiConfigMapper()
-        return mapper.map_config(config, model.model_detail, model.capabilities)

zhenxun/services/llm/adapters/openai.py

@@ -1,181 +1,15 @@
 """
 OpenAI API 适配器
 
-支持 OpenAI、智谱AI 等 OpenAI 兼容的 API 服务。
+支持 OpenAI、DeepSeek、智谱AI 和其他 OpenAI 兼容的 API 服务。
 """
 
-from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
-import base64
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
 
-import json_repair
+from .base import OpenAICompatAdapter
-
-from zhenxun.services.llm.config.generation import ImageAspectRatio
-from zhenxun.services.llm.types.exceptions import LLMErrorCode, LLMException
-from zhenxun.services.log import logger
-from zhenxun.utils.http_utils import AsyncHttpx
-
-from ..types import StructuredOutputStrategy
-from ..types.models import ToolChoice
-from ..utils import sanitize_schema_for_llm
-from .base import (
-    BaseAdapter,
-    OpenAICompatAdapter,
-    RequestData,
-    ResponseData,
-    process_image_data,
-)
-from .components.openai_components import (
-    OpenAIConfigMapper,
-    OpenAIMessageConverter,
-    OpenAIResponseParser,
-    OpenAIToolSerializer,
-)
 
 if TYPE_CHECKING:
-    from ..config.generation import LLMEmbeddingConfig, LLMGenerationConfig
     from ..service import LLMModel
-    from ..types import LLMMessage
-
-
-class APIProtocol(ABC):
-    """API 协议策略基类"""
-
-    @abstractmethod
-    def build_request_body(
-        self,
-        model: "LLMModel",
-        messages: list["LLMMessage"],
-        tools: list[dict[str, Any]] | None,
-        tool_choice: Any,
-    ) -> dict[str, Any]:
-        """构建不同协议下的请求体"""
-        pass
-
-    @abstractmethod
-    def parse_response(self, response_json: dict[str, Any]) -> ResponseData:
-        """解析不同协议下的响应"""
-        pass
-
-
-class StandardProtocol(APIProtocol):
-    """标准 OpenAI 协议策略"""
-
-    def __init__(self, adapter: "OpenAICompatAdapter"):
-        self.adapter = adapter
-
-    def build_request_body(
-        self,
-        model: "LLMModel",
-        messages: list["LLMMessage"],
-        tools: list[dict[str, Any]] | None,
-        tool_choice: Any,
-    ) -> dict[str, Any]:
-        converter = OpenAIMessageConverter()
-        openai_messages = converter.convert_messages(messages)
-        body: dict[str, Any] = {
-            "model": model.model_name,
-            "messages": openai_messages,
-        }
-        if tools:
-            body["tools"] = tools
-        if tool_choice:
-            body["tool_choice"] = tool_choice
-        return body
-
-    def parse_response(self, response_json: dict[str, Any]) -> ResponseData:
-        parser = OpenAIResponseParser()
-        return parser.parse(response_json)
-
-
-class ResponsesProtocol(APIProtocol):
-    """/v1/responses 新版协议策略"""
-
-    def __init__(self, adapter: "OpenAICompatAdapter"):
-        self.adapter = adapter
-
-    def build_request_body(
-        self,
-        model: "LLMModel",
-        messages: list["LLMMessage"],
-        tools: list[dict[str, Any]] | None,
-        tool_choice: Any,
-    ) -> dict[str, Any]:
-        input_items: list[dict[str, Any]] = []
-
-        for msg in messages:
-            role = msg.role
-            content_list: list[dict[str, Any]] = []
-            raw_contents = (
-                msg.content if isinstance(msg.content, list) else [msg.content]
-            )
-
-            for part in raw_contents:
-                if part is None:
-                    continue
-                if isinstance(part, str):
-                    content_list.append({"type": "input_text", "text": part})
-                    continue
-
-                if hasattr(part, "type"):
-                    part_type = getattr(part, "type", None)
-                    if part_type == "text":
-                        content_list.append(
-                            {"type": "input_text", "text": getattr(part, "text", "")}
-                        )
-                    elif part_type == "image":
-                        content_list.append(
-                            {
-                                "type": "input_image",
-                                "image_url": getattr(part, "image_source", ""),
-                            }
-                        )
-                    continue
-
-                if isinstance(part, dict):
-                    part_type = part.get("type")
-                    if part_type == "text":
-                        content_list.append(
-                            {"type": "input_text", "text": part.get("text", "")}
-                        )
-                    elif part_type in {"image", "image_url"}:
-                        image_src = part.get("image_url") or part.get(
-                            "image_source", ""
-                        )
-                        content_list.append(
-                            {
-                                "type": "input_image",
-                                "image_url": image_src,
-                            }
-                        )
-
-            input_items.append({"role": role, "content": content_list})
-
-        body: dict[str, Any] = {
-            "model": model.model_name,
-            "input": input_items,
-        }
-        if tools:
-            body["tools"] = tools
-        if tool_choice:
-            body["tool_choice"] = tool_choice
-        return body
-
-    def parse_response(self, response_json: dict[str, Any]) -> ResponseData:
-        self.adapter.validate_response(response_json)
-        text_content = ""
-        for item in response_json.get("output", []):
-            if item.get("type") == "message" and item.get("role") == "assistant":
-                for content_item in item.get("content", []):
-                    if content_item.get("type") == "output_text":
-                        text_content += content_item.get("text", "")
-
-        return ResponseData(
-            text=text_content,
-            usage_info=response_json.get("usage"),
-            raw_response=response_json,
-        )
 
 
 class OpenAIAdapter(OpenAICompatAdapter):
@@ -189,411 +23,23 @@ class OpenAIAdapter(OpenAICompatAdapter):
     def supported_api_types(self) -> list[str]:
         return [
             "openai",
+            "deepseek",
             "zhipu",
+            "general_openai_compat",
             "ark",
             "openrouter",
-            "openai_responses",
         ]
 
     def get_chat_endpoint(self, model: "LLMModel") -> str:
         """返回聊天完成端点"""
-        if model.model_detail.endpoint:
+        if model.api_type == "ark":
-            return model.model_detail.endpoint
-
-        current_api_type = model.model_detail.api_type or model.api_type
-
-        if current_api_type == "openai_responses":
-            return "/v1/responses"
-        if current_api_type == "ark":
             return "/api/v3/chat/completions"
-        if current_api_type == "zhipu":
+        if model.api_type == "zhipu":
             return "/api/paas/v4/chat/completions"
         return "/v1/chat/completions"
 
-    def _get_protocol_strategy(self, model: "LLMModel") -> APIProtocol:
-        """根据 API 类型获取对应的处理策略"""
-        current_api_type = model.model_detail.api_type or model.api_type
-        if current_api_type == "openai_responses":
-            return ResponsesProtocol(self)
-        return StandardProtocol(self)
-
     def get_embedding_endpoint(self, model: "LLMModel") -> str:
         """根据API类型返回嵌入端点"""
         if model.api_type == "zhipu":
             return "/v4/embeddings"
         return "/v1/embeddings"
-
-    def convert_generation_config(
-        self, config: "LLMGenerationConfig", model: "LLMModel"
-    ) -> dict[str, Any]:
-        mapper = OpenAIConfigMapper(api_type=self.api_type)
-        return mapper.map_config(config, model.model_detail, model.capabilities)
-
-    async def prepare_advanced_request(
-        self,
-        model: "LLMModel",
-        api_key: str,
-        messages: list["LLMMessage"],
-        config: "LLMGenerationConfig | None" = None,
-        tools: list[Any] | None = None,
-        tool_choice: str | dict[str, Any] | ToolChoice | None = None,
-    ) -> "RequestData":
-        """根据不同协议策略构建高级请求"""
-        url = self.get_api_url(model, self.get_chat_endpoint(model))
-        headers = self.get_base_headers(api_key)
-        if model.api_type == "openrouter":
-            headers.update(
-                {
-                    "HTTP-Referer": "https://github.com/zhenxun-org/zhenxun_bot",
-                    "X-Title": "Zhenxun Bot",
-                }
-            )
-
-        default_config = getattr(model, "_generation_config", None)
-        effective_config = config if config is not None else default_config
-        structured_strategy = (
-            effective_config.output.structured_output_strategy
-            if effective_config and effective_config.output
-            else None
-        )
-        if structured_strategy is None:
-            structured_strategy = StructuredOutputStrategy.NATIVE
-
-        openai_tools: list[dict[str, Any]] | None = None
-        executables: list[Any] = []
-        if tools:
-            if isinstance(tools, dict):
-                executables = list(tools.values())
-            else:
-                for tool in tools:
-                    if hasattr(tool, "get_definition"):
-                        executables.append(tool)
-
-        definition_tasks = [executable.get_definition() for executable in executables]
-        tool_defs: list[Any] = []
-        if definition_tasks:
-            import asyncio
-
-            tool_defs = await asyncio.gather(*definition_tasks)
-
-        if tool_defs:
-            serializer = OpenAIToolSerializer()
-            openai_tools = serializer.serialize_tools(tool_defs)
-
-        final_tool_choice = tool_choice
-        if final_tool_choice is None:
-            if (
-                effective_config
-                and effective_config.tool_config
-                and effective_config.tool_config.mode == "ANY"
-            ):
-                allowed = effective_config.tool_config.allowed_function_names
-                if allowed:
-                    if len(allowed) == 1:
-                        final_tool_choice = {
-                            "type": "function",
-                            "function": {"name": allowed[0]},
-                        }
-                    else:
-                        logger.warning(
-                            "OpenAI API 不支持多个 allowed_function_names，降级为"
-                            " required。"
-                        )
-                        final_tool_choice = "required"
-                else:
-                    final_tool_choice = "required"
-
-        if (
-            structured_strategy == StructuredOutputStrategy.TOOL_CALL
-            and effective_config
-            and effective_config.output
-            and effective_config.output.response_schema
-        ):
-            sanitized_schema = sanitize_schema_for_llm(
-                effective_config.output.response_schema, api_type="openai"
-            )
-            structured_tool = {
-                "type": "function",
-                "function": {
-                    "name": "return_structured_response",
-                    "description": "Return the final structured response.",
-                    "parameters": sanitized_schema,
-                    "strict": True if model.api_type != "deepseek" else False,
-                },
-            }
-            if openai_tools is None:
-                openai_tools = []
-            openai_tools.append(structured_tool)
-            final_tool_choice = {
-                "type": "function",
-                "function": {"name": "return_structured_response"},
-            }
-
-        protocol_strategy = self._get_protocol_strategy(model)
-        body = protocol_strategy.build_request_body(
-            model=model,
-            messages=messages,
-            tools=openai_tools,
-            tool_choice=final_tool_choice,
-        )
-
-        body = self.apply_config_override(model, body, config)
-
-        if final_tool_choice is not None:
-            body["tool_choice"] = final_tool_choice
-
-        response_format = body.get("response_format", {})
-        inject_prompt = (
-            structured_strategy == StructuredOutputStrategy.NATIVE
-            and isinstance(response_format, dict)
-            and response_format.get("type") == "json_object"
-        )
-
-        if inject_prompt:
-            messages_list = body.get("messages", [])
-            has_json_keyword = False
-            for msg in messages_list:
-                content = msg.get("content")
-                if isinstance(content, str) and "json" in content.lower():
-                    has_json_keyword = True
-                    break
-                if isinstance(content, list):
-                    for part in content:
-                        if (
-                            isinstance(part, dict)
-                            and part.get("type") == "text"
-                            and "json" in part.get("text", "").lower()
-                        ):
-                            has_json_keyword = True
-                            break
-                    if has_json_keyword:
-                        break
-
-            if not has_json_keyword:
-                injection_text = (
-                    "请务必输出合法的 JSON 格式，避免额外的文本、Markdown 或解释。"
-                )
-                system_msg = next(
-                    (m for m in messages_list if m.get("role") == "system"), None
-                )
-                if system_msg:
-                    if isinstance(system_msg.get("content"), str):
-                        system_msg["content"] += " " + injection_text
-                    elif isinstance(system_msg.get("content"), list):
-                        system_msg["content"].append(
-                            {"type": "text", "text": injection_text}
-                        )
-                else:
-                    messages_list.insert(
-                        0, {"role": "system", "content": injection_text}
-                    )
-                body["messages"] = messages_list
-
-        return RequestData(url=url, headers=headers, body=body)
-
-    def parse_response(
-        self,
-        model: "LLMModel",
-        response_json: dict[str, Any],
-        is_advanced: bool = False,
-    ) -> ResponseData:
-        """解析响应 - 使用策略模式委托处理"""
-        _ = is_advanced
-        protocol_strategy = self._get_protocol_strategy(model)
-        response_data = protocol_strategy.parse_response(response_json)
-
-        if response_data.tool_calls:
-            target_tool = next(
-                (
-                    tc
-                    for tc in response_data.tool_calls
-                    if tc.function.name == "return_structured_response"
-                ),
-                None,
-            )
-            if target_tool:
-                response_data.text = json_repair.repair_json(
-                    target_tool.function.arguments
-                )
-                remaining = [
-                    tc
-                    for tc in response_data.tool_calls
-                    if tc.function.name != "return_structured_response"
-                ]
-                response_data.tool_calls = remaining or None
-
-        return response_data
-
-
-class DeepSeekAdapter(OpenAIAdapter):
-    """DeepSeek 专用适配器 (基于 OpenAI 协议)"""
-
-    @property
-    def api_type(self) -> str:
-        return "deepseek"
-
-    @property
-    def supported_api_types(self) -> list[str]:
-        return ["deepseek"]
-
-
-class OpenAIImageAdapter(BaseAdapter):
-    """OpenAI 图像生成/编辑适配器"""
-
-    @property
-    def api_type(self) -> str:
-        return "openai_image"
-
-    @property
-    def log_sanitization_context(self) -> str:
-        return "openai_request"
-
-    @property
-    def supported_api_types(self) -> list[str]:
-        return ["openai_image", "nano_banana"]
-
-    async def prepare_advanced_request(
-        self,
-        model: "LLMModel",
-        api_key: str,
-        messages: list["LLMMessage"],
-        config: "LLMGenerationConfig | None" = None,
-        tools: list[Any] | None = None,
-        tool_choice: "str | dict[str, Any] | ToolChoice | None" = None,
-    ) -> RequestData:
-        _ = tools, tool_choice
-        effective_config = config if config is not None else model._generation_config
-        headers = self.get_base_headers(api_key)
-
-        prompt = ""
-        images_bytes_list: list[bytes] = []
-
-        for msg in reversed(messages):
-            if msg.role != "user":
-                continue
-            if isinstance(msg.content, str):
-                prompt = msg.content
-            elif isinstance(msg.content, list):
-                for part in msg.content:
-                    if part.type == "text" and not prompt:
-                        prompt = part.text
-                    elif part.type == "image":
-                        if part.is_image_base64():
-                            if b64_data := part.get_base64_data():
-                                _, b64_str = b64_data
-                                images_bytes_list.append(base64.b64decode(b64_str))
-                        elif part.is_image_url() and part.image_source:
-                            images_bytes_list.append(
-                                await AsyncHttpx.get_content(part.image_source)
-                            )
-            if prompt:
-                break
-
-        if not prompt and not images_bytes_list:
-            raise LLMException(
-                "图像生成需要提供 Prompt",
-                code=LLMErrorCode.CONFIGURATION_ERROR,
-            )
-
-        body: dict[str, Any] = {
-            "model": model.model_name,
-            "prompt": prompt,
-            "response_format": "b64_json",
-        }
-
-        if effective_config:
-            if effective_config.visual:
-                if effective_config.visual.aspect_ratio:
-                    ar = effective_config.visual.aspect_ratio
-                    size_map = {
-                        ImageAspectRatio.SQUARE: "1024x1024",
-                        ImageAspectRatio.LANDSCAPE_16_9: "1792x1024",
-                        ImageAspectRatio.PORTRAIT_9_16: "1024x1792",
-                    }
-                    if isinstance(ar, ImageAspectRatio) and ar in size_map:
-                        body["size"] = size_map[ar]
-                        body["aspect_ratio"] = ar.value
-                    elif isinstance(ar, str):
-                        if "x" in ar:
-                            body["size"] = ar
-                        else:
-                            body["aspect_ratio"] = ar
-
-                if effective_config.visual.resolution:
-                    res_val = effective_config.visual.resolution
-                    if not isinstance(res_val, str):
-                        res_val = getattr(res_val, "value", res_val)
-                    body["image_size"] = res_val
-
-            if effective_config.custom_params:
-                body.update(effective_config.custom_params)
-
-        if images_bytes_list:
-            b64_images = []
-            for img_bytes in images_bytes_list:
-                b64_str = base64.b64encode(img_bytes).decode("utf-8")
-                b64_images.append(b64_str)
-            body["image"] = b64_images
-
-        endpoint = "/v1/images/generations"
-        url = self.get_api_url(model, endpoint)
-        return RequestData(url=url, headers=headers, body=body)
-
-    def parse_response(
-        self,
-        model: "LLMModel",
-        response_json: dict[str, Any],
-        is_advanced: bool = False,
-    ) -> ResponseData:
-        _ = model, is_advanced
-        self.validate_response(response_json)
-
-        images_data: list[bytes | Path] = []
-        data_list = response_json.get("data", [])
-
-        for item in data_list:
-            if "b64_json" in item:
-                try:
-                    b64_str = item["b64_json"]
-                    if b64_str.startswith("data:"):
-                        b64_str = b64_str.split(",", 1)[1]
-                    img = base64.b64decode(b64_str)
-                    images_data.append(process_image_data(img))
-                except Exception as exc:
-                    logger.error(f"Base64 解码失败: {exc}")
-            elif "url" in item:
-                logger.warning(
-                    f"API 返回了 URL 而不是 Base64: {item.get('url', 'unknown')}"
-                )
-
-        text_summary = (
-            f"已生成 {len(images_data)} 张图片。"
-            if images_data
-            else "图像生成接口调用成功，但未解析到图片数据。"
-        )
-
-        return ResponseData(
-            text=text_summary,
-            images=images_data if images_data else None,
-            raw_response=response_json,
-        )
-
-    def prepare_embedding_request(
-        self,
-        model: "LLMModel",
-        api_key: str,
-        texts: list[str],
-        config: "LLMEmbeddingConfig",
-    ) -> RequestData:
-        raise NotImplementedError("OpenAIImageAdapter 不支持 Embedding")
-
-    def parse_embedding_response(
-        self, response_json: dict[str, Any]
-    ) -> list[list[float]]:
-        raise NotImplementedError("OpenAIImageAdapter 不支持 Embedding")
-
-    def convert_generation_config(
-        self, config: "LLMGenerationConfig", model: "LLMModel"
-    ) -> dict[str, Any]:
-        _ = config, model
-        return {}

zhenxun/services/llm/api.py

@@ -2,7 +2,6 @@
 LLM 服务的高级 API 接口 - 便捷函数入口 (无状态)
 """
 
-from collections.abc import Awaitable, Callable
 from pathlib import Path
 from typing import Any, TypeVar, overload
 
@@ -12,25 +11,19 @@ from pydantic import BaseModel
 from zhenxun.services.log import logger
 
 from .config import CommonOverrides
-from .config.generation import (
+from .config.generation import LLMGenerationConfig, create_generation_config_from_kwargs
-    GenConfigBuilder,
-    LLMEmbeddingConfig,
-    LLMGenerationConfig,
-    OutputConfig,
-)
 from .manager import get_model_instance
 from .session import AI
+from .tools.manager import tool_provider_manager
 from .types import (
+    EmbeddingTaskType,
     LLMContentPart,
     LLMErrorCode,
     LLMException,
     LLMMessage,
     LLMResponse,
     ModelName,
-    ToolChoice,
 )
-from .types.exceptions import get_user_friendly_error_message
-from .types.models import GeminiGoogleSearch
 from .utils import create_multimodal_message
 
 T = TypeVar("T", bound=BaseModel)
@@ -41,10 +34,9 @@ async def chat(
     *,
     model: ModelName = None,
     instruction: str | None = None,
-    tools: list[Any] | None = None,
+    tools: list[dict[str, Any] | str] | None = None,
-    tool_choice: str | dict[str, Any] | ToolChoice | None = None,
+    tool_choice: str | dict[str, Any] | None = None,
-    config: LLMGenerationConfig | GenConfigBuilder | None = None,
+    **kwargs: Any,
-    timeout: float | None = None,
 ) -> LLMResponse:
     """
     无状态的聊天对话便捷函数，通过临时的AI会话实例与LLM模型交互。
@@ -55,13 +47,14 @@ async def chat(
         instruction: 系统指令，用于指导AI的行为和回复风格。
         tools: 可用的工具列表，支持字典配置或字符串标识符。
         tool_choice: 工具选择策略，控制AI如何选择和使用工具。
-        config: (可选) 生成配置对象，将与默认配置合并后传递。
+        **kwargs: 额外的生成配置参数，会被转换为LLMGenerationConfig。
-        timeout: (可选) HTTP 请求超时时间（秒）。
 
     返回:
         LLMResponse: 包含AI回复内容、使用信息和工具调用等的完整响应对象。
     """
     try:
+        config = create_generation_config_from_kwargs(**kwargs) if kwargs else None
+
         ai_session = AI()
 
         return await ai_session.chat(
@@ -71,14 +64,12 @@ async def chat(
             tools=tools,
             tool_choice=tool_choice,
             config=config,
-            timeout=timeout,
         )
     except LLMException:
         raise
     except Exception as e:
-        friendly_msg = get_user_friendly_error_message(e)
+        logger.error(f"执行 chat 函数失败: {e}", e=e)
-        logger.error(f"执行 chat 函数失败: {e} | 建议: {friendly_msg}", e=e)
+        raise LLMException(f"聊天执行失败: {e}", cause=e)
-        raise LLMException(f"聊天执行失败: {friendly_msg}", cause=e)
 
 
 async def code(
@@ -86,6 +77,7 @@ async def code(
     *,
     model: ModelName = None,
     timeout: int | None = None,
+    **kwargs: Any,
 ) -> LLMResponse:
     """
     无状态的代码执行便捷函数，支持在沙箱环境中执行代码。
@@ -94,25 +86,66 @@ async def code(
         prompt: 代码执行的提示词，描述要执行的代码任务。
         model: 要使用的模型名称，默认使用Gemini/gemini-2.0-flash。
         timeout: 代码执行超时时间（秒），防止长时间运行的代码阻塞。
+        **kwargs: 额外的生成配置参数。
 
     返回:
         LLMResponse: 包含代码执行结果的完整响应对象。
     """
-    resolved_model = model
+    resolved_model = model or "Gemini/gemini-2.0-flash"
 
     config = CommonOverrides.gemini_code_execution()
     if timeout:
         config.custom_params = config.custom_params or {}
         config.custom_params["code_execution_timeout"] = timeout
 
-    return await chat(prompt, model=resolved_model, config=config)
+    final_config = config.to_dict()
+    final_config.update(kwargs)
+
+    return await chat(prompt, model=resolved_model, **final_config)
+
+
+async def search(
+    query: str | UniMessage | LLMMessage | list[LLMContentPart],
+    *,
+    model: ModelName = None,
+    instruction: str = (
+        "你是一位强大的信息检索和整合专家。请利用可用的搜索工具，"
+        "根据用户的查询找到最相关的信息，并进行总结和回答。"
+    ),
+    **kwargs: Any,
+) -> LLMResponse:
+    """
+    无状态的信息搜索便捷函数，利用搜索工具获取实时信息。
+
+    参数:
+        query: 搜索查询内容，支持多种输入格式。
+        model: 要使用的模型名称，如果为None则使用默认模型。
+        instruction: 搜索任务的系统指令，指导AI如何处理搜索结果。
+        **kwargs: 额外的生成配置参数。
+
+    返回:
+        LLMResponse: 包含搜索结果和AI整合回复的完整响应对象。
+    """
+    logger.debug("执行无状态 'search' 任务...")
+    search_config = CommonOverrides.gemini_grounding()
+
+    final_config = search_config.to_dict()
+    final_config.update(kwargs)
+
+    return await chat(
+        query,
+        model=model,
+        instruction=instruction,
+        **final_config,
+    )
 
 
 async def embed(
     texts: list[str] | str,
     *,
     model: ModelName = None,
-    config: LLMEmbeddingConfig | None = None,
+    task_type: EmbeddingTaskType | str = EmbeddingTaskType.RETRIEVAL_DOCUMENT,
+    **kwargs: Any,
 ) -> list[list[float]]:
     """
     无状态的文本嵌入便捷函数，将文本转换为向量表示。
@@ -120,7 +153,8 @@ async def embed(
     参数:
         texts: 要生成嵌入的文本内容，支持单个字符串或字符串列表。
         model: 要使用的嵌入模型名称，如果为None则使用默认模型。
-        config: 嵌入配置对象。
+        task_type: 嵌入任务类型，影响向量的优化方向（如检索、分类等）。
+        **kwargs: 额外的模型配置参数。
 
     返回:
         list[list[float]]: 文本对应的嵌入向量列表，每个向量为浮点数列表。
@@ -130,71 +164,27 @@ async def embed(
     if not texts:
         return []
 
-    final_config = config or LLMEmbeddingConfig()
-
     try:
         async with await get_model_instance(model) as model_instance:
-            return await model_instance.generate_embeddings(texts, config=final_config)
+            return await model_instance.generate_embeddings(
+                texts, task_type=task_type, **kwargs
+            )
     except LLMException:
         raise
     except Exception as e:
-        friendly_msg = get_user_friendly_error_message(e)
+        logger.error(f"文本嵌入失败: {e}", e=e)
-        logger.error(f"文本嵌入失败: {e} | 建议: {friendly_msg}", e=e)
         raise LLMException(
-            f"文本嵌入失败: {friendly_msg}",
+            f"文本嵌入失败: {e}", code=LLMErrorCode.EMBEDDING_FAILED, cause=e
-            code=LLMErrorCode.EMBEDDING_FAILED,
-            cause=e,
         )
 
 
-async def embed_query(
-    text: str,
-    *,
-    model: ModelName = None,
-    dimensions: int | None = None,
-) -> list[float]:
-    """
-    语义化便捷 API：为检索查询生成嵌入。
-    """
-    config = LLMEmbeddingConfig(
-        task_type="RETRIEVAL_QUERY",
-        output_dimensionality=dimensions,
-    )
-    vectors = await embed([text], model=model, config=config)
-    return vectors[0] if vectors else []
-
-
-async def embed_documents(
-    texts: list[str],
-    *,
-    model: ModelName = None,
-    dimensions: int | None = None,
-    title: str | None = None,
-) -> list[list[float]]:
-    """
-    语义化便捷 API：为文档集合生成嵌入。
-    """
-    config = LLMEmbeddingConfig(
-        task_type="RETRIEVAL_DOCUMENT",
-        output_dimensionality=dimensions,
-        title=title,
-    )
-    return await embed(texts, model=model, config=config)
-
-
 async def generate_structured(
-    message: str | UniMessage | LLMMessage | list[LLMContentPart],
+    message: str | LLMMessage | list[LLMContentPart],
     response_model: type[T],
     *,
     model: ModelName = None,
-    tools: list[Any] | None = None,
-    tool_choice: str | dict[str, Any] | ToolChoice | None = None,
-    max_validation_retries: int | None = None,
-    validation_callback: Callable[[T], Any | Awaitable[Any]] | None = None,
-    error_prompt_template: str | None = None,
-    auto_thinking: bool = False,
     instruction: str | None = None,
-    timeout: float | None = None,
+    **kwargs: Any,
 ) -> T:
     """
     无状态地生成结构化响应，并自动解析为指定的Pydantic模型。
@@ -202,48 +192,39 @@ async def generate_structured(
     参数:
         message: 用户输入的消息内容，支持多种格式。
         response_model: 用于解析和验证响应的Pydantic模型类。
-        max_validation_retries: 校验失败时的最大重试次数，默认为 None (使用全局配置)。
-        validation_callback: 自定义校验回调函数，抛出异常视为校验失败。
-        error_prompt_template: 自定义错误反馈提示词模板。
-        auto_thinking: 是否自动开启思维链 (CoT) 包装。适用于不支持原生思考的模型
         model: 要使用的模型名称，如果为None则使用默认模型。
         instruction: 系统指令，用于指导AI生成符合要求的结构化输出。
-        timeout: HTTP 请求超时时间（秒）。
+        **kwargs: 额外的生成配置参数。
 
     返回:
         T: 解析后的Pydantic模型实例，类型为response_model指定的类型。
     """
     try:
+        config = create_generation_config_from_kwargs(**kwargs) if kwargs else None
+
         ai_session = AI()
 
         return await ai_session.generate_structured(
             message,
             response_model,
             model=model,
-            tools=tools,
-            tool_choice=tool_choice,
-            max_validation_retries=max_validation_retries,
-            validation_callback=validation_callback,
-            error_prompt_template=error_prompt_template,
-            auto_thinking=auto_thinking,
             instruction=instruction,
-            timeout=timeout,
+            config=config,
         )
     except LLMException:
         raise
     except Exception as e:
-        friendly_msg = get_user_friendly_error_message(e)
+        logger.error(f"生成结构化响应失败: {e}", e=e)
-        logger.error(f"生成结构化响应失败: {e} | 建议: {friendly_msg}", e=e)
+        raise LLMException(f"生成结构化响应失败: {e}", cause=e)
-        raise LLMException(f"生成结构化响应失败: {friendly_msg}", cause=e)
 
 
 async def generate(
     messages: list[LLMMessage],
     *,
     model: ModelName = None,
-    tools: list[Any] | None = None,
+    tools: list[dict[str, Any] | str] | None = None,
-    tool_choice: str | dict[str, Any] | ToolChoice | None = None,
+    tool_choice: str | dict[str, Any] | None = None,
-    config: LLMGenerationConfig | GenConfigBuilder | None = None,
+    **kwargs: Any,
 ) -> LLMResponse:
     """
     根据完整的消息列表生成一次性响应，这是一个无状态的底层函数。
@@ -253,56 +234,109 @@ async def generate(
         model: 要使用的模型名称，如果为None则使用默认模型。
         tools: 可用的工具列表，支持字典配置或字符串标识符。
         tool_choice: 工具选择策略，控制AI如何选择和使用工具。
-        config: (可选) 生成配置对象，将与默认配置合并后传递。
+        **kwargs: 额外的生成配置参数，会覆盖默认配置。
 
     返回:
         LLMResponse: 包含AI回复内容、使用信息和工具调用等的完整响应对象。
     """
     try:
-        if isinstance(config, GenConfigBuilder):
-            config = config.build()
-
         async with await get_model_instance(
-            model, override_config=None
+            model, override_config=kwargs
         ) as model_instance:
             return await model_instance.generate_response(
                 messages,
-                config=config,
+                tools=tools,  # type: ignore
-                tools=tools,  # type: ignore[arg-type]
                 tool_choice=tool_choice,
             )
     except LLMException:
         raise
     except Exception as e:
-        friendly_msg = get_user_friendly_error_message(e)
+        logger.error(f"生成响应失败: {e}", e=e)
-        logger.error(f"生成响应失败: {e} | 建议: {friendly_msg}", e=e)
+        raise LLMException(f"生成响应失败: {e}", cause=e)
-        raise LLMException(f"生成响应失败: {friendly_msg}", cause=e)
+
+
+async def run_with_tools(
+    message: str | UniMessage | LLMMessage | list[LLMContentPart],
+    *,
+    model: ModelName = None,
+    instruction: str | None = None,
+    tools: list[str],
+    max_cycles: int = 5,
+    **kwargs: Any,
+) -> LLMResponse:
+    """
+    无状态地执行一个带本地Python函数的LLM调用循环。
+
+    参数:
+        message: 用户输入。
+        model: 使用的模型。
+        instruction: 系统指令。
+        tools: 要使用的本地函数工具名称列表 (必须已通过 @function_tool 注册)。
+        max_cycles: 最大工具调用循环次数。
+        **kwargs: 额外的生成配置参数。
+
+    返回:
+        LLMResponse: 包含最终回复的响应对象。
+    """
+    from .executor import ExecutionConfig, LLMToolExecutor
+    from .utils import normalize_to_llm_messages
+
+    messages = await normalize_to_llm_messages(message, instruction)
+
+    async with await get_model_instance(
+        model, override_config=kwargs
+    ) as model_instance:
+        resolved_tools = await tool_provider_manager.get_function_tools(tools)
+        if not resolved_tools:
+            logger.warning(
+                "run_with_tools 未找到任何可用的本地函数工具，将作为普通聊天执行。"
+            )
+            return await model_instance.generate_response(messages, tools=None)
+
+        executor = LLMToolExecutor(model_instance)
+        config = ExecutionConfig(max_cycles=max_cycles)
+        final_history = await executor.run(messages, resolved_tools, config)
+
+        for msg in reversed(final_history):
+            if msg.role == "assistant":
+                text = msg.content if isinstance(msg.content, str) else str(msg.content)
+                return LLMResponse(text=text, tool_calls=msg.tool_calls)
+
+    raise LLMException(
+        "带工具的执行循环未能产生有效的助手回复。", code=LLMErrorCode.GENERATION_FAILED
+    )
 
 
 async def _generate_image_from_message(
     message: UniMessage,
     model: ModelName = None,
-    config: LLMGenerationConfig | GenConfigBuilder | None = None,
+    **kwargs: Any,
 ) -> LLMResponse:
     """
     [内部] 从 UniMessage 生成图片的核心辅助函数。
     """
     from .utils import normalize_to_llm_messages
 
-    if isinstance(config, GenConfigBuilder):
+    config = (
-        config = config.build()
+        create_generation_config_from_kwargs(**kwargs)
-
+        if kwargs
-    config = config or LLMGenerationConfig()
+        else LLMGenerationConfig()
+    )
 
     config.validation_policy = {"require_image": True}
-    if config.output is None:
+    config.response_modalities = ["IMAGE", "TEXT"]
-        config.output = OutputConfig()
-    config.output.response_modalities = ["IMAGE", "TEXT"]
 
     try:
         messages = await normalize_to_llm_messages(message)
 
         async with await get_model_instance(model) as model_instance:
+            if not model_instance.can_generate_images():
+                raise LLMException(
+                    f"模型 '{model_instance.provider_name}/{model_instance.model_name}'"
+                    f"不支持图片生成",
+                    code=LLMErrorCode.CONFIGURATION_ERROR,
+                )
+
             response = await model_instance.generate_response(messages, config=config)
 
             if not response.images:
@@ -313,9 +347,8 @@ async def _generate_image_from_message(
     except LLMException:
         raise
     except Exception as e:
-        friendly_msg = get_user_friendly_error_message(e)
+        logger.error(f"执行图片生成时发生未知错误: {e}", e=e)
-        logger.error(f"执行图片生成时发生未知错误: {e} | 建议: {friendly_msg}", e=e)
+        raise LLMException(f"图片生成失败: {e}", cause=e)
-        raise LLMException(f"图片生成失败: {friendly_msg}", cause=e)
 
 
 @overload
@@ -324,6 +357,7 @@ async def create_image(
     *,
     images: None = None,
     model: ModelName = None,
+    **kwargs: Any,
 ) -> LLMResponse:
     """根据文本提示生成一张新图片。"""
     ...
@@ -335,6 +369,7 @@ async def create_image(
     *,
     images: list[Path | bytes | str] | Path | bytes | str,
     model: ModelName = None,
+    **kwargs: Any,
 ) -> LLMResponse:
     """在给定图片的基础上，根据文本提示进行编辑或重新生成。"""
     ...
@@ -345,7 +380,7 @@ async def create_image(
     *,
     images: list[Path | bytes | str] | Path | bytes | str | None = None,
     model: ModelName = None,
-    config: LLMGenerationConfig | GenConfigBuilder | None = None,
+    **kwargs: Any,
 ) -> LLMResponse:
     """
     智能图片生成/编辑函数。
@@ -365,43 +400,4 @@ async def create_image(
 
     message = create_multimodal_message(text=text_prompt, images=image_list)
 
-    return await _generate_image_from_message(message, model=model, config=config)
+    return await _generate_image_from_message(message, model=model, **kwargs)
-
-
-async def search(
-    query: str | UniMessage | LLMMessage | list[LLMContentPart],
-    *,
-    model: ModelName = None,
-    instruction: str = (
-        "你是一位强大的信息检索和整合专家。请利用可用的搜索工具，"
-        "根据用户的查询找到最相关的信息，并进行总结和回答。"
-    ),
-    config: LLMGenerationConfig | GenConfigBuilder | None = None,
-) -> LLMResponse:
-    """
-    无状态的信息搜索便捷函数，利用搜索工具获取实时信息。
-
-    参数:
-        query: 搜索查询内容，支持多种输入格式。
-        model: 要使用的模型名称，如果为None则使用默认模型。
-        config: (可选) 生成配置对象，将与预设配置合并后传递。
-        instruction: 搜索任务的系统指令，指导AI如何处理搜索结果。
-
-    返回:
-        LLMResponse: 包含搜索结果和AI整合回复的完整响应对象。
-    """
-    logger.debug("执行无状态 'search' 任务...")
-    search_config = CommonOverrides.gemini_grounding()
-
-    if isinstance(config, GenConfigBuilder):
-        config = config.build()
-
-    final_config = search_config.merge_with(config)
-
-    return await chat(
-        query,
-        model=model,
-        instruction=instruction,
-        config=final_config,
-        tools=[GeminiGoogleSearch()],
-    )

zhenxun/services/llm/config/__init__.py

@@ -5,12 +5,13 @@ LLM 配置模块
 """
 
 from .generation import (
-    CommonOverrides,
-    GenConfigBuilder,
-    LLMEmbeddingConfig,
     LLMGenerationConfig,
+    ModelConfigOverride,
+    apply_api_specific_mappings,
+    create_generation_config_from_kwargs,
     validate_override_params,
 )
+from .presets import CommonOverrides
 from .providers import (
     LLMConfig,
     get_gemini_safety_threshold,
@@ -22,10 +23,11 @@ from .providers import (
 
 __all__ = [
     "CommonOverrides",
-    "GenConfigBuilder",
     "LLMConfig",
-    "LLMEmbeddingConfig",
     "LLMGenerationConfig",
+    "ModelConfigOverride",
+    "apply_api_specific_mappings",
+    "create_generation_config_from_kwargs",
     "get_gemini_safety_threshold",
     "get_llm_config",
     "register_llm_configs",

zhenxun/services/llm/config/generation.py

@@ -3,397 +3,209 @@ LLM 生成配置相关类和函数
 """
 
 from collections.abc import Callable
-from enum import Enum
+from typing import Any
-from typing import Any, Literal
-from typing_extensions import Self
 
 from pydantic import BaseModel, ConfigDict, Field
 
 from zhenxun.services.log import logger
-from zhenxun.utils.pydantic_compat import model_copy, model_dump, model_validate
+from zhenxun.utils.pydantic_compat import model_dump
 
-from ..types import LLMResponse, ResponseFormat, StructuredOutputStrategy
+from ..types import LLMResponse
+from ..types.enums import ResponseFormat
 from ..types.exceptions import LLMErrorCode, LLMException
-from .providers import get_gemini_safety_threshold
 
 
-class ReasoningEffort(str, Enum):
+class ModelConfigOverride(BaseModel):
-    """推理努力程度枚举"""
+    """模型配置覆盖参数"""
-
-    LOW = "LOW"
-    MEDIUM = "MEDIUM"
-    HIGH = "HIGH"
-
-
-class ImageAspectRatio(str, Enum):
-    """图像宽高比枚举"""
-
-    SQUARE = "1:1"
-    LANDSCAPE_16_9 = "16:9"
-    PORTRAIT_9_16 = "9:16"
-    LANDSCAPE_4_3 = "4:3"
-    PORTRAIT_3_4 = "3:4"
-    LANDSCAPE_3_2 = "3:2"
-    PORTRAIT_2_3 = "2:3"
-
-
-class ImageResolution(str, Enum):
-    """图像分辨率/质量枚举"""
-
-    STANDARD = "STANDARD"
-    HD = "HD"
-
-
-class CoreConfig(BaseModel):
-    """核心生成参数"""
 
     temperature: float | None = Field(
         default=None, ge=0.0, le=2.0, description="生成温度"
     )
-    """生成温度"""
     max_tokens: int | None = Field(default=None, gt=0, description="最大输出token数")
-    """最大输出token数"""
     top_p: float | None = Field(default=None, ge=0.0, le=1.0, description="核采样参数")
-    """核采样参数"""
     top_k: int | None = Field(default=None, gt=0, description="Top-K采样参数")
-    """Top-K采样参数"""
     frequency_penalty: float | None = Field(
         default=None, ge=-2.0, le=2.0, description="频率惩罚"
     )
-    """频率惩罚"""
     presence_penalty: float | None = Field(
         default=None, ge=-2.0, le=2.0, description="存在惩罚"
     )
-    """存在惩罚"""
     repetition_penalty: float | None = Field(
         default=None, ge=0.0, le=2.0, description="重复惩罚"
     )
-    """重复惩罚"""
+
     stop: list[str] | str | None = Field(default=None, description="停止序列")
-    """停止序列"""
-
-
-class ReasoningConfig(BaseModel):
-    """推理能力配置"""
-
-    effort: ReasoningEffort | None = Field(
-        default=None, description="推理努力程度 (适用于 O1, Gemini 3)"
-    )
-    """推理努力程度 (适用于 O1, Gemini 3)"""
-    budget_tokens: int | None = Field(
-        default=None, description="具体的思考 Token 预算 (适用于 Gemini 2.5)"
-    )
-    """具体的思考 Token 预算 (适用于 Gemini 2.5)"""
-    show_thoughts: bool | None = Field(
-        default=None, description="是否在响应中显式包含思维链内容"
-    )
-    """是否在响应中显式包含思维链内容"""
-
-
-class VisualConfig(BaseModel):
-    """视觉生成配置"""
-
-    aspect_ratio: ImageAspectRatio | str | None = Field(
-        default=None, description="宽高比"
-    )
-    """宽高比"""
-    resolution: ImageResolution | str | None = Field(
-        default=None, description="生成质量/分辨率"
-    )
-    """生成质量/分辨率"""
-    media_resolution: str | None = Field(
-        default=None,
-        description="输入媒体的解析度 (Gemini 3+): 'LOW', 'MEDIUM', 'HIGH'",
-    )
-    """输入媒体的解析度 (Gemini 3+): 'LOW', 'MEDIUM', 'HIGH'"""
-    style: str | None = Field(
-        default=None, description="图像风格 (如 DALL-E 3 vivid/natural)"
-    )
-    """图像风格 (如 DALL-E 3 vivid/natural)"""
-
-
-class OutputConfig(BaseModel):
-    """输出格式控制"""
 
     response_format: ResponseFormat | dict[str, Any] | None = Field(
         default=None, description="期望的响应格式"
     )
-    """期望的响应格式"""
     response_mime_type: str | None = Field(
         default=None, description="响应MIME类型（Gemini专用）"
     )
-    """响应MIME类型（Gemini专用）"""
     response_schema: dict[str, Any] | None = Field(
         default=None, description="JSON响应模式"
     )
-    """JSON响应模式"""
+    thinking_budget: float | None = Field(
-    response_modalities: list[str] | None = Field(
+        default=None, ge=0.0, le=1.0, description="思考预算"
-        default=None, description="响应模态类型 (TEXT, IMAGE, AUDIO)"
     )
-    """响应模态类型 (TEXT, IMAGE, AUDIO)"""
+    include_thoughts: bool | None = Field(
-    structured_output_strategy: StructuredOutputStrategy | str | None = Field(
+        default=None, description="是否在响应中包含思维过程（Gemini专用）"
-        default=None, description="结构化输出策略 (NATIVE/TOOL_CALL/PROMPT)"
     )
-    """结构化输出策略 (NATIVE/TOOL_CALL/PROMPT)"""
-
-
-class SafetyConfig(BaseModel):
-    """安全设置"""
-
     safety_settings: dict[str, str] | None = Field(default=None, description="安全设置")
-    """安全设置"""
+    response_modalities: list[str] | None = Field(
-
+        default=None, description="响应模态类型"
-
-class ToolConfig(BaseModel):
-    """工具调用控制配置"""
-
-    mode: Literal["AUTO", "ANY", "NONE"] = Field(
-        default="AUTO",
-        description="工具调用模式: AUTO(自动), ANY(强制), NONE(禁用)",
     )
-    """工具调用模式: AUTO(自动), ANY(强制), NONE(禁用)"""
+
-    allowed_function_names: list[str] | None = Field(
+    enable_code_execution: bool | None = Field(
-        default=None,
+        default=None, description="是否启用代码执行"
-        description="当 mode 为 ANY 时，允许调用的函数名称白名单",
+    )
+    enable_grounding: bool | None = Field(
+        default=None, description="是否启用信息来源关联"
     )
-    """当 mode 为 ANY 时，允许调用的函数名称白名单"""
-
-
-class LLMGenerationConfig(BaseModel):
-    """
-    LLM 生成配置
-    采用组件化设计，不再扁平化参数。
-    """
-
-    core: CoreConfig | None = Field(default=None, description="基础生成参数")
-    """基础生成参数"""
-    reasoning: ReasoningConfig | None = Field(default=None, description="推理能力配置")
-    """推理能力配置"""
-    visual: VisualConfig | None = Field(default=None, description="视觉生成配置")
-    """视觉生成配置"""
-    output: OutputConfig | None = Field(default=None, description="输出格式配置")
-    """输出格式配置"""
-    safety: SafetyConfig | None = Field(default=None, description="安全配置")
-    """安全配置"""
-    tool_config: ToolConfig | None = Field(default=None, description="工具调用策略配置")
-    """工具调用策略配置"""
-
     enable_caching: bool | None = Field(default=None, description="是否启用响应缓存")
-    """是否启用响应缓存"""
 
     custom_params: dict[str, Any] | None = Field(default=None, description="自定义参数")
-    """自定义参数"""
 
     validation_policy: dict[str, Any] | None = Field(
         default=None, description="声明式的响应验证策略 (例如: {'require_image': True})"
     )
-    """声明式的响应验证策略 (例如: {'require_image': True})"""
     response_validator: Callable[[LLMResponse], None] | None = Field(
-        default=None,
+        default=None, description="一个高级回调函数，用于验证响应，验证失败时应抛出异常"
-        description="一个高级回调函数，用于验证响应，验证失败时应抛出异常",
     )
-    """一个高级回调函数，用于验证响应，验证失败时应抛出异常"""
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
-    @classmethod
-    def builder(cls) -> "GenConfigBuilder":
-        """创建一个新的配置构建器"""
-        return GenConfigBuilder()
-
     def to_dict(self) -> dict[str, Any]:
-        """
+        """转换为字典，排除None值"""
-        转换为字典，排除None值。
-        注意：这会返回嵌套结构的字典。适配器需要处理这种嵌套。
-        """
-        return model_dump(self, exclude_none=True)
 
-    def merge_with(self, other: "LLMGenerationConfig | None") -> "LLMGenerationConfig":
+        model_data = model_dump(self, exclude_none=True)
-        """
-        与另一个配置对象进行深度合并。
-        other 中的非 None 字段会覆盖当前配置中的对应字段。
-        返回一个新的配置对象，原对象不变。
-        """
-        if not other:
-            return model_copy(self, deep=True)
 
-        new_config = model_copy(self, deep=True)
+        result = {}
+        for key, value in model_data.items():
+            if key == "custom_params" and isinstance(value, dict):
+                result.update(value)
+            else:
+                result[key] = value
 
-        def _merge_component(base_comp, override_comp, comp_cls):
+        return result
-            if override_comp is None:
-                return base_comp
-            if base_comp is None:
-                return override_comp
-            updates = model_dump(override_comp, exclude_none=True)
-            return model_copy(base_comp, update=updates)
 
-        new_config.core = _merge_component(new_config.core, other.core, CoreConfig)
+    def merge_with_base_config(
-        new_config.reasoning = _merge_component(
-            new_config.reasoning, other.reasoning, ReasoningConfig
-        )
-        new_config.visual = _merge_component(
-            new_config.visual, other.visual, VisualConfig
-        )
-        new_config.output = _merge_component(
-            new_config.output, other.output, OutputConfig
-        )
-        new_config.safety = _merge_component(
-            new_config.safety, other.safety, SafetyConfig
-        )
-        new_config.tool_config = _merge_component(
-            new_config.tool_config, other.tool_config, ToolConfig
-        )
-
-        if other.enable_caching is not None:
-            new_config.enable_caching = other.enable_caching
-
-        if other.custom_params:
-            if new_config.custom_params is None:
-                new_config.custom_params = {}
-            new_config.custom_params.update(other.custom_params)
-
-        if other.validation_policy:
-            if new_config.validation_policy is None:
-                new_config.validation_policy = {}
-            new_config.validation_policy.update(other.validation_policy)
-
-        if other.response_validator:
-            new_config.response_validator = other.response_validator
-
-        return new_config
-
-
-class LLMEmbeddingConfig(BaseModel):
-    """Embedding 专用配置"""
-
-    task_type: str | None = Field(default=None, description="任务类型 (Gemini/Jina)")
-    """任务类型 (Gemini/Jina)"""
-    output_dimensionality: int | None = Field(
-        default=None, description="输出维度/压缩维度 (Gemini/Jina/OpenAI)"
-    )
-    """输出维度/压缩维度 (Gemini/Jina/OpenAI)"""
-    title: str | None = Field(
-        default=None, description="仅用于 Gemini RETRIEVAL_DOCUMENT 任务的标题"
-    )
-    """仅用于 Gemini RETRIEVAL_DOCUMENT 任务的标题"""
-    encoding_format: str | None = Field(
-        default="float", description="编码格式 (float/base64)"
-    )
-    """编码格式 (float/base64)"""
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-
-class GenConfigBuilder:
-    """
-    LLM 生成配置的语义化构建器。
-    设计原则：高频业务场景优先，低频参数命名空间化。
-    """
-
-    def __init__(self):
-        self._config = LLMGenerationConfig()
-
-    def _ensure_core(self) -> CoreConfig:
-        if self._config.core is None:
-            self._config.core = CoreConfig()
-        return self._config.core
-
-    def _ensure_output(self) -> OutputConfig:
-        if self._config.output is None:
-            self._config.output = OutputConfig()
-        return self._config.output
-
-    def _ensure_reasoning(self) -> ReasoningConfig:
-        if self._config.reasoning is None:
-            self._config.reasoning = ReasoningConfig()
-        return self._config.reasoning
-
-    def as_json(self, schema: dict[str, Any] | None = None) -> Self:
-        """
-        [高频] 强制模型输出 JSON 格式。
-        """
-        out = self._ensure_output()
-        out.response_format = ResponseFormat.JSON
-        if schema:
-            out.response_schema = schema
-        return self
-
-    def enable_thinking(
-        self, budget_tokens: int = -1, show_thoughts: bool = False
-    ) -> Self:
-        """
-        [高频] 启用模型的思考/推理能力 (如 Gemini 2.0 Flash Thinking, DeepSeek R1)。
-        """
-        reasoning = self._ensure_reasoning()
-        reasoning.budget_tokens = budget_tokens
-        reasoning.show_thoughts = show_thoughts
-        return self
-
-    def config_core(
         self,
-        temperature: float | None = None,
+        base_temperature: float | None = None,
-        max_tokens: int | None = None,
+        base_max_tokens: int | None = None,
-        top_p: float | None = None,
+    ) -> dict[str, Any]:
-        top_k: int | None = None,
+        """与基础配置合并，覆盖参数优先"""
-        stop: list[str] | str | None = None,
+        merged = {}
-        frequency_penalty: float | None = None,
-        presence_penalty: float | None = None,
-    ) -> Self:
-        """
-        [低频] 配置核心生成参数。
-        """
-        core = self._ensure_core()
-        if temperature is not None:
-            core.temperature = temperature
-        if max_tokens is not None:
-            core.max_tokens = max_tokens
-        if top_p is not None:
-            core.top_p = top_p
-        if top_k is not None:
-            core.top_k = top_k
-        if stop is not None:
-            core.stop = stop
-        if frequency_penalty is not None:
-            core.frequency_penalty = frequency_penalty
-        if presence_penalty is not None:
-            core.presence_penalty = presence_penalty
-        return self
 
-    def config_safety(self, settings: dict[str, str]) -> Self:
+        if base_temperature is not None:
-        """
+            merged["temperature"] = base_temperature
-        [低频] 配置安全过滤设置。
+        if base_max_tokens is not None:
-        """
+            merged["max_tokens"] = base_max_tokens
-        if self._config.safety is None:
-            self._config.safety = SafetyConfig()
-        self._config.safety.safety_settings = settings
-        return self
 
-    def config_visual(
+        override_dict = self.to_dict()
-        self,
+        merged.update(override_dict)
-        aspect_ratio: ImageAspectRatio | str | None = None,
-        resolution: ImageResolution | str | None = None,
-    ) -> Self:
-        """
-        [低频] 配置视觉生成参数 (DALL-E 3 / Gemini Imagen)。
-        """
-        if self._config.visual is None:
-            self._config.visual = VisualConfig()
-        if aspect_ratio:
-            self._config.visual.aspect_ratio = aspect_ratio
-        if resolution:
-            self._config.visual.resolution = resolution
-        return self
 
-    def set_custom_param(self, key: str, value: Any) -> Self:
+        return merged
-        """设置特定于厂商的自定义参数"""
-        if self._config.custom_params is None:
-            self._config.custom_params = {}
-        self._config.custom_params[key] = value
-        return self
 
-    def build(self) -> LLMGenerationConfig:
+
-        """构建最终的配置对象"""
+class LLMGenerationConfig(ModelConfigOverride):
-        return self._config
+    """LLM 生成配置，继承模型配置覆盖参数"""
+
+    def to_api_params(self, api_type: str, model_name: str) -> dict[str, Any]:
+        """转换为API参数，支持不同API类型的参数名映射"""
+        _ = model_name
+        params = {}
+
+        if self.temperature is not None:
+            params["temperature"] = self.temperature
+
+        if self.max_tokens is not None:
+            if api_type == "gemini":
+                params["maxOutputTokens"] = self.max_tokens
+            else:
+                params["max_tokens"] = self.max_tokens
+
+        if api_type == "gemini":
+            if self.top_k is not None:
+                params["topK"] = self.top_k
+            if self.top_p is not None:
+                params["topP"] = self.top_p
+        else:
+            if self.top_k is not None:
+                params["top_k"] = self.top_k
+            if self.top_p is not None:
+                params["top_p"] = self.top_p
+
+        if api_type in ["openai", "deepseek", "zhipu", "general_openai_compat"]:
+            if self.frequency_penalty is not None:
+                params["frequency_penalty"] = self.frequency_penalty
+            if self.presence_penalty is not None:
+                params["presence_penalty"] = self.presence_penalty
+
+            if self.repetition_penalty is not None:
+                if api_type == "openai":
+                    logger.warning("OpenAI官方API不支持repetition_penalty参数，已忽略")
+                else:
+                    params["repetition_penalty"] = self.repetition_penalty
+
+        if self.response_format is not None:
+            if isinstance(self.response_format, dict):
+                if api_type in ["openai", "zhipu", "deepseek", "general_openai_compat"]:
+                    params["response_format"] = self.response_format
+                    logger.debug(
+                        f"为 {api_type} 使用自定义 response_format: "
+                        f"{self.response_format}"
+                    )
+            elif self.response_format == ResponseFormat.JSON:
+                if api_type in ["openai", "zhipu", "deepseek", "general_openai_compat"]:
+                    params["response_format"] = {"type": "json_object"}
+                    logger.debug(f"为 {api_type} 启用 JSON 对象输出模式")
+                elif api_type == "gemini":
+                    params["responseMimeType"] = "application/json"
+                    if self.response_schema:
+                        params["responseSchema"] = self.response_schema
+                    logger.debug(f"为 {api_type} 启用 JSON MIME 类型输出模式")
+
+        if self.custom_params:
+            custom_mapped = apply_api_specific_mappings(self.custom_params, api_type)
+            params.update(custom_mapped)
+
+        if api_type == "gemini":
+            if (
+                self.response_format != ResponseFormat.JSON
+                and self.response_mime_type is not None
+            ):
+                params["responseMimeType"] = self.response_mime_type
+                logger.debug(
+                    f"使用显式设置的 responseMimeType: {self.response_mime_type}"
+                )
+
+            if self.response_schema is not None and "responseSchema" not in params:
+                params["responseSchema"] = self.response_schema
+
+            if self.thinking_budget is not None or self.include_thoughts is not None:
+                thinking_config = params.setdefault("thinkingConfig", {})
+
+                if self.thinking_budget is not None:
+                    max_budget = 24576
+                    budget_value = int(self.thinking_budget * max_budget)
+                    thinking_config["thinkingBudget"] = budget_value
+                    logger.debug(
+                        f"已将 thinking_budget (float: {self.thinking_budget}) "
+                        f"转换为 Gemini API 的整数格式: {budget_value}"
+                    )
+
+                if self.include_thoughts is not None:
+                    thinking_config["includeThoughts"] = self.include_thoughts
+                    logger.debug(f"已设置 includeThoughts: {self.include_thoughts}")
+
+            if self.safety_settings is not None:
+                params["safetySettings"] = self.safety_settings
+            if self.response_modalities is not None:
+                params["responseModalities"] = self.response_modalities
+
+        logger.debug(f"为{api_type}转换配置参数: {len(params)}个参数")
+        return params
 
 
 def validate_override_params(
@@ -403,12 +215,12 @@ def validate_override_params(
     if override_config is None:
         return LLMGenerationConfig()
 
-    if isinstance(override_config, LLMGenerationConfig):
-        return override_config
-
     if isinstance(override_config, dict):
         try:
-            return model_validate(LLMGenerationConfig, override_config)
+            filtered_config = {
+                k: v for k, v in override_config.items() if v is not None
+            }
+            return LLMGenerationConfig(**filtered_config)
         except Exception as e:
             logger.warning(f"覆盖配置参数验证失败: {e}")
             raise LLMException(
@@ -417,107 +229,56 @@ def validate_override_params(
                 cause=e,
             )
 
-    raise LLMException(
+    return override_config
-        f"不支持的配置类型: {type(override_config)}",
-        code=LLMErrorCode.CONFIGURATION_ERROR,
-    )
 
 
-class CommonOverrides:
+def apply_api_specific_mappings(
-    """常用的配置覆盖预设"""
+    params: dict[str, Any], api_type: str
+) -> dict[str, Any]:
+    """应用API特定的参数映射"""
+    mapped_params = params.copy()
 
-    @staticmethod
+    if api_type == "gemini":
-    def gemini_json() -> LLMGenerationConfig:
+        if "max_tokens" in mapped_params:
-        """Gemini JSON模式：强制JSON输出"""
+            mapped_params["maxOutputTokens"] = mapped_params.pop("max_tokens")
-        return LLMGenerationConfig(
+        if "top_k" in mapped_params:
-            core=CoreConfig(),
+            mapped_params["topK"] = mapped_params.pop("top_k")
-            output=OutputConfig(
+        if "top_p" in mapped_params:
-                response_format=ResponseFormat.JSON,
+            mapped_params["topP"] = mapped_params.pop("top_p")
-                response_mime_type="application/json",
-            ),
-        )
 
-    @staticmethod
+        unsupported = ["frequency_penalty", "presence_penalty", "repetition_penalty"]
-    def gemini_2_5_thinking(tokens: int = -1) -> LLMGenerationConfig:
+        for param in unsupported:
-        """Gemini 2.5 思考模式：默认 -1 (动态思考)，0 为禁用，>=1024 为固定预算"""
+            if param in mapped_params:
-        return LLMGenerationConfig(
+                logger.warning(f"Gemini 原生API不支持参数 '{param}'，已忽略")
-            core=CoreConfig(temperature=1.0),
+                mapped_params.pop(param)
-            reasoning=ReasoningConfig(budget_tokens=tokens, show_thoughts=True),
-        )
 
-    @staticmethod
+    elif api_type in ["openai", "deepseek", "zhipu", "general_openai_compat"]:
-    def gemini_3_thinking(level: str = "HIGH") -> LLMGenerationConfig:
+        if "repetition_penalty" in mapped_params and api_type == "openai":
-        """Gemini 3 深度思考模式：使用思考等级"""
+            logger.warning("OpenAI官方API不支持repetition_penalty参数，已忽略")
-        try:
+            mapped_params.pop("repetition_penalty")
-            effort = ReasoningEffort(level.upper())
-        except ValueError:
-            effort = ReasoningEffort.HIGH
 
-        return LLMGenerationConfig(
+        if "stop" in mapped_params:
-            core=CoreConfig(),
+            stop_value = mapped_params["stop"]
-            reasoning=ReasoningConfig(effort=effort, show_thoughts=True),
+            if isinstance(stop_value, str):
-        )
+                mapped_params["stop"] = [stop_value]
 
-    @staticmethod
+    return mapped_params
-    def gemini_structured(schema: dict[str, Any]) -> LLMGenerationConfig:
-        """Gemini 结构化输出：自定义JSON模式"""
-        return LLMGenerationConfig(
-            core=CoreConfig(),
-            output=OutputConfig(
-                response_mime_type="application/json", response_schema=schema
-            ),
-        )
 
-    @staticmethod
-    def gemini_safe() -> LLMGenerationConfig:
-        """Gemini 安全模式：使用配置的安全设置"""
-        threshold = get_gemini_safety_threshold()
-        return LLMGenerationConfig(
-            core=CoreConfig(),
-            safety=SafetyConfig(
-                safety_settings={
-                    "HARM_CATEGORY_HARASSMENT": threshold,
-                    "HARM_CATEGORY_HATE_SPEECH": threshold,
-                    "HARM_CATEGORY_SEXUALLY_EXPLICIT": threshold,
-                    "HARM_CATEGORY_DANGEROUS_CONTENT": threshold,
-                }
-            ),
-        )
 
-    @staticmethod
+def create_generation_config_from_kwargs(**kwargs) -> LLMGenerationConfig:
-    def gemini_code_execution() -> LLMGenerationConfig:
+    """从关键字参数创建生成配置"""
-        """Gemini 代码执行模式：启用代码执行功能"""
+    model_fields = getattr(LLMGenerationConfig, "model_fields", {})
-        return LLMGenerationConfig(
+    known_fields = set(model_fields.keys())
-            core=CoreConfig(),
+    known_params = {}
-            custom_params={"code_execution_timeout": 30},
+    custom_params = {}
-        )
 
-    @staticmethod
+    for key, value in kwargs.items():
-    def gemini_grounding() -> LLMGenerationConfig:
+        if key in known_fields:
-        """Gemini 信息来源关联模式：启用Google搜索"""
+            known_params[key] = value
-        return LLMGenerationConfig(
+        else:
-            core=CoreConfig(),
+            custom_params[key] = value
-            custom_params={
-                "grounding_config": {"dynamicRetrievalConfig": {"mode": "MODE_DYNAMIC"}}
-            },
-        )
 
-    @staticmethod
+    if custom_params:
-    def gemini_nano_banana(aspect_ratio: str = "16:9") -> LLMGenerationConfig:
+        known_params["custom_params"] = custom_params
-        """Gemini Nano Banana Pro：自定义比例生图"""
-        try:
-            ar = ImageAspectRatio(aspect_ratio)
-        except ValueError:
-            ar = ImageAspectRatio.LANDSCAPE_16_9
 
-        return LLMGenerationConfig(
+    return LLMGenerationConfig(**known_params)
-            core=CoreConfig(),
-            visual=VisualConfig(aspect_ratio=ar),
-        )
-
-    @staticmethod
-    def gemini_high_res() -> LLMGenerationConfig:
-        """Gemini 3: 强制使用高解析度处理输入媒体"""
-        return LLMGenerationConfig(
-            visual=VisualConfig(media_resolution="HIGH", resolution=ImageResolution.HD)
-        )

zhenxun/services/llm/config/presets.py

@@ -0,0 +1,172 @@
+"""
+LLM 预设配置
+
+提供常用的配置预设，特别是针对 Gemini 的高级功能。
+"""
+
+from typing import Any
+
+from .generation import LLMGenerationConfig
+
+
+class CommonOverrides:
+    """常用的配置覆盖预设"""
+
+    @staticmethod
+    def creative() -> LLMGenerationConfig:
+        """创意模式：高温度，鼓励创新"""
+        return LLMGenerationConfig(temperature=0.9, top_p=0.95, frequency_penalty=0.1)
+
+    @staticmethod
+    def precise() -> LLMGenerationConfig:
+        """精确模式：低温度，确定性输出"""
+        return LLMGenerationConfig(temperature=0.1, top_p=0.9, frequency_penalty=0.0)
+
+    @staticmethod
+    def balanced() -> LLMGenerationConfig:
+        """平衡模式：中等温度"""
+        return LLMGenerationConfig(temperature=0.5, top_p=0.9, frequency_penalty=0.0)
+
+    @staticmethod
+    def concise(max_tokens: int = 100) -> LLMGenerationConfig:
+        """简洁模式：限制输出长度"""
+        return LLMGenerationConfig(
+            temperature=0.3,
+            max_tokens=max_tokens,
+            stop=["\n\n", "。", "！", "？"],
+        )
+
+    @staticmethod
+    def detailed(max_tokens: int = 2000) -> LLMGenerationConfig:
+        """详细模式：鼓励详细输出"""
+        return LLMGenerationConfig(
+            temperature=0.7, max_tokens=max_tokens, frequency_penalty=-0.1
+        )
+
+    @staticmethod
+    def gemini_json() -> LLMGenerationConfig:
+        """Gemini JSON模式：强制JSON输出"""
+        return LLMGenerationConfig(
+            temperature=0.3, response_mime_type="application/json"
+        )
+
+    @staticmethod
+    def gemini_thinking(budget: float = 0.8) -> LLMGenerationConfig:
+        """Gemini 思考模式：使用思考预算"""
+        return LLMGenerationConfig(temperature=0.7, thinking_budget=budget)
+
+    @staticmethod
+    def gemini_creative() -> LLMGenerationConfig:
+        """Gemini 创意模式：高温度创意输出"""
+        return LLMGenerationConfig(temperature=0.9, top_p=0.95)
+
+    @staticmethod
+    def gemini_structured(schema: dict[str, Any]) -> LLMGenerationConfig:
+        """Gemini 结构化输出：自定义JSON模式"""
+        return LLMGenerationConfig(
+            temperature=0.3,
+            response_mime_type="application/json",
+            response_schema=schema,
+        )
+
+    @staticmethod
+    def gemini_safe() -> LLMGenerationConfig:
+        """Gemini 安全模式：使用配置的安全设置"""
+        from .providers import get_gemini_safety_threshold
+
+        threshold = get_gemini_safety_threshold()
+        return LLMGenerationConfig(
+            temperature=0.5,
+            safety_settings={
+                "HARM_CATEGORY_HARASSMENT": threshold,
+                "HARM_CATEGORY_HATE_SPEECH": threshold,
+                "HARM_CATEGORY_SEXUALLY_EXPLICIT": threshold,
+                "HARM_CATEGORY_DANGEROUS_CONTENT": threshold,
+            },
+        )
+
+    @staticmethod
+    def gemini_multimodal() -> LLMGenerationConfig:
+        """Gemini 多模态模式：优化多模态处理"""
+        return LLMGenerationConfig(temperature=0.6, max_tokens=2048, top_p=0.8)
+
+    @staticmethod
+    def gemini_code_execution() -> LLMGenerationConfig:
+        """Gemini 代码执行模式：启用代码执行功能"""
+        return LLMGenerationConfig(
+            temperature=0.3,
+            max_tokens=4096,
+            enable_code_execution=True,
+            custom_params={"code_execution_timeout": 30},
+        )
+
+    @staticmethod
+    def gemini_grounding() -> LLMGenerationConfig:
+        """Gemini 信息来源关联模式：启用Google搜索"""
+        return LLMGenerationConfig(
+            temperature=0.5,
+            max_tokens=4096,
+            enable_grounding=True,
+            custom_params={
+                "grounding_config": {"dynamicRetrievalConfig": {"mode": "MODE_DYNAMIC"}}
+            },
+        )
+
+    @staticmethod
+    def gemini_cached() -> LLMGenerationConfig:
+        """Gemini 缓存模式：启用响应缓存"""
+        return LLMGenerationConfig(
+            temperature=0.3,
+            max_tokens=2048,
+            enable_caching=True,
+        )
+
+    @staticmethod
+    def gemini_advanced() -> LLMGenerationConfig:
+        """Gemini 高级模式：启用所有高级功能"""
+        return LLMGenerationConfig(
+            temperature=0.5,
+            max_tokens=4096,
+            enable_code_execution=True,
+            enable_grounding=True,
+            enable_caching=True,
+            custom_params={
+                "code_execution_timeout": 30,
+                "grounding_config": {
+                    "dynamicRetrievalConfig": {"mode": "MODE_DYNAMIC"}
+                },
+            },
+        )
+
+    @staticmethod
+    def gemini_research() -> LLMGenerationConfig:
+        """Gemini 研究模式：思考+搜索+结构化输出"""
+        return LLMGenerationConfig(
+            temperature=0.6,
+            max_tokens=4096,
+            thinking_budget=0.8,
+            enable_grounding=True,
+            response_mime_type="application/json",
+            custom_params={
+                "grounding_config": {"dynamicRetrievalConfig": {"mode": "MODE_DYNAMIC"}}
+            },
+        )
+
+    @staticmethod
+    def gemini_analysis() -> LLMGenerationConfig:
+        """Gemini 分析模式：深度思考+详细输出"""
+        return LLMGenerationConfig(
+            temperature=0.4,
+            max_tokens=6000,
+            thinking_budget=0.9,
+            top_p=0.8,
+        )
+
+    @staticmethod
+    def gemini_fast_response() -> LLMGenerationConfig:
+        """Gemini 快速响应模式：低延迟+简洁输出"""
+        return LLMGenerationConfig(
+            temperature=0.3,
+            max_tokens=512,
+            top_p=0.8,
+        )

zhenxun/services/llm/config/providers.py

@@ -13,7 +13,6 @@ from zhenxun.configs.config import Config
 from zhenxun.configs.utils import parse_as
 from zhenxun.services.log import logger
 from zhenxun.utils.manager.priority_manager import PriorityLifecycle
-from zhenxun.utils.pydantic_compat import model_dump
 
 from ..core import key_store
 from ..tools import tool_provider_manager
@@ -23,39 +22,6 @@ AI_CONFIG_GROUP = "AI"
 PROVIDERS_CONFIG_KEY = "PROVIDERS"
 
 
-class DebugLogOptions(BaseModel):
-    """调试日志细粒度控制"""
-
-    show_tools: bool = Field(
-        default=True, description="是否在日志中显示工具定义(JSON Schema)"
-    )
-    show_schema: bool = Field(
-        default=True, description="是否在日志中显示结构化输出Schema(response_format)"
-    )
-    show_safety: bool = Field(
-        default=True, description="是否在日志中显示安全设置(safetySettings)"
-    )
-
-    def __bool__(self) -> bool:
-        """支持 bool(debug_options) 的语法，方便兼容旧逻辑。"""
-        return self.show_tools or self.show_schema or self.show_safety
-
-
-class ClientSettings(BaseModel):
-    """LLM 客户端通用设置"""
-
-    timeout: int = Field(default=300, description="API请求超时时间（秒）")
-    max_retries: int = Field(default=3, description="请求失败时的最大重试次数")
-    retry_delay: int = Field(default=2, description="请求重试的基础延迟时间（秒）")
-    structured_retries: int = Field(
-        default=2, description="结构化生成校验失败时的最大重试次数 (IVR)"
-    )
-    proxy: str | None = Field(
-        default=None,
-        description="网络代理，例如 http://127.0.0.1:7890",
-    )
-
-
 class LLMConfig(BaseModel):
     """LLM 服务配置类"""
 
@@ -63,16 +29,20 @@ class LLMConfig(BaseModel):
         default=None,
         description="LLM服务全局默认使用的模型名称 (格式: ProviderName/ModelName)",
     )
-    client_settings: ClientSettings = Field(
+    proxy: str | None = Field(
-        default_factory=ClientSettings, description="客户端连接与重试配置"
+        default=None,
+        description="LLM服务请求使用的网络代理，例如 http://127.0.0.1:7890",
+    )
+    timeout: int = Field(default=180, description="LLM服务API请求超时时间（秒）")
+    max_retries_llm: int = Field(
+        default=3, description="LLM服务请求失败时的最大重试次数"
+    )
+    retry_delay_llm: int = Field(
+        default=2, description="LLM服务请求重试的基础延迟时间（秒）"
     )
     providers: list[ProviderConfig] = Field(
         default_factory=list, description="配置多个 AI 服务提供商及其模型信息"
     )
-    debug_log: DebugLogOptions | bool = Field(
-        default_factory=DebugLogOptions,
-        description="LLM请求日志详情开关。支持 bool (全开/全关) 或 dict (细粒度控制)。",
-    )
 
     def get_provider_by_name(self, name: str) -> ProviderConfig | None:
         """根据名称获取提供商配置
@@ -256,29 +226,36 @@ def register_llm_configs():
     )
     Config.add_plugin_config(
         AI_CONFIG_GROUP,
-        "client_settings",
+        "proxy",
-        model_dump(llm_config.client_settings),
+        llm_config.proxy,
-        help=(
+        help="LLM服务请求使用的网络代理，例如 http://127.0.0.1:7890",
-            "LLM客户端高级设置。\n"
+        type=str,
-            "包含: timeout(超时秒数), max_retries(重试次数), "
-            "retry_delay(重试延迟), structured_retries(结构化生成重试), proxy(代理)"
-        ),
-        type=dict,
     )
     Config.add_plugin_config(
         AI_CONFIG_GROUP,
-        "debug_log",
+        "timeout",
-        {"show_tools": True, "show_schema": True, "show_safety": True},
+        llm_config.timeout,
-        help=(
+        help="LLM服务API请求超时时间（秒）",
-            "LLM日志详情开关。示例: {'show_tools': True, 'show_schema': False, "
+        type=int,
-            "'show_safety': False}"
+    )
-        ),
+    Config.add_plugin_config(
-        type=dict,
+        AI_CONFIG_GROUP,
+        "max_retries_llm",
+        llm_config.max_retries_llm,
+        help="LLM服务请求失败时的最大重试次数",
+        type=int,
+    )
+    Config.add_plugin_config(
+        AI_CONFIG_GROUP,
+        "retry_delay_llm",
+        llm_config.retry_delay_llm,
+        help="LLM服务请求重试的基础延迟时间（秒）",
+        type=int,
     )
     Config.add_plugin_config(
         AI_CONFIG_GROUP,
         "gemini_safety_threshold",
-        "BLOCK_NONE",
+        "BLOCK_MEDIUM_AND_ABOVE",
         help=(
             "Gemini 安全过滤阈值 "
             "(BLOCK_LOW_AND_ABOVE: 阻止低级别及以上, "
@@ -293,20 +270,7 @@ def register_llm_configs():
         AI_CONFIG_GROUP,
         PROVIDERS_CONFIG_KEY,
         get_default_providers(),
-        help=(
+        help="配置多个 AI 服务提供商及其模型信息",
-            "配置多个 AI 服务提供商及其模型信息。\n"
-            "注意：可以在特定模型配置下添加 'api_type' 以覆盖提供商的全局设置。\n"
-            "支持的 api_type 包括:\n"
-            "- 'openai': 标准 OpenAI 格式 (DeepSeek, SiliconFlow, Moonshot 等)\n"
-            "- 'gemini': Google Gemini API\n"
-            "- 'zhipu': 智谱 AI (GLM)\n"
-            "- 'ark': 字节跳动火山引擎 (Doubao)\n"
-            "- 'openrouter': OpenRouter 聚合平台\n"
-            "- 'openai_image': OpenAI 兼容的图像生成接口 (DALL-E)\n"
-            "- 'openai_responses': 支持新版 responses 格式的 OpenAI 兼容接口\n"
-            "- 'smart': 智能路由模式 (主要用于第三方中转场景，自动根据模型名"
-            "分发请求到 openai 或 gemini)"
-        ),
         default_value=[],
         type=list[ProviderConfig],
     )
@@ -314,21 +278,15 @@ def register_llm_configs():
 
 @lru_cache(maxsize=1)
 def get_llm_config() -> LLMConfig:
-    """获取 LLM 配置实例"""
+    """获取 LLM 配置实例，不再加载 MCP 工具配置"""
     ai_config = get_ai_config()
 
-    raw_debug = ai_config.get("debug_log", False)
-    if isinstance(raw_debug, bool):
-        debug_log_val = DebugLogOptions(
-            show_tools=raw_debug, show_schema=raw_debug, show_safety=raw_debug
-        )
-    else:
-        debug_log_val = raw_debug
-
     config_data = {
         "default_model_name": ai_config.get("default_model_name"),
-        "client_settings": ai_config.get("client_settings", {}),
+        "proxy": ai_config.get("proxy"),
-        "debug_log": debug_log_val,
+        "timeout": ai_config.get("timeout", 180),
+        "max_retries_llm": ai_config.get("max_retries_llm", 3),
+        "retry_delay_llm": ai_config.get("retry_delay_llm", 2),
         PROVIDERS_CONFIG_KEY: ai_config.get(PROVIDERS_CONFIG_KEY, []),
     }
 
@@ -356,14 +314,14 @@ def validate_llm_config() -> tuple[bool, list[str]]:
     try:
         llm_config = get_llm_config()
 
-        if llm_config.client_settings.timeout <= 0:
+        if llm_config.timeout <= 0:
             errors.append("timeout 必须大于 0")
 
-        if llm_config.client_settings.max_retries < 0:
+        if llm_config.max_retries_llm < 0:
-            errors.append("max_retries 不能小于 0")
+            errors.append("max_retries_llm 不能小于 0")
 
-        if llm_config.client_settings.retry_delay <= 0:
+        if llm_config.retry_delay_llm <= 0:
-            errors.append("retry_delay 必须大于 0")
+            errors.append("retry_delay_llm 必须大于 0")
 
         if not llm_config.providers:
             errors.append("至少需要配置一个 AI 服务提供商")

zhenxun/services/llm/core.py

@@ -254,7 +254,7 @@ class KeyStats:
         if total_calls == 0:
             return KeyStatus.UNUSED
 
-        if self.success_rate < 70:
+        if self.success_rate < 80:
             return KeyStatus.ERROR
 
         if total_calls >= 5 and self.avg_latency > 15000:
@@ -292,6 +292,96 @@ class RetryConfig:
         self.key_rotation = key_rotation
 
 
+async def with_smart_retry(
+    func,
+    *args,
+    retry_config: RetryConfig | None = None,
+    key_store: "KeyStatusStore | None" = None,
+    provider_name: str | None = None,
+    **kwargs: Any,
+) -> Any:
+    """
+    智能重试装饰器 - 支持Key轮询和错误分类
+
+    参数:
+        func: 要重试的异步函数。
+        *args: 传递给函数的位置参数。
+        retry_config: 重试配置。
+        key_store: API密钥状态存储。
+        provider_name: 提供商名称。
+        **kwargs: 传递给函数的关键字参数。
+
+    返回:
+        Any: 函数执行结果。
+    """
+    config = retry_config or RetryConfig()
+    last_exception: Exception | None = None
+    failed_keys: set[str] = set()
+
+    model_instance = next((arg for arg in args if hasattr(arg, "api_keys")), None)
+    all_provider_keys = model_instance.api_keys if model_instance else []
+
+    for attempt in range(config.max_retries + 1):
+        try:
+            if config.key_rotation and "failed_keys" in func.__code__.co_varnames:
+                kwargs["failed_keys"] = failed_keys
+
+            start_time = time.monotonic()
+            result = await func(*args, **kwargs)
+            latency = (time.monotonic() - start_time) * 1000
+
+            if key_store and isinstance(result, tuple) and len(result) == 2:
+                _, api_key_used = result
+                if api_key_used:
+                    await key_store.record_success(api_key_used, latency)
+                return result
+            else:
+                return result
+
+        except LLMException as e:
+            last_exception = e
+            api_key_in_use = e.details.get("api_key")
+
+            if api_key_in_use:
+                failed_keys.add(api_key_in_use)
+                if key_store and provider_name and len(all_provider_keys) > 1:
+                    status_code = e.details.get("status_code")
+                    error_message = f"({e.code.name}) {e.message}"
+                    await key_store.record_failure(
+                        api_key_in_use, status_code, error_message
+                    )
+
+            should_retry = _should_retry_llm_error(e, attempt, config.max_retries)
+            if not should_retry:
+                logger.error(f"不可重试的错误，停止重试: {e}")
+                raise
+
+            if attempt < config.max_retries:
+                wait_time = config.retry_delay
+                if config.exponential_backoff:
+                    wait_time *= 2**attempt
+                logger.warning(
+                    f"请求失败，{wait_time:.2f}秒后重试 (第{attempt + 1}次): {e}"
+                )
+                await asyncio.sleep(wait_time)
+            else:
+                logger.error(f"重试{config.max_retries}次后仍然失败: {e}")
+
+        except Exception as e:
+            last_exception = e
+            logger.error(f"非LLM异常，停止重试: {e}")
+            raise LLMException(
+                f"操作失败: {e}",
+                code=LLMErrorCode.GENERATION_FAILED,
+                cause=e,
+            )
+
+    if last_exception:
+        raise last_exception
+    else:
+        raise RuntimeError("重试函数未能正常执行且未捕获到异常")
+
+
 def _should_retry_llm_error(
     error: LLMException, attempt: int, max_retries: int
 ) -> bool:
@@ -300,9 +390,7 @@ def _should_retry_llm_error(
         LLMErrorCode.MODEL_NOT_FOUND,
         LLMErrorCode.CONTEXT_LENGTH_EXCEEDED,
         LLMErrorCode.USER_LOCATION_NOT_SUPPORTED,
-        LLMErrorCode.INVALID_PARAMETER,
         LLMErrorCode.CONFIGURATION_ERROR,
-        LLMErrorCode.API_KEY_INVALID,
     }
 
     if error.code in non_retryable_errors:
@@ -316,12 +404,15 @@ def _should_retry_llm_error(
         LLMErrorCode.RESPONSE_PARSE_ERROR,
         LLMErrorCode.GENERATION_FAILED,
         LLMErrorCode.CONTENT_FILTERED,
+        LLMErrorCode.API_KEY_INVALID,
         LLMErrorCode.API_QUOTA_EXCEEDED,
     }
 
     if error.code in retryable_errors:
         if error.code == LLMErrorCode.API_QUOTA_EXCEEDED:
             return attempt < min(2, max_retries)
+        elif error.code == LLMErrorCode.CONTENT_FILTERED:
+            return attempt < min(1, max_retries)
         return True
 
     return False
@@ -467,68 +558,14 @@ class KeyStatusStore:
         now = time.time()
         cooldown_duration = 300
 
-        location_not_supported = error_message and (
+        if status_code in [401, 403, 404]:
-            "USER_LOCATION_NOT_SUPPORTED" in error_message
-            or "User location is not supported" in error_message
-        )
-        if location_not_supported:
-            logger.warning(
-                f"API Key {key_id} 请求失败，原因是地区不支持 (Gemini)。"
-                " 这通常是代理节点问题，Key 本身可能是正常的。跳过冷却。"
-            )
-            async with self._lock:
-                stats = self._key_stats.setdefault(api_key, KeyStats())
-                stats.failure_count += 1
-                stats.last_error_info = error_message[:256]
-                await self._save_to_file_internal()
-            return
-
-        if error_message and (
-            "API_QUOTA_EXCEEDED" in error_message
-            or "insufficient_quota" in error_message.lower()
-        ):
-            cooldown_duration = 3600
-            logger.warning(f"API Key {key_id} 额度耗尽，冷却 1 小时。")
-
-        is_key_invalid = status_code == 401 or (
-            status_code == 400
-            and error_message
-            and (
-                "API_KEY_INVALID" in error_message
-                or "API key not valid" in error_message
-            )
-        )
-
-        if is_key_invalid:
             cooldown_duration = 31536000
             log_level = "error"
             log_message = f"API密钥认证/权限/路径错误，将永久禁用: {key_id}"
-        elif status_code == 403:
-            cooldown_duration = 3600
-            log_level = "warning"
-            log_message = f"API密钥权限不足或地区不支持(403)，冷却1小时: {key_id}"
-        elif status_code == 404:
-            log_level = "error"
-            log_message = "API请求返回 404 (未找到)，可能是模型名称错误或接口地址"
-            f"错误，不冷却密钥: {key_id}"
-        elif status_code == 422:
-            cooldown_duration = 0
-            log_level = "warning"
-            log_message = f"API请求无法处理(422)，可能是生成故障，不冷却密钥: {key_id}"
         elif status_code == 429:
             cooldown_duration = 60
             log_level = "warning"
             log_message = f"API密钥被限流，冷却60秒: {key_id}"
-        elif error_message and (
-            "ConnectError" in error_message
-            or "NetworkError" in error_message
-            or "Connection refused" in error_message
-            or "RemoteProtocolError" in error_message
-            or "ProxyError" in error_message
-        ):
-            cooldown_duration = 0
-            log_level = "warning"
-            log_message = f"网络连接层异常(代理/DNS)，不冷却密钥: {key_id}"
         else:
             log_level = "warning"
             log_message = f"API密钥遇到临时性错误，冷却{cooldown_duration}秒: {key_id}"

zhenxun/services/llm/executor.py

@@ -0,0 +1,193 @@
+"""
+LLM 轻量级工具执行器
+
+提供驱动 LLM 与本地函数工具之间交互的核心循环。
+"""
+
+import asyncio
+from enum import Enum
+import json
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from zhenxun.services.log import logger
+from zhenxun.utils.decorator.retry import Retry
+from zhenxun.utils.pydantic_compat import model_dump
+
+from .service import LLMModel
+from .types import (
+    LLMErrorCode,
+    LLMException,
+    LLMMessage,
+    ToolExecutable,
+    ToolResult,
+)
+
+
+class ExecutionConfig(BaseModel):
+    """
+    轻量级执行器的配置。
+    """
+
+    max_cycles: int = Field(default=5, description="工具调用循环的最大次数。")
+
+
+class ToolErrorType(str, Enum):
+    """结构化工具错误的类型枚举。"""
+
+    TOOL_NOT_FOUND = "ToolNotFound"
+    INVALID_ARGUMENTS = "InvalidArguments"
+    EXECUTION_ERROR = "ExecutionError"
+    USER_CANCELLATION = "UserCancellation"
+
+
+class ToolErrorResult(BaseModel):
+    """一个结构化的工具执行错误模型，用于返回给 LLM。"""
+
+    error_type: ToolErrorType = Field(..., description="错误的类型。")
+    message: str = Field(..., description="对错误的详细描述。")
+    is_retryable: bool = Field(False, description="指示这个错误是否可能通过重试解决。")
+
+    def model_dump(self, **kwargs):
+        return model_dump(self, **kwargs)
+
+
+def _is_exception_retryable(e: Exception) -> bool:
+    """判断一个异常是否应该触发重试。"""
+    if isinstance(e, LLMException):
+        retryable_codes = {
+            LLMErrorCode.API_REQUEST_FAILED,
+            LLMErrorCode.API_TIMEOUT,
+            LLMErrorCode.API_RATE_LIMITED,
+        }
+        return e.code in retryable_codes
+    return True
+
+
+class LLMToolExecutor:
+    """
+    一个通用的执行器，负责驱动 LLM 与工具之间的多轮交互。
+    """
+
+    def __init__(self, model: LLMModel):
+        self.model = model
+
+    async def run(
+        self,
+        messages: list[LLMMessage],
+        tools: dict[str, ToolExecutable],
+        config: ExecutionConfig | None = None,
+    ) -> list[LLMMessage]:
+        """
+        执行完整的思考-行动循环。
+        """
+        effective_config = config or ExecutionConfig()
+        execution_history = list(messages)
+
+        for i in range(effective_config.max_cycles):
+            response = await self.model.generate_response(
+                execution_history, tools=tools
+            )
+
+            assistant_message = LLMMessage(
+                role="assistant",
+                content=response.text,
+                tool_calls=response.tool_calls,
+            )
+            execution_history.append(assistant_message)
+
+            if not response.tool_calls:
+                logger.info("✅ LLMToolExecutor：模型未请求工具调用，执行结束。")
+                return execution_history
+
+            logger.info(
+                f"🛠️ LLMToolExecutor：模型请求并行调用 {len(response.tool_calls)} 个工具"
+            )
+            tool_results = await self._execute_tools_parallel_safely(
+                response.tool_calls,
+                tools,
+            )
+            execution_history.extend(tool_results)
+
+        raise LLMException(
+            f"超过最大工具调用循环次数 ({effective_config.max_cycles})。",
+            code=LLMErrorCode.GENERATION_FAILED,
+        )
+
+    async def _execute_single_tool_safely(
+        self, tool_call: Any, available_tools: dict[str, ToolExecutable]
+    ) -> tuple[Any, ToolResult]:
+        """安全地执行单个工具调用。"""
+        tool_name = tool_call.function.name
+        arguments = {}
+
+        try:
+            if tool_call.function.arguments:
+                arguments = json.loads(tool_call.function.arguments)
+        except json.JSONDecodeError as e:
+            error_result = ToolErrorResult(
+                error_type=ToolErrorType.INVALID_ARGUMENTS,
+                message=f"参数解析失败: {e}",
+                is_retryable=False,
+            )
+            return tool_call, ToolResult(output=model_dump(error_result))
+
+        try:
+            executable = available_tools.get(tool_name)
+            if not executable:
+                raise LLMException(
+                    f"Tool '{tool_name}' not found.",
+                    code=LLMErrorCode.CONFIGURATION_ERROR,
+                )
+
+            @Retry.simple(
+                stop_max_attempt=2, wait_fixed_seconds=1, return_on_failure=None
+            )
+            async def execute_with_retry():
+                return await executable.execute(**arguments)
+
+            execution_result = await execute_with_retry()
+            if execution_result is None:
+                raise LLMException("工具执行在多次重试后仍然失败。")
+
+            return tool_call, execution_result
+        except Exception as e:
+            error_type = ToolErrorType.EXECUTION_ERROR
+            is_retryable = _is_exception_retryable(e)
+            if (
+                isinstance(e, LLMException)
+                and e.code == LLMErrorCode.CONFIGURATION_ERROR
+            ):
+                error_type = ToolErrorType.TOOL_NOT_FOUND
+                is_retryable = False
+
+            error_result = ToolErrorResult(
+                error_type=error_type, message=str(e), is_retryable=is_retryable
+            )
+            return tool_call, ToolResult(output=model_dump(error_result))
+
+    async def _execute_tools_parallel_safely(
+        self,
+        tool_calls: list[Any],
+        available_tools: dict[str, ToolExecutable],
+    ) -> list[LLMMessage]:
+        """并行执行所有工具调用，并对每个调用的错误进行隔离。"""
+        if not tool_calls:
+            return []
+
+        tasks = [
+            self._execute_single_tool_safely(call, available_tools)
+            for call in tool_calls
+        ]
+        results = await asyncio.gather(*tasks)
+
+        tool_messages = [
+            LLMMessage.tool_response(
+                tool_call_id=original_call.id,
+                function_name=original_call.function.name,
+                result=result.output,
+            )
+            for original_call, result in results
+        ]
+        return tool_messages

zhenxun/services/llm/manager.py

@@ -13,19 +13,15 @@ from zhenxun.services.log import logger
 from zhenxun.utils.pydantic_compat import dump_json_safely
 
 from .config import validate_override_params
-from .config.generation import LLMGenerationConfig
+from .config.providers import AI_CONFIG_GROUP, PROVIDERS_CONFIG_KEY, get_ai_config
-from .config.providers import (
-    AI_CONFIG_GROUP,
-    PROVIDERS_CONFIG_KEY,
-    get_ai_config,
-    get_llm_config,
-)
 from .core import http_client_manager, key_store
 from .service import LLMModel
 from .types import LLMErrorCode, LLMException, ModelDetail, ProviderConfig
 from .types.capabilities import get_model_capabilities
 
 DEFAULT_MODEL_NAME_KEY = "default_model_name"
+PROXY_KEY = "proxy"
+TIMEOUT_KEY = "timeout"
 
 _model_cache: dict[str, tuple[LLMModel, float]] = {}
 _cache_ttl = 3600
@@ -43,8 +39,7 @@ def parse_provider_model_string(name_str: str | None) -> tuple[str | None, str |
 
 
 def _make_cache_key(
-    provider_model_name: str | None,
+    provider_model_name: str | None, override_config: dict | None
-    override_config: dict | LLMGenerationConfig | None,
 ) -> str:
     """生成缓存键"""
     config_str = (
@@ -120,12 +115,11 @@ def get_default_api_base_for_type(api_type: str) -> str | None:
     """根据API类型获取默认的API基础地址"""
     default_api_bases = {
         "openai": "https://api.openai.com",
-        "deepseek": "https://api.deepseek.com/beta",
+        "deepseek": "https://api.deepseek.com",
         "zhipu": "https://open.bigmodel.cn",
         "gemini": "https://generativelanguage.googleapis.com",
         "openrouter": "https://openrouter.ai/api",
-        "smart": None,
+        "general_openai_compat": None,
-        "openai_responses": None,
     }
 
     return default_api_bases.get(api_type)
@@ -250,7 +244,7 @@ def list_embedding_models() -> list[dict[str, Any]]:
 
 async def get_model_instance(
     provider_model_name: str | None = None,
-    override_config: dict[str, Any] | LLMGenerationConfig | None = None,
+    override_config: dict[str, Any] | None = None,
 ) -> LLMModel:
     """
     根据 'ProviderName/ModelName' 字符串获取并实例化 LLMModel (异步版本)
@@ -309,20 +303,21 @@ async def get_model_instance(
 
     model_detail_found.is_embedding_model = capabilities.is_embedding_model
 
-    llm_config = get_llm_config()
+    ai_config = get_ai_config()
-    client_settings = llm_config.client_settings
+    global_proxy_setting = ai_config.get(PROXY_KEY)
     default_timeout = (
         provider_config_found.timeout
         if provider_config_found.timeout is not None
-        else client_settings.timeout
+        else 180
     )
+    global_timeout_setting = ai_config.get(TIMEOUT_KEY, default_timeout)
 
     config_for_http_client = ProviderConfig(
         name=provider_config_found.name,
         api_key=provider_config_found.api_key,
         models=provider_config_found.models,
-        timeout=default_timeout,
+        timeout=global_timeout_setting,
-        proxy=client_settings.proxy,
+        proxy=global_proxy_setting,
         api_base=provider_config_found.api_base,
         api_type=provider_config_found.api_type,
         openai_compat=provider_config_found.openai_compat,

zhenxun/services/llm/memory.py

@@ -1,243 +1,55 @@
-"""
-LLM 服务 - 会话记忆模块
-
-定义了LLM会话记忆的存储、策略和处理接口。
-"""
-
 from abc import ABC, abstractmethod
 from collections import defaultdict
-from collections.abc import Callable
 from typing import Any
 
-from pydantic import BaseModel, Field
+from .types import LLMMessage
-
-from zhenxun.services.llm.types import LLMMessage
-from zhenxun.services.log import logger
-
-
-class AIConfig(BaseModel):
-    """AI配置类 (为保持独立性而在此处保留一个副本，实际使用中可能来自更高层)"""
-
-    model: Any = None
-    default_embedding_model: Any = None
-    default_preserve_media_in_history: bool = False
-    tool_providers: list[Any] = Field(default_factory=list)
-
-    def __post_init__(self):
-        """初始化后从配置中读取默认值"""
-        pass
-
-
-class BaseMessageStore(ABC):
-    """
-    底层存储接口 (DAO - Data Access Object)。
-
-    这是一个抽象基类，定义了消息数据最底层的 **持久化与检索 (CRUD)** 接口。
-    它只关心数据的存取，不涉及任何业务逻辑（如历史记录修剪）。
-
-    开发者如果希望将对话历史存储到 Redis、数据库或其他持久化后端，
-    应当实现这个接口。
-    """
-
-    @abstractmethod
-    async def get_messages(self, session_id: str) -> list[LLMMessage]:
-        """
-        根据会话ID获取完整的消息列表。
-        """
-        raise NotImplementedError
-
-    @abstractmethod
-    async def add_messages(self, session_id: str, messages: list[LLMMessage]) -> None:
-        """追加消息"""
-        raise NotImplementedError
-
-    @abstractmethod
-    async def set_messages(self, session_id: str, messages: list[LLMMessage]) -> None:
-        """
-        完全覆盖指定会话ID的消息列表。
-        主要用于历史记录修剪等场景。
-        """
-        raise NotImplementedError
-
-    @abstractmethod
-    async def clear(self, session_id: str) -> None:
-        """清空指定会话ID的所有消息数据。"""
-        raise NotImplementedError
-
-
-class InMemoryMessageStore(BaseMessageStore):
-    """
-    一个基于内存的 `BaseMessageStore` 实现。
-
-    它使用一个Python字典来存储所有会话的消息，提供了最简单、最快速的存储方案。
-    这是框架的默认存储方式，实现了开箱即用。
-
-    注意：此实现是 **非持久化** 的，当应用程序重启时，所有对话历史都会丢失。
-    适用于测试、简单应用或不需要长期记忆的场景。
-    """
-
-    def __init__(self):
-        self._data: dict[str, list[LLMMessage]] = defaultdict(list)
-
-    async def get_messages(self, session_id: str) -> list[LLMMessage]:
-        """从内存字典中获取消息列表的副本。"""
-        return self._data.get(session_id, []).copy()
-
-    async def add_messages(self, session_id: str, messages: list[LLMMessage]) -> None:
-        """向内存中的消息列表追加消息。"""
-        self._data[session_id].extend(messages)
-
-    async def set_messages(self, session_id: str, messages: list[LLMMessage]) -> None:
-        """在内存中直接替换指定会话的消息列表。"""
-        self._data[session_id] = messages
-
-    async def clear(self, session_id: str) -> None:
-        """从内存字典中删除指定会话的条目。"""
-        if session_id in self._data:
-            del self._data[session_id]
 
 
 class BaseMemory(ABC):
     """
-    记忆系统上层逻辑基类 (Strategy Layer)。
+    记忆系统的抽象基类。
-
+    定义了任何记忆后端都必须实现的接口。
-    此抽象基类定义了记忆系统的 **策略层** 接口。它负责对外提供统一的记忆操作
-    接口，并封装了具体的记忆管理策略，如历史记录的修剪、摘要生成等。
-
-    `AI` 会话客户端直接与此接口交互，而不关心底层的存储实现。
-
-    开发者可以通过实现此接口来创建自定义的记忆管理策略，例如：
-    - `SummarizationMemory`: 在历史记录过长时，自动调用LLM生成摘要来压缩历史。
-    - `VectorStoreMemory`: 将对话历史向量化并存入向量数据库，实现长期记忆检索。
     """
 
     @abstractmethod
     async def get_history(self, session_id: str) -> list[LLMMessage]:
-        """获取用于构建模型输入的完整历史消息列表。"""
+        """根据会话ID获取历史记录。"""
         raise NotImplementedError
 
+    @abstractmethod
+    async def add_message(self, session_id: str, message: LLMMessage) -> None:
+        """向指定会话添加一条消息。"""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def add_messages(self, session_id: str, messages: list[LLMMessage]) -> None:
+        """向指定会话添加多条消息。"""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def clear_history(self, session_id: str) -> None:
+        """清空指定会话的历史记录。"""
+        raise NotImplementedError
+
+
+class InMemoryMemory(BaseMemory):
+    """
+    一个简单的、默认的内存记忆后端。
+    将历史记录存储在进程内存中的字典里。
+    """
+
+    def __init__(self, **kwargs: Any):
+        self._history: dict[str, list[LLMMessage]] = defaultdict(list)
+
+    async def get_history(self, session_id: str) -> list[LLMMessage]:
+        return self._history.get(session_id, []).copy()
+
     async def add_message(self, session_id: str, message: LLMMessage) -> None:
-        """向记忆中添加单条消息。默认实现是调用 `add_messages`。"""
+        self._history[session_id].append(message)
-        await self.add_messages(session_id, [message])
-
-    @abstractmethod
-    async def add_messages(self, session_id: str, messages: list[LLMMessage]) -> None:
-        """向记忆中添加多条消息，并可能触发内部的记忆管理策略（如修剪）。"""
-        raise NotImplementedError
-
-    @abstractmethod
-    async def clear_history(self, session_id: str) -> None:
-        """清空指定会话的全部记忆。"""
-        raise NotImplementedError
-
-
-class ChatMemory(BaseMemory):
-    """
-    标准聊天记忆实现：组合 Store + 滑动窗口策略。
-
-    这是 `BaseMemory` 的默认实现，它通过组合一个 `BaseMessageStore` 实例来
-    完成实际的数据存储，并在此之上实现了一个简单的“滑动窗口”记忆修剪策略。
-    """
-
-    def __init__(self, store: BaseMessageStore, max_messages: int = 50):
-        self.store = store
-        self._max_messages = max_messages
-
-    async def _trim_history(self, session_id: str) -> None:
-        """
-        记忆修剪策略：确保历史记录不超过 `_max_messages` 条。
-
-        如果存在系统消息 (System Prompt)，它将被永久保留在列表的第一位。
-        """
-        history = await self.store.get_messages(session_id)
-        if len(history) <= self._max_messages:
-            return
-
-        has_system = history and history[0].role == "system"
-        new_history: list[LLMMessage] = []
-
-        if has_system:
-            keep_count = max(0, self._max_messages - 1)
-            new_history = [history[0], *history[-keep_count:]]
-        else:
-            new_history = history[-self._max_messages :]
-
-        await self.store.set_messages(session_id, new_history)
-
-    async def get_history(self, session_id: str) -> list[LLMMessage]:
-        """直接从底层存储获取历史记录。"""
-        return await self.store.get_messages(session_id)
 
     async def add_messages(self, session_id: str, messages: list[LLMMessage]) -> None:
-        """添加消息到历史记录，并立即执行修剪策略。"""
+        self._history[session_id].extend(messages)
-        await self.store.add_messages(session_id, messages)
-        await self._trim_history(session_id)
 
     async def clear_history(self, session_id: str) -> None:
-        """清空底层存储中的历史记录。"""
+        if session_id in self._history:
-        await self.store.clear(session_id)
+            del self._history[session_id]
-
-
-class MemoryProcessor(ABC):
-    """
-    记忆处理器接口 (Hook/Observer)。
-
-    这是一个扩展接口，允许开发者创建自定义的“记忆处理器”，以在记忆被修改后
-    执行额外的操作（“钩子”）。
-
-    当 `AI` 实例的记忆更新时，它会依次调用所有注册的 `MemoryProcessor`。
-
-    使用场景示例：
-    - `LoggingMemoryProcessor`: 将每一轮对话异步记录到外部日志系统。
-    - `SummarizationProcessor`: 在后台任务中检查对话长度，并在需要时生成摘要。
-    - `EntityExtractionProcessor`: 从对话中提取关键实体（如人名、地名）并存储。
-    """
-
-    @abstractmethod
-    async def process(self, session_id: str, new_messages: list[LLMMessage]) -> None:
-        """处理新添加到记忆中的消息。"""
-        pass
-
-
-_default_memory_factory: Callable[[], BaseMemory] | None = None
-
-
-def set_default_memory_backend(factory: Callable[[], BaseMemory]):
-    """
-    设置全局默认记忆后端工厂，允许统一替换会话的记忆实现。
-
-    这是一个高级依赖注入函数，允许插件或项目在启动时用自定义的 `BaseMemory`
-    实现替换掉默认的 `ChatMemory(InMemoryMessageStore())`。
-
-    Args:
-        factory: 一个无参数的、返回 `BaseMemory` 实例的函数或类。
-    """
-    global _default_memory_factory
-    _default_memory_factory = factory
-
-
-def _get_default_memory() -> BaseMemory:
-    """
-    [内部函数] 获取一个默认的记忆后端实例。
-
-    它会首先检查是否有通过 `set_default_memory_backend` 设置的全局工厂，
-    如果有，则使用该工厂创建实例；否则，返回一个标准的内存记忆实例。
-    """
-    if _default_memory_factory:
-        logger.debug("使用自定义的默认记忆后端工厂构建实例。")
-        return _default_memory_factory()
-
-    logger.debug("未配置自定义记忆后端，使用默认的 ChatMemory。")
-    return ChatMemory(store=InMemoryMessageStore())
-
-
-__all__ = [
-    "AIConfig",
-    "BaseMemory",
-    "BaseMessageStore",
-    "ChatMemory",
-    "InMemoryMessageStore",
-    "MemoryProcessor",
-    "_get_default_memory",
-    "set_default_memory_backend",
-]

zhenxun/services/llm/session.py

@@ -4,37 +4,30 @@ LLM 服务 - 会话客户端
 提供一个有状态的、面向会话的 LLM 客户端，用于进行多轮对话和复杂交互。
 """
 
-from collections.abc import Awaitable, Callable
 import copy
+from dataclasses import dataclass, field
 import json
-from typing import Any, TypeVar, cast
+from typing import Any, TypeVar
 import uuid
 
-from jinja2 import Template
+from jinja2 import Environment
-from nonebot.utils import is_coroutine_callable
+from nonebot.compat import type_validate_json
 from nonebot_plugin_alconna.uniseg import UniMessage
-from pydantic import BaseModel
+from pydantic import BaseModel, ValidationError
 
 from zhenxun.services.log import logger
-from zhenxun.utils.pydantic_compat import model_json_schema
+from zhenxun.utils.pydantic_compat import model_copy, model_dump, model_json_schema
 
 from .config import (
     CommonOverrides,
-    GenConfigBuilder,
-    LLMEmbeddingConfig,
     LLMGenerationConfig,
 )
-from .config.generation import OutputConfig
+from .config.providers import get_ai_config
-from .config.providers import get_llm_config
 from .manager import get_global_default_model_name, get_model_instance
-from .memory import (
+from .memory import BaseMemory, InMemoryMemory
-    AIConfig,
+from .tools.manager import tool_provider_manager
-    BaseMemory,
-    MemoryProcessor,
-    _get_default_memory,
-)
-from .tools import tool_provider_manager
 from .types import (
+    EmbeddingTaskType,
     LLMContentPart,
     LLMErrorCode,
     LLMException,
@@ -42,31 +35,30 @@ from .types import (
     LLMResponse,
     ModelName,
     ResponseFormat,
-    StructuredOutputStrategy,
-    ToolChoice,
     ToolExecutable,
+    ToolProvider,
 )
-from .types.models import (
+from .utils import normalize_to_llm_messages
-    GeminiCodeExecution,
-    GeminiGoogleSearch,
-)
-from .utils import (
-    create_cot_wrapper,
-    normalize_to_llm_messages,
-    parse_and_validate_json,
-    should_apply_autocot,
-)
 
 T = TypeVar("T", bound=BaseModel)
 
-DEFAULT_IVR_TEMPLATE = (
+jinja_env = Environment(autoescape=False)
-    "你的响应未能通过结构校验。\n"
+
-    "错误详情: {error_msg}\n\n"
+
-    "请执行以下步骤进行修正：\n"
+@dataclass
-    "1. 反思：分析为什么会出现这个错误。\n"
+class AIConfig:
-    "2. 修正：生成一个新的、符合 Schema 要求的 JSON 对象。\n"
+    """AI配置类 - [重构后] 简化版本"""
-    "请直接输出修正后的 JSON，不要包含 Markdown 标记或其他解释。"
+
-)
+    model: ModelName = None
+    default_embedding_model: ModelName = None
+    default_preserve_media_in_history: bool = False
+    tool_providers: list[ToolProvider] = field(default_factory=list)
+
+    def __post_init__(self):
+        """初始化后从配置中读取默认值"""
+        ai_config = get_ai_config()
+        if self.model is None:
+            self.model = ai_config.get("default_model_name")
 
 
 class AI:
@@ -81,7 +73,6 @@ class AI:
         config: AIConfig | None = None,
         memory: BaseMemory | None = None,
         default_generation_config: LLMGenerationConfig | None = None,
-        processors: list[MemoryProcessor] | None = None,
     ):
         """
         初始化AI服务
@@ -89,47 +80,25 @@ class AI:
         参数:
             session_id: 唯一的会话ID，用于隔离记忆。
             config: AI 配置.
-            memory: 可选的自定义记忆后端。如果为None，则使用默认的 ChatMemory
+            memory: 可选的自定义记忆后端。如果为None，则使用默认的InMemoryMemory。
-            (InMemoryMessageStore)。
+            default_generation_config: (新增) 此AI实例的默认生成配置。
-            default_generation_config: 此AI实例的默认生成配置。
-            processors: 记忆处理器列表，在添加记忆后触发。
         """
         self.session_id = session_id or str(uuid.uuid4())
         self.config = config or AIConfig()
-        self.memory = memory or _get_default_memory()
+        self.memory = memory or InMemoryMemory()
         self.default_generation_config = (
             default_generation_config or LLMGenerationConfig()
         )
-        self.processors = processors or []
 
         global_providers = tool_provider_manager._providers
         config_providers = self.config.tool_providers
         self._tool_providers = list(dict.fromkeys(global_providers + config_providers))
-        self.message_buffer: list[LLMMessage] = []
 
     async def clear_history(self):
         """清空当前会话的历史记录。"""
         await self.memory.clear_history(self.session_id)
         logger.info(f"AI会话历史记录已清空 (session_id: {self.session_id})")
 
-    async def add_observation(
-        self, message: str | UniMessage | LLMMessage | list[LLMContentPart]
-    ):
-        """
-        将一条观察消息加入缓冲区，不立即触发模型调用。
-
-        返回:
-            int: 缓冲区中消息的数量。
-        """
-        current_message = await self._normalize_input_to_message(message)
-        self.message_buffer.append(current_message)
-        content_preview = str(current_message.content)[:50]
-        logger.debug(
-            f"[放入观察] {content_preview} (缓冲区大小: {len(self.message_buffer)})",
-            "AI_MEMORY",
-        )
-        return len(self.message_buffer)
-
     async def add_user_message_to_history(
         self, message: str | LLMMessage | list[LLMContentPart]
     ):
@@ -192,7 +161,7 @@ class AI:
         self, message: str | UniMessage | LLMMessage | list[LLMContentPart]
     ) -> LLMMessage:
         """
-        内部辅助方法，将各种输入类型统一转换为单个 LLMMessage 对象。
+        [重构后] 内部辅助方法，将各种输入类型统一转换为单个 LLMMessage 对象。
         它调用共享的工具函数并提取最后一条消息（通常是用户输入）。
         """
         messages = await normalize_to_llm_messages(message)
@@ -203,79 +172,17 @@ class AI:
             )
         return messages[-1]
 
-    async def generate_internal(
-        self,
-        messages: list[LLMMessage],
-        *,
-        model: ModelName = None,
-        config: LLMGenerationConfig | GenConfigBuilder | None = None,
-        tools: list[Any] | dict[str, ToolExecutable] | None = None,
-        tool_choice: str | dict[str, Any] | ToolChoice | None = None,
-        timeout: float | None = None,
-        model_instance: Any = None,
-    ) -> LLMResponse:
-        """
-        内部生成核心方法，负责配置合并、工具解析和模型调用。
-        此方法不处理历史记录的存储，供 AgentExecutor 或 chat 方法调用。
-        """
-        final_config = self.default_generation_config
-        if isinstance(config, GenConfigBuilder):
-            config = config.build()
-
-        if config:
-            final_config = final_config.merge_with(config)
-
-        final_tools_list = []
-        if tools:
-            if isinstance(tools, dict):
-                final_tools_list = list(tools.values())
-            elif isinstance(tools, list):
-                to_resolve: list[Any] = []
-                for t in tools:
-                    if isinstance(t, str | dict):
-                        to_resolve.append(t)
-                    else:
-                        final_tools_list.append(t)
-
-                if to_resolve:
-                    resolved_dict = await self._resolve_tools(to_resolve)
-                    final_tools_list.extend(resolved_dict.values())
-
-        if model_instance:
-            return await model_instance.generate_response(
-                messages,
-                config=final_config,
-                tools=final_tools_list if final_tools_list else None,
-                tool_choice=tool_choice,
-                timeout=timeout,
-            )
-
-        resolved_model_name = self._resolve_model_name(model or self.config.model)
-        async with await get_model_instance(
-            resolved_model_name,
-            override_config=None,
-        ) as instance:
-            return await instance.generate_response(
-                messages,
-                config=final_config,
-                tools=final_tools_list if final_tools_list else None,
-                tool_choice=tool_choice,
-                timeout=timeout,
-            )
-
     async def chat(
         self,
-        message: str | UniMessage | LLMMessage | list[LLMContentPart] | None,
+        message: str | UniMessage | LLMMessage | list[LLMContentPart],
         *,
         model: ModelName = None,
         instruction: str | None = None,
         template_vars: dict[str, Any] | None = None,
         preserve_media_in_history: bool | None = None,
-        tools: list[Any] | dict[str, ToolExecutable] | None = None,
+        tools: list[dict[str, Any] | str] | dict[str, ToolExecutable] | None = None,
-        tool_choice: str | dict[str, Any] | ToolChoice | None = None,
+        tool_choice: str | dict[str, Any] | None = None,
-        config: LLMGenerationConfig | GenConfigBuilder | None = None,
+        config: LLMGenerationConfig | None = None,
-        use_buffer: bool = False,
-        timeout: float | None = None,
     ) -> LLMResponse:
         """
         核心交互方法，管理会话历史并执行单次LLM调用。
@@ -291,27 +198,18 @@ class AI:
             tools: 可用的工具列表或工具字典，支持临时工具和预配置工具。
             tool_choice: 工具选择策略，控制AI如何选择和使用工具。
             config: 生成配置对象，用于覆盖默认的生成参数。
-            use_buffer: 是否刷新并包含消息缓冲区的内容，在此次对话中一次性提交。
-            timeout: HTTP 请求超时时间（秒）。
 
         返回:
             LLMResponse: 包含AI回复、工具调用请求、使用信息等的完整响应对象。
         """
-        messages_to_add: list[LLMMessage] = []
+        current_message = await self._normalize_input_to_message(message)
-        if message:
-            current_message = await self._normalize_input_to_message(message)
-            messages_to_add.append(current_message)
-
-        if use_buffer and self.message_buffer:
-            messages_to_add = self.message_buffer + messages_to_add
-            self.message_buffer.clear()
 
         messages_for_run = []
         final_instruction = instruction
 
         if final_instruction and template_vars:
             try:
-                template = Template(final_instruction)
+                template = jinja_env.from_string(final_instruction)
                 final_instruction = template.render(**template_vars)
                 logger.debug(f"渲染后的系统指令: {final_instruction}")
             except Exception as e:
@@ -322,55 +220,51 @@ class AI:
 
         current_history = await self.memory.get_history(self.session_id)
         messages_for_run.extend(current_history)
-        messages_for_run.extend(messages_to_add)
+        messages_for_run.append(current_message)
 
         try:
-            response = await self.generate_internal(
+            resolved_model_name = self._resolve_model_name(model or self.config.model)
-                messages_for_run,
+
-                model=model,
+            final_config = model_copy(self.default_generation_config, deep=True)
-                config=config,
+            if config:
-                tools=tools,
+                update_dict = model_dump(config, exclude_unset=True)
-                tool_choice=tool_choice,
+                final_config = model_copy(final_config, update=update_dict)
-                timeout=timeout,
+
-            )
+            ad_hoc_tools = None
+            if tools:
+                if isinstance(tools, dict):
+                    ad_hoc_tools = tools
+                else:
+                    ad_hoc_tools = await self._resolve_tools(tools)
+
+            async with await get_model_instance(
+                resolved_model_name,
+                override_config=final_config.to_dict(),
+            ) as model_instance:
+                response = await model_instance.generate_response(
+                    messages_for_run, tools=ad_hoc_tools, tool_choice=tool_choice
+                )
 
             should_preserve = (
                 preserve_media_in_history
                 if preserve_media_in_history is not None
                 else self.config.default_preserve_media_in_history
             )
-            msgs_to_store: list[LLMMessage] = []
+            user_msg_to_store = (
-            for msg in messages_to_add:
+                current_message
-                store_msg = (
+                if should_preserve
-                    msg if should_preserve else self._sanitize_message_for_history(msg)
+                else self._sanitize_message_for_history(current_message)
+            )
+            assistant_response_msg = LLMMessage.assistant_text_response(response.text)
+            if response.tool_calls:
+                assistant_response_msg = LLMMessage.assistant_tool_calls(
+                    response.tool_calls, response.text
                 )
-                msgs_to_store.append(store_msg)
-
-            if response.content_parts:
-                assistant_response_msg = LLMMessage(
-                    role="assistant",
-                    content=response.content_parts,
-                    tool_calls=response.tool_calls,
-                )
-            else:
-                assistant_response_msg = LLMMessage.assistant_text_response(
-                    response.text
-                )
-                if response.tool_calls:
-                    assistant_response_msg = LLMMessage.assistant_tool_calls(
-                        response.tool_calls, response.text
-                    )
 
             await self.memory.add_messages(
-                self.session_id, [*msgs_to_store, assistant_response_msg]
+                self.session_id, [user_msg_to_store, assistant_response_msg]
             )
 
-            if self.processors:
-                for processor in self.processors:
-                    await processor.process(
-                        self.session_id, [*msgs_to_store, assistant_response_msg]
-                    )
-
             return response
 
         except Exception as e:
@@ -386,7 +280,7 @@ class AI:
         *,
         model: ModelName = None,
         timeout: int | None = None,
-        config: LLMGenerationConfig | GenConfigBuilder | None = None,
+        config: LLMGenerationConfig | None = None,
     ) -> LLMResponse:
         """
         代码执行
@@ -400,18 +294,16 @@ class AI:
         返回:
             LLMResponse: 包含执行结果的完整响应对象。
         """
-        resolved_model = model or self.config.model
+        resolved_model = model or self.config.model or "Gemini/gemini-2.0-flash"
 
         code_config = CommonOverrides.gemini_code_execution()
         if timeout:
             code_config.custom_params = code_config.custom_params or {}
             code_config.custom_params["code_execution_timeout"] = timeout
 
-        if isinstance(config, GenConfigBuilder):
-            config = config.build()
-
         if config:
-            code_config = code_config.merge_with(config)
+            update_dict = model_dump(config, exclude_unset=True)
+            code_config = model_copy(code_config, update=update_dict)
 
         return await self.chat(prompt, model=resolved_model, config=code_config)
 
@@ -425,7 +317,7 @@ class AI:
             "根据用户的查询找到最相关的信息，并进行总结和回答。"
         ),
         template_vars: dict[str, Any] | None = None,
-        config: LLMGenerationConfig | GenConfigBuilder | None = None,
+        config: LLMGenerationConfig | None = None,
     ) -> LLMResponse:
         """
         信息搜索的便捷入口，原生支持多模态查询。
@@ -433,11 +325,9 @@ class AI:
         logger.info("执行 'search' 任务...")
         search_config = CommonOverrides.gemini_grounding()
 
-        if isinstance(config, GenConfigBuilder):
-            config = config.build()
-
         if config:
-            search_config = search_config.merge_with(config)
+            update_dict = model_dump(config, exclude_unset=True)
+            search_config = model_copy(search_config, update=update_dict)
 
         return await self.chat(
             query,
@@ -445,36 +335,25 @@ class AI:
             instruction=instruction,
             template_vars=template_vars,
             config=search_config,
-            tools=[GeminiGoogleSearch()],
         )
 
     async def generate_structured(
         self,
-        message: str | UniMessage | LLMMessage | list[LLMContentPart] | None,
+        message: str | LLMMessage | list[LLMContentPart],
         response_model: type[T],
         *,
         model: ModelName = None,
-        tools: list[Any] | dict[str, ToolExecutable] | None = None,
-        tool_choice: str | dict[str, Any] | ToolChoice | None = None,
         instruction: str | None = None,
-        timeout: float | None = None,
+        config: LLMGenerationConfig | None = None,
-        template_vars: dict[str, Any] | None = None,
-        config: LLMGenerationConfig | GenConfigBuilder | None = None,
-        max_validation_retries: int | None = None,
-        validation_callback: Callable[[T], Any | Awaitable[Any]] | None = None,
-        error_prompt_template: str | None = None,
-        auto_thinking: bool = False,
     ) -> T:
         """
         生成结构化响应，并自动解析为指定的Pydantic模型。
 
         参数:
-            message: 用户输入的消息内容，支持多种格式。为None时只使用历史+缓冲区。
+            message: 用户输入的消息内容，支持多种格式。
             response_model: 用于解析和验证响应的Pydantic模型类。
             model: 要使用的模型名称，如果为None则使用配置中的默认模型。
             instruction: 本次调用的特定系统指令，会与JSON Schema指令合并。
-            timeout: HTTP 请求超时时间（秒）。
-            template_vars: 系统指令中的模板变量，用于动态渲染。
             config: 生成配置对象，用于覆盖默认的生成参数。
 
         返回:
@@ -483,46 +362,6 @@ class AI:
         异常:
             LLMException: 如果模型返回的不是有效的JSON或验证失败。
         """
-        if isinstance(config, GenConfigBuilder):
-            config = config.build()
-
-        final_config = self.default_generation_config.merge_with(config)
-
-        if final_config is None:
-            final_config = LLMGenerationConfig()
-
-        if max_validation_retries is None:
-            max_validation_retries = get_llm_config().client_settings.structured_retries
-
-        resolved_model_name = self._resolve_model_name(model or self.config.model)
-
-        request_autocot = True if auto_thinking is False else auto_thinking
-        effective_auto_thinking = should_apply_autocot(
-            request_autocot, resolved_model_name, final_config
-        )
-
-        target_model: type[T] = response_model
-        if effective_auto_thinking:
-            target_model = cast(type[T], create_cot_wrapper(response_model))
-            response_model = target_model
-
-            cot_instruction = (
-                "请务必先在 `reasoning` 字段中进行详细的一步步推理，确保逻辑正确，"
-                "然后再填充 `result` 字段。"
-            )
-            if instruction:
-                instruction = f"{instruction}\n\n{cot_instruction}"
-            else:
-                instruction = cot_instruction
-
-        final_instruction = instruction
-        if final_instruction and template_vars:
-            try:
-                template = Template(final_instruction)
-                final_instruction = template.render(**template_vars)
-            except Exception as e:
-                logger.error(f"渲染结构化指令模板失败: {e}", e=e)
-
         try:
             json_schema = model_json_schema(response_model)
         except AttributeError:
@@ -530,149 +369,41 @@ class AI:
 
         schema_str = json.dumps(json_schema, ensure_ascii=False, indent=2)
 
-        prompt_prefix = f"{final_instruction}\n\n" if final_instruction else ""
+        system_prompt = (
-        structured_strategy = (
+            (f"{instruction}\n\n" if instruction else "")
-            final_config.output.structured_output_strategy
+            + "你必须严格按照以下 JSON Schema 格式进行响应。"
-            if final_config.output
+            + "不要包含任何额外的解释、注释或代码块标记，只返回纯粹的 JSON 对象。\n\n"
-            else None
         )
-        if structured_strategy == StructuredOutputStrategy.TOOL_CALL:
+        system_prompt += f"JSON Schema:\n```json\n{schema_str}\n```"
-            system_prompt = prompt_prefix + "请调用提供的工具提交结构化数据。"
+
-        else:
+        final_config = model_copy(config) if config else LLMGenerationConfig()
-            system_prompt = (
+
-                prompt_prefix
+        final_config.response_format = ResponseFormat.JSON
-                + "请严格按照以下 JSON Schema 格式进行响应。不应包含任何额外的解释、"
+        final_config.response_schema = json_schema
-                "注释或代码块标记，只返回一个合法的 JSON 对象。\n\n"
+
+        response = await self.chat(
+            message, model=model, instruction=system_prompt, config=final_config
+        )
+
+        try:
+            return type_validate_json(response_model, response.text)
+        except ValidationError as e:
+            logger.error(f"LLM结构化输出验证失败: {e}", e=e)
+            raise LLMException(
+                "LLM返回的JSON未能通过结构验证。",
+                code=LLMErrorCode.RESPONSE_PARSE_ERROR,
+                details={"raw_response": response.text, "validation_error": str(e)},
+                cause=e,
             )
-            system_prompt += f"JSON Schema:\n```json\n{schema_str}\n```"
+        except Exception as e:
-
+            logger.error(f"解析LLM结构化输出时发生未知错误: {e}", e=e)
-        structured_strategy = (
+            raise LLMException(
-            final_config.output.structured_output_strategy
+                "解析LLM的JSON输出时失败。",
-            if final_config.output
+                code=LLMErrorCode.RESPONSE_PARSE_ERROR,
-            else StructuredOutputStrategy.NATIVE
+                details={"raw_response": response.text},
-        )
+                cause=e,
-
-        final_tools_list: list[ToolExecutable] | None = None
-        if structured_strategy != StructuredOutputStrategy.NATIVE:
-            if tools:
-                final_tools_list = []
-                if isinstance(tools, dict):
-                    final_tools_list = list(tools.values())
-                elif isinstance(tools, list):
-                    to_resolve: list[Any] = []
-                    for t in tools:
-                        if isinstance(t, str | dict):
-                            to_resolve.append(t)
-                        else:
-                            final_tools_list.append(t)
-                    if to_resolve:
-                        resolved_dict = await self._resolve_tools(to_resolve)
-                        final_tools_list.extend(resolved_dict.values())
-        elif tools:
-            logger.warning(
-                "检测到在 generate_structured (NATIVE 策略) 中传入了 tools。"
-                "为了避免 API 冲突(Gemini)及输出歧义(OpenAI)，这些"
-                "tools 将被本次请求忽略。"
-                "若需使用工具，请使用 chat() 方法或 Agent 流程。"
             )
 
-        if final_config.output is None:
-            final_config.output = OutputConfig()
-
-        final_config.output.response_format = ResponseFormat.JSON
-        final_config.output.response_schema = json_schema
-
-        messages_for_run = [LLMMessage.system(system_prompt)]
-        current_history = await self.memory.get_history(self.session_id)
-        messages_for_run.extend(current_history)
-        messages_for_run.extend(self.message_buffer)
-        if message:
-            normalized_message = await self._normalize_input_to_message(message)
-            messages_for_run.append(normalized_message)
-
-        ivr_messages = list(messages_for_run)
-        last_exception: Exception | None = None
-
-        for attempt in range(max_validation_retries + 1):
-            current_response_text: str = ""
-
-            async with await get_model_instance(
-                resolved_model_name,
-                override_config=None,
-            ) as model_instance:
-                response = await model_instance.generate_response(
-                    ivr_messages,
-                    config=final_config,
-                    tools=final_tools_list if final_tools_list else None,
-                    tool_choice=tool_choice,
-                    timeout=timeout,
-                )
-                current_response_text = response.text
-
-            try:
-                parsed_obj = parse_and_validate_json(response.text, target_model)
-
-                final_obj: T = cast(T, parsed_obj)
-                if effective_auto_thinking:
-                    logger.debug(
-                        f"AutoCoT 思考过程: {getattr(parsed_obj, 'reasoning', '')}"
-                    )
-                    final_obj = cast(T, getattr(parsed_obj, "result"))
-
-                if validation_callback:
-                    if is_coroutine_callable(validation_callback):
-                        await validation_callback(final_obj)
-                    else:
-                        validation_callback(final_obj)
-
-                return final_obj
-
-            except Exception as e:
-                is_llm_error = isinstance(e, LLMException)
-                llm_error: LLMException | None = (
-                    cast(LLMException, e) if is_llm_error else None
-                )
-                last_exception = e
-
-                if attempt < max_validation_retries:
-                    error_msg = (
-                        llm_error.details.get("validation_error", str(e))
-                        if llm_error
-                        else str(e)
-                    )
-                    raw_response = current_response_text or (
-                        llm_error.details.get("raw_response", "") if llm_error else ""
-                    )
-                    logger.warning(
-                        f"结构化校验失败 (尝试 {attempt + 1}/"
-                        f"{max_validation_retries + 1})。正在尝试 IVR 修复... 错误:"
-                        f"{error_msg}"
-                    )
-
-                    if raw_response:
-                        ivr_messages.append(
-                            LLMMessage.assistant_text_response(raw_response)
-                        )
-                    else:
-                        logger.warning(
-                            "IVR 警告: 无法获取上一轮生成的原始文本，"
-                            "模型将在无上下文情况下尝试修复。"
-                        )
-
-                    template = error_prompt_template or DEFAULT_IVR_TEMPLATE
-                    feedback_prompt = template.format(error_msg=error_msg)
-                    ivr_messages.append(LLMMessage.user(feedback_prompt))
-                    continue
-
-                if llm_error and not llm_error.recoverable:
-                    raise llm_error
-
-        if last_exception:
-            raise last_exception
-        raise LLMException(
-            "IVR 循环异常结束，未能生成有效结果。", code=LLMErrorCode.GENERATION_FAILED
-        )
-
     def _resolve_model_name(self, model_name: ModelName) -> str:
         """解析模型名称"""
         if model_name:
@@ -692,7 +423,8 @@ class AI:
         texts: list[str] | str,
         *,
         model: ModelName = None,
-        config: LLMEmbeddingConfig | None = None,
+        task_type: EmbeddingTaskType | str = EmbeddingTaskType.RETRIEVAL_DOCUMENT,
+        **kwargs: Any,
     ) -> list[list[float]]:
         """
         生成文本嵌入向量，将文本转换为数值向量表示。
@@ -700,13 +432,14 @@ class AI:
         参数:
             texts: 要生成嵌入的文本内容，支持单个字符串或字符串列表。
             model: 嵌入模型名称，如果为None则使用配置中的默认嵌入模型。
-            config: 嵌入配置
+            task_type: 嵌入任务类型，影响向量的优化方向（如检索、分类等）。
+            **kwargs: 传递给嵌入模型的额外参数。
 
         返回:
             list[list[float]]: 文本对应的嵌入向量列表，每个向量为浮点数列表。
 
         异常:
-            LLMException: 当嵌入生成失败或模型配置错误时抛出
+            LLMException: 如果嵌入生成失败或模型配置错误。
         """
         if isinstance(texts, str):
             texts = [texts]
@@ -719,20 +452,18 @@ class AI:
             )
             if not resolved_model_str:
                 raise LLMException(
-                    "使用 embed 方法时未指定嵌入模型名称，"
+                    "使用 embed 功能时必须指定嵌入模型名称，"
-                    "且 AIConfig 未设置 default_embedding_model。",
+                    "或在 AIConfig 中配置 default_embedding_model。",
                     code=LLMErrorCode.MODEL_NOT_FOUND,
                 )
             resolved_model_str = self._resolve_model_name(resolved_model_str)
 
-            final_config = config or LLMEmbeddingConfig()
-
             async with await get_model_instance(
                 resolved_model_str,
                 override_config=None,
             ) as embedding_model_instance:
                 return await embedding_model_instance.generate_embeddings(
-                    texts, config=final_config
+                    texts, task_type=task_type, **kwargs
                 )
         except LLMException:
             raise
@@ -753,15 +484,6 @@ class AI:
         resolved: dict[str, ToolExecutable] = {}
 
         for config in tool_configs:
-            if isinstance(config, str):
-                if config == "google_search":
-                    resolved[config] = GeminiGoogleSearch()  # type: ignore[arg-type]
-                    continue
-                elif config == "code_execution":
-                    resolved[config] = GeminiCodeExecution()  # type: ignore[arg-type]
-                    continue
-                elif config == "url_context":
-                    pass
             name = config if isinstance(config, str) else config.get("name")
             if not name:
                 raise LLMException(

zhenxun/services/llm/tools.py

@@ -1,839 +0,0 @@
-"""
-工具模块
-
-整合了工具参数解析器、工具提供者管理器与工具执行逻辑，便于在 LLM 服务层统一调用。
-"""
-
-import asyncio
-from collections.abc import Callable
-from enum import Enum
-import inspect
-import json
-import re
-import time
-from typing import (
-    Annotated,
-    Any,
-    Optional,
-    Union,
-    cast,
-    get_args,
-    get_origin,
-    get_type_hints,
-)
-from typing_extensions import override
-
-from httpx import NetworkError, TimeoutException
-
-try:
-    import ujson as fast_json
-except ImportError:
-    fast_json = json
-
-import nonebot
-from nonebot.dependencies import Dependent, Param
-from nonebot.internal.adapter import Bot, Event
-from nonebot.internal.params import (
-    BotParam,
-    DefaultParam,
-    DependParam,
-    DependsInner,
-    EventParam,
-    StateParam,
-)
-from pydantic import BaseModel, Field, ValidationError, create_model
-from pydantic.fields import FieldInfo
-
-from zhenxun.services.log import logger
-from zhenxun.utils.decorator.retry import Retry
-from zhenxun.utils.pydantic_compat import model_dump, model_fields, model_json_schema
-
-from .types import (
-    LLMErrorCode,
-    LLMException,
-    LLMMessage,
-    LLMToolCall,
-    ToolExecutable,
-    ToolProvider,
-    ToolResult,
-)
-from .types.models import ToolDefinition
-from .types.protocols import BaseCallbackHandler, ToolCallData
-
-
-class ToolParam(Param):
-    """
-    工具参数提取器。
-
-    用于在自定义工具函数（Function Tool）中，从 LLM 解析出的参数字典
-    (`state["_tool_params"]`)
-    中提取特定的参数值。通常配合 `Annotated` 和依赖注入系统使用。
-    """
-
-    def __init__(self, *args: Any, name: str, **kwargs: Any):
-        super().__init__(*args, **kwargs)
-        self.name = name
-
-    def __repr__(self) -> str:
-        return f"ToolParam(name={self.name})"
-
-    @classmethod
-    @override
-    def _check_param(
-        cls, param: inspect.Parameter, allow_types: tuple[type[Param], ...]
-    ) -> Optional["ToolParam"]:
-        if param.default is not inspect.Parameter.empty and isinstance(
-            param.default, DependsInner
-        ):
-            return None
-
-        if get_origin(param.annotation) is Annotated:
-            for arg in get_args(param.annotation):
-                if isinstance(arg, DependsInner):
-                    return None
-
-        if param.kind not in (
-            inspect.Parameter.VAR_POSITIONAL,
-            inspect.Parameter.VAR_KEYWORD,
-        ):
-            return cls(name=param.name)
-        return None
-
-    @override
-    async def _solve(self, **kwargs: Any) -> Any:
-        state: dict[str, Any] = kwargs.get("state", {})
-        tool_params = state.get("_tool_params", {})
-        if self.name in tool_params:
-            return tool_params[self.name]
-        return None
-
-
-class RunContext(BaseModel):
-    """
-    依赖注入容器（DI Container），保留原有上下文信息的同时提升获取类型的能力。
-    """
-
-    session_id: str | None = None
-    scope: dict[str, Any] = Field(default_factory=dict)
-    extra: dict[str, Any] = Field(default_factory=dict)
-
-    class Config:
-        arbitrary_types_allowed = True
-
-
-class RunContextParam(Param):
-    """自动注入 RunContext 的参数解析器"""
-
-    @classmethod
-    def _check_param(
-        cls, param: inspect.Parameter, allow_types: tuple[type[Param], ...]
-    ) -> Optional["RunContextParam"]:
-        if param.annotation is RunContext:
-            return cls()
-        return None
-
-    async def _solve(self, **kwargs: Any) -> Any:
-        state = kwargs.get("state", {})
-        return state.get("_agent_context")
-
-
-def _parse_docstring_params(docstring: str | None) -> dict[str, str]:
-    """
-    解析文档字符串，提取参数描述。
-    支持 Google Style (Args:), ReST Style (:param:), 和中文风格 (参数:)。
-    """
-    if not docstring:
-        return {}
-
-    params: dict[str, str] = {}
-    lines = docstring.splitlines()
-
-    rest_pattern = re.compile(r"[:@]param\s+(\w+)\s*:?\s*(.*)")
-    found_rest = False
-    for line in lines:
-        match = rest_pattern.search(line)
-        if match:
-            params[match.group(1)] = match.group(2).strip()
-            found_rest = True
-
-    if found_rest:
-        return params
-
-    section_header_pattern = re.compile(
-        r"^\s*(?:Args|Arguments|Parameters|参数)\s*[:：]\s*$"
-    )
-
-    param_section_active = False
-    google_pattern = re.compile(r"^\s*(\**\w+)(?:\s*\(.*?\))?\s*[:：]\s*(.*)")
-
-    for line in lines:
-        stripped_line = line.strip()
-        if not stripped_line:
-            continue
-
-        if section_header_pattern.match(line):
-            param_section_active = True
-            continue
-
-        if param_section_active:
-            if (
-                stripped_line.endswith(":") or stripped_line.endswith("：")
-            ) and not google_pattern.match(line):
-                param_section_active = False
-                continue
-
-            match = google_pattern.match(line)
-            if match:
-                name = match.group(1).lstrip("*")
-                desc = match.group(2).strip()
-                params[name] = desc
-
-    return params
-
-
-def _create_dynamic_model(func: Callable) -> type[BaseModel]:
-    """根据函数签名动态创建 Pydantic 模型"""
-    sig = inspect.signature(func)
-    doc_params = _parse_docstring_params(func.__doc__)
-    type_hints = get_type_hints(func, include_extras=True)
-
-    fields = {}
-    for name, param in sig.parameters.items():
-        if name in ("self", "cls"):
-            continue
-
-        annotation = type_hints.get(name, Any)
-        default = param.default
-
-        is_run_context = False
-        if annotation is RunContext:
-            is_run_context = True
-        else:
-            origin = get_origin(annotation)
-            if origin is Union:
-                args = get_args(annotation)
-                if RunContext in args:
-                    is_run_context = True
-
-        if is_run_context:
-            continue
-
-        if default is not inspect.Parameter.empty and isinstance(default, DependsInner):
-            continue
-
-        if get_origin(annotation) is Annotated:
-            args = get_args(annotation)
-            if any(isinstance(arg, DependsInner) for arg in args):
-                continue
-
-        description = doc_params.get(name)
-        if isinstance(default, FieldInfo):
-            if description and not getattr(default, "description", None):
-                default.description = description
-            fields[name] = (annotation, default)
-        else:
-            if default is inspect.Parameter.empty:
-                default = ...
-            fields[name] = (annotation, Field(default, description=description))
-
-    return create_model(f"{func.__name__}Params", **fields)
-
-
-class FunctionExecutable(ToolExecutable):
-    """一个 ToolExecutable 的实现，用于包装一个普通的 Python 函数。"""
-
-    def __init__(
-        self,
-        func: Callable,
-        name: str,
-        description: str,
-        params_model: type[BaseModel] | None = None,
-        unpack_args: bool = False,
-    ):
-        self._func = func
-        self._name = name
-        self._description = description
-        self._params_model = params_model
-        self._unpack_args = unpack_args
-
-        self.dependent = Dependent[Any].parse(
-            call=func,
-            allow_types=(
-                DependParam,
-                BotParam,
-                EventParam,
-                StateParam,
-                RunContextParam,
-                ToolParam,
-                DefaultParam,
-            ),
-        )
-
-    async def get_definition(self) -> ToolDefinition:
-        if not self._params_model:
-            return ToolDefinition(
-                name=self._name,
-                description=self._description,
-                parameters={"type": "object", "properties": {}},
-            )
-
-        schema = model_json_schema(self._params_model)
-
-        return ToolDefinition(
-            name=self._name,
-            description=self._description,
-            parameters={
-                "type": "object",
-                "properties": schema.get("properties", {}),
-                "required": schema.get("required", []),
-            },
-        )
-
-    async def execute(
-        self, context: RunContext | None = None, **kwargs: Any
-    ) -> ToolResult:
-        context = context or RunContext()
-
-        tool_arguments = kwargs
-
-        if self._params_model:
-            try:
-                _fields = model_fields(self._params_model)
-                validation_input = {
-                    key: value for key, value in kwargs.items() if key in _fields
-                }
-
-                validated_params = self._params_model(**validation_input)
-
-                if not self._unpack_args:
-                    pass
-                else:
-                    validated_dict = model_dump(validated_params)
-                    tool_arguments = validated_dict
-
-            except ValidationError as e:
-                error_msgs = []
-                for err in e.errors():
-                    loc = ".".join(str(x) for x in err["loc"])
-                    msg = err["msg"]
-                    error_msgs.append(f"Parameter '{loc}': {msg}")
-
-                formatted_error = "; ".join(error_msgs)
-                error_payload = {
-                    "error_type": "InvalidArguments",
-                    "message": f"Parameter validation failed: {formatted_error}",
-                    "is_retryable": True,
-                }
-                return ToolResult(
-                    output=json.dumps(error_payload, ensure_ascii=False),
-                    display_content=f"Validation Error: {formatted_error}",
-                )
-            except Exception as e:
-                logger.error(
-                    f"执行工具 '{self._name}' 时参数验证或实例化失败: {e}", e=e
-                )
-                raise
-
-        state = {
-            "_tool_params": tool_arguments,
-            "_agent_context": context,
-        }
-
-        bot: Bot | None = None
-        if context and context.scope.get("bot"):
-            bot = context.scope.get("bot")
-        if not bot:
-            try:
-                bot = nonebot.get_bot()
-            except ValueError:
-                pass
-
-        event: Event | None = None
-        if context and context.scope.get("event"):
-            event = context.scope.get("event")
-
-        raw_result = await self.dependent(
-            bot=bot,
-            event=event,
-            state=state,
-        )
-
-        return ToolResult(output=raw_result, display_content=str(raw_result))
-
-
-class BuiltinFunctionToolProvider(ToolProvider):
-    """一个内置的 ToolProvider，用于处理通过装饰器注册的函数。"""
-
-    def __init__(self):
-        self._functions: dict[str, dict[str, Any]] = {}
-
-    def register(
-        self,
-        name: str,
-        func: Callable,
-        description: str,
-        params_model: type[BaseModel] | None = None,
-        unpack_args: bool = False,
-    ):
-        self._functions[name] = {
-            "func": func,
-            "description": description,
-            "params_model": params_model,
-            "unpack_args": unpack_args,
-        }
-
-    async def initialize(self) -> None:
-        pass
-
-    async def discover_tools(
-        self,
-        allowed_servers: list[str] | None = None,
-        excluded_servers: list[str] | None = None,
-    ) -> dict[str, ToolExecutable]:
-        executables = {}
-        for name, info in self._functions.items():
-            executables[name] = FunctionExecutable(
-                func=info["func"],
-                name=name,
-                description=info["description"],
-                params_model=info["params_model"],
-                unpack_args=info.get("unpack_args", False),
-            )
-        return executables
-
-    async def get_tool_executable(
-        self, name: str, config: dict[str, Any]
-    ) -> ToolExecutable | None:
-        if config.get("type", "function") == "function" and name in self._functions:
-            info = self._functions[name]
-            return FunctionExecutable(
-                func=info["func"],
-                name=name,
-                description=info["description"],
-                params_model=info["params_model"],
-                unpack_args=info.get("unpack_args", False),
-            )
-        return None
-
-
-class ToolProviderManager:
-    """工具提供者的中心化管理器，采用单例模式。"""
-
-    _instance: "ToolProviderManager | None" = None
-
-    def __new__(cls) -> "ToolProviderManager":
-        if cls._instance is None:
-            cls._instance = super().__new__(cls)
-        return cls._instance
-
-    def __init__(self):
-        if hasattr(self, "_initialized") and self._initialized:
-            return
-
-        self._providers: list[ToolProvider] = []
-        self._resolved_tools: dict[str, ToolExecutable] | None = None
-        self._init_lock = asyncio.Lock()
-        self._init_promise: asyncio.Task | None = None
-        self._builtin_function_provider = BuiltinFunctionToolProvider()
-        self.register(self._builtin_function_provider)
-        self._initialized = True
-
-    def register(self, provider: ToolProvider):
-        """注册一个新的 ToolProvider。"""
-        if provider not in self._providers:
-            self._providers.append(provider)
-            logger.info(f"已注册工具提供者: {provider.__class__.__name__}")
-
-    def function_tool(
-        self,
-        name: str,
-        description: str,
-        params_model: type[BaseModel] | None = None,
-    ):
-        """装饰器：将一个函数注册为内置工具。"""
-
-        def decorator(func: Callable):
-            if name in self._builtin_function_provider._functions:
-                logger.warning(f"正在覆盖已注册的函数工具: {name}")
-
-            final_model = params_model
-            unpack_args = False
-            if final_model is None:
-                final_model = _create_dynamic_model(func)
-                unpack_args = True
-
-            self._builtin_function_provider.register(
-                name=name,
-                func=func,
-                description=description,
-                params_model=final_model,
-                unpack_args=unpack_args,
-            )
-            logger.info(f"已注册函数工具: '{name}'")
-            return func
-
-        return decorator
-
-    async def initialize(self) -> None:
-        """懒加载初始化所有已注册的 ToolProvider。"""
-        if not self._init_promise:
-            async with self._init_lock:
-                if not self._init_promise:
-                    self._init_promise = asyncio.create_task(
-                        self._initialize_providers()
-                    )
-        await self._init_promise
-
-    async def _initialize_providers(self) -> None:
-        """内部初始化逻辑。"""
-        logger.info(f"开始初始化 {len(self._providers)} 个工具提供者...")
-        init_tasks = [provider.initialize() for provider in self._providers]
-        await asyncio.gather(*init_tasks, return_exceptions=True)
-        logger.info("所有工具提供者初始化完成。")
-
-    async def get_resolved_tools(
-        self,
-        allowed_servers: list[str] | None = None,
-        excluded_servers: list[str] | None = None,
-    ) -> dict[str, ToolExecutable]:
-        """
-        获取所有已发现和解析的工具。
-        此方法会触发懒加载初始化，并根据是否传入过滤器来决定是否使用全局缓存。
-        """
-        await self.initialize()
-
-        has_filters = allowed_servers is not None or excluded_servers is not None
-
-        if not has_filters and self._resolved_tools is not None:
-            logger.debug("使用全局工具缓存。")
-            return self._resolved_tools
-
-        if has_filters:
-            logger.info("检测到过滤器，执行临时工具发现 (不使用缓存)。")
-            logger.debug(
-                f"过滤器详情: allowed_servers={allowed_servers}, "
-                f"excluded_servers={excluded_servers}"
-            )
-        else:
-            logger.info("未应用过滤器，开始全局工具发现...")
-
-        all_tools: dict[str, ToolExecutable] = {}
-
-        discover_tasks = []
-        for provider in self._providers:
-            sig = inspect.signature(provider.discover_tools)
-            params_to_pass = {}
-            if "allowed_servers" in sig.parameters:
-                params_to_pass["allowed_servers"] = allowed_servers
-            if "excluded_servers" in sig.parameters:
-                params_to_pass["excluded_servers"] = excluded_servers
-
-            discover_tasks.append(provider.discover_tools(**params_to_pass))
-
-        results = await asyncio.gather(*discover_tasks, return_exceptions=True)
-
-        for i, provider_result in enumerate(results):
-            provider_name = self._providers[i].__class__.__name__
-            if isinstance(provider_result, dict):
-                logger.debug(
-                    f"提供者 '{provider_name}' 发现了 {len(provider_result)} 个工具。"
-                )
-                for name, executable in provider_result.items():
-                    if name in all_tools:
-                        logger.warning(
-                            f"发现重复的工具名称 '{name}'，后发现的将覆盖前者。"
-                        )
-                    all_tools[name] = executable
-            elif isinstance(provider_result, Exception):
-                logger.error(
-                    f"提供者 '{provider_name}' 在发现工具时出错: {provider_result}"
-                )
-
-        if not has_filters:
-            self._resolved_tools = all_tools
-            logger.info(f"全局工具发现完成，共找到并缓存了 {len(all_tools)} 个工具。")
-        else:
-            logger.info(f"带过滤器的工具发现完成，共找到 {len(all_tools)} 个工具。")
-
-        return all_tools
-
-    async def resolve_specific_tools(
-        self, tool_names: list[str]
-    ) -> dict[str, ToolExecutable]:
-        """
-        仅解析指定名称的工具，避免触发全量工具发现。
-        """
-        resolved: dict[str, ToolExecutable] = {}
-        if not tool_names:
-            return resolved
-
-        await self.initialize()
-
-        for name in tool_names:
-            config: dict[str, Any] = {"name": name}
-            for provider in self._providers:
-                try:
-                    executable = await provider.get_tool_executable(name, config)
-                except Exception as exc:
-                    logger.error(
-                        f"provider '{provider.__class__.__name__}' 在解析工具 '{name}'"
-                        f"时出错: {exc}",
-                        e=exc,
-                    )
-                    continue
-
-                if executable:
-                    resolved[name] = executable
-                    break
-            else:
-                logger.warning(f"没有找到名为 '{name}' 的工具，已跳过。")
-
-        return resolved
-
-    async def get_function_tools(
-        self, names: list[str] | None = None
-    ) -> dict[str, ToolExecutable]:
-        """
-        仅从内置的函数提供者中解析指定的工具。
-        """
-        all_function_tools = await self._builtin_function_provider.discover_tools()
-        if names is None:
-            return all_function_tools
-
-        resolved_tools = {}
-        for name in names:
-            if name in all_function_tools:
-                resolved_tools[name] = all_function_tools[name]
-            else:
-                logger.warning(
-                    f"本地函数工具 '{name}' 未通过 @function_tool 注册，将被忽略。"
-                )
-        return resolved_tools
-
-
-tool_provider_manager = ToolProviderManager()
-function_tool = tool_provider_manager.function_tool
-
-
-class ToolErrorType(str, Enum):
-    """结构化工具错误的类型枚举。"""
-
-    TOOL_NOT_FOUND = "ToolNotFound"
-    INVALID_ARGUMENTS = "InvalidArguments"
-    EXECUTION_ERROR = "ExecutionError"
-    USER_CANCELLATION = "UserCancellation"
-
-
-class ToolErrorResult(BaseModel):
-    """一个结构化的工具执行错误模型。"""
-
-    error_type: ToolErrorType = Field(..., description="错误的类型。")
-    message: str = Field(..., description="对错误的详细描述。")
-    is_retryable: bool = Field(False, description="指示这个错误是否可能通过重试解决。")
-
-
-class ToolInvoker:
-    """
-    全能工具执行器。
-    负责接收工具调用请求，解析参数，触发回调，执行工具，并返回标准化的结果。
-    """
-
-    def __init__(self, callbacks: list[BaseCallbackHandler] | None = None):
-        self.callbacks = callbacks or []
-
-    async def _trigger_callbacks(self, event_name: str, *args, **kwargs: Any) -> None:
-        if not self.callbacks:
-            return
-        tasks = [
-            getattr(handler, event_name)(*args, **kwargs)
-            for handler in self.callbacks
-            if hasattr(handler, event_name)
-        ]
-        await asyncio.gather(*tasks, return_exceptions=True)
-
-    async def execute_tool_call(
-        self,
-        tool_call: LLMToolCall,
-        available_tools: dict[str, ToolExecutable],
-        context: Any | None = None,
-    ) -> tuple[LLMToolCall, ToolResult]:
-        tool_name = tool_call.function.name
-        arguments_str = tool_call.function.arguments
-        arguments: dict[str, Any] = {}
-
-        try:
-            if arguments_str:
-                arguments = json.loads(arguments_str)
-        except json.JSONDecodeError as e:
-            error_result = ToolErrorResult(
-                error_type=ToolErrorType.INVALID_ARGUMENTS,
-                message=f"参数解析失败: {e}",
-                is_retryable=False,
-            )
-            return tool_call, ToolResult(output=model_dump(error_result))
-
-        tool_data = ToolCallData(tool_name=tool_name, tool_args=arguments)
-        pre_calculated_result: ToolResult | None = None
-        for handler in self.callbacks:
-            res = await handler.on_tool_start(tool_call, tool_data)
-            if isinstance(res, ToolCallData):
-                tool_data = res
-                arguments = tool_data.tool_args
-                tool_call.function.arguments = json.dumps(arguments, ensure_ascii=False)
-            elif isinstance(res, ToolResult):
-                pre_calculated_result = res
-                break
-
-        if pre_calculated_result:
-            return tool_call, pre_calculated_result
-
-        executable = available_tools.get(tool_name)
-        if not executable:
-            error_result = ToolErrorResult(
-                error_type=ToolErrorType.TOOL_NOT_FOUND,
-                message=f"Tool '{tool_name}' not found.",
-                is_retryable=False,
-            )
-            return tool_call, ToolResult(output=model_dump(error_result))
-
-        from .config.providers import get_llm_config
-
-        if not get_llm_config().debug_log:
-            try:
-                definition = await executable.get_definition()
-                schema_payload = getattr(definition, "parameters", {})
-                schema_json = fast_json.dumps(
-                    schema_payload,
-                    ensure_ascii=False,
-                )
-                logger.debug(
-                    f"🔍 [JIT Schema] {tool_name}: {schema_json}",
-                    "ToolInvoker",
-                )
-            except Exception as e:
-                logger.trace(f"JIT Schema logging failed: {e}")
-
-        start_t = time.monotonic()
-        result: ToolResult | None = None
-        error: Exception | None = None
-
-        try:
-
-            @Retry.simple(stop_max_attempt=2, wait_fixed_seconds=1)
-            async def execute_with_retry():
-                return await executable.execute(context=context, **arguments)
-
-            result = await execute_with_retry()
-        except ValidationError as e:
-            error = e
-            error_msgs = []
-            for err in e.errors():
-                loc = ".".join(str(x) for x in err["loc"])
-                msg = err["msg"]
-                error_msgs.append(f"参数 '{loc}': {msg}")
-
-            formatted_error = "; ".join(error_msgs)
-            error_result = ToolErrorResult(
-                error_type=ToolErrorType.INVALID_ARGUMENTS,
-                message=f"参数验证失败。请根据错误修正你的输入: {formatted_error}",
-                is_retryable=True,
-            )
-            result = ToolResult(output=model_dump(error_result))
-        except (TimeoutException, NetworkError) as e:
-            error = e
-            error_result = ToolErrorResult(
-                error_type=ToolErrorType.EXECUTION_ERROR,
-                message=f"工具执行网络超时或连接失败: {e!s}",
-                is_retryable=False,
-            )
-            result = ToolResult(output=model_dump(error_result))
-        except Exception as e:
-            error = e
-            error_type = ToolErrorType.EXECUTION_ERROR
-            if (
-                isinstance(e, LLMException)
-                and e.code == LLMErrorCode.CONFIGURATION_ERROR
-            ):
-                error_type = ToolErrorType.TOOL_NOT_FOUND
-                is_retryable = False
-
-            is_retryable = False
-
-            error_result = ToolErrorResult(
-                error_type=error_type, message=str(e), is_retryable=is_retryable
-            )
-            result = ToolResult(output=model_dump(error_result))
-
-        duration = time.monotonic() - start_t
-
-        await self._trigger_callbacks(
-            "on_tool_end",
-            result=result,
-            error=error,
-            tool_call=tool_call,
-            duration=duration,
-        )
-
-        if result is None:
-            raise LLMException("工具执行未返回任何结果。")
-
-        return tool_call, result
-
-    async def execute_batch(
-        self,
-        tool_calls: list[LLMToolCall],
-        available_tools: dict[str, ToolExecutable],
-        context: Any | None = None,
-    ) -> list[LLMMessage]:
-        if not tool_calls:
-            return []
-
-        tasks = [
-            self.execute_tool_call(call, available_tools, context)
-            for call in tool_calls
-        ]
-        results = await asyncio.gather(*tasks, return_exceptions=True)
-
-        tool_messages: list[LLMMessage] = []
-        for index, result_pair in enumerate(results):
-            original_call = tool_calls[index]
-
-            if isinstance(result_pair, Exception):
-                logger.error(
-                    f"工具执行发生未捕获异常: {original_call.function.name}, "
-                    f"错误: {result_pair}"
-                )
-                tool_messages.append(
-                    LLMMessage.tool_response(
-                        tool_call_id=original_call.id,
-                        function_name=original_call.function.name,
-                        result={
-                            "error": f"System Execution Error: {result_pair}",
-                            "status": "failed",
-                        },
-                    )
-                )
-                continue
-
-            tool_call_result = cast(tuple[LLMToolCall, ToolResult], result_pair)
-            _, tool_result = tool_call_result
-            tool_messages.append(
-                LLMMessage.tool_response(
-                    tool_call_id=original_call.id,
-                    function_name=original_call.function.name,
-                    result=tool_result.output,
-                )
-            )
-        return tool_messages
-
-
-__all__ = [
-    "RunContext",
-    "RunContextParam",
-    "ToolErrorResult",
-    "ToolErrorType",
-    "ToolInvoker",
-    "ToolParam",
-    "function_tool",
-    "tool_provider_manager",
-]

zhenxun/services/llm/tools/__init__.py

@@ -0,0 +1,13 @@
+"""
+工具模块导出
+"""
+
+from .manager import tool_provider_manager
+
+function_tool = tool_provider_manager.function_tool
+
+
+__all__ = [
+    "function_tool",
+    "tool_provider_manager",
+]

zhenxun/services/llm/tools/manager.py

@@ -0,0 +1,293 @@
+"""
+工具提供者管理器
+
+负责注册、生命周期管理（包括懒加载）和统一提供所有工具。
+"""
+
+import asyncio
+from collections.abc import Callable
+import inspect
+from typing import Any
+
+from pydantic import BaseModel
+
+from zhenxun.services.log import logger
+from zhenxun.utils.pydantic_compat import model_json_schema
+
+from ..types import ToolExecutable, ToolProvider
+from ..types.models import ToolDefinition, ToolResult
+
+
+class FunctionExecutable(ToolExecutable):
+    """一个 ToolExecutable 的实现，用于包装一个普通的 Python 函数。"""
+
+    def __init__(
+        self,
+        func: Callable,
+        name: str,
+        description: str,
+        params_model: type[BaseModel] | None,
+    ):
+        self._func = func
+        self._name = name
+        self._description = description
+        self._params_model = params_model
+
+    async def get_definition(self) -> ToolDefinition:
+        if not self._params_model:
+            return ToolDefinition(
+                name=self._name,
+                description=self._description,
+                parameters={"type": "object", "properties": {}},
+            )
+
+        schema = model_json_schema(self._params_model)
+
+        return ToolDefinition(
+            name=self._name,
+            description=self._description,
+            parameters={
+                "type": "object",
+                "properties": schema.get("properties", {}),
+                "required": schema.get("required", []),
+            },
+        )
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        raw_result: Any
+
+        if self._params_model:
+            try:
+                params_instance = self._params_model(**kwargs)
+
+                if inspect.iscoroutinefunction(self._func):
+                    raw_result = await self._func(params_instance)
+                else:
+                    loop = asyncio.get_event_loop()
+                    raw_result = await loop.run_in_executor(
+                        None, lambda: self._func(params_instance)
+                    )
+            except Exception as e:
+                logger.error(
+                    f"执行工具 '{self._name}' 时参数验证或实例化失败: {e}", e=e
+                )
+                raise
+        else:
+            if inspect.iscoroutinefunction(self._func):
+                raw_result = await self._func(**kwargs)
+            else:
+                loop = asyncio.get_event_loop()
+                raw_result = await loop.run_in_executor(
+                    None, lambda: self._func(**kwargs)
+                )
+
+        return ToolResult(output=raw_result, display_content=str(raw_result))
+
+
+class BuiltinFunctionToolProvider(ToolProvider):
+    """一个内置的 ToolProvider，用于处理通过装饰器注册的函数。"""
+
+    def __init__(self):
+        self._functions: dict[str, dict[str, Any]] = {}
+
+    def register(
+        self,
+        name: str,
+        func: Callable,
+        description: str,
+        params_model: type[BaseModel] | None,
+    ):
+        self._functions[name] = {
+            "func": func,
+            "description": description,
+            "params_model": params_model,
+        }
+
+    async def initialize(self) -> None:
+        pass
+
+    async def discover_tools(
+        self,
+        allowed_servers: list[str] | None = None,
+        excluded_servers: list[str] | None = None,
+    ) -> dict[str, ToolExecutable]:
+        executables = {}
+        for name, info in self._functions.items():
+            executables[name] = FunctionExecutable(
+                func=info["func"],
+                name=name,
+                description=info["description"],
+                params_model=info["params_model"],
+            )
+        return executables
+
+    async def get_tool_executable(
+        self, name: str, config: dict[str, Any]
+    ) -> ToolExecutable | None:
+        if config.get("type") == "function" and name in self._functions:
+            info = self._functions[name]
+            return FunctionExecutable(
+                func=info["func"],
+                name=name,
+                description=info["description"],
+                params_model=info["params_model"],
+            )
+        return None
+
+
+class ToolProviderManager:
+    """工具提供者的中心化管理器，采用单例模式。"""
+
+    _instance: "ToolProviderManager | None" = None
+
+    def __new__(cls) -> "ToolProviderManager":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        if hasattr(self, "_initialized") and self._initialized:
+            return
+
+        self._providers: list[ToolProvider] = []
+        self._resolved_tools: dict[str, ToolExecutable] | None = None
+        self._init_lock = asyncio.Lock()
+        self._init_promise: asyncio.Task | None = None
+        self._builtin_function_provider = BuiltinFunctionToolProvider()
+        self.register(self._builtin_function_provider)
+        self._initialized = True
+
+    def register(self, provider: ToolProvider):
+        """注册一个新的 ToolProvider。"""
+        if provider not in self._providers:
+            self._providers.append(provider)
+            logger.info(f"已注册工具提供者: {provider.__class__.__name__}")
+
+    def function_tool(
+        self,
+        name: str,
+        description: str,
+        params_model: type[BaseModel] | None = None,
+    ):
+        """装饰器：将一个函数注册为内置工具。"""
+
+        def decorator(func: Callable):
+            if name in self._builtin_function_provider._functions:
+                logger.warning(f"正在覆盖已注册的函数工具: {name}")
+
+            self._builtin_function_provider.register(
+                name=name,
+                func=func,
+                description=description,
+                params_model=params_model,
+            )
+            logger.info(f"已注册函数工具: '{name}'")
+            return func
+
+        return decorator
+
+    async def initialize(self) -> None:
+        """懒加载初始化所有已注册的 ToolProvider。"""
+        if not self._init_promise:
+            async with self._init_lock:
+                if not self._init_promise:
+                    self._init_promise = asyncio.create_task(
+                        self._initialize_providers()
+                    )
+        await self._init_promise
+
+    async def _initialize_providers(self) -> None:
+        """内部初始化逻辑。"""
+        logger.info(f"开始初始化 {len(self._providers)} 个工具提供者...")
+        init_tasks = [provider.initialize() for provider in self._providers]
+        await asyncio.gather(*init_tasks, return_exceptions=True)
+        logger.info("所有工具提供者初始化完成。")
+
+    async def get_resolved_tools(
+        self,
+        allowed_servers: list[str] | None = None,
+        excluded_servers: list[str] | None = None,
+    ) -> dict[str, ToolExecutable]:
+        """
+        获取所有已发现和解析的工具。
+        此方法会触发懒加载初始化，并根据是否传入过滤器来决定是否使用全局缓存。
+        """
+        await self.initialize()
+
+        has_filters = allowed_servers is not None or excluded_servers is not None
+
+        if not has_filters and self._resolved_tools is not None:
+            logger.debug("使用全局工具缓存。")
+            return self._resolved_tools
+
+        if has_filters:
+            logger.info("检测到过滤器，执行临时工具发现 (不使用缓存)。")
+            logger.debug(
+                f"过滤器详情: allowed_servers={allowed_servers}, "
+                f"excluded_servers={excluded_servers}"
+            )
+        else:
+            logger.info("未应用过滤器，开始全局工具发现...")
+
+        all_tools: dict[str, ToolExecutable] = {}
+
+        discover_tasks = []
+        for provider in self._providers:
+            sig = inspect.signature(provider.discover_tools)
+            params_to_pass = {}
+            if "allowed_servers" in sig.parameters:
+                params_to_pass["allowed_servers"] = allowed_servers
+            if "excluded_servers" in sig.parameters:
+                params_to_pass["excluded_servers"] = excluded_servers
+
+            discover_tasks.append(provider.discover_tools(**params_to_pass))
+
+        results = await asyncio.gather(*discover_tasks, return_exceptions=True)
+
+        for i, provider_result in enumerate(results):
+            provider_name = self._providers[i].__class__.__name__
+            if isinstance(provider_result, dict):
+                logger.debug(
+                    f"提供者 '{provider_name}' 发现了 {len(provider_result)} 个工具。"
+                )
+                for name, executable in provider_result.items():
+                    if name in all_tools:
+                        logger.warning(
+                            f"发现重复的工具名称 '{name}'，后发现的将覆盖前者。"
+                        )
+                    all_tools[name] = executable
+            elif isinstance(provider_result, Exception):
+                logger.error(
+                    f"提供者 '{provider_name}' 在发现工具时出错: {provider_result}"
+                )
+
+        if not has_filters:
+            self._resolved_tools = all_tools
+            logger.info(f"全局工具发现完成，共找到并缓存了 {len(all_tools)} 个工具。")
+        else:
+            logger.info(f"带过滤器的工具发现完成，共找到 {len(all_tools)} 个工具。")
+
+        return all_tools
+
+    async def get_function_tools(
+        self, names: list[str] | None = None
+    ) -> dict[str, ToolExecutable]:
+        """
+        仅从内置的函数提供者中解析指定的工具。
+        """
+        all_function_tools = await self._builtin_function_provider.discover_tools()
+        if names is None:
+            return all_function_tools
+
+        resolved_tools = {}
+        for name in names:
+            if name in all_function_tools:
+                resolved_tools[name] = all_function_tools[name]
+            else:
+                logger.warning(
+                    f"本地函数工具 '{name}' 未通过 @function_tool 注册，将被忽略。"
+                )
+        return resolved_tools
+
+
+tool_provider_manager = ToolProviderManager()

zhenxun/services/llm/types/__init__.py

@@ -5,32 +5,30 @@ LLM 类型定义模块
 """
 
 from .capabilities import ModelCapabilities, ModelModality, get_model_capabilities
-from .exceptions import LLMErrorCode, LLMException, get_user_friendly_error_message
+from .content import (
-from .models import (
-    CodeExecutionOutcome,
-    EmbeddingTaskType,
-    GeminiCodeExecution,
-    GeminiGoogleSearch,
-    GeminiUrlContext,
-    LLMCacheInfo,
-    LLMCodeExecution,
     LLMContentPart,
-    LLMGroundingAttribution,
-    LLMGroundingMetadata,
     LLMMessage,
     LLMResponse,
+)
+from .enums import (
+    EmbeddingTaskType,
+    ModelProvider,
+    ResponseFormat,
+    TaskType,
+    ToolCategory,
+)
+from .exceptions import LLMErrorCode, LLMException, get_user_friendly_error_message
+from .models import (
+    LLMCacheInfo,
+    LLMCodeExecution,
+    LLMGroundingAttribution,
+    LLMGroundingMetadata,
     LLMToolCall,
     LLMToolFunction,
     ModelDetail,
     ModelInfo,
     ModelName,
-    ModelProvider,
     ProviderConfig,
-    ResponseFormat,
-    StructuredOutputStrategy,
-    TaskType,
-    ToolCategory,
-    ToolChoice,
     ToolMetadata,
     ToolResult,
     UsageInfo,
@@ -38,11 +36,7 @@ from .models import (
 from .protocols import ToolExecutable, ToolProvider
 
 __all__ = [
-    "CodeExecutionOutcome",
     "EmbeddingTaskType",
-    "GeminiCodeExecution",
-    "GeminiGoogleSearch",
-    "GeminiUrlContext",
     "LLMCacheInfo",
     "LLMCodeExecution",
     "LLMContentPart",
@@ -62,10 +56,8 @@ __all__ = [
     "ModelProvider",
     "ProviderConfig",
     "ResponseFormat",
-    "StructuredOutputStrategy",
     "TaskType",
     "ToolCategory",
-    "ToolChoice",
     "ToolExecutable",
     "ToolMetadata",
     "ToolProvider",

zhenxun/services/llm/types/capabilities.py

@@ -6,7 +6,6 @@ LLM 模型能力定义模块
 
 from enum import Enum
 import fnmatch
-from typing import Literal
 
 from pydantic import BaseModel, Field
 
@@ -21,35 +20,6 @@ class ModelModality(str, Enum):
     EMBEDDING = "embedding"
 
 
-class ReasoningMode(str, Enum):
-    """推理/思考模式类型"""
-
-    NONE = "none"
-    BUDGET = "budget"
-    LEVEL = "level"
-    EFFORT = "effort"
-
-
-PATTERNS_GEMINI_2_5 = [
-    "gemini-2.5*",
-    "gemini-flash*",
-    "gemini*lite*",
-    "gemini-flash-latest",
-]
-
-PATTERNS_GEMINI_3 = [
-    "gemini-3*",
-    "gemini-exp*",
-]
-
-PATTERNS_OPENAI_REASONING = [
-    "o1-*",
-    "o3-*",
-    "deepseek-r1*",
-    "deepseek-reasoner",
-]
-
-
 class ModelCapabilities(BaseModel):
     """定义一个模型的核心、稳定能力。"""
 
@@ -57,8 +27,6 @@ class ModelCapabilities(BaseModel):
     output_modalities: set[ModelModality] = Field(default={ModelModality.TEXT})
     supports_tool_calling: bool = False
     is_embedding_model: bool = False
-    reasoning_mode: ReasoningMode = ReasoningMode.NONE
-    reasoning_visibility: Literal["visible", "hidden", "none"] = "none"
 
 
 STANDARD_TEXT_TOOL_CAPABILITIES = ModelCapabilities(
@@ -67,7 +35,7 @@ STANDARD_TEXT_TOOL_CAPABILITIES = ModelCapabilities(
     supports_tool_calling=True,
 )
 
-CAP_GEMINI_2_5 = ModelCapabilities(
+GEMINI_CAPABILITIES = ModelCapabilities(
     input_modalities={
         ModelModality.TEXT,
         ModelModality.IMAGE,
@@ -76,44 +44,21 @@ CAP_GEMINI_2_5 = ModelCapabilities(
     },
     output_modalities={ModelModality.TEXT},
     supports_tool_calling=True,
-    reasoning_mode=ReasoningMode.BUDGET,
-    reasoning_visibility="visible",
 )
 
-CAP_GEMINI_3 = ModelCapabilities(
+GEMINI_IMAGE_GEN_CAPABILITIES = ModelCapabilities(
-    input_modalities={
-        ModelModality.TEXT,
-        ModelModality.IMAGE,
-        ModelModality.AUDIO,
-        ModelModality.VIDEO,
-    },
-    output_modalities={ModelModality.TEXT},
-    supports_tool_calling=True,
-    reasoning_mode=ReasoningMode.LEVEL,
-    reasoning_visibility="visible",
-)
-
-CAP_GEMINI_IMAGE_GEN = ModelCapabilities(
     input_modalities={ModelModality.TEXT, ModelModality.IMAGE},
     output_modalities={ModelModality.TEXT, ModelModality.IMAGE},
     supports_tool_calling=True,
 )
 
-CAP_OPENAI_REASONING = ModelCapabilities(
+GPT_ADVANCED_TEXT_IMAGE_CAPABILITIES = ModelCapabilities(
-    input_modalities={ModelModality.TEXT, ModelModality.IMAGE},
-    output_modalities={ModelModality.TEXT},
-    supports_tool_calling=True,
-    reasoning_mode=ReasoningMode.EFFORT,
-    reasoning_visibility="hidden",
-)
-
-CAP_GPT_ADVANCED = ModelCapabilities(
     input_modalities={ModelModality.TEXT, ModelModality.IMAGE},
     output_modalities={ModelModality.TEXT},
     supports_tool_calling=True,
 )
 
-CAP_GPT_MULTIMODAL_IO = ModelCapabilities(
+GPT_MULTIMODAL_IO_CAPABILITIES = ModelCapabilities(
     input_modalities={ModelModality.TEXT, ModelModality.AUDIO, ModelModality.IMAGE},
     output_modalities={ModelModality.TEXT, ModelModality.AUDIO},
     supports_tool_calling=True,
@@ -131,12 +76,6 @@ GPT_VIDEO_GENERATION_CAPABILITIES = ModelCapabilities(
     supports_tool_calling=True,
 )
 
-EMBEDDING_CAPABILITIES = ModelCapabilities(
-    input_modalities={ModelModality.TEXT},
-    output_modalities={ModelModality.EMBEDDING},
-    is_embedding_model=True,
-)
-
 DEFAULT_PERMISSIVE_CAPABILITIES = ModelCapabilities(
     input_modalities={
         ModelModality.TEXT,
@@ -168,33 +107,17 @@ MODEL_ALIAS_MAPPING: dict[str, str] = {
 }
 
 
-def _build_registry() -> dict[str, ModelCapabilities]:
+MODEL_CAPABILITIES_REGISTRY: dict[str, ModelCapabilities] = {
-    """构建模型能力注册表，展开模式列表以减少冗余"""
+    "gemini-*-tts": ModelCapabilities(
-    registry: dict[str, ModelCapabilities] = {}
-
-    def register_family(patterns: list[str], cap: ModelCapabilities) -> None:
-        for pattern in patterns:
-            registry[pattern] = cap
-
-    register_family(
-        ["*gemini-*-image-preview*", "gemini-*-image*"], CAP_GEMINI_IMAGE_GEN
-    )
-
-    register_family(PATTERNS_GEMINI_2_5, CAP_GEMINI_2_5)
-    register_family(PATTERNS_GEMINI_3, CAP_GEMINI_3)
-
-    register_family(PATTERNS_OPENAI_REASONING, CAP_OPENAI_REASONING)
-
-    registry["gemini-*-tts"] = ModelCapabilities(
         input_modalities={ModelModality.TEXT},
         output_modalities={ModelModality.AUDIO},
-    )
+    ),
-    registry["gemini-*-native-audio-*"] = ModelCapabilities(
+    "gemini-*-native-audio-*": ModelCapabilities(
         input_modalities={ModelModality.TEXT, ModelModality.AUDIO, ModelModality.VIDEO},
         output_modalities={ModelModality.TEXT, ModelModality.AUDIO},
         supports_tool_calling=True,
-    )
+    ),
-    registry["gemini-2.0-flash-preview-image-generation"] = ModelCapabilities(
+    "gemini-2.0-flash-preview-image-generation": ModelCapabilities(
         input_modalities={
             ModelModality.TEXT,
             ModelModality.IMAGE,
@@ -203,39 +126,39 @@ def _build_registry() -> dict[str, ModelCapabilities]:
         },
         output_modalities={ModelModality.TEXT, ModelModality.IMAGE},
         supports_tool_calling=True,
-    )
+    ),
-
+    "gemini-embedding-exp": ModelCapabilities(
-    registry["GLM-4V-Flash"] = ModelCapabilities(
+        input_modalities={ModelModality.TEXT},
+        output_modalities={ModelModality.EMBEDDING},
+        is_embedding_model=True,
+    ),
+    "*gemini-*-image-preview*": GEMINI_IMAGE_GEN_CAPABILITIES,
+    "gemini-*-pro*": GEMINI_CAPABILITIES,
+    "gemini-*-flash*": GEMINI_CAPABILITIES,
+    "GLM-4V-Flash": ModelCapabilities(
         input_modalities={ModelModality.TEXT, ModelModality.IMAGE},
         output_modalities={ModelModality.TEXT},
         supports_tool_calling=True,
-    )
+    ),
-    registry["GLM-4V-Plus*"] = ModelCapabilities(
+    "GLM-4V-Plus*": ModelCapabilities(
         input_modalities={ModelModality.TEXT, ModelModality.IMAGE, ModelModality.VIDEO},
         output_modalities={ModelModality.TEXT},
         supports_tool_calling=True,
-    )
+    ),
-
+    "glm-4-*": STANDARD_TEXT_TOOL_CAPABILITIES,
-    register_family(
+    "glm-z1-*": STANDARD_TEXT_TOOL_CAPABILITIES,
-        ["glm-4-*", "glm-z1-*", "deepseek-chat"], STANDARD_TEXT_TOOL_CAPABILITIES
+    "doubao-seed-*": DOUBAO_ADVANCED_MULTIMODAL_CAPABILITIES,
-    )
+    "doubao-1-5-thinking-vision-pro": DOUBAO_ADVANCED_MULTIMODAL_CAPABILITIES,
-    register_family(
+    "deepseek-chat": STANDARD_TEXT_TOOL_CAPABILITIES,
-        ["doubao-seed-*", "doubao-1-5-thinking-vision-pro"],
+    "deepseek-reasoner": STANDARD_TEXT_TOOL_CAPABILITIES,
-        DOUBAO_ADVANCED_MULTIMODAL_CAPABILITIES,
+    "gpt-5*": GPT_ADVANCED_TEXT_IMAGE_CAPABILITIES,
-    )
+    "gpt-4.1*": GPT_ADVANCED_TEXT_IMAGE_CAPABILITIES,
-
+    "gpt-4o*": GPT_MULTIMODAL_IO_CAPABILITIES,
-    register_family(["gpt-5*", "gpt-4.1*", "o4-mini*"], CAP_GPT_ADVANCED)
+    "o3*": GPT_ADVANCED_TEXT_IMAGE_CAPABILITIES,
-    registry["gpt-4o*"] = CAP_GPT_MULTIMODAL_IO
+    "o4-mini*": GPT_ADVANCED_TEXT_IMAGE_CAPABILITIES,
-
+    "gpt image*": GPT_IMAGE_GENERATION_CAPABILITIES,
-    registry["gpt image*"] = GPT_IMAGE_GENERATION_CAPABILITIES
+    "sora*": GPT_VIDEO_GENERATION_CAPABILITIES,
-    registry["sora*"] = GPT_VIDEO_GENERATION_CAPABILITIES
+}
-
-    registry["*embedding*"] = EMBEDDING_CAPABILITIES
-
-    return registry
-
-
-MODEL_CAPABILITIES_REGISTRY = _build_registry()
 
 
 def get_model_capabilities(model_name: str) -> ModelCapabilities:

zhenxun/services/llm/types/content.py

@@ -0,0 +1,434 @@
+"""
+LLM 内容类型定义
+
+包含多模态内容部分、消息和响应的数据模型。
+"""
+
+import base64
+import mimetypes
+from pathlib import Path
+from typing import Any
+
+import aiofiles
+from pydantic import BaseModel
+
+from zhenxun.services.log import logger
+
+
+class LLMContentPart(BaseModel):
+    """LLM 消息内容部分 - 支持多模态内容"""
+
+    type: str
+    text: str | None = None
+    image_source: str | None = None
+    audio_source: str | None = None
+    video_source: str | None = None
+    document_source: str | None = None
+    file_uri: str | None = None
+    file_source: str | None = None
+    url: str | None = None
+    mime_type: str | None = None
+    metadata: dict[str, Any] | None = None
+
+    def model_post_init(self, /, __context: Any) -> None:
+        """验证内容部分的有效性"""
+        _ = __context
+        validation_rules = {
+            "text": lambda: self.text,
+            "image": lambda: self.image_source,
+            "audio": lambda: self.audio_source,
+            "video": lambda: self.video_source,
+            "document": lambda: self.document_source,
+            "file": lambda: self.file_uri or self.file_source,
+            "url": lambda: self.url,
+        }
+
+        if self.type in validation_rules:
+            if not validation_rules[self.type]():
+                raise ValueError(f"{self.type}类型的内容部分必须包含相应字段")
+
+    @classmethod
+    def text_part(cls, text: str) -> "LLMContentPart":
+        """创建文本内容部分"""
+        return cls(type="text", text=text)
+
+    @classmethod
+    def image_url_part(cls, url: str) -> "LLMContentPart":
+        """创建图片URL内容部分"""
+        return cls(type="image", image_source=url)
+
+    @classmethod
+    def image_base64_part(
+        cls, data: str, mime_type: str = "image/png"
+    ) -> "LLMContentPart":
+        """创建Base64图片内容部分"""
+        data_url = f"data:{mime_type};base64,{data}"
+        return cls(type="image", image_source=data_url)
+
+    @classmethod
+    def audio_url_part(cls, url: str, mime_type: str = "audio/wav") -> "LLMContentPart":
+        """创建音频URL内容部分"""
+        return cls(type="audio", audio_source=url, mime_type=mime_type)
+
+    @classmethod
+    def video_url_part(cls, url: str, mime_type: str = "video/mp4") -> "LLMContentPart":
+        """创建视频URL内容部分"""
+        return cls(type="video", video_source=url, mime_type=mime_type)
+
+    @classmethod
+    def video_base64_part(
+        cls, data: str, mime_type: str = "video/mp4"
+    ) -> "LLMContentPart":
+        """创建Base64视频内容部分"""
+        data_url = f"data:{mime_type};base64,{data}"
+        return cls(type="video", video_source=data_url, mime_type=mime_type)
+
+    @classmethod
+    def audio_base64_part(
+        cls, data: str, mime_type: str = "audio/wav"
+    ) -> "LLMContentPart":
+        """创建Base64音频内容部分"""
+        data_url = f"data:{mime_type};base64,{data}"
+        return cls(type="audio", audio_source=data_url, mime_type=mime_type)
+
+    @classmethod
+    def file_uri_part(
+        cls,
+        file_uri: str,
+        mime_type: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> "LLMContentPart":
+        """创建Gemini File API URI内容部分"""
+        return cls(
+            type="file",
+            file_uri=file_uri,
+            mime_type=mime_type,
+            metadata=metadata or {},
+        )
+
+    @classmethod
+    async def from_path(
+        cls, path_like: str | Path, target_api: str | None = None
+    ) -> "LLMContentPart | None":
+        """
+        从本地文件路径创建 LLMContentPart。
+        自动检测MIME类型，并根据类型（如图片）可能加载为Base64。
+        target_api 可以用于提示如何最好地准备数据（例如 'gemini' 可能偏好 base64）
+        """
+        try:
+            path = Path(path_like)
+            if not path.exists() or not path.is_file():
+                logger.warning(f"文件不存在或不是一个文件: {path}")
+                return None
+
+            mime_type, _ = mimetypes.guess_type(path.resolve().as_uri())
+
+            if not mime_type:
+                logger.warning(
+                    f"无法猜测文件 {path.name} 的MIME类型，将尝试作为文本文件处理。"
+                )
+                try:
+                    async with aiofiles.open(path, encoding="utf-8") as f:
+                        text_content = await f.read()
+                    return cls.text_part(text_content)
+                except Exception as e:
+                    logger.error(f"读取文本文件 {path.name} 失败: {e}")
+                    return None
+
+            if mime_type.startswith("image/"):
+                if target_api == "gemini" or not path.is_absolute():
+                    try:
+                        async with aiofiles.open(path, "rb") as f:
+                            img_bytes = await f.read()
+                        base64_data = base64.b64encode(img_bytes).decode("utf-8")
+                        return cls.image_base64_part(
+                            data=base64_data, mime_type=mime_type
+                        )
+                    except Exception as e:
+                        logger.error(f"读取或编码图片文件 {path.name} 失败: {e}")
+                        return None
+                else:
+                    logger.warning(
+                        f"为本地图片路径 {path.name} 生成 image_url_part。"
+                        "实际API可能不支持 file:// URI。考虑使用Base64或公网URL。"
+                    )
+                    return cls.image_url_part(url=path.resolve().as_uri())
+            elif mime_type.startswith("audio/"):
+                return cls.audio_url_part(
+                    url=path.resolve().as_uri(), mime_type=mime_type
+                )
+            elif mime_type.startswith("video/"):
+                if target_api == "gemini":
+                    # 对于 Gemini API，将视频转换为 base64
+                    try:
+                        async with aiofiles.open(path, "rb") as f:
+                            video_bytes = await f.read()
+                        base64_data = base64.b64encode(video_bytes).decode("utf-8")
+                        return cls.video_base64_part(
+                            data=base64_data, mime_type=mime_type
+                        )
+                    except Exception as e:
+                        logger.error(f"读取或编码视频文件 {path.name} 失败: {e}")
+                        return None
+                else:
+                    return cls.video_url_part(
+                        url=path.resolve().as_uri(), mime_type=mime_type
+                    )
+            elif (
+                mime_type.startswith("text/")
+                or mime_type == "application/json"
+                or mime_type == "application/xml"
+            ):
+                try:
+                    async with aiofiles.open(path, encoding="utf-8") as f:
+                        text_content = await f.read()
+                    return cls.text_part(text_content)
+                except Exception as e:
+                    logger.error(f"读取文本类文件 {path.name} 失败: {e}")
+                    return None
+            else:
+                logger.info(
+                    f"文件 {path.name} (MIME: {mime_type}) 将作为通用文件URI处理。"
+                )
+                return cls.file_uri_part(
+                    file_uri=path.resolve().as_uri(),
+                    mime_type=mime_type,
+                    metadata={"name": path.name, "source": "local_path"},
+                )
+
+        except Exception as e:
+            logger.error(f"从路径 {path_like} 创建LLMContentPart时出错: {e}")
+            return None
+
+    def is_image_url(self) -> bool:
+        """检查图像源是否为URL"""
+        if not self.image_source:
+            return False
+        return self.image_source.startswith(("http://", "https://"))
+
+    def is_image_base64(self) -> bool:
+        """检查图像源是否为Base64 Data URL"""
+        if not self.image_source:
+            return False
+        return self.image_source.startswith("data:")
+
+    def get_base64_data(self) -> tuple[str, str] | None:
+        """从Data URL中提取Base64数据和MIME类型"""
+        if not self.is_image_base64() or not self.image_source:
+            return None
+
+        try:
+            header, data = self.image_source.split(",", 1)
+            mime_part = header.split(";")[0].replace("data:", "")
+            return mime_part, data
+        except (ValueError, IndexError):
+            logger.warning(f"无法解析Base64图像数据: {self.image_source[:50]}...")
+            return None
+
+    async def convert_for_api_async(self, api_type: str) -> dict[str, Any]:
+        """根据API类型转换多模态内容格式"""
+        from zhenxun.utils.http_utils import AsyncHttpx
+
+        if self.type == "text":
+            if api_type == "openai":
+                return {"type": "text", "text": self.text}
+            elif api_type == "gemini":
+                return {"text": self.text}
+            else:
+                return {"type": "text", "text": self.text}
+
+        elif self.type == "image":
+            if not self.image_source:
+                raise ValueError("图像类型的内容必须包含image_source")
+
+            if api_type == "openai":
+                return {"type": "image_url", "image_url": {"url": self.image_source}}
+            elif api_type == "gemini":
+                if self.is_image_base64():
+                    base64_info = self.get_base64_data()
+                    if base64_info:
+                        mime_type, data = base64_info
+                        return {"inlineData": {"mimeType": mime_type, "data": data}}
+                    else:
+                        raise ValueError(
+                            f"无法解析Base64图像数据: {self.image_source[:50]}..."
+                        )
+                elif self.is_image_url():
+                    logger.debug(f"正在为Gemini下载并编码URL图片: {self.image_source}")
+                    try:
+                        image_bytes = await AsyncHttpx.get_content(self.image_source)
+                        mime_type = self.mime_type or "image/jpeg"
+                        base64_data = base64.b64encode(image_bytes).decode("utf-8")
+                        return {
+                            "inlineData": {"mimeType": mime_type, "data": base64_data}
+                        }
+                    except Exception as e:
+                        logger.error(f"下载或编码URL图片失败: {e}", e=e)
+                        raise ValueError(f"无法处理图片URL: {e}")
+                else:
+                    raise ValueError(f"不支持的图像源格式: {self.image_source[:50]}...")
+            else:
+                return {"type": "image_url", "image_url": {"url": self.image_source}}
+
+        elif self.type == "video":
+            if not self.video_source:
+                raise ValueError("视频类型的内容必须包含video_source")
+
+            if api_type == "gemini":
+                # Gemini 支持视频，但需要通过 File API 上传
+                if self.video_source.startswith("data:"):
+                    # 处理 base64 视频数据
+                    try:
+                        header, data = self.video_source.split(",", 1)
+                        mime_type = header.split(";")[0].replace("data:", "")
+                        return {"inlineData": {"mimeType": mime_type, "data": data}}
+                    except (ValueError, IndexError):
+                        raise ValueError(
+                            f"无法解析Base64视频数据: {self.video_source[:50]}..."
+                        )
+                else:
+                    # 对于 URL 或其他格式，暂时不支持直接内联
+                    raise ValueError(
+                        "Gemini API 的视频处理需要通过 File API 上传，不支持直接 URL"
+                    )
+            else:
+                # 其他 API 可能不支持视频
+                raise ValueError(f"API类型 '{api_type}' 不支持视频内容")
+
+        elif self.type == "audio":
+            if not self.audio_source:
+                raise ValueError("音频类型的内容必须包含audio_source")
+
+            if api_type == "gemini":
+                # Gemini 支持音频，处理方式类似视频
+                if self.audio_source.startswith("data:"):
+                    try:
+                        header, data = self.audio_source.split(",", 1)
+                        mime_type = header.split(";")[0].replace("data:", "")
+                        return {"inlineData": {"mimeType": mime_type, "data": data}}
+                    except (ValueError, IndexError):
+                        raise ValueError(
+                            f"无法解析Base64音频数据: {self.audio_source[:50]}..."
+                        )
+                else:
+                    raise ValueError(
+                        "Gemini API 的音频处理需要通过 File API 上传，不支持直接 URL"
+                    )
+            else:
+                raise ValueError(f"API类型 '{api_type}' 不支持音频内容")
+
+        elif self.type == "file":
+            if api_type == "gemini" and self.file_uri:
+                return {
+                    "fileData": {"mimeType": self.mime_type, "fileUri": self.file_uri}
+                }
+            elif self.file_source:
+                file_name = (
+                    self.metadata.get("name", "file") if self.metadata else "file"
+                )
+                if api_type == "gemini":
+                    return {"text": f"[文件: {file_name}]\n{self.file_source}"}
+                else:
+                    return {
+                        "type": "text",
+                        "text": f"[文件: {file_name}]\n{self.file_source}",
+                    }
+            else:
+                raise ValueError("文件类型的内容必须包含file_uri或file_source")
+
+        else:
+            raise ValueError(f"不支持的内容类型: {self.type}")
+
+
+class LLMMessage(BaseModel):
+    """LLM 消息"""
+
+    role: str
+    content: str | list[LLMContentPart]
+    name: str | None = None
+    tool_calls: list[Any] | None = None
+    tool_call_id: str | None = None
+
+    def model_post_init(self, /, __context: Any) -> None:
+        """验证消息的有效性"""
+        _ = __context
+        if self.role == "tool":
+            if not self.tool_call_id:
+                raise ValueError("工具角色的消息必须包含 tool_call_id")
+            if not self.name:
+                raise ValueError("工具角色的消息必须包含函数名 (在 name 字段中)")
+        if self.role == "tool" and not isinstance(self.content, str):
+            logger.warning(
+                f"工具角色消息的内容期望是字符串，但得到的是: {type(self.content)}. "
+                "将尝试转换为字符串。"
+            )
+            try:
+                self.content = str(self.content)
+            except Exception as e:
+                raise ValueError(f"无法将工具角色的内容转换为字符串: {e}")
+
+    @classmethod
+    def user(cls, content: str | list[LLMContentPart]) -> "LLMMessage":
+        """创建用户消息"""
+        return cls(role="user", content=content)
+
+    @classmethod
+    def assistant_tool_calls(
+        cls,
+        tool_calls: list[Any],
+        content: str | list[LLMContentPart] = "",
+    ) -> "LLMMessage":
+        """创建助手请求工具调用的消息"""
+        return cls(role="assistant", content=content, tool_calls=tool_calls)
+
+    @classmethod
+    def assistant_text_response(
+        cls, content: str | list[LLMContentPart]
+    ) -> "LLMMessage":
+        """创建助手纯文本回复的消息"""
+        return cls(role="assistant", content=content, tool_calls=None)
+
+    @classmethod
+    def tool_response(
+        cls,
+        tool_call_id: str,
+        function_name: str,
+        result: Any,
+    ) -> "LLMMessage":
+        """创建工具执行结果的消息"""
+        import json
+
+        try:
+            content_str = json.dumps(result)
+        except TypeError as e:
+            logger.error(
+                f"工具 '{function_name}' 的结果无法JSON序列化: {result}. 错误: {e}"
+            )
+            content_str = json.dumps(
+                {"error": "工具结果无法JSON序列化", "details": str(e)}
+            )
+
+        return cls(
+            role="tool",
+            content=content_str,
+            tool_call_id=tool_call_id,
+            name=function_name,
+        )
+
+    @classmethod
+    def system(cls, content: str) -> "LLMMessage":
+        """创建系统消息"""
+        return cls(role="system", content=content)
+
+
+class LLMResponse(BaseModel):
+    """LLM 响应"""
+
+    text: str
+    images: list[bytes] | None = None
+    usage_info: dict[str, Any] | None = None
+    raw_response: dict[str, Any] | None = None
+    tool_calls: list[Any] | None = None
+    code_executions: list[Any] | None = None
+    grounding_metadata: Any | None = None
+    cache_info: Any | None = None

zhenxun/services/llm/types/enums.py

@@ -0,0 +1,78 @@
+"""
+LLM 枚举类型定义
+"""
+
+from enum import Enum, auto
+
+
+class ModelProvider(Enum):
+    """模型提供商枚举"""
+
+    OPENAI = "openai"
+    GEMINI = "gemini"
+    ZHIXPU = "zhipu"
+    CUSTOM = "custom"
+
+
+class ResponseFormat(Enum):
+    """响应格式枚举"""
+
+    TEXT = "text"
+    JSON = "json"
+    MULTIMODAL = "multimodal"
+
+
+class EmbeddingTaskType(str, Enum):
+    """文本嵌入任务类型 (主要用于Gemini)"""
+
+    RETRIEVAL_QUERY = "RETRIEVAL_QUERY"
+    RETRIEVAL_DOCUMENT = "RETRIEVAL_DOCUMENT"
+    SEMANTIC_SIMILARITY = "SEMANTIC_SIMILARITY"
+    CLASSIFICATION = "CLASSIFICATION"
+    CLUSTERING = "CLUSTERING"
+    QUESTION_ANSWERING = "QUESTION_ANSWERING"
+    FACT_VERIFICATION = "FACT_VERIFICATION"
+
+
+class ToolCategory(Enum):
+    """工具分类枚举"""
+
+    FILE_SYSTEM = auto()
+    NETWORK = auto()
+    SYSTEM_INFO = auto()
+    CALCULATION = auto()
+    DATA_PROCESSING = auto()
+    CUSTOM = auto()
+
+
+class TaskType(Enum):
+    """任务类型枚举"""
+
+    CHAT = "chat"
+    CODE = "code"
+    SEARCH = "search"
+    ANALYSIS = "analysis"
+    GENERATION = "generation"
+    MULTIMODAL = "multimodal"
+
+
+class LLMErrorCode(Enum):
+    """LLM 服务相关的错误代码枚举"""
+
+    MODEL_INIT_FAILED = 2000
+    MODEL_NOT_FOUND = 2001
+    API_REQUEST_FAILED = 2002
+    API_RESPONSE_INVALID = 2003
+    API_KEY_INVALID = 2004
+    API_QUOTA_EXCEEDED = 2005
+    API_TIMEOUT = 2006
+    API_RATE_LIMITED = 2007
+    NO_AVAILABLE_KEYS = 2008
+    UNKNOWN_API_TYPE = 2009
+    CONFIGURATION_ERROR = 2010
+    RESPONSE_PARSE_ERROR = 2011
+    CONTEXT_LENGTH_EXCEEDED = 2012
+    CONTENT_FILTERED = 2013
+    USER_LOCATION_NOT_SUPPORTED = 2014
+    GENERATION_FAILED = 2015
+    EMBEDDING_FAILED = 2016

zhenxun/services/llm/types/exceptions.py

@@ -2,31 +2,9 @@
 LLM 异常类型定义
 """
 
-from enum import Enum
 from typing import Any
 
-
+from .enums import LLMErrorCode
-class LLMErrorCode(Enum):
-    """LLM 服务相关的错误代码枚举"""
-
-    MODEL_INIT_FAILED = 2000
-    MODEL_NOT_FOUND = 2001
-    API_REQUEST_FAILED = 2002
-    API_RESPONSE_INVALID = 2003
-    API_KEY_INVALID = 2004
-    API_QUOTA_EXCEEDED = 2005
-    API_TIMEOUT = 2006
-    API_RATE_LIMITED = 2007
-    NO_AVAILABLE_KEYS = 2008
-    UNKNOWN_API_TYPE = 2009
-    CONFIGURATION_ERROR = 2010
-    RESPONSE_PARSE_ERROR = 2011
-    CONTEXT_LENGTH_EXCEEDED = 2012
-    CONTENT_FILTERED = 2013
-    USER_LOCATION_NOT_SUPPORTED = 2014
-    INVALID_PARAMETER = 2017
-    GENERATION_FAILED = 2015
-    EMBEDDING_FAILED = 2016
 
 
 class LLMException(Exception):
@@ -49,11 +27,7 @@ class LLMException(Exception):
 
     def __str__(self) -> str:
         if self.details:
-            safe_details = {k: v for k, v in self.details.items() if k != "api_key"}
+            return f"{self.message} (错误码: {self.code.name}, 详情: {self.details})"
-            if safe_details:
-                return (
-                    f"{self.message} (错误码: {self.code.name}, 详情: {safe_details})"
-                )
         return f"{self.message} (错误码: {self.code.name})"
 
     @property
@@ -72,13 +46,10 @@ class LLMException(Exception):
                 "当前所有API密钥均不可用，请稍后再试或联系管理员。"
             ),
             LLMErrorCode.USER_LOCATION_NOT_SUPPORTED: (
-                "当前网络环境不支持此 AI 模型 (如 Gemini/OpenAI)。\n"
+                "当前地区暂不支持此AI服务，请联系管理员或尝试其他模型。"
-                "原因: 代理节点所在地区（如香港/国内/非支持区）被服务商屏蔽。\n"
-                "建议: 请尝试更换代理节点至支持的地区（如美国/日本/新加坡）。"
             ),
             LLMErrorCode.API_REQUEST_FAILED: "AI服务请求失败，请稍后再试。",
             LLMErrorCode.API_RESPONSE_INVALID: "AI服务响应异常，请稍后再试。",
-            LLMErrorCode.INVALID_PARAMETER: "请求参数错误，请检查输入内容。",
             LLMErrorCode.CONFIGURATION_ERROR: "AI服务配置错误，请联系管理员。",
             LLMErrorCode.CONTEXT_LENGTH_EXCEEDED: "输入内容过长，请缩短后重试。",
             LLMErrorCode.CONTENT_FILTERED: "内容被安全过滤，请修改后重试。",
@@ -95,19 +66,15 @@ def get_user_friendly_error_message(error: Exception) -> str:
 
     error_str = str(error).lower()
 
-    if "timeout" in error_str or "timed out" in error_str:
+    if "timeout" in error_str or "超时" in error_str:
-        return "网络请求超时，请检查服务器网络或代理连接。"
+        return "请求超时，请稍后再试。"
-    if "connect" in error_str and ("refused" in error_str or "error" in error_str):
+    elif "connection" in error_str or "连接" in error_str:
-        return "无法连接到 AI 服务商，请检查网络连接或代理设置。"
+        return "网络连接失败，请检查网络后重试。"
-    if "proxy" in error_str:
+    elif "permission" in error_str or "权限" in error_str:
-        return "代理连接失败，请检查代理服务器是否正常运行。"
+        return "权限不足，请联系管理员。"
-    if "ssl" in error_str or "certificate" in error_str:
+    elif "not found" in error_str or "未找到" in error_str:
-        return "SSL 证书验证失败，请检查网络环境。"
+        return "请求的资源未找到，请检查配置。"
-    if "permission" in error_str or "forbidden" in error_str:
+    elif "invalid" in error_str or "无效" in error_str:
-        return "权限不足，可能是 API Key 权限受限。"
-    if "not found" in error_str:
-        return "请求的资源未找到 (404)，请检查模型名称或端点配置。"
-    if "invalid" in error_str or "无效" in error_str:
         return "请求参数无效，请检查输入。"
-
+    else:
-    return f"服务暂时不可用 ({type(error).__name__})，请稍后再试。"
+        return "服务暂时不可用，请稍后再试。"

zhenxun/services/llm/types/models.py

@@ -4,459 +4,12 @@ LLM 数据模型定义
 包含模型信息、配置、工具定义和响应数据的模型类。
 """
 
-import base64
 from dataclasses import dataclass, field
-from enum import Enum, auto
+from typing import Any
-import mimetypes
-from pathlib import Path
-import sys
-from typing import Any, Literal
 
-import aiofiles
 from pydantic import BaseModel, Field
 
-from zhenxun.services.log import logger
+from .enums import ModelProvider, ToolCategory
-
-if sys.version_info >= (3, 11):
-    from enum import StrEnum
-else:
-    from strenum import StrEnum
-
-
-class ModelProvider(Enum):
-    """模型提供商枚举"""
-
-    OPENAI = "openai"
-    GEMINI = "gemini"
-    ZHIXPU = "zhipu"
-    CUSTOM = "custom"
-
-
-class ResponseFormat(Enum):
-    """响应格式枚举"""
-
-    TEXT = "text"
-    JSON = "json"
-    MULTIMODAL = "multimodal"
-
-
-class StructuredOutputStrategy(str, Enum):
-    """结构化输出策略"""
-
-    NATIVE = "native"
-    """使用原生 API (如 OpenAI json_object/json_schema, Gemini mime_type)"""
-    TOOL_CALL = "tool_call"
-    """构造虚假工具调用来强制输出结构化数据 (适用于指令跟随弱但工具调用强的模型)"""
-    PROMPT = "prompt"
-    """仅在 Prompt 中追加 Schema 说明，依赖文本补全"""
-
-
-class EmbeddingTaskType(str, Enum):
-    """文本嵌入任务类型 (主要用于Gemini)"""
-
-    RETRIEVAL_QUERY = "RETRIEVAL_QUERY"
-    RETRIEVAL_DOCUMENT = "RETRIEVAL_DOCUMENT"
-    SEMANTIC_SIMILARITY = "SEMANTIC_SIMILARITY"
-    CLASSIFICATION = "CLASSIFICATION"
-    CLUSTERING = "CLUSTERING"
-    QUESTION_ANSWERING = "QUESTION_ANSWERING"
-    FACT_VERIFICATION = "FACT_VERIFICATION"
-
-
-class ToolCategory(Enum):
-    """工具分类枚举"""
-
-    FILE_SYSTEM = auto()
-    NETWORK = auto()
-    SYSTEM_INFO = auto()
-    CALCULATION = auto()
-    DATA_PROCESSING = auto()
-    CUSTOM = auto()
-
-
-class CodeExecutionOutcome(StrEnum):
-    """代码执行结果状态枚举"""
-
-    OUTCOME_OK = "OUTCOME_OK"
-    OUTCOME_FAILED = "OUTCOME_FAILED"
-    OUTCOME_DEADLINE_EXCEEDED = "OUTCOME_DEADLINE_EXCEEDED"
-    OUTCOME_COMPILATION_ERROR = "OUTCOME_COMPILATION_ERROR"
-    OUTCOME_RUNTIME_ERROR = "OUTCOME_RUNTIME_ERROR"
-    OUTCOME_UNKNOWN = "OUTCOME_UNKNOWN"
-
-
-class TaskType(Enum):
-    """任务类型枚举"""
-
-    CHAT = "chat"
-    CODE = "code"
-    SEARCH = "search"
-    ANALYSIS = "analysis"
-    GENERATION = "generation"
-    MULTIMODAL = "multimodal"
-
-
-class LLMContentPart(BaseModel):
-    """
-    LLM 消息内容部分 - 支持多模态内容。
-
-    这是一个联合体模型，`type` 字段决定了哪些其他字段是有效的。
-    例如：
-    - type='text': 使用 `text` 字段。
-    - type='image': 使用 `image_source` 字段。
-    - type='executable_code': 使用 `code_language` 和 `code_content` 字段。
-    """
-
-    type: str
-    text: str | None = None
-    image_source: str | None = None
-    audio_source: str | None = None
-    video_source: str | None = None
-    document_source: str | None = None
-    file_uri: str | None = None
-    file_source: str | None = None
-    url: str | None = None
-    mime_type: str | None = None
-    thought_text: str | None = None
-    media_resolution: str | None = None
-    code_language: str | None = None
-    code_content: str | None = None
-    execution_outcome: str | None = None
-    execution_output: str | None = None
-    metadata: dict[str, Any] | None = None
-
-    def model_post_init(self, /, __context: Any) -> None:
-        """验证内容部分的有效性"""
-        _ = __context
-        validation_rules = {
-            "text": lambda: self.text is not None,
-            "image": lambda: self.image_source,
-            "audio": lambda: self.audio_source,
-            "video": lambda: self.video_source,
-            "document": lambda: self.document_source,
-            "file": lambda: self.file_uri or self.file_source,
-            "url": lambda: self.url,
-            "thought": lambda: self.thought_text,
-            "executable_code": lambda: self.code_content is not None,
-            "execution_result": lambda: self.execution_outcome is not None,
-        }
-
-        if self.type in validation_rules:
-            if not validation_rules[self.type]():
-                raise ValueError(f"{self.type}类型的内容部分必须包含相应字段")
-
-    @classmethod
-    def text_part(cls, text: str) -> "LLMContentPart":
-        """创建文本内容部分"""
-        return cls(type="text", text=text)
-
-    @classmethod
-    def thought_part(cls, text: str) -> "LLMContentPart":
-        """创建思考过程内容部分"""
-        return cls(type="thought", thought_text=text)
-
-    @classmethod
-    def image_url_part(cls, url: str) -> "LLMContentPart":
-        """创建图片URL内容部分"""
-        return cls(type="image", image_source=url)
-
-    @classmethod
-    def image_base64_part(
-        cls, data: str, mime_type: str = "image/png"
-    ) -> "LLMContentPart":
-        """创建Base64图片内容部分"""
-        data_url = f"data:{mime_type};base64,{data}"
-        return cls(type="image", image_source=data_url)
-
-    @classmethod
-    def audio_url_part(cls, url: str, mime_type: str = "audio/wav") -> "LLMContentPart":
-        """创建音频URL内容部分"""
-        return cls(type="audio", audio_source=url, mime_type=mime_type)
-
-    @classmethod
-    def video_url_part(cls, url: str, mime_type: str = "video/mp4") -> "LLMContentPart":
-        """创建视频URL内容部分"""
-        return cls(type="video", video_source=url, mime_type=mime_type)
-
-    @classmethod
-    def video_base64_part(
-        cls, data: str, mime_type: str = "video/mp4"
-    ) -> "LLMContentPart":
-        """创建Base64视频内容部分"""
-        data_url = f"data:{mime_type};base64,{data}"
-        return cls(type="video", video_source=data_url, mime_type=mime_type)
-
-    @classmethod
-    def audio_base64_part(
-        cls, data: str, mime_type: str = "audio/wav"
-    ) -> "LLMContentPart":
-        """创建Base64音频内容部分"""
-        data_url = f"data:{mime_type};base64,{data}"
-        return cls(type="audio", audio_source=data_url, mime_type=mime_type)
-
-    @classmethod
-    def file_uri_part(
-        cls,
-        file_uri: str,
-        mime_type: str | None = None,
-        metadata: dict[str, Any] | None = None,
-    ) -> "LLMContentPart":
-        """创建Gemini File API URI内容部分"""
-        return cls(
-            type="file",
-            file_uri=file_uri,
-            mime_type=mime_type,
-            metadata=metadata or {},
-        )
-
-    @classmethod
-    def executable_code_part(cls, language: str, code: str) -> "LLMContentPart":
-        """创建可执行代码内容部分"""
-        return cls(type="executable_code", code_language=language, code_content=code)
-
-    @classmethod
-    def execution_result_part(
-        cls, outcome: str, output: str | None
-    ) -> "LLMContentPart":
-        """创建代码执行结果部分"""
-        return cls(
-            type="execution_result", execution_outcome=outcome, execution_output=output
-        )
-
-    @classmethod
-    async def from_path(
-        cls, path_like: str | Path, target_api: str | None = None
-    ) -> "LLMContentPart | None":
-        """
-        从本地文件路径创建 LLMContentPart。
-        自动检测MIME类型，并根据类型（如图片）可能加载为Base64。
-        target_api 可以用于提示如何最好地准备数据（例如 'gemini' 可能偏好 base64）
-        """
-        try:
-            path = Path(path_like)
-            if not path.exists() or not path.is_file():
-                logger.warning(f"文件不存在或不是一个文件: {path}")
-                return None
-
-            mime_type, _ = mimetypes.guess_type(path.resolve().as_uri())
-
-            if not mime_type:
-                logger.warning(
-                    f"无法猜测文件 {path.name} 的MIME类型，将尝试作为文本文件处理。"
-                )
-                try:
-                    async with aiofiles.open(path, encoding="utf-8") as f:
-                        text_content = await f.read()
-                    return cls.text_part(text_content)
-                except Exception as e:
-                    logger.error(f"读取文本文件 {path.name} 失败: {e}")
-                    return None
-
-            if mime_type.startswith("image/"):
-                if target_api == "gemini" or not path.is_absolute():
-                    try:
-                        async with aiofiles.open(path, "rb") as f:
-                            img_bytes = await f.read()
-                        base64_data = base64.b64encode(img_bytes).decode("utf-8")
-                        return cls.image_base64_part(
-                            data=base64_data, mime_type=mime_type
-                        )
-                    except Exception as e:
-                        logger.error(f"读取或编码图片文件 {path.name} 失败: {e}")
-                        return None
-                else:
-                    logger.warning(
-                        f"为本地图片路径 {path.name} 生成 image_url_part。"
-                        "实际API可能不支持 file:// URI。考虑使用Base64或公网URL。"
-                    )
-                    return cls.image_url_part(url=path.resolve().as_uri())
-            elif mime_type.startswith("audio/"):
-                return cls.audio_url_part(
-                    url=path.resolve().as_uri(), mime_type=mime_type
-                )
-            elif mime_type.startswith("video/"):
-                if target_api == "gemini":
-                    try:
-                        async with aiofiles.open(path, "rb") as f:
-                            video_bytes = await f.read()
-                        base64_data = base64.b64encode(video_bytes).decode("utf-8")
-                        return cls.video_base64_part(
-                            data=base64_data, mime_type=mime_type
-                        )
-                    except Exception as e:
-                        logger.error(f"读取或编码视频文件 {path.name} 失败: {e}")
-                        return None
-                else:
-                    return cls.video_url_part(
-                        url=path.resolve().as_uri(), mime_type=mime_type
-                    )
-            elif (
-                mime_type.startswith("text/")
-                or mime_type == "application/json"
-                or mime_type == "application/xml"
-            ):
-                try:
-                    async with aiofiles.open(path, encoding="utf-8") as f:
-                        text_content = await f.read()
-                    return cls.text_part(text_content)
-                except Exception as e:
-                    logger.error(f"读取文本类文件 {path.name} 失败: {e}")
-                    return None
-            else:
-                logger.info(
-                    f"文件 {path.name} (MIME: {mime_type}) 将作为通用文件URI处理。"
-                )
-                return cls.file_uri_part(
-                    file_uri=path.resolve().as_uri(),
-                    mime_type=mime_type,
-                    metadata={"name": path.name, "source": "local_path"},
-                )
-
-        except Exception as e:
-            logger.error(f"从路径 {path_like} 创建LLMContentPart时出错: {e}")
-            return None
-
-    def is_image_url(self) -> bool:
-        """检查图像源是否为URL"""
-        if not self.image_source:
-            return False
-        return self.image_source.startswith(("http://", "https://"))
-
-    def is_image_base64(self) -> bool:
-        """检查图像源是否为Base64 Data URL"""
-        if not self.image_source:
-            return False
-        return self.image_source.startswith("data:")
-
-    def get_base64_data(self) -> tuple[str, str] | None:
-        """从Data URL中提取Base64数据和MIME类型"""
-        if not self.is_image_base64() or not self.image_source:
-            return None
-
-        try:
-            header, data = self.image_source.split(",", 1)
-            mime_part = header.split(";")[0].replace("data:", "")
-            return mime_part, data
-        except (ValueError, IndexError):
-            logger.warning(f"无法解析Base64图像数据: {self.image_source[:50]}...")
-            return None
-
-
-class LLMMessage(BaseModel):
-    """
-    LLM 消息对象，用于构建对话历史。
-
-    核心字段说明：
-    - role: 消息角色，推荐值为 'user', 'assistant', 'system', 'tool'。
-    - content: 消息内容，可以是纯文本字符串，也可以是 LLMContentPart 列表（用于多模态）
-    - tool_calls: (仅 assistant) 包含模型生成的工具调用请求。
-    - tool_call_id: (仅 tool) 对应 tool 消息响应的调用 ID。
-    - name: (仅 tool) 对应 tool 消息响应的函数名称。
-    """
-
-    role: str
-    content: str | list[LLMContentPart]
-    name: str | None = None
-    tool_calls: list[Any] | None = None
-    tool_call_id: str | None = None
-    thought_signature: str | None = None
-
-    def model_post_init(self, /, __context: Any) -> None:
-        """验证消息的有效性"""
-        _ = __context
-        if self.role == "tool":
-            if not self.tool_call_id:
-                raise ValueError("工具角色的消息必须包含 tool_call_id")
-            if not self.name:
-                raise ValueError("工具角色的消息必须包含函数名 (在 name 字段中)")
-        if self.role == "tool" and not isinstance(self.content, str):
-            logger.warning(
-                f"工具角色消息的内容期望是字符串，但得到的是: {type(self.content)}. "
-                "将尝试转换为字符串。"
-            )
-            try:
-                self.content = str(self.content)
-            except Exception as e:
-                raise ValueError(f"无法将工具角色的内容转换为字符串: {e}")
-
-    @classmethod
-    def user(cls, content: str | list[LLMContentPart]) -> "LLMMessage":
-        """创建用户消息"""
-        return cls(role="user", content=content)
-
-    @classmethod
-    def assistant_tool_calls(
-        cls,
-        tool_calls: list[Any],
-        content: str | list[LLMContentPart] = "",
-    ) -> "LLMMessage":
-        """创建助手请求工具调用的消息"""
-        return cls(role="assistant", content=content, tool_calls=tool_calls)
-
-    @classmethod
-    def assistant_text_response(
-        cls, content: str | list[LLMContentPart]
-    ) -> "LLMMessage":
-        """创建助手纯文本回复的消息"""
-        return cls(role="assistant", content=content, tool_calls=None)
-
-    @classmethod
-    def tool_response(
-        cls,
-        tool_call_id: str,
-        function_name: str,
-        result: Any,
-    ) -> "LLMMessage":
-        """创建工具执行结果的消息"""
-        import json
-
-        try:
-            content_str = json.dumps(result)
-        except TypeError as e:
-            logger.error(
-                f"工具 '{function_name}' 的结果无法JSON序列化: {result}. 错误: {e}"
-            )
-            content_str = json.dumps(
-                {"error": "工具结果无法JSON序列化", "details": str(e)}
-            )
-
-        return cls(
-            role="tool",
-            content=content_str,
-            tool_call_id=tool_call_id,
-            name=function_name,
-        )
-
-    @classmethod
-    def system(cls, content: str) -> "LLMMessage":
-        """创建系统消息"""
-        return cls(role="system", content=content)
-
-
-class LLMResponse(BaseModel):
-    """
-    LLM 响应对象，封装了模型生成的全部信息。
-
-    核心字段说明：
-    - text: 模型生成的文本内容。如果是纯文本回复，此字段即为结果。
-    - tool_calls: 如果模型决定调用工具，此列表包含调用详情。
-    - content_parts: 包含多模态或结构化内容的原始部分列表（如思维链、代码块）。
-    - raw_response: 原始的第三方 API 响应字典（用于调试）。
-    - images: 如果请求涉及生图，此处包含生成的图片数据。
-    """
-
-    text: str
-    content_parts: list[Any] | None = None
-    images: list[bytes | Path] | None = None
-    usage_info: dict[str, Any] | None = None
-    raw_response: dict[str, Any] | None = None
-    tool_calls: list[Any] | None = None
-    code_executions: list[Any] | None = None
-    grounding_metadata: Any | None = None
-    cache_info: Any | None = None
-    thought_text: str | None = None
-    thought_signature: str | None = None
-
 
 ModelName = str | None
 
@@ -473,64 +26,6 @@ class ToolDefinition(BaseModel):
     )
 
 
-class ToolChoice(BaseModel):
-    """统一的工具选择配置"""
-
-    mode: Literal["auto", "none", "any", "required"] = Field(
-        default="auto", description="工具调用模式"
-    )
-    allowed_function_names: list[str] | None = Field(
-        default=None, description="允许调用的函数名称列表"
-    )
-
-
-class BasePlatformTool(BaseModel):
-    """平台原生工具基类"""
-
-    class Config:
-        extra = "forbid"
-
-    def get_tool_declaration(self) -> dict[str, Any]:
-        """获取放入 'tools' 列表中的声明对象 (Snake Case)"""
-        raise NotImplementedError
-
-    def get_tool_config(self) -> dict[str, Any] | None:
-        """获取放入 'toolConfig' 中的配置对象 (Snake Case)"""
-        return None
-
-
-class GeminiCodeExecution(BasePlatformTool):
-    """Gemini 代码执行工具"""
-
-    def get_tool_declaration(self) -> dict[str, Any]:
-        return {"code_execution": {}}
-
-
-class GeminiGoogleSearch(BasePlatformTool):
-    """Gemini 谷歌搜索 (Grounding) 工具"""
-
-    mode: Literal["MODE_DYNAMIC"] = "MODE_DYNAMIC"
-    dynamic_threshold: float | None = Field(default=None)
-
-    def get_tool_declaration(self) -> dict[str, Any]:
-        return {"google_search": {}}
-
-    def get_tool_config(self) -> dict[str, Any] | None:
-        return None
-
-
-class GeminiUrlContext(BasePlatformTool):
-    """Gemini 网址上下文工具"""
-
-    urls: list[str] = Field(..., description="作为上下文的 URL 列表", max_length=20)
-
-    def get_tool_declaration(self) -> dict[str, Any]:
-        return {"google_search": {}, "url_context": {}}
-
-    def get_tool_config(self) -> dict[str, Any] | None:
-        return None
-
-
 class ToolResult(BaseModel):
     """
     一个结构化的工具执行结果模型。
@@ -592,8 +87,6 @@ class ModelDetail(BaseModel):
     is_embedding_model: bool = False
     temperature: float | None = None
     max_tokens: int | None = None
-    api_type: str | None = None
-    endpoint: str | None = None
 
 
 class ProviderConfig(BaseModel):
@@ -623,7 +116,6 @@ class LLMToolCall(BaseModel):
 
     id: str
     function: LLMToolFunction
-    thought_signature: str | None = None
 
 
 class LLMCodeExecution(BaseModel):
@@ -651,12 +143,6 @@ class LLMGroundingMetadata(BaseModel):
     web_search_queries: list[str] | None = None
     grounding_attributions: list[LLMGroundingAttribution] | None = None
     search_suggestions: list[dict[str, Any]] | None = None
-    search_entry_point: str | None = Field(
-        default=None, description="Google搜索建议的HTML片段(renderedContent)"
-    )
-    map_widget_token: str | None = Field(
-        default=None, description="Google Maps 前端组件令牌"
-    )
 
 
 class LLMCacheInfo(BaseModel):

zhenxun/services/llm/types/protocols.py

@@ -2,97 +2,10 @@
 LLM 模块的协议定义
 """
 
-from abc import ABC
+from typing import Any, Protocol
-from typing import TYPE_CHECKING, Any, Protocol, Union
-
-from pydantic import BaseModel
 
 from .models import ToolDefinition, ToolResult
 
-if TYPE_CHECKING:
-    from .models import LLMMessage, LLMResponse, LLMToolCall
-
-
-class ToolCallData(BaseModel):
-    """传递给 on_tool_start 的数据模型"""
-
-    tool_name: str
-    tool_args: dict[str, Any]
-
-
-class ToolCallCompleteData(BaseModel):
-    """传递给 on_tool_call_complete 的数据模型"""
-
-    id: str
-    name: str
-    arguments: str
-    result: "ToolResult"
-
-
-class BaseCallbackHandler(ABC):
-    """
-    Agent/LLM 生命周期回调处理器的基类。
-    下沉至 LLM 层以允许 ToolInvoker 直接调用。
-    """
-
-    async def on_agent_start(self, messages: list["LLMMessage"], **kwargs: Any) -> None:
-        """在 AgentExecutor 开始运行时调用。"""
-        pass
-
-    async def on_model_start(
-        self, model_name: str, messages: list["LLMMessage"], **kwargs: Any
-    ) -> None:
-        """在向LLM发起请求之前调用。"""
-        pass
-
-    async def on_model_end(
-        self, response: "LLMResponse", duration: float, **kwargs: Any
-    ) -> None:
-        """在收到LLM响应之后调用。"""
-        pass
-
-    async def on_tool_start(
-        self, tool_call: "LLMToolCall", data: ToolCallData, **kwargs: Any
-    ) -> Union[ToolCallData, "ToolResult", None]:
-        """
-        在单个工具即将被执行时调用。
-
-        返回:
-            ToolCallData: 修改参数并继续执行
-            ToolResult: 拦截执行并直接返回给模型
-            None: 正常继续
-        """
-        pass
-
-    async def on_tool_end(
-        self,
-        result: Union["ToolResult", None],
-        error: Exception | None,
-        tool_call: "LLMToolCall",
-        duration: float,
-        **kwargs: Any,
-    ) -> None:
-        """在单个工具执行完毕后调用，无论成功或失败。"""
-        pass
-
-    async def on_tool_call_complete(
-        self, data: ToolCallCompleteData, **kwargs: Any
-    ) -> None:
-        """在工具调用完成并准备创建响应消息时调用。"""
-        pass
-
-    async def on_human_input_request(self, query: str, **kwargs: Any) -> str | None:
-        """
-        当 Agent 需要人类输入时调用。
-        """
-        return None
-
-    async def on_agent_end(
-        self, final_history: list["LLMMessage"], duration: float, **kwargs: Any
-    ) -> None:
-        """在 AgentExecutor 运行结束时调用。"""
-        pass
-
 
 class ToolExecutable(Protocol):
     """
@@ -106,14 +19,10 @@ class ToolExecutable(Protocol):
         """
         ...
 
-    async def execute(self, context: Any | None = None, **kwargs: Any) -> ToolResult:
+    async def execute(self, **kwargs: Any) -> ToolResult:
         """
         异步执行工具并返回一个结构化的结果。
         参数由LLM根据工具定义生成。
-
-        Args:
-            context: 运行时上下文 (RunContext)，可选注入
-            **kwargs: 工具参数
         """
         ...
 

zhenxun/services/llm/utils.py

@@ -3,176 +3,26 @@ LLM 模块的工具和转换函数
 """
 
 import base64
-from collections.abc import Awaitable, Callable
+import copy
-import io
 from pathlib import Path
-from typing import Any, TypeVar
+from typing import Any
 
-import aiofiles
-import json_repair
 from nonebot.adapters import Message as PlatformMessage
-from nonebot.compat import type_validate_json
 from nonebot_plugin_alconna.uniseg import (
     At,
     File,
     Image,
     Reply,
-    Segment,
     Text,
     UniMessage,
     Video,
     Voice,
 )
-from PIL.Image import Image as PILImageType
-from pydantic import BaseModel, Field, ValidationError, create_model
 
 from zhenxun.services.log import logger
 from zhenxun.utils.http_utils import AsyncHttpx
-from zhenxun.utils.pydantic_compat import model_validate
 
-from .types import LLMContentPart, LLMErrorCode, LLMException, LLMMessage
+from .types import LLMContentPart, LLMMessage
-from .types.capabilities import ReasoningMode, get_model_capabilities
-
-T = TypeVar("T", bound=BaseModel)
-
-
-S = TypeVar("S", bound=Segment)
-_SEGMENT_HANDLERS: dict[
-    type[Segment], Callable[[Any], Awaitable[LLMContentPart | None]]
-] = {}
-
-
-def register_segment_handler(seg_type: type[S]):
-    """装饰器：注册 Uniseg 消息段的处理器"""
-
-    def decorator(func: Callable[[S], Awaitable[LLMContentPart | None]]):
-        _SEGMENT_HANDLERS[seg_type] = func
-        return func
-
-    return decorator
-
-
-async def _process_media_data(seg: Any, default_mime: str) -> tuple[str, str] | None:
-    """
-    [内部复用] 通用媒体数据处理：获取 Base64 数据和 MIME 类型。
-    优先顺序：Raw -> Path -> URL (下载)
-    """
-    mime_type = getattr(seg, "mimetype", None) or default_mime
-    b64_data = None
-
-    if hasattr(seg, "raw") and seg.raw:
-        if isinstance(seg.raw, bytes):
-            b64_data = base64.b64encode(seg.raw).decode("utf-8")
-
-    elif getattr(seg, "path", None):
-        try:
-            path = Path(seg.path)
-            if path.exists():
-                async with aiofiles.open(path, "rb") as f:
-                    content = await f.read()
-                b64_data = base64.b64encode(content).decode("utf-8")
-        except Exception as e:
-            logger.error(f"读取媒体文件失败: {seg.path}, 错误: {e}")
-
-    elif getattr(seg, "url", None):
-        try:
-            logger.debug(f"检测到媒体URL，开始下载: {seg.url}")
-            media_bytes = await AsyncHttpx.get_content(seg.url)
-            b64_data = base64.b64encode(media_bytes).decode("utf-8")
-            logger.debug(f"媒体文件下载成功，大小: {len(media_bytes)} bytes")
-        except Exception as e:
-            logger.error(f"从URL下载媒体失败: {seg.url}, 错误: {e}")
-            return None
-
-    if b64_data:
-        return mime_type, b64_data
-    return None
-
-
-@register_segment_handler(Text)
-async def _handle_text(seg: Text) -> LLMContentPart | None:
-    if seg.text.strip():
-        return LLMContentPart.text_part(seg.text)
-    return None
-
-
-@register_segment_handler(Image)
-async def _handle_image(seg: Image) -> LLMContentPart | None:
-    media_info = await _process_media_data(seg, "image/png")
-    if media_info:
-        mime, data = media_info
-        return LLMContentPart.image_base64_part(data, mime)
-    return None
-
-
-@register_segment_handler(Voice)
-async def _handle_voice(seg: Voice) -> LLMContentPart | None:
-    media_info = await _process_media_data(seg, "audio/wav")
-    if media_info:
-        mime, data = media_info
-        return LLMContentPart.audio_base64_part(data, mime)
-    return LLMContentPart.text_part(f"[语音消息: {seg.id or 'unknown'}]")
-
-
-@register_segment_handler(Video)
-async def _handle_video(seg: Video) -> LLMContentPart | None:
-    media_info = await _process_media_data(seg, "video/mp4")
-    if media_info:
-        mime, data = media_info
-        return LLMContentPart.video_base64_part(data, mime)
-    return LLMContentPart.text_part(f"[视频消息: {seg.id or 'unknown'}]")
-
-
-@register_segment_handler(File)
-async def _handle_file(seg: File) -> LLMContentPart | None:
-    if seg.path:
-        return await LLMContentPart.from_path(seg.path)
-    return LLMContentPart.text_part(f"[文件: {seg.name} (ID: {seg.id})]")
-
-
-@register_segment_handler(At)
-async def _handle_at(seg: At) -> LLMContentPart | None:
-    if seg.flag == "all":
-        return LLMContentPart.text_part("[提及所有人]")
-    return LLMContentPart.text_part(f"[提及用户: {seg.target}]")
-
-
-@register_segment_handler(Reply)
-async def _handle_reply(seg: Reply) -> LLMContentPart | None:
-    text = str(seg.msg) if seg.msg else ""
-    if text:
-        return LLMContentPart.text_part(f'[回复消息: "{text[:50]}..."]')
-    return LLMContentPart.text_part("[回复了一条消息]")
-
-
-async def _transform_to_content_part(item: Any) -> LLMContentPart:
-    """
-    将混合输入转换为统一的 LLMContentPart，便于 normalize_to_llm_messages 使用。
-    """
-    if isinstance(item, LLMContentPart):
-        return item
-
-    if isinstance(item, str):
-        return LLMContentPart.text_part(item)
-
-    if isinstance(item, Path):
-        part = await LLMContentPart.from_path(item)
-        if part is None:
-            raise ValueError(f"无法从路径加载内容: {item}")
-        return part
-
-    if isinstance(item, dict):
-        return LLMContentPart(**item)
-
-    if PILImageType and isinstance(item, PILImageType):
-        buffer = io.BytesIO()
-        fmt = item.format or "PNG"
-        item.save(buffer, format=fmt)
-        b64_data = base64.b64encode(buffer.getvalue()).decode("utf-8")
-        mime_type = f"image/{fmt.lower()}"
-        return LLMContentPart.image_base64_part(b64_data, mime_type)
-
-    raise TypeError(f"不支持的输入类型用于构建 ContentPart: {type(item)}")
 
 
 async def unimsg_to_llm_parts(message: UniMessage) -> list[LLMContentPart]:
@@ -186,25 +36,110 @@ async def unimsg_to_llm_parts(message: UniMessage) -> list[LLMContentPart]:
     返回:
         list[LLMContentPart]: 转换后的内容部分列表。
     """
-    if not _SEGMENT_HANDLERS:
-        pass
-
     parts: list[LLMContentPart] = []
     for seg in message:
-        handler = _SEGMENT_HANDLERS.get(type(seg))
+        part = None
-        if handler:
+        if isinstance(seg, Text):
-            try:
+            if seg.text.strip():
-                part = await handler(seg)
+                part = LLMContentPart.text_part(seg.text)
+        elif isinstance(seg, Image):
+            if seg.path:
+                part = await LLMContentPart.from_path(seg.path, target_api="gemini")
+            elif seg.url:
+                part = LLMContentPart.image_url_part(seg.url)
+            elif hasattr(seg, "raw") and seg.raw:
+                mime_type = (
+                    getattr(seg, "mimetype", "image/png")
+                    if hasattr(seg, "mimetype")
+                    else "image/png"
+                )
+                if isinstance(seg.raw, bytes):
+                    b64_data = base64.b64encode(seg.raw).decode("utf-8")
+                    part = LLMContentPart.image_base64_part(b64_data, mime_type)
+
+        elif isinstance(seg, File | Voice | Video):
+            if seg.path:
+                part = await LLMContentPart.from_path(seg.path)
+            elif seg.url:
+                try:
+                    logger.debug(f"检测到媒体URL，开始下载: {seg.url}")
+                    media_bytes = await AsyncHttpx.get_content(seg.url)
+
+                    new_seg = copy.copy(seg)
+                    new_seg.raw = media_bytes
+                    seg = new_seg
+                    logger.debug(f"媒体文件下载成功，大小: {len(media_bytes)} bytes")
+                except Exception as e:
+                    logger.error(f"从URL下载媒体失败: {seg.url}, 错误: {e}")
+                    part = LLMContentPart.text_part(
+                        f"[下载媒体失败: {seg.name or seg.url}]"
+                    )
+
                 if part:
                     parts.append(part)
-            except Exception as e:
+                    continue
-                logger.warning(f"处理消息段 {seg} 失败: {e}", "LLMUtils")
+
+            if hasattr(seg, "raw") and seg.raw:
+                mime_type = getattr(seg, "mimetype", None)
+                if isinstance(seg.raw, bytes):
+                    b64_data = base64.b64encode(seg.raw).decode("utf-8")
+
+                    if isinstance(seg, Video):
+                        if not mime_type:
+                            mime_type = "video/mp4"
+                        part = LLMContentPart.video_base64_part(
+                            data=b64_data, mime_type=mime_type
+                        )
+                        logger.debug(
+                            f"处理视频字节数据: {mime_type}, 大小: {len(seg.raw)} bytes"
+                        )
+                    elif isinstance(seg, Voice):
+                        if not mime_type:
+                            mime_type = "audio/wav"
+                        part = LLMContentPart.audio_base64_part(
+                            data=b64_data, mime_type=mime_type
+                        )
+                        logger.debug(
+                            f"处理音频字节数据: {mime_type}, 大小: {len(seg.raw)} bytes"
+                        )
+                    else:
+                        part = LLMContentPart.text_part(
+                            f"[FILE: {mime_type or 'unknown'}, {len(seg.raw)} bytes]"
+                        )
+                        logger.debug(
+                            f"处理其他文件字节数据: {mime_type}, "
+                            f"大小: {len(seg.raw)} bytes"
+                        )
+
+        elif isinstance(seg, At):
+            if seg.flag == "all":
+                part = LLMContentPart.text_part("[提及所有人]")
+            else:
+                part = LLMContentPart.text_part(f"[提及用户: {seg.target}]")
+
+        elif isinstance(seg, Reply):
+            if seg.msg:
+                try:
+                    extract_method = getattr(seg.msg, "extract_plain_text", None)
+                    if extract_method and callable(extract_method):
+                        reply_text = str(extract_method()).strip()
+                    else:
+                        reply_text = str(seg.msg).strip()
+                    if reply_text:
+                        part = LLMContentPart.text_part(
+                            f'[回复消息: "{reply_text[:50]}..."]'
+                        )
+                except Exception:
+                    part = LLMContentPart.text_part("[回复了一条消息]")
+
+        if part:
+            parts.append(part)
 
     return parts
 
 
 async def normalize_to_llm_messages(
-    message: str | UniMessage | LLMMessage | list[Any],
+    message: str | UniMessage | LLMMessage | list[LLMContentPart] | list[LLMMessage],
     instruction: str | None = None,
 ) -> list[LLMMessage]:
     """
@@ -232,10 +167,7 @@ async def normalize_to_llm_messages(
         content_parts = await unimsg_to_llm_parts(message)
         messages.append(LLMMessage.user(content_parts))
     elif isinstance(message, list):
-        parts = []
+        messages.append(LLMMessage.user(message))  # type: ignore
-        for item in message:
-            parts.append(await _transform_to_content_part(item))
-        messages.append(LLMMessage.user(parts))
     else:
         raise TypeError(f"不支持的消息类型: {type(message)}")
 
@@ -323,271 +255,53 @@ def message_to_unimessage(message: PlatformMessage) -> UniMessage:
     返回:
         UniMessage: 转换后的通用消息对象。
     """
-    return UniMessage.of(message)
+    uni_segments = []
+    for seg in message:
+        if seg.type == "text":
+            uni_segments.append(Text(seg.data.get("text", "")))
+        elif seg.type == "image":
+            uni_segments.append(Image(url=seg.data.get("url")))
+        elif seg.type == "record":
+            uni_segments.append(Voice(url=seg.data.get("url")))
+        elif seg.type == "video":
+            uni_segments.append(Video(url=seg.data.get("url")))
+        elif seg.type == "at":
+            uni_segments.append(At("user", str(seg.data.get("qq", ""))))
+        else:
+            logger.debug(f"跳过不支持的平台消息段类型: {seg.type}")
 
-
+    return UniMessage(uni_segments)
-def resolve_json_schema_refs(schema: dict) -> dict:
-    """
-    递归解析 JSON Schema 中的 $ref，将其替换为 $defs/definitions 中的定义。
-    用于兼容不支持 $ref 的 Gemini API。
-    """
-    definitions = schema.get("$defs") or schema.get("definitions") or {}
-
-    def _resolve(node: Any) -> Any:
-        if isinstance(node, dict):
-            if "$ref" in node:
-                ref_name = node["$ref"].split("/")[-1]
-                if ref_name in definitions:
-                    return _resolve(definitions[ref_name])
-
-            return {
-                key: _resolve(value)
-                for key, value in node.items()
-                if key not in ("$defs", "definitions")
-            }
-
-        if isinstance(node, list):
-            return [_resolve(item) for item in node]
-
-        return node
-
-    return _resolve(schema)
 
 
 def sanitize_schema_for_llm(schema: Any, api_type: str) -> Any:
     """
     递归地净化 JSON Schema，移除特定 LLM API 不支持的关键字。
+
+    参数:
+        schema: 要净化的 JSON Schema (可以是字典、列表或其它类型)。
+        api_type: 目标 API 的类型，例如 'gemini'。
+
+    返回:
+        Any: 净化后的 JSON Schema。
     """
-    if isinstance(schema, list):
-        return [sanitize_schema_for_llm(item, api_type) for item in schema]
     if isinstance(schema, dict):
-        schema_copy = schema.copy()
+        schema_copy = {}
+        for key, value in schema.items():
+            if api_type == "gemini":
+                unsupported_keys = ["exclusiveMinimum", "exclusiveMaximum", "default"]
+                if key in unsupported_keys:
+                    continue
 
-        if api_type == "gemini":
+                if key == "format" and isinstance(value, str):
-            if "const" in schema_copy:
+                    supported_formats = ["enum", "date-time"]
-                schema_copy["enum"] = [schema_copy.pop("const")]
+                    if value not in supported_formats:
-
+                        continue
-            if "type" in schema_copy and isinstance(schema_copy["type"], list):
-                types_list = schema_copy["type"]
-                if "null" in types_list:
-                    schema_copy["nullable"] = True
-                    types_list = [t for t in types_list if t != "null"]
-                    if len(types_list) == 1:
-                        schema_copy["type"] = types_list[0]
-                    else:
-                        schema_copy["type"] = types_list
-
-            if "anyOf" in schema_copy:
-                any_of = schema_copy["anyOf"]
-                has_null = any(
-                    isinstance(x, dict) and x.get("type") == "null" for x in any_of
-                )
-                if has_null:
-                    schema_copy["nullable"] = True
-                    new_any_of = [
-                        x
-                        for x in any_of
-                        if not (isinstance(x, dict) and x.get("type") == "null")
-                    ]
-                    if len(new_any_of) == 1:
-                        schema_copy.update(new_any_of[0])
-                        schema_copy.pop("anyOf", None)
-                    else:
-                        schema_copy["anyOf"] = new_any_of
-
-            unsupported_keys = [
-                "exclusiveMinimum",
-                "exclusiveMaximum",
-                "default",
-                "title",
-                "additionalProperties",
-                "$schema",
-                "$id",
-            ]
-            for key in unsupported_keys:
-                schema_copy.pop(key, None)
-
-            if schema_copy.get("format") and schema_copy["format"] not in [
-                "enum",
-                "date-time",
-            ]:
-                schema_copy.pop("format", None)
-
-        elif api_type == "openai":
-            unsupported_keys = [
-                "default",
-                "minLength",
-                "maxLength",
-                "pattern",
-                "format",
-                "minimum",
-                "maximum",
-                "multipleOf",
-                "patternProperties",
-                "minItems",
-                "maxItems",
-                "uniqueItems",
-                "$schema",
-                "title",
-            ]
-            for key in unsupported_keys:
-                schema_copy.pop(key, None)
-
-            if "$ref" in schema_copy:
-                ref_key = schema_copy["$ref"].split("/")[-1]
-                defs = schema_copy.get("$defs") or schema_copy.get("definitions")
-                if defs and ref_key in defs:
-                    schema_copy.pop("$ref", None)
-                    schema_copy.update(defs[ref_key])
-                else:
-                    return {"$ref": schema_copy["$ref"]}
-
-            is_object = (
-                schema_copy.get("type") == "object" or "properties" in schema_copy
-            )
-            if is_object:
-                schema_copy["type"] = "object"
-                schema_copy["additionalProperties"] = False
-
-                properties = schema_copy.get("properties", {})
-                required = schema_copy.get("required", [])
-                if properties:
-                    existing_req = set(required)
-                    for prop in properties.keys():
-                        if prop not in existing_req:
-                            required.append(prop)
-                    schema_copy["required"] = required
-
-        for def_key in ["$defs", "definitions"]:
-            if def_key in schema_copy and isinstance(schema_copy[def_key], dict):
-                schema_copy[def_key] = {
-                    k: sanitize_schema_for_llm(v, api_type)
-                    for k, v in schema_copy[def_key].items()
-                }
-
-        recursive_keys = ["properties", "items", "allOf", "anyOf", "oneOf"]
-        for key in recursive_keys:
-            if key in schema_copy:
-                if key == "properties" and isinstance(schema_copy[key], dict):
-                    schema_copy[key] = {
-                        k: sanitize_schema_for_llm(v, api_type)
-                        for k, v in schema_copy[key].items()
-                    }
-                else:
-                    schema_copy[key] = sanitize_schema_for_llm(
-                        schema_copy[key], api_type
-                    )
 
+            schema_copy[key] = sanitize_schema_for_llm(value, api_type)
         return schema_copy
+
+    elif isinstance(schema, list):
+        return [sanitize_schema_for_llm(item, api_type) for item in schema]
+
     else:
         return schema
-
-
-def extract_text_from_content(
-    content: str | list[LLMContentPart] | None,
-) -> str:
-    """
-    从消息内容中提取纯文本，自动过滤非文本部分，防止污染 Prompt。
-    """
-    if content is None:
-        return ""
-    if isinstance(content, str):
-        return content
-    if isinstance(content, list):
-        return " ".join(
-            part.text for part in content if part.type == "text" and part.text
-        )
-    return str(content)
-
-
-def parse_and_validate_json(text: str, response_model: type[T]) -> T:
-    """
-    通用工具：尝试将文本解析为指定的 Pydantic 模型，并统一处理异常。
-    """
-    try:
-        return type_validate_json(response_model, text)
-    except (ValidationError, ValueError) as e:
-        try:
-            logger.warning(f"标准JSON解析失败，尝试使用json_repair修复: {e}")
-            repaired_obj = json_repair.loads(text, skip_json_loads=True)
-            return model_validate(response_model, repaired_obj)
-        except Exception as repair_error:
-            logger.error(
-                f"LLM结构化输出校验最终失败: {repair_error}",
-                e=repair_error,
-            )
-            raise LLMException(
-                "LLM返回的JSON未能通过结构验证。",
-                code=LLMErrorCode.RESPONSE_PARSE_ERROR,
-                details={
-                    "raw_response": text,
-                    "validation_error": str(repair_error),
-                    "original_error": repair_error,
-                },
-                cause=repair_error,
-            )
-    except Exception as e:
-        logger.error(f"解析LLM结构化输出时发生未知错误: {e}", e=e)
-        raise LLMException(
-            "解析LLM的JSON输出时失败。",
-            code=LLMErrorCode.RESPONSE_PARSE_ERROR,
-            details={"raw_response": text},
-            cause=e,
-        )
-
-
-def create_cot_wrapper(inner_model: type[BaseModel]) -> type[BaseModel]:
-    """
-    [动态运行时封装]
-    创建一个包含思维链 (Chain of Thought) 的包装模型。
-    强制模型在生成最终 JSON 结构前，先输出一个 reasoning 字段进行思考。
-    """
-    wrapper_name = f"CoT_{inner_model.__name__}"
-
-    return create_model(
-        wrapper_name,
-        reasoning=(
-            str,
-            Field(
-                ...,
-                min_length=10,
-                description=(
-                    "在生成最终结果之前，请务必在此字段中详细描述你的推理步骤、计算过程或思考逻辑。禁止留空。"
-                ),
-            ),
-        ),
-        result=(
-            inner_model,
-            Field(
-                ...,
-            ),
-        ),
-    )
-
-
-def should_apply_autocot(
-    requested: bool,
-    model_name: str | None,
-    config: Any,
-) -> bool:
-    """
-    [智能决策管道]
-    判断是否应该应用 AutoCoT (显式思维链包装)。
-    防止在模型已有原生思维能力时进行“双重思考”。
-    """
-    if not requested:
-        return False
-
-    if config:
-        thinking_budget = getattr(config, "thinking_budget", 0) or 0
-        if thinking_budget > 0:
-            return False
-        if getattr(config, "thinking_level", None) is not None:
-            return False
-
-    if model_name:
-        caps = get_model_capabilities(model_name)
-        if caps.reasoning_mode != ReasoningMode.NONE:
-            return False
-
-    return True

zhenxun/services/tags/manager.py

@@ -9,7 +9,6 @@ from typing import Any, ClassVar
 
 from aiocache import Cache, cached
 from arclet.alconna import Alconna, Args
-import nonebot
 from nonebot.adapters import Bot
 from tortoise.exceptions import IntegrityError
 from tortoise.expressions import Q
@@ -177,49 +176,6 @@ class TagManager:
         deleted_count = await GroupTag.filter(name=name).delete()
         return deleted_count > 0
 
-    @invalidate_on_change
-    async def remove_group_from_all_tags(self, group_id: str) -> int:
-        """
-        从所有静态标签中移除一个指定的群组ID。
-        主要用于机器人退群时的实时清理。
-
-        参数：
-            group_id: 要移除的群组ID。
-
-        返回：
-            被删除的关联数量。
-        """
-        deleted_count = await GroupTagLink.filter(group_id=group_id).delete()
-        if deleted_count > 0:
-            logger.info(f"已从 {deleted_count} 个标签中移除群组 {group_id} 的关联。")
-        return deleted_count
-
-    @invalidate_on_change
-    async def prune_stale_group_links(self) -> int:
-        """
-        清理所有静态标签中无效的群组关联。
-        无效指的是机器人已不再任何一个已连接的Bot的群组列表中。
-
-        返回：
-            被清理的无效关联的总数。
-        """
-        all_bot_group_ids = set()
-        for bot in nonebot.get_bots().values():
-            groups, _ = await PlatformUtils.get_group_list(bot)
-            all_bot_group_ids.update(g.group_id for g in groups if g.group_id)
-
-        all_static_links = await GroupTagLink.filter(tag__tag_type="STATIC").all()
-
-        stale_link_ids = [
-            link.id
-            for link in all_static_links
-            if link.group_id not in all_bot_group_ids
-        ]
-
-        if stale_link_ids:
-            return await GroupTagLink.filter(id__in=stale_link_ids).delete()
-        return 0
-
     @invalidate_on_change
     async def add_groups_to_tag(self, name: str, group_ids: list[str]) -> int:  # type: ignore
         """

zhenxun/utils/depends/__init__.py

@@ -1,7 +1,6 @@
 from typing import Any, Literal
 
 from nonebot.adapters import Bot, Event
-from nonebot.exception import SkippedException
 from nonebot.internal.params import Depends
 from nonebot.matcher import Matcher
 from nonebot.params import Command
@@ -10,7 +9,6 @@ from nonebot_plugin_session import EventSession
 from nonebot_plugin_uninfo import Uninfo
 
 from zhenxun.configs.config import Config
-from zhenxun.services import group_settings_service
 from zhenxun.utils.limiters import ConcurrencyLimiter, FreqLimiter, RateLimiter
 from zhenxun.utils.message import MessageUtils
 from zhenxun.utils.time_utils import TimeUtils
@@ -251,34 +249,6 @@ def GetConfig(
     return Depends(dependency)
 
 
-def GetGroupConfig(model: type[Any]):
-    """
-    依赖注入函数，用于获取并解析插件的分群配置。
-    """
-
-    async def dependency(matcher: Matcher, session: EventSession):
-        """
-        实际的依赖注入逻辑。
-        """
-        plugin_name = matcher.plugin_name
-        group_id = session.id3 or session.id2
-
-        if not plugin_name:
-            raise SkippedException("无法确定插件名称以获取配置")
-
-        if not group_id:
-            try:
-                return model()
-            except Exception:
-                raise SkippedException("在私聊中无法获取分群配置")
-
-        return await group_settings_service.get_all_for_plugin(
-            group_id, plugin_name, parse_model=model
-        )
-
-    return Depends(dependency)
-
-
 def CheckConfig(
     module: str | None = None,
     config: str | list[str] = "",

zhenxun/utils/enum.py

@@ -53,8 +53,6 @@ class CacheType(StrEnum):
     """全局全部插件"""
     GROUPS = "GLOBAL_ALL_GROUPS"
     """全局全部群组"""
-    GROUP_PLUGIN_SETTINGS = "GROUP_PLUGIN_SETTINGS"
-    """插件分群配置"""
     USERS = "GLOBAL_ALL_USERS"
     """全部用户"""
     BAN = "GLOBAL_ALL_BAN"
@@ -65,12 +63,6 @@ class CacheType(StrEnum):
     """用户权限"""
     LIMIT = "GLOBAL_LIMIT"
     """插件限制"""
-    TEMP = "TEMP"
-    """临时缓存"""
-    AUTH_SNAPSHOT = "AUTH_SNAPSHOT"
-    """权限快照（预聚合的用户+群组+Bot权限数据）"""
-    PLUGIN_SNAPSHOT = "PLUGIN_SNAPSHOT"
-    """插件快照（预聚合的插件配置数据）"""
 
 
 class DbLockType(StrEnum):

zhenxun/utils/http_utils.py

@@ -64,8 +64,6 @@ async def _():
     _client = get_async_client(
         headers=get_user_agent(),
         follow_redirects=True,
-        limits=httpx.Limits(max_connections=500, max_keepalive_connections=200),
-        timeout=httpx.Timeout(10),
         **client_kwargs,
     )
 

zhenxun/utils/log_sanitizer.py

@@ -14,34 +14,9 @@ def _truncate_base64_string(value: str, threshold: int = 256) -> str:
     if value.startswith(prefixes) and len(value) > threshold:
         prefix = next((p for p in prefixes if value.startswith(p)), "base64")
         return f"[{prefix}_data_omitted_len={len(value)}]"
-
-    if len(value) > 1000:
-        return f"[long_string_omitted_len={len(value)}] {value[:20]}...{value[-20:]}"
-
-    if len(value) > 2000:
-        return f"[long_string_omitted_len={len(value)}] {value[:50]}...{value[-20:]}"
-
     return value
 
 
-def _truncate_vector_list(vector: list, threshold: int = 10) -> list:
-    """如果列表过长（通常是embedding向量），则截断它用于日志显示。"""
-    if isinstance(vector, list) and len(vector) > threshold:
-        return [*vector[:3], f"...({len(vector)} floats omitted)...", *vector[-3:]]
-    return vector
-
-
-def _recursive_sanitize_any(obj: Any) -> Any:
-    """递归清洗任何对象中的长字符串"""
-    if isinstance(obj, dict):
-        return {k: _recursive_sanitize_any(v) for k, v in obj.items()}
-    elif isinstance(obj, list):
-        return [_recursive_sanitize_any(v) for v in obj]
-    elif isinstance(obj, str):
-        return _truncate_base64_string(obj)
-    return obj
-
-
 def _sanitize_ui_html(html_string: str) -> str:
     """
     专门用于净化UI渲染调试HTML的函数。
@@ -89,37 +64,6 @@ def _sanitize_openai_response(response_json: dict) -> dict:
                                 message["images"][i]["image_url"]["url"] = (
                                     _truncate_base64_string(url)
                                 )
-                    if "reasoning_details" in message and isinstance(
-                        message["reasoning_details"], list
-                    ):
-                        for detail in message["reasoning_details"]:
-                            if isinstance(detail, dict):
-                                if "data" in detail and isinstance(detail["data"], str):
-                                    if len(detail["data"]) > 100:
-                                        detail["data"] = (
-                                            f"[encrypted_data_omitted_len={len(detail['data'])}]"
-                                        )
-                                if "text" in detail and isinstance(detail["text"], str):
-                                    detail["text"] = _truncate_base64_string(
-                                        detail["text"], threshold=2000
-                                    )
-        if "data" in sanitized_json and isinstance(sanitized_json["data"], list):
-            for item in sanitized_json["data"]:
-                if "embedding" in item and isinstance(item["embedding"], list):
-                    item["embedding"] = _truncate_vector_list(item["embedding"])
-                if "b64_json" in item and isinstance(item["b64_json"], str):
-                    if len(item["b64_json"]) > 256:
-                        item["b64_json"] = (
-                            f"[base64_json_omitted_len={len(item['b64_json'])}]"
-                        )
-        if "input" in sanitized_json and isinstance(sanitized_json["input"], list):
-            for item in sanitized_json["input"]:
-                if "content" in item and isinstance(item["content"], list):
-                    for part in item["content"]:
-                        if isinstance(part, dict) and part.get("type") == "input_image":
-                            image_url = part.get("image_url")
-                            if isinstance(image_url, str):
-                                part["image_url"] = _truncate_base64_string(image_url)
         return sanitized_json
     except Exception:
         return response_json
@@ -127,44 +71,22 @@ def _sanitize_openai_response(response_json: dict) -> dict:
 
 def _sanitize_openai_request(body: dict) -> dict:
     """净化OpenAI兼容API的请求体，主要截断图片base64。"""
-    from zhenxun.services.llm.config.providers import (
-        DebugLogOptions,
-        get_llm_config,
-    )
-
-    debug_conf = get_llm_config().debug_log
-    if isinstance(debug_conf, bool):
-        debug_conf = DebugLogOptions(
-            show_tools=debug_conf, show_schema=debug_conf, show_safety=debug_conf
-        )
-
     try:
-        sanitized_json = _recursive_sanitize_any(copy.deepcopy(body))
+        sanitized_json = copy.deepcopy(body)
-        if "tools" in sanitized_json and not debug_conf.show_tools:
+        if "messages" in sanitized_json and isinstance(
-            tools = sanitized_json["tools"]
+            sanitized_json["messages"], list
-            if isinstance(tools, list):
+        ):
-                tool_names = []
+            for message in sanitized_json["messages"]:
-                for t in tools:
+                if "content" in message and isinstance(message["content"], list):
-                    if isinstance(t, dict):
+                    for i, part in enumerate(message["content"]):
-                        name = None
+                        if part.get("type") == "image_url":
-                        if "function" in t and isinstance(t["function"], dict):
+                            if "image_url" in part and isinstance(
-                            name = t["function"].get("name")
+                                part["image_url"], dict
-                        if not name and "name" in t:
+                            ):
-                            name = t.get("name")
+                                url = part["image_url"].get("url", "")
-                        tool_names.append(name or "unknown")
+                                message["content"][i]["image_url"]["url"] = (
-                sanitized_json["tools"] = (
+                                    _truncate_base64_string(url)
-                    f"<{len(tool_names)} tools hidden: {', '.join(tool_names)}>"
+                                )
-                )
-
-        if "response_format" in sanitized_json and not debug_conf.show_schema:
-            response_format = sanitized_json["response_format"]
-            if isinstance(response_format, dict):
-                if response_format.get("type") == "json_schema":
-                    sanitized_json["response_format"] = {
-                        "type": "json_schema",
-                        "json_schema": "<JSON Schema Hidden>",
-                    }
-
         return sanitized_json
     except Exception:
         return body
@@ -172,9 +94,6 @@ def _sanitize_openai_request(body: dict) -> dict:
 
 def _sanitize_gemini_response(response_json: dict) -> dict:
     """净化Gemini API的响应体，处理文本和图片生成两种格式。"""
-    from zhenxun.services.llm.config.providers import get_llm_config
-
-    debug_mode = get_llm_config().debug_log
     try:
         sanitized_json = copy.deepcopy(response_json)
 
@@ -195,15 +114,6 @@ def _sanitize_gemini_response(response_json: dict) -> dict:
                                     content["parts"][i]["inlineData"]["data"] = (
                                         f"[base64_data_omitted_len={len(data)}]"
                                     )
-                            if "thoughtSignature" in part:
-                                signature = part.get("thoughtSignature", "")
-                                if isinstance(signature, str) and len(signature) > 256:
-                                    content["parts"][i]["thoughtSignature"] = (
-                                        f"[signature_omitted_len={len(signature)}]"
-                                    )
-                if not debug_mode and isinstance(candidate, dict):
-                    if "safetyRatings" in candidate:
-                        candidate["safetyRatings"] = "<Safety Ratings Hidden>"
 
         if "candidates" in sanitized_json:
             _process_candidates(sanitized_json["candidates"])
@@ -214,19 +124,6 @@ def _sanitize_gemini_response(response_json: dict) -> dict:
             if "candidates" in sanitized_json["image_generation"]:
                 _process_candidates(sanitized_json["image_generation"]["candidates"])
 
-        if "embeddings" in sanitized_json and isinstance(
-            sanitized_json["embeddings"], list
-        ):
-            for embedding in sanitized_json["embeddings"]:
-                if "values" in embedding and isinstance(embedding["values"], list):
-                    embedding["values"] = _truncate_vector_list(embedding["values"])
-
-        if not debug_mode and "promptFeedback" in sanitized_json:
-            prompt_feedback = sanitized_json.get("promptFeedback") or {}
-            if isinstance(prompt_feedback, dict) and "safetyRatings" in prompt_feedback:
-                prompt_feedback["safetyRatings"] = "<Safety Ratings Hidden>"
-                sanitized_json["promptFeedback"] = prompt_feedback
-
         return sanitized_json
     except Exception:
         return response_json
@@ -234,46 +131,8 @@ def _sanitize_gemini_response(response_json: dict) -> dict:
 
 def _sanitize_gemini_request(body: dict) -> dict:
     """净化Gemini API的请求体，进行结构转换和总结。"""
-    from zhenxun.services.llm.config.providers import (
-        DebugLogOptions,
-        get_llm_config,
-    )
-
-    debug_conf = get_llm_config().debug_log
-    if isinstance(debug_conf, bool):
-        debug_conf = DebugLogOptions(
-            show_tools=debug_conf, show_schema=debug_conf, show_safety=debug_conf
-        )
-
     try:
         sanitized_body = copy.deepcopy(body)
-        if "tools" in sanitized_body and not debug_conf.show_tools:
-            tool_summary = []
-            for tool_group in sanitized_body["tools"]:
-                if (
-                    isinstance(tool_group, dict)
-                    and "functionDeclarations" in tool_group
-                ):
-                    declarations = tool_group["functionDeclarations"]
-                    if isinstance(declarations, list):
-                        for func in declarations:
-                            if isinstance(func, dict):
-                                tool_summary.append(func.get("name", "unknown"))
-            sanitized_body["tools"] = (
-                f"<{len(tool_summary)} functions hidden: {', '.join(tool_summary)}>"
-            )
-
-        if not debug_conf.show_safety and "safetySettings" in sanitized_body:
-            sanitized_body["safetySettings"] = "<Safety Settings Hidden>"
-
-        if not debug_conf.show_schema and "generationConfig" in sanitized_body:
-            generation_config = sanitized_body["generationConfig"]
-            if (
-                isinstance(generation_config, dict)
-                and "responseJsonSchema" in generation_config
-            ):
-                generation_config["responseJsonSchema"] = "<JSON Schema Hidden>"
-
         if "contents" in sanitized_body and isinstance(
             sanitized_body["contents"], list
         ):
@@ -294,13 +153,6 @@ def _sanitize_gemini_request(body: dict) -> dict:
                                 continue
                         new_parts.append(part)
 
-                        if "thoughtSignature" in part:
-                            sig = part["thoughtSignature"]
-                            if isinstance(sig, str) and len(sig) > 64:
-                                part["thoughtSignature"] = (
-                                    f"[signature_omitted_len={len(sig)}]"
-                                )
-
                     if media_summary:
                         summary_text = (
                             f"[多模态内容: {len(media_summary)}个文件 - "
@@ -343,5 +195,8 @@ def sanitize_for_logging(data: Any, context: str | None = None) -> Any:
     elif context == "ui_html":
         if isinstance(data, str):
             return _sanitize_ui_html(data)
+    else:
+        if isinstance(data, str):
+            return _truncate_base64_string(data)
 
-    return _recursive_sanitize_any(data)
+    return data

zhenxun/utils/manager/bot_profile_manager.py

@@ -141,7 +141,7 @@ class BotProfileManager:
         """构建BOT自我介绍图片"""
         profile, service_count, call_count = await asyncio.gather(
             cls.get_bot_profile(bot_id),
-            UserConsole.get_user_count(),
+            UserConsole.get_new_uid(),
             Statistics.filter(bot_id=bot_id).count(),
         )
         if not profile:

zhenxun/utils/message.py

@@ -3,7 +3,6 @@ from io import BytesIO
 from pathlib import Path
 
 import nonebot
-from nonebot.adapters import Bot
 from nonebot.adapters.onebot.v11 import Message, MessageSegment
 from nonebot_plugin_alconna import (
     At,
@@ -17,7 +16,6 @@ from nonebot_plugin_alconna import (
     Video,
     Voice,
 )
-from nonebot_plugin_uninfo import Uninfo
 from pydantic import BaseModel
 import ujson as json
 
@@ -106,32 +104,22 @@ class MessageUtils:
         cls,
         msg_list: MESSAGE_TYPE | list[MESSAGE_TYPE | list[MESSAGE_TYPE]],
         format_args: dict | None = None,
-        auto_forward_msg: Bot | Uninfo | None = None,
     ) -> UniMessage:
         """构造消息
 
         参数:
             msg_list: 消息列表
             format_args: 用于格式化字符串的参数字典.
-            auto_forward_msg: 是否自动转发消息
 
         返回:
             UniMessage: 构造完成的消息列表
         """
-        from zhenxun.utils.platform import PlatformUtils
-
         message_list = []
         if not isinstance(msg_list, list):
             msg_list = [msg_list]
         for m in msg_list:
             _data = m if isinstance(m, list) else [m]
             message_list += cls.__build_message(_data, format_args)
-        if auto_forward_msg and PlatformUtils.is_forward_merge_supported(
-            auto_forward_msg
-        ):
-            message_list = cls.alc_forward_msg(
-                message_list, auto_forward_msg.self_id, auto_forward_msg.self_id
-            )
         return UniMessage(message_list)
 
     @classmethod

zhenxun/utils/platform.py

@@ -18,6 +18,7 @@ from zhenxun.models.friend_user import FriendUser
 from zhenxun.models.group_console import GroupConsole
 from zhenxun.services.log import logger
 from zhenxun.utils.exception import NotFindSuperuser
+from zhenxun.utils.http_utils import AsyncHttpx
 from zhenxun.utils.message import MessageUtils
 
 driver = nonebot.get_driver()
@@ -225,8 +226,6 @@ class PlatformUtils:
             user_id: 用户id
             platform: 平台
         """
-        from zhenxun.utils.http_utils import AsyncHttpx
-
         url = None
         if platform == "qq":
             if user_id.isdigit():

zhenxun/utils/pydantic_compat.py

@@ -10,14 +10,8 @@ from enum import Enum
 from pathlib import Path
 from typing import Any, TypeVar, get_args, get_origin
 
-from nonebot.compat import (
+from nonebot.compat import PYDANTIC_V2, model_dump
-    PYDANTIC_V2,
+from pydantic import VERSION, BaseModel
-    model_dump,
-    model_fields,
-    type_validate_json,
-    type_validate_python,
-)
-from pydantic import BaseModel
 import ujson as json
 
 T = TypeVar("T", bound=BaseModel)
@@ -30,16 +24,11 @@ __all__ = [
     "_is_pydantic_type",
     "compat_computed_field",
     "dump_json_safely",
-    "model_construct",
     "model_copy",
     "model_dump",
-    "model_dump_json",
-    "model_fields",
     "model_json_schema",
     "model_validate",
     "parse_as",
-    "type_validate_json",
-    "type_validate_python",
 ]
 
 
@@ -56,30 +45,14 @@ def model_copy(
         return model.copy(update=update_dict, deep=deep)
 
 
-def model_construct(model_class: type[T], **kwargs: Any) -> T:
-    """
-    Pydantic `model_construct` (v2) 与 `construct` (v1) 的兼容函数。
-    """
-    if PYDANTIC_V2:
-        return model_class.model_construct(**kwargs)
-    else:
-        return model_class.construct(**kwargs)
-
-
 def model_validate(model_class: type[T], obj: Any) -> T:
     """
-    Pydantic 模型验证兼容函数。
+    Pydantic `model_validate` (v2) 与 `parse_obj` (v1) 的兼容函数。
-    """
-    return type_validate_python(model_class, obj)
-
-
-def model_dump_json(model: BaseModel, **kwargs: Any) -> str:
-    """
-    Pydantic `model.json()` (v1) 和 `model.model_dump_json()` (v2) 的兼容函数。
     """
     if PYDANTIC_V2:
-        return model.model_dump_json(**kwargs)
+        return model_class.model_validate(obj)
-    return model.json(**kwargs)
+    else:
+        return model_class.parse_obj(obj)
 
 
 if PYDANTIC_V2:
@@ -94,7 +67,8 @@ def model_json_schema(model_class: type[BaseModel], **kwargs: Any) -> dict[str,
     """
     if PYDANTIC_V2:
         return model_class.model_json_schema(**kwargs)
-    return model_class.schema(by_alias=kwargs.get("by_alias", True))
+    else:
+        return model_class.schema(by_alias=kwargs.get("by_alias", True))
 
 
 def _is_pydantic_type(t: Any) -> bool:
@@ -123,7 +97,18 @@ def _dump_pydantic_obj(obj: Any) -> Any:
     return obj
 
 
-parse_as = type_validate_python
+def parse_as(type_: type[V], obj: Any) -> V:
+    """
+    一个兼容 Pydantic V1 的 parse_obj_as 和V2的TypeAdapter.validate_python 的辅助函数。
+    """
+    if VERSION.startswith("1"):
+        from pydantic import parse_obj_as
+
+        return parse_obj_as(type_, obj)
+    else:
+        from pydantic import TypeAdapter  # type: ignore
+
+        return TypeAdapter(type_).validate_python(obj)
 
 
 def dump_json_safely(obj: Any, **kwargs) -> str:

zhenxun/utils/utils.py

@@ -9,7 +9,6 @@ from types import TracebackType
 from typing import Any, ClassVar
 
 import httpx
-from nonebot_plugin_session import EventSession, Session
 from nonebot_plugin_uninfo import Uninfo
 import pypinyin
 
@@ -210,7 +209,7 @@ def is_valid_date(date_text: str, separator: str = "-") -> bool:
         return False
 
 
-def get_entity_ids(session: Uninfo | EventSession) -> EntityIDs:
+def get_entity_ids(session: Uninfo) -> EntityIDs:
     """获取用户id，群组id，频道id
 
     参数:
@@ -219,21 +218,16 @@ def get_entity_ids(session: Uninfo | EventSession) -> EntityIDs:
     返回:
         EntityIDs: 用户id，群组id，频道id
     """
-    if isinstance(session, Session):
+    user_id = session.user.id
-        user_id = session.id1
+    group_id = None
-        group_id = session.id2
+    channel_id = None
-        channel_id = session.id3
+    if session.group:
-    else:
+        if session.group.parent:
-        user_id = session.user.id
+            group_id = session.group.parent.id
-        group_id = session.group.id if session.group else None
+            channel_id = session.group.id
-        channel_id = session.channel.id if session.channel else None
+        else:
-        if session.group:
+            group_id = session.group.id
-            if session.group.parent:
+    return EntityIDs(user_id=user_id, group_id=group_id, channel_id=channel_id)
-                group_id = session.group.parent.id
-                channel_id = session.group.id
-            else:
-                group_id = session.group.id
-    return EntityIDs(user_id=user_id or "", group_id=group_id, channel_id=channel_id)
 
 
 def is_number(text: str) -> bool:

zhenxun/utils/withdraw_manage.py

@@ -8,11 +8,9 @@ from nonebot.adapters import Bot
 from nonebot.adapters.onebot.v11 import Bot as v11Bot
 from nonebot.adapters.onebot.v12 import Bot as v12Bot
 from nonebot_plugin_session import EventSession
-from nonebot_plugin_uninfo import Uninfo
 from ruamel.yaml.comments import CommentedSeq
 
 from zhenxun.services.log import logger
-from zhenxun.utils.utils import get_entity_ids
 
 
 class WithdrawManager:
@@ -20,9 +18,7 @@ class WithdrawManager:
     _index = 0
 
     @classmethod
-    def check(
+    def check(cls, session: EventSession, withdraw_time: tuple[int, int]) -> bool:
-        cls, session: Uninfo | EventSession, withdraw_time: tuple[int, int]
-    ) -> bool:
         """配置项检查
 
         参数:
@@ -32,17 +28,12 @@ class WithdrawManager:
         返回:
             bool: 是否允许撤回
         """
-        entity_ids = get_entity_ids(session)
         if withdraw_time[0] and withdraw_time[0] > 0:
             if withdraw_time[1] == 2:
                 return True
-            if withdraw_time[1] == 1 and entity_ids.group_id:
+            if withdraw_time[1] == 1 and (session.id2 or session.id3):
                 return True
-            if (
+            if withdraw_time[1] == 0 and not session.id2 and not session.id3:
-                withdraw_time[1] == 0
-                and not entity_ids.group_id
-                and not entity_ids.channel_id
-            ):
                 return True
         return False