v1.18.1 - 修复背包图片里 5 个物品的图标变形

修复背包图片里 5 个物品的图标变形

查看背包时，末地烛被画成了「一根米色竖条 + 中间一个灰方块」的怪形状，脚手架则显示为问号方块。

原因

这 5 个物品在原版 models/item/<id>.json 里的 parent 是 block/<model>，也就是它们的物品图标本来就是 3D 方块模型渲染，而不是一张平面贴图：

assets/minecraft/models/item/end_rod.json  →  { "parent": "minecraft:block/end_rod" }

而背包图片渲染器只有两条路——「等距完整方块」和「平面贴图」。这些物品的 Material.isSolid() 为 false，于是走了平面分支，把方块贴图图集（末地烛那张图左边窄条是烛杆侧面、中间小方块是顶面）直接铺平画了出来。脚手架更糟，它根本没有对应的物品贴图，只能落到 unknown 问号方块。

修复

按原版方块模型的 elements / uv / 纹理引用离线烘焙成 64×64 图标，投影与明暗（顶 1.0 / 左 0.80 / 右 0.68）与现有等距方块完全一致：

物品	修复前	修复后
末地烛	被掰弯的图集	细烛杆 + 底座
雪	白色噪点方块	薄白雪层
传送植物	紫色噪点方块	立体植株
传送花	紫色噪点方块	立体植株
脚手架	unknown 问号方块	完整框架

判定方式不是肉眼猜测：按原版物品模型的 parent 字段扫描了全部 84 个「非完整方块」材质，只有这 5 个属于三维模型渲染。其余 79 个（虞美人、火把、轨道、珊瑚、蘑菇等）虽然贴图同样取自 block/，但原版物品模型本就是 layer0: block/xxx 平面贴图，图标正确，未做改动。

升级提示

• 只新增 5 张图标，无代码改动、无配置变化，配置版本仍为 10
• 直接替换 jar 即可

附件

文件	说明
HuHoBot-Penguin_Spigot-1.18.1.jar	主插件（Spigot / Paper）
HuHoBot-Engine-GraalJs-1.18.1.jar	GraalJs 扩展
HuHoBot-Engine-GraalPy-1.18.1.jar	GraalPy 扩展

Closes #24

v1.18.0 - 免验证名单，无需 QQ 绑定也可进服

免验证名单：无需 QQ 也能进服

部分人员受限于自身设备或环境，无法使用或安装 QQ，强制绑定会让他们进不了服务器。管理员人工审查后把他们加入免验证名单，这些人无需绑定即可正常游玩。

• 新增配置 binding.verify-exempt
• 新增管理员命令 /添加免验证 <玩家名>、/取消免验证 <玩家名>，改动即时写入配置，无需重启
• WebUI「绑定」页可直接编辑该列表

管理员：/添加免验证 Steve
HuHoBot：已添加免验证：Steve
        该玩家无需 QQ 绑定即可进入服务器

免验证玩家解绑不再被踢出

他们本来就能免绑定进服，解绑后踢出没有意义。非免验证玩家维持原样：强制绑定开启时解绑即踢出。

更正：游戏内验证在强制绑定下仍然有效

此前文档与配置注释里写的「强制绑定开启时 binding.require-game-verification 无效」不准确：

• 被踢出的玩家用 5 位验证码 /绑定 <验证码> 直接完成绑定，确实不经过游戏内验证；
• 但免验证玩家主动 /绑定 <游戏ID> 走的仍是普通流程，需不需要游戏内 /qqbind 验证由 binding.require-game-verification 决定。

config.yml、WebUI 说明与文档站均已更正；配置项的补充说明改为按位置替换，你旧配置里那句错误的注释会在下次启动时被自动覆盖。

升级提示

• 配置版本升到 10，启动时自动补 binding.verify-exempt 与两条命令开关
• 免验证名单默认留空，升级后行为与 1.17.0 一致
• 建议停服替换 jar 后启动一次

附件

