bettergi-scripts-list/repo/js/ActivitySwitchNotice/README.md

# 活动期限/周本通知器

## 项目概述

这是一个用于《原神》游戏的自动化脚本工具，主要功能是自动检测游戏内活动的剩余时间，并在活动即将结束时/每周指定日期自动提醒征讨领域减半剩余次数发送通知提醒玩家。

## 功能特性

- ✅ 自动返回游戏主界面并打开活动页面
- ✅ OCR识别活动列表和剩余时间
- ✅ 自动滚动浏览所有活动页面
- ✅ 智能解析剩余时间（支持"22天14小时"等格式）
- ✅ 可配置的通知阈值（默认8760小时内结束的活动）
- ✅ 支持指定特定活动进行监控
- ✅ 支持活动黑名单过滤功能
- ✅ 防重复检测机制
- ✅ 异常处理和错误恢复
- ✅ 自动提醒征讨领域减半剩余次数（默认`周日`提醒可配置）

---

## 用户使用指南

### 快速开始

#### 1. 安装与配置

- 确保游戏分辨率为 **1920×1080**（推荐分辨率）
- 将脚本导入到 BetterGI 脚本管理器中
- 在脚本设置界面进行个性化配置

#### 2. 基础设置

在 `settings.json` 中可以配置以下参数：

| 设置项                        | 说明                                             | 默认值         | 开放 |
|:---------------------------|:-----------------------------------------------|:------------|:--:|
| `toMainUi`                 | 执行前是否自动返回游戏主界面                                 | true        | v  |
| `activityNameList`         | 监控的特定活动名称（用\|分隔）                               | 空（监控所有活动）   | v  |
| `blackActivityNameList`    | 黑名单活动名称（用\|分隔）                                 | 空（无黑名单活动）   | v  |
| `notifyHoursThreshold`     | 通知时间阈值（小时）                                     | 8760（365天）  | v  |
| `activityKey`              | 打开活动页面的快捷键                                     | F5          | v  |
| `toTopCount`               | 滑动到顶最大尝试次数                                     | 10          | x  |
| `scrollPageCount`          | 滑动次数/页                                         | 4           | x  |
| `campaignAreaKey`          | 打开征讨领域页面的快捷键                                   | F1          | v  |
| `campaignAreaReminderDay`  | 周本提醒日(0-6,0=周日,1=周一,2=周二,3=周三,4=周四,5=周五,6=周六)  | 0           | v  |

### 使用流程

#### 自动模式（推荐）

1. 启动脚本后，程序会自动：
   - 检测当前是否在游戏主界面
   - 如未在主界面，自动返回主界面
   - 按设定的快捷键打开活动页面
   - 开始扫描所有活动

#### 手动模式

1. 关闭 `toMainUi` 选项
2. 确保游戏处于主界面状态
3. 启动脚本开始扫描

### 功能详解

#### 活动筛选

- **全部活动监控**：`activityNameList` 保持空值，监控所有有剩余时间的活动
- **指定活动监控**：填写活动关键词，如 `海灯节\|盛典`，只监控包含这些关键词的活动
- **黑名单过滤**：`blackActivityNameList` 可以设置不想接收提醒的活动名称，多个活动用`|`分隔

#### 时间通知机制

- 默认监控所有活动（`notifyHoursThreshold`=8760小时）
- 可设置阈值，如设置为24，则只通知剩余时间≤24小时的活动
- 即将结束(24小时内)的活动会在通知中标记 `<即将结束>`

#### 智能防重复

- 自动识别已扫描过的活动页面
- 防止因页面滚动不准确造成的重复识别
- 自动判断是否已滚动到页面底部

### 注意事项

#### 使用环境要求

- ✅ 游戏分辨率为 1920×1080（最佳兼容性）
- ✅ 游戏处于前台运行状态
- ✅ 活动页面可通过设置的快捷键正常打开

#### 运行期间注意事项

- 🚫 运行期间请勿手动操作鼠标
- 🚫 避免切换窗口或最小化游戏
- ⚠️ 如遇异常可重新启动脚本

### 高级配置

#### 自定义快捷键

如活动页面不是F5打开，可在 `activityKey` 中修改为对应按键。
如冒险之书页面不是F1打开，可在 `campaignAreaKey` 中修改为对应按键。

#### 时间阈值设置

根据个人需求设置 `notifyHoursThreshold`：

- 24：只关注24小时内结束的活动
- 168：关注一周内结束的活动
- 720：关注一个月内结束的活动

### 输出示例

通知消息格式如下：

