130 lines
5.8 KiB
Markdown
130 lines
5.8 KiB
Markdown
# 禾汐 (HeXi)
|
||
|
||
基于 **NoneBot2** 的个人娱乐 QQ 机器人,使用 **OneBot V11** 协议接入。集成了游戏战绩查询、群聊学习、每日打卡、人设卡、表情包等大量功能,以插件化方式组织,方便增删。
|
||
|
||
## 功能特性
|
||
|
||
### 游戏相关
|
||
|
||
| 插件 | 功能 | 主要命令 |
|
||
| --- | --- | --- |
|
||
| `nonebot_plugin_bf_bot` | 战地系列 (BF3/BF4/BF1/BFV/BF2042/BF6) 战绩查询,PIL 生成统计卡片 | `/bft` `/bfbind` `/unbind` `/update_bind` |
|
||
| `nonebot_plugin_deadlock` | Deadlock 战绩、段位、近期比赛查询 | `/nekoscore` `/nekobind` `/nekounbind` `/nekorank` `/nekomatch` |
|
||
| `nonebot_plugin_steam_info` | Steam 玩家信息、库存、游戏时长查询 | `/steamhelp` `/steambind` `/steaminfo` `/steamplaytime` 等 |
|
||
| `nonebot_plugin_helldivers_tools` | 绝地潜兵 2 前线战况简报、星球详报、随机战备推荐 | `/简报` `/详报` `/随机战备` |
|
||
| `nonebot_plugin_mc_server_status` | Minecraft 服务器状态查询 | `/信息` `/信息数据` |
|
||
| `nonebot_plugin_ncm_saying` | 网易云音乐热评(网抑云) | `/网抑云` |
|
||
| `nonebot-bison` | Bilibili / 微博等订阅推送 | — |
|
||
|
||
### 聊天娱乐
|
||
|
||
| 插件 | 功能 | 主要命令 |
|
||
| --- | --- | --- |
|
||
| `nonebot_plugin_learning_chat` | 马尔可夫链群聊学习:被动学习群消息并模仿回复,定时主动发言;附 Vue 3 Web 管理后台 | — |
|
||
| `nonebot_plugin_galgame_card` | 群友"人设卡"生成与展示,带 Web 管理后台 | — |
|
||
| `nonebot_plugin_group_tools` | 群工具集(头像、表情、签到素材、游戏素材图等) | — |
|
||
| `nonebot_plugin_dailywife` | 每日随机抽取群友当"老婆" | `/今日老婆` |
|
||
| `nonebot_plugin_deer_pipe` | 每日打卡(鹿)与打卡记录,日历可视化 | `/打卡记鹿` `/查询记录` |
|
||
| `nonebot_plugin_makeaquote` | 生成"名言"引用图片 | — |
|
||
| `memes_ops` | 表情包运营/管理 | — |
|
||
| `nonebot_plugin_random_jm_code` | 随机 JM 本子代码 | `/jm` |
|
||
| `nonebot_plugin_dice` | 骰子掷点 | — |
|
||
|
||
### 实用工具
|
||
|
||
| 插件 | 功能 | 主要命令 |
|
||
| --- | --- | --- |
|
||
| `hexi/core`（核心模块） | 核心库:消息解析、权限分级、限流器 (token bucket)、命令冷却、热插件管理（**非插件**） | — |
|
||
| `nonebot_plugin_video_analysis` | 视频链接解析 | — |
|
||
| `nonebot_plugin_regif` | GIF 注册与处理 | — |
|
||
| `nonebot_plugin_picfinder_take` | 识图(Playwright 驱动) | — |
|
||
| `nonebot_plugin_picstatus` | 头像状态图生成 | — |
|
||
| `nonebot_plugin_group_daily_analysis` | 群聊行为分析报告 | `/群分析` |
|
||
| `hexi/web_hub`（核心模块） | 统一 Web 管理入口 `/hub`（**非插件**） | — |
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Python **3.10+**,使用 [Poetry](https://python-poetry.org/) 管理依赖
|
||
- 一个 OneBot V11 实现(如 [NapCat](https://github.com/NapNeko/NapCatQQ)、Lagrange)作为 QQ 接入端
|
||
|
||
### 安装与启动
|
||
|
||
```bash
|
||
# 安装依赖
|
||
poetry install
|
||
|
||
# 配置环境变量(见下节),然后启动
|
||
poetry run python bot.py
|
||
```
|
||
|
||
- **开发**:使用 `.env.dev`(监听 `127.0.0.1:11011`,昵称 Elika)
|
||
- **生产**:复制为根目录 `.env` 后启动(监听 `0.0.0.0:39697`,超级用户 `2931589710`,昵称 爱丽丝)
|
||
|
||
`.env` / `.env.dev` 均已被 `.gitignore` 排除,包含凭据的文件不会进入仓库。
|
||
|
||
## 配置
|
||
|
||
启动时 NoneBot 自动加载根目录 `.env` 文件,主要变量:
|
||
|
||
| 变量 | 说明 |
|
||
| --- | --- |
|
||
| `HOST` / `PORT` | 监听地址与端口 |
|
||
| `SUPERUSERS` | 超级用户 QQ 号 |
|
||
| `NICKNAME` | 机器人昵称 |
|
||
| `COMMAND_START` / `COMMAND_SEP` | 命令前缀与分隔符 |
|
||
| `DRIVER` | NoneBot 驱动器(httpx + fastapi + websockets) |
|
||
| `ONEBOT_ACCESS_TOKEN` | OneBot 接入鉴权 token |
|
||
| `DATASTORE_*` | 数据目录(localstore 统一指向 `hexi/data/` 等) |
|
||
| `SENTRY_DSN` / `SENTRY_ENVIRONMENT` | Sentry 错误上报(可选) |
|
||
| `BISON_*` | Bison 订阅推送配置 |
|
||
|
||
各插件专属配置(Steam API key、网易云 cookie、识图等)按需在 `.env` 中补充,详见各插件文档。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
HeXi/
|
||
├── bot.py pyproject.toml README.md
|
||
├── hexi/
|
||
│ ├── plugins/ # 全部插件(pyproject [tool.nonebot] plugin_dirs 加载)
|
||
│ ├── core/ # 机器人核心模块(非插件):工具库/插件控制面/热拔插管理
|
||
│ ├── web_hub/ # 机器人核心模块:统一 Web 管理台 + 鉴权/插件注册/配置标准
|
||
│ ├── data/ # 运行数据(不入库)
|
||
│ ├── config/ # 业务配置(不入库)
|
||
│ ├── resource/ # 全局静态资源(fonts/ 字体、menu_config 等)
|
||
│ ├── web/ # 统一 Web 前端(React + Vite,构建产物 dist/ 供 /hub 挂载)
|
||
│ ├── logs/ # 日志(不入库)
|
||
│ └── web_hub/ # 见上：统一 Web 管理台/鉴权/插件注册/配置标准
|
||
├── docs/ # 插件开发标准文档
|
||
├── tests/ # pytest 测试
|
||
└── plugin_template/ # 新插件脚手架模板
|
||
```
|
||
|
||
- **数据库**:`hexi/data/data.db`(datastore)、`hexi/data/nonebot_plugin_orm/db.sqlite3`(orm,各插件表)
|
||
- **群聊学习数据**:`hexi/data/record.json` + `inverted_index.json`(马尔可夫链)
|
||
- **本地插件数据**通过 localstore 统一收进 `hexi/data/`,避免散落根目录
|
||
|
||
## 测试与开发
|
||
|
||
```bash
|
||
poetry run pytest # 运行测试(tests/,asyncio auto 模式)
|
||
poetry run black . # 格式化
|
||
poetry run isort . # import 排序
|
||
poetry run ruff check . # lint
|
||
poetry run pyright # 类型检查
|
||
```
|
||
|
||
> 注意:测试文件必须放在 `tests/`,**不要**放进 `test/` —— `pyproject.toml` 中 `test` 是插件目录,NoneBot 启动时会把其中所有文件当插件加载。
|
||
|
||
新增插件请参考:
|
||
|
||
- [插件结构标准](dev/docs/plugin-structure-standard.md)
|
||
- [插件配置标准](dev/docs/plugin-config-standard.md)
|
||
- `dev/plugin_template/` 脚手架模板
|
||
|
||
## 许可
|
||
|
||
无
|