文件	说明
HuHoBot-Penguin_Spigot-1.18.0.jar	主插件（Spigot / Paper）
HuHoBot-Engine-GraalJs-1.18.0.jar	GraalJs 扩展
HuHoBot-Engine-GraalPy-1.18.0.jar	GraalPy 扩展

Closes #21

HuHoBot-Penguin_Spigot v1.17.0

HuHoBot-Penguin_Spigot v1.17.0

强制绑定、配置文件自动升级，以及 WebUI 分节介绍改写。

下载

文件	用途	大小
HuHoBot-Penguin_Spigot-1.17.0.jar	主插件，必需。放在 plugins/	22.7 MB
HuHoBot-Engine-GraalJs-1.17.0.jar	可选。仅当你要写 .js 脚本时需要，放进 plugins/HuHoBotPenguin/engines/	34.1 MB
HuHoBot-Engine-GraalPy-1.17.0.jar	可选。仅当你要写 .py 脚本时需要，放进 plugins/HuHoBotPenguin/engines/	124.6 MB

只想用现成附属插件的话，只下载主插件即可，两个引擎包不必装。
.lua 脚本不需要任何引擎——LuaJ 已经打进主 jar，不放引擎包插件照常启动，只是对应语言的脚本加载失败，其它语言不受影响。
引擎包需与主插件同一次构建产出（文件名版本号要一致，对不上时启动会给出告警）。

强制绑定

开启后，没绑定的玩家一进服务器就会被踢出，并拿到一个 5 位验证码。在 QQ 群执行 /绑定 <验证码> 完成绑定，重新进服即可游玩。解绑的瞬间，其在线连接也会被立即断开。

binding:
  force-bind: true
  force-bind-groups:
    - "123456789"

踢出画面里带全部信息：服务器名、说明、验证码、群号与命令、重新进入会刷新验证码的提示。

开启前请注意

• 不要叠加任何白名单插件，也不要开启 Minecraft 自带白名单。否则未绑定玩家会在白名单阶段先被拦下，拿到不了验证码。
• 强制绑定依赖 QQ 机器人可用。QQ 未连接时插件会自动把 binding.force-bind 改回 false 并在日志说明，避免把人挡在门外却绑不了。
• 强制绑定开启时，绑定与解绑不再执行白名单同步命令。

绑定时的游戏内验证（binding.require-game-verification）在强制绑定下不生效。

配置文件自动升级

以前升级插件时，旧 config.yml 里经常缺一堆新配置项（比如 update-check、placeholder-api），因为 config.contains() 会回落到 jar 模板的默认值，误判成"已存在"就跳过了。

现在改成文本级增量升级：

• 缺失的配置项连同注释补进对应段落，缺失的中间层级自动创建
• 旧配置里被清掉的注释每次启动自动补回
• 只增不删，你改过的值原样保留

配置版本号升到 9。

WebUI

每个分节的介绍改为手写文案，说明这一页是干什么的、有什么坑，而不是把各字段说明拼成一长串。

升级提示

从 1.16.x 升级无需改配置，启动时会自动补齐新增配置项。建议停服替换 jar 后启动一次，让配置升级逻辑跑完。

需要注意：此前没有配置过 binding.require-game-verification 的服务器，升级后该项会补为 true，即绑定需要游戏内 /qqbind 验证。不希望改变的服务器请手动填 false。

HuHoBot-Penguin_Spigot v1.16.0

HuHoBot-Penguin_Spigot v1.16.0

死亡播报、WebUI 扫码连接、绑定跨群共享，以及内联键盘的三个修复。

对应 Issues：#14 死亡播报互通 · #15 WebUI 扫码连接入口 · #16 绑定信息跨群互通

下载

文件	用途	大小
HuHoBot-Penguin_Spigot-1.16.0.jar	主插件，必需。放在 plugins/	22.7 MB
HuHoBot-Engine-GraalJs-1.16.0.jar	可选。仅当你要写 .js 脚本时需要，放进 plugins/HuHoBotPenguin/engines/	34.1 MB
HuHoBot-Engine-GraalPy-1.16.0.jar	可选。仅当你要写 .py 脚本时需要，放进 plugins/HuHoBotPenguin/engines/	124.6 MB

