暂停维护
请勿安装使用！请勿安装使用！请勿安装使用！
AstrBot 的 Nintendo Switch Online 玩家数据插件。 群友加一个「机器人 NS 账号」为好友并绑定好友码，即可在群里查看谁在线、正在玩什么，结果以图片形式返回。
这是与 PlayStation 插件配套的姊妹插件。为解决「每人都要 OAuth 绑定太麻烦」的问题，本插件采用单机器人账号模式。
登录与刷新令牌所需的 f-token 默认由公共服务 imink 生成。但经实测，目前公共 f-token 服务长期不稳定/基本不可用（api.imink.app 的 /f 频繁返回 HTTP 500，老牌 flapg 已停服，且全网匿名公开的 f 服务仅此一家），会导致登录机器人账号、刷新在线状态失败。
👉 强烈建议自建 f-token 服务，一次部署、彻底摆脱公共服务波动。f 由 NSO App 本地计算，不需要连接任天堂、境内机器即可部署。
- 📖 完整教程：自建 f-token 服务指南
- ✅ 最省事方案：一台已 root 的闲置安卓手机（arm64）+ 电脑上跑 znca-api，无需云服务器；
- ✅ 或一台 aarch64（ARM）云服务器用 Docker 部署。
⚠️ 普通 x86_64 云服务器无法自建（任天堂新版 App 只有 ARM 原生库，x86 指令翻译下 frida 注入会崩溃，已实测）。
未自建时插件仍会按默认顺序尝试 imink 公共服务，可用时能正常工作；不可用时面板「测试 f-token 连通性」会显示故障。
- 任天堂没有成就/奖杯系统，也不公开完整游戏库，因此本插件只做在线状态 / 正在游玩 / 好友列表；
- 在线状态只有互为好友后才可见，所以需要大家加机器人账号为好友；
- 全程走 Nintendo Switch Online 官方 App 接口，不模拟 Switch 设备连接游戏服务器，封号风险较低，但仍建议用小号当机器人。
- 管理员准备一个 Nintendo 账号（建议小号），在 **WebUI 面板的「NS 管理面板」**中登录，
session_token会自动保存； - 插件显示该账号的好友码，群友在 Switch 上加它为好友；
- 插件后台每 2 分钟自动通过好友申请（可在面板开关或手动审核）；
- 群友发送
/绑定ns SW-XXXX-XXXX-XXXX关联自己的好友码； - 之后
/ns在线等指令通过机器人账号的好友列表读取大家的在线状态。
相比旧版「每人各自 OAuth 登录」，这种方式群友几乎零门槛。
cd plugins
git clone https://github.com/Eason4869/astrbot_plugin_NintendoGames.git依赖仅 aiohttp，必要时：
pip install -r requirements.txt大多数配置都可在 WebUI 面板 → 本插件的「NS 管理面板」→ 设置 中直接修改并即时生效；插件配置页中的值仅作为初始值，面板修改会覆盖它并持久化到数据目录。常用配置：
| 配置项 | 说明 |
|---|---|
bot_session_token |
机器人 Nintendo 账号的 session_token。一般留空，在面板登录后自动保存 |
auto_accept_friend_requests |
自动通过收到的好友申请，默认开启（可在面板开关） |
f_token_api |
f-token 服务地址。公共 imink 服务现已长期不稳定，强烈建议自建（见自建指南）；默认依次尝试 imink（api.imink.app、api.imink.us）。支持多个地址用逗号/换行分隔做容灾；可填服务根地址，插件会自动归一化到正确的 f 端点 |
f_token_insecure_ssl |
不校验 f-token 服务证书，默认 false（证书过期会自动降级重试，一般无需开启） |
enabled_groups |
启用群聊名单（群号列表），空列表表示全部启用 |
proxy |
HTTP/HTTPS 代理 |
user_lang |
接口语言，默认 zh-CN |
image_quality |
图片质量 10-100 |
cache_ttl |
在线状态缓存秒数，默认 120 |
session_token 是 Nintendo Account 的长期登录令牌（形如 eyJhbGciOiJIUzI1NiJ9.xxx.yyy 的三段字符串），插件用它换取后续访问令牌，不需要账号密码。建议用专门的小号作为机器人账号。
推荐直接在 AstrBot WebUI 中完成：
- 打开 AstrBot 面板 →「插件」→ 找到本插件 → 打开「NS 管理面板」；
- 点「① 打开 Nintendo 登录页」，在新标签页登录机器人 Nintendo 账号（建议小号）；
- 若点击后没有弹出新标签页（受限 iframe 可能拦截弹窗），请右键该按钮 → 在新标签页中打开链接，或点击页面显示的兜底链接；
- 登录后点「选择此用户」，会跳到一个以
npf71b963c1b7b6d119://auth#...开头、浏览器显示打不开/空白的页面——这是正常的； - 复制该页面地址栏的完整链接，粘贴回面板输入框，点「② 完成绑定」；
- 提示「绑定成功」后面板自动切换到管理视图，token 已保存，无需重启。
为什么还要手动复制一次链接？任天堂对该客户端固定了
npf71b963c1b7b6d119://auth作为回调地址（自定义协议），无法改成我们的网页地址，所以授权后一定会跳到那个打不开的页面。
登录后面板还可：查看机器人资料/好友总数与在线数、浏览好友列表（在线状态 + 正在游玩）、审核并一键通过好友申请、开关「自动通过好友申请」、修改 f-token/代理/语言/图片质量/缓存时长等设置，以及退出登录。
也可以用 nxapi（npx nxapi nso auth）等第三方工具获取 session_token 后填入配置项作为初始值。
| 指令 | 说明 |
|---|---|
/ns帮助 |
查看帮助（会显示机器人好友码） |
/绑定ns SW-XXXX-XXXX-XXXX |
绑定你自己的好友码 |
/解绑ns |
解除绑定 |
/ns同步 |
把自己同步到当前群 |
/ns |
查看机器人账号资料、好友码、好友数/在线数 |
/ns在线 |
群内谁在线、正在玩什么 |
/ns好友 |
机器人账号的 NS 好友列表 |
/ns名片 |
生成你的 NS 名片 |
/ns刷新 |
刷新缓存 |
/ns启用、/ns禁用 |
管理员开关本群插件 |
使用流程：加机器人 NS 好友 → /绑定ns 你的好友码 → /ns在线。
数据位于 AstrBot 数据目录 data/astrbot_plugin_NintendoGames/：
ns_bindings.json # QQ号 -> 好友码/nsaId/昵称；及群成员映射
enabled_groups.json # 运行时增删的启用群
runtime_settings.json # WebUI 面板修改的运行时设置（优先级高于插件配置）
bot_session_token.txt # 面板登录保存的 session_token（优先级高于配置项）
usage.log # 使用日志
image_cache/ # 头像/游戏图标缓存
机器人账号的 session_token 在面板登录后保存为 bot_session_token.txt（优先级高于配置项）。面板里修改的「自动通过好友申请」等设置写入 runtime_settings.json，重启后仍生效。该令牌等同于账号登录凭证，请勿分享或提交到 Git。
Q：加了好友但 /ns在线 看不到我？
A：确认 ① 好友申请已被通过（默认自动通过，约 2 分钟内）；② 你已用正确的好友码 /绑定ns；③ 你的在线状态在 Switch 隐私设置中设为对好友可见。可执行 /ns刷新 后重试。
Q：机器人好友码在哪看？
A：发送 /ns帮助 或 /ns；也可在 WebUI 的「NS 管理面板」概览页查看。
Q：不想自动通过好友申请，想手动审核怎么办？ A：在 WebUI「NS 管理面板 → 设置」关闭「自动通过好友申请」，然后在「好友申请」页手动通过单个或一键全部通过。
Q：提示 f-token 服务不可用 / imink 报错（DNS 失败、HTTP 500、证书过期）怎么办？ A：f-token 默认由公共服务 imink 生成，该服务近期长期不稳定（HTTP 500），这是当前最常见问题。解决与排查：
- 首选——自建 f-token 服务（一劳永逸）：一台已 root 的闲置安卓手机，或一台 ARM(aarch64) 云服务器即可；f 本地计算、不连任天堂、境内可部署。完整步骤见 自建 f-token 服务教程。部署后把
http://.../api/znca/f（或直接填服务根地址，插件会自动补全）填入f_token_api。 - 临时排查：打开「NS 管理面板 → 设置」，点「测试 f-token 连通性」，查看每个端点的状态与延迟；
- 若显示“DNS 解析失败”，是本机网络无法访问 imink：在设置里填可用的 HTTP/HTTPS 代理（如
http://127.0.0.1:7890）后重试； - 若显示“HTTP 500”，是 imink 服务端故障，只能等待恢复，或改用自建；
- 证书过期可开启「不校验 f-token 服务证书」（默认遇到证书错误会自动降级重试一次）。
注意：代理必须是运行 AstrBot 的那台机器能访问到的地址。普通 x86_64 云服务器无法自建（新版 NSO 只有 ARM 原生库，x86 指令翻译下 frida 注入会崩溃），请用 root 安卓手机或 ARM 云服务器，详见教程。
Q：能只凭好友码查任意人的在线状态吗？ A：不能。任天堂只对好友返回在线状态，这也是本插件需要大家加机器人为好友的原因。
Q：会被封号吗？ A：只调用官方 App 的好友/状态接口，不模拟设备、不连游戏服务器，风险较低，但非官方使用无法保证零风险，建议用小号当机器人账号。
MIT