docs: add MatrixCook wiki and refresh MatrixShop docs

Author: 54895y

docs/intro.md

@@ -2,27 +2,27 @@
 title: 插件 Wiki
 ---
 
-这里是 Matrix 系列插件的统一文档站。
+这里是 Matrix 系列插件的统一文档站点。
 
-当前已收录：
+当前已经收录：
 
-- [MatrixAuth](./matrixauth/overview.md)
-- [MatrixShop](./matrixshop/index.mdx)
+- [MatrixAuth](/docs/matrixauth/overview)
+- [MatrixCook](/docs/matrixcook/overview)
+- [MatrixShop](/docs/matrixshop)
 
-当前文档约定：
+## 文档约定
 
-- 每个插件放在 `docs/{plugin}/` 目录下。
-- 每个插件至少维护概览、部署、配置、命令和常见问题等基础页面。
-- 文档以当前源码和默认配置为准，不沿用旧交接文档中的过时命令或路径。
-- 首页只保留总入口，具体内容落到对应插件章节。
+- 每个插件单独放在 `docs/{plugin}/` 目录下。
+- 文档内容以当前源码、默认配置和默认资源文件为准。
+- 如果代码已经和旧文档分叉，以代码行为为准，并在对应页面里注明迁移差异。
+- 首页只做索引，具体使用说明放到插件各自章节。
 
-MatrixAuth 入口：
+## 推荐阅读顺序
 
-- [概览](./matrixauth/overview.md)
-- [部署指南](./matrixauth/installation.md)
-- [配置说明](./matrixauth/configuration.md)
-- [命令说明](./matrixauth/commands.md)
-- [PlaceholderAPI](./matrixauth/placeholders.md)
-- [EasyBot 对接](./matrixauth/easybot.md)
-- [开发说明](./matrixauth/development.md)
-- [常见问题](./matrixauth/faq.md)
+首次接触某个插件时，建议按这个顺序阅读：
+
+1. 概览
+2. 安装 / 快速开始
+3. 配置结构
+4. 命令与权限
+5. 常见问题

docs/matrixcook/commands-and-placeholders.mdx

@@ -0,0 +1,64 @@
+---
+title: 命令与占位符
+description: MatrixCook 的命令入口、权限节点和 PlaceholderAPI 变量。
+---
+
+# 命令与占位符
+
+## 主命令
+
+根命令是 `/matrixcook`，总权限为 `matrixcook.command`。
+
+### 玩家常用命令
+
+| 命令 | 权限 | 说明 |
+| --- | --- | --- |
+| `/matrixcook help` | `matrixcook.command` | 查看帮助面板 |
+| `/matrixcook menu` | `matrixcook.command.menu` | 打开锅具总览菜单 |
+| `/matrixcook menu cooker <锅具ID>` | `matrixcook.command.menu` | 查看某个锅具的配方列表 |
+| `/matrixcook menu categories <分类ID>` | `matrixcook.command.menu` | 查看分类详情 |
+
+### 管理命令
+
+| 命令 | 权限 | 说明 |
+| --- | --- | --- |
+| `/matrixcook reload` | `matrixcook.command.reload` | 重载配置、语言和缓存 |
+| `/matrixcook give cooker <玩家> <锅具ID> [数量]` | `matrixcook.command.give` | 发放锅具 |
+| `/matrixcook give fuel <玩家> <燃料ID> [数量]` | `matrixcook.command.give` | 发放燃料 |
+| `/matrixcook give item <玩家> <配方ID> <result\|failure> [数量]` | `matrixcook.command.give` | 发放配方产物或失败产物 |
+| `/matrixcook debug` | `matrixcook.admin` | 输出当前已放置锅具的调试信息 |
+
+## 配置内权限
+
+除了命令权限，配置本身还有两类运行权限：
+
+- 锅具权限：默认 `cookly.cooker.<id>`
+- 配方权限：默认 `cookly.recipe.<id>`
+
+也就是说，命令权限前缀是 `matrixcook.*`，而锅具/配方使用权限默认还是 `cookly.*`。这是当前代码里的真实行为。
+
+## PlaceholderAPI
+
+如果服务器安装了 PlaceholderAPI，插件会注册 `cookly` 前缀。
+
+当前已实现的占位符形式：
+
+- `%cookly_cooker_<id>_amount%`
+- `%cookly_cooker_<id>_active%`
+- `%cookly_cooker_<id>_normal%`
+
+含义分别是：
+
+- `amount`：玩家拥有或放置的该锅具总数
+- `active`：当前处于烹饪中的数量
+- `normal`：当前空闲中的数量
+
+示例：
+
+```text
+%cookly_cooker_iron_pot_amount%
+%cookly_cooker_iron_pot_active%
+%cookly_cooker_iron_pot_normal%
+```
+
+占位符前缀之所以还是 `cookly`，是因为扩展类 `CooklyExpansion` 当前就是按这个名字注册的。