只想用现成附属插件的话，只下载主插件即可，两个引擎包不必装。
.lua 脚本不需要任何引擎——LuaJ 已经打进主 jar，不放引擎包插件照常启动，只是对应语言的脚本加载失败，其它语言不受影响。
引擎包需与主插件同一次构建产出（文件名版本号要一致，对不上时启动会给出告警）。

死亡播报

玩家死亡后自动播报到 QQ 群，可在 WebUI「玩家事件」页开关。

player-events.death.enabled = true
player-events.death.format  = "[游戏] {message}"

{message} 是自动生成的中文死亡描述（不是原版英文），例如「Steve 被苦力怕杀死了」「Steve 从高处摔落而死」，覆盖玩家/生物/投射物击杀与摔落、岩浆、火烧、溺水和窒息、虚空、闪电、爆炸、中毒、饿死等 14 种死法。{killer} 是击杀者名。

WebUI 扫码连接

首次使用不必再调终端窗口大小。启动后打开 WebUI「QQ 机器人」页点「打开扫码连接」，手机 QQ 扫码即自动写入 AppID / Secret 并连接。

• 未配置凭据时 WebUI 照常启动，服务器不再卡在启动阶段等扫码
• 控制台二维码与网页扫码共用同一次授权任务，任一端扫码成功或取消，另一端状态同步
• 二维码过期会自动刷新，30 秒未选择视为取消

绑定跨群共享

绑定改为以 openid 为唯一标识：在一个群绑定成功后，该服务器的所有群都视为已绑定，查背包/末影箱不用再绑一次。MC 玩家名同时改为全局唯一，避免冒名顶替。

command-state.ini 会自动从旧的按群分组格式迁移为按 openid 索引，跨群重复记录会合并并保留原有显示名称设置，无需手动改文件。

新增管理员命令：

/强制解绑 <MC玩家名 | @某人 | openid | QQ昵称>

用于撤销冒名顶替的绑定，会同步移出白名单。/解除绑定 现在会先发「确定 / 取消」确认键盘，防止误操作。

键盘修复

• 内联键盘按钮不渲染（漏调 RowBuilder.build()，导致 rows 为空）
• 解绑确认点击无反应
• 点击后客户端提示「请求第三方失败 / 请求超时」（未按官方要求回应互动事件，AI 审批按钮同样受影响）
• 消息载荷按官方文档修正：传 markdown 时 content 置空

升级提示

从 1.15.x 升级无需改配置。建议在停服状态下替换 jar，绑定数据会在下次启动时自动迁移。

Fixes #14
Fixes #15
Fixes #16

HuHoBot-Penguin_Spigot v1.15.1

HuHoBot-Penguin_Spigot v1.15.1

修复版本：QQ 指令面板同步 30019「面板版本冲突」。直接替换 plugins/ 下的主插件 jar 重启即可。

下载

文件	用途	大小
HuHoBot-Penguin_Spigot-1.15.1.jar	主插件，必需。放在 plugins/	22.6 MB
HuHoBot-Engine-GraalJs-1.15.1.jar	可选。仅当你要写 .js 脚本时需要，放进 plugins/HuHoBotPenguin/engines/	34.1 MB
HuHoBot-Engine-GraalPy-1.15.1.jar	可选。仅当你要写 .py 脚本时需要，放进 plugins/HuHoBotPenguin/engines/	124.6 MB

只想用现成附属插件的话，只下载主插件即可，两个引擎包不必装。
.lua 脚本不需要任何引擎——LuaJ 已经打进主 jar，不放引擎包插件照常启动，只是对应语言的脚本加载失败，其它语言不受影响。
引擎包需与主插件同一次构建产出（文件名版本号要一致，对不上时启动会给出告警）。

