Python ✨LumenBridge——基于Endstone的群服互通插件！支持QQ官Bot！🎉 1.0.13

[MD] # LumenBridge 更新日志汇总（v1.0.8 → v1.0.13） ## 新增 - 子插件依赖一键补全：市场安装、链接下载或手动上传均可自动补全，支持 requirements.txt 声明依赖链接 - 插件市场已装状态：已安装子插件显示「已安装」徽章，有新版本时显示「更新」按钮 - QQ 官方机器人按钮键盘消息：点击回调、插入指令、跳转链接 - QQ 官方机器人引用消息、合并转发、@ 提及、语音消息的事件翻译，单聊消息撤回 - 子插件语言统一 API（`lumen.language`） - 正则引擎新增 6 个内置变量：`$rawMessage`、`$card`、`$role`、`$messageId`、`$selfId`、`$domain` - WebUI 实时日志页升级：级别筛选、关键词过滤与命中高亮、暂停/继续、连接状态指示 - `/lumen webui-host` 指令：控制台切换 WebUI 监听地址，立即生效 ## 修复 - `/lumen update framework -y` 网络超时甩大段堆栈 → 现仅提示「网络超时」等友好文案 - `/lumen update framework -y` 需执行两次命令才能完成更新 → 现一条命令完成「检查 → 下载 → 自动热重载」 - 子插件声明 Endstone 依赖时检查被跳过并误报、ZIP 升级后自定义页面不更新 - 服务端 `/reload` 后误播报「服务器已关闭 / 已启动」 - QQ 官方机器人群服互通设置无法保存、绑定主群后总览页仍显示未配置 - WebUI 语言切换按钮不生效、监听 0.0.0.0 时启动日志仍显示 127.0.0.1 - 移动端返回顶部按钮、子插件自定义页面弹窗层级/遮罩等多项 UI 问题 ## 优化 - 统一安装体验：上传 ZIP / 链接安装复用市场安装的进度条 + 任务日志窗口，链接下载实时显示进度 - 依赖补全弹窗改用大卡片样式，下载链接允许跳转其它地址 - 子插件配置界面美化，正则页面卡片布局自适应 - 受保护 pip 包名单扩充至 32 项，安装 pip 依赖后自动热重载 - WebUI 检测配置文件外部修改，自动热生效并刷新页面 - 适配器类型显示名统一（OneBot / QQ 官方机器人） [/MD]

[MD]# 更新日志 ## [1.0.8] - 2026-09-26 ### 新增 - `/lumen webui-host` 指令：在控制台切换 WebUI 监听地址（`local` = 仅本机、`public` = 所有接口、也可指定具体 IP），立即生效 (#1) - WebUI 配置页支持检测配置文件外部修改：手动编辑 config.json 后自动热生效并刷新页面，无需重启或手动刷新 ### 修复 - 适配器开关关闭后重新打开仍显示开启、配置文件未实际修改的问题 - QQ 官方机器人适配器群服互通设置无法保存、重开弹窗仍为旧值的问题 - 官方 QQ 机器人绑定主群后，总览页仍显示未配置的问题 - WebUI 左下角语言切换按钮不生效、只能改配置文件的问题 - WebUI 监听地址设为 0.0.0.0 后，启动日志仍显示 127.0.0.1 的问题 (#1) - 启动时控制台 Logo 错乱的问题 - 总览页「OneBot 连接」文案改为「适配器状态」 - 适配器重载日志不再对 QQ 官方等非 OneBot 适配器误报「OneBot 连接」 - WebUI 连接管理中「WebSocket」适配器字样统一改为「OneBot」[/MD]

[MD]# 更新日志 ## [1.0.7] - 2026-09-19 ### 新增 - **子插件图标库扩展（7 → 34 个 + emoji 支持）** - **登录页密码框明暗切换重制** ### 安全修复 - **Xbox 玩家名字符集校验** - **反向 WebSocket 无鉴权监听告警** - **callPluginCommand 参数解析加固** ### 修复 - **桌面端子插件自定义图标不生效** - **手机横屏语言切换按钮溢出** ### 优化 - 内置 `websockets` 库由 15.0.1 升级至 17.1 **Full Changelog**: https://github.com/gxh6438/LumenBridge/compare/v1.0.6...v1.0.7[/MD]

