bettergi-scripts-list/repo/js/SwitchParty/README.md
云端客 f5a7331ddd
切换队伍(BgiTools版) (#3629)
* feat(SwitchParty): 添加BgiTools版切换队伍功能

- 新增BgiTools工具类,支持通过API获取团队信息
- 实现OCR识别长期训练点数功能
- 添加队伍切换主逻辑,支持输入加载和BgiTools加载两种模式
- 集成HTTP请求工具,支持GET/POST/PUT/DELETE方法
- 实现UI操作工具类,包含返回主界面等功能
- 添加红框绘制工具用于调试显示
- 集成日志、格式化、找图找文本等通用工具
- 配置项目清单文件和设置界面选项

docs(SwitchParty): 添加切换队伍脚本的详细文档

- 新增 README.md 文件,包含脚本简介和功能特点说明
- 详细描述输入加载和 bgi_tools 加载两种模式的使用方法
- 提供完整的目录结构和配置说明表格
- 添加使用示例和 API 请求格式说明
- 包含切换队伍逻辑流程和常见问题解答
- 记录版本历史和注意事项

docs(switchparty): 更新 README 添加演示图片

- 在文档中添加了 bgi_tools_init.jpg 演示图片
- 在文档中添加了 bgi_tools_js.jpg 演示图片
- 丰富了脚本初始化和 JS 配置的视觉说明

* refactor(bgi_tools): 重构接口响应处理逻辑

- 新增 Result 类用于统一接口响应结构封装
- 添加状态码、消息、时间戳和数据字段的标准响应格式
- 实现 isSuccess 方法用于判断响应成功状态
- 添加 fromJson 静态方法支持 JSON 字符串或对象解析
- 修改 getTeamInfo 方法使用 Result 统一处理响应数据
- 移除原有的手动 JSON 解析和格式验证逻辑
- 优化错误处理和日志记录机制

fix(bgi_tools): 统一处理响应数据格式解析

- 移除原有的 isJson 函数判断逻辑
- 添加字符串类型的 JSON 解析处理
- 增加对象类型的直接使用逻辑
- 添加错误处理以应对无效 JSON 响应
- 统一响应数据的解析方式确保格式一致性

fix(bgi_tools): 修复JSON解析错误处理

- 添加isJson函数验证响应体是否为有效JSON字符串
- 防止非JSON格式响应导致的解析异常
- 确保只有有效的JSON字符串才进行解析操作
- 提高请求响应处理的健壮性

fix(utils): 解决响应体解析错误问题

- 添加了安全的JSON解析函数safeParse
- 当JSON解析失败时返回原始字符串
- 避免因响应体格式异常导致的程序崩溃
- 提高了代码的容错性和稳定性

refactor(SwitchParty): 优化团队信息获取逻辑

- 移除未使用的代码注释和变量声明
- 直接解析HTTP响应体为JSON格式
- 重命名变量以提高代码可读性
- 统一错误处理机制

fix(utils): 修复URL参数拼接逻辑

- 在get方法中避免空查询字符串时添加多余的问号
- 在delete方法中避免空查询字符串时添加多余的问号
- 确保只有在查询字符串非空时才添加问号分隔符

fix(utils): 修复查询字符串处理逻辑

- 添加了对空字符串的检查,避免无效的切片操作
- 当查询字符串为空时返回空字符串而不是执行切片
- 防止了潜在的字符串索引越界问题

fix(bgi_tools): 修复团队信息获取功能

- 移除未使用的查询字符串构造逻辑
- 更新Http.get调用方式以支持参数传递
- 添加请求成功日志记录
- 统一错误处理机制为抛出异常
- 在main.js中添加团队信息获取日志
- 完善HTTP工具类的异步处理和日志记录

refactor(SwitchParty): 优化队伍切换逻辑并改进变量命名

- 将 team 变量重命名为 team_name 以提高可读性
- 统一代码风格,移除不必要的分号和空行
- 优化 BgiTools 集成中的团队数据提取逻辑
- 改进错误处理和日志记录的一致性
- 简化条件判断和团队切换流程

feat(SwitchParty): 添加BGI版本信息到清单文件

- 在manifest.json中添加bgi_version字段
- 设置BGI版本为0.64.0以匹配当前依赖版本
2026-09-10 23:23:46 +08:00

135 lines
4.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 切换队伍(BgiTools版)
## 简介
该脚本用于 BetterGI 中自动切换原神队伍。支持两种加载模式:
- **输入加载**:手动在设置中填写队伍名称,脚本直接切换。
- **bgi_tools加载**:通过 BgiTools HTTP 接口查询当前 UID 对应的队伍信息,再自动完成切换。(需要JS HTTP权限支持)
## 功能特点
- 支持输入加载和 bgi_tools 加载两种模式
- 自动获取当前游戏 UID,并通过 HTTP 接口查询目标队伍
- 切换队伍失败时自动传送至七天神像并重试
- 支持自定义 Token 名称和值
- 完善的日志记录和错误通知
## 目录结构
```text
SwitchParty/
├── main.js # 脚本入口
├── manifest.json # BetterGI 插件清单
├── settings.json # 设置界面定义
├── assets/
│ └── ui/main_ui.png # 主界面识别模板图
└── utils/
├── tools.js # 通用工具类
└── bgi_tools.js # BgiTools API 请求封装
```
## 配置说明
| 设置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `auto_load` | 下拉选择 | `输入加载` | 加载模式,可选“输入加载”或“bgi_tools加载” |
| `team` | 文本框 | 空 | 队伍名称,适用于“输入加载”模式;留空表示不切换队伍 |
| `type` | 文本框 | 空 | 分组类型,适用于“bgi_tools加载”模式,会作为请求参数传给接口 |
| `bgi_tools_uid_team_api` | 文本框 | `http://127.0.0.1:8081/bgi/uid/team` | BgiTools HTTP API 地址 |
| `bgi_tools_token` | 文本框 | `Authorization= ` | BgiTools 鉴权 Token,格式为 `Token名=Token值` |
### 输入加载使用示例
- 加载模式:`输入加载`
- 队伍名称:`1`(请填写游戏内实际的队伍名称)
- 其他字段可留空
脚本会直接使用 `team` 作为目标队伍名称,调用 `genshin.switchParty(team)` 切换。
### bgi_tools 加载使用示例
- 加载模式:`bgi_tools加载`
- 分组类型:`独立`(可按需填写,用于在 BgiTools 侧分组)
- BgiTools HTTP API:`http://127.0.0.1:8081/bgi/uid/team` 请部署[bettergi-scripts-tools](https://github.com/Kirito520Asuna/bettergi-scripts-tools)(点击前往部署) v0.1.9以上版本
- Token 示例:`Authorization=你的Token值`
### bettergi-scripts-tools 使用演示
![demo](./assets/md/bgi_tools_init.jpg)
![js](./assets/md/bgi_tools_js.jpg)
脚本运行逻辑如下:
1. 通过 `genshin.uid()` 获取当前游戏 UID。
2. 将 `uid` 和 `type` 作为查询参数请求配置的 API。
3. 从返回结果中取出 `team` 字段作为目标队伍名称。
4. 执行队伍切换。
请求格式:
```text
GET {bgi_tools_uid_team_api}?uid={uid}&type={type}
Headers:
{Token名}: {Token值}
```
期望接口返回格式示例:
```json
{
"code": 200,
"message": "success",
"data": {
"id": "记录ID",
"uid": "玩家UID",
"team": "目标队伍名称",
"type": "分组类型"
}
}
```
> 注意:如果接口返回的 `code` 不是 `200`,脚本会记录错误日志并放弃切换。如果请求本身失败(网络异常、非 200 状态码等),同样会记录错误信息。
## 切换队伍逻辑
1. 根据配置的加载模式确定“目标队伍名称”。
2. 如果队伍名称非空,尝试调用 `genshin.switchParty(team)` 切换队伍。
3. 若切换失败,自动传送至七天神像,再次尝试切换。
4. 若依然失败或发生异常,会弹出错误通知,并返回游戏主界面,避免影响后续操作。
## 常见问题
### 1. 为什么提示“切换队伍失败”?
可能原因包括:
- 当前处于联机模式。
- 当前游戏场景不允许切换队伍,例如战斗状态或禁用区域。
- 队伍名称与游戏内实际配置不一致。
- 切换冷却时间未结束。
### 2. Token 应该怎么填?
如果 BgiTools 接口要求的鉴权头是:
```text
Authorization: xxxxx
```
则在设置中填写:
```text
Authorization=xxxxx
```
脚本会以等号分隔,将前半部分作为 Header 名称,后半部分作为 Header 值。
### 3. 接口返回正常但切换成功后又失败了?
请检查返回 JSON 中 `team` 字段是否与游戏内队伍名称完全一致,包括空格、大小写和特殊字符。
## 版本历史
- **v1.0.0**
- 首个版本
- 支持“输入加载”和“bgi_tools加载”两种队伍获取方式
- 支持队伍切换失败后传送七天神像重试