修复内容

• fix: QQ 指令面板同步报 30019「面板版本冲突」 —— 原位更新按官方文档补传 panel.version（详情接口顶层与 panel 内两个位置都读取）；冲突时重读一次版本再重试一次
• fix: 面板同步并发自撞与撞限频（40030009「面板操作进行中」） —— 同步入口串行化，同一时刻只跑一次，期间的请求收敛为一次补跑；两次同步最小间隔 6 秒，对应官方写接口 10 QPM 限频
• improve: 面板同步错误提示区分 30013 / 30019 / 40030009 并给出排查建议

原因说明

PUT /v2/panels/{panel_id} 属于乐观并发接口：请求体的 panel.version 必须等于服务端当前版本，否则返回 30019。旧实现从查询详情里取回了面板却丢掉了 version，只提交 remark + items，因此原位更新必然触发版本冲突；多个命令注册并发触发同步时还会互相覆盖，进一步触发 40030009。本版本在请求中带上版本号、冲突时重读重试，并对同步入口做串行化与节流。

HuHoBot-Penguin_Spigot v1.15.0

HuHoBot-Penguin_Spigot v1.15.0

下载

文件	用途	大小
HuHoBot-Penguin_Spigot-1.15.0.jar	主插件，必需。放进 plugins/	22.6 MB
HuHoBot-Engine-GraalJs-1.15.0.jar	可选。仅当你要写 .js 脚本时需要，放进 plugins/HuHoBotPenguin/engines/	34.1 MB
HuHoBot-Engine-GraalPy-1.15.0.jar	可选。仅当你要写 .py 脚本时需要，放进 plugins/HuHoBotPenguin/engines/	124.6 MB

只想用现成附属插件的话，只下载主插件即可，两个引擎包不必装。

.lua 脚本不需要任何引擎——LuaJ 已经打进主 jar。不放引擎包插件照常启动，只是对应语言的脚本加载失败，其它语言不受影响。

引擎包需与主插件同一次构建产出（文件名版本号要一致，对不上时启动会给出告警）。

脚本扩展系统（新增，仅 Spigot / Paper）

不用编译就能扩展插件，用 JavaScript / Lua / Python 写脚本即可。

目录式脚本插件——plugins/HuHoBotPenguin/addons/<名字>/ 下放一个目录就是一个插件：

plugins/HuHoBotPenguin/addons/hello/
├── metadata.yaml          name / version / author / description / entry
├── _conf_schema.json      配置声明（可选），默认值写回 addons/config/hello.json
├── requirements.txt       Python 依赖声明（可选，仅预检提示）
└── main.js                或 main.lua / main.py

根目录上直接放 .js / .lua / .py 不再加载（会有一条提示告诉你挪到哪）。

Bird 桥——三种语言注入同一组对象，能力完全对等：

能力	说明
Bird.onEvent	监听任意 Bukkit 事件，可指定优先级
Bird.onCommand	注册游戏内命令，不需要改 plugin.yml，支持 Tab 补全
Bird.runTask*	同步 / 异步定时任务，重载时自动取消
Bird.fetch	异步 HTTP，回调切回主线程
Bird.on / Bird.emit	跨脚本事件总线
Bird.registerBotCommand	往 QQ 群里加自定义命令
config / kv / setData	用户可改配置、键值存储、脚本私有持久化
玩家 / 世界 / 方块 / 物品 / 音效 / 粒子	常用 Bukkit 操作的封装

引擎按需安装：

入口	引擎	放在哪	体积
main.lua	LuaJ 3.0.1	已在主 jar 内	—
main.js	GraalJS 24.1.2	plugins/HuHoBotPenguin/engines/HuHoBot-Engine-GraalJs-<版本>.jar	约 34 MB
main.py	GraalPy 24.1.2（Python 3）	plugins/HuHoBotPenguin/engines/HuHoBot-Engine-GraalPy-<版本>.jar	约 125 MB

重载

