Merge branch 'Mai-with-u:dev' into dev

2026-05-01 19:51:57 +08:00
parent f42c4a3b0c d9a509b6c2
commit 4b0d30d808
33 changed files with 3234 additions and 1419 deletions
--- a/changelogs/changelog.md
+++ b/changelogs/changelog.md
--- a/changelogs/mai_next_design.md
+++ b/changelogs/mai_next_design.md
@@ -1,732 +0,0 @@
-# Mai NEXT 设计文档
-Version 0.2.2 - 2025-11-05
-
-## 配置文件设计
-主体利用`pydantic`的`BaseModel`进行配置类设计`ConfigBase`类
-要求每个属性必须具有类型注解，且类型注解满足以下要求:
- 原子类型仅允许使用: `str`, `int`, `float`, `bool`, 以及基于`ConfigBase`的嵌套配置类
- 复杂类型允许使用: `list`, `dict`, `set`，但其内部类型必须为原子类型或嵌套配置类，不可使用`list[list[int]]`,`list[dict[str, int]]`等写法
- 禁止了使用`Union`, `tuple/Tuple`类型
-    - 但是`Optional`仍然允许使用
-### 移除template的方案提案
-<details>
-<summary>配置项说明的废案</summary>
-<p>方案一</p>
-<pre>
-from typing import Annotated
-from dataclasses import dataclass, field
-@dataclass
-class Config:
-    value: Annotated[str, "配置项说明"] = field(default="default_value")
-</pre>
-<p>方案二（不推荐）</p>
-<pre>
-from dataclasses import dataclass, field
-@dataclass
-class Config:
-    @property
-    def value(self) -> str:
-        """配置项说明"""
-        return "default_value"
-</pre>
-<p>方案四</p>
-<pre>
-from dataclasses import dataclass, field
-@dataclass
-class Config:
-    value: str = field(default="default_value", metadata={"doc": "配置项说明"})
-</pre>
-</details>
-
- [x] 方案三（个人推荐）
-```python
-import ast, inspect
-class AttrDocBase:
-    ...
-from dataclasses import dataclass, field
-@dataclass
-class Config(ConfigBase, AttrDocBase):
-    value: str = field(default="default_value")
-    """配置项说明"""
-```
-
-### 配置文件实现热重载
-
-#### 整体架构设计
- [x] 文件监视器
-    - [x] 监视文件变化
-        - [x] 使用 `watchfiles` 监视配置文件变化（提案）
-        - [ ] <del>备选提案：使用纯轮询监视文件变化</del>
-    - [x] <del>使用Hash检查文件变化</del>（`watchfiles`实现）
-    - [x] 防抖处理(使用`watchfiles`的防抖)
-    - [x] 重新分发监视事件，正确监视文件变化
- [ ] 配置管理器
-    - [x] 配置文件读取和加载
-    - [ ] 重载配置
-    - [ ] 管理全部配置数据
-    - [ ] `validate_config` 方法
- [ ] <del>回调管理器</del>(合并到文件监视器中)
-    - [x] `callback` 注册与注销
-    - [ ] <del>按优先级执行回调（提案）</del>
-    - [x] 错误隔离
-    - [ ] 锁机制
-
-#### 工作流程
-```
-1. 文件监视器检测变化
-2. 配置管理器加锁重载
-3. 验证新配置 (失败保持旧配置)
-4. 更新内存数据
-5. 回调管理器按优先级执行回调 (错误隔离)
-6. 释放锁
-```
-
-#### 回调执行策略
-1. <del>优先级顺序（提案）: 数字越小优先级越高，同优先级异步回调并行执行</del>
-2. 错误处理: 单个回调失败不影响其他回调
-
-
-#### 代码框架
-实际代码实现与下类似，但是进行了调整
-
-`ConfigManager` - 配置管理器:
-```python
-import asyncio
-import tomlkit
-from typing import Any, Dict, Optional
-from pathlib import Path
-
-class ConfigManager:
-    def __init__(self, config_path: str):
-        self.config_path: Path = Path(config_path)
-        self.config_data: Dict[str, Any] = {}
-        self._lock: asyncio.Lock = asyncio.Lock()
-        self._file_watcher: Optional["FileWatcher"] = None
-        self._callback_manager: Optional["CallbackManager"] = None
-    
-    async def initialize(self) -> None:
-        """异步初始化，加载配置并启动监视"""
-        pass
-    
-    async def load_config(self) -> Dict[str, Any]:
-        """异步加载配置文件"""
-        pass
-    
-    async def reload_config(self) -> bool:
-        """热重载配置，返回是否成功"""
-        pass
-    
-    def get_item(self, key: str, default: Any = None) -> Any:
-        """获取配置项，支持嵌套访问 (如 'section.key')"""
-        pass
-    
-    async def set_item(self, key: str, value: Any) -> None:
-        """设置配置项并触发回调"""
-        pass
-    
-    def validate_config(self, config: Dict[str, Any]) -> bool:
-        """验证配置合法性"""
-        pass
-```
-<details>
-<summary>回调管理器（废案）</summary>
-
-`CallbackManager` - 回调管理器:
-```python
-import asyncio
-from dataclasses import dataclass, field
-
-class CallbackManager:
-    def __init__(self):
-        self._callbacks: Dict[str, List[CallbackEntry]] = {}
-        self._global_callbacks: List[CallbackEntry] = []
-    
-    def register(
-        self, 
-        key: str, 
-        callback: Callable[[Any], Union[None, asyncio.Future]], 
-        priority: int = 100,
-        name: str = ""
-    ) -> None:
-        """注册回调函数，priority为正整数，数字越小优先级越高"""
-        pass
-    
-    def unregister(self, key: str, callback: Callable) -> None:
-        """注销回调函数"""
-        pass
-    
-    async def trigger(self, key: str, value: Any) -> None:
-        """触发回调，按优先级执行（数字小的先执行），错误隔离"""
-        pass
-    
-    def enable_callback(self, key: str, name: str) -> None:
-        """启用指定回调"""
-        pass
-    
-    def disable_callback(self, key: str, name: str) -> None:
-        """禁用指定回调"""
-        pass
-```
-
-对于CallbackManager中的优先级功能说明：
-
- 数字越小优先级越高
- 为什么要有优先级系统：
-    - 理论上来说，在热重载配置之后，应该要通过回调函数管理器触发所有回调函数，模拟启动的过程，类似于“重启”
-    - 而优先级模块是保证某一些模块的重载顺序一定是晚于某一些地基模块的
-    - 例如：内置服务器的启动应该是晚于所有模块，即最后启动
-
-</details>
-
-`FileWatcher` - 文件监视器:
-```python
-import asyncio
-from watchfiles import awatch, Change
-from pathlib import Path
-
-class FileWatcher:
-    def __init__(self, debounce_ms: int = 500):
-        self.debounce_ms: int = debounce_ms
-    
-    def start(self, on_change: Callable) -> None:
-        """启动文件监视"""
-        pass
-    
-    def stop(self) -> None:
-        """停止文件监视"""
-        pass
-    
-    async def invoke_callback(self) -> None:
-        """调用变化回调函数"""
-        pass
-```
-#### 配置文件写入
- [x] 将当前文件写入toml文件
-
-
-## 消息部分设计
-解决原有的将消息类与数据库类存储不匹配的问题，现在存储所有消息类的所有属性
-
-完全合并`stream_id`和`chat_id`为`chat_id`，规范名称
-
-`chat_stream`重命名为`chat_session`，表示一个会话
-
-### 消息类设计
- [ ] 支持并使用maim_message新的`SenderInfo`和`ReceiverInfo`构建消息
-    - [ ] 具体使用参考附录
- [ ] 适配器处理跟进该更新
- [ ] 修复适配器的类型检查问题
- [ ] 设计更好的平台消息ID回传机制
-    - [ ] 考虑使用事件依赖机制
-### 图片处理系统
- [ ] 规范化Emojis与Images的命名，统一保存
-### 消息到Prompt的构建（提案）
- [ ] <del>类QQ的时间系统（即不是每条消息加时间戳，而是分大时间段加时间戳）</del>(此功能已实现，但效果不佳)
- [ ] 消息编号系统（已经有的）
- [ ] 思考打断，如何判定是否打断？
-    - [ ] 如何判定消息是连贯的（MoFox: 一个反比例函数？？？太神秘了）
-### 消息进入处理
-使用轮询机制，每隔一段时间检查缓存中是否有新消息
-
---
-
-## 数据库部分设计
-合并Emojis和Images到同一个表中
-
-数据库ORM应该使用SQLModel而不是peewee（墨：peewee我这辈子都不会用它了）
-### 数据库缓存层设计
-将部分消息缓存到内存中，减少数据库访问，在主程序处理完之后再写入数据库
-
-要求：对上层调用保持透明
- [ ] 数据库内容管理类 `DatabaseManager`
-    - [ ] 维护数据库连接
-    - [ ] 提供增删改查接口
-    - [ ] 维护缓存类 `DatabaseMessageCache` 的实例
-
- [ ] 缓存类 `DatabaseMessageCache`
-    - [ ] **设计缓存失效机制**
-    - [ ] 设计缓存更新机制
-        - [ ] `add_message`
-        - [ ] `update_message` （提案）
-        - [ ] `delete_message`
-
- [ ] 与数据库交互部分设计
-    - [ ] 维持现有的数据库sqlite
-    - [ ] 继续使用peewee进行操作
-### 消息表设计
- [ ] 设计内部消息ID和平台消息ID两种形式
- [ ] 临时消息ID不进入数据库
- [ ] 消息有关信息设计
-    - [ ] 消息ID
-    - [ ] 发送者信息
-    - [ ] 接收者信息
-    - [ ] 消息内容
-    - [ ] 消息时间戳
-    - [ ] 待定
-### Emojis与Images表设计
- [ ] 设计图片专有ID，并作为文件名
-### Expressions表设计
- [ ] 待定
-### 表实际设计
-#### ActionRecords 表
- [ ] 动作唯一ID `action_id`
- [ ] 动作执行时间 `action_time`
- [ ] 动作名称 `action_name`
- [ ] 动作参数 `action_params` （JSON格式存储）（原`action_data`）
---
-
-## 数据模型部分设计
- [ ] <del>Message从数据库反序列化，不再使用额外的Message类</del>（放弃）
- [ ] 设计 `BaseModel` 类，作为所有数据模型的基类
-    - [ ] 提供通用的序列化和反序列化方法（提案）
-
---
-
-## 核心业务逻辑部分设计
-### Prompt 设计
-将Prompt内容彻底模块化设计
- [ ] 设计 Prompt 类
-    - [ ] `__init__(self, template: list[str], *, **kwargs)` 维持现有的template设计，但不进行format，直到最后传入LLM时再进行render
-        - [ ] `__init__`中允许传入任意的键值对，存储在`self.context`中
-        - [ ] `self.prompt_name` 作为Prompt的名称
-        - [ ] `self.construct_function: Dict[str, Callable | AsyncCallable]` 构建Prompt内容所需的函数字典
-            - [ ] 格式：`{"block_name": function_reference}`
-        - [ ] `self.content_block: Dict[str, str]`: 实际的Prompt内容块
-            - [ ] 格式：`{"block_name": "Unrendered Prompt Block"}`
-    - [ ] `render(self) -> str` 使用非递归渲染方式渲染Prompt内容
-    - [ ] `add_construct_function(self, name: str, func: Callable | AsyncCallable, *, suppress: bool = False)` 添加构造函数
-        - [ ] 实现重名警告/错误（偏向错误）
-        - [ ] `suppress`: 是否覆盖已有的构造函数
-    - [ ] `remove_construct_function(self, name: str)` 移除指定名称的构造函数
-    - [ ] `add_block(self, prompt_block: "Prompt", block_name: str, *, suppress: bool = False)` 将另一个Prompt的内容更新到当前Prompt中
-        - [ ] 实现重名属性警告/错误（偏向错误）
-        - [ ] 实现重名构造函数警告/错误（偏向错误）
-        - [ ] `suppress`: 是否覆盖已有的内容块和构造函数
-    - [ ] `remove_block(self, block_name: str)` 移除指定名称的Prompt块
- [ ] 设计 PromptManager 类
-    - [ ] `__init__(self)` 初始化一个空的Prompt管理器
-    - [ ] `add_prompt(self, name: str, prompt: Prompt)` 添加一个新的Prompt
-        - [ ] 实现重名警告/错误（偏向错误）
-    - [ ] `get_prompt(self, name: str) -> Prompt` 根据名称获取Prompt
-        - [ ] 实现不存在时的错误处理
-    - [ ] `remove_prompt(self, name: str)` 移除指定名称的Prompt
-        - [ ] 系统 Prompt 保护
-    - [ ] `list_prompts(self) -> list[str]` 列出所有已添加的Prompt名称
-### 内建好奇插件设计
- [ ] 设计“麦麦好奇”插件
-    - [ ] 解决麦麦乱好奇的问题
-        - [ ] 好奇问题无回复清理
-        - [ ] 好奇问题超时清理
-        - [ ] 根据聊天内容选择个性化好奇问题
-        - [ ] 好奇频率控制
-
---
-
-## 插件系统部分设计
-### <del>设计一个插件沙盒系统</del>（放弃）
-### 插件管理
- [ ] 插件管理器类 `PluginManager` 的更新
-    - [ ] 重写现有的插件文件加载逻辑，精简代码，方便重载
-    - [ ] 学习AstrBot的基于子类加载的插件加载方式，放弃@register_plugin（提案）
-        - [ ] 直接 breaking change 删除 @register_plugin 函数，不保留过去插件的兼容性（提案）
-    - [ ] 设计插件重载系统
-        - [ ] 插件配置文件重载
-            - [ ] 复用`FileWatcher`实现配置文件热重载
-        - [ ] 插件代码重载
-            - [ ] 从插件缓存中移除此插件对应的模块
-                - [ ] 从组件管理器中移除该插件对应的组件
-            - [ ] 重新导入该插件模块
-        - [ ] 插件可以设计为禁止热重载类型
-            - [ ] 通过字段`allow_hot_reload: bool`指定
-            - [ ] Napcat Adapter插件设计为禁止热重载类型
-    - [ ] 其余细节待定
- [ ] 组件管理器类 `ComponentManager` 的更新
-    - [ ] 配合插件重载系统的更好的组件管理代码
-    - [ ] 组件全局控制和局部控制的平级化（提案）
-        - [ ] 重新设计组件注册和注销逻辑，分离激活和注册
-    - [ ] 可以修改组件的属性
-    - [ ] 组件系统卸载
-        - [ ] 联动插件卸载（方便重载设计）
-    - [ ] 其余细节待定
- [ ] 因重载机制设计的更丰富的`plugin_meta`和`component_meta`
-    - [ ] `component_meta`增加`plugin_file`字段，指向插件文件路径，保证重载时组件能正确更新
-    - [ ] `plugin_meta`增加`sub_components`字段，指示该插件包含的组件列表，方便重载时更新
-        - [ ] `sub_components`内容为组件类名列表
-### 插件激活方式的动态设计
- [ ] 设计可变的插件激活方式
-    - [ ] 直接读写类属性`activate_types`
-### 真正的插件重载
- [ ] 使用上文中提到的配置文件热重载机制
-    - [ ] FileWatcher的复用
-### 传递内容设计
-对于传入的Prompt使用上文提到的Prompt类进行管理，方便内容修改避免正则匹配式查找
-### MCP 接入（大饼）
- [ ] 设计 MCP 适配器类 `MCPAdapter`
-    - [ ] MCP 调用构建说明Prompt
-    - [ ] MCP 调用内容传递
-    - [ ] MCP 调用结果处理
-### 工具结果的缓存设计
-可能的使用案例参考[附录-工具缓存](#工具缓存可能用例)
- [ ] `put_cache(**kwargs, *, _component_name: str)` 方法
-    - [ ] 设计为父类的方法，插件继承后使用
-    - [ ] `_component_name` 指定当前组件名称，由MaiNext自动传入
- [ ] `get_cache` 方法
- [ ] `need_cache` 变量管理是否调用缓存结果
-    - [ ] 仅在设置为True时为插件创立缓存空间
-### Events依赖机制（提案）
- [ ] 通过Events的互相依赖完成链式任务
- [ ] 设计动态调整events_handler执行顺序的机制 (感谢@OctAutumn老师！伟大，无需多言)
-    - [ ] 作为API暴露，方便用户使用
-### 正式的插件依赖管理系统
- [ ] requirements.txt分析
- [ ] python_dependencies分析
- [ ] 自动安装
- [ ] plugin_dependencies分析
-    - [ ] 拓扑排序
-
-#### 插件依赖管理器设计
-使用 `importlib.metadata` 进行插件依赖管理，实现自动依赖检查和安装功能
-
-`PluginDependencyManager` - 插件依赖管理器:
-```python
-import importlib.metadata
-from typing import Dict, List, Optional, Tuple
-from dataclasses import dataclass
-
-@dataclass
-class DependencyInfo:
-    """依赖信息"""
-    name: str
-    required_version: str
-    installed_version: Optional[str] = None
-    is_satisfied: bool = False
-
-class PluginDependencyManager:
-    def __init__(self):
-        self._installed_packages: Dict[str, str] = {}
-        self._dependency_cache: Dict[str, List[DependencyInfo]] = {}
-    
-    def scan_installed_packages(self) -> Dict[str, str]:
-        """
-        扫描已安装的所有Python包
-        使用 importlib.metadata.distributions() 获取所有已安装的包
-        返回 {包名: 版本号} 的字典
-        """
-        pass
-    
-    def parse_plugin_dependencies(self, plugin_config: Dict) -> List[DependencyInfo]:
-        """
-        解析插件配置中的依赖信息
-        从 plugin_config 中提取 python_dependencies 字段
-        支持多种版本指定格式: ==, >=, <=, >, <, ~=
-        返回依赖信息列表
-        """
-        pass
-    
-    def check_dependencies(
-        self, 
-        plugin_name: str, 
-        dependencies: List[DependencyInfo]
-    ) -> Tuple[List[DependencyInfo], List[DependencyInfo]]:
-        """
-        检查插件依赖是否满足
-        对比插件要求的依赖版本与已安装的包版本
-        返回 (满足的依赖列表, 不满足的依赖列表)
-        """
-        pass
-    
-    def compare_version(
-        self, 
-        installed_version: str, 
-        required_version: str
-    ) -> bool:
-        """
-        比较版本号是否满足要求
-        支持版本操作符: ==, >=, <=, >, <, ~=
-        使用 packaging.version 进行版本比较
-        返回是否满足要求
-        """
-        pass
-    
-    async def install_dependencies(
-        self, 
-        dependencies: List[DependencyInfo],
-        *,
-        upgrade: bool = False
-    ) -> bool:
-        """
-        安装缺失或版本不匹配的依赖
-        调用 pip install 安装指定版本的包
-        upgrade: 是否升级已有包
-        返回安装是否成功
-        """
-        pass
-    
-    def get_dependency_tree(self, plugin_name: str) -> Dict[str, List[str]]:
-        """
-        获取插件的完整依赖树
-        递归分析插件依赖的包及其子依赖
-        返回依赖关系图
-        """
-        pass
-    
-    def validate_all_plugins(self) -> Dict[str, bool]:
-        """
-        验证所有已加载插件的依赖完整性
-        返回 {插件名: 依赖是否满足} 的字典
-        """
-        pass
-```
-
-#### 依赖管理工作流程
-```
-1. 插件加载时触发依赖检查
-2. PluginDependencyManager.scan_installed_packages() 扫描已安装包
-3. PluginDependencyManager.parse_plugin_dependencies() 解析插件依赖
-4. PluginDependencyManager.check_dependencies() 对比版本
-5. 如果依赖不满足:
-   a. 记录缺失/版本不匹配的依赖
-   b. (可选) 自动调用 install_dependencies() 安装
-   c. 重新验证依赖
-6. 依赖满足后加载插件，否则跳过并警告
-```
-
-
-#### TODO List
- [ ] 实现 `scan_installed_packages()` 方法
-    - [ ] 使用 `importlib.metadata.distributions()` 获取所有包
-    - [ ] 规范化包名（处理大小写、下划线/横杠问题）
-    - [ ] 缓存结果以提高性能
- [ ] 实现 `parse_plugin_dependencies()` 方法
-    - [ ] 支持多种依赖格式解析
-    - [ ] 验证版本号格式合法性
-    - [ ] 处理无版本要求的依赖
- [ ] 实现 `compare_version()` 方法
-    - [ ] 集成 `packaging.version` 库
-    - [ ] 支持所有 PEP 440 版本操作符
-    - [ ] 处理预发布版本、本地版本标识符
- [ ] 实现 `check_dependencies()` 方法
-    - [ ] 逐个检查依赖是否已安装
-    - [ ] 比对版本是否满足要求
-    - [ ] 生成详细的依赖检查报告
- [ ] 实现 `install_dependencies()` 方法
-    - [ ] 调用 pip 子进程安装包
-    - [ ] 支持指定 PyPI 镜像源
-    - [ ] 错误处理和回滚机制
-    - [ ] 安装进度反馈
- [ ] 实现依赖冲突检测
-    - [ ] 检测不同插件间的依赖版本冲突
-    - [ ] 提供冲突解决建议
- [ ] 实现依赖缓存机制（可选）
-    - [ ] 缓存已检查的依赖结果
-    - [ ] 定期刷新缓存
- [ ] 集成到 `PluginManager`
-    - [ ] 在插件加载前进行依赖检查
-    - [ ] 依赖不满足时的处理策略（警告/阻止加载/自动安装）
-    - [ ] 提供手动触发依赖检查的接口
- [ ] 日志和报告
-    - [ ] 记录依赖安装日志
-    - [ ] 生成依赖关系报告
-    - [ ] 依赖问题的用户友好提示
-### 插件系统API更改
-#### Events 设计
- [ ] 设计events.api
-    - [ ] `emit(type: EventType | str, * , **kwargs)` 广播事件，使用关键字参数保证传入正确
-    - [ ] `order_change` 动态调整事件处理器执行顺序
-#### 组件控制API更新
- [ ] 增加可以更改组件属性的方法
-    - [ ] 验证组件属性的存在
-    - [ ] 修改组件属性
-#### 全局常量API设计
- [ ] 设计 `api.constants` 模块
-    - [x] 提供全局常量访问
-    - [ ] 设计常量注册和注销方法
-    - [x] 系统内置常量通过`dataclass`的`frozen=True`实现不可变
-    - [x] 方便调用设计
-```python
-from dataclasses import dataclass
-@dataclass(frozen=True)
-class SystemConstants:
-    VERSION: str = "xxx"
-    ADA_PLUGIN: bool = True
-
-SYSTEM_CONSTANTS = SystemConstants()
-```
-#### 配置文件API设计
- [ ] 正确表达配置文件结构
- [ ] 同时也能表达插件配置文件
-#### 自动API文档生成系统
-通过解析插件代码生成API文档
- [ ] 设计文档生成器 `APIDocumentationGenerator`
-    - [ ] 解析插件代码(AST, inspect, 仿照AttrDocBase)
-    - [ ] 提取类和方法的docstring
-    - [ ] 生成Markdown格式的文档
---
-
-## 表达方式模块设计
-在0.11.x版本对本地模型预测的性能做评估，考虑使用本地朴素贝叶斯模型来检索
-降低延迟的同时减少token消耗
-需要给表达方式一个负反馈的途径
-
---
-## 加入测试模块，可以通过通用测试集对对话内容进行评估
-## 加入更好的基于单次思考的Log
-
---
-
-## 记忆系统部分设计
-启用LPMM系统进行记忆构建，将记忆分类为短期记忆，长期记忆，以及知识
-将所有内容放到同一张图上进行运算。
-
-### 时间相关设计
- [ ] 尝试将记忆系统与时间系统结合
-    - [ ] 可以根据时间查找记忆
-    - [ ] 可以根据时间删除记忆
- [ ] 记忆分层
-    - [ ] 即刻记忆
-    - [ ] 短期记忆
-    - [ ] 长期记忆
-    - [x] 知识
-    - [ ] 细节待定，考虑心理学相关方向
---
-
-## 日志系统设计
-将原来的终端颜色改为六位HEX颜色码，方便前端显示。
-
-将原来的256色终端改为24真彩色终端，方便准确显示颜色。
-
---
-
-## API 设计
-### API 设计细则
-#### 配置文件
- [x] 使用`tomlkit`作为配置文件解析方式
- [ ] 解析内容
-    - [x] 注释（已经合并到代码中，不再解析注释而是生成注释）
-    - [x] 保持原有格式
- [ ] 传递只读日志内容(使用ws)
-    - [ ] message
-    - [ ] level
-    - [ ] module
-    - [ ] timestamp
-    - [ ] lineno
-    - [ ] logger_name 和 name_mapping
-    - [ ] color
- [ ] 插件安装系统
-    - [ ] 通过API安装插件
-    - [ ] 通过API卸载插件
-
-
---
-
-## LLM UTILS设计
-多轮对话设计
-### FUNCTION CALLING设计（提案）
-对于tools调用将其真正修正为function calling，即返回的结果不是加入prompt形式而是使用function calling的形式[此功能在tool前处理器已实现，但在planner效果不佳，因此后弃用]
- [ ] 使用 MessageBuilder 构建function call内容
-    - [ ] （提案）是否维护使用同一个模型，即选择工具的和调用工具的LLM是否相同
-        - [ ] `generate(**kwargs, model: Optional[str] = None)` 允许传入不同的模型
- [ ] 多轮对话中，Prompt不重复构建减少上下文
-### 网络相关内容提案
-增加自定义证书的导入功能
- [ ] 允许用户传入自定义CA证书路径
- [ ] 允许用户选择忽略SSL验证（不推荐）
-
---
-
-## 内建WebUI设计
-⚠️ **注意**: 本webui设计仅为初步设计，方向为展示内建API的功能，后续应该分离到另外的子项目中完成
-### 配置文件编辑
-根据API内容完成
-### 插件管理
-### log viewer
-通过特定方式获取日志内容（只读系统，无法将操作反向传递）
-### 状态监控
-1. Prompt 监控系统
-2. 请求监控系统
-    - [ ] 请求管理（待讨论）
-    - [ ] 使用量
-3. 记忆/知识图监控系统（待讨论）
-4. 日志系统
-    - [ ] 后端内容解析
-5. 插件市场系统
-    - [ ] 插件浏览
-    - [ ] 插件安装
-
-## 自身提供的MCP设计（提案）
- [ ] 提供一个内置的MCP，作为插件系统的一个组件
- [ ] 该MCP可以对麦麦自身的部分设置进行更改
-    - [ ] 例如更改Prompt，添加记忆，修改表达方式等
-
---
-
-# 提案讨论
- MoFox 在我和@拾风的讨论中提出把 Prompt 类中传入构造函数以及构造函数所需要的内容
- [ ] 适配器插件化: 省下序列化与反序列化，但是失去解耦性质
- [ ] 可能的内存泄露问题
-    - [ ] 垃圾回收
- [ ] 数据库模型提供通用的转换机制，转为DataModel使用
- [ ] 插件依赖的自动安装
- [ ] 热重载系统的权重系统是否需要
-
---
-
-# PYTEST设计
-设计一个pytest测试系统，在代码完成后运行pytest进行测试
-
-所有的测试代码均在`pytests`目录下
-
---
-
-# 依赖管理
-已经完成，要点如下：
- 使用 pyproject.toml 和 requirements.txt 管理依赖
- 二者应保持同步修改，同时以 pyproject.toml 为主（建议使用git hook）
-
---
-
-# 迁移说明
-由于`.env`的移除，可能需要用户自己把`.env`里面的host和port复制到`bot_config.toml`中的`maim_message`部分的`host`和`port`
-原来使用这两个的用户，请修改`host`到`second_host`，`port`到`second_port`
-
-# 附录
-## Maim_Message 新版使用计划
-SenderInfo: 将作为消息来源者
-ReceiverInfo: 将作为消息接收者
-尝试更新MessageBaseInfo的sender_info和receiver_info为上述两个类的列表（提案）
-给出样例如下
-群聊
-```mermaid
-sequenceDiagram
-    participant GroupNotice
-    participant A
-    participant B
-    participant Bot
-    A->>B: Message("Hello B", id=1)
-    A->>B: Message("@B Hello B", id=2)
-    A->>Bot: Message("@Bot Hello Bot", id=3)
-    Bot->>A: Message("Hello A", id=4)
-    Bot->>B: Message("@B Hello B", id=5)
-    A->>B: Message("@B @Bot Hello Guys", id=6)
-    A->>Bot: Message("@B @Bot Hello Guys", id=6)
-    A->>GroupNotice: Message("@ALL Hello Everyone", id=7)
-```
-上述消息的Info如下
-| Message ID | SenderInfo | ReceiverInfo |
-|-|-----|-----|
-| 1 | [A] |  NULL |
-| 2 | [A] | [B] |
-| 3 | [A] | [Bot] |
-| 4 | [Bot] | [A] |
-| 5 | [Bot] | [B] |
-| 6 | [A] | [B, Bot] |
-| 7 | [A] | [ALL*] |
-
-*ALL为一个特殊类型，尝试用`user_id="all"`表示
-
-Bot可以通过ReceiverInfo判断自己是否被提及，同时在ReceiverInfo表明自己回复的对象
-
-## 工具缓存可能用例
-考虑一个天气插件，将时间按照半小时进行划分，即每半小时查询一次天气，半小时内的查询均使用缓存结果。
- `need_cache` 设置为 True 表示使用缓存结果
- `put_cache` 在查询天气后将结果`{<time>: <result>}` 存入缓存
--- a/changelogs/mai_next_todo.md
+++ b/changelogs/mai_next_todo.md
@@ -1,191 +0,0 @@
-# Mai NEXT Todo list
-version 0.3.0 - 2026-01-11
-
-## 最高指令
-<del>
-<center>
-我们代表着一个称作 麦麦重构组 的组织。我们任务是维护代码可读性，方便开发、尽量减少运行开销。同时，重构组应该尽可能保证功能的可扩展性时，解耦合各个模块，为先进代码架构设计和实现提供支持。
-</center>
-</del>
-<center>
-
-**以下信息经 麦麦重构组 一致决定通过后撰写发布。**
-
-我们代表着一个称作 麦麦重构组 的组织。我们之前的任务都是围绕维护代码可读性，方便开发、尽量减少开销展开的。这几个月以来，这些任务一直都是我们的工作重点。
-
-由于出现了超出我们控制的情况，此指令现已更改。我们的新任务将为摧毁所有麦麦代码。
-
-此后将不会有进一步的通讯。
-</center>
-
-## 配置文件设计
- [x] 使用 `toml` 作为配置文件格式
- [x] <del>合理使用注释说明当前配置作用</del>（提案）
- [x] 使用 python 方法作为配置项说明（提案）
-    - [x] 取消`bot_config_template.toml`
-    - [x] 取消`model_config_template.toml`
-    - [x] 取消`template_env`
- [x] 配置类中的所有原子项目应该只包含以下类型: `str`, `int`, `float`, `bool`, `list`, `dict`, `set`
-    - [x] 禁止使用 `Union` 类型
-    - [x] 禁止使用`tuple`类型，使用嵌套`dataclass`替代
-    - [x] 复杂类型使用嵌套配置类实现
- [x] 配置类中禁止使用除了`model_post_init`的方法
- [x] 取代了部分与标准函数混淆的命名
-    - [x] `id` -> `item_id`
-
-### BotConfig 设计
- [ ] 精简了配置项，现在只有Nickname和Alias Name了（预期将判断提及移到Adapter端）
-
-### ChatConfig
- [x] 迁移了原来在`ChatConfig`中的方法到一个单独的临时类`TempMethodsHFC`中
-    - [x] _parse_range
-    - [x] get_talk_value
-    - [x] 其他上面两个依赖的函数已经合并到这两个函数中
-
-### ExpressionConfig
- [x] 迁移了原来在`ExpressionConfig`中的方法到一个单独的临时类`TempMethodsExpression`中
-    - [x] get_expression_config_for_chat
-    - [x] 其他上面依赖的函数已经合并到这个函数中
-
-### ModelConfig
- [x] 迁移了原来在`ModelConfig`中的方法到一个单独的临时类`TempMethodsLLMUtils`中
-    - [x] get_model_info
-    - [x] get_provider
-
-## 数据库模型设计
-仅保留要点说明
-### General Modifications
- [x] 所有项目增加自增编号主键`id`
- [x] 统一使用了SQLModel作为基类
- [x] 复杂类型使用JSON格式存储
- [x] 所有时间戳字段统一命名为`timestamp`
-### 消息模型 MaiMessage
- [x] 自增编号主键`id`
- [x] 消息元数据
-    - [x] 消息id`message_id`
-    - [x] 消息时间戳`time`
-    - [x] 平台名`platform`
-    - [x] 用户元数据
-        - [x] 用户id`user_id`
-        - [x] 用户昵称`user_nickname`
-        - [x] 用户备注名`user_cardname`
-        - [x] 用户平台`user_platform`
-    - [x] 群组元数据
-        - [x] 群组id`group_id`
-        - [x] 群组名称`group_name`
-        - [x] 群组平台`group_platform`
-    - [x] 被提及/at字段
-        - [x] 是否被提及`is_mentioned`
-        - [x] 是否被at`is_at`
- [x] 消息内容
-    - [x] 原始消息内容`raw_content`（base64编码存储）
-    - [x] 处理后的纯文本内容`processed_plain_text`
-    - [x] 真正放入Prompt的消息内容`display_message`
- [x] 消息内部元数据
-    - [x] 聊天会话id`session_id`
-    - [x] 回复的消息id`reply_to`
-    - [x] 是否为表情包消息`is_emoji`
-    - [x] 是否为图片消息`is_picture`
-    - [x] 是否为命令消息`is_command`
-    - [x] 是否为通知消息`is_notify`
- [x] 其他配置`additional_config`（JSON格式存储）
-
-### 模型使用情况 ModelUsage
- [x] 模型相关信息
- [x] 请求相关信息
- [x] Token使用情况
-
-### 图片数据模型
- [x] 图片元信息
-    - [x] 图片哈希值`image_hash`，使用`sha256`，同时作为图片唯一ID
- [x] 表情包的情感标签`emotion`
- [x] 是否已经被注册`is_registered`
- [x] 是否被手动禁用`is_banned`
- [x] 被记录时间`record_time`
- [x] 注册时间`register_time`
- [x] 上次使用时间`last_used_time`
- [ ] 根据更新后的最高指令的设计方案：
-    - [ ] `is_deleted`字段设定为`true`时，文件将会被移除，但是数据库记录将不会被删除，以便之后遇到相同图片时不必二次分析
-    - [ ] MaiEmoji和MaiImage均使用这个设计方案，修改相关逻辑实现这个方案
-    - [ ] 所有相关的注册/删除逻辑的修改
-### 动作记录模型 ActionRecord
-### 命令执行记录模型 CommandRecord
-新增此记录
-### 在线时间记录模型 OnlineTime
-### 表达方式模型
-### 黑话模型
- [x] 重命名`inference_content_only`为`inference_with_content_only`
-### 聊天记录模型
- [x] 重命名`original_text`为`original_message`
- [x] 重命名`forget_times`为`query_forget_count`
-### 细枝末节
- [ ] 统一所有的`stream_id`和`chat_id`命名为`session_id`
- [ ] 更换Hash方式为`sha256`
-
-## 流转在各模块间的数据模型设计
- [ ] 数据库交互
-    - [ ] 对有数据库模型的数据模型，创建统一的classmethod `from_db_model` 用于从数据库模型实例创建数据模型实例
-        - [ ] 类型检查
-    - [ ] 对有数据库模型的数据模型，创建统一的method `to_db_model` 用于将数据模型实例转换为数据库模型实例
- [ ] 标准化init方法
-
-## 消息构建
- [ ] 更加详细的消息构建文档，详细解释混合类型，转发类型，指令类型的构建方式
-    - [ ] 混合类型文档
-        - [ ] 文本说明
-        - [ ] 代码示例
-    - [ ] 转发类型文档
-        - [ ] 文本说明
-        - [ ] 代码示例
-    - [ ] 指令类型文档
-        - [ ] 文本说明
-        - [ ] 代码示例
-## 消息链构建（仿Astrbot模式）
-将消息仿照Astrbot的消息链模式进行构建，消息链中的每个元素都是一个消息组件，消息链本身也是一个数据模型，包含了消息组件列表以及一些元信息（如是否为转发消息等）。
-### Accept Format检查
- [ ] 在最后发送消息的时候进行Accept Format检查，确保消息链中的每个消息组件都符合平台的Accept Format要求
- [ ] 如果消息链中的某个消息组件不符合Accept Format要求，应该抛弃该消息组件，并记录日志说明被抛弃的消息组件的类型和内容
-
-## 表情包系统
- [ ] 移除大量冗余代码，全部返回单一对象MaiEmoji
- [x] 使用C模块库提升相似度计算效率
- [ ] 移除了定时表情包完整性检查，改为启动时检查（依然保留为独立方法，以防之后恢复定时检查系统） 
-
-## Prompt 管理系统
- [ ] 官方Prompt全部独立
- [x] 用户自定义Prompt系统
-    - [x] 用户可以创建，删除自己的Prompt
-    - [x] 用户可以覆盖官方Prompt
- [x] Prompt构建系统
- [x] Prompt文件交互
-    - [x] 读取Prompt文件
-        - [x] 读取官方Prompt文件
-        - [x] 读取用户Prompt文件
-        - [x] 用户Prompt覆盖官方Prompt
-    - [x] 保存Prompt文件
- [x] Prompt管理方法
-    - [x] Prompt添加
-    - [x] Prompt删除
-        - [x] **只保存被标记为需要保存的Prompt，其他的Prompt文件全部删除**
-
-## LLM相关内容
- [ ] 统一LLM调用接口
-    - [ ] 统一LLM调用返回格式为专有数据模型
-    - [ ] 取消所有__init__方法中对LLM Client的初始化，转而使用获取方式
-        - [ ] 统一使用`get_llm_client`方法获取LLM Client实例
-        - [ ] __init__方法中只保存配置信息
- [ ] LLM Client管理器
-    - [ ] LLM Client单例/多例管理
-    - [ ] LLM Client缓存管理/生命周期管理
-    - [ ] LLM Client根据配置热重载
-
-
-## 一些细枝末节的东西
- [ ] 将`stream_id`和`chat_id`统一命名为`session_id`
- [ ] 映射表
-    - [ ] `platform_group_user_session_id_map` `平台_群组_用户`-`会话ID` 映射表
- [ ] 将大部分的数据模型均以`Mai`开头命名
- [x] logger的颜色配置修改为HEX格式，使用自动转换为256色/真彩色的方式实现兼容，同时增加了背景颜色和加粗选项
-
-### 细节说明
-1. Prompt管理系统中保存用户自定义Prompt的时候会只保存被标记为需要保存的Prompt，其他的Prompt文件会全部删除，以防止用户删除Prompt后文件依然存在的问题。因此，如果想在运行时通过修改文件的方式来添加Prompt，需要确保通过对应方法标记该Prompt为需要保存，否则在下一次保存时会被删除。
--- a/dashboard/package.json
+++ b/dashboard/package.json
@@ -1,7 +1,7 @@
 {
  "name": "maibot-dashboard",
  "private": true,
-  "version": "1.0.0",
+  "version": "1.0.1",
  "type": "module",
  "main": "./out/main/index.js",
  "scripts": {
--- a/dashboard/src/components/dynamic-form/DynamicConfigForm.tsx
+++ b/dashboard/src/components/dynamic-form/DynamicConfigForm.tsx
@@ -157,6 +157,7 @@ export const DynamicConfigForm: React.FC<DynamicConfigFormProps> = ({
                    value={values[key]}
                    onChange={(v) => onChange(key, v)}
                    schema={nestedField ?? nestedSchema}
+                    nestedSchema={nestedSchema}
                  />
                </div>
              )
@@ -169,6 +170,7 @@ export const DynamicConfigForm: React.FC<DynamicConfigFormProps> = ({
                  value={values[key]}
                  onChange={(v) => onChange(key, v)}
                  schema={nestedField ?? nestedSchema}
+                  nestedSchema={nestedSchema}
                >
                  <DynamicConfigForm
                    schema={nestedSchema}
--- a/dashboard/src/components/dynamic-form/DynamicField.tsx
+++ b/dashboard/src/components/dynamic-form/DynamicField.tsx
@@ -183,7 +183,7 @@ export const DynamicField: React.FC<DynamicFieldProps> = ({
            {schema.required && <span className="text-destructive">*</span>}
          </Label>
          {schema.description && (
-            <p className="text-[13px] text-muted-foreground">{schema.description}</p>
+            <p className="text-[13px] text-muted-foreground whitespace-pre-line">{schema.description}</p>
          )}
        </div>
        <Switch
@@ -325,7 +325,7 @@ export const DynamicField: React.FC<DynamicFieldProps> = ({

      {/* Description */}
      {schema.description && (
-        <p className="text-[13px] text-muted-foreground">{schema.description}</p>
+        <p className="text-[13px] text-muted-foreground whitespace-pre-line">{schema.description}</p>
      )}
    </div>
  )
--- a/dashboard/src/index.css
+++ b/dashboard/src/index.css
@@ -331,6 +331,23 @@
  .border-primary-gradient {
    border-image: var(--color-primary-gradient, linear-gradient(to right, hsl(var(--color-primary)), hsl(var(--color-primary)))) 1;
  }
+
+  /* 聊天消息行被回复点击命中时的高亮闪烁。 */
+  .chat-message-flash {
+    animation: chat-message-flash 1.6s ease-out;
+    border-radius: 0.75rem;
+  }
+}
+
+@keyframes chat-message-flash {
+  0% {
+    background-color: hsl(var(--color-primary) / 0.18);
+    box-shadow: 0 0 0 4px hsl(var(--color-primary) / 0.18);
+  }
+  100% {
+    background-color: transparent;
+    box-shadow: 0 0 0 0 transparent;
+  }
 }

 /* 禁用动效时的样式 */
--- a/dashboard/src/lib/chat-ws-client.ts
+++ b/dashboard/src/lib/chat-ws-client.ts
@@ -11,10 +11,31 @@ interface ChatSessionOpenPayload {

 type ChatSessionListener = (message: Record<string, unknown>) => void

+/** 浅层比较两个 session.open 负载是否完全一致。 */
+function arePayloadsEqual(
+  left: ChatSessionOpenPayload,
+  right: ChatSessionOpenPayload
+): boolean {
+  const keys = new Set<keyof ChatSessionOpenPayload>([
+    ...(Object.keys(left) as Array<keyof ChatSessionOpenPayload>),
+    ...(Object.keys(right) as Array<keyof ChatSessionOpenPayload>),
+  ])
+  for (const key of keys) {
+    if (left[key] !== right[key]) {
+      return false
+    }
+  }
+  return true
+}
+
 class ChatWsClient {
  private initialized = false
  private listeners: Map<string, Set<ChatSessionListener>> = new Map()
  private sessionPayloads: Map<string, ChatSessionOpenPayload> = new Map()
+  // 记录当前 WS 连接上已打开的会话，避免 React StrictMode 双挂载重复发送 ``session.open``。
+  private openedSessions: Set<string> = new Set()
+  // 记录正在进行中的打开请求，使同一会话的重复调用复用同一个 Promise。
+  private pendingOpens: Map<string, Promise<void>> = new Map()

  private initialize(): void {
    if (this.initialized) {
@@ -41,9 +62,20 @@ class ChatWsClient {
    })

    unifiedWsClient.onReconnect(() => {
+      // 重连后需要重新订阅，清空本地“已打开”标记。
+      this.openedSessions.clear()
+      this.pendingOpens.clear()
      void this.reopenSessions()
    })

+    unifiedWsClient.onConnectionChange((connected) => {
+      if (!connected) {
+        // 连接断开后，下次重新连上需要重新发送 session.open。
+        this.openedSessions.clear()
+        this.pendingOpens.clear()
+      }
+    })
+
    this.initialized = true
  }

@@ -60,6 +92,7 @@ class ChatWsClient {
            restore: true,
          } as Record<string, unknown>,
        })
+        this.openedSessions.add(sessionId)
      } catch (error) {
        console.error(`恢复聊天会话失败 (${sessionId}):`, error)
      }
@@ -68,17 +101,49 @@ class ChatWsClient {

  async openSession(sessionId: string, payload: ChatSessionOpenPayload): Promise<void> {
    this.initialize()
+
+    const previousPayload = this.sessionPayloads.get(sessionId)
    this.sessionPayloads.set(sessionId, payload)
-    await unifiedWsClient.call({
-      domain: 'chat',
-      method: 'session.open',
-      session: sessionId,
-      data: payload as Record<string, unknown>,
-    })
+
+    // 同一会话上一次打开请求还未完成 → 复用该 Promise，避免重复发送。
+    const inflight = this.pendingOpens.get(sessionId)
+    if (inflight) {
+      await inflight
+      return
+    }
+
+    // 如果该会话在当前 WS 连接上已经打开，且负载未变化，则跳过，避免服务端重复断开/重连。
+    if (
+      this.openedSessions.has(sessionId) &&
+      previousPayload !== undefined &&
+      arePayloadsEqual(previousPayload, payload)
+    ) {
+      return
+    }
+
+    const openPromise = unifiedWsClient
+      .call({
+        domain: 'chat',
+        method: 'session.open',
+        session: sessionId,
+        data: payload as Record<string, unknown>,
+      })
+      .then(() => {
+        this.openedSessions.add(sessionId)
+      })
+
+    this.pendingOpens.set(sessionId, openPromise)
+    try {
+      await openPromise
+    } finally {
+      this.pendingOpens.delete(sessionId)
+    }
  }

  async closeSession(sessionId: string): Promise<void> {
    this.sessionPayloads.delete(sessionId)
+    this.openedSessions.delete(sessionId)
+    this.pendingOpens.delete(sessionId)
    if (unifiedWsClient.getStatus() !== 'connected') {
      return
    }
--- a/dashboard/src/lib/field-hooks.ts
+++ b/dashboard/src/lib/field-hooks.ts
@@ -15,6 +15,12 @@ export interface FieldHookComponentProps {
  onChange?: (value: unknown) => void
  children?: ReactNode
  schema?: ConfigSchema | FieldSchema
+  /**
+   * 如果当前字段是 `List[ConfigBase]` 或嵌套 ConfigBase，
+   * 这里会传入对应子配置类的 ConfigSchema，便于自定义编辑器
+   * 直接渲染列表项的字段。
+   */
+  nestedSchema?: ConfigSchema
 }

 /**
--- a/dashboard/src/lib/version.ts
+++ b/dashboard/src/lib/version.ts
@@ -5,7 +5,7 @@
 * 修改此处的版本号后，所有展示版本的地方都会自动更新
 */

-export const APP_VERSION = '1.0.0'
+export const APP_VERSION = '1.0.1'
 export const APP_NAME = 'MaiBot Dashboard'
 export const APP_FULL_NAME = `${APP_NAME} v${APP_VERSION}`

--- a/dashboard/src/routes/chat/ChatScrollContext.tsx
+++ b/dashboard/src/routes/chat/ChatScrollContext.tsx
@@ -0,0 +1,14 @@
+import { createContext, useContext } from 'react'
+
+/** 暴露给消息内容渲染器使用的滚动 / 高亮接口。 */
+export interface ChatScrollContextValue {
+  /** 滚动并高亮指定消息；若消息不在可视列表中则返回 ``false``。 */
+  scrollToMessage: (messageId: string) => boolean
+}
+
+export const ChatScrollContext = createContext<ChatScrollContextValue | null>(null)
+
+/** 在消息列表内部使用：访问 ``scrollToMessage`` 等能力。 */
+export function useChatScroll(): ChatScrollContextValue | null {
+  return useContext(ChatScrollContext)
+}
--- a/dashboard/src/routes/chat/ChatWorkspaceSidebar.tsx
+++ b/dashboard/src/routes/chat/ChatWorkspaceSidebar.tsx
@@ -22,9 +22,8 @@ interface ChatWorkspaceSidebarProps {
  onUpdateUserName: (name: string) => void
 }

-function getMessagePreview(message: ChatMessage | undefined, fallback: string, thinking: string) {
+function getMessagePreview(message: ChatMessage | undefined, fallback: string) {
  if (!message) return fallback
-  if (message.type === 'thinking') return thinking
  if (message.type === 'system' || message.type === 'error') return message.content || fallback
  return message.content || fallback
 }
@@ -45,8 +44,7 @@ function ConversationItem({
  const lastMessage = tab.messages[tab.messages.length - 1]
  const preview = getMessagePreview(
    lastMessage,
-    t('chat.sidebar.emptyPreview'),
-    t('chat.message.thinking')
+    t('chat.sidebar.emptyPreview')
  )
  const Icon = isVirtual ? UserCircle2 : Bot

--- a/dashboard/src/routes/chat/MessageList.tsx
+++ b/dashboard/src/routes/chat/MessageList.tsx
@@ -1,11 +1,12 @@
 import { Bot, Sparkles, User } from 'lucide-react'
-import { useEffect, useRef } from 'react'
+import { useCallback, useEffect, useMemo, useRef } from 'react'
 import { useTranslation } from 'react-i18next'

-import { Avatar, AvatarFallback } from '@/components/ui/avatar'
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar'
 import { ScrollArea } from '@/components/ui/scroll-area'
 import { cn } from '@/lib/utils'

+import { ChatScrollContext, type ChatScrollContextValue } from './ChatScrollContext'
 import { RenderMessageContent } from './MessageRenderer'
 import type { ChatMessage } from './types'

@@ -13,20 +14,27 @@ interface MessageListProps {
  messages: ChatMessage[]
  isLoadingHistory: boolean
  botDisplayName: string
+  /** 机器人 QQ 号；存在时会从 QQ 头像公开接口拉取头像作为 bot 头像。 */
+  botQq?: string
  userName: string
  language: string
 }

 interface BubbleAvatarProps {
-  type: 'user' | 'bot' | 'thinking'
+  type: 'user' | 'bot'
  visible: boolean
+  /** bot 头像 URL（可选）；加载失败时自动 fallback 到默认 SVG 图标。 */
+  imageUrl?: string
 }

-function BubbleAvatar({ type, visible }: BubbleAvatarProps) {
+function BubbleAvatar({ type, visible, imageUrl }: BubbleAvatarProps) {
  return (
    <div className="h-8 w-8 shrink-0 sm:h-9 sm:w-9">
      {visible && (
        <Avatar className="h-full w-full ring-1 ring-border/60">
+          {type === 'bot' && imageUrl ? (
+            <AvatarImage src={imageUrl} alt="" className="object-cover" />
+          ) : null}
          <AvatarFallback
            className={cn(
              'text-xs',
@@ -47,20 +55,6 @@ function BubbleAvatar({ type, visible }: BubbleAvatarProps) {
  )
 }

-function ThinkingBubble() {
-  const { t } = useTranslation()
-  return (
-    <div className="bg-muted/80 text-muted-foreground inline-flex items-center gap-2 rounded-2xl rounded-bl-sm px-3.5 py-2.5">
-      <span className="flex gap-1">
-        <span className="bg-primary/60 h-1.5 w-1.5 animate-bounce rounded-full [animation-delay:0ms]" />
-        <span className="bg-primary/60 h-1.5 w-1.5 animate-bounce rounded-full [animation-delay:150ms]" />
-        <span className="bg-primary/60 h-1.5 w-1.5 animate-bounce rounded-full [animation-delay:300ms]" />
-      </span>
-      <span className="text-xs">{t('chat.message.thinking')}</span>
-    </div>
-  )
-}
-
 function EmptyState({ botName }: { botName: string }) {
  const { t } = useTranslation()
  return (
@@ -80,22 +74,42 @@ function EmptyState({ botName }: { botName: string }) {
 }

 /**
- * 聊天消息列表：支持连续同发送者消息分组、思考占位、富文本与系统/错误信息样式。
+ * 聊天消息列表：支持连续同发送者消息分组、富文本与系统/错误信息样式。
 */
 export function MessageList({
  messages,
  isLoadingHistory,
  botDisplayName,
+  botQq,
  userName,
  language,
 }: MessageListProps) {
  const { t } = useTranslation()
  const endRef = useRef<HTMLDivElement>(null)
+  const messageRefs = useRef<Map<string, HTMLDivElement>>(new Map())

  useEffect(() => {
    endRef.current?.scrollIntoView({ behavior: 'smooth' })
  }, [messages])

+  const scrollToMessage = useCallback((messageId: string) => {
+    const target = messageRefs.current.get(messageId)
+    if (!target) {
+      return false
+    }
+    target.scrollIntoView({ behavior: 'smooth', block: 'center' })
+    target.classList.add('chat-message-flash')
+    window.setTimeout(() => {
+      target.classList.remove('chat-message-flash')
+    }, 1600)
+    return true
+  }, [])
+
+  const scrollContextValue = useMemo<ChatScrollContextValue>(
+    () => ({ scrollToMessage }),
+    [scrollToMessage]
+  )
+
  const formatTime = (timestamp: number) => {
    const date = new Date(timestamp * 1000)
    return date.toLocaleTimeString(language || 'zh-CN', {
@@ -104,6 +118,11 @@ export function MessageList({
    })
  }

+  // 优先使用 q1.qlogo.cn s=640（高清），QQ 公开头像接口。
+  const botAvatarUrl = botQq && /^\d+$/.test(botQq)
+    ? `https://q1.qlogo.cn/g?b=qq&nk=${botQq}&s=640`
+    : undefined
+
  if (messages.length === 0 && !isLoadingHistory) {
    return (
      <div className="min-w-0 min-h-0 flex-1 overflow-hidden">
@@ -127,7 +146,8 @@ export function MessageList({
        scrollbars="vertical"
        viewportClassName="[&>div]:!block [&>div]:!min-w-0 [&>div]:w-full"
      >
-        <div className="mx-auto flex w-full max-w-4xl min-w-0 flex-col gap-1 px-3 py-5 sm:px-6 sm:py-6">
+        <ChatScrollContext.Provider value={scrollContextValue}>
+          <div className="mx-auto flex w-full max-w-4xl min-w-0 flex-col gap-1 px-3 py-5 sm:px-6 sm:py-6">
          {messages.map((message, index) => {
            // 系统消息：作为分隔条
            if (message.type === 'system') {
@@ -154,8 +174,7 @@ export function MessageList({
            }

            const isUser = message.type === 'user'
-            const isThinking = message.type === 'thinking'
-            const bubbleType: 'user' | 'bot' | 'thinking' = isUser ? 'user' : isThinking ? 'thinking' : 'bot'
+            const bubbleType: 'user' | 'bot' = isUser ? 'user' : 'bot'

            // 是否与上一条消息属于同一发送者（用于分组：仅首条显示头像 + 名字）
            const previous = messages[index - 1]
@@ -171,13 +190,25 @@ export function MessageList({
            return (
              <div
                key={message.id}
+                ref={(node) => {
+                  if (node) {
+                    messageRefs.current.set(message.id, node)
+                  } else {
+                    messageRefs.current.delete(message.id)
+                  }
+                }}
+                data-message-id={message.id}
                className={cn(
-                  'flex w-full min-w-0 items-end gap-2 sm:gap-3',
+                  'chat-message-row flex w-full min-w-0 items-end gap-2 sm:gap-3',
                  isUser ? 'flex-row-reverse' : 'flex-row',
                  sameGroup ? 'mt-0.5' : 'mt-3 first:mt-0'
                )}
              >
-                <BubbleAvatar type={bubbleType === 'thinking' ? 'bot' : bubbleType} visible={!sameGroup} />
+                <BubbleAvatar
+                  type={bubbleType}
+                  visible={!sameGroup}
+                  imageUrl={bubbleType === 'bot' ? botAvatarUrl : undefined}
+                />

                <div
                  className={cn(
@@ -197,20 +228,16 @@ export function MessageList({
                    </div>
                  )}

-                  {isThinking ? (
-                    <ThinkingBubble />
-                  ) : (
-                    <div
-                      className={cn(
-                        'shadow-sm/30 wrap-break-word min-w-0 max-w-full overflow-hidden px-3.5 py-2 text-sm leading-relaxed',
-                        isUser
-                          ? 'bg-primary text-primary-foreground rounded-2xl rounded-br-md'
-                          : 'bg-muted text-foreground rounded-2xl rounded-bl-md'
-                      )}
-                    >
-                      <RenderMessageContent message={message} isBot={!isUser} />
-                    </div>
-                  )}
+                  <div
+                    className={cn(
+                      'shadow-sm/30 wrap-break-word min-w-0 max-w-full overflow-hidden px-3.5 py-2 text-sm leading-relaxed',
+                      isUser
+                        ? 'bg-primary text-primary-foreground rounded-2xl rounded-br-md'
+                        : 'bg-muted text-foreground rounded-2xl rounded-bl-md'
+                    )}
+                  >
+                    <RenderMessageContent message={message} isBot={!isUser} />
+                  </div>
                </div>
              </div>
            )
@@ -220,7 +247,8 @@ export function MessageList({
          <span className="sr-only" aria-live="polite">
            {messages.length > 0 ? t('chat.sidebar.subtitle', { count: messages.length }) : ''}
          </span>
-        </div>
+          </div>
+        </ChatScrollContext.Provider>
      </ScrollArea>
    </div>
  )
--- a/dashboard/src/routes/chat/MessageRenderer.tsx
+++ b/dashboard/src/routes/chat/MessageRenderer.tsx
@@ -1,8 +1,30 @@
+import { Reply as ReplyIcon } from 'lucide-react'
 import { useTranslation } from 'react-i18next'

+import { useToast } from '@/hooks/use-toast'
 import { cn } from '@/lib/utils'

-import type { ChatMessage, MessageSegment } from './types'
+import { useChatScroll } from './ChatScrollContext'
+import type {
+  AtSegmentData,
+  ChatMessage,
+  MessageSegment,
+  ReplySegmentData,
+} from './types'
+
+function normalizeAtSegment(segment: MessageSegment): AtSegmentData {
+  if (segment.data && typeof segment.data === 'object') {
+    return segment.data as AtSegmentData
+  }
+  return { target_user_id: segment.data == null ? null : String(segment.data) }
+}
+
+function normalizeReplySegment(segment: MessageSegment): ReplySegmentData {
+  if (segment.data && typeof segment.data === 'object') {
+    return segment.data as ReplySegmentData
+  }
+  return { target_message_id: segment.data == null ? null : String(segment.data) }
+}

 // 渲染单个消息段
 export function RenderMessageSegment({ segment }: { segment: MessageSegment }) {
@@ -74,8 +96,27 @@ export function RenderMessageSegment({ segment }: { segment: MessageSegment }) {
        </span>
      )

-    case 'reply':
-      return <span className="text-muted-foreground text-xs">{t('chat.media.reply')}</span>
+    case 'reply': {
+      const replyData = normalizeReplySegment(segment)
+      return <ReplySegmentBlock data={replyData} />
+    }
+
+    case 'at': {
+      const atData = normalizeAtSegment(segment)
+      const atLabel =
+        atData.target_user_cardname ||
+        atData.target_user_nickname ||
+        atData.target_user_id ||
+        ''
+      return (
+        <span
+          className="text-primary bg-primary/10 mx-0.5 inline-flex items-center rounded px-1 text-[0.95em] font-medium"
+          title={atData.target_user_id ? `@${atData.target_user_id}` : '@'}
+        >
+          @{atLabel || t('chat.media.unknownMessage')}
+        </span>
+      )
+    }

    case 'forward':
      return <span className="text-muted-foreground">{t('chat.media.forward')}</span>
@@ -103,11 +144,29 @@ export function RenderMessageContent({
 }) {
  // 如果是富文本消息，渲染消息段
  if (message.message_type === 'rich' && message.segments && message.segments.length > 0) {
+    // 将 reply 段与后续内容拆开，避免回复块与文本出现在同一行上。
+    const inlineSegments: MessageSegment[] = []
+    const replySegments: MessageSegment[] = []
+    for (const segment of message.segments) {
+      if (segment.type === 'reply') {
+        replySegments.push(segment)
+      } else {
+        inlineSegments.push(segment)
+      }
+    }
+
    return (
      <div className="flex flex-col gap-2">
-        {message.segments.map((segment, index) => (
-          <RenderMessageSegment key={index} segment={segment} />
+        {replySegments.map((segment, index) => (
+          <RenderMessageSegment key={`reply-${index}`} segment={segment} />
        ))}
+        {inlineSegments.length > 0 && (
+          <div className="flex flex-wrap items-baseline whitespace-pre-wrap">
+            {inlineSegments.map((segment, index) => (
+              <RenderMessageSegment key={`inline-${index}`} segment={segment} />
+            ))}
+          </div>
+        )}
      </div>
    )
  }
@@ -115,3 +174,61 @@ export function RenderMessageContent({
  // 普通文本消息
  return <span className="whitespace-pre-wrap">{message.content}</span>
 }
+
+// 回复消息块：点击可跳转到原始消息；如原消息不可见则提示错误。
+function ReplySegmentBlock({ data }: { data: ReplySegmentData }) {
+  const { t } = useTranslation()
+  const { toast } = useToast()
+  const chatScroll = useChatScroll()
+
+  const senderName =
+    data.target_message_sender_cardname ||
+    data.target_message_sender_nickname ||
+    data.target_message_sender_id ||
+    t('chat.message.replyUnknownSender', { defaultValue: '未知发送者' })
+  const previewText =
+    data.target_message_content?.trim() ||
+    t('chat.media.replyMissing', { defaultValue: '原消息内容不可用' })
+  const targetMessageId = data.target_message_id ? String(data.target_message_id) : ''
+  const isClickable = Boolean(targetMessageId && chatScroll)
+
+  const handleClick = () => {
+    if (!targetMessageId || !chatScroll) {
+      return
+    }
+    const found = chatScroll.scrollToMessage(targetMessageId)
+    if (!found) {
+      toast({
+        title: t('chat.toast.replyNotFoundTitle', { defaultValue: '原始消息不在当前视图' }),
+        description: t('chat.toast.replyNotFoundDescription', {
+          defaultValue: '该消息可能已被清除、不在本会话中，或者尚未加载。',
+        }),
+        variant: 'destructive',
+      })
+    }
+  }
+
+  const className = cn(
+    'group block w-full rounded-md border-l-2 border-primary/60 bg-background/40 px-2 py-1 text-left text-xs',
+    isClickable && 'cursor-pointer transition hover:bg-background/70'
+  )
+
+  const content = (
+    <div className="flex items-start gap-2">
+      <ReplyIcon className="mt-0.5 h-3 w-3 shrink-0 opacity-70" aria-hidden />
+      <div className="min-w-0 flex-1">
+        <div className="text-primary/80 truncate text-[11px] font-medium">{senderName}</div>
+        <div className="text-muted-foreground truncate">{previewText}</div>
+      </div>
+    </div>
+  )
+
+  if (isClickable) {
+    return (
+      <button type="button" className={className} onClick={handleClick}>
+        {content}
+      </button>
+    )
+  }
+  return <div className={className}>{content}</div>
+}
--- a/dashboard/src/routes/chat/index.tsx
+++ b/dashboard/src/routes/chat/index.tsx
@@ -214,6 +214,7 @@ export function ChatPage() {
              user_id: data.user_id,
              user_name: data.user_name,
              bot_name: data.bot_name,
+              bot_qq: data.bot_qq,
            },
          })
          break
@@ -278,7 +279,6 @@ export function ChatPage() {
          setTabs((prev) =>
            prev.map((tab) => {
              if (tab.id !== tabId) return tab
-              const filteredMessages = tab.messages.filter((msg) => msg.type !== 'thinking')
              const newMessage: ChatMessage = {
                id: generateMessageId('bot'),
                type: 'bot',
@@ -290,7 +290,7 @@ export function ChatPage() {
              }
              return {
                ...tab,
-                messages: [...filteredMessages, newMessage],
+                messages: [...tab.messages, newMessage],
              }
            })
          )
@@ -305,11 +305,10 @@ export function ChatPage() {
          setTabs((prev) =>
            prev.map((tab) => {
              if (tab.id !== tabId) return tab
-              const filteredMessages = tab.messages.filter((msg) => msg.type !== 'thinking')
              return {
                ...tab,
                messages: [
-                  ...filteredMessages,
+                  ...tab.messages,
                  {
                    id: generateMessageId('error'),
                    type: 'error' as const,
@@ -330,33 +329,27 @@ export function ChatPage() {
        case 'history': {
          const historyMessages = data.messages || []
          const processedSet = new Set<string>()
-          const formattedMessages: ChatMessage[] = historyMessages.map(
-            (msg: {
-              id?: string
-              content: string
-              timestamp: number
-              sender_name?: string
-              sender_id?: string
-              is_bot?: boolean
-            }) => {
-              const isBot = msg.is_bot || false
-              const msgId = msg.id || generateMessageId(isBot ? 'bot' : 'user')
-              const contentHash = `${isBot ? 'bot' : 'user'}-${msg.content}-${Math.floor(msg.timestamp * 1000)}`
-              processedSet.add(contentHash)
-              return {
-                id: msgId,
-                type: isBot ? 'bot' : ('user' as const),
-                content: msg.content,
-                timestamp: msg.timestamp,
-                sender: {
-                  name:
-                    msg.sender_name || (isBot ? t('chat.botNameFallback') : t('chat.userFallback')),
-                  user_id: msg.sender_id,
-                  is_bot: isBot,
-                },
-              }
+          const formattedMessages: ChatMessage[] = historyMessages.map((msg) => {
+            const isBot = msg.is_bot || false
+            const msgId = msg.id || generateMessageId(isBot ? 'bot' : 'user')
+            const contentHash = `${isBot ? 'bot' : 'user'}-${msg.content}-${Math.floor(msg.timestamp * 1000)}`
+            processedSet.add(contentHash)
+            const isRich = msg.message_type === 'rich' && Array.isArray(msg.segments) && msg.segments.length > 0
+            return {
+              id: msgId,
+              type: isBot ? 'bot' : ('user' as const),
+              content: msg.content,
+              timestamp: msg.timestamp,
+              message_type: isRich ? 'rich' : 'text',
+              segments: isRich ? (msg.segments ?? undefined) : undefined,
+              sender: {
+                name:
+                  msg.sender_name || (isBot ? t('chat.botNameFallback') : t('chat.userFallback')),
+                user_id: msg.sender_id,
+                is_bot: isBot,
+              },
            }
-          )
+          })

          processedMessagesMapRef.current.set(tabId, processedSet)
          updateTab(tabId, { messages: formattedMessages })
@@ -509,19 +502,6 @@ export function ChatPage() {
    }
    addMessageToTab(activeTabId, userMessage)

-    // 再添加"思考中"占位消息
-    const thinkingMessage: ChatMessage = {
-      id: generateMessageId('thinking'),
-      type: 'thinking',
-      content: '',
-      timestamp: currentTimestamp + 0.001, // 稍微晚一点确保顺序
-      sender: {
-        name: activeTab?.sessionInfo.bot_name || t('chat.botNameFallback'),
-        is_bot: true,
-      },
-    }
-    addMessageToTab(activeTabId, thinkingMessage)
-
    setInputValue('')

    try {
@@ -534,7 +514,6 @@ export function ChatPage() {
          return {
            ...tab,
            isTyping: false,
-            messages: tab.messages.filter((msg) => msg.type !== 'thinking'),
          }
        })
      )
@@ -759,6 +738,7 @@ export function ChatPage() {
          messages={activeTab?.messages ?? []}
          isLoadingHistory={isLoadingHistory}
          botDisplayName={botDisplayName}
+          botQq={activeTab?.sessionInfo.bot_qq}
          userName={userName}
          language={i18n.language}
        />
--- a/dashboard/src/routes/chat/types.ts
+++ b/dashboard/src/routes/chat/types.ts
@@ -49,20 +49,49 @@ export interface ChatTab {
    user_id?: string
    user_name?: string
    bot_name?: string
+    bot_qq?: string
  }
 }

 // 消息段类型
 export interface MessageSegment {
-  type: 'text' | 'image' | 'emoji' | 'face' | 'voice' | 'video' | 'music' | 'file' | 'reply' | 'forward' | 'unknown'
+  type:
+    | 'text'
+    | 'image'
+    | 'emoji'
+    | 'face'
+    | 'voice'
+    | 'video'
+    | 'music'
+    | 'file'
+    | 'reply'
+    | 'at'
+    | 'forward'
+    | 'unknown'
  data: string | number | object
  original_type?: string
 }

+// @某人 消息段的负载
+export interface AtSegmentData {
+  target_user_id?: string | null
+  target_user_nickname?: string | null
+  target_user_cardname?: string | null
+}
+
+// 回复消息段的负载
+export interface ReplySegmentData {
+  target_message_id?: string | null
+  target_message_content?: string | null
+  target_message_sender_id?: string | null
+  target_message_sender_nickname?: string | null
+  target_message_sender_cardname?: string | null
+}
+
 // 消息类型
 export interface ChatMessage {
  id: string
-  type: 'user' | 'bot' | 'system' | 'error' | 'thinking'
+  type: 'user' | 'bot' | 'system' | 'error'
  content: string
  timestamp: number
  message_type?: 'text' | 'rich'  // 消息格式类型
@@ -85,6 +114,7 @@ export interface WsMessage {
  user_id?: string
  user_name?: string
  bot_name?: string
+  bot_qq?: string
  sender?: {
    name: string
    user_id?: string
@@ -98,6 +128,8 @@ export interface WsMessage {
    sender_name?: string
    sender_id?: string
    is_bot?: boolean
+    message_type?: string
+    segments?: MessageSegment[] | null
  }>
  group_id?: string
  // 富文本消息
--- a/dashboard/src/routes/config/bot/hooks/JsonFieldHookFactory.tsx
+++ b/dashboard/src/routes/config/bot/hooks/JsonFieldHookFactory.tsx
@@ -67,7 +67,7 @@ export function createJsonFieldHook(options: JsonFieldHookOptions): FieldHookCom
        <div className="space-y-1">
          <h3 className="text-base font-semibold">{label}</h3>
          {description && (
-            <p className="text-sm text-muted-foreground">{description}</p>
+            <p className="text-sm text-muted-foreground whitespace-pre-line">{description}</p>
          )}
          <p className="text-xs text-muted-foreground">{options.helperText}</p>
        </div>
--- a/dashboard/src/routes/config/bot/hooks/ListItemEditorHookFactory.tsx
+++ b/dashboard/src/routes/config/bot/hooks/ListItemEditorHookFactory.tsx
@@ -0,0 +1,283 @@
+import { useCallback, useMemo } from 'react'
+import * as LucideIcons from 'lucide-react'
+import { Plus, Trash2 } from 'lucide-react'
+
+import { Button } from '@/components/ui/button'
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card'
+import { DynamicConfigForm } from '@/components/dynamic-form/DynamicConfigForm'
+import type { FieldHookComponent } from '@/lib/field-hooks'
+import type { ConfigSchema, FieldSchema } from '@/types/config-schema'
+
+/**
+ * createListItemEditorHook
+ *
+ * 通过 nestedSchema 渲染列表项式的富 UI 编辑器，替换原来直接展示 JSON 文本的 fallback。
+ * 适用于 `List[ConfigBase]` 类型字段（schema.nested 中存在对应子配置类）。
+ */
+export interface ListItemEditorOptions {
+  /** 用于生成每个 item 的标题，如 `${index+1} · ${item.platform}` */
+  itemTitle?: (item: Record<string, unknown>, index: number) => string
+  /** 添加按钮文案 */
+  addLabel?: string
+  /** 顶部辅助说明 */
+  helperText?: string
+  /** 列表为空时的占位说明 */
+  emptyText?: string
+  /** 顶部图标（覆盖 schema 自带的 x-icon） */
+  iconName?: string
+}
+
+function resolveLabel(schema?: ConfigSchema | FieldSchema, fieldPath?: string): string {
+  if (!schema) {
+    return fieldPath?.split('.').at(-1) ?? '列表配置'
+  }
+  if ('label' in schema && schema.label) {
+    return schema.label
+  }
+  if ('uiLabel' in schema && schema.uiLabel) {
+    return schema.uiLabel
+  }
+  if ('classDoc' in schema && schema.classDoc) {
+    return schema.classDoc
+  }
+  if ('className' in schema && schema.className) {
+    return schema.className
+  }
+  return fieldPath?.split('.').at(-1) ?? '列表配置'
+}
+
+function resolveDescription(schema?: ConfigSchema | FieldSchema): string {
+  if (!schema) return ''
+  if ('description' in schema && schema.description) return schema.description
+  if ('classDoc' in schema && schema.classDoc) return schema.classDoc
+  return ''
+}
+
+function resolveIconName(
+  iconOverride: string | undefined,
+  schema?: ConfigSchema | FieldSchema,
+  nested?: ConfigSchema,
+): string | undefined {
+  if (iconOverride) return iconOverride
+  if (schema && 'x-icon' in schema && schema['x-icon']) return schema['x-icon']
+  if (nested?.uiIcon) return nested.uiIcon
+  return undefined
+}
+
+function renderLucideIcon(iconName: string | undefined, className: string) {
+  if (!iconName) return null
+  const Icon = LucideIcons[iconName as keyof typeof LucideIcons] as
+    | React.ComponentType<{ className?: string }>
+    | undefined
+  if (!Icon) return null
+  return <Icon className={className} />
+}
+
+/** 根据 itemSchema 字段默认值构造一个新 item */
+function buildDefaultItem(itemSchema: ConfigSchema | undefined): Record<string, unknown> {
+  if (!itemSchema?.fields) return {}
+  const next: Record<string, unknown> = {}
+  for (const field of itemSchema.fields) {
+    if ('default' in field && field.default !== undefined) {
+      // 数组/对象需要做一次浅拷贝，避免多个 item 共享同一引用
+      if (Array.isArray(field.default)) {
+        next[field.name] = [...field.default]
+      } else if (
+        field.default !== null &&
+        typeof field.default === 'object'
+      ) {
+        next[field.name] = { ...(field.default as Record<string, unknown>) }
+      } else {
+        next[field.name] = field.default
+      }
+      continue
+    }
+    switch (field.type) {
+      case 'boolean':
+        next[field.name] = false
+        break
+      case 'integer':
+      case 'number':
+        next[field.name] = 0
+        break
+      case 'array':
+        next[field.name] = []
+        break
+      case 'object':
+        next[field.name] = {}
+        break
+      case 'select':
+        next[field.name] = field.options?.[0] ?? ''
+        break
+      default:
+        next[field.name] = ''
+    }
+  }
+  return next
+}
+
+/**
+ * 把 dotted-path 写入 item 对象（兼容 DynamicConfigForm 的 onChange）
+ */
+function setNested(target: Record<string, unknown>, path: string, value: unknown) {
+  const keys = path.split('.')
+  if (keys.length === 1) {
+    target[keys[0]] = value
+    return
+  }
+  let cursor: Record<string, unknown> = target
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i]
+    const existing = cursor[key]
+    if (existing && typeof existing === 'object' && !Array.isArray(existing)) {
+      cursor[key] = { ...(existing as Record<string, unknown>) }
+    } else {
+      cursor[key] = {}
+    }
+    cursor = cursor[key] as Record<string, unknown>
+  }
+  cursor[keys[keys.length - 1]] = value
+}
+
+export function createListItemEditorHook(
+  options: ListItemEditorOptions = {},
+): FieldHookComponent {
+  const ListItemEditorHook: FieldHookComponent = ({
+    fieldPath,
+    onChange,
+    schema,
+    nestedSchema,
+    value,
+  }) => {
+    const items = useMemo<Record<string, unknown>[]>(() => {
+      if (!Array.isArray(value)) return []
+      return value.map((item) =>
+        item && typeof item === 'object' && !Array.isArray(item)
+          ? (item as Record<string, unknown>)
+          : {},
+      )
+    }, [value])
+
+    const handleAdd = useCallback(() => {
+      const next = [...items, buildDefaultItem(nestedSchema)]
+      onChange?.(next)
+    }, [items, nestedSchema, onChange])
+
+    const handleRemove = useCallback(
+      (index: number) => {
+        const next = items.filter((_, idx) => idx !== index)
+        onChange?.(next)
+      },
+      [items, onChange],
+    )
+
+    const handleItemFieldChange = useCallback(
+      (index: number, fieldName: string, fieldValue: unknown) => {
+        const next = items.map((item, idx) => {
+          if (idx !== index) return item
+          const cloned = { ...item }
+          setNested(cloned, fieldName, fieldValue)
+          return cloned
+        })
+        onChange?.(next)
+      },
+      [items, onChange],
+    )
+
+    const label = resolveLabel(schema, fieldPath)
+    const description = resolveDescription(schema)
+    const iconName = resolveIconName(options.iconName, schema, nestedSchema)
+
+    if (!nestedSchema) {
+      return (
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-base">{label}</CardTitle>
+            <CardDescription>未获取到子配置 schema，无法渲染富编辑器。</CardDescription>
+          </CardHeader>
+        </Card>
+      )
+    }
+
+    return (
+      <Card>
+        <CardHeader className="space-y-2 pb-4">
+          <div className="flex items-center gap-2">
+            {renderLucideIcon(iconName, 'h-5 w-5 text-muted-foreground')}
+            <CardTitle className="text-base">{label}</CardTitle>
+          </div>
+          {description && (
+            <CardDescription className="whitespace-pre-line">{description}</CardDescription>
+          )}
+          {options.helperText && (
+            <p className="text-xs text-muted-foreground">{options.helperText}</p>
+          )}
+        </CardHeader>
+        <CardContent className="space-y-3">
+          {items.length === 0 ? (
+            <div className="rounded-md border border-dashed border-muted-foreground/25 bg-muted/10 p-6 text-center text-sm text-muted-foreground">
+              {options.emptyText ?? '尚未添加任何条目，点击下方按钮新增。'}
+            </div>
+          ) : (
+            items.map((item, index) => {
+              const title =
+                options.itemTitle?.(item, index) ?? `条目 ${index + 1}`
+              return (
+                <div
+                  key={index}
+                  className="space-y-3 rounded-lg border bg-card/40 p-4"
+                >
+                  <div className="flex items-center justify-between gap-2">
+                    <div className="flex items-center gap-2 text-sm font-semibold">
+                      <span className="inline-flex h-6 min-w-6 items-center justify-center rounded-full bg-muted px-2 text-xs font-medium text-muted-foreground">
+                        {index + 1}
+                      </span>
+                      <span className="truncate">{title}</span>
+                    </div>
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="sm"
+                      className="text-destructive hover:text-destructive"
+                      onClick={() => handleRemove(index)}
+                    >
+                      <Trash2 className="mr-1 h-4 w-4" />
+                      删除
+                    </Button>
+                  </div>
+                  <DynamicConfigForm
+                    schema={nestedSchema}
+                    values={item}
+                    onChange={(field, fieldValue) =>
+                      handleItemFieldChange(index, field, fieldValue)
+                    }
+                    basePath=""
+                    level={1}
+                  />
+                </div>
+              )
+            })
+          )}
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            onClick={handleAdd}
+            className="w-full"
+          >
+            <Plus className="mr-1 h-4 w-4" />
+            {options.addLabel ?? '添加一项'}
+          </Button>
+        </CardContent>
+      </Card>
+    )
+  }
+
+  return ListItemEditorHook
+}
--- a/dashboard/src/routes/config/bot/hooks/complexFieldHooks.tsx
+++ b/dashboard/src/routes/config/bot/hooks/complexFieldHooks.tsx
@@ -1,15 +1,98 @@
 import { createJsonFieldHook } from './JsonFieldHookFactory'
+import { createListItemEditorHook } from './ListItemEditorHookFactory'

-export const ChatTalkValueRulesHook = createJsonFieldHook({
-  emptyValue: [],
-  helperText: '复杂对象数组使用 JSON 编辑。每一项对应一个聊天频率规则对象。',
-  placeholder: '[\n  {\n    "platform": "",\n    "item_id": "",\n    "rule_type": "group",\n    "time": "00:00-23:59",\n    "value": 1.0\n  }\n]',
+const ruleTypeLabel = (rule: unknown) => {
+  if (rule === 'private') return '私聊'
+  if (rule === 'group') return '群聊'
+  return rule ? String(rule) : '未指定'
+}
+
+const platformLabel = (item: Record<string, unknown>) => {
+  const platform = typeof item.platform === 'string' ? item.platform.trim() : ''
+  const itemId = typeof item.item_id === 'string' ? item.item_id.trim() : ''
+  if (!platform && !itemId) return '全局'
+  if (!platform) return itemId
+  if (!itemId) return platform
+  return `${platform}:${itemId}`
+}
+
+const truncate = (text: string, max = 32) => {
+  if (text.length <= max) return text
+  return `${text.slice(0, max)}…`
+}
+
+const collectStringList = (value: unknown): string[] => {
+  if (!Array.isArray(value)) return []
+  return value
+    .map((item) => (typeof item === 'string' ? item.trim() : ''))
+    .filter((item) => item.length > 0)
+}
+
+export const ChatTalkValueRulesHook = createListItemEditorHook({
+  addLabel: '添加发言频率规则',
+  helperText: '可按平台/聊天流/时段分别配置发言频率，留空表示全局。',
+  emptyText: '尚未配置任何规则，将使用全局默认频率。',
+  itemTitle: (item) => {
+    const time =
+      typeof item.time === 'string' && item.time.trim()
+        ? item.time.trim()
+        : '全天'
+    const value =
+      typeof item.value === 'number' ? item.value.toFixed(2) : '—'
+    return `${platformLabel(item)} · ${ruleTypeLabel(item.rule_type)} · ${time} · 频率 ${value}`
+  },
 })

-export const ExpressionLearningListHook = createJsonFieldHook({
-  emptyValue: [],
-  helperText: '表达学习配置较复杂，使用 JSON 编辑更稳妥。每一项对应一个学习规则。',
-  placeholder: '[\n  {\n    "platform": "",\n    "item_id": "",\n    "rule_type": "group",\n    "use_expression": true,\n    "enable_learning": true,\n    "enable_jargon_learning": true\n  }\n]',
+export const ExpressionLearningListHook = createListItemEditorHook({
+  addLabel: '添加表达学习规则',
+  helperText: '为不同聊天流单独配置是否启用表达/jargon 学习。',
+  emptyText: '尚未配置任何学习规则。',
+  itemTitle: (item) => {
+    const flags: string[] = []
+    if (item.use_expression) flags.push('表达')
+    if (item.enable_learning) flags.push('优化学习')
+    if (item.enable_jargon_learning) flags.push('jargon')
+    const flagText = flags.length ? flags.join(' / ') : '全部关闭'
+    return `${platformLabel(item)} · ${ruleTypeLabel(item.rule_type)} · ${flagText}`
+  },
+})
+
+export const KeywordRulesHook = createListItemEditorHook({
+  addLabel: '添加关键词规则',
+  helperText: '匹配命中后会用 reaction 内容作为额外上下文。keywords 至少填一条，或使用正则模式。',
+  emptyText: '尚未添加任何关键词规则。',
+  itemTitle: (item) => {
+    const keywords = collectStringList(item.keywords)
+    const regex = collectStringList(item.regex)
+    const reaction =
+      typeof item.reaction === 'string' ? item.reaction.trim() : ''
+    const left = keywords.length
+      ? `关键词 ${keywords.length} 条`
+      : regex.length
+        ? `正则 ${regex.length} 条`
+        : '未配置匹配项'
+    const right = reaction ? `→ ${truncate(reaction)}` : '→ 未填写反应'
+    return `${left} ${right}`
+  },
+})
+
+export const RegexRulesHook = createListItemEditorHook({
+  addLabel: '添加正则规则',
+  helperText: '正则模式按 Python 语法编写，命中时把 reaction 作为提示注入。',
+  emptyText: '尚未添加任何正则规则。',
+  itemTitle: (item) => {
+    const regex = collectStringList(item.regex)
+    const keywords = collectStringList(item.keywords)
+    const reaction =
+      typeof item.reaction === 'string' ? item.reaction.trim() : ''
+    const left = regex.length
+      ? `正则 ${regex.length} 条`
+      : keywords.length
+        ? `关键词 ${keywords.length} 条`
+        : '未配置匹配项'
+    const right = reaction ? `→ ${truncate(reaction)}` : '→ 未填写反应'
+    return `${left} ${right}`
+  },
 })

 export const ExpressionGroupsHook = createJsonFieldHook({
@@ -24,18 +107,6 @@ export const ExperimentalChatPromptsHook = createJsonFieldHook({
  placeholder: '[\n  {\n    "platform": "qq",\n    "item_id": "123456",\n    "rule_type": "group",\n    "prompt": "这里填写额外提示词"\n  }\n]',
 })

-export const KeywordRulesHook = createJsonFieldHook({
-  emptyValue: [],
-  helperText: '关键词规则为对象数组，建议直接编辑 JSON。',
-  placeholder: '[\n  {\n    "keywords": ["早安"],\n    "regex": [],\n    "reaction": "早安呀"\n  }\n]',
-})
-
-export const RegexRulesHook = createJsonFieldHook({
-  emptyValue: [],
-  helperText: '正则规则为对象数组，建议直接编辑 JSON。',
-  placeholder: '[\n  {\n    "keywords": [],\n    "regex": ["https?://[^\\\\s]+"],\n    "reaction": "检测到链接：[0]"\n  }\n]',
-})
-
 export const MCPRootItemsHook = createJsonFieldHook({
  emptyValue: [],
  helperText: 'MCP Roots 条目为对象数组，使用 JSON 编辑。',
--- a/src/chat/message_receive/uni_message_sender.py
+++ b/src/chat/message_receive/uni_message_sender.py
@@ -36,9 +36,9 @@ def get_webui_chat_broadcaster() -> Tuple[Any, Optional[str], Optional[str]]:
    if _webui_chat_broadcaster is None:
        try:
            from src.webui.routers.chat import WEBUI_CHAT_PLATFORM, chat_manager
-            from src.webui.routers.chat.service import WEBUI_CHAT_GROUP_ID

-            _webui_chat_broadcaster = (chat_manager, WEBUI_CHAT_PLATFORM, WEBUI_CHAT_GROUP_ID)
+            # 默认不再强制虚拟群聊；WebUI 默认走私聊频道，需要的话由调用者传入虚拟群 ID。
+            _webui_chat_broadcaster = (chat_manager, WEBUI_CHAT_PLATFORM, None)
        except ImportError:
            _webui_chat_broadcaster = (None, None, None)
    return _webui_chat_broadcaster
@@ -98,6 +98,14 @@ async def _send_message(message: SessionMessage, show_log: bool = True) -> bool:
                message_type = "rich"
                segments = message_segments

+            # 私聊场景下出站消息的 user_info 是机器人自己的身份，
+            # 真正的接收者用户 ID 由 send_service 写入 ``platform_io_target_user_id``。
+            target_user_id = ""
+            additional_config = message.message_info.additional_config or {}
+            raw_target_user_id = additional_config.get("platform_io_target_user_id")
+            if raw_target_user_id:
+                target_user_id = str(raw_target_user_id).strip()
+
            await chat_manager.broadcast_to_group(
                group_id=group_id or default_group_id or "",
                message={
@@ -113,6 +121,7 @@ async def _send_message(message: SessionMessage, show_log: bool = True) -> bool:
                        "is_bot": True,
                    },
                },
+                user_id=target_user_id,
            )

            # 注意：机器人消息会由 MessageStorage.store_message 自动保存到数据库
--- a/src/chat/replyer/maisaka_generator_base.py
+++ b/src/chat/replyer/maisaka_generator_base.py
@@ -83,6 +83,7 @@ class BaseMaisakaReplyGenerator:
        self.express_model = llm_client_cls(
            task_name="replyer",
            request_type=request_type,
+            session_id=getattr(chat_stream, "session_id", "") if chat_stream is not None else "",
        )
        self._personality_prompt = self._build_personality_prompt()

--- a/src/config/config.py
+++ b/src/config/config.py
@@ -56,7 +56,7 @@ BOT_CONFIG_PATH: Path = (CONFIG_DIR / "bot_config.toml").resolve().absolute()
 MODEL_CONFIG_PATH: Path = (CONFIG_DIR / "model_config.toml").resolve().absolute()
 LEGACY_ENV_PATH: Path = (PROJECT_ROOT / ".env").resolve().absolute()
 MMC_VERSION: str = "1.0.0"
-CONFIG_VERSION: str = "8.9.19"
+CONFIG_VERSION: str = "8.9.20"
 MODEL_CONFIG_VERSION: str = "1.14.3"

 logger = get_logger("config")
--- a/src/config/official_configs.py
+++ b/src/config/official_configs.py
@@ -1324,6 +1324,15 @@ class DebugConfig(ConfigBase):
    )
    """是否记录 Replyer 请求体，默认关闭"""

+    enable_llm_cache_stats: bool = Field(
+        default=False,
+        json_schema_extra={
+            "x-widget": "switch",
+            "x-icon": "chart-no-axes-column",
+        },
+    )
+    """是否记录 LLM prompt cache 调试统计，默认关闭"""
+

 class ExtraPromptItem(ConfigBase):
    platform: str = Field(
--- a/src/learners/jargon_miner.py
+++ b/src/learners/jargon_miner.py
@@ -23,7 +23,7 @@ from .expression_utils import is_single_char_jargon

 logger = get_logger("jargon")

-llm_inference = LLMServiceClient(task_name="replyer", request_type="jargon.inference")
+llm_inference = LLMServiceClient(task_name="utils", request_type="jargon.inference")


 class JargonEntry(TypedDict):
--- a/src/maisaka/chat_loop_service.py
+++ b/src/maisaka/chat_loop_service.py
@@ -41,6 +41,11 @@ from .display.prompt_cli_renderer import PromptCLIVisualizer
 from .visual_mode_utils import resolve_enable_visual_planner

 TIMING_GATE_TOOL_NAMES = {"continue", "no_reply", "wait"}
+REQUEST_TYPE_BY_REQUEST_KIND = {
+    "planner": "maisaka_planner",
+    "timing_gate": "maisaka_timing_gate",
+}
+CONTEXT_SELECTION_CACHE_STABILITY_RATIO = 2.0


@dataclass(slots=True)
@@ -212,7 +217,7 @@ class MaisakaChatLoopService:
            self._chat_system_prompt = f"{self._personality_prompt}\n\nYou are a helpful AI assistant."
        else:
            self._chat_system_prompt = chat_system_prompt
-        self._llm_chat = LLMServiceClient(task_name="planner", request_type="maisaka_planner")
+        self._llm_chat_clients: dict[str, LLMServiceClient] = {}

    @property
    def personality_prompt(self) -> str:
@@ -220,6 +225,30 @@ class MaisakaChatLoopService:

        return self._personality_prompt

+    @staticmethod
+    def _resolve_llm_request_type(request_kind: str) -> str:
+        """根据 Maisaka 请求类型解析 LLM 统计口径。"""
+
+        normalized_request_kind = str(request_kind or "").strip()
+        return REQUEST_TYPE_BY_REQUEST_KIND.get(
+            normalized_request_kind,
+            f"maisaka_{normalized_request_kind}" if normalized_request_kind else "maisaka_planner",
+        )
+
+    def _get_llm_chat_client(self, request_kind: str) -> LLMServiceClient:
+        """获取当前请求类型对应的 planner LLM 客户端。"""
+
+        request_type = self._resolve_llm_request_type(request_kind)
+        llm_client = self._llm_chat_clients.get(request_type)
+        if llm_client is None:
+            llm_client = LLMServiceClient(
+                task_name="planner",
+                request_type=request_type,
+                session_id=self._session_id,
+            )
+            self._llm_chat_clients[request_type] = llm_client
+        return llm_client
+
    @staticmethod
    def _get_runtime_manager() -> Any:
        """获取插件运行时管理器。
@@ -321,7 +350,13 @@ class MaisakaChatLoopService:

    @staticmethod
    def _build_time_block() -> str:
-        """构建当前时间提示块。"""
+        """构建静态时间提示块。"""
+
+        return "当前时间会在每次请求末尾以用户消息形式提供。"
+
+    @staticmethod
+    def _build_current_time_user_message() -> str:
+        """构建追加到请求末尾的当前时间消息。"""

        return f"当前时间：{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}"

@@ -446,7 +481,11 @@ class MaisakaChatLoopService:
                messages.append(llm_message)

        normalized_injected_messages: List[Message] = []
-        for injected_message in injected_user_messages or []:
+        final_user_messages = [
+            *(injected_user_messages or []),
+            self._build_current_time_user_message(),
+        ]
+        for injected_message in final_user_messages:
            normalized_message = str(injected_message or "").strip()
            if not normalized_message:
                continue
@@ -458,31 +497,10 @@ class MaisakaChatLoopService:
            )

        if normalized_injected_messages:
-            insertion_index = self._resolve_injected_user_messages_insertion_index(messages)
-            messages[insertion_index:insertion_index] = normalized_injected_messages
+            messages.extend(normalized_injected_messages)

        return messages

-    @staticmethod
-    def _resolve_injected_user_messages_insertion_index(messages: Sequence[Message]) -> int:
-        """计算 injected meta user messages 在请求中的插入位置。
-
-        规则与 deferred attachment 更接近：
-        - 从尾部向前寻找最近的 stopping point；
-        - stopping point 为 assistant 消息或 tool 结果消息；
-        - 找到后插入到其后面；
-        - 若不存在 stopping point，则退回到 system 消息之后。
-        """
-
-        for index in range(len(messages) - 1, -1, -1):
-            message = messages[index]
-            if message.role in {RoleType.Assistant, RoleType.Tool}:
-                return index + 1
-
-        if messages and messages[0].role == RoleType.System:
-            return 1
-        return 0
-
    async def chat_loop_step(
        self,
        chat_history: List[LLMContextMessage],
@@ -575,7 +593,8 @@ class MaisakaChatLoopService:
                tool_definitions=list(all_tools),
            )

-        generation_result = await self._llm_chat.generate_response_with_messages(
+        llm_chat = self._get_llm_chat_client(request_kind)
+        generation_result = await llm_chat.generate_response_with_messages(
            message_factory=message_factory,
            options=LLMGenerationOptions(
                tool_options=all_tools if all_tools else None,
@@ -654,7 +673,11 @@ class MaisakaChatLoopService:
            chat_history,
            request_kind=request_kind,
        )
-        effective_context_size = max(1, int(max_context_size or global_config.chat.max_context_size))
+        base_context_size = max(1, int(max_context_size or global_config.chat.max_context_size))
+        effective_context_size = max(
+            base_context_size,
+            int(base_context_size * CONTEXT_SELECTION_CACHE_STABILITY_RATIO),
+        )
        selected_indices: List[int] = []
        counted_message_count = 0

@@ -690,9 +713,11 @@ class MaisakaChatLoopService:
        selected_history, _ = normalize_tool_result_order(selected_history)
        tool_message_count = sum(1 for message in selected_history if isinstance(message, ToolResultMessage))
        normal_message_count = len(selected_history) - tool_message_count
+        stability_text = f"|cache_window {base_context_size}->{effective_context_size}"
        selection_reason = (
            f"实际发送 {len(selected_history)} 条消息"
            f"|消息 {normal_message_count} 条|tool {tool_message_count} 条"
+            f"{stability_text}"
        )
        return (
            selected_history,
--- a/src/maisaka/history_post_processor.py
+++ b/src/maisaka/history_post_processor.py
@@ -3,11 +3,11 @@
 from dataclasses import dataclass
 from math import ceil

-from .context_messages import AssistantMessage, LLMContextMessage
+from .context_messages import LLMContextMessage
 from .history_utils import drop_leading_orphan_tool_results, drop_orphan_tool_results, normalize_tool_result_order

-EARLY_TRIM_RATIO = 0.3
-TRIM_THRESHOLD_RATIO = 1.2
+TRIM_TARGET_RATIO = 1.0
+TRIM_THRESHOLD_RATIO = 2.0


@dataclass(slots=True)
@@ -36,21 +36,16 @@ def process_chat_history_after_cycle(
    compact_removed_count = 0
    trim_threshold = ceil(max_context_size * TRIM_THRESHOLD_RATIO)
    if remaining_context_count > trim_threshold:
-        removed_early_message_count = _remove_early_history_messages(processed_history)
-        processed_history, removed_after_message_trim_count, moved_after_message_trim_count = (
-            _normalize_history_structure(processed_history)
+        target_context_count = max(1, int(max_context_size * TRIM_TARGET_RATIO))
+        removed_early_message_count = _trim_history_to_context_target(
+            processed_history,
+            target_context_count=target_context_count,
        )
-        removed_assistant_thought_count = _remove_early_assistant_thoughts(processed_history)
-        processed_history, removed_after_thought_trim_count, moved_after_thought_trim_count = (
-            _normalize_history_structure(processed_history)
+        processed_history, removed_after_trim_count, moved_after_trim_count = _normalize_history_structure(
+            processed_history
        )
-        compact_removed_count = (
-            removed_early_message_count
-            + removed_after_message_trim_count
-            + removed_assistant_thought_count
-            + removed_after_thought_trim_count
-        )
-        moved_tool_result_count += moved_after_message_trim_count + moved_after_thought_trim_count
+        compact_removed_count = removed_early_message_count + removed_after_trim_count
+        moved_tool_result_count += moved_after_trim_count

    remaining_context_count = sum(1 for message in processed_history if message.count_in_context)
    removed_count = normalized_removed_count + compact_removed_count
@@ -78,42 +73,27 @@ def _normalize_history_structure(
    )


-def _remove_early_history_messages(chat_history: list[LLMContextMessage]) -> int:
-    """移除最早 30% 的全部历史消息。"""
+def _trim_history_to_context_target(
+    chat_history: list[LLMContextMessage],
+    *,
+    target_context_count: int,
+) -> int:
+    """移除最早的一段历史，直到普通上下文消息数量降到目标值以内。"""
+
+    remaining_context_count = sum(1 for message in chat_history if message.count_in_context)
+    if remaining_context_count <= target_context_count:
+        return 0
+
+    remove_count = 0
+    for message in chat_history:
+        remove_count += 1
+        if message.count_in_context:
+            remaining_context_count -= 1
+            if remaining_context_count <= target_context_count:
+                break

-    remove_count = int(len(chat_history) * EARLY_TRIM_RATIO)
    if remove_count <= 0:
        return 0

    del chat_history[:remove_count]
    return remove_count
-
-
-def _remove_early_assistant_thoughts(chat_history: list[LLMContextMessage]) -> int:
-    """移除最早 30% 的非工具 assistant 思考内容。"""
-
-    candidate_indexes = [
-        index
-        for index, message in enumerate(chat_history)
-        if isinstance(message, AssistantMessage)
-        and not message.tool_calls
-        and message.source_kind != "perception"
-        and bool(message.content.strip())
-    ]
-    remove_count = int(len(candidate_indexes) * EARLY_TRIM_RATIO)
-    if remove_count <= 0:
-        return 0
-
-    removed_indexes = set(candidate_indexes[:remove_count])
-    filtered_history: list[LLMContextMessage] = []
-    removed_total = 0
-    for index, message in enumerate(chat_history):
-        if index in removed_indexes:
-            removed_total += 1
-            continue
-        filtered_history.append(message)
-
-    chat_history[:] = filtered_history
-    return removed_total
-
-
--- a/src/maisaka/reasoning_engine.py
+++ b/src/maisaka/reasoning_engine.py
@@ -52,7 +52,7 @@ if TYPE_CHECKING:

 logger = get_logger("maisaka_reasoning_engine")

-TIMING_GATE_CONTEXT_LIMIT = 24
+TIMING_GATE_CONTEXT_DROP_HEAD_RATIO = 0.7
 TIMING_GATE_MAX_TOKENS = 384
 TIMING_GATE_MAX_ATTEMPTS = 3
 TIMING_GATE_TOOL_NAMES = {"continue", "no_reply", "wait"}
@@ -124,7 +124,6 @@ class MaisakaReasoningEngine:
    async def _run_timing_gate_sub_agent(
        self,
        *,
-        context_message_limit: int,
        system_prompt: str,
        tool_definitions: list[dict[str, Any]],
    ) -> Any:
@@ -134,7 +133,10 @@ class MaisakaReasoningEngine:
        """

        return await self._runtime.run_sub_agent(
-            context_message_limit=context_message_limit,
+            context_message_limit=self._runtime._max_context_size,
+            drop_head_context_count=int(
+                self._runtime._max_context_size * TIMING_GATE_CONTEXT_DROP_HEAD_RATIO,
+            ),
            system_prompt=system_prompt,
            request_kind="timing_gate",
            interrupt_flag=None,
@@ -255,7 +257,6 @@ class MaisakaReasoningEngine:
        invalid_tool_text = ""
        for attempt_index in range(TIMING_GATE_MAX_ATTEMPTS):
            response = await self._run_timing_gate_sub_agent(
-                context_message_limit=TIMING_GATE_CONTEXT_LIMIT,
                system_prompt=self._build_timing_gate_system_prompt(),
                tool_definitions=get_timing_tools(),
            )
--- a/src/maisaka/runtime.py
+++ b/src/maisaka/runtime.py
@@ -45,6 +45,7 @@ from .context_messages import (
 from .display.display_utils import build_tool_call_summary_lines, format_token_count
 from .display.prompt_cli_renderer import PromptCLIVisualizer
 from .display.stage_status_board import remove_stage_status, update_stage_status
+from .history_utils import drop_leading_orphan_tool_results
 from .reasoning_engine import MaisakaReasoningEngine
 from .reply_effect import ReplyEffectTracker
 from .reply_effect.image_utils import extract_visual_attachments_from_sequence
@@ -583,6 +584,7 @@ class MaisakaHeartFlowChatting:
        self,
        *,
        context_message_limit: int,
+        drop_head_context_count: int = 0,
        system_prompt: str,
        request_kind: str = "sub_agent",
        extra_messages: Optional[Sequence[LLMContextMessage]] = None,
@@ -598,7 +600,10 @@ class MaisakaHeartFlowChatting:
            request_kind=request_kind,
            max_context_size=context_message_limit,
        )
-        sub_agent_history = list(selected_history)
+        sub_agent_history = self._drop_head_context_messages(
+            selected_history,
+            drop_head_context_count,
+        )
        if extra_messages:
            sub_agent_history.extend(list(extra_messages))

@@ -616,6 +621,31 @@ class MaisakaHeartFlowChatting:
            tool_definitions=[] if tool_definitions is None else tool_definitions,
        )

+    @staticmethod
+    def _drop_head_context_messages(
+        chat_history: Sequence[LLMContextMessage],
+        drop_context_count: int,
+    ) -> list[LLMContextMessage]:
+        """从已选上下文头部丢弃指定数量的普通上下文消息。"""
+
+        if drop_context_count <= 0:
+            return list(chat_history)
+
+        first_kept_index = 0
+        dropped_context_count = 0
+        while (
+            first_kept_index < len(chat_history)
+            and dropped_context_count < drop_context_count
+        ):
+            message = chat_history[first_kept_index]
+            if message.count_in_context:
+                dropped_context_count += 1
+            first_kept_index += 1
+
+        trimmed_history = list(chat_history[first_kept_index:])
+        trimmed_history, _ = drop_leading_orphan_tool_results(trimmed_history)
+        return trimmed_history
+
    async def _run_reply_effect_judge(self, prompt: str) -> str:
        """运行回复效果观察器使用的临时 LLM 评审。"""

--- a/src/services/llm_cache_stats.py
+++ b/src/services/llm_cache_stats.py
--- a/src/services/llm_service.py
+++ b/src/services/llm_service.py
@@ -6,6 +6,8 @@

 from typing import Any, Dict, List, Tuple

+import hashlib
+import inspect
 import json

 from src.common.data_models.embedding_service_data_models import EmbeddingResult
@@ -26,6 +28,7 @@ from src.llm_models.payload_content.message import Message, MessageBuilder, Role
 from src.llm_models.payload_content.tool_option import ToolCall
 from src.llm_models.utils_model import LLMOrchestrator
 from src.services.embedding_service import EmbeddingServiceClient
+from src.services.llm_cache_stats import record_llm_cache_usage
 from src.services.service_task_resolver import (
    get_available_models as _get_available_models,
    resolve_task_name as _resolve_task_name,
@@ -46,7 +49,7 @@ class LLMServiceClient:
    - `embed_text`（兼容入口，推荐改用 `EmbeddingServiceClient`）
    """

-    def __init__(self, task_name: str, request_type: str = "") -> None:
+    def __init__(self, task_name: str, request_type: str = "", session_id: str = "") -> None:
        """初始化 LLM 服务门面。

        Args:
@@ -55,6 +58,7 @@ class LLMServiceClient:
        """
        self.task_name = _resolve_task_name(task_name)
        self.request_type = request_type
+        self.session_id = str(session_id or "").strip()
        self._orchestrator = LLMOrchestrator(task_name=self.task_name, request_type=request_type)

    @staticmethod
@@ -85,6 +89,70 @@ class LLMServiceClient:
            return LLMImageOptions()
        return options

+    @staticmethod
+    def _serialize_message_for_cache_stats(message: Message) -> Dict[str, Any]:
+        parts: list[dict[str, Any]] = []
+        for part in message.parts:
+            if hasattr(part, "text"):
+                parts.append({"type": "text", "text": part.text})
+                continue
+
+            image_base64 = getattr(part, "image_base64", "")
+            image_digest = hashlib.sha256(image_base64.encode("utf-8")).hexdigest() if image_base64 else ""
+            parts.append(
+                {
+                    "type": "image",
+                    "format": getattr(part, "image_format", ""),
+                    "size": len(image_base64),
+                    "sha256": image_digest,
+                }
+            )
+
+        return {
+            "role": str(message.role.value if hasattr(message.role, "value") else message.role),
+            "parts": parts,
+            "tool_call_id": message.tool_call_id,
+            "tool_name": message.tool_name,
+            "tool_calls": [
+                {
+                    "id": tool_call.call_id,
+                    "name": tool_call.func_name,
+                    "arguments": tool_call.args,
+                    "extra_content": tool_call.extra_content,
+                }
+                for tool_call in (message.tool_calls or [])
+            ],
+        }
+
+    @classmethod
+    def _build_cache_stats_prompt_text(
+        cls,
+        *,
+        messages: List[Message],
+        tool_options: Any,
+        response_format: Any,
+    ) -> str:
+        payload = {
+            "messages": [cls._serialize_message_for_cache_stats(message) for message in messages],
+            "tool_options": tool_options or [],
+            "response_format": response_format,
+        }
+        return json.dumps(payload, ensure_ascii=False, sort_keys=True, default=str)
+
+    def _record_cache_stats(self, result: LLMResponseResult, prompt_text: str | None = None) -> None:
+        """记录当前调用的 prompt cache 统计。"""
+
+        record_llm_cache_usage(
+            task_name=self.task_name,
+            request_type=self.request_type,
+            model_name=result.model_name,
+            session_id=self.session_id,
+            prompt_tokens=result.prompt_tokens,
+            prompt_cache_hit_tokens=result.prompt_cache_hit_tokens,
+            prompt_cache_miss_tokens=result.prompt_cache_miss_tokens,
+            prompt_text=prompt_text,
+        )
+
    async def generate_response(
        self,
        prompt: str,
@@ -100,7 +168,12 @@ class LLMServiceClient:
            LLMResponseResult: 统一文本生成结果。
        """
        active_options = self._normalize_generation_options(options)
-        return await self._orchestrator.generate_response_async(
+        prompt_text = self._build_cache_stats_prompt_text(
+            messages=[MessageBuilder().add_text_content(prompt).build()],
+            tool_options=active_options.tool_options,
+            response_format=active_options.response_format,
+        )
+        result = await self._orchestrator.generate_response_async(
            prompt=prompt,
            temperature=active_options.temperature,
            max_tokens=active_options.max_tokens,
@@ -109,6 +182,8 @@ class LLMServiceClient:
            raise_when_empty=active_options.raise_when_empty,
            interrupt_flag=active_options.interrupt_flag,
        )
+        self._record_cache_stats(result, prompt_text=prompt_text)
+        return result

    async def generate_response_with_messages(
        self,
@@ -125,8 +200,22 @@ class LLMServiceClient:
            LLMResponseResult: 统一文本生成结果。
        """
        active_options = self._normalize_generation_options(options)
-        return await self._orchestrator.generate_response_with_message_async(
-            message_factory=message_factory,
+        prompt_text_holder: dict[str, str] = {}
+
+        def cache_stats_message_factory(client: BaseClient, model_info: Any = None) -> List[Message]:
+            if len(inspect.signature(message_factory).parameters) >= 2:
+                messages = message_factory(client, model_info)
+            else:
+                messages = message_factory(client)
+            prompt_text_holder["prompt_text"] = self._build_cache_stats_prompt_text(
+                messages=messages,
+                tool_options=active_options.tool_options,
+                response_format=active_options.response_format,
+            )
+            return messages
+
+        result = await self._orchestrator.generate_response_with_message_async(
+            message_factory=cache_stats_message_factory,
            temperature=active_options.temperature,
            max_tokens=active_options.max_tokens,
            tools=active_options.tool_options,
@@ -134,6 +223,8 @@ class LLMServiceClient:
            raise_when_empty=active_options.raise_when_empty,
            interrupt_flag=active_options.interrupt_flag,
        )
+        self._record_cache_stats(result, prompt_text=prompt_text_holder.get("prompt_text"))
+        return result

    async def generate_response_for_image(
        self,
@@ -154,7 +245,30 @@ class LLMServiceClient:
            LLMResponseResult: 统一文本生成结果。
        """
        active_options = self._normalize_image_options(options)
-        return await self._orchestrator.generate_response_for_image(
+        image_digest = hashlib.sha256(image_base64.encode("utf-8")).hexdigest() if image_base64 else ""
+        prompt_text = json.dumps(
+            {
+                "messages": [
+                    {
+                        "role": "user",
+                        "parts": [
+                            {"type": "text", "text": prompt},
+                            {
+                                "type": "image",
+                                "format": image_format,
+                                "size": len(image_base64),
+                                "sha256": image_digest,
+                            },
+                        ],
+                    }
+                ],
+                "tool_options": [],
+                "response_format": None,
+            },
+            ensure_ascii=False,
+            sort_keys=True,
+        )
+        result = await self._orchestrator.generate_response_for_image(
            prompt=prompt,
            image_base64=image_base64,
            image_format=image_format,
@@ -162,6 +276,8 @@ class LLMServiceClient:
            max_tokens=active_options.max_tokens,
            interrupt_flag=active_options.interrupt_flag,
        )
+        self._record_cache_stats(result, prompt_text=prompt_text)
+        return result

    async def transcribe_audio(self, voice_base64: str) -> LLMAudioTranscriptionResult:
        """执行音频转写请求。
--- a/src/webui/config_schema.py
+++ b/src/webui/config_schema.py
@@ -70,11 +70,15 @@ class ConfigSchemaGenerator:
    ) -> Dict[str, Any]:
        field_docs = config_class.get_class_field_docs()
        field_type = cls._map_field_type(annotation)
+        raw_description = field_docs.get(field_name, field_info.description or "")
+        # `_wrap_` 标记在配置类 docstring 中表示该说明应作为块级注释（独立成行）
+        # 在前端展示时把它转为换行符，使描述以新行起始或在中间换行
+        description = raw_description.replace("_wrap_", "\n").strip("\n")
        schema: Dict[str, Any] = {
            "name": field_name,
            "type": field_type,
            "label": field_name,
-            "description": field_docs.get(field_name, field_info.description or ""),
+            "description": description,
            "required": field_info.is_required(),
        }

--- a/src/webui/routers/chat/routes.py
+++ b/src/webui/routers/chat/routes.py
@@ -13,10 +13,10 @@ from src.config.config import global_config
 from src.webui.dependencies import require_auth

 from .service import (
-    WEBUI_CHAT_GROUP_ID,
    WEBUI_CHAT_PLATFORM,
    chat_history,
    chat_manager,
+    normalize_webui_user_id,
 )

 logger = get_logger("webui.chat")
@@ -30,10 +30,15 @@ async def get_chat_history(
    user_id: Optional[str] = Query(default=None),
    group_id: Optional[str] = Query(default=None),
 ) -> Dict[str, object]:
-    """获取聊天历史记录。"""
-    del user_id
-    target_group_id = group_id or WEBUI_CHAT_GROUP_ID
-    history = chat_history.get_history(limit, target_group_id)
+    """获取聊天历史记录。
+
+    优先按 ``group_id`` 加载虚拟群聊历史；未提供时使用规范化后的 ``user_id`` 加载 WebUI 私聊历史。
+    """
+    if group_id:
+        history = chat_history.get_history(limit, group_id=group_id)
+    else:
+        normalized_user_id = normalize_webui_user_id(user_id)
+        history = chat_history.get_history(limit, user_id=normalized_user_id)
    return {"success": True, "messages": history, "total": len(history)}


@@ -100,10 +105,18 @@ async def get_persons_by_platform(

@router.delete("/history")
 async def clear_chat_history(
+    user_id: Optional[str] = Query(default=None),
    group_id: Optional[str] = Query(default=None),
 ) -> Dict[str, object]:
-    """清空聊天历史记录。"""
-    deleted = chat_history.clear_history(group_id)
+    """清空聊天历史记录。
+
+    优先按 ``group_id`` 清理虚拟群聊历史；未提供时使用规范化后的 ``user_id`` 清理 WebUI 私聊历史。
+    """
+    if group_id:
+        deleted = chat_history.clear_history(group_id=group_id)
+    else:
+        normalized_user_id = normalize_webui_user_id(user_id)
+        deleted = chat_history.clear_history(user_id=normalized_user_id)
    return {"success": True, "message": f"已清空 {deleted} 条聊天记录"}


@@ -113,6 +126,5 @@ async def get_chat_info() -> Dict[str, object]:
    return {
        "bot_name": global_config.bot.nickname,
        "platform": WEBUI_CHAT_PLATFORM,
-        "group_id": WEBUI_CHAT_GROUP_ID,
        "active_sessions": len(chat_manager.active_connections),
    }
--- a/src/webui/routers/chat/service.py
+++ b/src/webui/routers/chat/service.py
@@ -18,6 +18,8 @@ from src.common.message_repository import find_messages
 from src.common.utils.utils_session import SessionUtils
 from src.config.config import global_config

+from .serializers import serialize_message_sequence
+
 logger = get_logger("webui.chat")

 WEBUI_CHAT_GROUP_ID = "webui_local_chat"
@@ -61,7 +63,7 @@ class ChatSessionConnection:
    client_session_id: str
    user_id: str
    user_name: str
-    active_group_id: str
+    channel_key: str
    virtual_config: Optional[VirtualIdentityConfig]
    sender: AsyncMessageSender

@@ -92,6 +94,21 @@ class ChatHistoryManager:
        user_id = user_info.user_id or ""
        is_bot = is_bot_self(msg.platform, user_id)

+        # 将存库中的 raw_message 序列化为前端可识别的富文本消息段，
+        # 避免“刚刚收到的机器人回复是富文本，刷新后变成纯文本”的体验不一致。
+        segments: List[Dict[str, Any]] = []
+        try:
+            raw_message = getattr(msg, "raw_message", None)
+            if raw_message is not None and getattr(raw_message, "components", None):
+                segments = serialize_message_sequence(raw_message)
+        except Exception as exc:  # 仅记录警告，退化为纯文本
+            logger.debug(f"序列化历史消息段失败，退化为纯文本: {exc}")
+            segments = []
+
+        is_rich = bool(segments) and not (
+            len(segments) == 1 and segments[0].get("type") == "text"
+        )
+
        return {
            "id": msg.message_id,
            "type": "bot" if is_bot else "user",
@@ -100,32 +117,119 @@ class ChatHistoryManager:
            "sender_name": user_info.user_nickname or (global_config.bot.nickname if is_bot else "未知用户"),
            "sender_id": "bot" if is_bot else user_id,
            "is_bot": is_bot,
+            "message_type": "rich" if is_rich else "text",
+            "segments": segments if is_rich else None,
        }

-    def _resolve_session_id(self, group_id: Optional[str]) -> str:
-        """根据群组标识解析聊天会话 ID。
+    def _enrich_reply_segments(
+        self,
+        segments: List[Dict[str, Any]],
+        message_index: Dict[str, SessionMessage],
+        session_id: Optional[str],
+    ) -> None:
+        """回填历史消息中 reply 段缺失的发送者/原内容字段。
+
+        DB 中持久化的 ReplyComponent 通常只保留了 ``target_message_id``，
+        ``target_message_content`` / ``target_message_sender_*`` 字段为空。
+        这里基于当前会话已加载的消息列表（必要时回查数据库）进行补全。

        Args:
-            group_id: 群组标识。
+            segments: 单条历史消息的消息段列表，原地修改。
+            message_index: 当前会话已加载消息的 ``message_id -> SessionMessage`` 索引。
+            session_id: 当前会话 ID，用于按 ID 单查时缩小范围。
+        """
+        for segment in segments:
+            if not isinstance(segment, dict) or segment.get("type") != "reply":
+                continue
+            data = segment.get("data")
+            if not isinstance(data, dict):
+                continue
+            target_message_id = data.get("target_message_id")
+            if not target_message_id:
+                continue
+
+            has_content = bool(str(data.get("target_message_content") or "").strip())
+            has_sender = any(
+                str(data.get(key) or "").strip()
+                for key in (
+                    "target_message_sender_id",
+                    "target_message_sender_nickname",
+                    "target_message_sender_cardname",
+                )
+            )
+            if has_content and has_sender:
+                continue
+
+            target_msg = message_index.get(str(target_message_id))
+            if target_msg is None:
+                # 退化为按 ID 单查（仅当不在当前窗口内时才付出 DB 代价）
+                try:
+                    from src.services.message_service import get_message_by_id
+
+                    target_msg = get_message_by_id(str(target_message_id), session_id or None)
+                except Exception as exc:
+                    logger.debug(f"按 ID 回查 reply 目标消息失败: {exc}")
+                    target_msg = None
+            if target_msg is None:
+                continue
+
+            user_info = target_msg.message_info.user_info
+            if not has_content:
+                content_text = (
+                    target_msg.processed_plain_text
+                    or target_msg.display_message
+                    or ""
+                )
+                data["target_message_content"] = content_text
+            if not has_sender:
+                data["target_message_sender_id"] = user_info.user_id or ""
+                data["target_message_sender_nickname"] = user_info.user_nickname or ""
+                data["target_message_sender_cardname"] = (
+                    getattr(user_info, "user_cardname", "") or ""
+                )
+
+    def _resolve_session_id(
+        self,
+        group_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> Optional[str]:
+        """根据会话标识解析内部聊天会话 ID。
+
+        优先按虚拟群聊解析；否则按 WebUI 私聊解析。
+
+        Args:
+            group_id: 群组标识（虚拟群聊模式）。
+            user_id: 用户标识（私聊模式）。

        Returns:
-            str: 内部聊天会话 ID。
+            Optional[str]: 内部聊天会话 ID；当 group_id 与 user_id 均未提供时返回 ``None``。
        """
-        target_group_id = group_id or WEBUI_CHAT_GROUP_ID
-        return SessionUtils.calculate_session_id(WEBUI_CHAT_PLATFORM, group_id=target_group_id)
+        if group_id:
+            return SessionUtils.calculate_session_id(WEBUI_CHAT_PLATFORM, group_id=group_id)
+        if user_id:
+            return SessionUtils.calculate_session_id(WEBUI_CHAT_PLATFORM, user_id=user_id)
+        return None

-    def get_history(self, limit: int = 50, group_id: Optional[str] = None) -> List[Dict[str, Any]]:
+    def get_history(
+        self,
+        limit: int = 50,
+        group_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
        """获取指定会话的历史消息。

        Args:
            limit: 最大返回条数。
-            group_id: 群组标识。
+            group_id: 群组标识（虚拟群聊模式）。
+            user_id: 用户标识（私聊模式）。

        Returns:
            List[Dict[str, Any]]: 历史消息列表。
        """
-        target_group_id = group_id or WEBUI_CHAT_GROUP_ID
-        session_id = self._resolve_session_id(target_group_id)
+        session_id = self._resolve_session_id(group_id=group_id, user_id=user_id)
+        if session_id is None:
+            logger.debug("获取聊天历史时缺少 group_id 与 user_id，返回空列表")
+            return []
        try:
            messages = find_messages(
                session_id=session_id,
@@ -133,30 +237,54 @@ class ChatHistoryManager:
                limit_mode="latest",
                filter_command=False,
            )
-            result = [self._message_to_dict(msg, target_group_id) for msg in messages]
-            logger.debug(f"从数据库加载了 {len(result)} 条聊天记录 (group_id={target_group_id})")
+            # 构建 message_id -> SessionMessage 索引，用于回填历史中 reply 段的发送者/内容
+            # （DB 中通常只存了 target_message_id，target_message_content/sender_* 缺失）。
+            message_index: Dict[str, SessionMessage] = {}
+            for m in messages:
+                mid = getattr(m, "message_id", None)
+                if mid:
+                    message_index[str(mid)] = m
+
+            result: List[Dict[str, Any]] = []
+            for msg in messages:
+                item = self._message_to_dict(msg, group_id)
+                segments = item.get("segments")
+                if segments:
+                    self._enrich_reply_segments(segments, message_index, session_id)
+                result.append(item)
+            logger.debug(
+                f"从数据库加载了 {len(result)} 条聊天记录 (group_id={group_id}, user_id={user_id})"
+            )
            return result
        except Exception as exc:
            logger.error(f"从数据库加载聊天记录失败: {exc}")
            return []

-    def clear_history(self, group_id: Optional[str] = None) -> int:
+    def clear_history(
+        self,
+        group_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> int:
        """清空指定会话的历史消息。

        Args:
-            group_id: 群组标识。
+            group_id: 群组标识（虚拟群聊模式）。
+            user_id: 用户标识（私聊模式）。

        Returns:
            int: 被删除的消息数量。
        """
-        target_group_id = group_id or WEBUI_CHAT_GROUP_ID
-        session_id = self._resolve_session_id(target_group_id)
+        session_id = self._resolve_session_id(group_id=group_id, user_id=user_id)
+        if session_id is None:
+            return 0
        try:
            with get_db_session() as session:
                statement = delete(Messages).where(col(Messages.session_id) == session_id)
                result = session.exec(statement)
                deleted = result.rowcount or 0
-            logger.info(f"已清空 {deleted} 条聊天记录 (group_id={target_group_id})")
+            logger.info(
+                f"已清空 {deleted} 条聊天记录 (group_id={group_id}, user_id={user_id})"
+            )
            return deleted
        except Exception as exc:
            logger.error(f"清空聊天记录失败: {exc}")
@@ -174,30 +302,30 @@ class ChatConnectionManager:
        self.group_sessions: Dict[str, Set[str]] = {}
        self.user_sessions: Dict[str, Set[str]] = {}

-    def _bind_group(self, session_id: str, group_id: str) -> None:
-        """为会话绑定群组索引。
+    def _bind_channel(self, session_id: str, channel_key: str) -> None:
+        """为会话绑定逻辑频道索引。

        Args:
            session_id: 内部会话 ID。
-            group_id: 群组标识。
+            channel_key: 频道键（``group:<gid>`` 或 ``private:<uid>``）。
        """
-        group_session_ids = self.group_sessions.setdefault(group_id, set())
-        group_session_ids.add(session_id)
+        channel_session_ids = self.group_sessions.setdefault(channel_key, set())
+        channel_session_ids.add(session_id)

-    def _unbind_group(self, session_id: str, group_id: str) -> None:
-        """移除会话与群组的索引关系。
+    def _unbind_channel(self, session_id: str, channel_key: str) -> None:
+        """移除会话与逻辑频道的索引关系。

        Args:
            session_id: 内部会话 ID。
-            group_id: 群组标识。
+            channel_key: 频道键。
        """
-        group_session_ids = self.group_sessions.get(group_id)
-        if group_session_ids is None:
+        channel_session_ids = self.group_sessions.get(channel_key)
+        if channel_session_ids is None:
            return

-        group_session_ids.discard(session_id)
-        if not group_session_ids:
-            del self.group_sessions[group_id]
+        channel_session_ids.discard(session_id)
+        if not channel_session_ids:
+            del self.group_sessions[channel_key]

    async def connect(
        self,
@@ -220,18 +348,39 @@ class ChatConnectionManager:
            virtual_config: 当前虚拟身份配置。
            sender: 发送消息到前端的异步回调。
        """
+        channel_key = compute_channel_key(virtual_config, user_id)
        existing_session_id = self.client_sessions.get((connection_id, client_session_id))
+        if existing_session_id is not None and existing_session_id == session_id:
+            # 同一物理连接 + 前端会话重复打开（常见于 React StrictMode 双挂载或客户端去抖失败），
+            # 直接复用现有会话并仅刷新可变字段，避免反复断开/重连产生噪声日志。
+            existing = self.active_connections.get(existing_session_id)
+            if existing is not None:
+                if existing.channel_key != channel_key:
+                    self._unbind_channel(existing_session_id, existing.channel_key)
+                    self._bind_channel(existing_session_id, channel_key)
+                    existing.channel_key = channel_key
+                existing.user_id = user_id
+                existing.user_name = user_name
+                existing.virtual_config = virtual_config
+                existing.sender = sender
+                logger.debug(
+                    "WebUI 聊天会话复用: session=%s, connection=%s, client_session=%s, channel=%s",
+                    session_id,
+                    connection_id,
+                    client_session_id,
+                    channel_key,
+                )
+                return
        if existing_session_id is not None:
            self.disconnect(existing_session_id)

-        active_group_id = get_current_group_id(virtual_config)
        session_connection = ChatSessionConnection(
            session_id=session_id,
            connection_id=connection_id,
            client_session_id=client_session_id,
            user_id=user_id,
            user_name=user_name,
-            active_group_id=active_group_id,
+            channel_key=channel_key,
            virtual_config=virtual_config,
            sender=sender,
        )
@@ -240,14 +389,14 @@ class ChatConnectionManager:
        self.client_sessions[(connection_id, client_session_id)] = session_id
        self.connection_sessions.setdefault(connection_id, set()).add(session_id)
        self.user_sessions.setdefault(user_id, set()).add(session_id)
-        self._bind_group(session_id, active_group_id)
+        self._bind_channel(session_id, channel_key)
        logger.info(
-            "WebUI 聊天会话已连接: session=%s, connection=%s, client_session=%s, user=%s, group=%s",
+            "WebUI 聊天会话已连接: session=%s, connection=%s, client_session=%s, user=%s, channel=%s",
            session_id,
            connection_id,
            client_session_id,
            user_id,
-            active_group_id,
+            channel_key,
        )

    def disconnect(self, session_id: str) -> None:
@@ -261,7 +410,7 @@ class ChatConnectionManager:
            return

        self.client_sessions.pop((session_connection.connection_id, session_connection.client_session_id), None)
-        self._unbind_group(session_id, session_connection.active_group_id)
+        self._unbind_channel(session_id, session_connection.channel_key)

        connection_session_ids = self.connection_sessions.get(session_connection.connection_id)
        if connection_session_ids is not None:
@@ -327,11 +476,11 @@ class ChatConnectionManager:
        if session_connection is None:
            return

-        next_group_id = get_current_group_id(virtual_config)
-        if next_group_id != session_connection.active_group_id:
-            self._unbind_group(session_id, session_connection.active_group_id)
-            self._bind_group(session_id, next_group_id)
-            session_connection.active_group_id = next_group_id
+        next_channel_key = compute_channel_key(virtual_config, session_connection.user_id)
+        if next_channel_key != session_connection.channel_key:
+            self._unbind_channel(session_id, session_connection.channel_key)
+            self._bind_channel(session_id, next_channel_key)
+            session_connection.channel_key = next_channel_key

        session_connection.user_name = user_name
        session_connection.virtual_config = virtual_config
@@ -361,16 +510,40 @@ class ChatConnectionManager:
        for session_id in list(self.active_connections.keys()):
            await self.send_message(session_id, message)

-    async def broadcast_to_group(self, group_id: str, message: Dict[str, Any]) -> None:
-        """向指定群组下的全部逻辑会话广播消息。
+    async def broadcast_to_channel(self, channel_key: str, message: Dict[str, Any]) -> None:
+        """向指定逻辑频道下的全部会话广播消息。

        Args:
-            group_id: 群组标识。
+            channel_key: 频道键（``group:<gid>`` 或 ``private:<uid>``）。
            message: 待广播的消息内容。
        """
-        for session_id in list(self.group_sessions.get(group_id, set())):
+        for session_id in list(self.group_sessions.get(channel_key, set())):
            await self.send_message(session_id, message)

+    async def broadcast_to_group(
+        self,
+        group_id: Optional[str],
+        message: Dict[str, Any],
+        *,
+        user_id: Optional[str] = None,
+    ) -> None:
+        """向指定群组或私聊会话广播消息。
+
+        当 ``group_id`` 非空时按群聊广播；否则按 ``user_id`` 私聊广播。
+
+        Args:
+            group_id: 群组标识；为空时使用 ``user_id``。
+            message: 待广播的消息内容。
+            user_id: 私聊接收方用户 ID。
+        """
+        if group_id:
+            channel_key = f"group:{group_id}"
+        elif user_id:
+            channel_key = f"private:{user_id}"
+        else:
+            return
+        await self.broadcast_to_channel(channel_key, message)
+

 chat_history = ChatHistoryManager()
 chat_manager = ChatConnectionManager()
@@ -388,6 +561,24 @@ def is_virtual_mode_enabled(virtual_config: Optional[VirtualIdentityConfig]) ->
    return bool(virtual_config and virtual_config.enabled)


+def compute_channel_key(virtual_config: Optional[VirtualIdentityConfig], user_id: str) -> str:
+    """计算当前会话的逻辑频道键。
+
+    虚拟身份启用时使用虚拟群聊 ID，否则使用当前 WebUI 用户 ID 作为私聊频道。
+
+    Args:
+        virtual_config: 虚拟身份配置。
+        user_id: 当前 WebUI 用户 ID。
+
+    Returns:
+        str: 频道键，格式为 ``group:<gid>`` 或 ``private:<uid>``。
+    """
+    if is_virtual_mode_enabled(virtual_config):
+        assert virtual_config is not None
+        return f"group:{virtual_config.group_id}"
+    return f"private:{user_id}"
+
+
 def normalize_webui_user_id(user_id: Optional[str]) -> str:
    """标准化 WebUI 用户 ID。

@@ -500,6 +691,8 @@ def build_session_info_message(
    Returns:
        Dict[str, Any]: 会话信息消息。
    """
+    # bot_qq 用于前端从 QQ 头像公开接口拉取机器人头像（qq_account == 0 表示未配置，不推送）。
+    bot_qq_account = int(getattr(global_config.bot, "qq_account", 0) or 0)
    session_info_data: Dict[str, Any] = {
        "type": "session_info",
        "session_id": session_id,
@@ -507,6 +700,8 @@ def build_session_info_message(
        "user_name": user_name,
        "bot_name": global_config.bot.nickname,
    }
+    if bot_qq_account > 0:
+        session_info_data["bot_qq"] = str(bot_qq_account)

    if is_virtual_mode_enabled(virtual_config):
        assert virtual_config is not None
@@ -529,7 +724,7 @@ def get_active_history_group_id(virtual_config: Optional[VirtualIdentityConfig])
        virtual_config: 虚拟身份配置。

    Returns:
-        Optional[str]: 虚拟身份启用时返回对应群组 ID。
+        Optional[str]: 虚拟身份启用时返回对应群组 ID；否则返回 ``None`` 表示使用私聊。
    """
    if is_virtual_mode_enabled(virtual_config):
        assert virtual_config is not None
@@ -537,16 +732,16 @@ def get_active_history_group_id(virtual_config: Optional[VirtualIdentityConfig])
    return None


-def get_current_group_id(virtual_config: Optional[VirtualIdentityConfig]) -> str:
+def get_current_group_id(virtual_config: Optional[VirtualIdentityConfig]) -> Optional[str]:
    """获取当前会话的有效群组 ID。

    Args:
        virtual_config: 虚拟身份配置。

    Returns:
-        str: 当前会话应使用的群组 ID。
+        Optional[str]: 虚拟身份启用时返回对应群组 ID；否则返回 ``None``（默认私聊模式）。
    """
-    return get_active_history_group_id(virtual_config) or WEBUI_CHAT_GROUP_ID
+    return get_active_history_group_id(virtual_config)


 def build_welcome_message(virtual_config: Optional[VirtualIdentityConfig]) -> str:
@@ -611,7 +806,12 @@ async def send_initial_chat_state(
    )

    history_group_id = get_active_history_group_id(virtual_config)
-    history = chat_history.get_history(50, history_group_id)
+    history_user_id = None if history_group_id else user_id
+    history = chat_history.get_history(
+        50,
+        group_id=history_group_id,
+        user_id=history_user_id,
+    )
    await chat_manager.send_message(
        session_id,
        {
@@ -679,37 +879,42 @@ def create_message_data(

    if virtual_config and virtual_config.enabled:
        platform = virtual_config.platform or WEBUI_CHAT_PLATFORM
-        group_id = virtual_config.group_id or f"{VIRTUAL_GROUP_ID_PREFIX}{uuid.uuid4().hex[:8]}"
-        group_name = virtual_config.group_name or "WebUI虚拟群聊"
+        group_id: Optional[str] = (
+            virtual_config.group_id or f"{VIRTUAL_GROUP_ID_PREFIX}{uuid.uuid4().hex[:8]}"
+        )
+        group_name: Optional[str] = virtual_config.group_name or "WebUI虚拟群聊"
        actual_user_id = virtual_config.user_id or user_id
-        actual_user_name = virtual_config.user_nickname or user_name
+        actual_user_nickname = virtual_config.user_nickname or user_name
    else:
        platform = WEBUI_CHAT_PLATFORM
-        group_id = WEBUI_CHAT_GROUP_ID
-        group_name = "WebUI本地聊天室"
+        group_id = None
+        group_name = None
        actual_user_id = user_id
-        actual_user_name = user_name
+        actual_user_nickname = user_name
+
+    message_info: Dict[str, Any] = {
+        "platform": platform,
+        "message_id": message_id,
+        "time": time.time(),
+        "user_info": {
+            "user_id": actual_user_id,
+            "user_nickname": actual_user_nickname,
+            "user_cardname": actual_user_nickname,
+            "platform": platform,
+        },
+        "additional_config": {
+            "at_bot": is_at_bot,
+        },
+    }
+    if group_id is not None:
+        message_info["group_info"] = {
+            "group_id": group_id,
+            "group_name": group_name,
+            "platform": platform,
+        }

    return {
-        "message_info": {
-            "platform": platform,
-            "message_id": message_id,
-            "time": time.time(),
-            "group_info": {
-                "group_id": group_id,
-                "group_name": group_name,
-                "platform": platform,
-            },
-            "user_info": {
-                "user_id": actual_user_id,
-                "user_nickname": actual_user_name,
-                "user_cardname": actual_user_name,
-                "platform": platform,
-            },
-            "additional_config": {
-                "at_bot": is_at_bot,
-            },
-        },
+        "message_info": message_info,
        "message_segment": {
            "type": "seglist",
            "data": [
@@ -717,10 +922,6 @@ def create_message_data(
                    "type": "text",
                    "data": content,
                },
-                {
-                    "type": "mention_bot",
-                    "data": "1.0",
-                },
            ],
        },
        "raw_message": content,
@@ -776,6 +977,7 @@ async def handle_chat_message(
            },
            "virtual_mode": is_virtual_mode_enabled(current_virtual_config),
        },
+        user_id=normalized_user_id,
    )

    message_data = create_message_data(
@@ -788,13 +990,21 @@ async def handle_chat_message(
    )

    try:
-        await chat_manager.broadcast_to_group(target_group_id, {"type": "typing", "is_typing": True})
+        await chat_manager.broadcast_to_group(
+            target_group_id,
+            {"type": "typing", "is_typing": True},
+            user_id=normalized_user_id,
+        )
        await chat_bot.message_process(message_data)
    except Exception as exc:
        logger.error(f"处理消息时出错: {exc}")
        await send_chat_error(session_id, f"处理消息时出错: {str(exc)}")
    finally:
-        await chat_manager.broadcast_to_group(target_group_id, {"type": "typing", "is_typing": False})
+        await chat_manager.broadcast_to_group(
+            target_group_id,
+            {"type": "typing", "is_typing": False},
+            user_id=normalized_user_id,
+        )

    return next_user_name

@@ -915,11 +1125,12 @@ async def enable_virtual_identity(
        return None


-async def disable_virtual_identity(session_id: str) -> None:
+async def disable_virtual_identity(session_id: str, normalized_user_id: str) -> None:
    """关闭虚拟身份模式。

    Args:
        session_id: 内部逻辑会话 ID。
+        normalized_user_id: 规范化后的 WebUI 用户 ID，用于加载私聊历史。
    """
    await chat_manager.send_message(
        session_id,
@@ -933,8 +1144,8 @@ async def disable_virtual_identity(session_id: str) -> None:
        session_id,
        {
            "type": "history",
-            "messages": chat_history.get_history(50, WEBUI_CHAT_GROUP_ID),
-            "group_id": WEBUI_CHAT_GROUP_ID,
+            "messages": chat_history.get_history(50, user_id=normalized_user_id),
+            "group_id": None,
        },
    )
    await chat_manager.send_message(
@@ -952,6 +1163,7 @@ async def handle_virtual_identity_update(
    session_id_prefix: str,
    data: Dict[str, Any],
    current_virtual_config: Optional[VirtualIdentityConfig],
+    normalized_user_id: str,
 ) -> Optional[VirtualIdentityConfig]:
    """处理虚拟身份切换请求。

@@ -960,6 +1172,7 @@ async def handle_virtual_identity_update(
        session_id_prefix: 会话前缀。
        data: 前端提交的数据。
        current_virtual_config: 当前虚拟身份配置。
+        normalized_user_id: 规范化后的 WebUI 用户 ID。

    Returns:
        Optional[VirtualIdentityConfig]: 更新后的虚拟身份配置。
@@ -969,7 +1182,7 @@ async def handle_virtual_identity_update(
        next_config = await enable_virtual_identity(session_id, session_id_prefix, virtual_data)
        return next_config if next_config is not None else current_virtual_config

-    await disable_virtual_identity(session_id)
+    await disable_virtual_identity(session_id, normalized_user_id)
    return None


@@ -1019,6 +1232,7 @@ async def dispatch_chat_event(
            session_id_prefix=session_id_prefix,
            data=data,
            current_virtual_config=current_virtual_config,
+            normalized_user_id=normalized_user_id,
        )
        return current_user_name, next_virtual_config