+
+
+
+ 基于 AstrBot 的剑网三综合数据查询插件 +
-## 功能概览 +`astrbot_plugin_jx3` 通过 JX3API、剑侠茶馆、JX3BOX 等数据源查询《剑网3》游戏数据，并根据功能将结果发送为纯文本、图片、图文消息或两轮交互消息。插件同时提供本地避雷记录和开服、新闻、刷马、赤兔后台推送能力。 -插件内置 `功能` 指令，会以图片形式展示完整指令列表、参数说明和是否需要令牌。当前帮助页按 13 个功能分组维护，约 88 条指令。 +当前仓库版本为 **v3.1**，要求 **AstrBot >= 4.11.0**，元数据声明支持 `aiocqhttp` 与 `weixin_oc` 平台。 -主要功能包括： -【活动情报】 -活动日历： 日常 [延后天数] | 日常预测 -声望社：楚天社 | 云从社 | 披风会 | 穹野卫 -关隘首领：关隘 -赤兔：赤兔 | 本周赤兔 -阵营事件：阵营奉献 [阵营] -烟花记录:：烟花 区服 角色 -马场查询：刷马 | 马场 -【名剑相关】 -名剑战绩：战绩 服务器 角色 [模式] -名剑排行：名剑排行 [模式] [数量] -名剑统计：名剑统计 [模式] -【排行榜单】 -排行统计：名士五十强 服务器 | 老江湖五十强 服务器 | 兵甲藏家五十强 服务器 | 名师五十强 服务器 | 阵营英雄五十强 服务器 | 薪火相传五十强 服务器 | - 庐园广记一百强 服务器 | 浩气神兵宝甲五十强 服务器 | 恶人神兵宝甲五十强 服务器 | 浩气爱心帮会五十强 服务器 | 恶人爱心帮会五十强 服务器 | - 赛季恶人五十强 服务器 | 赛季浩气五十强 服务器 | 上周恶人五十强 服务器 | 上周浩气五十强 服务器 | 本周恶人五十强 服务器 | 本周浩气五十强 服务器 -试炼排行：试炼排行 服务器 心法 -【物价交易】 -阵营拍卖：阵营拍卖 服务器 [物品] [数量] -的卢拍卖：的卢 服务器 -金价行情：金价 服务器 -物品价格：物价 外观名称 [服务器] -成本计算：成本 服务器 物品名称 -编号搜索：看号 万宝楼编号 -【阵营战场】 -帮战记录：帮战 服务器 -阵营沙盘：沙盘 服务器 -诛恶事件：诛恶 服务器 -【角色名片】 -名片缓存：名片 服务器 角色 -名片历史：全名片 服务器 角色 -随机名片：随机秀 服务器 [门派] [体型] -【奇遇相关】 -奇遇记录：奇遇 服务器 角色 | 查询 服务器 角色 -未触发的：未出 服务器 角色 -奇遇汇总：汇总 服务器 [天数] -近期奇遇：近期 服务器 [数量] -奇遇统计：统计 奇遇 [服务器] [数量] -奇遇攻略：攻略 奇遇 -【百战记录】 -角色百战：精耐 服务器 角色 -百战首领：百战 -【角色信息】 -成就查询：成就 服务器 角色 成就 -角色详情：角色 服务器 名称 -【心法配装】 -阵眼效果：阵眼 心法 -魔盒配装：配装 心法 -资历榜单：资历排行 [服务器] [门派] -技能信息：技能 心法 -奇穴信息：奇穴 心法 -【游戏社区】 -角色聊天；聊天 服务器 角色 [条数] [页数] -统战歪歪：统战 [服务器] -家园鲜花：花价 服务器 [名称] [地图] -家园装饰：装饰 名称 -器物图谱：器物 地图名称 -师徒列表：拜师 服务器 [关键词] | 收徒 服务器 [关键词] -维护公告：维护 [数量] -新闻资讯：新闻 [数量] -团队招募：招募 服务器 [副本] | 团长 服务器 [名称] | 团牌 服务器 [内容] -骚话语录：答案之书 | 舔狗语录 | 疯狂星期四 | 彩虹屁 | 毒鸡汤 | 朋友圈 | 喝什么 | 吃什么 | 骚话 | 渣男语录 -【百度贴吧】 -外观记录：贴吧物价 名称 [服务器] [数量] -百度贴吧：818 [服务器] [数量] -【系统工具】 -科举答案：科举 题目 [条数] -大区状态：区服 | 开服 服务器 -技改记录：技改 -秘境方位：解密 -副本记录：副本 服务器 角色 -掉落统计：掉落 物品 [服务器] [数量] -【魔盒数据】 -魔盒宏：宏 心法 -资历查询：资历 服务器 角色 -交易行：交易行 服务器 物品 -【避雷功能】 -避雷添加：避雷添加 名称 备注 -避雷查看：避雷查看 -避雷查询：避雷查询 名称 -避雷修改：避雷修改 ID 名称 备注 -避雷删除：避雷删除 ID -【推送功能】 -开服监控：开服监控 -新闻推送：新闻推送 -刷马推送：刷马推送 -赤兔推送：赤兔推送 +> 本 README 以 v3.1 的 `main.py` 指令映射、`core/message.py` 参数签名和三个数据服务的实际实现为准。当前代码与内置帮助图之间存在少量差异，详见[当前版本状态](#当前版本状态)。 +## 功能特点 -## 安装与依赖 +- 108 个中文触发词，覆盖活动、名剑、排行、交易、阵营、角色、奇遇、副本、家园、社区等场景。 +- 支持纯文本、远程图片、HTML/Jinja2 渲染图片和图文消息链。 +- 支持 `宏`、`资历` 两类 30 秒两轮交互。 +- 支持本地 SQLite 避雷记录的增删改查。 +- 支持开服、新闻、刷马、赤兔四类定时轮询与会话推送。 +- 复用 `aiohttp.ClientSession`，统一处理 GET、POST、JSON、图片和分页请求。 +- 内置 46 个 HTML 模板，以及通用、门派/心法和奇遇图标资源。 -将插件目录放入 AstrBot 的插件目录中，例如： +## 数据来源 + +| 数据源 | 代码入口 | 主要用途 | +| --- | --- | --- | +| [JX3API](https://www.jx3api.com/) | `core/jx3api_data.py` | 绝大多数游戏查询、官方资讯、排行、角色和推送数据 | +| [剑侠茶馆](https://www.jianxiachaguan.cn/) | `core/aijx3_data.py` | 阵营沙盘图片 | +| [JX3BOX](https://www.jx3box.com/) | `core/jx3box_data.py` | 奇遇攻略、配装、宏、资历和交易行 | +| 本地 SQLite | `core/sqlite.py`、`core/bilei_data.py` | 心法别名、避雷记录、推送状态和基础数据缓存 | + +外部数据源的可用性、数据时效和字段结构均不由本插件控制。接口变更、网络异常、凭据权限不足或上游限流都可能导致查询失败。 + +## 安装 + +### 环境要求 + +- AstrBot `>= 4.11.0` +- 能够运行当前 AstrBot 版本的 Python 环境 +- 能够访问插件使用的外部数据源 +- 图片类指令需要 AstrBot 的 HTML 渲染能力正常可用 + +### 安装插件 + +将仓库放入 AstrBot 的插件目录： ```text data/plugins/astrbot_plugin_jx3 ``` -安装依赖： +也可以在 AstrBot 根目录执行： ```bash -pip install -r requirements.txt +git clone https://github.com/qsc20001102/astrbot_plugin_jx3.git data/plugins/astrbot_plugin_jx3 ``` -当前依赖： +使用 AstrBot 所在的 Python 环境安装依赖： -- `aiohttp`：异步 HTTP 请求。 -- `aiofiles`：异步文件处理。 -- `aiosqlite`：本地 SQLite 数据库。 -- `apscheduler`：后台推送任务调度。 -- `matplotlib`：部分图像/数据展示依赖。 +```bash +pip install -r data/plugins/astrbot_plugin_jx3/requirements.txt +``` -插件元信息在 `metadata.yaml` 中维护，当前版本为 `v2.7`，要求 AstrBot 版本 `>=4.11.0`。 +随后重启 AstrBot 或重新加载插件，并在 AstrBot 管理面板中完成插件配置。 + +### Python 依赖 + +| 依赖 | 用途 | +| --- | --- | +| `aiohttp` | 异步 HTTP 请求与连接复用 | +| `aiofiles` | 异步读取 HTML 模板 | +| `aiosqlite` | 异步访问本地 SQLite 数据库 | +| `apscheduler` | 后台轮询与消息推送调度 | +| `matplotlib` | 当前依赖清单保留的绘图依赖；v3.1 业务代码未直接导入 | ## 插件配置 -配置结构由 `_conf_schema.json` 定义，主要配置项如下。 +配置结构由 `_conf_schema.json` 定义。 -### 指令前缀 +| 配置项 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| `prefix.enable` | `bool` | `true` | 是否启用指令前缀检查 | +| `prefix.text` | `string` | `剑三` | 指令前缀内容 | +| `server` | `string` | `梦江南` | 后台推送使用的服务器；当前查询指令中仅 `烟花` 显式使用该值补齐空服务器 | +| `jx3api_token` | `string` | 空 | JX3API Token | +| `jx3api_ticket` | `string` | 空 | 部分名剑和心法接口需要的推栏 Ticket | +| `kfts` | `object` | 关闭、60 秒 | 开服监控配置 | +| `xwts` | `object` | 关闭、280 秒 | 新闻资讯推送配置 | +| `smts` | `object` | 关闭、60 秒 | 刷马消息推送配置 | +| `ctts` | `object` | 关闭、60 秒 | 赤兔消息推送配置 | + +四个推送对象都包含以下字段： ```json { - "prefix": { - "enable": true, - "text": "剑三" - } + "enable": false, + "time": 60, + "umos": ["QQ:GroupMessage:123456"] } ``` -- `enable`：是否启用指令前缀检查。 -- `text`：指令前缀内容，默认 `剑三`。 +- `enable`：是否在插件初始化时创建该任务。 +- `time`：轮询周期，单位为秒。 +- `umos`：接收推送的 AstrBot 会话唯一 ID 列表，可通过 AstrBot 的 `/std` 等方式获取。 -启用后，用户需要发送类似 `剑三 日常`、`剑三 奇遇 角色名` 才能触发。关闭后可直接发送 `日常`、`奇遇 角色名`。 +推送配置在插件初始化时读取。修改配置后应重新加载插件；`开服推送` 等查询指令只显示任务状态，不会动态开启或关闭任务。 -### 默认服务器 +### Token 与 Ticket -```json -{ - "server": "梦江南" -} -``` +JX3API Token 可从 [JX3API](https://www.jx3api.com/) 获取。推栏 Ticket 通常来自推栏客户端的登录请求，属于敏感凭据。 -许多指令都带有 `[服务器]` 可选参数。用户未填写服务器时，插件会使用这里配置的默认服务器。 +当前代码会同时传入 Token 和 Ticket 的指令有： -示例： +- `战绩`、`名剑排行`、`名剑统计` +- `阵眼`、`资历排行`、`技能`、`奇穴` -```text -奇遇 飞翔大野猪 -``` - -等价于： - -```text -奇遇 飞翔大野猪 梦江南 -``` - -前提是默认服务器配置为 `梦江南`。 - -### JX3API Token - -```json -{ - "jx3api_token": "" -} -``` - -需要令牌的功能必须配置该字段。Token 需要在 [JX3API](https://www.jx3api.com/) 注册并购买后获取。 - -帮助页中标记为“需令牌”的指令，如果未配置 Token，可能无法正常返回数据。 - -### 推栏 Ticket - -```json -{ - "jx3api_ticket": "" -} -``` - -部分接口需要推栏 ticket，例如部分职业、角色、学校类接口。该值通常需要通过抓包推栏 App 的请求参数获得。 - -### 推送配置 - -插件支持 4 类后台推送： - -- `kfts`：开服监控。 -- `xwts`：新闻资讯。 -- `smts`：刷马消息。 -- `ctts`：赤兔消息。 - -每类推送配置都包含： - -- `enable`：是否启用。 -- `time`：轮询间隔，单位秒。 -- `umos`：推送目标会话 ID 列表。 - -示例： - -```json -{ - "kfts": { - "enable": false, - "time": 60, - "umos": ["QQ:GroupMessage:123456"] - } -} -``` - -`umos` 需要填写完整会话 ID，可通过 AstrBot 的 `/std` 等方式获取。推送本质是后台定时请求接口，检测状态变化后向配置的会话发送消息，不建议将轮询间隔设置得过短。 +其余在下方标记为“Token”的指令只传入 JX3API Token。是否还需要对应接口权限，以数据提供方的实际规则为准。 ## 使用方式 -发送： - -```text -功能 -``` - -即可获取完整指令帮助图。 - -如果开启了指令前缀，则发送： +默认启用前缀，因此推荐发送： ```text 剑三 功能 +剑三 日常 +剑三 战绩 梦江南 角色名 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 -日常 -诛恶 -资历 飞翔大野猪 -交易行 五行石 梦江南 -奇遇 飞翔大野猪 -未做奇遇 飞翔大野猪 梦江南 -战绩 飞翔大野猪 梦江南 33 -名剑排行 50 33 -贴吧物价 狐金 5 梦江南 -统战 梦江南 +名士五十强 +老江湖五十强 +兵甲藏家五十强 +名师五十强 +阵营英雄五十强 +薪火相传五十强 +庐园广记一百强 +浩气神兵宝甲五十强 +恶人神兵宝甲五十强 +浩气爱心帮会五十强 +恶人爱心帮会五十强 +赛季恶人五十强 +赛季浩气五十强 +上周恶人五十强 +上周浩气五十强 +本周恶人五十强 +本周浩气五十强 ``` -## 目录结构 +### 物价与交易 -```text -astrbot_plugin_jx3/ -├─ main.py # AstrBot 插件入口，初始化配置、资源、服务和指令分发 -├─ metadata.yaml # 插件元信息 -├─ _conf_schema.json # AstrBot 后台配置 schema -├─ requirements.txt # Python 依赖 -├─ data/ -│ ├─ api_config.json # 外部接口配置，按功能 key 维护 URL、method、默认参数 -│ └─ plugin_data.db # 插件随包数据，主要用于内置数据 -├─ core/ -│ ├─ jx3_data.py # 业务数据层，调用接口、整理数据、选择模板 -│ ├─ message.py # 消息构建层，负责文本、图片、富媒体回复 -│ ├─ request.py # aiohttp 请求封装，统一处理 GET/POST 和接口返回 -│ ├─ async_task.py # APScheduler 后台推送任务 -│ ├─ bilei_data.py # 本地避雷数据增删改查 -│ ├─ sqlite.py # SQLite 异步封装 -│ └─ fun_basic.py # 模板加载、图片 base64、通用格式化工具 -└─ templates/ - ├─ helps.html # 功能帮助页 - ├─ *.html # 各图片指令的 HTML/Jinja2 模板 - ├─ img/ # 通用图片资源 - ├─ sect/ # 门派/心法图标 - └─ serendipity/ # 奇遇图标 +| 指令 | 说明与输出 | 凭据 | +| --- | --- | --- | +| `阵营拍卖 服务器 [物品] [数量]` | 阵营拍卖记录，默认最多 50 条；图片 | Token | +| `的卢 服务器` | 的卢拍卖记录；图片 | Token | +| `金价 服务器 [数量]` | 金价行情，默认 15 条；图片 | Token | +| `物价 外观名称 [服务器]` | 外观价格记录；图片 | Token | +| `成本 服务器 物品名称 [来源]` | 制造成本，来源默认 `0`；图片 | Token | +| `看号 万宝楼编号` | 万宝楼账号详情；文本 | Token | +| `交易行 服务器 物品` | 本地模糊匹配物品后批量查询 JX3BOX 交易行价格；图片 | 无 | + +`交易行` 会按“完全匹配、前缀匹配、包含匹配”排序，最多取 50 个物品 ID。基础物品分组会缓存 30 天；价格结果展示物品图标、砖/金/银/铜价格、样本数量和数据时间。 + +### 阵营战场 + +| 指令 | 说明与输出 | 凭据 | +| --- | --- | --- | +| `帮战 服务器` | 帮战记录；图片 | 无 | +| `沙盘 [服务器]` | 从剑侠茶馆获取沙盘图片 URL 并直接发送 | 无 | +| `诛恶 服务器` | 诛恶事件，固定最多 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 | +| `宏 心法` | 先返回宏列表，30 秒内回复序号后返回宏文本和帖子内容 | 无 | +| `资历 服务器 角色` | 先返回 `0-18` 分类菜单，30 秒内回复序号后渲染资历进度图 | Token | + +`资历` 的 `0` 表示总览，`1-18` 依次对应杂闻、武学、修为、装备、技艺、阅读、任务、足迹、战斗、声望、秘境、帮会、阵营、节日、活动、风雨江湖路、家园和剑侠录。第二轮只需回复数字，不需要再次添加插件前缀。 + +### 游戏社区与休闲 + +| 指令 | 说明与输出 | 凭据 | +| --- | --- | --- | +| `聊天 服务器 角色 [条数] [页数]` | 角色聊天记录，默认 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 或消息平台层配置访问控制。 + +### 推送任务状态 + +| 指令 | 对应配置 | 作用 | +| --- | --- | --- | +| `开服推送` | `kfts` | 查看开服监控任务状态 | +| `新闻推送` | `xwts` | 查看新闻推送任务状态 | +| `刷马推送` | `smts` | 查看刷马推送任务状态 | +| `赤兔推送` | `ctts` | 查看赤兔推送任务状态 | + +状态信息包含任务键、是否启用、轮询周期、上次状态和推送对象。任务只在 `enable=true` 且 `umos` 非空时加入调度器；检测到新旧状态不同时，插件向所有目标会话发送消息并持久化新状态。 + +## 业务流程 + +```mermaid +flowchart LR + A["AstrBot 消息事件"] --> B["前缀检查与空白切分"] + B --> C["command_map 查找处理器"] + C --> D["MessageBuilder 参数适配"] + D --> E1["JX3APIService"] + D --> E2["AIJX3Service"] + D --> E3["JX3BOXService"] + D --> E4["BiLeidata / AsyncTask"] + E1 --> F["APIClient"] + E2 --> F + E3 --> F + F --> G["外部 HTTP 数据源"] + E3 --> H["plugin_data.db / local_data.db"] + E4 --> H + E1 --> I["标准返回对象"] + E2 --> I + E3 --> I + E4 --> I + I --> J1["纯文本"] + I --> J2["HTML 模板渲染图片"] + I --> J3["远程图片或图文消息链"] ``` -## 核心实现逻辑 +### 1. 初始化与销毁 -### 1. 插件初始化 +`main.py` 中的 `Jx3ApiPlugin` 是插件入口。构造阶段完成以下工作： -`main.py` 中的 `Jx3ApiPlugin` 是插件入口。 +1. 读取前缀、默认服务器、Token、Ticket 和推送配置。 +2. 计算插件目录、AstrBot 数据目录、模板目录和两个 SQLite 文件路径。 +3. 把 `templates/img`、`templates/sect`、`templates/serendipity` 中的图片读取为 base64 Data URL。 +4. 创建本地数据库、随包数据库、三个数据服务、避雷服务、推送调度器和消息构建器。 -初始化时会完成以下工作： +异步初始化阶段会连接数据库并创建以下本地表： -1. 读取 AstrBot 插件配置，包括前缀、默认服务器、Token、Ticket 和推送配置。 -2. 计算本地数据目录、插件数据目录、模板目录和接口配置文件路径。 -3. 加载 `templates/img`、`templates/sect`、`templates/serendipity` 中的图片，并转为 base64，供 HTML 模板直接引用。 -4. 初始化 SQLite、JX3Service、AsyncTask、BiLeidata、MessageBuilder。 -5. 在异步初始化阶段创建本地表，并启动后台推送任务。 -6. 构建 `command_map`，将中文触发词映射到对应的消息处理函数。 +- `bilei`：避雷记录。 +- `tuishong`：四类推送的最新状态，固定使用 `id=1` 的单行记录。 +- `achievement_cache`：JSON 基础数据缓存及更新时间。 + +随后连接随包的 `plugin_data.db`、启动已配置的后台任务，最后建立指令映射。插件停用时会关闭调度器、三个 HTTP Session 和两个 SQLite 连接。 ### 2. 指令分发 -用户消息进入插件后，`main.py` 会： +入口监听全部消息事件： -1. 根据配置判断是否需要指令前缀。 -2. 将消息按空格切分为 `指令 + 参数`。 -3. 在 `command_map` 中查找对应处理函数。 -4. 使用 `inspect.signature` 根据函数参数数量自动传入用户参数。 -5. 找不到指令时不处理，参数错误时返回提示。 +1. `parse_message()` 检查前缀并使用 `str.split()` 切分消息。 +2. 第一段作为指令，其余段作为位置参数。 +3. `command_map` 将中文触发词映射到 `MessageBuilder` 方法。 +4. `_call_with_auto_args()` 通过 `inspect.signature()` 读取参数签名，按注解转换 `int` 和 `float`。 +5. 找不到指令时忽略消息；找到指令后停止事件继续传播并调用处理器。 -### 3. 消息构建 +分发器不会检查多余参数，多出的参数会被忽略。缺少必填参数会抛出异常并返回统一错误提示。 -`core/message.py` 的 `MessageBuilder` 负责把业务数据发出去，主要有几类输出： +### 3. 数据服务 -- `plain_msg()`：发送纯文本。 -- `T2I_image_msg()`：把业务数据传入 HTML 模板，调用 AstrBot 的 HTML 渲染能力生成图片。 -- `image_msg()`：直接发送图片 URL 或图片数据。 -- `plain_chain()`：发送文本 + 图片等富媒体消息链。 -- `handler_plain_image_msg()`：先发文本，再发图片，适用于部分组合型功能。 -- `handler_zili_msg()`：资历查询专用两轮会话，先发送 `0-18` 分类菜单，再按用户选择渲染资历进度图片。 +三个数据服务按上游来源拆分： -所有可选服务器参数都会通过 `serverdefault()` 补齐默认服务器。 +- `JX3APIService`：以 `https://www.jx3api.com` 为根地址，通过 GET 请求实现主体功能。 +- `AIJX3Service`：向剑侠茶馆发送 POST 请求，目前只负责沙盘图片。 +- `JX3BOXService`：直接访问 JX3BOX 的 Node、CMS、Next2 和图标地址，负责攻略、配装、宏、资历和交易行。 -### 4. 数据请求与业务处理 - -`core/jx3_data.py` 是主要业务层。每个功能通常对应一个异步方法，例如： - -```python -async def jinqiqiyu(self, server: str) -> Dict[str, Any]: - ... -``` - -业务方法通常遵循统一结构： - -1. 调用 `_init_return_data()` 创建标准返回对象。 -2. 构造接口参数，填入 `server`、`name`、`token`、`ticket` 等。 -3. 通过 `_base_request(config_key, method, params)` 读取 `data/api_config.json` 中的接口配置并发起请求。 -4. 判断接口返回是否为空或结构异常。 -5. 整理时间戳、字段名、分组、列表、统计值等模板需要的数据。 -6. 文本功能直接写入 `return_data["data"]`。 -7. 图片功能额外加载对应 HTML 模板并写入 `return_data["temp"]`。 -8. 成功时设置 `return_data["code"] = 200`。 - -标准返回结构大致为： +服务方法通常返回统一结构： ```python { "code": 0, - "msg": "错误提示", + "msg": "功能函数未执行", "data": {}, "temp": "", "icons": {} } ``` -### 5. 接口请求封装 +成功时设置 `code=200`；失败时保留非 200 状态并在 `msg` 中返回原因。图片功能会在 `temp` 中放入已加载的 HTML 模板正文，在 `data` 中放入模板上下文。 -`core/request.py` 中的 `APIClient` 负责实际 HTTP 请求。 +### 4. HTTP 请求层 -实现特点： +`core/request.py` 中的 `APIClient`： -- 复用 `aiohttp.ClientSession`。 -- 支持 GET 和 POST。 -- 自动识别 JSON、图片或二进制响应。 -- 对 JX3API 常见返回结构做基础校验。 -- 支持通过 `out_key` 抽取返回对象中的指定字段，默认通常取 `data`。 +- 延迟创建并复用一个 `aiohttp.ClientSession`。 +- 默认总超时时间为 10 秒。 +- 支持 GET、JSON POST 和分页拉取。 +- 根据 `Content-Type` 自动返回 JSON 或二进制数据。 +- 兼容 JX3API 常见成功码 `200`、`"0"`、`0`、`1`。 +- 可通过 `out_key` 提取响应中的指定字段。 +- 网络、HTTP、JSON 和业务码异常统一记录日志并返回 `None`。 -`JX3Service._base_request()` 会在业务层进一步统一： +### 5. 消息与图片渲染 -- 根据 `data/api_config.json` 查找接口。 -- 合并接口默认参数和运行时参数。 -- 根据配置 method 调用 GET 或 POST。 -- 捕获异常并输出日志。 +`core/message.py` 根据业务结果选择输出方式： -### 6. 图片渲染 +- `plain_msg()`：纯文本。 +- `T2I_image_msg()`：向模板注入业务数据和本地图标，再调用 AstrBot HTML 渲染器生成 JPEG。 +- `image_msg()`：直接发送远程图片 URL 或图片数据。 +- `plain_chain()`：发送文本与多张图片组成的消息链。 +- `handler_plain_image_msg()`：宏查询的两轮会话。 +- `handler_zili_msg()`：资历查询的两轮会话。 -图片输出功能使用 `templates/*.html`。 +图片默认使用质量 `100`、完整页面截图和普通设备缩放级别。模板可通过 `icons.img`、`icons.sect`、`icons.serendipity` 访问通用、门派/心法和奇遇图标。 -典型数据流： +### 6. 本地数据与缓存 + +插件使用两个 SQLite 文件： + +| 文件 | 生命周期 | 内容 | +| --- | --- | --- | +| `data/plugin_data.db` | 随插件分发，只读基础数据为主 | `kungfu` 心法名称、别名和 JX3BOX 配装 ID | +| AstrBot 插件数据目录下的 `local_data.db` | 运行时创建和维护 | 避雷记录、推送状态、资历与交易行基础数据缓存 | + +`achievement_cache` 同时被资历基础数据和交易行物品分组复用。缓存有效期为 30 天；缓存过期后优先刷新，上游请求失败时会尝试使用旧缓存兜底。 + +### 7. 后台推送 + +`core/async_task.py` 使用 `AsyncIOScheduler` 和 `IntervalTrigger`。每类任务保存： + +- 是否启用； +- 轮询周期； +- 目标会话列表； +- 本地旧状态； +- 最近请求得到的新状态。 + +调度任务取得业务数据后读取其中的 `status`。状态发生变化时，向所有 `umos` 发送 `data` 文本，并将新状态写回 `tuishong` 表。插件卸载时会移除全部任务并以非等待方式关闭调度器。 + +## 目录结构 ```text -JX3Service 整理数据 - ↓ -MessageBuilder.T2I_image_msg() - ↓ -注入 icons - ↓ -html_renderer.render_custom_template() - ↓ -发送图片 +astrbot_plugin_jx3/ +├── main.py # 插件入口、生命周期、数据库建表和指令分发 +├── metadata.yaml # 插件名称、版本、平台和 AstrBot 版本要求 +├── _conf_schema.json # AstrBot 管理面板配置结构 +├── requirements.txt # Python 依赖 +├── CHANGELOG.md # 版本更新记录 +├── LICENSE # GNU AGPL v3 +├── data/ +│ └── plugin_data.db # 随包心法/别名基础数据 +├── core/ +│ ├── jx3api_data.py # JX3API 业务服务 +│ ├── aijx3_data.py # 剑侠茶馆业务服务 +│ ├── jx3box_data.py # JX3BOX 业务服务与缓存逻辑 +│ ├── message.py # 文本、图片、消息链和两轮会话构建 +│ ├── request.py # aiohttp 请求封装 +│ ├── async_task.py # APScheduler 后台推送 +│ ├── bilei_data.py # 避雷数据增删改查 +│ ├── sqlite.py # aiosqlite 通用封装 +│ └── fun_basic.py # 模板、图标、时间和货币格式化工具 +└── templates/ + ├── helps.html # 内置功能帮助图 + ├── *.html # 各图片查询模板 + ├── img/ # 通用图片资源 + ├── sect/ # 门派与心法图标 + └── serendipity/ # 奇遇图标 ``` -模板里可以使用： +## 新增功能开发 -- `icons.img`：通用图标。 -- `icons.sect`：门派/心法图标。 -- `icons.serendipity`：奇遇图标。 +新增查询功能时，建议按当前分层复用现有能力： -例如门派图标常见写法： +1. 根据数据来源选择 `JX3APIService`、`AIJX3Service` 或 `JX3BOXService`。 +2. 在业务服务中新增异步方法，复用 `APIClient`，完成请求、空数据检查、字段整理和标准返回对象构建。 +3. 需要图片输出时新增或复用 `templates/*.html`；不要在业务层直接拼装最终图片消息。 +4. 在 `MessageBuilder` 中增加薄包装方法，选择文本、HTML 图片、远程图片、消息链或会话处理器。 +5. 在 `main.py` 的 `command_map` 注册触发词。 +6. 同步更新 `templates/helps.html`、README 和 CHANGELOG，确保参数顺序以包装方法签名为准。 +7. 如果新增运行时数据，使用参数化 SQL 并在初始化阶段创建表；如果新增敏感配置，同时更新 `_conf_schema.json`。 +8. 至少执行语法检查，并在带有效凭据的 AstrBot 环境中手工验证成功、空数据、上游异常和参数错误路径。 -```jinja2 -{% set icon = icons.sect.get(item.forceName) %} -{% if icon %} -