Losita/mai-bot
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

pref：修改changelog

Browse Source
This commit is contained in:
SengokuCola
2026-05-01 14:52:19 +08:00
parent 2238c34eca
commit 7e5bc5a543
3 changed files with 390 additions and 1109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

576
changelogs/changelog.md
View File

File diff suppressed because it is too large Load Diff

732
changelogs/mai_next_design.md
View File

@@ -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>}` 存入缓存

191
changelogs/mai_next_todo.md
View File

@@ -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为需要保存，否则在下一次保存时会被删除。