[MD]# 更新日志 ## [1.0.6] - 2026-09-13 ### 新增 - **前端样式共享层 `/lumen.css`**：主面板样式拆分为「共享层 + 主面板层」两级（`lumen.css` / `app.css`）。子插件自定义页面引用共享层即获得与主面板一致的主题观感（深浅色跟随系统），无需自备样式；也支持「共享层 + 页内扩展」或完全自写（详见子插件开发文档）。共享层为公开 API，不兼容变更将升主版本号 - **群绑定密钥（免手填绑定群与管理员）**：适配器编辑「权限与身份设置」新增「获取绑定密钥」入口。面板签发一次性密钥（仅显示一次、5 分钟自动过期、生成新钥即焚毁旧钥、绑定成功即消费），支持一键复制绑定指令；管理员在目标群发送「/lumen绑定 密钥」即可自动把当前群与发送者写入群列表和管理员列表（@ 或不@ 机器人均可；简体 `/lumen绑定`、繁体 `/lumen綁定`、英文 `/lumen bind` 指令变体通吃，大小写不敏感）；多群绑定时群与管理员自动去重不重复填写；QQ 官方机器人域同样适用（group_openid / openid） - **群内 @ 批量添加管理员**：管理员在群内发送「/添加管理员 @用户 @用户 …」即可把被 @ 的用户批量写入当前适配器的管理员列表，QQ 号 / openid 自动从消息中的 @ 提及获取（兼容 OneBot 消息段与 CQ 码两种格式），无需再手抄号码到面板填写；非管理员使用会被拒绝，重复添加自动去重 - **`/lumen password` 控制台密码重置命令**：服务器控制台执行 `/lumen password <新密码>` 即可重置 WebUI 管理员密码（PBKDF2 哈希落盘、实时生效，所有已登录会话同步失效）；留空执行 `/lumen password` 则清除密码并转入随机密码模式（等同配置哨兵 `*`，随机密码仅打印到服务器控制台）。该命令仅限服务器控制台执行，游戏内（含 OP）一律拒绝 ### 修复 - **聊天美化插件导致游戏消息不转发到群（加固重制）**：美化 / 格式化类插件（如 u_beautiful_chat）会取消原版聊天事件再以自己的格式重发，旧版会因此丢消息。聊天吸收探针重制为**时间戳回溯**机制：无条件记录广播并打时间戳，原生聊天事件到达时回看时间窗内是否出现过包含原始发言的广播，据此判定「已被美化插件吸收展示」并照常转发玩家原始发言（游戏内格式的修饰不带进群消息）。该机制不再依赖事件分发顺序与线程局部状态，对基岩版修改聊天的 addon 兼容性更好 - **新增 `chat.forward_cancelled` 转发策略**：被取消的聊天事件如何处理，支持「自动（按展示证据判定）/ 始终转发 / 取消即不转发」三档，WebUI 配置页新增「聊天转发」独立导航与下拉选项（auto / always / never，三语均已翻译）。无广播信号的「逐玩家私发」型美化插件可用「始终转发」兜底 - **回到顶部按钮点击后不消失**：平滑滚动结束后按钮仍悬停在右下角的漏网口 - **适配器编辑页面卡顿**：弹窗打开期间自动停用遮罩下方各层的毛玻璃效果（backdrop-filter），显著降低 GPU 负载，关闭弹窗即恢复 - **QQ 官方机器人静默日志失效**：开启「后台静默日志」后 `access_token 已刷新`、连接就绪等运行日志仍输出的漏网口 ### 优化 - 框架更新旧 wheel 备份仅保留最近 3 份，不再无限累积 - 获取绑定密钥弹窗的倒计时改为纯色进度条 + 等宽数字（最后 60 秒切警示色），去除渐变动效 - 聊天事件链路诊断日志（`[chatdbg]`）统一纳入 `debug: true` 配置开关，调试模式关闭时完全静默[/MD]

