Metadata-Version: 2.5
Name: nonebot-plugin-xbox-status
Version: 0.1.0
Summary: 播报群友的 Xbox 游戏状态，玩法参考 nonebot-plugin-steam-info
Project-URL: Homepage, https://github.com/MadXX517/nonebot-plugin-xbox-status
Project-URL: Issues, https://github.com/MadXX517/nonebot-plugin-xbox-status/issues
Author-email: MadXX517 <141333482+MadXX517@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: nonebot,nonebot2,plugin,xbox,xbox-live
Classifier: Framework :: AsyncIO
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: <4.0,>=3.9
Requires-Dist: httpx>=0.26.0
Requires-Dist: nonebot-adapter-onebot>=2.4.0
Requires-Dist: nonebot-plugin-apscheduler>=0.5.0
Requires-Dist: nonebot-plugin-localstore>=0.7.0
Requires-Dist: nonebot2>=2.3.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pydantic>=1.10.0
Description-Content-Type: text/markdown

<div align="center">

# nonebot-plugin-xbox-status

_✨ 播报群友的 Xbox 游戏状态 ✨_

<a href="./LICENSE"><img src="https://img.shields.io/github/license/MadXX517/nonebot-plugin-xbox-status.svg" alt="license"></a>
<a href="https://pypi.python.org/pypi/nonebot-plugin-xbox-status"><img src="https://img.shields.io/pypi/v/nonebot-plugin-xbox-status.svg" alt="pypi"></a>
<img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="python">

</div>

玩法参考 [nonebot-plugin-steam-info](https://github.com/zhaomaoniu/nonebot-plugin-steam-info)：群友绑定 Xbox 账号后，有人开始、停止或切换游戏时自动在群里播报；也可以随时查看全群的在线状态。

数据来自官方 Xbox Live 接口，不经过第三方服务。

## 效果

| 开始游戏播报 | `xboxcheck` 状态总览 |
| :---: | :---: |
| ![broadcast](docs/broadcast.png) | ![check](docs/check.png) |

播报文字示例：

```
MajorNelson (老王) 开始玩 Forza Horizon 5 了
SpartanJoe 玩了 1 小时 5 分钟 Halo Infinite 后不玩了
```

## 安装

使用 nb-cli 安装：

```bash
nb plugin install nonebot-plugin-xbox-status
```

<details>
<summary>使用包管理器安装</summary>

在 nonebot2 项目的根目录下执行：

```bash
pip install nonebot-plugin-xbox-status
# 或 pdm add / poetry add / uv add nonebot-plugin-xbox-status
```

然后在 `pyproject.toml` 的 `[tool.nonebot]` 中的 `plugins` 里追加 `"nonebot_plugin_xbox_status"`。

</details>

## 准备工作

Xbox 没有 Steam 那样的开发者 API Key，插件需要以一个微软账号（下称「查询账号」）的身份调用接口。一次性配置如下：

### 1. 注册 Azure 应用（免费）

1. 打开 [Azure 门户 - 应用注册](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)，点击「新注册」
2. 名称随意；**受支持的帐户类型选「仅限个人 Microsoft 帐户」**；重定向 URI 留空
3. 注册后在「概述」页复制「应用程序(客户端) ID」
4. 进入「身份验证」，将「允许公共客户端流」设为「是」并保存

### 2. 配置并登录

1. 在 `.env` 中填写 `XBOX_CLIENT_ID=<客户端 ID>`，重启机器人
2. 超级用户**私聊**机器人发送 `xboxlogin`，按提示打开链接、输入代码，用查询账号登录授权
3. 机器人回复「Xbox 登录成功」即完成。令牌会自动续期，之后无需再登录

> 建议使用单独的小号作为查询账号。该账号需要已创建 Xbox 档案（登录一次 xbox.com 即可）。

### 3. 让查询账号看得到你

Xbox 隐私设置默认只对好友公开在线状态，**每位被绑定的玩家都需要与查询账号互加好友**，否则会一直显示为离线。

若已是好友仍显示离线，请检查：设置 → 帐户 → 隐私和联机安全 → Xbox 隐私 → 查看详细信息并自定义 → 联机状态和历史记录。

## 配置

在 nonebot2 项目的 `.env` 文件中添加：

| 配置项 | 必填 | 默认值 | 说明 |
| :--- | :---: | :---: | :--- |
| `XBOX_CLIENT_ID` | 是 | 无 | Azure 应用的客户端 ID。未填写时插件仍可加载，但无法登录 |
| `XBOX_REQUEST_INTERVAL` | 否 | `300` | 轮询间隔（秒） |
| `XBOX_PROXY` | 否 | 无 | HTTP 代理，如 `http://127.0.0.1:7890` |
| `XBOX_LANGUAGE` | 否 | `zh-CN` | 游戏名等文本的语言 |
| `XBOX_FONT_REGULAR_PATH` | 否 | 自动查找 | 常规字体路径（需支持中文） |
| `XBOX_FONT_BOLD_PATH` | 否 | 自动查找 | 粗体字体路径，缺失时使用常规字体 |

未配置字体时，依次尝试 `fonts/MiSans-*.ttf`（与 steam-info 插件共用）、Noto Sans CJK、文泉驿微米黑、微软雅黑、苹方。都找不到时启动日志会给出警告。

## 使用

| 指令 | 别名 | 权限 | 范围 | 说明 |
| :--- | :--- | :---: | :---: | :--- |
| `xboxbind <玩家代号或 XUID>` | `绑定xbox` | 所有人 | 群聊 | 绑定 Xbox 账号 |
| `xboxunbind` | `解绑xbox` | 所有人 | 群聊 | 解绑 |
| `xboxcheck` | `查看xbox` `查xbox` | 所有人 | 群聊 | 查看本群已绑定玩家的状态 |
| `xboxnickname <昵称>` | `xbox昵称` | 所有人 | 群聊 | 设置播报中显示的昵称 |
| `xboxenable` | `启用xbox` | 群管理 | 群聊 | 开启本群播报（默认开启） |
| `xboxdisable` | `禁用xbox` | 群管理 | 群聊 | 关闭本群播报 |
| `xboxlogin` | `登录xbox` | 超级用户 | 私聊 | 登录查询账号 |
| `xboxhelp` | `xbox帮助` | 所有人 | 全部 | 查看帮助 |

指令前缀取决于你的 `COMMAND_START` 配置。

## 说明

- 仅支持 OneBot V11 适配器
- 绑定按群隔离：同一 QQ 在不同群可绑定不同账号，播报只发到绑定所在的群
- 在主机主页、Xbox App 中挂机不算玩游戏，不会触发播报
- 机器人启动和新绑定时只记录当前状态、不播报，避免重启后误报和时长错误
- 查询账号的令牌保存在 localstore 数据目录的 `token.json` 中，**请勿泄露**。长时间停机（约 90 天未刷新）或修改密码后需重新 `xboxlogin`

## 开发

```bash
pip install -e . "nonebot2[fastapi]"
python tests/test_plugin.py   # 零配置加载、状态判定、绘图自检，不访问网络
```

发布：更新 `pyproject.toml` 中的版本号，推送 `v<版本号>` 标签，GitHub Actions 会通过 [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) 自动发布。

## 致谢

- [nonebot-plugin-steam-info](https://github.com/zhaomaoniu/nonebot-plugin-steam-info)：玩法与交互参考
- [xbox-webapi-python](https://github.com/OpenXbox/xbox-webapi-python)：Xbox Live 接口资料

## 许可

[MIT](./LICENSE)
