fxdyz

README.md

@@ -13,7 +13,7 @@
 
 ## 功能特点
 
-- 中文触发词覆盖活动、名剑、排行、交易、阵营、角色、奇遇、副本、家园、社区等场景。
+- 中文触发词覆盖活动、名剑、排行、交易、阵营、角色、奇遇、百战、家园、社区等场景。
 - 支持纯文本、远程图片、HTML/Jinja2 渲染图片和图文消息链。
 - 支持 `宏`、`资历` 以及帮会、阵营、其他排行榜的 10 秒两轮交互，超时默认选择第一项。
 - 查询图片统一使用浅色高对比主题，并可在插件配置页调整渲染清晰度、输出格式和 JPEG 质量。
@@ -231,7 +231,7 @@ JX3API Token 可从 [JX3API](https://www.jx3api.com/) 获取。推栏 Ticket 通
 
 | 指令 | 说明与输出 | 凭据 |
 | --- | --- | --- |
-| `聊天 服务器 角色 [条数] [页数]` | 角色聊天记录，默认 20 条、第 1 页；图片 | Token |
+| `发言 服务器 角色 [条数] [页数]` | 角色发言记录，默认 20 条、第 1 页；图片 | Token |
 | `统战 [服务器]` | 统战频道统计；文本 | 无 |
 | `小药 [心法]` | 小吃小药推荐；图片 | 无 |
 | `骗子 UID [服务器]` | 查询欺诈记录；文本 | Token |
@@ -274,7 +274,7 @@ JX3API Token 可从 [JX3API](https://www.jx3api.com/) 获取。推栏 Ticket 通
 | `避雷修改 ID 名称 备注` | 按 ID 更新记录，同时覆盖修改时间和修改人 |
 | `避雷删除 ID` | 按 ID 删除记录 |
 
-避雷功能没有内置权限校验。只要能够触发插件指令，当前实现就允许新增、修改和删除记录；公开群聊部署时应在 AstrBot 或消息平台层配置访问控制。
+避雷功能没有会话内的用户角色校验。在“会话控制”放行的会话中，只要能够触发插件指令，当前实现就允许新增、修改和删除记录；如需限制到指定管理员，仍应在 AstrBot 或消息平台层配置权限。
 
 ### 实时事件推送
 
@@ -291,7 +291,9 @@ JX3API Token 可从 [JX3API](https://www.jx3api.com/) 获取。推栏 Ticket 通
 
 ### WebUI 插件管理
 
-AstrBot 插件详情页中的“剑网三插件管理”页面提供四个页签：会话绑定、事件订阅、区服别名和心法别名。页面可以新增、修改或解除任意会话绑定，查看所有会话的事件总开关及订阅编号。区服别名页展示完整标准区服目录，标准名称只读，只能行内编辑别名；心法别名页隐藏 JX3BOX 配装 ID，标准心法名称只读，同样只允许行内编辑最多 5 个别名。管理页通过 AstrBot Plugin Pages 桥接调用插件 Web API，不直接访问 Dashboard 凭据。
+AstrBot 插件详情页中的“剑网三插件管理”页面提供五个页签：会话控制、事件推送、区服绑定、区服别名和心法别名，不再显示顶部统计区域。会话控制为默认页签，页面会明确标出当前真正生效的模式，并区分尚未保存的模式选择。该功能默认使用“全部会话”，也可切换为白名单或黑名单；会话 ID 可从已有绑定和订阅记录中选择，也可直接输入，并可维护名单类型和备注。空白名单不放行任何会话，空黑名单放行全部会话，名单策略同时作用于插件指令和实时事件推送。
+
+区服绑定页可使用自定义会话 ID 添加记录，绑定区服只能从标准区服下拉框选择。编辑已有记录时会话 ID 保持只读，只在绑定区服列内修改，点击解除绑定会直接删除该行。事件推送页显示所有会话的总开关及订阅编号。区服别名页展示完整标准区服目录，标准名称只读，只能行内编辑别名；心法别名页隐藏 JX3BOX 配装 ID，标准心法名称只读，同样只允许行内编辑最多 5 个别名。两个别名页均可使用随插件分发的 JSON 种子完整覆盖数据库并恢复默认配置。管理页通过 AstrBot Plugin Pages 桥接调用插件 Web API，不直接访问 Dashboard 凭据。
 
 ## 业务流程
 
@@ -299,7 +301,9 @@ AstrBot 插件详情页中的“剑网三插件管理”页面提供四个页签
 flowchart LR
     A["AstrBot 消息事件"] --> B["前缀检查与空白切分"]
     B --> C["command_map 查找处理器"]
-    C --> D["MessageBuilder 参数适配"]
+    C --> K{"会话控制是否放行"}
+    K -->|是| D["MessageBuilder 参数适配"]
+    K -->|否| X["停止处理"]
     D --> E1["JX3APIService"]
     D --> E2["JX3BOXService"]
     D --> E3["BiLeidata / EventPushService / KungfuAliasService"]
@@ -322,13 +326,15 @@ flowchart LR
 1. 读取前缀、Token、Ticket 和 WebSocket 配置。
 2. 计算插件目录、AstrBot 数据目录、本地 SQLite 和模板目录路径。
 3. 把 `templates/img`、`templates/img/sand`、`templates/sect`、`templates/serendipity` 中的图片读取为 base64 Data URL。
-4. 创建本地数据库、两个数据服务、心法别名服务、避雷服务、事件推送服务和消息构建器。
+4. 创建本地数据库、两个数据服务、心法别名服务、会话控制服务、避雷服务、事件推送服务、WebUI 服务和消息构建器。
 
 异步初始化阶段会连接数据库并创建以下本地表：
 
 - `bilei`：避雷记录。
 - `event_push_subscriptions`：按 AstrBot 会话保存事件总开关和每个事件编号的订阅开关。
 - `session_server_bindings`：两列结构，保存会话 ID 与绑定区服。
+- `session_control_settings`：保存当前会话控制模式，首次初始化默认为 `all`。
+- `session_control_entries`：保存白名单或黑名单会话 ID 及备注。
 - `server_aliases`：保存标准区服名及其 JSON 别名列表。
 - `kungfu`：保存 JX3BOX 配装 ID、标准心法名及最多 5 个别名。
 - `trade_item_cache`：JX3BOX 交易行基础物品数据缓存及更新时间。
@@ -431,7 +437,7 @@ AstrBot 的渲染接口接收完整 HTML 字符串，因此插件不会依赖渲
 
 | 文件 | 生命周期 | 内容 |
 | --- | --- | --- |
-| AstrBot 插件数据目录下的 `local_data.db` | 运行时创建和维护 | 心法与别名、避雷记录、会话区服绑定、区服别名、事件订阅及基础数据缓存 |
+| AstrBot 插件数据目录下的 `local_data.db` | 运行时创建和维护 | 心法与别名、避雷记录、会话控制、会话区服绑定、区服别名、事件订阅及基础数据缓存 |
 | `data/kungfu.json` | 随插件分发，只在初始化时读取 | 32 条默认心法、别名和 JX3BOX 配装 ID |
 | `data/server_aliases.json` | 随插件分发，只在初始化时读取 | 默认标准区服及其别名 |
 
@@ -441,7 +447,7 @@ AstrBot 的渲染接口接收完整 HTML 字符串，因此插件不会依赖渲
 
 `core/event_push.py` 与 JX3API WebSocket 保持长连接，每 30 秒发送协议心跳。连接中断后按 1、2、4、8 秒递增重试，最大间隔为 30 秒；插件卸载时会取消心跳和重连任务并关闭连接。当前支持官方 `SocketEventMap` 中的全部 39 种事件，包含奇遇、马驹、扶摇、烟花、的卢、玄晶、阵营、宣战、据点、攻防拍卖与免费资讯事件。
 
-每条消息按 `action` 识别事件，正文优先读取 `detail`，同时兼容 `data`。分发时联查会话区服绑定：正文包含 `server` 时仅保留同区服或未绑定区服的接收会话，正文不含 `server` 时不做区服过滤。之后只有会话的 `enabled=1` 且对应 `action_编号=1` 时才发送。会话 ID 直接取当前消息的 `unified_msg_origin`。
+每条消息按 `action` 识别事件，正文优先读取 `detail`，同时兼容 `data`。分发时先应用会话控制策略，再联查会话区服绑定：正文包含 `server` 时仅保留同区服或未绑定区服的接收会话，正文不含 `server` 时不做区服过滤。之后只有会话的 `enabled=1` 且对应 `action_编号=1` 时才发送。会话 ID 直接取当前消息的 `unified_msg_origin`。
 
 表中使用 `action_1001` 这类列名保存各事件开关，并在新增事件编号时自动为旧数据库补列。升级时旧的 `tuishong` 轮询状态表会被删除。
 
@@ -465,6 +471,8 @@ astrbot_plugin_jx3/
 │   ├── message.py           # 文本、图片、消息链和两轮会话构建
 │   ├── request.py           # aiohttp 请求封装
 │   ├── event_push.py        # WebSocket 事件通道与会话订阅
+│   ├── session_control.py   # 全部会话、白名单与黑名单访问策略
+│   ├── webui.py             # 插件管理页路由、数据聚合与请求处理
 │   ├── server_binding.py    # 会话区服绑定、别名与区服目录
 │   ├── kungfu_alias.py      # 本地心法目录初始化、校验与 WebUI 写入
 │   ├── bilei_data.py        # 避雷数据增删改查
@@ -512,16 +520,17 @@ git diff --check
 
 ## 当前版本状态
 
-以下内容是对 v3.4.2 当前源码的静态核对结果，部署和二次开发前应注意：
+以下内容是对 v3.4.3 当前源码的静态核对结果，部署和二次开发前应注意：
 
 1. 查询图片使用浅色高对比主题和放大的内容区域；渲染清晰度、JPEG/PNG 格式及 JPEG 质量由 `image_render_quality` 配置组控制，提高清晰度或使用 PNG 会增加图片体积与渲染耗时。
 2. `帮会排行`、`阵营排行`、`其他排行` 使用固定的“数字序号 → 榜单名称”首轮菜单，次轮查询统一截取接口返回的前 50 条；取得有效选择后会先停止超时计时器，避免渲染期间重复输出。
-3. 区服别名 WebUI 展示完整标准区服目录并只允许行内编辑别名；心法别名 WebUI 隐藏配装 ID，后端保存接口也只更新已有心法的别名。
-4. aiocqhttp 图片发送返回 `retcode=1200` 时只记录警告，不再追加“猪脑过载”提示；该回执代表发送结果不确定，仍建议结合平台日志确认实际送达情况。
-5. 带区服参数的指令在入口层统一进行会话绑定补齐和别名解析；新增此类指令时参数名应继续使用 `server`。
-6. 资历分布使用固定的“数字序号 → 大类名称”首轮菜单，通用会话裁剪出单项字典后交给 JX3API `/tuilan/achievement` 次轮查询；模板兼容总览与指定 `subclass` 的不同 `data.total` 层级，并直接使用接口角色字段、`pieces`、`seniority` 和 `score/totalScore` 渲染，JX3BOX 不再参与资历查询。
-7. `APIClient` 当前默认 `ssl_verify=False`，即外部 HTTPS 请求不校验证书。对传输安全有要求的部署应先评估并调整该设置。
-8. JX3API 服务初始化时会把 Token 和 Ticket 写入 debug 日志。不要公开调试日志，建议二次开发时移除敏感值输出。
+3. 区服绑定 WebUI 的新增及行内编辑均只接受标准区服，聊天指令仍可使用区服别名；区服别名页展示完整标准区服目录并只允许行内编辑别名，心法别名页隐藏配装 ID，后端保存接口也只更新已有心法的别名。“恢复默认”使用页面内二次点击确认，确认后会用随包 JSON 完整覆盖对应数据库表，当前自定义别名无法从页面撤销恢复。
+4. 会话控制默认放行全部会话；切换白名单后只有白名单记录可执行插件指令及接收推送，切换黑名单后仅拦截黑名单记录。名单记录会保留在数据库中，切换模式不会删除已有配置。
+5. aiocqhttp 图片发送返回 `retcode=1200` 时只记录警告，不再追加“猪脑过载”提示；该回执代表发送结果不确定，仍建议结合平台日志确认实际送达情况。
+6. 带区服参数的指令在入口层统一进行会话绑定补齐和别名解析；新增此类指令时参数名应继续使用 `server`。
+7. 资历分布使用固定的“数字序号 → 大类名称”首轮菜单，通用会话裁剪出单项字典后交给 JX3API `/tuilan/achievement` 次轮查询；模板兼容总览与指定 `subclass` 的不同 `data.total` 层级，并直接使用接口角色字段、`pieces`、`seniority` 和 `score/totalScore` 渲染，JX3BOX 不再参与资历查询。
+8. `APIClient` 当前默认 `ssl_verify=False`，即外部 HTTPS 请求不校验证书。对传输安全有要求的部署应先评估并调整该设置。
+9. JX3API 服务初始化时会把 Token 和 Ticket 写入 debug 日志。不要公开调试日志，建议二次开发时移除敏感值输出。
 
 ## 注意事项