[MD]# 更新日志 ## [1.0.5] - 2026-09-06 ## 修复 * **框架热重载崩服修复**：历史实现在调度器任务内执行 `Server.reload()`，reload 过程 `disablePlugins` → `cancelTasks` 会取消"当前正在执行的任务"，随后 `removeCancelledTasks()` 直接改动 `mainThreadHeartbeat` 正在迭代的任务队列，心跳循环悬垂引用 → SIGSEGV 崩服。热重载现在只能由管理员在命令上下文同步触发（`/lumen update framework -y`，与内建 `/reload` 同款安全路径）；`apply_framework_update` 只做下载校验与原子暂存，绝不触发重载 *** ## 一、框架更新「暂存 → 确认」两段式流程 * 新版本下载校验后**原子暂存**（含旧版备份，不会自动生效）：`auto_update` 开启时自动完成暂存并提示管理员确认 * 生效途径二选一：WebUI 更新页「**立即热重载**」按钮（带确认弹窗，明确提示将重载服务器内全部插件）/ 服务器控制台 `/lumen update framework -y` * 新增 `staged_framework_update()` 本地暂存回执查询（不触网），命令可快速判断是否可直接热重载 ## 二、WebUI 热重载体验 * 热重载过程 overlay：提示面板将短暂无法访问，完成后**自动刷新**；等待超时给出回滚排查指引（新版本启动失败会自动回滚旧版本，刷新页面即可恢复） * `/api/health` 免认证健康检查端点（热重载后面板恢复探测） * 周期性市场更新检查线程于 `on_disable` 置位停止信号，热重载/停服时干净退出，避免清理期间仍在触网/写暂存文件 ## 三、子插件页面（iframe）体验修复 | 问题 | 修复 | | ---- | ---- | | 高度自适应整体失效 | 旧版子插件页面自带的上报脚本抢占幂等标志，新版脚本从未安装（改用独立哨兵标志） | | 满屏型/短内容页面被截断 | 高度下限 = 视口高 − 顶部位置，保证至少铺满可视区 | | 「嵌入式网页方框」观感 | 主面板注入融合基础样式（背景透明），与普通页面观感一致；自定义背景可内联 `!important` 覆盖 | | 其它 | 重复调用幂等；border-bottom 计量修正；移动端手势内部滚动耗尽后链式传播到主文档 | ## 四、其它优化 * 注册类日志（插件 API / 配置表单 / 自定义页面注册提示）降为 debug 级别，仅 debug 配置开启时输出，不再刷屏 * 敏感词过滤：词条重复、正则语法错误的明确提示与一键清除 * 子插件配置搜索显示「{n} 项匹配」计数 * 依赖约束（requires）版本比较口径明确为宽松元组比较（`1.2.0 > 1.2`），与框架更新比较的「补 0 对齐」口径分离，docstring 与测试同步说明 *** [/MD]

更新日志

[1.0.4] - 2026-09-1

新增

- 子插件配置页焕然一新：分组卡片、搜索过滤、单项恢复默认、未保存拦截
- ConfigFormBuilder 新增 4 类字段能力：分组、多选、密码框、滑块
- QQ 官方适配器：断线 Resume 重放消息重复下发修复
- 子插件加载器 4 项健壮性修复（同名冲突 / 热重载保护 / 升级数据保留 / 开关即时生效）
- 新增敏感词过滤功能，支持一键导入敏感词库，QQ→MC，MC→QQ双向消息支持拦截/打码

一、子插件配置页面升级

全新布局

- 分组嵌套卡片：子插件可通过 section() 声明配置分组，渲染为嵌套卡片形成层级感
- 两列行式布局：左侧字段名 + 描述、右侧控件，窄屏（手机端）自动退化为上下堆叠
- 配置项数量徽章：弹窗标题栏实时显示当前配置项总数

全新交互

特性 说明
搜索过滤 顶部搜索框按 key / label / desc 模糊匹配，无命中的分组整组隐藏
单项恢复默认 当前值 ≠ 默认值的字段右侧出现恢复按钮，一键回填默认值
全部恢复默认 底部一键恢复全部字段（带二次确认）
未保存拦截 任意输入即标记「未保存的更改」（底部脉冲徽章），关闭弹窗前弹出确认
快捷保存 配置弹窗打开时支持 Ctrl / Cmd + S 快捷保存
批量导入 array 字段支持按行批量导入，逐项去重
全屏编辑 textarea 字段右上角提供全屏编辑弹窗

