From 6eca7c1b59afea1854f9ad03eb73ad421c7017bf Mon Sep 17 00:00:00 2001 From: ClovertaTheTrilobita Date: Thu, 27 Nov 2025 19:13:27 +0000 Subject: [PATCH] =?UTF-8?q?doc:=20=E4=BF=AE=E6=94=B9=E9=85=8D=E7=BD=AE?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=8C=E5=9C=A8=E9=85=8D=E7=BD=AE=E6=96=87?= =?UTF-8?q?=E4=BB=B6=E4=B8=AD=E5=8A=A0=E5=85=A5=E8=AF=A6=E7=BB=86=E6=B3=A8?= =?UTF-8?q?=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 146 +++++++++++++----- bot.py | 17 ++- docs/configuration.md | 313 ++++++++++++++++++++++++++++++++++++++ docs/features.md | 103 +++++++++++++ example.config.yaml | 23 ++- src/configs/api_config.py | 14 +- 6 files changed, 570 insertions(+), 46 deletions(-) create mode 100644 docs/configuration.md create mode 100644 docs/features.md diff --git a/README.md b/README.md index 7a1eadf..e25803b 100644 --- a/README.md +++ b/README.md @@ -213,6 +213,8 @@ npm install crypto-js 在一切开始前，你需要将项目根目录下的[example.env.prod](example.env.prod)文件更名为.env.prod，这是机器人的账号配置文件。 +我加了神必小代码，如果你没配置这两个配置文件是启动不起来的，因为有~~海量~~个例显示，很多人不看README就想当然地启动bot，并在群里问为什么会有报错（ + ``` DRIVER=~fastapi+~httpx+~websockets @@ -236,50 +238,116 @@ QQ_BOTS="
-#### 📄 需要替换的文件 +#### 📄 需要修改的配置文件 -首先找到 [**src/configs/api_config_example.py**](src/configs/api_config_example.py) 文件，并根据需要替换以下配置项： +首先找到 [**example.config.yaml**](example.config.yaml) ，将其重命名为config.yaml -```python -app_id = "" -bot_account = "" +并根据需要替换以下配置项： -""" -图床配置 -""" -# SMMS图床相关配置 -smms_token = "" # sm.ms图床的token -smms_image_upload_history = "https://sm.ms/api/v2/upload_history" # sm.ms图床获取上传图片历史API地址 +```yaml +####################################### +# 如果您已经配置好了，请将此字段改为 ‘False’# +####################################### +default: "True" # 配置完成后，请将这个字段改为 False -# 聚合图床相关配置 -ju_he_token = "" # 聚合图床的token -ju_he_image_list = "https://api.superbed.cn/timeline" # 聚合图床获取上传图片历史API地址 +bot: + app_id: "" + bot_account: "" -""" -AI -""" -admin_password = "123456" # 默认注册管理员密码 -# 图灵机器人相关配置 -v3url = "https://api.vveai.com/v1/chat/completions" -v3key = "" -# DeepSeek相关配置 -deepseek_url = "https://api.deepseek.com" -deepseek_key = "" +############################ +# 三叶草邮箱发信设置 # +############################ +mail: + google: + enabled: 'False' + smtp_server: 'smtp.gmail.com' + email: 'xxxxxx@gmail.com' + password: '1234567891234567' # 16 位应用码 -""" -Wenku8账号 -""" -wenku8_username = "" -wenku8_password = "" + qq: + enabled: 'True' + smtp_server: 'smtp.qq.com' + email: 'xxxxxxxx@qq.com' + password: '1234567891234567' # qq邮箱应用码 -""" -多米HTTP代理api -""" -proxy_api = "" + server: # 自建服务器 + enabled: 'False' + smtp_server: 'mail.example.com' # 自建邮局域名 + email: 'user_name@example.com' + password: '123456' + port: '587' + +############################ +# 三叶草图床设置 # +############################ +image_hosting: + smms: # sm.ms图床 + enabled: 'False' + token: '' + smms_image_upload_history: "https://sm.ms/api/v2/upload_history" + + superbed: # 聚合图床 + enabled: 'False' + token: '' + superbed_image_list: "https://api.superbed.cn/timeline" + + random_pic: "https://image.anosu.top/pixiv/json" + + animetrace: + url: "https://api.animetrace.com/v1/search" + +############################ +# 三叶草AI设置 # +############################ +ai: + admin: + password: '123456' + + api: + v3: + enabled: "False" + url: "https://api.vveai.com/v1/chat/completions" + key: '' + + deepseek: + enabled: "False" + url: "https://api.deepseek.com" + key: '' + + silicon_flow: + enabled: "True" + url: "https://api.siliconflow.cn/v1/chat/completions" + model: "Pro/deepseek-ai/DeepSeek-V3" + key: '' + +############################ +# 其他时尚小功能 # +############################ + +wenku8: + # 通过wenku8.com获取最新轻小说咨询 + # 此功能需要启用代理 + enabled: 'False' + user_name: '' + password: '' + +proxy: + # 目前代码中仅支持多米HTTP代理 + enabled: 'False' + key: '' + +qr: + # 二维码生成api + url: "https://api.qrserver.com/v1/create-qr-code/" + size: "200x200" + +codeforces: + # 查询codeforces比赛列表 + key: "" + secret: "" ``` -🚫注意： -将你的 `app_id` 和 `smms_token` 替换为实际值（可以根据自身需求选填），然后将文件重命名为 **api_config.py**。 +🚫注意： 将你的 `app_id` 和 `smms_token` 替换为实际值（可以根据自身需求选填）
@@ -297,8 +365,6 @@ python bot.py
-当然可以！以下是根据您提供的文件内容整理后的项目结构： - ### 🗒️ 四、项目结构 ``` @@ -580,10 +646,12 @@ menu = ["/重启","/今日运势","/今日塔罗","/图","/日报","/点歌","/ ###### 1. 注册为管理员 -在 [**src/configs/api_config_example.py**](src/configs/api_config_example.py) 内，找到： +在 [**config.yaml**](config.yaml) 内，找到： ```python -admin_password = "123456" # 默认注册管理员密码 +ai: + admin: + password: '123456' ``` diff --git a/bot.py b/bot.py index e65f201..0eefcae 100644 --- a/bot.py +++ b/bot.py @@ -11,11 +11,25 @@ from nonebot.adapters.qq import Adapter as QQAdapter from apscheduler.schedulers.background import BackgroundScheduler from src.configs.path_config import log_path,temp_path,video_path,yuc_wiki_path +# 检查配置文件是否都存在，若不存在则直接退出 +CURRENT_FILE = Path(__file__).resolve() +ROOT_DIR = CURRENT_FILE.parent +ENV_PROD = ROOT_DIR / ".env.prod" +CONFIG_PATH = ROOT_DIR / "config.yaml" + +if not ENV_PROD.is_file(): + raise FileNotFoundError( + f"未找到配置文件: {ENV_PROD}，请根据README.md，将example.env.prod重命名为.env.prod，并进行正确配置") + +if not CONFIG_PATH.is_file(): + raise FileNotFoundError( + f"未找到配置文件: {CONFIG_PATH}，请根据README.md，将example.config.yaml重命名为config.yaml，并配置机器人设置") + + nonebot.init() from backend import start_flask - driver = nonebot.get_driver() driver.register_adapter(QQAdapter) # 注册QQ适配器 nonebot.load_from_toml("pyproject.toml") @@ -41,6 +55,7 @@ scheduler = BackgroundScheduler() scheduler.add_job(clean_temp_cache, 'cron', hour=0, minute=0) if __name__ == "__main__": + flask_thread = threading.Thread(target=start_flask, daemon=True) flask_thread.start() scheduler.start() diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..60bddaf --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,313 @@ +### 🗒️ 四、项目结构 + +``` +SanYeCao-Nonebot:. +│ .gitignore +│ bot.py +│ chat_bot.db +│ example.env.prod +│ package-lock.json +│ package.json +│ pyproject.toml +│ README.md +│ requirements.txt +│ +├─node_modules +│ └─crypto-js +│ +└─src + ├─clover_image + │ └─get_image.py + │ + ├─clover_music + │ ├─cloud_music + │ │ ├─cloud_music_cookies.cookie + │ │ └─qrcode.png + │ └─netease_music + │ + ├─clover_openai + │ ├─api_config_example.py + │ └─api_config.py + │ + ├─clover_sqlite + │ ├─data_init + │ │ ├─init_tables.py + │ │ └─... + │ └─models + │ ├─models.py + │ └─... + │ + ├─clover_videos + │ └─billibili + │ ├─bilibili_search.py + │ └─... + │ + ├─configs + │ ├─path_config.py + │ ├─api_config_example.py + │ └─utils + │ ├─utils.py + │ └─... + │ + ├─plugins + │ ├─check.py + │ ├─todo.py + │ ├─weather.py + │ ├─fortune.py + │ ├─tarot.py + │ ├─music.py + │ ├─image.py + │ ├─petpet.py + │ ├─openai.py + │ ├─bilibili.py + │ ├─news.py + │ ├─light_novel.py + │ ├─anime.py + │ └─... + │ + └─resources + ├─font + │ ├─font.ttf + │ └─... + ├─image + │ ├─codeforces + │ │ ├─image1.png + │ │ └─... + │ ├─github_repo + │ │ ├─image2.png + │ │ └─... + │ ├─good_bad_news + │ │ ├─image3.png + │ │ └─... + │ ├─MaoYuNa + │ │ ├─image4.png + │ │ └─... + │ ├─rua + │ │ ├─image5.png + │ │ └─... + │ ├─tarot + │ │ ├─sideTarotImages + │ │ │ ├─image6.png + │ │ │ └─... + │ │ └─TarotImages + │ │ ├─image7.png + │ │ └─... + │ └─who_say + │ ├─image8.png + │ └─... + ├─log + │ ├─bot.log + │ └─... + ├─temp + │ ├─temp_file1.tmp + │ └─... + └─videos + ├─video1.mp4 + └─... +``` + + +### 详细说明 + +- **根目录文件** + - `.gitignore`: 忽略文件配置。 + - `bot.py`: 机器人启动文件。 + - `chat_bot.db`: SQLite 数据库文件。 + - `example.env.prod`: 示例环境配置文件。 + - `package-lock.json`: npm 依赖锁定文件。 + - `package.json`: npm 依赖配置文件。 + - `pyproject.toml`: Python 项目配置文件。 + - `README.md`: 项目说明文档。 + - `requirements.txt`: Python 依赖配置文件。 + +- **node_modules** + - `crypto-js`: 加密库。 + +- **src 目录** + - **clover_image** + - `get_image.py`: 图片获取模块。 + + - **clover_music** + - **cloud_music** + - `cloud_music_cookies.cookie`: 网易云音乐 cookie 文件。 + - `qrcode.png`: 网易云音乐扫码登录二维码。 + - **netease_music** + - 网易云音乐相关模块。 + + - **clover_openai** + - `api_config_example.py`: 示例 API 配置文件。 + - `api_config.py`: 实际 API 配置文件。 + + - **clover_sqlite** + - **data_init** + - `init_tables.py`: 数据库初始化脚本。 + - 其他初始化脚本。 + - **models** + - `models.py`: 数据库模型定义。 + - 其他模型定义文件。 + + - **clover_videos** + - **bilibili** + - `bilibili_search.py`: B站视频搜索模块。 + - 其他 B站相关模块。 + + - **configs** + - `path_config.py`: 路径配置文件。 + - `api_config_example.py`: 示例 API 配置文件。 + - **utils** + - `utils.py`: 工具函数。 + - 其他工具函数文件。 + + - **plugins** + - `check.py`: 指令检查模块。 + - `todo.py`: 待办事项模块。 + - `weather.py`: 天气模块。 + - `fortune.py`: 运势模块。 + - `tarot.py`: 塔罗牌模块。 + - `music.py`: 点歌模块。 + - `image.py`: 图片模块。 + - `petpet.py`: 摸摸头模块。 + - `openai.py`: AI 模块。 + - `bilibili.py`: B站视频模块。 + - `news.py`: 日报模块。 + - `light_novel.py`: 轻小说模块。 + - `anime.py`: 新番信息模块。 + - 其他插件模块。 + + - **resources** + - **font** + - `font.ttf`: 字体文件。 + - 其他字体文件。 + - **image** + - **codeforces** + - `image1.png`: 图片文件。 + - 其他图片文件。 + - **github_repo** + - `image2.png`: 图片文件。 + - 其他图片文件。 + - **good_bad_news** + - `image3.png`: 图片文件。 + - 其他图片文件。 + - **MaoYuNa** + - `image4.png`: 图片文件。 + - 其他图片文件。 + - **rua** + - `image5.png`: 图片文件。 + - 其他图片文件。 + - **tarot** + - **sideTarotImages** + - `image6.png`: 图片文件。 + - 其他图片文件。 + - **TarotImages** + - `image7.png`: 图片文件。 + - 其他图片文件。 + - **who_say** + - `image8.png`: 图片文件。 + - 其他图片文件。 + - **log** + - `bot.log`: 日志文件。 + - 其他日志文件。 + - **temp** + - `temp_file1.tmp`: 临时文件。 + - 其他临时文件。 + - **videos** + - `video1.mp4`: 视频文件。 + - 其他视频文件。 + +
+ +### 📦三、插件 + + - 插件的目录位于src/plugins中
+ - 插件的配置文件位于src/configs中
+ - 基本插件存储在plugins目录中，启动即可使用
+ - 部分插件通过调用其它目录中的方法完成其功能
+ - 部分插件需要调用第三方API，需要在配置文件中填写相关配置
+ +
+ +### 🎈五、更多功能 + +#### 📲所有指令 + +机器人的指令列表在[src/plugins/check.py](src/plugins/check.py)中，有如下指令： + +```python +menu = ["/重启","/今日运势","/今日塔罗","/图","/日报","/点歌","/摸摸头","/群老婆","/今日老婆", "/开启ai","/关闭ai", + "/角色列表","/添加人设", "/更新人设", "/删除人设", "/切换人设", "/管理员注册","/待办", "/test","/天气", + "我喜欢你", "❤", "/待办查询", "/新建待办", "/删除待办" ,"/cf","/B站搜索", "/BV搜索", "/喜报", "/悲报", + "/luxun","/鲁迅说", "/奶龙", "/repo", "/info", "/menu", "/轻小说","/本季新番","/新番观察"] +``` + +输入其它指令机器人会回复听不懂哦。 + +
+ + + +### 🎨 功能补充说明 + + +#### 🎵 使用网易云API实现点歌 + +若您是初次使用点歌功能，在群聊中 @ 机器人后，机器人会提示： + +``` +登录失效，请联系管理员进行登录 +``` + + +此时会在 [**src/music**](src/clover_music) 目录下生成一张 **qrcode.png**，您需要使用手机端网易云音乐扫码该二维码，登录您的网易云账号。 + +注意： 我们使用 cookie 存储用户登录信息，所以会存在登录过期的情况。若 cookie 过期，机器人会提示： + +``` +歌曲音频获取失败：登录信息失效。 +``` + + +此时需要并重新扫码登录。 [cloud_music.py](src/plugins/cloud_music.py) 内有控制是否发送到qq,详情请看 Line:33 + +
+ +#### ✋ 管理员身份认证 + +##### 介绍 + +机器人现已更新管理员机制，机器人管理员可以控制是否使用第三方大语言模型进行交互。后续其它功能更新中。 + +##### 使用 + +###### 1. 注册为管理员 + +在 [**config.yaml**](config.yaml) 内，找到： + +```python +ai: + admin: + password: '123456' +``` + + +可以更改为自己的密码。 + +设置好密码后，在 QQ 中 at 你的机器人，格式为： + +``` +@<机器人名称> /管理员注册 <密码> +``` + + +例如，对三叶草进行管理员注册时，假如密码是 123456，需要： + +``` +@三叶草 /管理员注册 123456 +``` + + +注意： 管理员密码请不要泄露给其他人，建议定期更换密码。 + +注册成为管理员之后，你的 `member_openid` 将会被保存至 `chatbot.db` 下的 `admin_list` 表中。 + + + diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 0000000..2d8c742 --- /dev/null +++ b/docs/features.md @@ -0,0 +1,103 @@ +# 三叶草详细功能 + +#### 待办 + +- **功能描述**: 用户可以添加、查询和删除个人待办事项。 +- **指令**: `/待办`, `/待办查询`, `/新建待办`, `/删除待办` + +#### 天气 + +- **功能描述**: 提供当前天气信息。 +- **指令**: `/天气` + +#### 今日运势 + +- **功能描述**: 提供用户的今日运势。 +- **指令**: `/今日运势` + +#### 今日塔罗 + +- **功能描述**: 提供一张随机的塔罗牌及其解读。 +- **指令**: `/今日塔罗` + +#### 点歌 + +- **功能描述**: 通过网易云音乐API点歌，并将音乐文件以QQ语音的形式发送至群聊。 快点一首你喜欢的歌给群友听吧！ +- **指令**: `/点歌` +- **注意事项**: + - 使用网易云点歌需要另外安装依赖：Node.js 和在目录下输入 npm install crypto-js + - 初次使用或者提示登录失效需要需扫码登录 （在 src\music 目录下）。 + +#### 图 + +- **功能描述**: 返回图库中的图片。 +- **指令**: `/图` + +#### 摸摸头 + +- **功能描述**: 与机器人进行互动，发送“摸摸头”的回复。 +- **指令**: `/摸摸头` + +#### 接入语言模型 + +- **功能描述**: 使用第三方大语言模型进行交互。 +- **指令**: `/开启ai`, `/关闭ai` `/角色列表`,`/添加人设`, `/更新人设`, `/删除人设`, `/切换人设`, `/管理员注册` +- **注意事项**: + - 需要管理员身份认证。 + - AI功能为每个群单独启动，默认关闭。 + +#### 搜索B站视频 + +- **功能描述**: 通过BV号搜索B站视频，并将视频文件发送至群聊。 +- **指令**: `/BV搜索 ` +- **注意事项**: + - 🚨注意： 由于QQ的限制，官方bot无法发送文件大于10M。 + - 需要安装 Chrome Driver。您需要首先确保自己的电脑安装了[Chrome Driver](https://developer.chrome.google.cn/docs/chromedriver?hl=zh-cn)。 + - 若没安装过，请参考教程：[chromedriver下载与安装方法，亲测可用-CSDN博客](https://blog.csdn.net/zhoukeguai/article/details/113247342) + - 程序第一次启动时，会获取B站的cookie保存至本地，使用selenium库完成，下载可能较慢，需要稍等一会儿。 + +#### 今日老婆 + +- **功能描述**: 提供今日老婆的信息。 +- **指令**: `/今日老婆` +- **状态**: 待开发 + +#### 群老婆 + +- **功能描述**: 提供群内成员的老婆信息。 +- **指令**: `/群老婆` + +#### 鲁迅说 + +- **功能描述**: 提供鲁迅的经典语录。 +- **指令**: `/鲁迅说`,`/luxun` + +#### 喜报、悲报 + +- **功能描述**: 提供喜报和悲报的信息。 +- **指令**: `/喜报`, `/悲报` + +#### 查询cf比赛 + +- **功能描述**: 通过CodeForces官方API查询近期比赛。 +- **指令**: `/cf` + +#### 日报 + +- **功能描述**: 提供每日的新闻或信息。 +- **指令**: `/日报` + +#### 查询热门轻小说 + +- **功能描述**: 查询当前热门的轻小说。 +- **指令**: `/轻小说` + +#### 获取新番信息 + +- **功能描述**: 获取当季动漫的新番信息和预期新番上线信息。 +- **指令**: `/本季新番`, `/新番观察` + +#### 绝对色感小游戏 + +- **功能描述**: 返回一个绝对色感小游戏，玩家需要猜测一个颜色，并输入颜色代码。 +- **指令**: `/绝对色感 初级、中级、高级、超神` \ No newline at end of file diff --git a/example.config.yaml b/example.config.yaml index 8242a8a..b47af56 100644 --- a/example.config.yaml +++ b/example.config.yaml @@ -1,3 +1,8 @@ +####################################### +# 如果您已经配置好了，请将此字段改为 ‘False’# +####################################### +default: "True" # 配置完成后，请将这个字段改为 False + bot: app_id: "" bot_account: "" @@ -5,6 +10,10 @@ bot: ############################ # 三叶草邮箱发信设置 # ############################ +# 此内容用于配置三叶草发送邮件的邮箱及账号密码 +# 目前支持三种邮箱，分别为gmail、qq邮箱、自建服务器邮局 +# 如果你需要启用此邮箱，请将该邮箱下的 ‘enabled’ 字段修改为 'True' +# 请至少启用一个邮箱，若三个邮箱均启用，则优先级为gmail > qq邮箱 > 自建邮箱 （按照此配置文件中的顺序） mail: google: enabled: 'False' @@ -47,9 +56,16 @@ image_hosting: ############################ # 三叶草AI设置 # ############################ +# 此内容用于配置ai聊天 +# 目前支持三种api,分别为vveai、deepseek api、硅基流动 +# 但是理论上只要你的api支持openai格式的接口，你可以把硅基流动那一栏换成任意api +# 如果你想使用ai聊天功能，请至少启用其中一个api +# 如果启用多个，则优先级为 v3 > deepseek > silicon flow （按照顺序进行优先级排序） +# +# ai聊天功能分群聊开启，若你想在某个群聊中启用三叶草的ai功能，请在该群聊中 @机器人 并发送 “/管理员注册 <密码>” ai: admin: - password: '123456' + password: '123456' # 默认管理员密码 api: v3: @@ -73,8 +89,8 @@ ai: ############################ wenku8: - # 通过wenku8.com获取最新轻小说咨询 - # 此功能需要启用代理 + # 通过wenku8.net获取最新轻小说咨询 + # 此功能可能需要启用代理 enabled: 'False' user_name: '' password: '' @@ -91,5 +107,6 @@ qr: codeforces: # 查询codeforces比赛列表 + # 但如果仅查询比赛列表或个人rating，本内容可以不用配置 key: "" secret: "" \ No newline at end of file diff --git a/src/configs/api_config.py b/src/configs/api_config.py index 1455267..10460b3 100644 --- a/src/configs/api_config.py +++ b/src/configs/api_config.py @@ -1,14 +1,22 @@ import yaml from pathlib import Path +from nonebot import logger CURRENT_FILE = Path(__file__).resolve() ROOT_DIR = CURRENT_FILE.parent.parent.parent # config -> src -> project root CONFIG_PATH = ROOT_DIR / "config.yaml" -with open(CONFIG_PATH, "r", encoding="utf-8") as f: - config = yaml.safe_load(f) +try: + with open(CONFIG_PATH, "r", encoding="utf-8") as f: + config = yaml.safe_load(f) +except FileNotFoundError: + raise FileNotFoundError(f"未找到配置文件: {CONFIG_PATH}，请根据README.md，将example.config.yaml重命名为config.yaml，并正确配置机器人设置") + +default_config = config['default'] + +if default_config == "True": + logger.warning(f"正在使用未经配置的配置文件，若你不想看到此警告，请将 {CONFIG_PATH} 第一行的default字段改为：False") -#print(data) app_id = config['bot']['app_id'] bot_account = config['bot']['bot_account'] """