```
原神活动剩余时间提醒:
> 海灯节庆典 剩余时间：3天14小时<还剩 86 小时>
> 风花节活动 剩余时间：1天5小时<还剩 29 小时><即将结束>
```



**`以上为用户使用指南全部内容`**
---

## 文件结构

```
ActivitySwitchNotice/
├── utils/
│   ├── activity.js     # 核心活动处理逻辑
│   ├── campaignArea.js # 征讨领域提醒功能
│   └── notice.js       # 通知发送功能
├── main.js             # 主入口文件
├── manifest.json       # 插件配置文件
├── settings.json       # 用户设置界面定义
└── README.md           # 说明文档
```



## 核心模块

### `activity.js` - 活动处理核心

主要包含以下功能函数：

- `scrollPage()` - 页面滚动基础函数
- `scrollPagesByActivity()` - 按页滚动活动列表
- `scrollPagesByActivityToTop()` - 滚动到活动列表顶部
- `parseRemainingTimeToHours()` - 解析剩余时间文本为小时数
- `OcrRemainingTime()` - OCR识别剩余时间
- `activityMain()` - 主流程控制函数

### `notice.js` - 通知模块

- `sendNotice()` - 发送活动提醒通知，按剩余时间排序
- `send()` - 发送普通通知

### `campaignArea.js` - 征讨领域模块

- `ocrWeeklyCount()` - OCR识别征讨领域周次数
- `getDayOfWeek()` - 获取当前星期信息
- `campaignAreaMain()` - 征讨领域提醒主函数

## 配置选项

在 `settings.json` 中可配置以下参数：

| 配置项                        |   类型    | 说明                                             |
|:---------------------------|:-------:|:--|
| `toMainUi`                 | Boolean | 是否先返回主界面再执行                                    |
| `activityNameList`         | String  | 指定活动名称（用\|分隔）                                  |
| `blackActivityNameList`    | String  | 黑名单活动名称（用\|分隔）                                 |
| `notifyHoursThreshold`     | Number  | 通知阈值（小时）                                       |
| `activityKey`              | String  | 打开活动页面的快捷键                                     |
| `toTopCount`               | Number  | 滑动到顶最大尝试次数                                     | 
| `scrollPageCount`          | Number  | 滑动次数/页                                         | 
| `campaignAreaKey`          | String  | 打开冒险之书页面的快捷键                                   |
| `campaignAreaReminderDay`  | Number  | 周本提醒日(0-6,0=周日,1=周一,2=周二,3=周三,4=周四,5=周五,6=周六)  | 

## 工作原理

1. 自动返回游戏主界面
2. 检查是否为设置的提醒日(默认周日)，如果是则执行征讨领域提醒功能
3. 按配置快捷键打开活动页面
4. 滚动到活动列表顶部
5. 逐页扫描所有活动
6. OCR识别每个活动的剩余时间
7. 解析时间为小时数并过滤（包括黑名单过滤）
8. 发送符合条件的活动提醒

## 注意事项

- 请确保游戏分辨率为1920×1080以获得最佳效果
- 脚本运行期间请勿操作鼠标
- 某些特殊活动可能无法正确识别剩余时间
- 建议在游戏空闲时运行此脚本

---

## 版本历史

### 0.0.2 (2025-12-22)

- 新增 征讨领域周次数提醒功能
- 新增 `campaignArea.js` 模块，包含征讨领域相关功能
- 新增 `campaignAreaKey` 配置选项，用于自定义冒险之书页面快捷键
- 新增 `campaignAreaReminderDay` 配置选项，用于配置提醒日
- 改进 增强滚动到顶部功能的稳定性
- 新增 活动黑名单过滤功能，支持通过 `blackActivityNameList` 配置项排除不关心的活动
- 新增 特殊活动时间格式支持，针对"砺行修远"等活动提供周数显示
- 新增 额外OCR识别支持，可识别特定活动的附加信息（如"本周进度"）
- 改进 活动过滤逻辑，增强黑名单匹配准确性
- 改进 通知显示格式，增加活动描述信息展示
- 修复 若干已知问题，提升脚本稳定性

### 0.0.1 (2025-12-21)

- 新增 活动期限检测与通知功能
- 新增 OCR识别活动列表和剩余时间
- 新增 自动滚动浏览所有活动页面
- 新增 智能解析剩余时间（支持"22天14小时"等格式）
- 新增 可配置的通知阈值功能
- 新增 指定特定活动监控功能
- 新增 防重复检测机制
- 新增 异常处理和错误恢复机制

---

## 其它

作者：云端客
脚本反馈邮箱：doutianmianxia@qq.com