- 版权类型
- 原创
- 插件中文名称
- 仙鱼
- 插件英文名称
- WoIdleFish
- 原帖地址
- #
- 支持的核心（服务端）
- Spigot
- Paper
- Folia
- Purpur
- 语言支持
- 中文（简体）
- 前置组件
- 无硬前置
- 适配版本（Java）
- 26.x
- 1.21
[MD]
# 仙鱼 WoIdleFish · 委托市场
**一个面向生存服的服务委托市场。**玩家发布委托或服务，双方自由报价还价，钱和物品全程托管，在确认验收之后交给对方，谈不拢还可以请管理员介入。
**零命令也能用。** GUI菜单功能齐全，需要打字的地方都在聊天栏分步引导。
**钱和物都托管。** 交割那一刻人不在线、背包满、自定义物品插件没加载，物品会进「待领取箱」，上线自动发或 `/xy claim` 手动领。
---
| | |
| -------- | ---------------------------------------------------- |
| **版本** | 2.3.1 |
| **作者** | LittleWo |
| **支持核心** | Spigot / Paper / Purpur / Folia |
| **支持版本** | Minecraft 1.21.x ~ 26.x |
| **必需依赖** | 无（自带内置余额，零依赖可跑） |
| **可选依赖** | Vault（接第三方经济）、ItemsAdder / Nexo / CraftEngine（自定义物品） |
| **命令入口** | `/xianyu`（别名 `/xy`） |
---
[ATTACH type="full" width="391px" size="889x959"]149935[/ATTACH]
[ATTACH type="full" width="519px" size="955x421"]149936[/ATTACH]
## 交易流程简介
**委托**（发布者出钱，接单者出力）
```
A 发布 → B 报价 → A 接受 → A 付款到托管 → B 开始 → B 申请验收 → A 验收 → 打款给 B
```
**服务**（发布者出力，接单者出钱）
```
A 发布 → B 报价 → A 接受 → B 付款到托管 → A 开始 → A 申请验收 → B 验收 → 打款给 A
```
**履约保证金**（可选，默认关闭）：双方可各按成交价的一定比例缴纳保证金。资金托管之后**谁单方违约退出，谁的保证金就赔给对手方，托管款原路退回付款方**。
---
## 功能一览
### 交易与协商
| 功能 | 说明 |
| ----------- | ------------------------------------------------ |
| **报价 / 还价** | A 报 → B 还 → A 再还 → B 再还可以**无限来回**，直到有一方按下「确认接受」。 |
| **价格洽谈界面** | 挑人、还价、接受。上半块是「发给我、等我回应的」，下半块是「我发出去、还在等对方」的，一眼看清。 |
| **留言板** | 每张订单可留言协商细节，带未读计数，上线时自动提醒。 |
| **有效期** | 发布时可设天数，无人接单到期自动下架。 |
| **管理员介入** | 谈不拢可申请介入，管理员在专用GUI界面里逐张处理，裁定打款或退款。 |
### 经济
| 功能 | 说明 |
| --------- | --------------------------------------------------------------------------------- |
| **经济后端** | 优先用 Vault 接第三方经济插件；没装或主动关闭时，自动使用插件内置余额（零依赖可跑）。 |
| **手续费** | 成交时从「收钱一方所得」里按比例扣除，可设最低值；手续费可直接销当做回收货币销毁或转给指定账户。 |
| **履约保证金** | 默认关闭（`percent: 0.0`），双方可各按成交价的一定比例缴纳保证金。资金托管之后**谁单方违约退出，谁的保证金就赔给对手方，托管款原路退回付款方**。 |
| **统计与流水** | `/xy admin stats` 看累计成交与手续费；每笔资金动作追加到 `logs/economy.log`，可事后对账。（仅管理员） |
### 物品托管
订单除了押钱，还能**押东西**。订单详情页有「物品托管」入口：
- **当事人**点进去 = 自己的托管仓，真箱子界面，直接存取，关掉界面即保存；
- **旁观者**点进去 = 双方托管总览，只读。
**注意：**两侧锁定时机不同：**付款方仓**在资金托管那一刻锁定（对方就是看着这仓报酬开工的）；**交付方仓**在按下「申请验收」那一刻锁定（在那之前他还在备货，理应随时能拿回来）。
**自定义物品支持：**ItemsAdder / Nexo / CraftEngine
### 其他
| 功能 | 说明 |
| --------- | --------------------------------------- |
| **关键词订阅** | `/xy sub <关键词>`，有人上架命中关键词的新订单就私聊提醒玩家。 |
| **收藏** | 收藏感兴趣的订单，界面里可只看收藏。 |
| **热重载** | `/xy reload` 重读配置与文案，**不动订单数据**，改完立刻生效。 |
---
## 命令
**玩家命令**（GUI菜单可操作，一般用不到，权限 `woidlefish.use`，默认所有玩家可用）
| 命令 | 作用 |
| --------------------------------------------------- | ----------------------- |
| `/xy` | 打开市场界面（不带参数，最常用） |
| `/xy help` | 查看帮助 |
| `/xy list` | 列出订单 |
| `/xy create <demand\|service> <价格\|-> <标题> [\| 描述]` | 发布委托 / 服务（价格写 `-` 表示面议） |
| `/xy view <编号>` | 查看订单详情 |
| `/xy info <编号>` | 查看订单信息 |
| `/xy offer <编号> <金额> [玩家\|-] [备注]` | 报价 / 还价（备注可省略） |
| `/xy accept <编号> [玩家]` | 接受报价（多人报价时要点名，价格就此商定） |
| `/xy pay <编号>` | 付款到托管 |
| `/xy start <编号>` | 开始执行 |
| `/xy done <编号>` | 申请验收 |
| `/xy confirm <编号>` | 验收通过（打款，扣手续费） |
| `/xy dispute <编号> [理由]` | 申请管理员介入 |
| `/xy board <编号>` | 查看留言板 |
| `/xy msg <编号> <内容>` | 给这张订单留言 |
| `/xy cancel <编号>` | 取消订单（仅在未托管时） |
| `/xy mine` | 我的订单 |
| `/xy fav <编号>` | 收藏 / 取消收藏 |
| `/xy sub <关键词>` | 订阅关键词 |
| `/xy unsub <关键词>` | 取消订阅 |
| `/xy subs` | 查看已订阅的词 |
| `/xy items <编号>` | 打开自己在这张订单里的物品托管仓 |
| `/xy claim` | 领取还没发到手上的托管物品 |
| `/xy reload` | 重载配置与文案（需管理员权限） |
**管理员命令**（GUI菜单可操作，一般用不到，权限 `woidlefish.admin`，默认 OP）
| 命令 | 作用 |
| -------------------------------------- | ---------------------- |
| `/xy admin resolve <编号> <pay\|refund>` | 裁定争议：打款给交付方 / 退款给付款方 |
| `/xy admin disputes` | 打开待处理争议订单列表界面 |
| `/xy admin give <玩家> <金额>` | 发放内置余额 |
| `/xy admin take <玩家> <金额>` | 回收内置余额 |
| `/xy admin cleanup` | 手动清理超过保留期的订单 |
| `/xy admin info` | 查看插件信息 |
| `/xy admin stats` | 查看服务器累计统计 |
| `/xy admin upgrade` | 手动补齐配置与文案文件（只补文件，不改数据） |
| `/xy admin reload` | 等同 `/xy reload` |
> 所有带 `<编号>` 的命令都有对应的**界面入口**，玩家不必记命令。
---
## 权限
| 权限节点 | 默认 | 说明 |
| ------------------ | ------ | ------------------------- |
| `woidlefish.use` | `true` | 使用市场的基础功能（发布、报价、交易等） |
| `woidlefish.admin` | `op` | 管理员指令：处理争议、清理数据、发放余额、重载配置 |
---
## 配置项
首次启动生成 `plugins/WoIdleFish/config.yml`，全部带中文注释。
```yaml
# ------------------------------------------------------------------ 经济
economy:
use-vault: true # 装了 Vault 就优先用第三方货币；否则用内置余额
internal-currency: "金币" # 内置余额的货币名
internal-symbol: "¤" # 内置余额的货币符号
min-price: 1.0 # 允许的最小金额
max-price: 1000000.0 # 允许的最大金额
# ------------------------------------------------------------------ 手续费
fee:
percent: 2.0 # 成交时从「收钱一方」扣除的百分比，0 = 关闭
minimum: 0.0 # 每单最低手续费
recipient: "" # 留空 = 直接销毁；填玩家名 = 转给该账户
# ------------------------------------------------------------------ 市场
market:
max-title-length: 32 # 标题最大长度
max-description-lines: 5 # 描述最多几行
max-open-orders-per-player: 5 # 每人同时挂出的未完成订单上限
max-note-length: 60 # 报价备注最大长度
ask-offer-note: true # 界面报价时是否多问一步「备注」
max-reason-length: 60 # 介入理由最大长度
completed-retention-days: 30 # 终态订单保留天数（0 = 永久保留）
cleanup-interval-minutes: 60 # 自动清理检查间隔（分钟）
default-expire-days: 0 # 默认有效期天数（0 = 永久）
max-expire-days: 30 # 玩家可选的最大有效期天数
# ------------------------------------------------------------------ 履约保证金
deposit:
percent: 0.0 # 保证金比例，0 = 关闭（默认）
minimum: 0.0 # 每单最低保证金
maximum: 0.0 # 每单保证金上限，0 = 不设上限
# ------------------------------------------------------------------ 物品托管
items:
enabled: true # 是否允许订单托管物品
max-stacks: 27 # 单侧托管仓最多几格（1~54）
allow-custom-items: true # 是否允许存自定义物品（引用 + 整包备份）
# ------------------------------------------------------------------ 提醒
notify:
broadcast-new-order: true # 有新订单时全服播报
remind-unread-on-join: true # 上线时提醒未读留言
notify-subscribers: true # 私聊提醒订阅命中的玩家
notify-self: false # 自己发的单命中自己的订阅词时是否也提醒自己
# ------------------------------------------------------------------ 统计
stats:
economy-log: true # 是否把每笔资金动作写入 logs/economy.log
# ------------------------------------------------------------------ 留言板
board:
max-messages-per-order: 50 # 每张订单最多留言条数
max-message-length: 120 # 单条留言最大长度
rows: 6 # 留言板界面行数（2~6）
```
**数据与日志文件**（`plugins/WoIdleFish/` 下）：
| 文件 | 内容 |
| ------------------------ | --------------------- |
| `config.yml` | 上述配置 |
| `messages.yml` | 全部界面与聊天栏文案，可自定义 |
| `data/orders.yml` | 订单主数据 |
| `data/subscribes.yml` | 关键词订阅 |
| `data/favorites.yml` | 收藏 |
| `data/stats.yml` | 服务器累计统计（只累加不回退） |
| `data/pending-items.yml` | 待领取物品箱 |
| `logs/economy.log` | 逐笔资金流水（追加，不修改） |
| `backup/` | 升级前的配置备份（每份保留 10 个版本） |
---
## 安装
1. **放到服务端。** 把 `WoIdleFish-x.x.x.jar` 放进服务端的 `plugins/` 目录。
2. **重启服务端。**
3. **（可选）接经济。** 想要用服务器现有货币，装好 `Vault` + 任意经济插件（EssentialsX / CMI 等）即可，插件会自动识别；不装则用内置余额。
4. **开始用。** 玩家输入 `/xy` 打开市场界面，或让管理员用 `/xy admin give <玩家> <金额>` 先发点内置余额试试。
**升级**：直接替换 jar 重启。新增的配置项与文案会自动补进你的文件，旧文件先备份到 `backup/`。
---
## 常见问题
**Q：插件会判断委托做完了没有吗？**
不会。仙鱼刻意不做裁判，验收通过与否由玩家点确认，谈不拢请管理员介入。
**Q：玩家中途下线，托管的物品会丢吗？**
不会。交割那一刻人不在线、背包满、或自定义物品还原失败，物品会进入「待领取箱」，下次上线自动发放，也可以 `/xy claim` 手动领。
**Q：手续费谁出？**
收钱的一方。
**Q：没装 Vault 能用吗？**
能。插件自带内置余额，`/xy admin give|take` 可以发放和回收。
**Q：改了配置要重启吗？**
不用。`/xy reload` 即时生效，但「切换经济后端」和「自定义物品适配」需要重启。
**Q：`/xy reload` 连订单数据一起重载吗？**
不重载。要动数据请先关服。
**Q：支持哪些自定义物品插件？**
ItemsAdder、Nexo、CraftEngine。
**Q：支持 Folia 吗？**
理论上支持。
---
## 更新日志
### 2.3.1
- 首次公开发布。
---
## 联系作者
### *发送邮件到 block409@foxmail.com*
[/MD]
