基于 AstrBot 的剑网三综合数据查询插件
`astrbot_plugin_jx3` 通过 JX3API、JX3BOX 等数据源查询《剑网3》游戏数据，并根据功能将结果发送为纯文本、图片、图文消息或两轮交互消息。插件同时提供本地避雷记录和基于 JX3API WebSocket 的实时事件推送。 ## 功能特点 - 中文触发词覆盖活动、名剑、排行、交易、阵营、角色、奇遇、副本、家园、社区等场景。 - 支持纯文本、远程图片、HTML/Jinja2 渲染图片和图文消息链。 - 支持 `宏`、`资历` 两类 10 秒两轮交互，超时默认选择第一项。 - 支持本地 SQLite 避雷记录的增删改查。 - 支持按 AstrBot 会话分别开启总开关和具体 JX3API 实时事件订阅。 - 复用 `aiohttp.ClientSession`，统一处理 GET、POST、JSON、图片和分页请求。 - JX3BOX 的 Node、Next2、CMS 请求统一封装，交易行基础物品数据支持本地快照缓存和过期兜底。 - 内置 47 个页面片段，通过公共布局与样式在本地组装为完整 HTML，并附带通用、沙盘、门派/心法和奇遇图标资源。 ## 数据来源 | 数据源 | 代码入口 | 主要用途 | | --- | --- | --- | | [JX3API](https://www.jx3api.com/) | `core/jx3api_data.py`、`core/event_push.py` | 游戏查询、资历分布、沙盘据点数据及 WebSocket 实时事件 | | [JX3BOX](https://www.jx3box.com/) | `core/jx3box_data.py` | 奇遇攻略、配装、宏及交易行 | | 本地 SQLite | `core/sqlite.py`、`core/bilei_data.py` | 心法别名、避雷记录、事件订阅和基础数据缓存 | 外部数据源的可用性、数据时效和字段结构均不由本插件控制。接口变更、网络异常、凭据权限不足或上游限流都可能导致查询失败。 ## 安装 ### 环境要求 - AstrBot `>= 4.24.1`（管理页依赖 Plugin Pages） - 能够运行当前 AstrBot 版本的 Python 环境 - 能够访问插件使用的外部数据源 - 图片类指令需要 AstrBot 的 HTML 渲染能力正常可用 ### 安装插件 将仓库放入 AstrBot 的插件目录： ```text data/plugins/astrbot_plugin_jx3 ``` 也可以在 AstrBot 根目录执行： ```bash git clone https://github.com/qsc20001102/astrbot_plugin_jx3.git data/plugins/astrbot_plugin_jx3 ``` 使用 AstrBot 所在的 Python 环境安装依赖： ```bash pip install -r data/plugins/astrbot_plugin_jx3/requirements.txt ``` 随后重启 AstrBot 或重新加载插件，并在 AstrBot 管理面板中完成插件配置。 ### Python 依赖 | 依赖 | 用途 | | --- | --- | | `aiohttp` | 异步 HTTP 请求与连接复用 | | `aiofiles` | 异步读取 HTML 模板 | | `aiosqlite` | 异步访问本地 SQLite 数据库 | | `matplotlib` | 当前依赖清单保留的绘图依赖；v3.2.1 业务代码未直接导入 | ## 插件配置 配置结构由 `_conf_schema.json` 定义。 | 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | `prefix.enable` | `bool` | `true` | 是否启用指令前缀检查 | | `prefix.text` | `string` | `剑三` | 指令前缀内容 | | `jx3api_token` | `string` | 空 | JX3API Token | | `jx3api_ticket` | `string` | 空 | 部分名剑和心法接口需要的推栏 Ticket | | `jx3api_wss` | `string` | `wss://socket.nicemoe.cn` | JX3API 事件通道地址 | | `jx3api_wss_token` | `string` | 空 | 事件版令牌；免费事件无需填写 | 会话区服绑定、区服别名和事件订阅均保存在本地 SQLite。修改 WebSocket 地址或事件版令牌后需要重新加载插件。 ### Token 与 Ticket JX3API Token 可从 [JX3API](https://www.jx3api.com/) 获取。推栏 Ticket 通常来自推栏客户端的登录请求，属于敏感凭据。 当前代码会同时传入 Token 和 Ticket 的指令有： - `战绩`、`名剑排行`、`名剑统计` - `阵眼`、`资历排行`、`技能`、`奇穴` 其余在下方标记为“Token”的指令只传入 JX3API Token。是否还需要对应接口权限，以数据提供方的实际规则为准。 ## 使用方式 默认启用前缀，因此推荐发送： ```text 剑三 功能 剑三 日常 剑三 战绩 梦江南 角色名 33 ``` 前缀与指令之间的空格可以省略，例如 `剑三日常` 也能触发。关闭前缀检查后可直接发送 `日常`。 参数规则： - 指令和参数使用空白字符分隔。 - `[参数]` 表示可选参数；未加方括号的参数必须提供。 - 当前分发器按空白切分消息，因此角色名、物品名、备注等单个参数不能包含空格。 - 未识别的消息会被忽略；已识别的指令会停止继续传播给其他插件。 - 缺少必填参数、数字转换失败或执行异常时，入口层统一回复 `参数错误或执行失败`。 - 未绑定区服时按指令表提供标准参数。绑定后可以省略 `server` 参数；显式填写完整参数时仍优先使用本次输入的区服。在区服参数位置填写 `全区` 时，会忽略会话绑定并向接口传入空区服以查询全区数据。 - 标准区服名和 WebUI 中配置的别名都可用于查询。对于区服后的可选参数，分发器通过当前有效区服目录和别名判断首个参数是显式区服还是后续参数。 ### 会话区服绑定 | 指令 | 作用 | | --- | --- | | `绑定区服` | 查看当前会话的绑定状态 | | `绑定区服 梦江南` | 将当前会话绑定到指定区服；支持区服别名 | | `解绑区服` | 解除当前会话绑定 | 例如会话已经绑定 `梦江南` 后，`战绩 角色名 33` 等价于 `战绩 梦江南 角色名 33`；仍可发送 `战绩 唯我独尊 角色名 33` 临时查询其他区服，或发送 `战绩 全区 角色名 33` 查询全区数据。 ## 指令参考 凭据列含义： - **无**：当前实现不会向该查询传入 `jx3api_token` 或 `jx3api_ticket`。 - **Token**：当前实现会传入 `jx3api_token`。 - **Token + Ticket**：当前实现会同时传入两项凭据。 - 本地功能和任务状态查询不访问对应的游戏查询接口。 ### 帮助与活动情报 | 指令 | 说明与输出 | 凭据 | | --- | --- | --- | | `功能` | 渲染完整功能帮助图 | 无 | | `日常 [延后天数]` | 查询指定偏移天数的活动日历，默认当天；文本 | 无 | | `日常预测` | 查询未来 15 天日历；图片 | 无 | | `穹野卫`、`披风会`、`云从社`、`楚天社` | 查询对应地图活动；图片 | 无 | | `关隘` | 查询关隘首领状态；图片 | Token | | `赤兔`、`本周赤兔` | 查询当日或本周赤兔记录；文本 | Token | | `阵营奉献 [阵营]` | 查询阵营奉献事件，固定最多 50 条；图片 | Token | | `烟花 服务器 [角色]` | 查询指定服务器的烟花记录；已绑定会话可省略服务器；图片 | Token | | `刷马 服务器` | 查询刷马聊天情报；文本 | Token | | `马场 服务器` | 查询未过期马场记录；文本 | Token | ### 名剑与排行榜 | 指令 | 说明与输出 | 凭据 | | --- | --- | --- | | `战绩 服务器 角色 [模式]` | 角色名剑战绩，模式默认 `33`；图片 | Token + Ticket | | `名剑排行 [模式] [数量]` | 名剑大会排行，默认 `33`、50 条；图片 | Token + Ticket | | `名剑统计 [模式]` | 名剑门派统计，模式默认 `33`；图片 | Token + Ticket | | `试炼排行 服务器 心法` | 试炼之地排行；图片 | Token | 以下排行榜指令均使用 `指令 服务器` 格式，输出图片并需要 Token： ```text 名士五十强 老江湖五十强 兵甲藏家五十强 名师五十强 阵营英雄五十强 薪火相传五十强 庐园广记一百强 浩气神兵宝甲五十强 恶人神兵宝甲五十强 浩气爱心帮会五十强 恶人爱心帮会五十强 赛季恶人五十强 赛季浩气五十强 上周恶人五十强 上周浩气五十强 本周恶人五十强 本周浩气五十强 ``` ### 物价与交易 | 指令 | 说明与输出 | 凭据 | | --- | --- | --- | | `阵营拍卖 服务器 [物品] [数量]` | 阵营拍卖记录，默认最多 50 条；图片 | Token | | `的卢 服务器` | 的卢拍卖记录；图片 | Token | | `金价 服务器 [数量]` | 金价行情，默认 15 条；图片 | Token | | `物价 外观名称 [服务器]` | 外观价格记录；图片 | Token | | `成本 服务器 物品名称 [来源]` | 制造成本，来源默认 `0`；图片 | Token | | `看号 万宝楼编号` | 万宝楼账号详情；文本 | Token | | `交易行 服务器 物品` | 本地模糊匹配物品后批量查询 JX3BOX 交易行价格；图片 | 无 | `交易行` 会按“完全匹配、前缀匹配、包含匹配”排序，最多取 50 个物品 ID。基础物品分组会缓存 30 天；价格结果展示物品图标、砖/金/银/铜价格、样本数量和数据时间。 ### 阵营战场 | 指令 | 说明与输出 | 凭据 | | --- | --- | --- | | `帮战 服务器` | 帮战记录；图片 | 无 | | `沙盘 服务器` | 查询 JX3API 据点归属并使用本地图层渲染阵营沙盘；已绑定会话可省略服务器 | Token | | `诛恶 服务器` | 诛恶事件，固定最多 20 条；图片 | Token | ### 角色名片与奇遇 | 指令 | 说明与输出 | 凭据 | | --- | --- | --- | | `名片 服务器 角色` | 缓存名片，发送文字与角色图片 | Token | | `全名片 服务器 角色` | 历史名片，发送文字与多张图片 | Token | | `随机秀 服务器 [门派] [体型]` | 随机角色秀；图文消息 | Token | | `奇遇 服务器 角色` | 角色奇遇记录；图片 | Token | | `查询 服务器 角色` | `奇遇` 的别名 | Token | | `未出 服务器 角色` | 未触发奇遇；图片 | Token | | `汇总 服务器 [天数]` | 区服奇遇汇总，默认 7 天；图片 | Token | | `近期 服务器 [数量]` | 区服近期奇遇，默认 20 条；图片 | Token | | `统计 奇遇 [服务器] [数量]` | 指定奇遇的触发统计，默认 20 条；图片 | Token | | `攻略 奇遇` | 从 JX3BOX 获取奇遇攻略正文并渲染；图片 | 无 | ### 百战、角色与心法 | 指令 | 说明与输出 | 凭据 | | --- | --- | --- | | `精耐 服务器 角色` | 角色百战精耐记录；图片 | Token | | `百战` | 本周百战首领；图片 | Token | | `成就 服务器 角色 成就` | 查询指定成就；图片 | Token | | `角色 服务器 名称` | 查询角色详情与历史信息；文本 | Token | | `阵眼 心法` | 查询阵眼效果；文本 | Token + Ticket | | `配装 心法 [类型]` | 从 JX3BOX 获取推荐配装链接；文本。当前 `类型` 参数已接收但尚未用于请求筛选 | 无 | | `资历排行 [服务器] [门派]` | 资历排行榜；图片 | Token + Ticket | | `技能 心法` | 心法技能；图片 | Token + Ticket | | `奇穴 心法` | 心法奇穴；图片 | Token + Ticket | | `宏 心法` | 先返回动态宏列表，10 秒内回复序号后返回宏文本和帖子内容；超时默认选择热度第一项 | 无 | | `资历 服务器 角色` | 返回固定资历分类菜单，10 秒内回复序号后通过 JX3API 渲染资历进度图 | Token + Ticket | `资历` 的 `1` 表示总览，`2-19` 固定对应杂闻、武学、修为、装备、技艺、阅读、任务、足迹、战斗、声望、秘境、帮会、阵营、节日、活动、风雨江湖路、家园和剑侠录，不再使用本地资历菜单和点数缓存。第二轮只需回复数字，不需要再次添加插件前缀；10 秒未选择时默认把首项 `{"1": "总览"}` 交给次轮查询并继续渲染。 ### 游戏社区与休闲 | 指令 | 说明与输出 | 凭据 | | --- | --- | --- | | `聊天 服务器 角色 [条数] [页数]` | 角色聊天记录，默认 20 条、第 1 页；图片 | Token | | `统战 [服务器]` | 统战频道统计；文本 | 无 | | `小药 [心法]` | 小吃小药推荐；图片 | 无 | | `骗子 UID [服务器]` | 查询欺诈记录；文本 | Token | | `花价 服务器 [名称] [地图]` | 家园鲜花价格；图片 | 无 | | `装饰 名称` | 家园装饰信息；图片 | 无 | | `器物 地图名称` | 器物图谱；图片 | 无 | | `拜师 服务器 [关键词]` | 师父列表，固定最多 50 条；图片 | Token | | `收徒 服务器 [关键词]` | 徒弟列表，固定最多 50 条；图片 | Token | | `维护 [数量]` | 维护公告，默认 5 条；文本 | 无 | | `新闻 [数量]` | 新闻资讯，默认 5 条；文本 | 无 | | `招募 服务器 [副本]` | 团队招募，固定最多 50 条；图片 | Token | | `团长 服务器 [名称]` | 按团长搜索招募；图片 | Token | | `团牌 服务器 [内容]` | 按团牌内容搜索招募；图片 | Token | | `答案之书` | 随机答案；文本 | 无 | | `舔狗语录` | 随机语录；文本 | 无 | | `疯狂星期四`、`彩虹屁`、`毒鸡汤`、`朋友圈` | 指定类型的文案；文本 | Token | | `喝什么`、`吃什么`、`骚话`、`渣男语录` | 随机文案；文本 | 无 | ### 百度贴吧、系统工具与副本 | 指令 | 说明与输出 | 凭据 | | --- | --- | --- | | `贴吧物价 名称 [服务器] [数量]` | 贴吧物价记录，默认 5 条；文本 | Token | | `818 [服务器] [数量]` | 随机 818 内容，默认 10 条；文本 | Token | | `科举 题目 [条数]` | 科举题目搜索，默认 5 条；文本 | 无 | | `区服` | 全区服状态；图片 | 无 | | `开服 服务器` | 指定服务器开服状态；文本 | 无 | | `技改` | 最近技改记录；文本 | 无 | | `解密` | 当前秘境解密信息；文本 | Token | | `副本 服务器 角色` | 角色副本记录；图片 | Token | | `掉落 物品 [服务器] [数量]` | 副本掉落统计，默认 20 条；图片 | Token | ### 本地避雷 | 指令 | 说明与输出 | | --- | --- | | `避雷添加 名称 备注` | 写入名称、备注、当前时间和发送者名称 | | `避雷查看` | 查看全部记录；图片 | | `避雷查询 名称` | 按名称模糊查询；图片 | | `避雷修改 ID 名称 备注` | 按 ID 更新记录，同时覆盖修改时间和修改人 | | `避雷删除 ID` | 按 ID 删除记录 | 避雷功能没有内置权限校验。只要能够触发插件指令，当前实现就允许新增、修改和删除记录；公开群聊部署时应在 AstrBot 或消息平台层配置访问控制。 ### 实时事件推送 | 指令 | 作用 | | --- | --- | | `事件推送`、`事件推送 状态` | 查看当前会话的总开关和已订阅事件 | | `事件推送 开启` | 开启当前会话的事件推送总开关 | | `事件推送 关闭` | 关闭总开关；保留各事件的订阅选择 | | `事件推送 2001 开启` | 为当前会话订阅事件 `2001` | | `事件推送 2001 关闭` | 为当前会话取消订阅事件 `2001` | | `事件推送 列表` | 查看支持的全部事件编号 | 总开关和具体事件开关必须同时开启，消息才会发送到当前会话。事件正文包含 `server` 时，只向绑定该区服和未绑定区服的订阅会话发送；不含服务器的新闻、版本更新等事件不受区服过滤影响。插件已覆盖 JX3API 当前 39 种 WebSocket 事件，并按各事件的官方字段输出可读中文消息。免费事件为：`2001` 开服状态、`2002` 官方新闻、`2003` 版本更新、`2004` 八卦速报、`2005` 关隘首领、`2006` 云丛预告；其他事件需要独立的事件版令牌，可通过 `事件推送 列表` 查看全部编号。 ### WebUI 插件管理 AstrBot 插件详情页中的“剑网三插件管理”页面提供四个页签：会话绑定、事件订阅、区服别名和心法别名。页面可以新增、修改或解除任意会话绑定，查看所有会话的事件总开关及订阅编号，为每个标准区服配置多个别名，并维护心法的 JX3BOX 配装 ID、标准名称和最多 5 个别名。管理页通过 AstrBot Plugin Pages 桥接调用插件 Web API，不直接访问 Dashboard 凭据。 ## 业务流程 ```mermaid flowchart LR A["AstrBot 消息事件"] --> B["前缀检查与空白切分"] B --> C["command_map 查找处理器"] C --> D["MessageBuilder 参数适配"] D --> E1["JX3APIService"] D --> E2["JX3BOXService"] D --> E3["BiLeidata / EventPushService / KungfuAliasService"] E1 --> F["APIClient"] E2 --> F F --> G["外部 HTTP 数据源"] E3 --> H["local_data.db"] E1 --> I["标准返回对象"] E2 --> I E3 --> I I --> J1["纯文本"] I --> J2["HTML 模板渲染图片"] I --> J3["远程图片或图文消息链"] ``` ### 1. 初始化与销毁 `main.py` 中的 `Jx3ApiPlugin` 是插件入口。构造阶段完成以下工作： 1. 读取前缀、Token、Ticket 和 WebSocket 配置。 2. 计算插件目录、AstrBot 数据目录、本地 SQLite 和模板目录路径。 3. 把 `templates/img`、`templates/img/sand`、`templates/sect`、`templates/serendipity` 中的图片读取为 base64 Data URL。 4. 创建本地数据库、两个数据服务、心法别名服务、避雷服务、事件推送服务和消息构建器。 异步初始化阶段会连接数据库并创建以下本地表： - `bilei`：避雷记录。 - `event_push_subscriptions`：按 AstrBot 会话保存事件总开关和每个事件编号的订阅开关。 - `session_server_bindings`：两列结构，保存会话 ID 与绑定区服。 - `server_aliases`：保存标准区服名及其 JSON 别名列表。 - `kungfu`：保存 JX3BOX 配装 ID、标准心法名及最多 5 个别名。 - `trade_item_cache`：JX3BOX 交易行基础物品数据缓存及更新时间。 `kungfu` 表首次创建时从 `data/kungfu.json` 幂等导入 32 条默认心法，`server_aliases` 表从 `data/server_aliases.json` 幂等导入默认区服别名；已存在的本地记录均不会被覆盖。随后启动 JX3API WebSocket 事件通道并建立指令映射。插件停用时会关闭事件通道、两个 HTTP Session 和本地 SQLite 连接。 ### 2. 指令分发 入口监听全部消息事件： 1. `parse_message()` 检查前缀并使用 `str.split()` 切分消息。 2. 第一段作为指令，其余段作为位置参数。 3. `command_map` 将中文触发词映射到 `MessageBuilder` 方法。 4. `_call_with_auto_args()` 通过 `inspect.signature()` 读取参数签名，按注解转换 `int` 和 `float`。 5. 找不到指令时忽略消息；找到指令后停止事件继续传播并调用处理器。 分发器不会检查多余参数，多出的参数会被忽略。缺少必填参数会抛出异常并返回统一错误提示。 ### 3. 数据服务 两个数据服务按上游来源拆分： - `JX3APIService`：以 `https://www.jx3api.com` 为根地址，通过 GET 请求实现主体功能、资历分布和沙盘据点查询。 - `JX3BOXService`：通过统一请求入口访问 JX3BOX 的 Node、CMS 和 Next2 服务，负责攻略、配装、宏及交易行。 服务方法通常返回统一结构： ```python { "code": 0, "msg": "功能函数未执行", "data": {}, "temp": "", "icons": {} } ``` 成功时设置 `code=200`；失败时保留非 200 状态并在 `msg` 中返回原因。图片功能会在 `temp` 中放入已加载的 HTML 模板正文，在 `data` 中放入模板上下文。 ### 4. HTTP 请求层 `core/request.py` 中的 `APIClient`： - 延迟创建并复用一个 `aiohttp.ClientSession`。 - 默认总超时时间为 10 秒。 - 支持 GET、JSON POST 和分页拉取。 - 根据 `Content-Type` 自动返回 JSON 或二进制数据。 - 兼容 JX3API 常见成功码 `200`、`"0"`、`0`、`1`。 - 可通过 `out_key` 提取响应中的指定字段。 - 网络、HTTP、JSON 和业务码异常统一记录日志并返回 `None`。 业务服务在 `APIClient` 之上维护各自的基础请求方法。`JX3APIService` 以 `https://www.jx3api.com` 为固定根地址；`JX3BOXService._base_request()` 根据 `node`、`next2`、`cms` 数据源选择基础地址，并统一转发 GET/POST 参数和 `out` 返回字段。JX3BOX 业务代码只传接口路径，不再重复拼接完整域名。 ### 5. 消息与图片渲染 `core/message.py` 根据业务结果选择输出方式： - `plain_msg()`：纯文本。 - `T2I_image_msg()`：向模板注入业务数据和本地图标，再调用 AstrBot HTML 渲染器生成 JPEG。 - `image_msg()`：直接发送远程图片 URL 或图片数据。 - `plain_chain()`：发送文本与图片组成的富媒体消息链；结果包含 HTML 正文时，会将其渲染为图片组件追加到消息链。 - `handler_plain_image_msg()`：通用两轮会话；首轮函数直接返回 `{"1": "总览", "2": "杂闻"}` 形式的数字键值对（无 `code`、`msg`、`data` 外层），处理器据此生成序号文本；选择后裁剪为只含所选项的新字典交给次轮函数，再由注入的输出器发送结果；超时固定选择第一项。 - `zili()`：在指令入口直接调用上述通用两轮会话处理器，并通过标准图片流程输出结果。 图片默认使用质量 `100`、完整页面截图和普通设备缩放级别。模板可通过 `icons.img`、`icons.sect`、`icons.serendipity` 访问通用、门派/心法和奇遇图标。 AstrBot 的渲染接口接收完整 HTML 字符串，因此插件不会依赖渲染端读取本地 CSS 文件。`core/template.py` 会异步读取并缓存公共布局、设计变量、基础样式和组件样式，再按需读取页面专属样式及页面片段，组装完成后把单个完整字符串交给渲染器。共享资源只在首次请求时读取一次；标准页面没有同名 CSS 文件也可以正常组合。 `styles/components.css` 是公共组件的唯一来源，内部使用 `@component` 标记划分表格、网格、能力卡片等组件块。页面通过顶部元数据声明需要的组件，加载器只把声明过的样式块注入最终 HTML，不会让只使用表格的页面同时携带技能卡片、器物卡片等无关 CSS： ```html {# template-title: 角色榜单 #} {# template-components: data-table #} ``` 样式职责如下： - `styles/tokens.css`：颜色、间距、圆角、字体和各页面内容宽度。 - `styles/base.css`：固定图片画布的页面背景、外框和基础排版。 - `styles/components.css`：统一维护数据表格、列状态、排行、统计卡片、可配置列数网格、技能/奇穴卡片、奇遇卡片、器物详情、标签和空数据等跨页面组件。 - `styles/pages/*.css`：可选，仅保留成本计算、成就、副本记录、沙盘等无法合理复用的复杂页面布局。当前 47 个页面中只有 14 个需要专属 CSS。 沙盘坐标集中在 `templates/pages/shapan.html`。搜索 `data-castle="据点名"` 后，同一段内第一个 `