HNCore v2.3.0

• 发布日期：2026-04-21
• 发布提交：4d56c10
• 版本定位：完善多渠道输入框架，新增 SIGN 输入方式，优化工具箱结构

版本定位

v2.3.0 这一轮的核心目标是 完善 2.2.0 引入的多渠道输入框架。

在 2.2.0 中引入了聊天输入和铁砧输入，但告示牌输入仍为占位实现。本次更新完整实现了 SIGN 输入方式，包括临时告示牌管理、持久化注册表、安全检查等完整功能。

同时对工具箱服务进行了重构优化，提取了 GUI 渲染器和预览服务，消除了重复代码和弃用方法，代码行数从 1067 行减少到 708 行（-34%）。

本次重点新增

1. SIGN 输入方式完整实现

来源提交：626e567（2026-04-21，[新增] 实现 SIGN 输入方式并完善临时告示牌管理）

核心能力：

• 完整的告示牌输入会话实现
• 临时告示牌自动管理（放置、清理、恢复原方块）
• 持久化注册表（服务器崩溃后自动清理残留告示牌）
• 安全位置检测（避免破坏玩家方块）
• 支持 4 行文本输入
• 自动合并多行内容

API 入口：

SignInputSession<MyContext> session = SignInputSession.<MyContext>builder(player.getUniqueId(), context)
    .initialLines(List.of("第一行", "第二行", "", ""))
    .promptMessage("§a请在告示牌上输入内容：")
    .onInput((p, input) -> {
        // input 是所有行合并后的文本（用空格分隔）
    })
    .onCancel(p -> {
        // 处理取消
    })
    .timeout(60000)
    .build();

sessionManager.beginSession(player, session);

安全特性：

• 自动寻找玩家附近的安全位置（空气或可替换方块如草、花）
• 编辑完成后自动恢复原方块
• 服务器崩溃或玩家离线时自动清理残留告示牌
• 持久化注册表确保重启后也能清理临时告示牌

适用场景：

• 邮件系统（多行内容输入）
• 公告系统（多行文本编辑）
• 任何需要多行短文本输入的场景

2. 工具箱服务重构优化

来源提交：28c4f34 + 2fef01a + 07077fc + 82b895f

优化内容：

• 提取 ToolboxGuiRenderer（209 行）- 负责 GUI 渲染逻辑
• 提取 ToolboxPreviewService（173 行）- 负责预览功能
• 引入 ToolboxCatalogBuilder - 统一条目构建
• 消除重复代码和弃用方法
• 代码行数从 1067 行减少到 708 行（-34%）

重构收益：

• 职责更清晰（服务层、渲染层、预览层分离）
• 代码更易维护
• 减少重复逻辑
• 为后续扩展打下基础

3. 文档完善

来源提交：c89c29f + 83e78c9（2026-04-19）

新增文档：

• API_2.2.0_SUMMARY.md - 2.2.0 版本发布总结
• DOWNSTREAM_API_GUIDE.md - 下游插件 API 使用指南（完整版）

文档内容：

• 通用搜索框架详细使用指南
• 多渠道输入会话框架完整示例
• 最佳实践和迁移指南
• 常见问题解答

破坏性变更

无 - 2.3.0 完全向后兼容 2.2.0

迁移指南

从 2.2.0 迁移

无需任何修改 - 2.3.0 完全向后兼容 2.2.0

推荐升级

如果你在 2.2.0 中使用了输入会话框架，现在可以使用完整的 SIGN 输入方式：

旧代码（2.2.0 占位实现）：

// 告示牌输入在 2.2.0 中为占位实现，需要自行完善

新代码（2.3.0 完整实现）：

SignInputSession<MyContext> session = SignInputSession.<MyContext>builder(player.getUniqueId(), context)
    .initialLines(List.of("邮件标题", "邮件内容", "", ""))
    .promptMessage("§a请在告示牌上输入邮件内容：")
    .onInput((p, content) -> {
        if (content.isBlank()) {
            p.sendMessage("§c内容不能为空");
            return;
        }
        draft.setContent(content);
        p.sendMessage("§a内容已设置");
    })
    .onCancel(p -> {
        p.sendMessage("§7已取消");
    })
    .timeout(60000)
    .build();

sessionManager.beginSession(player, session);

性能影响

• ✅ 无性能损失
• ✅ 临时告示牌自动清理，无内存泄漏
• ✅ 持久化注册表使用高效的 JSON 存储
• ✅ 工具箱重构后代码更精简（-34%）

已知问题

• 告示牌输入需要 Paper 服务器（不支持 Spigot），因为使用了 Paper 的 player.openSign() API

相关文档

完整文档

• 下游 API 指南: DOWNSTREAM_API_GUIDE.md
• 迁移指南: MIGRATION_GUIDE.md

示例代码

• 工具箱: HNCoreToolboxService - 搜索框架 + 聊天输入
• 测试命令: SignInputTestCommand - 告示牌输入示例

总结

v2.3.0 通过完整实现 SIGN 输入方式，补齐了多渠道输入框架的最后一块拼图。现在下游插件可以根据场景选择最合适的输入方式：

渠道	适用场景	优点	缺点
CHAT	长文本、多行内容	无长度限制	需要关闭 GUI
ANVIL	短文本、价格、名称	GUI 内输入、体验流畅	长度限制（~35 字符）
SIGN	多行短文本	支持 4 行、GUI 内输入	需要 Paper API

同时通过工具箱重构，代码质量得到显著提升，为后续功能扩展打下了良好基础。