docs/matrixcook/configuration.mdx

@@ -0,0 +1,49 @@
+---
+title: 配置说明
+description: MatrixCook 的全局配置与存储配置。
+---
+
+# 配置说明
+
+`config.yml` 负责全局语言、全息高度、燃料耗尽超时和放置状态存储。
+
+## `config.yml`
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `language.default` | `zh_cn` | 默认语言文件 |
+| `hologram.height` | `1.5` | 全息文字相对锅具的高度 |
+| `cooking.fuel_out_timeout` | `60` | 燃料耗尽后，锅具进入失败判定前的秒数 |
+| `database.type` | `sqlite` | 放置状态存储类型 |
+| `database.flush_interval` | `10` | 异步刷盘间隔，单位秒 |
+| `database.table` | `matrixcook_placed_cookers` | SQL 表名 |
+| `database.sqlite.file` | `data/matrixcook.db` | SQLite 文件路径 |
+| `database.mysql.*` | 见默认配置 | MySQL 连接参数 |
+| `database.redis.*` | 见默认配置 | Redis 键空间与连接参数 |
+
+## 存储类型
+
+当前代码支持 4 种放置状态存储：
+
+| 类型 | 说明 |
+| --- | --- |
+| `sqlite` | 默认选项，单机最省事 |
+| `mysql` | 多服或外部数据库环境可用 |
+| `redis` | 运行态快照写入 Redis key |
+| `yaml` | 兼容旧版 `data/placed_cookers.yml` |
+
+需要注意的是，存储后端只负责“已放置锅具”的运行态数据，不负责锅具、配方、燃料这些静态配置。
+
+## 旧版数据迁移
+
+如果当前配置使用的存储后端还是空的，而 `plugins/MatrixCook/data/placed_cookers.yml` 存在，`ConfigManager` 会尝试把旧 YAML 数据迁移到新的后端，然后把旧文件改名为 `.migrated`。
+
+## 自动保存
+
+放置状态不会每次都同步写盘，而是通过：
+
+- 配置变更后的强制持久化
+- 周期性自动刷盘
+- 服务器关闭前的同步落盘
+
+这也是 `database.flush_interval` 存在的原因。

docs/matrixcook/cookers-and-recipes.mdx

