Help、Help-Key 与 Hint-Keys

MatrixShop 当前的命令帮助有三层：

1. 固定命令列表
2. Help-Key
3. Help

其中：

• Help-Key 负责“主入口一句话描述”
• Help 负责“多行补充说明”
• Hint-Keys 负责“某个子动作的提示键”

这三个字段写在哪里

模块级

适用于没有 shops/*.yml 的模块，例如：

• SystemShop
• ChestShop
• Cart
• Record

写在：

Bindings:
  Commands:
    ...

商店级

适用于带 shops/*.yml 的模块，例如：

• PlayerShop
• GlobalMarket
• Auction
• Transaction

也写在：

Bindings:
  Commands:
    ...

只是位置在 shops/*.yml 里。

Help-Key

这是一个 i18n key，对应主帮助列表中的一句描述。

例如：

Help-Key: '@commands.bindings.auction'

这会影响：

• /ms help
• /auction help
• /ms auction help

Help

这是多行帮助文本，会在模块帮助页里优先显示。

支持两种写法。

写法 1：列表

Help:
  - '&7拍卖模块支持英式拍卖与荷兰式拍卖。'
  - '&7打开大厅: &f{command} open'
  - '&7上架物品: &f{command} upload <english|dutch> <起拍价> [一口价|结束价] [时长]'

写法 2：多行字符串

Help: |-
  &7交易记录用于查看成交、退款和统计信息。
  &7打开记录页: &f{command} open [关键字]
  &7查看详情: &f{command} detail <记录ID>

当前实现两种都支持。

Hint-Keys

Hint-Keys 用于某个子动作的提示文案。

例如：

Hint-Keys:
  open: '@commands.bindings.auction'
  bid: '@commands.hints.auction-bid'
  upload-english: '@commands.hints.auction-upload-english'

模块代码在需要时会按 key 读取：

• open
• bid
• upload
• request
• money
• exp
• amount

具体支持哪些 key，取决于模块本身。

可用占位符

在 Help 文本里当前可以稳定使用：

占位符	说明
{command}	当前实际使用的命令前缀
{binding}	当前绑定命令，不含 /
{shop-id}	当前商店 id
{shop}	当前商店 id

这意味着：

• /auction help 会显示 /auction ...
• /ah help 会显示 /ah ...
• /cart help 会显示 /cart ...

一个完整示例

Auction/shops/default.yml

Bindings:
  Commands:
    Bindings:
      - 'auction'
      - 'ah'
    Register: true
    Show-In-Help: true
    Priority: 100
    Help-Key: '@commands.bindings.auction'
    Hint-Keys:
      open: '@commands.bindings.auction'
      bid: '@commands.hints.auction-bid'
      upload-english: '@commands.hints.auction-upload-english'
      upload-dutch: '@commands.hints.auction-upload-dutch'
    Help:
      - '&7拍卖模块支持英式拍卖与荷兰式拍卖。'
      - '&7打开大厅: &f{command} open'
      - '&7上架物品: &f{command} upload <english|dutch> <起拍价> [一口价|结束价] [时长]'
      - '&7出价: &f{command} bid <id> [价格]'
      - '&7管理自己的拍卖: &f{command} manage'

Cart/settings.yml

Bindings:
  Commands:
    Bindings:
      - 'cart'
    Register: true
    Show-In-Help: true
    Priority: 40
    Help-Key: '@commands.bindings.cart'
    Hint-Keys:
      open: '@commands.bindings.cart'
      amount: '@commands.hints.cart-amount'
    Help:
      - '&7购物车会汇总可结算的条目。'
      - '&7打开购物车: &f{command} open'
      - '&7打开结算预览: &f{command} checkout [valid_only]'
      - '&7确认结算: &f{command} checkout confirm [valid_only]'
      - '&7调整数量: &f{command} amount <槽位> <数量>'

当前表现

现在默认模块的帮助行为是：

• 先输出 Help 多行说明
• 再输出固定命令列表

如果没有 Help：

• 就只显示固定命令列表

重载与生效

Help、Help-Key、Hint-Keys 都属于配置内容。

当前行为：

• /matrixshopadmin reload 后即可更新
• 不需要重启服务器

唯一例外仍然是：

• 独立命令关键字本身
• Register

这两类改动仍建议重启后验证。