## 更新记录

### version: 3.4.6（2026-09-06）：

本地避雷记录新增按 AstrBot 会话隔离的数据范围。新增、查看、查询、修改和删除均使用当前消息的 `unified_msg_origin`，修改与删除同时校验会话 ID 和记录 ID，其他会话即使知道记录 ID 也无法访问或操作。

插件升级时会自动迁移旧版 `bilei` 表，原有记录完整保留在不可由普通会话访问的“历史公共数据”区；新安装直接创建包含会话 ID 的表结构，并为会话内查询建立联合索引。

插件 WebUI 新增“避雷迁移”页签，集中展示历史公共数据区中的旧记录。管理员可为每条记录选择已有会话或直接输入目标会话 ID；迁移采用带历史区条件的原子更新，完成后记录立即离开待迁移列表并仅归属于目标会话。

功能帮助图片将“插件与推送”调整为第一个功能分区，其余分区序号依次后移，避雷功能仍保留在最后。

功能帮助底部的会话区服说明移动到顶部，并补充方括号参数可省略且使用默认值的规则；所有“服务器”和“区服”参数统一移除方括号，其他可选参数标记保持不变。

优化烟花、跨服名剑和武林争霸的可选参数：烟花条数为非正整数或无法解析时自动回退 50；跨服名剑改用 `22`、`33`、`55` 并映射接口值 `0`、`1`、`2`；武林争霸改用 `浩气盟`、`恶人谷` 并映射接口值 `1`、`2`。三项无效输入均使用默认值，不再返回参数范围错误。

调整指令前缀容错：开启前缀检查但前缀内容为空或只有空格时，自动按未开启前缀处理并记录警告，普通指令仍可直接触发；仅在前缀内容非空时强制匹配。

新增查询双层缓存：JX3API 原始 JSON 采用内存与 SQLite 两级缓存，缓存键排除 Token、Ticket 等敏感值并使用凭据摘要隔离；同参数并发请求会合并为一次上游调用，请求失败时可使用七天内的过期数据兜底。HTML 渲染图片保存到插件数据目录；普通图片指令会先按指令、完整参数、选择项、会话数据范围、资源和渲染配置查询最终图片，命中后直接发送，不再请求上游接口或重复渲染。图文结果会连同正文一起缓存，同键并发执行也只会产生一次请求和渲染。

插件 WebUI 新增“缓存管理”页签，可分别设置接口数据和各图片指令的默认缓存秒数，也可逐项覆盖、恢复默认或单独清除；设置为 `0` 即关闭对应缓存。单独清除接口时会同步删除该路径的内存与 SQLite 缓存，单独清除图片时会删除该指令生成的缓存文件，均不改变已配置的缓存时间。页面同时展示缓存条数、占用空间，并支持分别清空全部接口和图片缓存。接口内存缓存条数与图片缓存总容量均可在页面调整，默认分别为 256 条和 512 MB，保存后立即按最少使用优先策略清理超额缓存；随机内容接口以及会话避雷图片采用 0 秒安全默认值，仍可显式覆盖。

所有 HTML 渲染图片统一在页面底部显示“数据时间”。JX3API 数据优先显示接口缓存最初写入时间，非接口页面显示本次数据生成时间；命中最终图片缓存时保留原图片时间，便于直接判断当前图片所展示数据的新鲜程度。旧版最终图片缓存键同步升级，避免继续复用不含时间栏的历史图片。

### version: 3.4.5（2026-09-05）：

新增 `跨服名剑 服务器 [模式]` 指令，接入 JX3API 跨服名剑榜；竞技模式支持 `0=2v2`、`1=3v3`、`2=5v5`，默认为 `1`。榜单按接口数组顺序生成排名，使用统一数据表格模板展示队伍名称、积分、胜场、败场和总场数，并同步更新功能帮助与 README。

新增 `武林争霸 服务器 [阵营]` 指令，接入 JX3API 武林争霸赛帮会榜；阵营支持 `1=浩气`、`2=恶人`，默认为 `1`。榜单按接口数组顺序生成排名，使用统一数据表格模板展示帮会、帮主、所属服务器、阵营、胜负场、积分和最后比赛时间。