ConfigFormBuilder API 扩展

子插件配置表单构建器新增以下能力：
新增字段方法

python

builder.section("基本设置", "触发与输出行为") # 分组卡片
builder.multiselect("events", ["join"], OPTIONS) # 多选复选框组
builder.text("token", val, secret=True) # 密码框（带明文切换）
builder.number("interval", 30, minimum=10, maximum=300, step=5) # 滑块联动


通用可选参数（除 file 外所有字段支持）

参数 说明
default 显式默认值；未声明时以注册时初始值为默认，作为「恢复默认」数据源
obvious_hint 标记重要配置项，字段名旁显示
show_key 在字段名旁以等宽字体显示配置键名
其它控件升级

- array 字段升级为 chips 列表编辑器（逐项增删 + 批量导入）
- select 字段改用自定义下拉组件（带搜索），options 由后端统一规范化

二、修复

QQ 官方机器人适配器

- 断线 Resume 重放消息重复下发：网关断线重连（Resume 补投）期间，官方会重放已处理过的 seq 事件，旧逻辑会重复下发消息导致机器人复读。现按 seq 去重，重放事件直接丢弃，新事件正常放行
- msg_id 过期被动凭据堆积（错误码 40034005）：官方判定 msg_id 过期后，被动凭据池中的过期条目现在会被及时清理，并自动剥离过期凭据字段改走主动通道重试，消息不再发送失败
- 会话失效关闭码处理：网关 op=9（无效会话）时 seq 归零并走全新 Identify 重连，不再携带失效会话反复被拒

子插件加载器

- 同名子插件冲突：两个目录的清单声明同一插件名时，仅先加载者生效，后者明确拒绝（原先行为未定义）
- 热重载保护： reload_one 现在先校验新清单再卸载旧实例——清单损坏（非法 JSON）或 load: false 时直接返回失败，运行中的实例不再被误卸载
- 升级数据保留：子插件升级时递归保留全部嵌套目录中的用户数据（如 data/nested/state.json 、 config/settings.json ），仅替换代码文件
- 开关即时生效：WebUI / 命令启用、禁用子插件立即加载或卸载运行实例（原先仅改写清单，需重启或手动重载）

正则引擎

- 非法动作元素跳过：规则文件中含未知 / 格式错误的动作元素时跳过该项并记录日志，不再中断整条规则执行

插件市场

- 清单检查时间原子写入：更新检查时间戳改为临时文件 + 替换的原子写入，进程中断不再留下 .json.tmp 残留或损坏的清单

配置页自身

- 批量导入面板无法展开：显隐 CSS 规则误写在 textarea 上而非包裹容器，已修正

lumenbridge框架自动更新

- 自动更新热重载崩服：已修复

