主题
这页的目标是带你 按最短路径跑通一条真实可验证链路：
HNCore与HNWarehouse能正常启动- 默认配置与仓库模板能正常生成
- 玩家能打开自己的仓库
- 一件物品能按预期投递到目标仓库页
- 管理员能查询玩家仓库摘要
- 能从仓库中提取一条物品回到在线玩家背包
第 1 步：准备依赖
必需依赖
HNCoreHNWarehouse
可选联动
HNEconomy：用于economy类型条件PlaceholderAPI：用于placeholder类型条件
建议环境
- Paper
1.20.1 - Java
17
第 2 步：首次启动先确认这些点
启动服务器后，优先确认：
plugins/HNWarehouse/config.yml已生成plugins/HNWarehouse/warehouses/已生成默认仓库模板- 存储后端已初始化成功
/hnwarehouse status显示的存储后端符合预期- 控制台没有出现依赖缺失、配置解析失败或仓库定义加载错误
- 如果你是从旧版本升级，存在
plugins/HNWarehouse/data/players/*.yml时，应确认自动迁移已完成
默认会生成：
text
plugins/HNWarehouse/config.yml
plugins/HNWarehouse/warehouses/main.yml
plugins/HNWarehouse/warehouses/reward.yml
plugins/HNWarehouse/warehouses/overflow.yml若你从旧版本升级，仍可能看到
plugins/HNWarehouse/data/players/目录；它现在主要作为旧 YAML 迁移来源，而不是正式主数据目录。
你还可以执行：
text
/hnwarehouse status重点确认：
- 统一存储系统已初始化
- 存储后端是否符合预期
- 自动保存间隔是否符合预期
- 离线摘要缓存是否符合预期
- 默认 capture 路由是否正确
- 默认仓库定义数量是否符合预期
- HNCore 共享物品库 / HNEconomy Hook 状态是否符合当前环境
第 3 步：先打开自己的仓库
当前玩家打开仓库页的命令是：
text
/hnwarehouse open <你的玩家名> <仓库> [页面]例如：
text
/hnwarehouse open Alice main
/hnwarehouse open Alice main page-1建议先验证：
- 能打开
main仓库总览 - 能进入
page-1 - 如果仓库被锁定，会看到清晰的锁定 / 限制提示，而不是静默失败
当前没有单独的
/warehouse玩家命令入口，主入口仍是/hnwarehouse子命令体系。
第 4 步：跑通一条最基础的投递链路
最简单的验证方式是先用下游接入或调试代码调用 HNWarehouseAPI.deliverItem(...)，让一件普通物品按 manual 来源进入默认仓库。
当前默认路由是：
- 普通投递 ->
capture.manual-default-warehouse - 奖励投递 ->
capture.reward-default-warehouse - 自动收纳投递 ->
capture.auto-collect-default-warehouse
你至少要验证：
- 物品能进入目标仓库而不是直接消失
- 页面的
allowed-sources与priority生效 - 如果目标仓库被规则拦截，会返回明确原因
如果你当前没有接入方，也可以先使用：
text
/hnwarehouse routecheck <玩家名|UUID> <仓库> [manual|reward|auto-collect]配合 执行者主手物品 预览路由结果。
例如：
text
/hnwarehouse routecheck Alice main manual你要重点看：
- 预计可投递页
- 预计存入数量 / 剩余数量
- 哪些仓库被拦截
- 被拦截时是访问条件问题还是
item-admission规则问题
第 5 步：查询玩家当前仓库状态
管理员执行：
text
/hnwarehouse inspect <玩家名|UUID>例如：
text
/hnwarehouse inspect Alice
/hnwarehouse inspect Alice access
/hnwarehouse inspect Alice detail建议重点核对：
Session 已加载状态是否符合你的预期- 总仓库数 / 总页数 / 总容量
- 当前可访问仓库数与锁定仓库数
- 每个仓库的访问状态
- 页面的已用槽位、允许来源与自动收纳状态
detail模式下是否能看到具体条目 ID
第 6 步：验证提取回背包
当仓库里已经有条目后，使用：
text
/hnwarehouse withdraw <玩家名|UUID> <仓库> <页面> <条目ID> [数量]例如：
text
/hnwarehouse withdraw Alice main page-1 <entryId>
/hnwarehouse withdraw Alice main page-1 <entryId> 16建议验证：
- 在线玩家背包能收到提取物品
- 条目数量会按提取结果正确变化
- 数量不足 / 背包无法回填 / 条目不存在时会有明确失败提示
推荐的首版验证顺序
最建议按下面这个顺序来：
/hnwarehouse status/hnwarehouse open <自己> main/hnwarehouse routecheck <自己> main manual- 用接入代码或测试流程真正投递一件物品
/hnwarehouse inspect <自己> detail/hnwarehouse withdraw <自己> <仓库> <页面> <条目ID>
不要一开始就把购买、解锁、扩容、item-admission、占位符条件全部叠上。先跑通基础链路，再逐层加限制。