新增 `捕快荣誉 服务器` 和 `江湖浪客 服务器` 指令，分别接入 JX3API `/rank/constable` 与 `/rank/outlaw`。两个榜单复用同一数据处理流程和统一表格模板，按接口数组顺序生成排名，展示角色、帮会、门派、阵营和抓捕数；江湖浪客榜额外展示敌对数。

新增 `决斗挑战 服务器 [模式]` 指令，接入 JX3API `/rank/wanted`；模式支持 `1=公开`、`2=私密`，默认为 `1`。榜单按接口数组顺序生成排名，展示被悬赏角色、门派、赏金、剩余时间和发起人，并将 `timeOut` 结束时间戳转换为动态剩余时长。

统一图片列表中的阵营列：浩气盟、恶人谷和中立改为显示 `templates/img` 内对应图标，不再显示阵营文本；空值或未识别阵营使用“未知”图标兜底。

### version: 3.4.4（2026-09-05）：

烟花查询在角色名称后新增可选的“条数”参数，默认展示前 50 条，支持指定正整数条数；沿用已绑定会话省略服务器的用法，并同步更新功能帮助和 README。上游接口未提供条数参数，查询结果在本地截取后生成图片。

修复绑定区服后，省略服务器并填写后续可选参数时被误判为显式服务器的问题；例如 `战绩 晏卿卿 22` 现在会正确补齐绑定区服，并按角色“晏卿卿”、模式“22”查询。

修复名剑战绩模板固定读取 `performance['3v3']`，导致 `22` 和 `55` 模式渲染失败的问题；现在会按查询模式分别使用 `2v2`、`3v3`、`5v5` 表现数据。

名剑战绩的对战记录按胜负统一整行文本颜色，胜利显示绿色，失败显示红色。

名剑排行榜的门派列复用名剑统计的图标样式，在门派名称前显示对应门派图标。

心法别名接入全局指令参数解析：试炼排行、阵眼、配装、技能、奇穴、小药和宏会在调用业务接口前将标准名称或别名统一转换为标准心法名；WebUI 保存或恢复别名后会立即刷新解析缓存，门派筛选参数保持原义。

### version: 3.4.3（2026-09-05）：

接入 JX3API `POST /token/stats` 令牌统计接口，使用插件配置的 `jx3api_token` 查询等级、已用次数、剩余次数和有效状态；WebUI 顶部恢复为四项令牌统计，接口不可用或未配置令牌时显示未获取状态且不影响其他管理数据。

重构功能帮助图片：由不规则卡片区块改为统一的“功能分区 + 指令列表 + 说明”三列结构，每条指令行预留默认空白的说明区域，并整体放大分区、功能名、指令及辅助文字；按照当前 `command_map` 校正 18 个分区和 92 个真实触发词，角色记录指令由“聊天”更新为“发言”，同时补入“小药”“骗子”并移除未注册的“副本”指令。

新增基于 WebUI 与 SQLite 的“会话控制”：默认使用“全部会话”模式，也可切换为白名单或黑名单，并维护任意 AstrBot 会话 ID 及备注。访问策略同时作用于插件指令与实时事件推送；空白名单不放行任何会话，空黑名单放行全部会话。

整理 WebUI 后端结构：新增独立的 `core/webui.py` 服务，统一负责管理页路由注册、Dashboard 数据聚合、请求校验和保存、删除、恢复接口；`main.py` 仅保留服务构造与注册调用，现有 Web API 路径和前端调用协议不变。

插件 WebUI 的区服别名和心法别名页新增“恢复默认”操作；采用页面内可见的二次点击确认，不依赖嵌入页面可能无法显示的浏览器原生确认框。确认后分别读取随插件分发的 `data/server_aliases.json` 和 `data/kungfu.json`，在事务中完整重写对应数据库表并刷新页面数据。

移除 WebUI 原有的会话绑定和事件推送数量统计，顶部区域改为显示 JX3API 令牌等级、已用次数、剩余次数和有效状态；“会话控制”移动为第一个默认页签，并新增醒目的当前生效模式状态。模式卡片明确区分当前模式与尚未保存的选择，切换按钮同步显示目标模式。“会话绑定”更名为“区服绑定”并保留在“事件推送”之后。

重构 WebUI 区服绑定交互：顶部入口改为“添加绑定”，会话 ID 可自定义但绑定区服只能从标准区服下拉框选择；列表编辑时会话 ID 保持只读，仅在对应绑定区服列内切换下拉框进行保存，解除绑定改为点击后直接删除对应记录。Web API 同步拒绝别名及任意文本作为绑定区服。

