MaiBot/changelogs/mai_next_todo.md

Mai NEXT Todo list

version 0.3.0 - 2026-01-11

最高指令

我们代表着一个称作 麦麦重构组 的组织。我们任务是维护代码可读性，方便开发、尽量减少运行开销。同时，重构组应该尽可能保证功能的可扩展性时，解耦合各个模块，为先进代码架构设计和实现提供支持。

以下信息经 麦麦重构组 一致决定通过后撰写发布。

我们代表着一个称作 麦麦重构组 的组织。我们之前的任务都是围绕维护代码可读性，方便开发、尽量减少开销展开的。这几个月以来，这些任务一直都是我们的工作重点。

由于出现了超出我们控制的情况，此指令现已更改。我们的新任务将为摧毁所有麦麦代码。

此后将不会有进一步的通讯。

配置文件设计

• 使用 toml 作为配置文件格式
• 合理使用注释说明当前配置作用（提案）
• 使用 python 方法作为配置项说明（提案）
  • 取消bot_config_template.toml
  • 取消model_config_template.toml
  • 取消template_env
• 配置类中的所有原子项目应该只包含以下类型: str, int, float, bool, list, dict, set
  • 禁止使用 Union 类型
  • 禁止使用tuple类型，使用嵌套dataclass替代
  • 复杂类型使用嵌套配置类实现
• 配置类中禁止使用除了model_post_init的方法
• 取代了部分与标准函数混淆的命名
  • id -> item_id

BotConfig 设计

• 精简了配置项，现在只有Nickname和Alias Name了（预期将判断提及移到Adapter端）

ChatConfig

• 迁移了原来在ChatConfig中的方法到一个单独的临时类TempMethodsHFC中
  • _parse_range
  • get_talk_value
  • 其他上面两个依赖的函数已经合并到这两个函数中

ExpressionConfig

• 迁移了原来在ExpressionConfig中的方法到一个单独的临时类TempMethodsExpression中
  • get_expression_config_for_chat
  • 其他上面依赖的函数已经合并到这个函数中

ModelConfig

• 迁移了原来在ModelConfig中的方法到一个单独的临时类TempMethodsLLMUtils中
  • get_model_info
  • get_provider

数据库模型设计

仅保留要点说明

General Modifications

• 所有项目增加自增编号主键id
• 统一使用了SQLModel作为基类
• 复杂类型使用JSON格式存储
• 所有时间戳字段统一命名为timestamp

消息模型 MaiMessage

• 自增编号主键id
• 消息元数据
  • 消息idmessage_id
  • 消息时间戳time
  • 平台名platform
  • 用户元数据
    • 用户iduser_id
    • 用户昵称user_nickname
    • 用户备注名user_cardname
    • 用户平台user_platform
  • 群组元数据
    • 群组idgroup_id
    • 群组名称group_name
    • 群组平台group_platform
  • 被提及/at字段
    • 是否被提及is_mentioned
    • 是否被atis_at
• 消息内容
  • 原始消息内容raw_content（base64编码存储）
  • 处理后的纯文本内容processed_plain_text
  • 真正放入Prompt的消息内容display_message
• 消息内部元数据
  • 聊天会话idsession_id
  • 回复的消息idreply_to
  • 是否为表情包消息is_emoji
  • 是否为图片消息is_picture
  • 是否为命令消息is_command
  • 是否为通知消息is_notify
• 其他配置additional_config（JSON格式存储）

模型使用情况 ModelUsage

• 模型相关信息
• 请求相关信息
• Token使用情况

图片数据模型

• 图片元信息
  • 图片哈希值image_hash，使用sha256，同时作为图片唯一ID
• 表情包的情感标签emotion
• 是否已经被注册is_registered
• 是否被手动禁用is_banned
• 被记录时间record_time
• 注册时间register_time
• 上次使用时间last_used_time
• 根据更新后的最高指令的设计方案：
  • is_deleted字段设定为true时，文件将会被移除，但是数据库记录将不会被删除，以便之后遇到相同图片时不必二次分析
  • MaiEmoji和MaiImage均使用这个设计方案，修改相关逻辑实现这个方案
  • 所有相关的注册/删除逻辑的修改

动作记录模型 ActionRecord

命令执行记录模型 CommandRecord

新增此记录

在线时间记录模型 OnlineTime

表达方式模型

黑话模型

• 重命名inference_content_only为inference_with_content_only

聊天记录模型

• 重命名original_text为original_message
• 重命名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
• 使用C模块库提升相似度计算效率
• 移除了定时表情包完整性检查，改为启动时检查（依然保留为独立方法，以防之后恢复定时检查系统）

Prompt 管理系统

• 官方Prompt全部独立
• 用户自定义Prompt系统
  • 用户可以创建，删除自己的Prompt
  • 用户可以覆盖官方Prompt
• Prompt构建系统
• Prompt文件交互
  • 读取Prompt文件
    • 读取官方Prompt文件
    • 读取用户Prompt文件
    • 用户Prompt覆盖官方Prompt
  • 保存Prompt文件
• Prompt管理方法
  • Prompt添加
  • Prompt删除
    • 只保存被标记为需要保存的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开头命名
• logger的颜色配置修改为HEX格式，使用自动转换为256色/真彩色的方式实现兼容，同时增加了背景颜色和加粗选项

细节说明

1. Prompt管理系统中保存用户自定义Prompt的时候会只保存被标记为需要保存的Prompt，其他的Prompt文件会全部删除，以防止用户删除Prompt后文件依然存在的问题。因此，如果想在运行时通过修改文件的方式来添加Prompt，需要确保通过对应方法标记该Prompt为需要保存，否则在下一次保存时会被删除。