/huhobot scripts reload              卸载全部再加载全部
/huhobot scripts reload hello        只重载 addons/hello/，目录名大小写不敏感

重载和加载失败都会撤销该脚本登记的全部内容——Bukkit 事件、动态命令、定时任务、QQ 群命令、addon 元数据，不会留下幽灵条目。_enabled: false 记为「跳过」而不是「失败」。

兼容性

• 仅 Spigot / Paper 平台（其它平台未适配）
• 主插件保持 Java 8 字节码，可运行在 1.16.5 及以上服务端
• 引擎包由 Java 17 构建，但只是被加载的库，不影响服务端自身的 Java 要求

三语言写法差异

同一种返回值，三种语言拿到的形态不同，这是最容易踩的地方：

	命令参数	列表	字典
JavaScript	args[0]	.length、arr[0]	obj.key
Lua	args[1]	#t、t[1]、ipairs(t)	t.key、pairs(t)
Python	args[0]	len(x)、for v in x	x["key"]

Lua 侧是 1 起。LuaJ 会把 Java 的 List / Map 变成 userdata，在 Lua 里既不能取长度也不能 pairs，所以插件的 Lua 绑定层会把容器返回值转成真正的 table。另外 Lua 调用 Bird 的方法必须用冒号（Bird:broadcast(...)），点号会丢掉 self 导致参数错位。

Bird.tell 支持玩家、任意 CommandSender 和玩家名三种重载，所以从控制台执行脚本命令也能正常回应；giveItem / sendActionBar 这些只接受 Player，从控制台调用前先 Bird.getPlayer(...) 并判空。

已知边界

• Bird.fetch 走 JVM 默认信任库。目标站点证书链不被信任时会失败（例如本机装了流量代理时 GitHub 会被拦截），需要访问这类站点时把根证书导入服务端 JVM 的 cacerts。
• Python 的 requirements.txt 只做 import 预检并打警告，不会自动安装任何第三方库。
• .py 首次加载需要解压 GraalPy 标准库，约 10 秒，之后有缓存会快很多。
• 脚本回调在主线程执行，回调里不要做长时间阻塞操作。

文档

完整说明见仓库 docs/spigot-script-addons.md，含全部 Bird API 清单、三语言完整示例和常见报错速查。

致谢

脚本扩展系统（Bird 桥与脚本加载、生命周期设计）借鉴并移植自 birdlibraryapi（Apache-2.0，原作者 prach1121），并按 Spigot 1.16+ 与 HuHoBot 附属插件注册做了适配。

v1.14.0

HuHoBot-Penguin_Spigot v1.14.0

WebUI 附属插件中心（新增）

• 侧边栏新增「附属插件中心」分区，从附属插件中心 API 拉取插件列表
• 只显示 Spigot / Paper 平台的插件，其他平台自动过滤
• 支持按名称/简介搜索，可展开查看插件详情（readme）
• 一键下载安装：下载到服务端 plugins/ 目录，不做热加载，飘窗提示「重启服务器后生效」
• 下载记录持久化到 installed-addons.json，刷新页面不会退回「未安装」
• 支持删除已下载的插件（文件不存在时直接清理记录），同样提示重启后生效

WebUI 体验优化

• Toast 从底部改为顶部中上方飘窗，带淡入缩放动画
• 面板切换、配置字段、状态卡片逐条错峰淡入
• 导航项与按钮点击涟漪反馈，按下回弹，聚焦光圈
• 「保存全部」按钮保存中显示 loading 并禁用
• 分区图标补齐：绑定 🔗 / 命令黑名单 🚫 / 版本更新 🆕 / PlaceholderAPI 🔤
• 群名称在获取完成前显示「正在获取…」，失败后才显示「名称暂不可用」

群接入

• 群列表为空或未收录该群时，收到任意消息即自动把群 OpenID 写入 bot.groups（不再要求先发「查信息」）

群服互通与占位符