[MD]# 更新日志 ## [1.0.3] - 2026-08-21 ### 新增 - LumenBridge 框架本体在线更新：从市场检查新版本 → 下载并 SHA-256 校验后暂存（幂等，已暂存不重复下载）→ 热重载生效。热重载走 Endstone 官方 `Server.reload()`（与 `/reload` 命令同一实现）；旧版 Endstone 无该绑定时自动回退派发 `reload` 命令 - `/lumen update framework [-y]` 命令（两步确认）：不带 `-y` 只检查新版本并下载校验暂存（不更新）；带 `-y` 才执行更新并热重载。热重载会重载服务器内**全部**插件（等同 `/reload`），故 `updates.auto_update` 对框架本体只通知不自动更新，必须由管理员经命令或 WebUI 确认弹窗手动确认（弹窗明确提示将重载所有插件、面板短暂下线后自动恢复） - 热重载失败自动回滚：移除失败的新 wheel → 放回备份旧 wheel → 再次触发 reload 恢复旧版本运行 - 三语言（zh_CN / zh_TW / en）框架更新命令与 WebUI 确认弹窗文案 - 子插件强制依赖（`requires`）：`lumen.json` 新增 `requires` 字段，可声明对其它子插件与 Endstone 插件的强制依赖（支持 `>= <= > < == !=` 六种版本约束，比较符与版本号成对出现）。加载时按依赖拓扑排序（被依赖者先加载，循环依赖按原顺序各自报错）并强制检查：Endstone 插件依赖缺失时报错提示用户先安装并启用；子插件依赖缺失时在市场安装/升级/「补装依赖」时自动从市场按 `manifest_name` 精确匹配补装（像 pip 依赖一样递归安装，带循环依赖检测与版本约束选择，市场中找不到时提示手动安装） - 卸载/禁用子插件前的反向依赖预检：其它子插件依赖目标插件时列出依赖方并警告 - 插件市场端配套（需同步更新市场 PHP 程序）：上传 ZIP 时校验 `requires` 格式（非法声明拒绝发布）并按版本存储；插件列表 API 新增 `manifest_name` 精确搜索参数；公开 API 在插件列表/详情/版本接口输出 `manifest_name` 与 `requires`；社区页插件详情与后台审核视图展示依赖信息 - `/lumen update <子插件名>` 命令：更新指定子插件到最新版 - `/lumen update -A|--all` 命令：一键更新全部有新版本的市场子插件（单个失败不阻断其余，结果逐个回显） - WebUI「检查插件更新」升级：发现新版本时弹出「可更新的子插件」卡片列表（支持选择目标版本单独更新，仅可更新到更高版本），底部支持一键更新全部；均为最新版时弹窗提示 - 子插件更新相关三语言（zh_CN / zh_TW / en）文案与命令权限配置项（`commands.update.allow_player`） - WebUI 慢速读取（Slowloris）防护：请求体读取按 16KB/s 最低速率设置总超时，杜绝慢速滴漏攻击占满连接线程 ### WebUI 优化 - 子插件卡片新增「插件依赖」徽章与「插件依赖缺失」红色标识，缺失时提供一键「补装依赖」入口（子插件依赖自动从市场安装，Endstone 插件依赖提示手动安装） - 插件市场详情页版本列表展示「子插件依赖 / Endstone 插件依赖」 - 横屏（电脑端）子插件页面卡片改为两列并排，窄屏保持单列 - 子插件卡片大小严格一致：列轨道改用 `minmax(0, 1fr)` 切断长描述/长名称对列宽的影响，描述固定两行占位、标题行单行省略号截断，全部卡片等宽等高（名称截断后悬停可看全名） - 插件市场图标修复为固定正方形（原先被拉伸为长方形） - 「已是最新版」弹窗按钮移至右侧 ### 修复 - 子插件升级数据丢失：改为递归备份全部非代码文件（原仅备份顶层白名单后缀文件） - 市场清单检查时间改为原子写入，进程中断不再留下不完整文件 - 市场端依赖字段类型异常不再中断整个更新检查流程 - `/lumen pip`、`/lumen update` 命令在实例未完成初始化时崩溃：新增安全日志访问器逐级回退（tee logger → logger → 模块级 logger），后台线程日志不再丢失 - WebUI 安装端点（上传/链接安装）未持主线程操作锁可并发执行：补锁后冲突请求返回 409，防止并发主线程操作 - pip 卸载同步阻塞 WebUI 线程最长 60 秒：移入后台任务队列与进度跟踪（与安装一致） - QQ 官方适配器事件在 WebSocket 线程内同步处理导致心跳停跳：新增独立派发队列与工作线程（与 WS 适配器同构），消除重连风暴 - WebSocket 派发线程退出泄漏：补双退出条件（哨兵值 + 运行标志），队列满丢哨兵时线程仍可退出 - 白名单文件损坏时被直接覆写丢失全部绑定：覆盖前自动备份 `.corrupt` 文件 - 子插件 ZIP 安装包解压无限制（ZIP 炸弹）：新增条目数 / 单文件大小 / 总解压大小三级限额 - 子插件依赖版本约束解析失败：`~=` 兼容版本比较与通配符匹配按 PEP 440 实现 - 后台线程（pip 安装/卸载、市场更新）直接调用原始 logger 在 Windows 下与控制台输入线程竞争导致服务端崩溃：统一改用线程安全 tee logger ### 日志 - QQ 官方机器人「连接成功，群服互通已就绪」「会话已恢复（Resume 补投完成）」纳入后台静默日志开关（`suppress_connection_log`，默认开启）：连接/重连不再刷屏，排障时可在连接管理卡片关闭开关查看全部日志；WS/AstrBot 适配器行为不变 [/MD]

