Document multiline help bindings

Author: 54895y

docs/matrixshop/bindings-and-ui.mdx

@@ -36,6 +36,16 @@ Bindings:
 - `Show-In-Help`：是否出现在 `/ms help`
 - `Priority`：冲突时优先级
 
+如果你需要：
+
+- 自定义多行帮助
+- 自定义帮助描述键
+- 自定义子命令提示键
+
+请继续看：
+
+- [Help、Help-Key 与 Hint-Keys](./bindings-help-and-hints)
+
 ## `shopId` 规则
 
 当前实现里，`shopId` 不再依赖 YAML 内部的 `id` 字段，而是直接取：

docs/matrixshop/bindings-help-and-hints.mdx

@@ -0,0 +1,216 @@
+---
+title: Help、Help-Key 与 Hint-Keys
+description: MatrixShop 中绑定命令的多行帮助、描述键和提示键的配置规则。
+---
+
+# Help、Help-Key 与 Hint-Keys
+
+MatrixShop 当前的命令帮助有三层：
+
+1. 固定命令列表
+2. `Help-Key`
+3. `Help`
+
+其中：
+
+- `Help-Key` 负责“主入口一句话描述”
+- `Help` 负责“多行补充说明”
+- `Hint-Keys` 负责“某个子动作的提示键”
+
+## 这三个字段写在哪里
+
+### 模块级
+
+适用于没有 `shops/*.yml` 的模块，例如：
+
+- `SystemShop`
+- `ChestShop`
+- `Cart`
+- `Record`
+
+写在：
+
+```yml
+Bindings:
+  Commands:
+    ...
+```
+
+### 商店级
+
+适用于带 `shops/*.yml` 的模块，例如：
+
+- `PlayerShop`
+- `GlobalMarket`
+- `Auction`
+- `Transaction`
+
+也写在：
+
+```yml
+Bindings:
+  Commands:
+    ...
+```
+
+只是位置在 `shops/*.yml` 里。
+
+## `Help-Key`
+
+这是一个 i18n key，对应主帮助列表中的一句描述。
+
+例如：
+
+```yml
+Help-Key: '@commands.bindings.auction'
+```
+
+这会影响：
+
+- `/ms help`
+- `/auction help`
+- `/ms auction help`
+
+## `Help`
+
+这是多行帮助文本，会在模块帮助页里优先显示。
+
+支持两种写法。
+
+### 写法 1：列表
+
+```yml
+Help:
+  - '&7拍卖模块支持英式拍卖与荷兰式拍卖。'
+  - '&7打开大厅: &f{command} open'
+  - '&7上架物品: &f{command} upload <english|dutch> <起拍价> [一口价|结束价] [时长]'
+```
+
+### 写法 2：多行字符串
+
+```yml
+Help: |-
+  &7交易记录用于查看成交、退款和统计信息。
+  &7打开记录页: &f{command} open [关键字]
+  &7查看详情: &f{command} detail <记录ID>
+```
+
+当前实现两种都支持。
+
+## `Hint-Keys`
+
+`Hint-Keys` 用于某个子动作的提示文案。
+
+例如：
+
+```yml
+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`
+
+```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`
+
+```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`
+
+这两类改动仍建议重启后验证。

sidebars.ts

@@ -72,6 +72,7 @@ const sidebars: SidebarsConfig = {
           ],
         },
         'matrixshop/bindings-and-ui',
+        'matrixshop/bindings-help-and-hints',
         'matrixshop/faq',
       ],
     },