• 群服互通默认格式恢复为 [游戏] {name}: {message} / [QQ] {name}: {message}
• 绑定后不再自动把 QQ→游戏 显示名切成 MC 名，默认仍用 QQ 用户名，需要时用 /MC显示名称 MC 切换
• PlaceholderAPI 解析改用在线玩家实例，玩家类占位符可正常返回

其它

• 群名获取失败日志改为按数据源汇总，便于定位
• 群名刷新失败 30 秒内不重复请求，控制台不再刷屏
• 版本检查失败日志区分数据源（gh-proxy / github）

v1.13.0

HuHoBot-Penguin_Spigot v1.13.0

本次实现并关闭以下 Issue：

#10 Agent 获取类工具结果不再刷屏

• 获取插件列表 / 命令帮助 / 服务器日志的结果只交给 AI，不再在群里发卡片
• 新增开关 agent.hide-fetch-results（默认开启），需要回显可在 WebUI 或配置文件关闭

#9 接入 PlaceholderAPI

• 安装 PlaceholderAPI 后，配置里的 %占位符% 交由 PAPI 解析（纯反射接入，不引入编译期依赖，未安装时原样保留）
• 覆盖场景：游戏↔QQ 双向转发、进服/退服通知、白名单命令、自定义命令、在线列表与 MOTD 模板
• 玩家类占位符使用在线玩家实例解析；新增开关 placeholder-api.enabled（默认开启）
• 默认配置文本未改动，也不内置任何占位符

#8 版本更新提醒

• 启动时后台检查一次，/版本 命令再检查一次（10 分钟内复用结果）
• /版本 现在显示：当前版本、最新版本、官网 huhobot.dpdns.org、GitHub、文档 docs.huhobot.dpdns.org
• 只认 GitHub 正式 Release，忽略 Pre-Release；发现新版提示前往官网下载
• 数据源走 gh-proxy 代理的 GitHub API，国内网络可用；失败时降级为「暂时无法检查」，不影响启动
• 新增 update-check.enabled、update-check.url（自定义数据源）

#7 QQ 群接入简化

• WebUI「群列表」显示群名称（附 OpenID 尾号），点击可复制完整 OpenID；名称缓存 30 分钟并持久化
• 状态页列出已绑定群名称
• 陌生群发来消息时自动把群 OpenID 写入 bot.groups，无需手动查询复制；开关 bot.auto-add-groups（默认开启）

其它

• 群服互通默认格式恢复为 [游戏] {name}: {message} / [QQ] {name}: {message}
• 绑定后不再自动把 QQ→游戏 显示名切成 MC 名，默认仍用 QQ 用户名，需要时用 /MC显示名称 MC 切换
• 清理群管理 API 的调试输出，控制台更干净

---

Closes #7
Closes #8
Closes #9
Closes #10

v1.12.0

HuHoBot-Penguin_Spigot v1.12.0

新功能

• 集成 bStats 统计（插件 ID 34268），bStats 库已重定位到 cn.huohuas001.bstats，不会与其他插件冲突
• README 新增项目计数器

构建

• 产物：HuHoBot-Penguin_Spigot-1.12.0.jar

HuHoBot v1.11.0

HuHoBot-Penguin_Spigot v1.11.0

消息键盘自动撤回

• 所有带键盘的消息发送后 30 秒自动撤回，不再长期刷屏
• 点击键盘按钮后可立即撤回对应卡片

AI Agent 审批超时

• 手动审批模式下，审批卡片 30 秒未处理自动拒绝，并撤回卡片
• 超时后 Agent 会继续执行后续流程，并向群内说明操作已被自动拒绝
• 任务被紧急停止时，待审批卡片同样会被撤回

修复

• 修复 qqpd-bot-java 消息撤回接口始终返回失败的问题（RestApi 依赖未绑定导致 DELETE 请求被跳过），撤回现已正常工作
• 撤回失败时输出 HTTP 状态码与响应体，便于排查

依赖

• qqpd-bot-java 更新至 0287d4e（撤回接口修复）