AstrBot 的 PlayStation Network (PSN) 玩家数据可视化插件。 支持按群启用、绑定 PSN 账号、查询游戏库 / 游戏时间 / 奖杯、群内排行与对比，所有结果均以图片形式返回。
简体中文 · English README
灵感参考：astrbot_plugin_steam_status_monitor、astrbot_plugin_steamgame。
- 白名单群聊：可自定义启用插件的群聊名单（配置文件 + 管理员指令动态增删）。
- 账号绑定：群友通过
/绑定psn <PSN在线ID>绑定自己的 PlayStation 账号。 - 个人数据查询：
/psn：个人资料、在线状态、正在游玩、奖杯等级与各稀有度数量；/psn游戏库：游戏库列表、总游戏时长、各平台游戏数量、游戏封面墙；/psn奖杯：每个游戏的奖杯完成度、各稀有度进度条；/psn游戏 <游戏名关键词>：指定某一款游戏的详情——总游玩时长/小时、启动次数、首次与最近游玩日期，以及该游戏的奖杯完成度与白金/金/银/铜进度。游戏名支持强模糊匹配：俗称/简称/英文名/中文正式名互通（如「老头环」「法环」「黑悟空」「战神5」「美末2」「大镖客2」），自动忽略大小写、全半角、音标、版本后缀（Remake/Remaster/PS5 等），并带版本号校验（查「2」不会误中前作）；找不到时会提示最接近的游戏名。
- 群内排行榜：
/psn排行支持按- 游戏时长（肝度）
- 游戏数量
- 奖杯总分（白金/金/银/铜加权）
- 白金杯数 多维度排行。
- 群友对比：
/psn对比 @某人对比游戏数、总时长、奖杯、白金数，以及共同拥有的游戏。 - 群内联动：
/psn联动：分析群友之间的 PSN 好友关系，以及「大家都在玩」的共同游戏；/psn在线：群内谁在线、正在玩什么游戏。
- 可视化图片输出：所有数据均使用 AstrBot 的 HTML 渲染能力生成精美深色风格图片。
- 缓存与日志：内置内存缓存减少 PSN 请求；使用情况写入数据目录下的
usage.log。 - 💬 自然语言支持（确定性为主、可选 LLM 辅助）：直接 @机器人 说「查下我的奖杯」「群里谁最肝」「看看 @某人 的 PSN 在线状态」「我大镖客2玩了多久」「和 @某人 对比 PSN 奖杯」即可触发。自然语言意图先在插件层确定性识别（
@filter.regex），运行在 Agent/LLM 阶段之前，因此不强制依赖 LLM 就能用，且不受memory_companion、private_companion等接管 Agent 的插件干扰；单款游戏名称匹配失败时，可选开关nl_llm_assist（默认开启）会调用一次已配置的 LLM 从游戏库中挑选候选，同时保留 LLM 函数调用（@filter.llm_tool）作为兜底。
插件仅使用 AstrBot 的平台无关通用接口（指令 / 文字 / 图片 / 群号 / @ 消息段），因此理论上兼容所有支持群聊、图片与 @ 功能的消息平台。
- 已实测：
aiocqhttp（NapCat / Lagrange / go-cqhttp 等 OneBot 实现，即 QQ）。 - 通用接口推断兼容（未逐一实测）：QQ 官方（
qq_official/qq_official_webhook）、Telegram、Discord、Satori、飞书、企业微信、钉钉、KOOK、Slack、Misskey、Mattermost。 - 不适用：微信公众号（无群聊、被动回复受限）、企业微信智能机器人等无群成员/排行模型的渠道，故未声明支持。
在未实测平台如遇到图片或 @ 解析差异，欢迎提 issue 反馈。
在 AstrBot 面板的「插件市场」中搜索 astrbot_plugin_PlayStationGames 安装即可。
可从 Releases 下载 astrbot_plugin_PlayStationGames-1.4.2.zip，解压后将其中的 astrbot_plugin_PlayStationGames 文件夹放入 AstrBot 的 data/plugins/ 目录；也可使用 Git：
# 在 AstrBot 的 data/plugins 目录下
cd data/plugins
git clone https://github.com/Eason4869/astrbot_plugin_PlayStationGames.git升级时在插件市场点击更新，或在 Git 安装目录执行 git pull，然后在 AstrBot 面板重载插件。升级不会清除 data/plugin_data/astrbot_plugin_PlayStationGames/ 中的绑定和群开关数据。插件会自动安装依赖：
PSNAWP—— PSN 的非官方 Python API 封装；aiohttp—— 异步下载封面/头像；requests—— PSN 网络错误识别与重试。
如果自动安装失败，请在插件目录手动执行：
pip install -r requirements.txt
本插件通过 PSNAWP 访问 PlayStation Network，必须配置一个有效的 NPSSO 令牌（64 位字符）：
- 用浏览器打开并登录 PlayStation 中国官网（点击右上角「登录」，登录你的 PSN 账号）；
- 保持登录状态，在同一浏览器访问
https://ca.account.sony.com/api/v1/ssocookie； - 页面会返回类似
{"npsso":"xxxxxxxx...（64 位字符）..."}的内容，复制其中的字符串； - 在 AstrBot 插件配置中粘贴到 NPSSO 令牌 项。
- NPSSO 是你账号的会话凭证，请勿泄露；
- 令牌有效期约几个月，过期后查询会报「认证失败」，重新获取并更新即可；
- 插件仅用该令牌读取公开资料、游戏时间和奖杯信息，不会进行任何账号写操作；
- 服务器若位于无法直连 PSN 的地区，请在配置中设置 代理（proxy）。
在 AstrBot 管理面板的插件配置页可修改：
| 配置项 | 说明 | 默认值 |
|---|---|---|
npsso_token |
PSN 的 NPSSO 令牌（必填） | 空 |
enabled_groups |
启用插件的群聊名单（群号列表）；留空表示所有群启用 | [] |
proxy |
HTTP/HTTPS 代理，如 http://127.0.0.1:7890 |
空 |
image_quality |
输出 JPEG 图片质量（10-100） | 90 |
cache_ttl |
个人/游戏库/奖杯数据的缓存时间（秒） | 300 |
max_titles |
游戏库/排行最多统计的游戏数量 | 200 |
command_prefix |
指令前缀（仅作展示用，指令已开启 prefix_optional） |
/ |
nl_llm_assist |
单款游戏查询匹配失败时，是否让 LLM 从游戏库前 60 项中选候选；不负责识别意图或未 @ 的群友 | true |
运行期管理员执行 /psn禁用 的群会记录在数据目录 enabled_groups.json 的 disabled_groups 中，并覆盖配置白名单；/psn启用 会取消该群的禁用。白名单为空时，除已禁用的群外，其余群仍可使用。
所有指令均支持带 / 或不带前缀触发（prefix_optional=True）。
| 指令 | 说明 | 权限 |
|---|---|---|
/psn帮助 |
查看指令帮助 | 所有人 |
/绑定psn <PSN在线ID> |
绑定你的 PSN 账号 | 所有人 |
/解绑psn |
解除绑定 | 所有人 |
/psn同步 |
将已有绑定同步到当前群聊 | 所有人 |
/psn [@某人或ID] |
查看个人资料 / 在线状态 / 奖杯总览 | 所有人 |
/psn游戏库 [@某人] |
查看游戏库与游戏时间 | 所有人 |
/psn奖杯 [@某人] |
查看各游戏奖杯进度 | 所有人 |
/psn游戏 <游戏名关键词> [@某人] |
查看指定游戏的时长 / 奖杯详情 | 所有人 |
/psn排行 [游戏数|时长|奖杯|白金] |
本群排行榜 | 所有人 |
/psn对比 @某人 |
与群友对比数据 | 所有人 |
/psn联动 |
群内好友关系与共同游戏 | 所有人 |
/psn在线 |
群内谁在线、正在玩什么 | 所有人 |
/psn刷新 |
强制刷新自己的数据缓存 | 所有人 |
/psn启用 |
在当前群启用插件 | 仅管理员 |
/psn禁用 |
在当前群禁用插件 | 仅管理员 |
@某人表示可以 @ 群内其他成员来查询 TA（前提是 TA 已绑定）；也可直接写对方的 PSN 在线 ID。
/psn游戏示例：/psn游戏 艾尔登法环（查自己）、/psn游戏 黑神话悟空 @某人（查群友）、/psn游戏 老头环、/psn游戏 战神5、/psn游戏 美末2。游戏名支持俗称/简称/英文名/中文正式名模糊互通，自动忽略大小写、全半角、音标与版本后缀（Remake/Remaster/PS5 等）；带版本号的查询不会误中前作；找不到时会列出最接近的游戏名。展示该游戏的总时长、启动次数、首次/最近游玩日期与奖杯进度。🧹 进度提示自动撤回：较慢的查询（资料/游戏库/奖杯/指定游戏/排行/对比/联动/在线/绑定）会先发一条「正在获取…」提示，结果发出后自动撤回该提示（OneBot 系协议，如 NapCat/Lagrange/go-cqhttp）。非 OneBot 平台会自动降级为普通提示（保留不撤回）。
本插件支持用日常说话的方式查询，不必记忆指令。自然语言在插件层先做确定性意图识别（@filter.regex），运行在 Agent / LLM 阶段之前，因此：
- ✅ 不强制要求给机器人配好“能聊天”的 LLM 也能用（只要 @ 机器人 / 私聊唤醒）；语义识别以确定性规则为主，速度快、结果稳定；
- ✅ 不受其他 Agent 类插件干扰——即使同时安装了
memory_companion、private_companion等会接管对话的插件，PSN 请求也会在进入它们之前被本插件直接处理并终止事件，不会出现「LLM 不调用工具、直接回接口有问题」的情况； - 💡 可选 LLM 辅助：已识别为单款游戏查询、但确定性匹配没找到游戏时，
nl_llm_assist可让当前 LLM 从游戏库前 60 项中选候选。失败会回退；关闭该项可避免这一路额外 LLM 调用。群昵称仍按群名册确定性识别； - 同时仍注册了一组 函数调用工具（
@filter.llm_tool） 作为兜底。
示例（直接 @机器人 说）：
- 「查一下我的 PSN 资料」/「我的 PSN 现在在玩什么？」
- 「@某人 的 PSN 现在在玩什么游戏？」
- 「看看我的奖杯」/「我的游戏库有哪些？」
- 「我大镖客2玩了多久？」/「我r6玩了多久」（句首「我」与游戏名粘连也会被自动剔除：会先试着把关键词还原成「大镖客2」「r6」再搜）/「老头环的游戏信息」/「战神5奖杯进度」
- 「@小明 艾尔登法环玩了多久？」（查 @小明 的这款游戏）/「@小明 的游戏库」/「@小明 奖杯进度」
- 「看看 小明 的奖杯」（没 @ 也行：在支持群名册的平台上会按群昵称识别出“小明”再查询）
- 「群里谁最肝？」/「本群游戏时长排行」/「群里谁的白金多？」
- 「我和 @某人 谁的奖杯多？」
- 「现在群里谁在线？」
- 「我想绑定 PSN，ID 是 XiaoMing」
被 @ 的人会被自动识别为查询目标（同样要求 TA 已绑定）；未 @ 但直接写了对方昵称/名字时，会尽量按群昵称识别（对手动输入昵称与实际昵称一致的情况最可靠）。
提示：通用词如「绑定」「对比」「在线」「游戏怎么样」不会单独触发 PSN 查询；请带上「PSN」或明确的游戏数据问题。意图识别以确定性关键词为骨架；未识别出的问法会交还聊天 LLM，
nl_llm_assist不负责意图识别。直接用/psn等指令最稳妥。绑定/解绑等操作也可直接用自然语言完成，但需明确提到 PSN。
🤔 一个小众游戏的俗称不在“预置名单”里，怎么搜？ 模糊匹配并不是靠一张写死的俗称表，而是按下面三层兜底，越往后越“懂行”：
- 别名/俗称表（
GAME_ALIAS_KEYWORDS）+ 强模糊匹配：先按你的说法（含去掉主语后的变体）去命中你真实拥有的游戏列表；只要你的库里有这款，多数情况下靠「中文名/英文名/子串/内容词」相似度就能命中； - 真实游戏库为准：能命中与否最终看的是你实际拥有的那批游戏，而不是某个“全网游戏名单”——所以任意一款玩过的游戏都覆盖得到；
- 可选 LLM 判定：单款游戏查询已识别，但确定性匹配未命中时，会带原文问一次当前 LLM（
nl_llm_assist=开），从按时长排序的游戏库前 60 项中挑候选；超出该范围的游戏不会参与这一步。
如果你希望某句开头更好用，最简单是告诉作者把该俗称加进 GAME_ALIAS_KEYWORDS 第一层即可（我们随时能补），但正常情况下第 1、3 层已经够用。
插件通过 StarTools.get_data_dir() 保存数据，通常位于 data/plugin_data/astrbot_plugin_PlayStationGames/：
data/plugin_data/astrbot_plugin_PlayStationGames/
├── psn_bindings.json # 用户绑定与群成员映射
├── enabled_groups.json # 运行时启用/禁用的群聊
├── usage.log # 指令使用日志
└── image_cache/ # 头像、游戏封面缓存
psn_bindings.json结构：{ "users": { "QQ号": "PSN在线ID" }, "groups": { "群号": { "QQ号": "PSN在线ID" } } }- 所有数据仅保存在本地，不会上传到任何第三方服务器。
Q：为什么游戏库里看不到某些游戏？
A：PSN 的游戏时间接口（titleStats）只返回 PS4 及以上且有游玩记录的游戏，PS3、PSV 及从未启动过的数字版游戏不会出现。
Q：为什么查不到某个用户 / 提示私密？ A：对方可能在 PSN 隐私设置中关闭了「活动状态 / 游戏历史 / 奖杯」的公开可见性。本插件只能读取公开数据。
Q：排行很慢？
A：排行需要为群内每位成员分别请求游戏库与奖杯，而 PSNAWP 默认遵循 PSN 的速率限制（约每 3 秒 1 个请求）。人多时请耐心等待；可适当调小 max_titles 减少单次拉取量。
Q：报「认证失败 / NPSSO 无效」？ A：令牌过期或被吊销。重新按上文步骤获取新的 NPSSO 并更新配置即可。
Q：网络连接错误？
A：请在配置中设置可用的 proxy；同时确认服务器能访问 *.playstation.com、*.playstation.net 等域名。
项目结构：
astrbot_plugin_PlayStationGames/
├── main.py # 插件主入口，注册所有指令
├── psn_client.py # 对 PSNAWP 的异步封装 + 缓存
├── media.py # 图片/封面下载与 data-uri 缓存
├── metadata.yaml # 插件元信息
├── _conf_schema.json # AstrBot 配置面板 schema
├── requirements.txt
├── logo.png
├── templates/ # HTML 渲染模板（Jinja2 风格，由 AstrBot 渲染）
│ ├── profile.html
│ ├── library.html
│ ├── trophies.html
│ ├── game.html
│ ├── ranking.html
│ ├── compare.html
│ ├── network.html
│ └── online.html
├── README.md # 中文说明
├── README_EN.md # English README
PSNAWP 是同步库，内部使用 requests。psn_client.py 通过 asyncio 线程池执行阻塞调用，并加锁串行化以遵守 PSN 的速率限制。