项目介绍

wyf9s-discord-bot 是一个多功能 Discord 机器人，基于 discord.py 构建，使用 YAML + Pydantic v2 进行配置验证，采用模块化 Cog 架构。

整体架构

config.py            # Pydantic 配置模型 + 加载器
config.yaml          # 运行时配置 (被 gitignore)
config.example.yaml  # 带内联文档的示例配置 (配置字段的事实来源)
schedules.yaml       # 计划锁定数据 (自动生成)
perm.yaml            # 动态权限数据 (通过 /perm 指令管理)
main.py              # 机器人入口，Cog 加载
utils.py             # 共享工具 (权限判定、限速器、消息发送等)
perm.py              # 动态权限存储服务
cogs/                # 命令模块 (discord.py Cog)
  admin.py           # 管理指令: /sync, /reload
  emoji.py           # 表情 / 贴纸指令: /e, /emoji info, /emoji update
  tools.py           # 工具 / 管理指令
  lock.py            # 频道锁定 / 解锁 + 计划锁定
  voice.py           # 语音频道指令: /vc join, /vc leave
  antispam.py        # 反垃圾消息处理
  manage.py          # 自动删除事件处理
  perm.py            # 动态权限指令: /perm add/rm/show
modules/             # 共享服务 (非 Cog)
  audit.py           # 审计日志服务
  clear_message.py   # 批量清理消息服务

启动流程

main.py 的启动过程如下：

初始化日志：先配置 Loguru，并将标准库 logging（含 discord.py 的日志）拦截转发到 Loguru。
加载配置：Config() 读取 config.yaml，用 Pydantic 模型校验。校验失败或文件缺失会直接退出。
重配置日志：根据配置的日志等级、文件路径、轮转/保留策略重新设置输出。
创建客户端：commands.Bot，启用 message_content intent，可选配置代理。将 config、audit、rate_limiter、perm_store 等共享状态挂载到 bot 实例上。
加载 Cog：通过 load_extension() 按需加载各 Cog 模块 (根据 enabled 开关)。
登录：on_ready 时同步斜杠指令、同步表情列表。

核心设计

Cog 架构

所有命令模块使用 discord.py Cog 架构，支持热重载 (/reload)、生命周期钩子 (cog_load / cog_unload)、事件监听 (@Cog.listener)。共享状态 (emoji 缓存、限速器、计划锁定数据、动态权限等) 存储在 bot 实例上，重载 Cog 不会丢失：

python

class EmojiCog(commands.Cog):
    def __init__(self, bot: commands.Bot):
        self.bot = bot
        self.c = bot.config
        ...

    @app_commands.command(name="e", description="Send an emoji")
    async def e(self, interaction: discord.Interaction, name: str):
        ...

    # 子命令组
    emoji_group = app_commands.Group(name="emoji", description="...")

    @emoji_group.command(name="update")
    async def emoji_update(self, interaction: discord.Interaction):
        ...

热重载

/reload [module] 可在不重启 bot 的情况下热更新单个 Cog (有 15s 冷却防滥用)。不带参数则列出所有可用 Cog 及加载状态。语音连接 (VoiceClient)、限速状态、计划锁数据等存储在 bot 实例上，重载时不会丢失。

声明式权限控制

通过 @u.requires(Permission.MOD) 装饰器统一进行权限判定，支持 config.yaml + perm.yaml 双层权限。详见权限系统。

双命令模式

模式	触发方式	配置开关
斜杠命令	`/random`	各模块的 `slash: true`
前缀命令	`//vc leave`（前缀由 `command_prefix` 决定）	各模块的 `prefix: true`

关于前缀命令的参数

斜杠命令通过 Discord 原生参数 UI 传参；前缀命令部分复杂指令（如 clear-message、lock plan）使用 --key=value 形式的 flag 传参（支持带引号的值）。

技术栈

组件	说明
Python 3.13	运行时（`pyproject.toml` 要求 `>=3.10`）
uv	包管理器
discord.py `[voice]`	Discord API 封装 (Cog 架构)
Pydantic v2	配置模型验证
PyYAML	配置文件解析
Loguru	日志记录
aiohttp	异步 HTTP 请求
davey / PyNaCl	语音 / DAVE 加密支持

功能模块一览

模块	键名	类型	说明
工具 / 管理	`tools`	指令	随机数 / UUID、删消息、批量清理、频道移动、文本转文件
表情	`emoji`	指令	远程表情包浏览 / 搜索 / 发送
频道锁定	`lock`	指令	锁定 / 解锁频道，计划锁定
语音频道	`voicechannel`	指令	加入 / 离开语音频道
管理指令	—	指令	指令同步 `/sync`、热重载 `/reload`
动态权限	`perm`	指令	`/perm add/rm/show` 权限规则管理
自动管理	`rmmsg` / `rmtodo`	事件	自动删除消息
反垃圾	`antispam`	事件	频道级反垃圾规则
审计日志	`audit`	服务	记录管理操作到指定频道

每个模块的详细指令、用法、所需权限见模块总览。

项目介绍 ​

整体架构 ​

启动流程 ​

核心设计 ​

Cog 架构 ​

热重载 ​

声明式权限控制 ​

双命令模式 ​

技术栈 ​

功能模块一览 ​