@@ -0,0 +1,154 @@
+---
+title: 锅具、配方与燃料
+description: MatrixCook 的核心 YAML 结构。
+---
+
+# 锅具、配方与燃料
+
+MatrixCook 的核心配置分布在 4 个目录：
+
+- `cooker/`：锅具定义
+- `recipe/`：配方定义
+- `fuel/`：燃料定义
+- `categories/`：分类定义
+
+## 锅具文件
+
+锅具示例 `cooker/iron_pot.yml` 包含这些重点字段：
+
+```yaml
+iron_pot:
+  permission: "cookly.cooker.iron_pot"
+  properties:
+    speed: 1.0
+    allowed_recipes:
+      - "fried_egg"
+  hologram:
+    idle:
+      - "&7铁锅"
+    cooking:
+      - "&7铁锅"
+      - "&a烹饪中 %progress%"
+  items:
+    hand:
+      type: "CAULDRON"
+      custom-model-data: 1001
+    placed:
+      source: "minecraft"
+      type: "block"
+      id: "CAMPFIRE"
+  gui:
+    title: "&6铁锅"
+    layout:
+      - "AAAAAAAAA"
+      - "AAIAIAIAA"
+      - "AAAAFAAAA"
+      - "AAAAOAAAA"
+      - "AAAACAAAA"
+```
+
+### 关键点
+
+- `permission`：玩家是否可以使用这个锅具。
+- `properties.speed`：速度倍率。真实烹饪时间会用 `配方时间 / speed` 计算。
+- `properties.allowed_recipes`：留空表示允许全部配方。
+- `items.hand`：玩家手里拿到的锅具物品。
+- `items.placed`：放下后在世界中对应的实体或方块。
+
+`items.placed` 支持：
+
+- `source`: `minecraft`、`craftengine`、`itemsadder`
+- `type`: `block`、`furniture`
+
+如果你使用 CraftEngine 或 ItemsAdder，锅具的放置监听会分别由对应的监听器处理。
+
+## 配方文件
+
+配方示例 `recipe/basic.yml` 使用这些字段：
+
+```yaml
+fried_egg:
+  permission: "cookly.recipe.fried_egg"
+  ingredients:
+    - "EGG:1"
+  cooking_time: 10
+  result:
+    item:
+      type: "COOKED_CHICKEN"
+      name: "&6煎蛋"
+    amount: 1
+    actions: []
+  failure:
+    item:
+      type: "CHARCOAL"
+      name: "&7烧焦的食物"
+    actions: []
+```
+
+### 配方规则
+
+- `ingredients` 支持 `物品ID:数量`。
+- 也支持分类写法，例如 `categories:蔬菜:2`。
+- `allowed_fuels` 留空表示兼容所有燃料。
+- `result.actions` / `failure.actions` 会在完成后执行 Kether 动作。
+
+### 批量烹饪
+
+如果当前锅具内的原料足够多，`CookingManager` 会计算最大批次数，并连续处理下一锅。中途如果输出槽满了，或原料不再满足，就会停止批量流程。
+
+### 燃料耗尽失败
+
+烹饪中如果燃料耗尽，锅具会进入 `FUEL_OUT` 状态。超过 `config.yml` 中的 `cooking.fuel_out_timeout` 后，当前配方会走 `failure` 分支。
+
+## 燃料文件
+
+`fuel/fuels.yml` 支持两种常见写法：
+
+1. 只按物品类型匹配
+2. 按完整名称、Lore、CMD 精确匹配
+
+示例：
+
+```yaml
+煤炭:
+  item:
+    type: "COAL"
+  time: 1
+
+超级煤炭:
+  item:
+    type: "COAL"
+    name: "&e超级煤炭"
+  time: 100
+```
+
+如果 `item` 里只写了 `type`，任何同类型物品都能作为燃料；一旦加入 `name`、`lore` 或 `custom-model-data`，就会变成严格匹配。
+
+## 分类文件
+
+`categories/example.yml` 的结构是：
+
+```yaml
+categories:
+  蔬菜:
+    display: "蔬菜"
+    list:
+      - "minecraft:carrot"
+      - "minecraft:potato"
+```
+
+分类的用途主要有两个：
+
+- 作为配方原料条件，例如 `categories:蔬菜:2`
+- 作为燃料来源，例如 `categories:木质物品`
+
+## 物品 ID 规则
+
+`ItemData` 最终通过 Arim 物品解析器构建物品。当前文档里最常用的写法有：
+
+- 原版：`minecraft:stone`
+- 省略前缀时默认按原版处理，例如 `DIAMOND`
+- CraftEngine：`ce:namespace:item`
+- 分类：`categories:<分类ID>`
+
+如果你使用 ItemsAdder，自定义物品也可以按其命名空间 ID 参与匹配和生成。

docs/matrixcook/faq.mdx

@@ -0,0 +1,55 @@
+---
+title: 常见问题
+description: MatrixCook 的排错与注意事项。
+---
+
+# 常见问题
+
+## 为什么命令是 `matrixcook`，但权限和占位符里还有 `cookly`
+
+这是当前代码保留下来的兼容痕迹：
+
+- 命令权限走 `matrixcook.*`
+- 锅具/配方默认权限走 `cookly.*`
+- PlaceholderAPI 前缀也是 `cookly`
+
+写权限组和记分板时要按这个现状处理。
+
+## 为什么配方明明写了却匹配不上
+
+优先检查这几项：
+
+- 当前锅具 `allowed_recipes` 是否允许这条配方
+- 原料数量是否满足 `ingredients`
+- 配方权限是否真的给到了玩家
+- 如果用了分类，`categories/*.yml` 里的物品 ID 是否正确
+
+## 为什么燃料放进去没有反应
+
+`FuelConfig` 的匹配逻辑分两档：
+
+- 只写 `type` 时，按材质匹配
+- 写了 `name`、`lore`、`custom-model-data` 后，要求完全匹配
+
+另外，配方如果声明了 `allowed_fuels`，不在名单里的燃料也不会被消耗。
+
+## 为什么没有全息文字
+
+全息系统需要以下两者之一：
+
+- `DecentHolograms`
+- `CMI`
+
+如果两者都没装，锅具依然能工作，只是不会创建全息提示。
+
+## 存档会不会自动迁移
+
+会。当前后端为空而旧版 `data/placed_cookers.yml` 存在时，插件会尝试导入旧数据，并把原文件改名为 `.migrated`。
+
+## 什么时候该用 `minecraft`，什么时候该用 `craftengine` / `itemsadder`
+
+- 纯原版方块锅具：用 `minecraft`
+- 自定义方块或家具来自 CraftEngine：用 `craftengine`
+- 自定义方块或家具来自 ItemsAdder：用 `itemsadder`
+
+放置来源和监听器必须与实际使用的物品系统一致，否则放下去之后不会被识别为锅具。