11

2026-08-03 22:19:32 +08:00
parent 6c26486f49
commit 4b6c86a32b
1 changed files with 409 additions and 401 deletions
@@ -1,503 +1,511 @@
 # astrbot_plugin_jx3
-基于 [AstrBot](https://docs.astrbot.app/) 框架开发的剑网三游戏数据查询插件。插件主要通过 JX3API、JX3BOX、茶馆等外部接口获取游戏数据，整理为文本消息、富媒体消息，或通过 `HTML + Jinja2` 模板渲染成图片后发送。
+<p align="center">
  <img src="logo.png" alt="astrbot_plugin_jx3" width="160">
 </p>
-当前插件以“查询型功能”为主，覆盖日常、官方、角色、职业、休闲、阵营、副本、活动、交易、杂项、排行、推送和本地避雷等场景。部分功能需要配置 JX3API Token，少量职业/角色类接口还需要推栏 ticket。
+<p align="center">
  基于 AstrBot 的剑网三综合数据查询插件
 </p>
-## 功能概览
+`astrbot_plugin_jx3` 通过 JX3API、剑侠茶馆、JX3BOX 等数据源查询《剑网3》游戏数据，并根据功能将结果发送为纯文本、图片、图文消息或两轮交互消息。插件同时提供本地避雷记录和开服、新闻、刷马、赤兔后台推送能力。
-插件内置 `功能` 指令，会以图片形式展示完整指令列表、参数说明和是否需要令牌。当前帮助页按 13 个功能分组维护，约 88 条指令。
+当前仓库版本为 **v3.1**，要求 **AstrBot >= 4.11.0**，元数据声明支持 `aiocqhttp` 与 `weixin_oc` 平台。
-主要功能包括：
+> 本 README 以 v3.1 的 `main.py` 指令映射、`core/message.py` 参数签名和三个数据服务的实际实现为准。当前代码与内置帮助图之间存在少量差异，详见[当前版本状态](#当前版本状态)。
 【活动情报】
 活动日历： 日常 [延后天数] | 日常预测
 声望社：楚天社 | 云从社 | 披风会 | 穹野卫
 关隘首领：关隘
 赤兔：赤兔 | 本周赤兔
 阵营事件：阵营奉献 [阵营]
 烟花记录:：烟花 区服 角色
 马场查询：刷马 | 马场
 【名剑相关】
 名剑战绩：战绩 服务器 角色 [模式]
 名剑排行：名剑排行 [模式] [数量]
 名剑统计：名剑统计 [模式]
 【排行榜单】
 排行统计：名士五十强 服务器 | 老江湖五十强 服务器 | 兵甲藏家五十强 服务器 | 名师五十强 服务器 | 阵营英雄五十强 服务器 | 薪火相传五十强 服务器 | 
 	庐园广记一百强 服务器 | 浩气神兵宝甲五十强 服务器 | 恶人神兵宝甲五十强 服务器 | 浩气爱心帮会五十强 服务器 | 恶人爱心帮会五十强 服务器 |
 	赛季恶人五十强 服务器 | 赛季浩气五十强 服务器 | 上周恶人五十强 服务器 | 上周浩气五十强 服务器 | 本周恶人五十强 服务器 | 本周浩气五十强 服务器
 试炼排行：试炼排行 服务器 心法
 【物价交易】
 阵营拍卖：阵营拍卖 服务器 [物品] [数量]
 的卢拍卖：的卢 服务器 
 金价行情：金价 服务器
 物品价格：物价 外观名称 [服务器]
 成本计算：成本 服务器 物品名称
 编号搜索：看号 万宝楼编号
 【阵营战场】
 帮战记录：帮战 服务器
 阵营沙盘：沙盘 服务器
 诛恶事件：诛恶 服务器
 【角色名片】
 名片缓存：名片 服务器 角色
 名片历史：全名片 服务器 角色
 随机名片：随机秀 服务器 [门派] [体型]
 【奇遇相关】
 奇遇记录：奇遇 服务器 角色 | 查询 服务器 角色
 未触发的：未出 服务器 角色
 奇遇汇总：汇总 服务器 [天数]
 近期奇遇：近期 服务器 [数量]
 奇遇统计：统计 奇遇 [服务器] [数量]
 奇遇攻略：攻略 奇遇
 【百战记录】
 角色百战：精耐 服务器 角色
 百战首领：百战
 【角色信息】
 成就查询：成就 服务器 角色 成就
 角色详情：角色 服务器 名称
 【心法配装】
 阵眼效果：阵眼 心法
 魔盒配装：配装 心法
 资历榜单：资历排行 [服务器] [门派]
 技能信息：技能 心法
 奇穴信息：奇穴 心法
 【游戏社区】
 角色聊天；聊天 服务器 角色 [条数] [页数]
 统战歪歪：统战 [服务器]
 家园鲜花：花价 服务器 [名称] [地图]
 家园装饰：装饰 名称
 器物图谱：器物 地图名称
 师徒列表：拜师 服务器 [关键词] | 收徒 服务器 [关键词]
 维护公告：维护 [数量]
 新闻资讯：新闻 [数量]
 团队招募：招募 服务器 [副本] | 团长 服务器 [名称] | 团牌 服务器 [内容] 
 骚话语录：答案之书 | 舔狗语录 | 疯狂星期四 | 彩虹屁 | 毒鸡汤 | 朋友圈 | 喝什么 | 吃什么 | 骚话 | 渣男语录
 【百度贴吧】
 外观记录：贴吧物价 名称 [服务器] [数量]
 百度贴吧：818 [服务器] [数量]
 【系统工具】
 科举答案：科举 题目 [条数]
 大区状态：区服 | 开服 服务器
 技改记录：技改
 秘境方位：解密
 副本记录：副本 服务器 角色
 掉落统计：掉落 物品 [服务器] [数量]
 【魔盒数据】
 魔盒宏：宏 心法
 资历查询：资历 服务器 角色 
 交易行：交易行 服务器 物品 
 【避雷功能】
 避雷添加：避雷添加 名称 备注
 避雷查看：避雷查看
 避雷查询：避雷查询 名称
 避雷修改：避雷修改 ID 名称 备注
 避雷删除：避雷删除 ID
 【推送功能】
 开服监控：开服监控
 新闻推送：新闻推送
 刷马推送：刷马推送
 赤兔推送：赤兔推送
 ## 功能特点
-## 安装与依赖
+- 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 请求。
+```bash
- `aiofiles`：异步文件处理。
+pip install -r data/plugins/astrbot_plugin_jx3/requirements.txt
- `aiosqlite`：本地 SQLite 数据库。
+```
 - `apscheduler`：后台推送任务调度。
 - `matplotlib`：部分图像/数据展示依赖。
-插件元信息在 `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`：是否启用指令前缀检查。
 - `text`：指令前缀内容，默认 `剑三`。
 启用后，用户需要发送类似 `剑三 日常`、`剑三 奇遇 角色名` 才能触发。关闭后可直接发送 `日常`、`奇遇 角色名`。
 ### 默认服务器
 ```json
 {
  "server": "梦江南"
 }
 ```
 许多指令都带有 `[服务器]` 可选参数。用户未填写服务器时，插件会使用这里配置的默认服务器。
 示例：
 ```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` 等方式获取。推送本质是后台定时请求接口，检测状态变化后向配置的会话发送消息，不建议将轮询间隔设置得过短。
+- `enable`：是否在插件初始化时创建该任务。
 - `time`：轮询周期，单位为秒。
 - `umos`：接收推送的 AstrBot 会话唯一 ID 列表，可通过 AstrBot 的 `/std` 等方式获取。
 推送配置在插件初始化时读取。修改配置后应重新加载插件；`开服推送` 等查询指令只显示任务状态，不会动态开启或关闭任务。
 ### Token 与 Ticket
 JX3API Token 可从 [JX3API](https://www.jx3api.com/) 获取。推栏 Ticket 通常来自推栏客户端的登录请求，属于敏感凭据。
 当前代码会同时传入 Token 和 Ticket 的指令有：
 - `战绩`、`名剑排行`、`名剑统计`
 - `阵眼`、`资历排行`、`技能`、`奇穴`
 其余在下方标记为“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 插件入口，初始化配置、资源、服务和指令分发
+| `阵营拍卖 服务器 [物品] [数量]` | 阵营拍卖记录，默认最多 50 条；图片 | Token |
-├─ metadata.yaml            # 插件元信息
+| `的卢 服务器` | 的卢拍卖记录；图片 | Token |
-├─ _conf_schema.json        # AstrBot 后台配置 schema
+| `金价 服务器 [数量]` | 金价行情，默认 15 条；图片 | Token |
-├─ requirements.txt         # Python 依赖
+| `物价 外观名称 [服务器]` | 外观价格记录；图片 | Token |
-├─ data/
+| `成本 服务器 物品名称 [来源]` | 制造成本，来源默认 `0`；图片 | Token |
-│  ├─ api_config.json       # 外部接口配置，按功能 key 维护 URL、method、默认参数
+| `看号 万宝楼编号` | 万宝楼账号详情；文本 | Token |
-│  └─ plugin_data.db        # 插件随包数据，主要用于内置数据
+| `交易行 服务器 物品` | 本地模糊匹配物品后批量查询 JX3BOX 交易行价格；图片 | 无 |
-├─ core/
+
-│  ├─ jx3_data.py           # 业务数据层，调用接口、整理数据、选择模板
+`交易行` 会按“完全匹配、前缀匹配、包含匹配”排序，最多取 50 个物品 ID。基础物品分组会缓存 30 天；价格结果展示物品图标、砖/金/银/铜价格、样本数量和数据时间。
-│  ├─ message.py            # 消息构建层，负责文本、图片、富媒体回复
+
-│  ├─ request.py            # aiohttp 请求封装，统一处理 GET/POST 和接口返回
+### 阵营战场
-│  ├─ async_task.py         # APScheduler 后台推送任务
+
-│  ├─ bilei_data.py         # 本地避雷数据增删改查
+| 指令 | 说明与输出 | 凭据 |
-│  ├─ sqlite.py             # SQLite 异步封装
+| --- | --- | --- |
-│  └─ fun_basic.py          # 模板加载、图片 base64、通用格式化工具
+| `帮战 服务器` | 帮战记录；图片 | 无 |
-└─ templates/
+| `沙盘 [服务器]` | 从剑侠茶馆获取沙盘图片 URL 并直接发送 | 无 |
-   ├─ helps.html            # 功能帮助页
+| `诛恶 服务器` | 诛恶事件，固定最多 20 条；图片 | Token |
-   ├─ *.html                # 各图片指令的 HTML/Jinja2 模板
+
-   ├─ img/                  # 通用图片资源
+### 角色名片与奇遇
-   ├─ sect/                 # 门派/心法图标
+
-   └─ serendipity/          # 奇遇图标
+| 指令 | 说明与输出 | 凭据 |
 | --- | --- | --- |
 | `名片 服务器 角色` | 缓存名片，发送文字与角色图片 | 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 和推送配置。
+- `bilei`：避雷记录。
-2. 计算本地数据目录、插件数据目录、模板目录和接口配置文件路径。
+- `tuishong`：四类推送的最新状态，固定使用 `id=1` 的单行记录。
-3. 加载 `templates/img`、`templates/sect`、`templates/serendipity` 中的图片，并转为 base64，供 HTML 模板直接引用。
+- `achievement_cache`：JSON 基础数据缓存及更新时间。
-4. 初始化 SQLite、JX3Service、AsyncTask、BiLeidata、MessageBuilder。
+
-5. 在异步初始化阶段创建本地表，并启动后台推送任务。
+随后连接随包的 `plugin_data.db`、启动已配置的后台任务，最后建立指令映射。插件停用时会关闭调度器、三个 HTTP Session 和两个 SQLite 连接。
 6. 构建 `command_map`，将中文触发词映射到对应的消息处理函数。
 ### 2. 指令分发
-用户消息进入插件后，`main.py` 会：
+入口监听全部消息事件：
-1. 根据配置判断是否需要指令前缀。
+1. `parse_message()` 检查前缀并使用 `str.split()` 切分消息。
-2. 将消息按空格切分为 `指令 + 参数`。
+2. 第一段作为指令，其余段作为位置参数。
-3. 在 `command_map` 中查找对应处理函数。
+3. `command_map` 将中文触发词映射到 `MessageBuilder` 方法。
-4. 使用 `inspect.signature` 根据函数参数数量自动传入用户参数。
+4. `_call_with_auto_args()` 通过 `inspect.signature()` 读取参数签名，按注解转换 `int` 和 `float`。
-5. 找不到指令时不处理，参数错误时返回提示。
+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`。
+- 延迟创建并复用一个 `aiohttp.ClientSession`。
- 支持 GET 和 POST。
+- 默认总超时时间为 10 秒。
- 自动识别 JSON、图片或二进制响应。
+- 支持 GET、JSON POST 和分页拉取。
- 对 JX3API 常见返回结构做基础校验。
+- 根据 `Content-Type` 自动返回 JSON 或二进制数据。
- 支持通过 `out_key` 抽取返回对象中的指定字段，默认通常取 `data`。
+- 兼容 JX3API 常见成功码 `200`、`"0"`、`0`、`1`。
 - 可通过 `out_key` 提取响应中的指定字段。
 - 网络、HTTP、JSON 和业务码异常统一记录日志并返回 `None`。
-`JX3Service._base_request()` 会在业务层进一步统一：
+### 5. 消息与图片渲染
- 根据 `data/api_config.json` 查找接口。
+`core/message.py` 根据业务结果选择输出方式：
 - 合并接口默认参数和运行时参数。
 - 根据配置 method 调用 GET 或 POST。
 - 捕获异常并输出日志。
-### 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 整理数据
+astrbot_plugin_jx3/
-        ↓
+├── main.py                  # 插件入口、生命周期、数据库建表和指令分发
-MessageBuilder.T2I_image_msg()
+├── metadata.yaml            # 插件名称、版本、平台和 AstrBot 版本要求
-        ↓
+├── _conf_schema.json        # AstrBot 管理面板配置结构
-注入 icons
+├── requirements.txt         # Python 依赖
-        ↓
+├── CHANGELOG.md             # 版本更新记录
-html_renderer.render_custom_template()
+├── 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 %}
+```bash
-<img src="{{ icon }}">
+python -m compileall -q .
 {% endif %}
 ```
-### 7. 本地数据库
+仓库当前没有自动化测试套件，`compileall` 只能检查 Python 语法，不能替代真实 AstrBot 消息、HTML 渲染和外部接口联调。
-插件使用两个 SQLite 数据库：
+## 当前版本状态
- 插件目录下的 `data/plugin_data.db`：随插件提供的内置数据。
+以下内容是对 v3.1 当前源码的静态核对结果，部署和二次开发前应注意：
 - AstrBot 数据目录中的 `local_data.db`：运行期本地数据。
-本地数据主要用于：
+1. `command_map` 实际注册 108 个触发词；`templates/helps.html` 标注 105 条，并遗漏 `功能`、`小药`、`骗子`、`开服推送`。帮助图中的 `开服监控` 不是当前有效触发词。
-
+2. 默认服务器配置会用于四类后台任务，并只在 `烟花` 查询中通过 `serverdefault()` 显式补齐；其他可选服务器参数会原样传为空字符串。
- 避雷记录。
+3. `JX3BOXService._get_achievement_base_data()` 当前调用了该类中未定义的 `_base_request()`，因此 `资历` 在用户选择分类后无法完成基础数据加载。
- 推送任务状态缓存。
+4. 刷马和赤兔后台任务当前调用了 `JX3APIService` 中不存在的 `shuamamsg()`，启用 `smts` 或 `ctts` 后，定时回调会记录执行异常。
- 资历菜单与资历点数基础数据缓存，默认缓存 30 天，接口失败时可使用旧缓存兜底。
+5. `main.py` 仍计算 `data/jx3api_config.json` 路径，但仓库没有该文件，当前三个服务也不从该路径读取接口配置；接口地址直接维护在服务代码中。
- 交易行物品库基础数据缓存，默认缓存 30 天，接口失败时可使用旧缓存兜底。
+6. `APIClient` 当前默认 `ssl_verify=False`，即外部 HTTPS 请求不校验证书。对传输安全有要求的部署应先评估并调整该设置。
-
+7. JX3API 服务初始化时会把 Token 和 Ticket 写入 debug 日志。不要公开调试日志，建议二次开发时移除敏感值输出。
 `core/sqlite.py` 封装了异步增删改查；`core/bilei_data.py` 基于该封装实现避雷数据管理。
 ### 8. 资历查询
 `资历 角色名称 [服务器]` 是 2.6 新增的两轮对话功能。
 第一轮会发送固定分类菜单，用户输入 `0-18` 后进入第二轮：
 - `0`：展示角色资历总览，并列出 18 个大类的完成进度。
 - `1-18`：展示对应大类总览，并列出该大类下所有子类的完成进度。
 实现流程：
 1. 通过角色信息接口 `jx3_jueshexinxi` 获取角色 `globalId`。
 2. 用 `globalId` 请求 JX3BOX 角色资历接口，获取已完成资历 ID 列表。
 3. 从资历菜单接口和资历点数接口读取基础数据，并缓存到本地 SQLite。
 4. 展开菜单中单个 ID 和数组 ID，按资历点数计算 `已完成点数 / 总点数` 与百分比。
 5. 使用 `templates/zili.html` 渲染进度条图片。
 ### 9. 交易行查询
 `交易行 物品名称 [服务器]` 在 2.7 中完成重构，属于交易功能，免令牌，输出为图片。
 实现流程：
 1. 从 JX3BOX 交易行物品库接口读取所有可查询物品，并缓存到本地 SQLite。
 2. 用户输入物品名后，在本地物品库中按名称进行模糊匹配。
 3. 匹配结果按“完全匹配、前缀匹配、包含匹配”排序，默认最多取前 50 个物品 ID。
 4. 调用 `https://next2.jx3box.com/api/auction/` 批量查询指定服务器的交易行价格。
 5. 价格接口未返回的物品不展示；全部无价格数据时直接返回文本提示。
 6. 使用 `templates/jiaoyihang.html` 渲染列表图片，展示物品图标、物品名称、价格、数量和数据时间。
 价格单位按铜钱换算为砖、金、银、铜，并使用 `templates/img` 下的 `zhuang.png`、`jin.png`、`yin.png`、`tong.png` 图标展示；0 砖不会显示砖图标。
 ### 10. 后台推送
 `core/async_task.py` 使用 APScheduler 实现轮询推送。
 当前支持：
 - 开服监控。
 - 新闻资讯。
 - 刷马消息。
 - 赤兔消息。
 推送逻辑是：
 1. 初始化时读取配置和本地旧状态。
 2. 对启用且配置了推送目标的任务创建 interval job。
 3. 定时调用对应业务方法。
 4. 比较新旧状态。
 5. 状态变化时向配置会话发送消息，并更新本地状态。
 ## 新增功能开发流程
 新增一个查询功能通常需要改动 4 到 5 个位置：
 1. 在 `data/api_config.json` 添加接口配置。
 2. 在 `core/jx3_data.py` 添加业务方法，完成请求、数据整理和错误处理。
 3. 在 `core/message.py` 添加消息包装方法，选择文本、图片或富媒体输出。
 4. 在 `main.py` 的 `command_map` 注册中文触发指令。
 5. 如果是图片输出，新增 `templates/xxx.html`。
 6. 在 `templates/helps.html` 增加帮助卡片并更新统计。
 建议保持以下约定：
 - 方法名使用拼音或稳定英文名，避免与现有方法冲突。
 - 接口配置 key 使用 `jx3_功能名` 形式。
 - 文本功能失败时返回清晰的 `msg`。
 - 图片功能返回空数据时不要渲染空图，直接返回文本提示。
 - 可选服务器统一通过 `MessageBuilder.serverdefault()` 处理。
 - 时间戳尽量在业务层格式化后传给模板。
 ## 注意事项
- 本插件依赖多个外部接口，接口变更、网络异常、Token 权限不足都会影响结果。
+- Token、Ticket 和会话唯一 ID 都可能属于敏感信息，不要提交到仓库、粘贴到 Issue 或输出到公开日志。
- JX3API 数据源可能存在延迟或遗漏，奇遇、掉落、排行榜等数据不保证 100% 完整。
+- 不要将推送间隔设置得过短，以免触发上游限流或给目标会话造成刷屏。
- Token 与 Ticket 属于敏感配置，不要提交到仓库或公开日志。
+- 奇遇、排行、掉落、贴吧等数据来自第三方聚合接口，不保证实时、完整或永久可用。
- 后台推送会持续请求接口，轮询间隔不要设置过短。
+- 部分返回正文会直接交给 AstrBot HTML 渲染器；上游格式变化可能导致截图布局异常。
- HTML 模板渲染依赖 AstrBot 的文转图能力，运行环境需要支持对应渲染服务。
+- 本地避雷数据位于 AstrBot 插件数据目录，升级或迁移前应备份 `local_data.db`。
 ## License
-本项目遵循仓库内 `LICENSE` 文件声明的许可协议。
+本项目基于 [GNU Affero General Public License v3.0](LICENSE) 开源。