[MD]# 更新日志 ## [1.0.2] - 2026-08-20 ### 新增 - QQ 官方群聊 @ 提及恢复正常显示（适配官方新格式，旧格式弃用不受影响） - 存储目录化：适配器配置拆分到 `connections/` 分文件存储，运行数据统一迁入 `data/` 目录 ### WebUI 优化 - 插件市场卡片：图标居左、文字并排，按钮移至右下角，布局更紧凑 - 子插件卡片：操作按钮收进「⋯ 更多」菜单，消除按钮堆砌；描述超长时折叠，卡片大小统一 - 更新流程：单一更新按钮，可选市场更新（支持选择历史版本）或手动更新；已是最新版时弹出美化提示 - 安装/更新进度弹窗现在包含依赖安装的进度与日志 ### 修复 - `/lumen pip install` 命令无法使用 - 关闭 WebUI 后 `/lumen reload` 不生效，且会覆写用户配置 - 手改 config.json 出错时被默认配置覆写（现自动备份损坏文件） - 适配器名超长、旧配置迁移后静默断连、损坏 lumen.json 阻断加载等问题 - 反向 WebSocket 多客户端在线状态不对称、事件误判重复丢弃 - 群聊广播单个目标失败中断整轮发送、消息超长截断协议错误 - 跨线程日志丢失、pip 安装失败无提示等运维问题 - 连接日志开关（`suppress_connection_log`）语义明确化，默认静默[/MD]

[MD]# LumenBridge 更新日志 ## v1.0.1 **发布日期：** 2026-08-18 ### Bug 修复 - **修复插件市场封面图加载失败** 市场卡片左侧封面图无法加载的问题，原因是封面 URL 校验函数导入失败导致所有封面请求抛 `ImportError`。已移除该校验，依赖项目现有内网部署策略。 - **修复 `MarketplaceError` 构造异常** 路由回退信号 `_RouteNotFoundError` 继承 `MarketplaceError` 时未传递 `message` 参数，导致部分 404 场景抛出 `TypeError`。已为子类添加无参构造函数。 - **修复框架更新按钮样式异常** 总览界面"框架更新"按钮多余的向上箭头图标已移除。 ### 新功能 - **框架热重载** 框架 wheel 更新安装后自动清除 Endstone 模块缓存并重载，无需手动重启服务端即可生效。基于 Endstone `_invalidate_caches` 机制实现。 - **点赞 / 举报完全匿名化** 引入市场匿名会话管理，通过访问市场页面获取匿名 Cookie 与 CSRF Token 完成点赞和举报操作。`webui_report_api_key` 配置项已删除，不再需要填写任何密钥。 - **任务进度弹窗** 安装 pip 依赖、安装 / 更新子插件、应用框架更新等长耗时操作现在会在 WebUI 弹出实时日志面板和进度条（仿 AstrBot 风格）。包含： - 实时滚动日志输出 - 0–100% 进度条与状态标签 - 完成 / 失败 / 热重载中状态徽章 - 三语国际化文案（zh_CN / zh_TW / en） ### 改进 - **国际化文案完善** `task_log_modal` 与 `task_log` 相关键已补齐到全部三种语言包。 - **第三方子插件兼容性** 修复 `picture_rank` 子插件 `NameError: name '_fmt_money' is not defined` —— 嵌套函数内静态方法调用需带 `self.` 前缀。 ### 破坏性变更 - 配置项 `report_api_key` 已移除，升级后旧配置值会被自动忽略。建议在 WebUI 配置页保存一次以清理残留键。 ### 升级方法 1.下载"endstone_lumenbridge-1.0.1-py3-none-any.whl" 放入plugins文件夹，并删除旧版本，在服务器后台执行reload或者重启Endstone 2. 进入 WebUI 保存一次配置以清理已移除的 `report_api_key` 键[/MD]