Mofox-Core/.github/copilot-instructions.md

MoFox_Bot AI Coding Agent Instructions

MoFox_Bot 是基于 MaiCore 的增强型 QQ 聊天机器人，集成了 LLM、插件系统、记忆图谱、情感系统等高级特性。本指南帮助 AI 代理快速理解项目架构并高效开发。

🏗️ 核心架构

应用启动流程

• 入口点: bot.py → src/main.py 的 MainSystem 类
• 启动顺序: EULA 检查 → 数据库初始化 → 插件加载 → 组件初始化 → WebUI 启动（可选）
• 关键管理器: 所有管理器通过单例模式获取（如 get_xxx_manager()）

六层数据库架构

项目在 2025年11月重构了完整的数据库层，采用 SQLAlchemy 2.0：

1. Core Layer (src/common/database/core.py): DatabaseEngine 单例、WAL 模式 SQLite、连接池管理
2. API Layer (src/common/database/api/): CRUDBase 通用 CRUD、QueryBuilder 链式查询、specialized.py 业务特化 API
3. Optimization Layer (src/common/database/optimization/): 3级缓存 (L1内存/L2 SQLite/L3预加载)、IntelligentPreloader、AdaptiveBatchScheduler
4. Config Layer (src/common/database/config/): 数据库/缓存/预加载器配置
5. Utils Layer (src/common/database/utils/): 装饰器（重试、超时、缓存）、性能监控
6. Compatibility Layer (src/common/database/compatibility/): 向后兼容旧 API（db_query、db_save 等）

关键原则:

• ✅ 新代码使用 CRUDBase 或 QueryBuilder
• ✅ 批量操作使用 AdaptiveBatchScheduler
• ⚠️ 避免直接使用 Session，使用提供的 API 层
• ⚠️ 数据模型在 src/common/database/sqlalchemy_models.py 统一定义

插件系统架构

核心概念: 组件化设计，插件包含多个可注册组件

组件类型 (src/plugin_system/base/component_types.py):

• ACTION: 主动/被动行为（回复、发送表情、禁言等）
• COMMAND: 命令处理（传统 / 前缀命令）
• PLUS_COMMAND: 增强命令（支持参数解析、权限检查）
• TOOL: LLM 工具调用（函数调用集成）
• EVENT_HANDLER: 事件订阅处理器
• INTEREST_CALCULATOR: 兴趣值计算器
• PROMPT: 自定义提示词注入

插件开发流程:

1. 在 plugins/ 下创建目录，编写 _manifest.json
2. 创建 plugin.py，继承 BasePlugin 或 PlusPlugin
3. 使用 @register_plugin 装饰器注册
4. 实现 get_plugin_components() 返回组件列表
5. 组件通过 ComponentRegistry 自动注册

示例结构:

from src.plugin_system import BasePlugin, register_plugin, BaseAction

@register_plugin
class MyPlugin(BasePlugin):
    plugin_name = "my_plugin"
    enable_plugin = True
    
    def get_plugin_components(self):
        return [(ActionInfo(...), MyAction)]

关键 API (src/plugin_system/apis/):

• chat_api: 聊天功能（获取消息、发送消息）
• database_api: 数据库操作（推荐使用新 API）
• llm_api: LLM 交互（模型调用、工具注册）
• permission_api: 权限管理（检查权限、节点操作）
• component_manage_api: 组件查询与管理

统一调度器（Unified Scheduler）

位置: src/schedule/unified_scheduler.py

触发类型:

• TIME: 延迟触发（delay_seconds）或指定时间（trigger_at）
• EVENT: 事件触发（基于 event_manager）
• CUSTOM: 自定义条件函数

使用模式:

from src.schedule.unified_scheduler import unified_scheduler, TriggerType

await unified_scheduler.create_schedule(
    callback=my_async_function,
    trigger_type=TriggerType.TIME,
    trigger_config={"delay_seconds": 30},
    is_recurring=True,
    task_name="periodic_task"
)

⚠️ 自动启动: 调度器在 MainSystem.initialize() 中自动启动，无需手动初始化

记忆系统架构

双轨记忆:

• Memory Graph (src/memory_graph/): 基于图的持久记忆（人物、事件、关系）
• Chat Memory (src/chat/memory_system/): 会话上下文记忆

兴趣值系统 (src/chat/interest_system/):

• 通过插件自动注册 InterestCalculator 组件
• 支持主题聚类、时间衰减、动态权重
• 影响 AFC (Affinity Flow Chatter) 对话策略

关系系统 (src/person_info/):

• 亲密度值影响回复风格和语气
• 与兴趣值系统协同工作

🛠️ 开发工作流

环境管理

首选: uv 包管理器（配置清华镜像）

uv venv
uv pip install -r requirements.txt

