# 禾汐 (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/` 脚手架模板

## 许可

无