### version: 3.4.2（2026-09-04）：

图片模板整体调整为浅色背景、深色高对比文本和更大的字号，缩小内容与金色边框之间的留白并扩大主体区域；同步检查并调整多个独立页面的字号、间距及表格布局，提高长图阅读体验。

插件配置页新增“图片渲染质量”分组，可选择 `1.0`、`1.3`、`1.8` 三档渲染清晰度以及 JPEG/PNG 输出格式，并可设置 JPEG 质量；默认使用 `1.3` 倍设备像素比和 JPEG 质量 `100`。

将 17 个独立排行榜指令合并为 `帮会排行`、`阵营排行`、`其他排行` 三个两轮会话入口；首轮按分类展示固定序号菜单，第二轮复用排行榜图片流程输出所选榜单，并统一只保留接口数据的前 50 条。

修复两轮会话已经取得有效选择后等待计时器仍继续运行，导致耗时查询或图片渲染期间触发超时分支并重复输出第二张图片的问题。

修复 aiocqhttp 已成功发送图片但返回 `retcode=1200` 超时回执时，插件继续补发“猪脑过载”错误提示的问题；该回执现在只记录警告。

优化插件 WebUI 的别名管理：区服页展示全部标准区服并移除删除操作，心法页隐藏不可修改的配装 ID；标准区服名和标准心法名均保持只读，点击“编辑”后直接在对应别名单元格内修改并保存。

### version: 3.4.1（2026-09-04）：

带区服参数的查询新增 `全区` 保留值；即使当前会话已绑定区服，也会向接口传入空区服以查询全区数据。

资历分布由 JX3BOX 重构为 JX3API `/tuilan/achievement` 实时查询，使用固定的总览及 18 个大类菜单；模板直接读取角色信息、`data.total`、`pieces`、`seniority` 与 `score/totalScore`，并分别兼容总览的“大类 → 小类 → 统计”和指定分类的“小类 → 统计”返回结构。

重构通用两轮会话处理器：首轮函数直接返回 `{"1": "总览", "2": "杂闻"}` 形式的裸键值对，由处理器生成序号文本；用户选择或 10 秒超时后，将所选项裁剪成单项字典交给次轮函数。资历和宏查询均已接入，宏结果统一复用富媒体消息链发送文本及 HTML 渲染附图。

移除 JX3BOX 资历菜单、点数和角色成就拼装逻辑及其本地缓存；旧 `achievement_cache` 仅迁移交易行物品分组后删除，交易行缓存独立保存到 `trade_item_cache`。

提高插件指令监听优先级；确认消息属于本插件指令后立即停止后续事件传播，避免重复触发其他插件或默认 LLM 回复。

补齐 JX3API 当前 39 种 WebSocket 事件处理，付费事件不再回退输出原始 JSON；新增缺失的扶摇预告、烟花报时、阵营祭天预告及帮会野外宣战事件，并按官方字段生成可读中文消息。

统一查询图片和插件 WebUI 的表格样式：表头、内容及图标文字组合水平和垂直居中，移除固定列宽并按内容自动分配；合并跨页面可复用的表格、卡片、状态和布局规则，清理重复或失效的页面 CSS。

### version: 3.4.0：

移除插件级默认区服，新增按 AstrBot 会话保存的区服绑定。已绑定会话可省略查询指令中的区服参数，完整填写区服时仍优先查询指定区服。

新增区服别名配置，一个标准区服可以对应多个别名；别名可用于会话绑定和查询指令。

新增 `data/server_aliases.json` 区服别名种子，插件启动时幂等写入本地数据库，已有区服别名配置不会被覆盖。

事件正文含服务器时按每个目标会话的绑定区服分别过滤；未绑定会话继续接收全部服务器的已订阅事件。

新增 AstrBot 插件 WebUI 管理页，可管理会话区服绑定和区服别名，并查看所有会话的事件总开关及订阅事件。

新增心法别名 WebUI，可维护 JX3BOX 配装 ID、标准心法名及最多 5 个别名。

移除随包 SQLite `data/plugin_data.db`，原有 32 条心法数据改为 JSON 种子并在启动时幂等写入本地 `local_data.db`，心法查询和配置统一使用本地数据库。