环境配置:

1. 复制 template/template.env → .env
2. 设置 EULA_CONFIRMED=true
3. 编辑 config/bot_config.toml 和 config/model_config.toml

代码质量

Linter: Ruff（配置在 pyproject.toml）

ruff check .      # 检查
ruff format .     # 格式化

规范:

• 行长度: 120 字符
• 引号: 双引号
• 类型提示: 推荐使用（尤其是公共 API）
• 异步优先: 所有 I/O 操作使用 async/await

日志系统

位置: src/common/logger.py

使用模式:

from src.common.logger import get_logger

logger = get_logger("module_name")
logger.info("信息")
logger.error("错误")

日志级别: 通过 bot_config.toml 的 [logging] 配置

运行与调试

启动命令:

python bot.py              # 标准启动
python __main__.py         # 备用入口

WebUI 开发:

• WebUI 位于同级目录 webui/ 或 ../webui
• 自动通过 npm run dev 启动（可在 .env 设置 WEBUI_DIR）
• 超时 60 秒检测是否成功

调试技巧:

• 检查 logs/app_*.jsonl 结构化日志
• 使用 get_errors() 工具查看编译错误
• 数据库问题：查看 data/MaiBot.db（SQLite）或 PostgreSQL 连接

📋 关键约定与模式

配置管理

全局配置: src/config/config.py 的 global_config 单例

• 通过 TOML 文件驱动（config/bot_config.toml）
• 支持环境变量覆盖（.env）
• 数据库类型切换：database.database_type = "sqlite" | "postgresql"

事件系统

Event Manager (src/plugin_system/core/event_manager.py):

from src.plugin_system.core.event_manager import event_manager
from src.plugin_system.base.component_types import EventType

await event_manager.trigger_event(
    EventType.ON_MESSAGE_RECEIVED,
    message_data=data,
    permission_group="USER"
)

常用事件:

• ON_START / ON_STOP: 系统生命周期
• ON_MESSAGE_RECEIVED: 消息接收
• ON_PLUGIN_LOADED / ON_PLUGIN_UNLOADED: 插件生命周期

消息处理

核心类: ChatBot (src/chat/message_receive/bot.py)

• 消息通过 _message_process_wrapper 异步并行处理
• 使用 MessageStorageBatcher 批量存储（src/chat/message_receive/storage.py）
• 消息分块重组: MessageReassembler (src/utils/message_chunker.py)

批量操作最佳实践

场景: 需要保存大量数据库记录

from src.common.database.optimization.batch_scheduler import get_batch_scheduler

scheduler = get_batch_scheduler()
await scheduler.schedule_batch_insert(model_class, data_list)

权限系统

检查权限:

from src.plugin_system.apis.permission_api import permission_api

has_permission = await permission_api.check_permission(
    user_id="123456",
    platform="qq",
    permission_node="plugin.my_plugin.admin"
)

Master 用户: 在 bot_config.toml 的 [permission.master_users] 配置

🔍 常见问题与陷阱

数据库相关

❌ 错误: 直接创建 Session 对象 ✅ 正确: 使用 CRUDBase 或 QueryBuilder API

❌ 错误: 循环中逐条插入 ✅ 正确: 使用 AdaptiveBatchScheduler 批量插入

插件开发

❌ 错误: 在 __init__ 中执行异步操作 ✅ 正确: 在 on_plugin_loaded() 中执行异步初始化

❌ 错误: 硬编码配置值 ✅ 正确: 使用 self.plugin_config 读取配置

性能优化

⚠️ 避免: 在主事件循环中阻塞 I/O ✅ 使用: asyncio.to_thread() 或 loop.run_in_executor()

⚠️ 避免: 频繁的小查询 ✅ 使用: 预加载、缓存或批量查询

📚 关键文档参考

• 插件开发: docs/plugins/quick-start.md
• 数据库架构: docs/database_refactoring_completion.md
• 统一调度器: docs/unified_scheduler_guide.md
• 记忆图谱: docs/memory_graph_guide.md
• 部署指南: docs/deployment_guide.md
• 配置说明: 在线文档 https://mofox-studio.github.io/MoFox-Bot-Docs/

🎯 快速定位关键文件

功能域	入口文件
主系统	src/main.py
插件管理器	src/plugin_system/core/plugin_manager.py
数据库 API	src/common/database/api/crud.py
消息处理	src/chat/message_receive/bot.py
LLM 集成	src/llm_models/model_client/
配置系统	src/config/config.py
日志系统	src/common/logger.py

---

项目特色: 本项目集成了 MCP (Model Context Protocol) 支持、Affinity Flow Chatter 智能对话、视频分析、日程管理等独特功能。探索 src/plugins/built_in/ 查看内置插件示例。