nonebot-plugin-hoyo-events 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. nonebot_plugin_hoyo_events-0.1.0/LICENSE +21 -0
  2. nonebot_plugin_hoyo_events-0.1.0/PKG-INFO +304 -0
  3. nonebot_plugin_hoyo_events-0.1.0/README.md +274 -0
  4. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events/__init__.py +72 -0
  5. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events/commands.py +428 -0
  6. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events/config.py +43 -0
  7. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events/datasource.py +452 -0
  8. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events/formatter.py +268 -0
  9. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events/games.py +100 -0
  10. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events/jobs.py +188 -0
  11. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events/messaging.py +49 -0
  12. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events/models.py +253 -0
  13. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events/runtime.py +103 -0
  14. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events/service.py +420 -0
  15. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events/store.py +288 -0
  16. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events.egg-info/PKG-INFO +304 -0
  17. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events.egg-info/SOURCES.txt +30 -0
  18. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events.egg-info/dependency_links.txt +1 -0
  19. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events.egg-info/entry_points.txt +2 -0
  20. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events.egg-info/requires.txt +6 -0
  21. nonebot_plugin_hoyo_events-0.1.0/nonebot_plugin_hoyo_events.egg-info/top_level.txt +1 -0
  22. nonebot_plugin_hoyo_events-0.1.0/pyproject.toml +71 -0
  23. nonebot_plugin_hoyo_events-0.1.0/setup.cfg +4 -0
  24. nonebot_plugin_hoyo_events-0.1.0/tests/test_commands.py +168 -0
  25. nonebot_plugin_hoyo_events-0.1.0/tests/test_datasource.py +202 -0
  26. nonebot_plugin_hoyo_events-0.1.0/tests/test_formatter.py +116 -0
  27. nonebot_plugin_hoyo_events-0.1.0/tests/test_identity.py +79 -0
  28. nonebot_plugin_hoyo_events-0.1.0/tests/test_jobs.py +156 -0
  29. nonebot_plugin_hoyo_events-0.1.0/tests/test_load.py +47 -0
  30. nonebot_plugin_hoyo_events-0.1.0/tests/test_models.py +86 -0
  31. nonebot_plugin_hoyo_events-0.1.0/tests/test_service.py +205 -0
  32. nonebot_plugin_hoyo_events-0.1.0/tests/test_store.py +110 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Tony
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,304 @@
1
+ Metadata-Version: 2.4
2
+ Name: nonebot-plugin-hoyo-events
3
+ Version: 0.1.0
4
+ Summary: 原神 / 崩坏:星穹铁道 / 绝区零 活动日历与未完成提醒 NoneBot2 插件
5
+ Author-email: Tony <plia0974@uni.sydney.edu.au>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/TonyLiangP2010405/nonebot-plugin-hoyo-events
8
+ Project-URL: Repository, https://github.com/TonyLiangP2010405/nonebot-plugin-hoyo-events
9
+ Project-URL: Issues, https://github.com/TonyLiangP2010405/nonebot-plugin-hoyo-events/issues
10
+ Keywords: nonebot,nonebot2,genshin,starrail,zenless,hoyoverse,mihoyo,event,calendar
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.9
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Communications :: Chat
20
+ Requires-Python: >=3.9
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: nonebot2>=2.2.0
24
+ Requires-Dist: nonebot-adapter-onebot>=2.4.0
25
+ Requires-Dist: nonebot-plugin-apscheduler>=0.5.0
26
+ Requires-Dist: nonebot-plugin-localstore>=0.7.0
27
+ Requires-Dist: httpx>=0.27.0
28
+ Requires-Dist: pydantic>=2.0.0
29
+ Dynamic: license-file
30
+
31
+ <div align="center">
32
+ <a href="https://v2.nonebot.dev/store"><img src="https://github.com/A-kirami/nonebot-plugin-template/blob/resources/nbp_logo.png" width="180" height="180" alt="NoneBotPluginLogo"></a>
33
+ <br>
34
+ <p><img src="https://github.com/A-kirami/nonebot-plugin-template/blob/resources/NoneBotPlugin.svg" width="240" alt="NoneBotPluginText"></p>
35
+ </div>
36
+
37
+ <div align="center">
38
+
39
+ # nonebot-plugin-hoyo-events
40
+
41
+ _✨ 原神 / 崩坏:星穹铁道 / 绝区零 活动日历与「未完成」@ 提醒 ✨_
42
+
43
+ <a href="./LICENSE">
44
+ <img src="https://img.shields.io/github/license/TonyLiangP2010405/nonebot-plugin-hoyo-events.svg" alt="license">
45
+ </a>
46
+ <a href="https://pypi.python.org/pypi/nonebot-plugin-hoyo-events">
47
+ <img src="https://img.shields.io/pypi/v/nonebot-plugin-hoyo-events.svg" alt="pypi">
48
+ </a>
49
+ <img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="python">
50
+ <img src="https://img.shields.io/badge/nonebot-2.2+-red.svg" alt="nonebot">
51
+
52
+ </div>
53
+
54
+ ## 📖 介绍
55
+
56
+ 群友天天问「现在有啥活动」「这个还剩几天」,问完还要挨个催?
57
+
58
+ 这个插件把**原神、崩坏:星穹铁道、绝区零**当前版本的活动抓下来,在群里展示活动名称和剩余天数,并且**按「群 + 人 + 活动」分别记录完成状态**:
59
+
60
+ - 群友发了「已完成 1」之后,**只有活动 1** 不再 @ 他,其他活动照常提醒;
61
+ - 不同群、不同人的完成进度互相独立,不会串;
62
+ - 活动数据定时自动更新,跟着游戏版本走,不用手动维护。
63
+
64
+ ## ✨ 功能
65
+
66
+ - 🗓 **活动总览**:三个游戏的活动一屏看完,带版本号、版本剩余天数和每个活动的剩余天数
67
+ - ⏰ **加急标记**:默认 3 天内结束的活动会带 ⏰,一眼看出先做哪个
68
+ - ✅ **分开记录完成**:`已完成 1 3`、`已完成 幽境危战`、`已完成 原神`、`已完成 全部` 都行,按人按活动单独存
69
+ - 📢 **每日推送**:每个群可以自己设时间(默认 21:00),到点播报活动并 @ 出「这个活动还没做」的人
70
+ - 🙅 **已完成的不会被 @**:推送时按活动分组列 @ 名单,全部做完的人一个都不 @;活动太多时自动合并成一行,不会刷屏
71
+ - 🔕 **个人免打扰**:群友自己可以关掉被 @
72
+ - 🔄 **自动更新**:后台定时拉取(默认 60 分钟),查询时也有缓存 TTL(默认 30 分钟),保证看到的是最新活动
73
+ - 🛠 **可手动修正**:数据源抽风或者少活动时,编辑 `override.json` 就能补/改/删,无需改代码
74
+
75
+ ## 📸 效果
76
+
77
+ 群友发 `/活动`:
78
+
79
+ ```
80
+ 🎮 米哈游活动 · 11-20
81
+ ━━━━━━━━━━
82
+ 🌏【原神】v7.2 坏灭肇始之时 · 版本剩 26 天
83
+ 1. 幽境危战 · 剩 25 天
84
+ 2. 魔神任务「坏灭肇始之时」限时奖励 · 剩 25 天
85
+ 3. 「相遇·悠久旅途之暇」千音雅集更新 · 剩 25 天
86
+ 4. 全域镇卫·逆捍谬罚 · 剩 26 天
87
+ 5. 砺行修远(第六期) · 剩 66 天
88
+ 6. 「晶石如林生长之地」区域探索限时奖励 · 剩 67 天
89
+
90
+ 🚄【星铁】v4.7 此刻,将群星付之一笑 · 版本剩 33 天
91
+ 7. 虚构叙事•取象为文 · 剩 10 天
92
+ 8. 混沌回忆•物竞天择 · 剩 24 天
93
+ 9. 剧场版绒绒号:欢闹厨房 · 剩 33 天
94
+ 10. 星际和平盛典:成名之路 · 剩 33 天
95
+ 11. 奇库寻遗 · 剩 33 天
96
+ 12. 开场好礼先抱走 · 剩 33 天
97
+ 13. 异相仲裁•隐藏关卡 · 剩 33 天
98
+ 14. 末日幻影•领航冥茫 · 剩 38 天
99
+
100
+ 📺【绝区零】v3.3 重返天空的旅程 · 版本剩 12 天
101
+ 15. 天使应援大作战 · 剩 10 天
102
+ 16. 怪奇诡屋惊魂记 · 剩 10 天
103
+ 17. 跛脚乌鸦奇踪记 · 剩 10 天
104
+ 18. 修复吧!漂流画集 · 剩 10 天
105
+ 19. 全新放送 · 剩 11 天
106
+ 20. 「嗯呢」从天降 · 剩 11 天
107
+ ━━━━━━━━━━
108
+ 共 20 个进行中的活动
109
+ 发送「已完成 编号」标记完成,如:已完成 1 3
110
+ ```
111
+
112
+ 小明发了 `/已完成 1 3`:
113
+
114
+ ```
115
+ ✅ 已记录完成 2 个活动
116
+ · 幽境危战(还剩 25 天)
117
+ · 「相遇·悠久旅途之暇」千音雅集更新(还剩 25 天)
118
+
119
+ 你的进度:2/20 已完成
120
+ 发送「未完成」查看还差哪些。
121
+ ```
122
+
123
+ 第二天 21:00 的自动推送(节选,@ 会自动变成真正的 at):
124
+
125
+ ```
126
+ 📢 今日活动提醒 · 11-20
127
+ ━━━━━━━━━━
128
+ 🌏【原神】v7.2 坏灭肇始之时 · 版本剩 26 天
129
+ 1. 幽境危战 · 剩 25 天
130
+ ...
131
+ ━━━━━━━━━━
132
+ 还没完成的群友:
133
+ · 幽境危战 · 剩 25 天: @小红 @阿伟
134
+ · 魔神任务「坏灭肇始之时」限时奖励 · 剩 25 天: @小明 @小红 @阿伟
135
+ · 「相遇·悠久旅途之暇」千音雅集更新 · 剩 25 天: @小红 @阿伟
136
+ 发送「已完成 编号」即可不再被 @,例如:已完成 1 3
137
+ ```
138
+
139
+ > 小明完成了活动 1 和 3,所以这两条里没有他,其余活动照常 @ 他 —— 这正是本插件和「一键全部免打扰」最大的区别。
140
+
141
+ ## 💿 安装
142
+
143
+ <details open>
144
+ <summary>使用 nb-cli 安装</summary>
145
+
146
+ 在 nonebot2 项目的根目录下打开命令行,输入:
147
+
148
+ ```bash
149
+ nb plugin install nonebot-plugin-hoyo-events
150
+ ```
151
+
152
+ </details>
153
+
154
+ <details>
155
+ <summary>使用包管理器安装</summary>
156
+
157
+ ```bash
158
+ pip install nonebot-plugin-hoyo-events
159
+ # 或者
160
+ poetry add nonebot-plugin-hoyo-events
161
+ # 或者
162
+ uv add nonebot-plugin-hoyo-events
163
+ ```
164
+
165
+ 然后在 `pyproject.toml` / `bot.py` 里加载:
166
+
167
+ ```python
168
+ nonebot.load_plugin("nonebot_plugin_hoyo_events")
169
+ ```
170
+
171
+ </details>
172
+
173
+ 需要 `nonebot-adapter-onebot`(OneBot V11)以及 `nonebot-plugin-apscheduler`、`nonebot-plugin-localstore`,它们会在安装本插件时一起装上。
174
+
175
+ ## ⚙️ 配置
176
+
177
+ 全部配置都有默认值,不写也能跑。在项目的 `.env` 里按需覆盖:
178
+
179
+ | 配置项 | 必填 | 默认值 | 说明 |
180
+ |:---:|:---:|:---:|:---|
181
+ | `HOYO_EVENTS_ENABLED` | 否 | `true` | 是否启用插件 |
182
+ | `HOYO_EVENTS_API_BASE` | 否 | `https://starrailassistant.top/api/v1/activity` | 活动数据源前缀 |
183
+ | `HOYO_EVENTS_CACHE_TTL` | 否 | `1800` | 查询时的缓存时长(秒),过期会先拉最新数据 |
184
+ | `HOYO_EVENTS_REFRESH_INTERVAL` | 否 | `60` | 后台刷新间隔(分钟),`0` 关闭后台刷新 |
185
+ | `HOYO_EVENTS_PUSH_TIME` | 否 | `21:00` | 群默认推送时间 |
186
+ | `HOYO_EVENTS_PUSH_DEFAULT_ENABLED` | 否 | `false` | 新群是否默认开启每日推送 |
187
+ | `HOYO_EVENTS_REMIND_DAYS` | 否 | `3` | 剩余天数 ≤ 该值时加 ⏰ |
188
+ | `HOYO_EVENTS_LIST_AT` | 否 | `false` | 查询时是否默认 @ 未完成的人 |
189
+ | `HOYO_EVENTS_MAX_EVENTS` | 否 | `20` | 每个游戏最多展示多少条活动 |
190
+ | `HOYO_EVENTS_MAX_AT_USERS` | 否 | `15` | 每条活动最多 @ 多少人 |
191
+ | `HOYO_EVENTS_MAX_AT_LINES` | 否 | `12` | 推送时最多为几个活动单独列 @ 名单,多余的合并成一行 |
192
+ | `HOYO_EVENTS_HTTP_TIMEOUT` | 否 | `15` | 请求数据源的超时(秒) |
193
+
194
+ ## 🎉 使用
195
+
196
+ ### 指令表
197
+
198
+ | 指令 | 权限 | 范围 | 说明 |
199
+ |:---|:---:|:---:|:---|
200
+ | `/活动` | 所有人 | 群聊/私聊 | 三个游戏的活动总览,带剩余天数 |
201
+ | `/活动 提醒` | 所有人 | 群聊 | 查看活动并顺手 @ 还没完成的群友 |
202
+ | `/活动 原神` | 所有人 | 群聊/私聊 | 只看某个游戏 |
203
+ | `/原神活动` `/星铁活动` `/绝区零活动` | 所有人 | 群聊/私聊 | 单游戏活动,同上 |
204
+ | `/已完成` | 所有人 | 群聊/私聊 | 列出自己还没完成的活动(带编号) |
205
+ | `/已完成 1 3` | 所有人 | 群聊/私聊 | 按编号标记完成 |
206
+ | `/已完成 幽境危战` | 所有人 | 群聊/私聊 | 按活动名标记,支持模糊匹配 |
207
+ | `/已完成 原神` | 所有人 | 群聊/私聊 | 标记某个游戏的全部活动 |
208
+ | `/已完成 全部` | 所有人 | 群聊/私聊 | 一键全部完成(之后不再被 @) |
209
+ | `/未完成` | 所有人 | 群聊/私聊 | 查看自己还差哪些活动 |
210
+ | `/取消完成 1` | 所有人 | 群聊/私聊 | 撤销完成标记 |
211
+ | `/活动免打扰` | 群员 | 群聊 | 自己不再被 @,再发一次恢复 |
212
+ | `/活动提醒 开` `/关` | 群管/超管 | 群聊 | 开关每日推送 |
213
+ | `/活动提醒 时间 22:30` | 群管/超管 | 群聊 | 设置推送时间(会自动开启推送) |
214
+ | `/活动提醒 状态` | 所有人 | 群聊 | 查看当前群设置 |
215
+ | `/活动提醒 立即` | 群管/超管 | 群聊 | 立刻推送一次,用来试效果 |
216
+ | `/活动刷新` | 超级用户 | 任意 | 手动拉取最新活动数据 |
217
+ | `/活动帮助` | 所有人 | 任意 | 查看帮助 |
218
+
219
+ ### 关于编号
220
+
221
+ 列表里的 **1、2、3** 是「这次渲染」的编号,会按当前活动列表自动生成,并缓存 6 小时:
222
+
223
+ - 群友刚发过 `/活动`,就按他这次看到的编号算;
224
+ - 如果刚收到过每日推送,也可以直接用推送里的编号;
225
+ - 实在记不清,直接发 `/已完成 活动名` 也行(支持模糊匹配)。
226
+
227
+ ### 关于「@ 谁」
228
+
229
+ 插件只 @ **在群里用过本插件命令的人**(发过一次 `/活动` 或 `/已完成` 就算登记),不会去 @ 完全不参与的群友。
230
+
231
+ 某人被 @ 的条件是:**当前这个活动他还没标记完成**。所以:
232
+
233
+ | 场景 | 结果 |
234
+ |:---|:---|
235
+ | 小红一个都没完成 | 每个活动都 @ 她 |
236
+ | 小明只完成了活动 1 | 活动 1 不 @ 他,其他活动继续 @ |
237
+ | 阿伟全部完成 | 一条都不 @ 他 |
238
+ | 阿伟下周开了新活动没做 | 新活动继续 @ 他(新活动是新的记录) |
239
+
240
+ ## 🧠 工作原理
241
+
242
+ 1. **数据来源**:默认使用 [SRA 公共 API](https://starrailassistant.top/reference/public-api/) 的 `ys` / `sr` / `zzz` 三个活动接口,免费、无需鉴权,返回当前版本号和每个活动的起止时间(UTC+8)。
243
+ 2. **定时刷新**:APScheduler 每 `HOYO_EVENTS_REFRESH_INTERVAL` 分钟拉一次;查询时如果缓存超过 `HOYO_EVENTS_CACHE_TTL` 也会先拉一次。拉取失败时沿用上一次的数据,不会把列表清空。
244
+ 3. **活动身份**:活动以「游戏 + 活动名」生成稳定 ID。
245
+ - 活动延期(只改结束时间)→ ID 不变,已完成的标记保留;
246
+ - 活动复刻(上一期结束后同名活动再来一次)→ 代次 +1,视为新活动,重新开始提醒。
247
+ 4. **完成状态**:存成 `群 → 人 → 活动` 三层映射,因此天然做到「不同活动分开记」「不同群互不影响」「不同人互不影响」。
248
+ 5. **推送**:每分钟检查一次各群的推送时间,到点且当天没推过就推;失败会重试,最多 5 次。
249
+
250
+ 数据文件在 NoneBot 的 localstore 目录下(一般是 `data/nonebot_plugin_hoyo_events/`):
251
+
252
+ | 文件 | 作用 |
253
+ |:---|:---|
254
+ | `store.json` | 活动缓存、完成记录、群设置(**含群号和 QQ 号,注意备份与隐私**) |
255
+ | `override.json` | 手动修正活动数据 |
256
+
257
+ ### 手动修正活动(可选)
258
+
259
+ 数据源偶尔会晚一步,或者你想加一个数据源里没有的活动,改 `override.json` 即可,下一条命令就生效,不用重启:
260
+
261
+ ```json
262
+ {
263
+ "ys": {
264
+ "remove": ["数据源里错的或不想显示的活动名"],
265
+ "patch": [
266
+ { "name": "某活动", "endTime": "2026-12-10T03:59:59" }
267
+ ],
268
+ "add": [
269
+ {
270
+ "name": "自己加的活动",
271
+ "startTime": "2026-11-20T10:00:00",
272
+ "endTime": "2026-12-01T03:59:59",
273
+ "description": "可选"
274
+ }
275
+ ]
276
+ },
277
+ "sr": { "add": [], "remove": [], "patch": [] },
278
+ "zzz": { "add": [], "remove": [], "patch": [] }
279
+ }
280
+ ```
281
+
282
+ ## ❓ 常见问题
283
+
284
+ **Q:为什么群友明明完成了,还在被 @?**
285
+ A:检查是不是在**另一个群**发的 `/已完成`(进度按群保存),或者用 `取消完成` 误撤销过。发 `/未完成` 可以看到当前群的实时状态。
286
+
287
+ **Q:为什么有人一次都没被 @?**
288
+ A:他从没在这个群用过插件的命令,插件不知道他玩不玩。让他发一次 `/活动` 就登记上了。
289
+
290
+ **Q:活动列表里少了某个活动?**
291
+ A:数据源以当前版本为主,可能抓取滞后。用 `override.json` 的 `add` 补一条,或者等下一次刷新。
292
+
293
+ **Q:能只看原神吗?**
294
+ A:`/原神活动`,或者 `/活动 原神`。
295
+
296
+ **Q:推送时间能每个群不一样吗?**
297
+ A:可以,`/活动提醒 时间 22:30` 是按群保存的。
298
+
299
+ **Q:支持多 bot / 一个 bot 在多群?**
300
+ A:推送会遍历当前连上的 OneBot bot,只要有一个在目标群就能发出去;群设置按群号保存,与 bot 无关。
301
+
302
+ ## 📄 许可证
303
+
304
+ [MIT](./LICENSE)
@@ -0,0 +1,274 @@
1
+ <div align="center">
2
+ <a href="https://v2.nonebot.dev/store"><img src="https://github.com/A-kirami/nonebot-plugin-template/blob/resources/nbp_logo.png" width="180" height="180" alt="NoneBotPluginLogo"></a>
3
+ <br>
4
+ <p><img src="https://github.com/A-kirami/nonebot-plugin-template/blob/resources/NoneBotPlugin.svg" width="240" alt="NoneBotPluginText"></p>
5
+ </div>
6
+
7
+ <div align="center">
8
+
9
+ # nonebot-plugin-hoyo-events
10
+
11
+ _✨ 原神 / 崩坏:星穹铁道 / 绝区零 活动日历与「未完成」@ 提醒 ✨_
12
+
13
+ <a href="./LICENSE">
14
+ <img src="https://img.shields.io/github/license/TonyLiangP2010405/nonebot-plugin-hoyo-events.svg" alt="license">
15
+ </a>
16
+ <a href="https://pypi.python.org/pypi/nonebot-plugin-hoyo-events">
17
+ <img src="https://img.shields.io/pypi/v/nonebot-plugin-hoyo-events.svg" alt="pypi">
18
+ </a>
19
+ <img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="python">
20
+ <img src="https://img.shields.io/badge/nonebot-2.2+-red.svg" alt="nonebot">
21
+
22
+ </div>
23
+
24
+ ## 📖 介绍
25
+
26
+ 群友天天问「现在有啥活动」「这个还剩几天」,问完还要挨个催?
27
+
28
+ 这个插件把**原神、崩坏:星穹铁道、绝区零**当前版本的活动抓下来,在群里展示活动名称和剩余天数,并且**按「群 + 人 + 活动」分别记录完成状态**:
29
+
30
+ - 群友发了「已完成 1」之后,**只有活动 1** 不再 @ 他,其他活动照常提醒;
31
+ - 不同群、不同人的完成进度互相独立,不会串;
32
+ - 活动数据定时自动更新,跟着游戏版本走,不用手动维护。
33
+
34
+ ## ✨ 功能
35
+
36
+ - 🗓 **活动总览**:三个游戏的活动一屏看完,带版本号、版本剩余天数和每个活动的剩余天数
37
+ - ⏰ **加急标记**:默认 3 天内结束的活动会带 ⏰,一眼看出先做哪个
38
+ - ✅ **分开记录完成**:`已完成 1 3`、`已完成 幽境危战`、`已完成 原神`、`已完成 全部` 都行,按人按活动单独存
39
+ - 📢 **每日推送**:每个群可以自己设时间(默认 21:00),到点播报活动并 @ 出「这个活动还没做」的人
40
+ - 🙅 **已完成的不会被 @**:推送时按活动分组列 @ 名单,全部做完的人一个都不 @;活动太多时自动合并成一行,不会刷屏
41
+ - 🔕 **个人免打扰**:群友自己可以关掉被 @
42
+ - 🔄 **自动更新**:后台定时拉取(默认 60 分钟),查询时也有缓存 TTL(默认 30 分钟),保证看到的是最新活动
43
+ - 🛠 **可手动修正**:数据源抽风或者少活动时,编辑 `override.json` 就能补/改/删,无需改代码
44
+
45
+ ## 📸 效果
46
+
47
+ 群友发 `/活动`:
48
+
49
+ ```
50
+ 🎮 米哈游活动 · 11-20
51
+ ━━━━━━━━━━
52
+ 🌏【原神】v7.2 坏灭肇始之时 · 版本剩 26 天
53
+ 1. 幽境危战 · 剩 25 天
54
+ 2. 魔神任务「坏灭肇始之时」限时奖励 · 剩 25 天
55
+ 3. 「相遇·悠久旅途之暇」千音雅集更新 · 剩 25 天
56
+ 4. 全域镇卫·逆捍谬罚 · 剩 26 天
57
+ 5. 砺行修远(第六期) · 剩 66 天
58
+ 6. 「晶石如林生长之地」区域探索限时奖励 · 剩 67 天
59
+
60
+ 🚄【星铁】v4.7 此刻,将群星付之一笑 · 版本剩 33 天
61
+ 7. 虚构叙事•取象为文 · 剩 10 天
62
+ 8. 混沌回忆•物竞天择 · 剩 24 天
63
+ 9. 剧场版绒绒号:欢闹厨房 · 剩 33 天
64
+ 10. 星际和平盛典:成名之路 · 剩 33 天
65
+ 11. 奇库寻遗 · 剩 33 天
66
+ 12. 开场好礼先抱走 · 剩 33 天
67
+ 13. 异相仲裁•隐藏关卡 · 剩 33 天
68
+ 14. 末日幻影•领航冥茫 · 剩 38 天
69
+
70
+ 📺【绝区零】v3.3 重返天空的旅程 · 版本剩 12 天
71
+ 15. 天使应援大作战 · 剩 10 天
72
+ 16. 怪奇诡屋惊魂记 · 剩 10 天
73
+ 17. 跛脚乌鸦奇踪记 · 剩 10 天
74
+ 18. 修复吧!漂流画集 · 剩 10 天
75
+ 19. 全新放送 · 剩 11 天
76
+ 20. 「嗯呢」从天降 · 剩 11 天
77
+ ━━━━━━━━━━
78
+ 共 20 个进行中的活动
79
+ 发送「已完成 编号」标记完成,如:已完成 1 3
80
+ ```
81
+
82
+ 小明发了 `/已完成 1 3`:
83
+
84
+ ```
85
+ ✅ 已记录完成 2 个活动
86
+ · 幽境危战(还剩 25 天)
87
+ · 「相遇·悠久旅途之暇」千音雅集更新(还剩 25 天)
88
+
89
+ 你的进度:2/20 已完成
90
+ 发送「未完成」查看还差哪些。
91
+ ```
92
+
93
+ 第二天 21:00 的自动推送(节选,@ 会自动变成真正的 at):
94
+
95
+ ```
96
+ 📢 今日活动提醒 · 11-20
97
+ ━━━━━━━━━━
98
+ 🌏【原神】v7.2 坏灭肇始之时 · 版本剩 26 天
99
+ 1. 幽境危战 · 剩 25 天
100
+ ...
101
+ ━━━━━━━━━━
102
+ 还没完成的群友:
103
+ · 幽境危战 · 剩 25 天: @小红 @阿伟
104
+ · 魔神任务「坏灭肇始之时」限时奖励 · 剩 25 天: @小明 @小红 @阿伟
105
+ · 「相遇·悠久旅途之暇」千音雅集更新 · 剩 25 天: @小红 @阿伟
106
+ 发送「已完成 编号」即可不再被 @,例如:已完成 1 3
107
+ ```
108
+
109
+ > 小明完成了活动 1 和 3,所以这两条里没有他,其余活动照常 @ 他 —— 这正是本插件和「一键全部免打扰」最大的区别。
110
+
111
+ ## 💿 安装
112
+
113
+ <details open>
114
+ <summary>使用 nb-cli 安装</summary>
115
+
116
+ 在 nonebot2 项目的根目录下打开命令行,输入:
117
+
118
+ ```bash
119
+ nb plugin install nonebot-plugin-hoyo-events
120
+ ```
121
+
122
+ </details>
123
+
124
+ <details>
125
+ <summary>使用包管理器安装</summary>
126
+
127
+ ```bash
128
+ pip install nonebot-plugin-hoyo-events
129
+ # 或者
130
+ poetry add nonebot-plugin-hoyo-events
131
+ # 或者
132
+ uv add nonebot-plugin-hoyo-events
133
+ ```
134
+
135
+ 然后在 `pyproject.toml` / `bot.py` 里加载:
136
+
137
+ ```python
138
+ nonebot.load_plugin("nonebot_plugin_hoyo_events")
139
+ ```
140
+
141
+ </details>
142
+
143
+ 需要 `nonebot-adapter-onebot`(OneBot V11)以及 `nonebot-plugin-apscheduler`、`nonebot-plugin-localstore`,它们会在安装本插件时一起装上。
144
+
145
+ ## ⚙️ 配置
146
+
147
+ 全部配置都有默认值,不写也能跑。在项目的 `.env` 里按需覆盖:
148
+
149
+ | 配置项 | 必填 | 默认值 | 说明 |
150
+ |:---:|:---:|:---:|:---|
151
+ | `HOYO_EVENTS_ENABLED` | 否 | `true` | 是否启用插件 |
152
+ | `HOYO_EVENTS_API_BASE` | 否 | `https://starrailassistant.top/api/v1/activity` | 活动数据源前缀 |
153
+ | `HOYO_EVENTS_CACHE_TTL` | 否 | `1800` | 查询时的缓存时长(秒),过期会先拉最新数据 |
154
+ | `HOYO_EVENTS_REFRESH_INTERVAL` | 否 | `60` | 后台刷新间隔(分钟),`0` 关闭后台刷新 |
155
+ | `HOYO_EVENTS_PUSH_TIME` | 否 | `21:00` | 群默认推送时间 |
156
+ | `HOYO_EVENTS_PUSH_DEFAULT_ENABLED` | 否 | `false` | 新群是否默认开启每日推送 |
157
+ | `HOYO_EVENTS_REMIND_DAYS` | 否 | `3` | 剩余天数 ≤ 该值时加 ⏰ |
158
+ | `HOYO_EVENTS_LIST_AT` | 否 | `false` | 查询时是否默认 @ 未完成的人 |
159
+ | `HOYO_EVENTS_MAX_EVENTS` | 否 | `20` | 每个游戏最多展示多少条活动 |
160
+ | `HOYO_EVENTS_MAX_AT_USERS` | 否 | `15` | 每条活动最多 @ 多少人 |
161
+ | `HOYO_EVENTS_MAX_AT_LINES` | 否 | `12` | 推送时最多为几个活动单独列 @ 名单,多余的合并成一行 |
162
+ | `HOYO_EVENTS_HTTP_TIMEOUT` | 否 | `15` | 请求数据源的超时(秒) |
163
+
164
+ ## 🎉 使用
165
+
166
+ ### 指令表
167
+
168
+ | 指令 | 权限 | 范围 | 说明 |
169
+ |:---|:---:|:---:|:---|
170
+ | `/活动` | 所有人 | 群聊/私聊 | 三个游戏的活动总览,带剩余天数 |
171
+ | `/活动 提醒` | 所有人 | 群聊 | 查看活动并顺手 @ 还没完成的群友 |
172
+ | `/活动 原神` | 所有人 | 群聊/私聊 | 只看某个游戏 |
173
+ | `/原神活动` `/星铁活动` `/绝区零活动` | 所有人 | 群聊/私聊 | 单游戏活动,同上 |
174
+ | `/已完成` | 所有人 | 群聊/私聊 | 列出自己还没完成的活动(带编号) |
175
+ | `/已完成 1 3` | 所有人 | 群聊/私聊 | 按编号标记完成 |
176
+ | `/已完成 幽境危战` | 所有人 | 群聊/私聊 | 按活动名标记,支持模糊匹配 |
177
+ | `/已完成 原神` | 所有人 | 群聊/私聊 | 标记某个游戏的全部活动 |
178
+ | `/已完成 全部` | 所有人 | 群聊/私聊 | 一键全部完成(之后不再被 @) |
179
+ | `/未完成` | 所有人 | 群聊/私聊 | 查看自己还差哪些活动 |
180
+ | `/取消完成 1` | 所有人 | 群聊/私聊 | 撤销完成标记 |
181
+ | `/活动免打扰` | 群员 | 群聊 | 自己不再被 @,再发一次恢复 |
182
+ | `/活动提醒 开` `/关` | 群管/超管 | 群聊 | 开关每日推送 |
183
+ | `/活动提醒 时间 22:30` | 群管/超管 | 群聊 | 设置推送时间(会自动开启推送) |
184
+ | `/活动提醒 状态` | 所有人 | 群聊 | 查看当前群设置 |
185
+ | `/活动提醒 立即` | 群管/超管 | 群聊 | 立刻推送一次,用来试效果 |
186
+ | `/活动刷新` | 超级用户 | 任意 | 手动拉取最新活动数据 |
187
+ | `/活动帮助` | 所有人 | 任意 | 查看帮助 |
188
+
189
+ ### 关于编号
190
+
191
+ 列表里的 **1、2、3** 是「这次渲染」的编号,会按当前活动列表自动生成,并缓存 6 小时:
192
+
193
+ - 群友刚发过 `/活动`,就按他这次看到的编号算;
194
+ - 如果刚收到过每日推送,也可以直接用推送里的编号;
195
+ - 实在记不清,直接发 `/已完成 活动名` 也行(支持模糊匹配)。
196
+
197
+ ### 关于「@ 谁」
198
+
199
+ 插件只 @ **在群里用过本插件命令的人**(发过一次 `/活动` 或 `/已完成` 就算登记),不会去 @ 完全不参与的群友。
200
+
201
+ 某人被 @ 的条件是:**当前这个活动他还没标记完成**。所以:
202
+
203
+ | 场景 | 结果 |
204
+ |:---|:---|
205
+ | 小红一个都没完成 | 每个活动都 @ 她 |
206
+ | 小明只完成了活动 1 | 活动 1 不 @ 他,其他活动继续 @ |
207
+ | 阿伟全部完成 | 一条都不 @ 他 |
208
+ | 阿伟下周开了新活动没做 | 新活动继续 @ 他(新活动是新的记录) |
209
+
210
+ ## 🧠 工作原理
211
+
212
+ 1. **数据来源**:默认使用 [SRA 公共 API](https://starrailassistant.top/reference/public-api/) 的 `ys` / `sr` / `zzz` 三个活动接口,免费、无需鉴权,返回当前版本号和每个活动的起止时间(UTC+8)。
213
+ 2. **定时刷新**:APScheduler 每 `HOYO_EVENTS_REFRESH_INTERVAL` 分钟拉一次;查询时如果缓存超过 `HOYO_EVENTS_CACHE_TTL` 也会先拉一次。拉取失败时沿用上一次的数据,不会把列表清空。
214
+ 3. **活动身份**:活动以「游戏 + 活动名」生成稳定 ID。
215
+ - 活动延期(只改结束时间)→ ID 不变,已完成的标记保留;
216
+ - 活动复刻(上一期结束后同名活动再来一次)→ 代次 +1,视为新活动,重新开始提醒。
217
+ 4. **完成状态**:存成 `群 → 人 → 活动` 三层映射,因此天然做到「不同活动分开记」「不同群互不影响」「不同人互不影响」。
218
+ 5. **推送**:每分钟检查一次各群的推送时间,到点且当天没推过就推;失败会重试,最多 5 次。
219
+
220
+ 数据文件在 NoneBot 的 localstore 目录下(一般是 `data/nonebot_plugin_hoyo_events/`):
221
+
222
+ | 文件 | 作用 |
223
+ |:---|:---|
224
+ | `store.json` | 活动缓存、完成记录、群设置(**含群号和 QQ 号,注意备份与隐私**) |
225
+ | `override.json` | 手动修正活动数据 |
226
+
227
+ ### 手动修正活动(可选)
228
+
229
+ 数据源偶尔会晚一步,或者你想加一个数据源里没有的活动,改 `override.json` 即可,下一条命令就生效,不用重启:
230
+
231
+ ```json
232
+ {
233
+ "ys": {
234
+ "remove": ["数据源里错的或不想显示的活动名"],
235
+ "patch": [
236
+ { "name": "某活动", "endTime": "2026-12-10T03:59:59" }
237
+ ],
238
+ "add": [
239
+ {
240
+ "name": "自己加的活动",
241
+ "startTime": "2026-11-20T10:00:00",
242
+ "endTime": "2026-12-01T03:59:59",
243
+ "description": "可选"
244
+ }
245
+ ]
246
+ },
247
+ "sr": { "add": [], "remove": [], "patch": [] },
248
+ "zzz": { "add": [], "remove": [], "patch": [] }
249
+ }
250
+ ```
251
+
252
+ ## ❓ 常见问题
253
+
254
+ **Q:为什么群友明明完成了,还在被 @?**
255
+ A:检查是不是在**另一个群**发的 `/已完成`(进度按群保存),或者用 `取消完成` 误撤销过。发 `/未完成` 可以看到当前群的实时状态。
256
+
257
+ **Q:为什么有人一次都没被 @?**
258
+ A:他从没在这个群用过插件的命令,插件不知道他玩不玩。让他发一次 `/活动` 就登记上了。
259
+
260
+ **Q:活动列表里少了某个活动?**
261
+ A:数据源以当前版本为主,可能抓取滞后。用 `override.json` 的 `add` 补一条,或者等下一次刷新。
262
+
263
+ **Q:能只看原神吗?**
264
+ A:`/原神活动`,或者 `/活动 原神`。
265
+
266
+ **Q:推送时间能每个群不一样吗?**
267
+ A:可以,`/活动提醒 时间 22:30` 是按群保存的。
268
+
269
+ **Q:支持多 bot / 一个 bot 在多群?**
270
+ A:推送会遍历当前连上的 OneBot bot,只要有一个在目标群就能发出去;群设置按群号保存,与 bot 无关。
271
+
272
+ ## 📄 许可证
273
+
274
+ [MIT](./LICENSE)
@@ -0,0 +1,72 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import logging
5
+
6
+ from nonebot import get_driver, require
7
+ from nonebot.plugin import PluginMetadata
8
+
9
+ from .config import Config
10
+
11
+ __plugin_meta__ = PluginMetadata(
12
+ name="米哈游活动助手",
13
+ description="原神 / 崩坏:星穹铁道 / 绝区零 活动日历、剩余天数与未完成成员 @ 提醒",
14
+ usage=(
15
+ "/活动 —— 三个游戏的活动总览(含剩余天数)\n"
16
+ "/原神活动 /星铁活动 /绝区零活动 —— 单游戏活动\n"
17
+ "/已完成 1 3 —— 标记列表里的第 1、3 项(按人、按群、按活动分别记录)\n"
18
+ "/已完成 活动名 —— 按名称标记,支持模糊匹配\n"
19
+ "/未完成 —— 查看自己还差哪些活动\n"
20
+ "/取消完成 1 —— 撤销标记\n"
21
+ "/活动提醒 开|关|时间 21:30|状态|立即 —— 群管设置每日推送\n"
22
+ "/活动免打扰 —— 不再被 @\n"
23
+ "/活动刷新 —— 管理员手动拉取最新活动\n"
24
+ "/活动帮助 —— 查看完整说明"
25
+ ),
26
+ type="application",
27
+ homepage="https://github.com/TonyLiangP2010405/nonebot-plugin-hoyo-events",
28
+ config=Config,
29
+ supported_adapters={"~onebot.v11"},
30
+ )
31
+
32
+ require("nonebot_plugin_apscheduler")
33
+ require("nonebot_plugin_localstore")
34
+
35
+ from nonebot_plugin_apscheduler import scheduler # noqa: E402
36
+
37
+ from . import jobs # noqa: E402
38
+ from .commands import ( # noqa: E402,F401
39
+ done_matcher,
40
+ game_matcher,
41
+ help_matcher,
42
+ list_matcher,
43
+ mute_matcher,
44
+ push_matcher,
45
+ refresh_matcher,
46
+ todo_matcher,
47
+ undo_matcher,
48
+ )
49
+ from .runtime import DATA_DIR, config, service # noqa: E402
50
+
51
+ logger = logging.getLogger("nonebot_plugin_hoyo_events")
52
+
53
+ if config.hoyo_events_enabled:
54
+ jobs.register_jobs(scheduler)
55
+
56
+ driver = get_driver()
57
+
58
+ @driver.on_startup
59
+ async def _startup() -> None:
60
+ """启动时加载数据并异步拉一次活动,不阻塞 NoneBot 启动。"""
61
+
62
+ await service.startup()
63
+
64
+ async def _warm_up() -> None:
65
+ try:
66
+ await service.ensure_data()
67
+ except Exception as exc: # noqa: BLE001
68
+ logger.warning("启动时拉取活动数据失败:%s", exc)
69
+
70
+ asyncio.create_task(_warm_up())
71
+
72
+ logger.info("米哈游活动助手已加载,数据目录:%s", DATA_DIR)