### version: 3.3.1：

沙盘功能改用 JX3API `/sand/records` 据点数据接口，并使用随插件分发的沙盘底图、阵营领地图层和据点图标在本地渲染完整图片。

移除仅用于旧剑侠茶馆沙盘图片接口的 `AIJX3Service`，沙盘命令现在支持缺省使用插件配置的默认服务器。

### version: 3.3.0：

移除开服、新闻、刷马、赤兔四类定时轮询推送及 APScheduler 依赖。

新增 JX3API WebSocket 实时事件通道，支持心跳保活、断线重连和按事件编号分发。

新增按 AstrBot 会话保存的事件订阅表，总开关与每个事件开关独立存储；免费事件 2001 至 2006 可直接订阅。

### version: 3.2.3：

API区服接口功能调整，做对应调整

### version: 3.2.2：

调整部分功能指令的描述

### version: 3.2.1：

统一封装 JX3BOX Node、Next2 和 CMS 三类接口请求，集中处理基础地址、GET/POST、请求参数、返回字段提取与异常日志。

修复资历菜单和点数缓存的刷新链路，缓存过期后分别请求 `/api/node/achievement/menus` 与 `/api/node/achievement/points`，上游失败时继续使用旧缓存。

刷马与赤兔后台推送改用 JX3BOX Next2 马场消息接口，并向后台任务管理器注入 `JX3BOXService`。

配装查询开始实际传递类型筛选参数。

新增项目级 `.gitignore`，忽略 Python 缓存、虚拟环境、日志、临时文件及整个 `tests/` 目录。

同步更新 README、插件注册信息和元数据版本号。

### version: 3.1：

增加副本记录查询功能。

重构 46 个 HTML 图片模板：公共文档骨架、设计变量、基础样式和组件样式统一维护，页面仅保留内容与独有布局；渲染前在本地组合为完整 HTML 字符串。

进一步组件化列表和卡片页面：表格、排行、技能/奇穴、奇遇网格、区服状态、器物详情等改为复用公共 CSS；页面专属 CSS 从 46 个减少至 13 个。模板通过元数据声明组件，加载器从单一组件样式表中选择性注入所需样式，并支持无同名 CSS 的标准页面及共享资源缓存。

重新整理功能帮助页，按 17 个分类展示 69 项功能和 105 条指令，并按固定图片画布优化三列排版。

### version: 3.0：

大部分功能重写，还有部分未写完。

### version: 2.7：

重构 **交易行 物品名称 [服务器]** 指令，改为免令牌图片查询。

新增 JX3BOX 交易行物品库缓存，用户输入物品名后先在本地模糊匹配物品 ID，再批量请求交易行价格接口。

交易行结果图改为列表展示，包含物品图标与名称、砖金银铜图标化价格、数量和数据时间。

价格接口未返回的物品不再展示，全部无价格数据时返回明确提示。

### version: 2.6：

新增 **资历 角色名称 [服务器]** 指令，支持两轮对话选择资历总览或分类总览，并以图片形式展示角色资历点数完成进度。

新增资历菜单与点数基础数据缓存，减少长期稳定接口的重复请求。

调整功能帮助页分类，指令分组改为日常、官方、角色、职业、休闲、阵营、副本、活动、交易、杂项、排行、推送和避雷。

调整指令触发词：**诛恶事件** 改为 **诛恶**，**排行** 改为 **名剑排行**。

### version: 2.5：

增加部分新指令，调整功能页面

### version: 2.4：

增加大量新指令

### version: 2.3：

宏查询接口调整，恢复使用

### version: 2.2：

接口地址调整,增加部分功能

### version: 2.1：

接口地址调整

### version: 2.0：

接口地址调整

### version: 1.2.4：

角色信息查询数据展示优化

角色名片查询功能优化

### version: 1.2.3：

查询个人奇遇的指令名称调整为 **查询**

新增角色基本信息查询功能 **角色 名称 [服务器]**

### version: 1.2.2：

调整角色名片查询功能。

### version: 1.2.1：

调整角色名片查询功能。

### version: 1.2.0：

部分HTML渲染图片功能优化，增加本地图片加载功能。

### version: 1.1.1：

图片渲染参数优化。

### version: 1.1.0：

部分代码功能重写。

### version: 1.0.0：

大部分重要功能已经实现