koishi-plugin-monetary-mission

koishi-plugin-monetary-mission

为 Koishi 的货币系统提供任务/悬赏功能。插件支持管理员直接发布任务、普通用户付费提交任务（管理员审核）、用户接取/完成任务并领取奖励，以及灵活的手续费与押金逻辑。

特性

• 管理员与用户双向发布任务：管理员可直接发布，用户发布需管理员审核。
• 完成条件可配置：手动确认、计数（count）、关键词、或自定义扩展。
• 多种任务结束条件：按时间、接取人数、完成人数或手动结束。
• 自动管理押金与手续费：货币奖励按比例收取手续费，自定义奖励收固定手续费。
• 内置审核流程：同意、拒绝、修改（待用户确认）与退还押金逻辑。
• 图形化界面：支持 puppeteer 渲染精美的任务卡片、详情页、发布指南和审核面板。

依赖与兼容

• Koishi v4（参见 peerDependencies）。
• 依赖数据库服务（必需）。
• 可选集成 koishi-plugin-monetary（若存在将用于货币扣除/发放）。
• 可选集成 koishi-plugin-puppeteer（若存在将启用图形化输出）。

安装

在你的 bot 项目中安装并构建插件：

npm install koishi-plugin-monetary-mission --save
# 或者在本地开发时
npm run build

然后在 Koishi 配置中加载该插件。

配置项

配置位于 Koishi 插件配置项中（示例为默认值）：

• currency：默认货币单位，默认为 信用点。
• baseServiceFee：发布任务基础手续费（数额），默认 100。
• rewardFeeRate：货币奖励手续费比例（%），默认 20。
• customRewardFee：自定义奖励固定手续费，默认 500。
• depositRate：奖励押金比例（%），默认 100（用于按接取人数预付押金）。
• allowUserPublish：是否允许普通用户发布（默认 true）。
• adminFreePublish：管理员发布是否免手续费（默认 true）。
• pageSize：任务列表分页大小，默认 10。
• enableGraphics：是否启用图形化输出（需要 puppeteer 服务），默认 true。

示例（Koishi 配置片段）：

{
	"plugins": {
		"koishi-plugin-monetary-mission": {
			"currency": "信用点",
			"baseServiceFee": 100,
			"rewardFeeRate": 20,
			"customRewardFee": 500,
			"depositRate": 100,
			"enableGraphics": true
		}
	}
}

指令概览

用户指令：

• mission.list [页码]：查看任务列表（默认只显示进行中，支持图形化卡片）。
  • -m 只看我接取的任务
  • -a 显示所有任务（包括已结束）
  • --text 强制使用文字输出
• mission.view <id>：查看任务详情及自己的完成/接取状态（支持图形化详情页）。
  • --text 强制使用文字输出
• mission.accept <id>：接取任务。
• mission.abandon <id>：放弃任务。
• mission.progress <id> [count]：更新计数类任务进度（默认 +1）。
• mission.guide：查看发布任务的帮助指引（支持图形化指南）。
• mission.publish -t <标题> -d <描述> [-r <奖励>] [-c <自定义奖励>]：用户发布任务（需审核）。
• mission.pending：查看自己提交的待审核任务。
• mission.confirm <id>：确认管理员修改并同意发布（若被修改需补差价或退款）。
• mission.cancel <id>：撤回待审核任务并退还押金（手续费不退）。

管理员指令（需要 authority >= 3）：

• mission.admin.publish：管理员直接发布任务（无须审核）。
• mission.admin.review：列出所有待审核任务（支持图形化审核面板）。
  • --text 强制使用文字输出
• mission.admin.approve <id>：同意发布并将任务入库。
• mission.admin.reject <id> -n <备注>：拒绝发布并退还押金（手续费不退）。
• mission.admin.modify <id> -f <手续费> -n <说明>：修改手续费并标记为需用户确认。
• mission.admin.end <id>：手动结束任务（不会影响已接取的正在进行中的用户）。
• mission.admin.complete <taskId> <userId>：手动确认指定用户完成任务并发放奖励。
• mission.admin.delete <id>：删除任务，可选择退还剩余押金。

图形化界面

本插件支持图形化输出，需要安装并启用 koishi-plugin-puppeteer 服务。启用后，以下功能将以精美的图片卡片形式展示：

• 任务列表 (mission.list)：深色主题卡片，显示任务状态、奖励、接取/完成人数
• 任务详情 (mission.view)：完整的任务信息卡片，包含进度条显示
• 发布指南 (mission.guide)：交互式指南，展示所有参数说明和费用计算
• 审核面板 (mission.admin.review)：管理员专用，快速审核待处理任务

如果 puppeteer 服务不可用，或使用 --text 选项，将自动回退到纯文字输出。

示例：

mission.publish -t "帮忙测试" -d "转发群公告" -r 50 -m 3 --cond count --target 5
mission.admin.review
mission.admin.approve 12
mission.accept 12
mission.progress 12 2

数据库表（简介）

插件会在 Koishi 的数据库中创建三张表：

• mission_task：已发布任务记录（id、标题、描述、发布者、奖励、条件、当前接取/完成人数、状态等）。
• mission_progress：用户任务进度（taskId、userId、uid、状态、进度数据、接取/完成时间）。
• mission_pending：用户提交的待审核任务（包含 paidFee、serviceFee、modifiedFee、reviewStatus、awaitingConfirm 等字段）。

请根据你的数据库管理策略备份或迁移这些表。

手续费与押金逻辑说明

• 用户发布任务时需计算并预付 totalFee = serviceFee + deposit。
  • serviceFee = baseServiceFee + （若为货币奖励）rewardAmount * rewardFeeRate / 100；若为自定义奖励则加上 customRewardFee。
  • deposit（仅货币奖励）= rewardAmount * maxAcceptCount * depositRate / 100。
• 管理员审核：
  • 同意：将任务发布到 mission_task，押金保留用于后续奖励发放。
  • 拒绝：退还押金（paidFee - serviceFee），手续费不退。
  • 修改：管理员可降低或提高手续费，若修改导致差价，需等待用户确认并补差价或退款。

工作流程示例

• 用户使用 mission.publish 提交任务并支付费用（手续费 + 押金）。
• 管理员使用 mission.admin.review 查看待审核任务。管理员可 approve / reject / modify。
• 若 approve，任务进入 mission_task，用户可 accept、完成并领取奖励。
• 若 reject，系统退还押金（手续费不退），并在 mission_pending 标记为 rejected。

注意：任务结束（例如到达截止时间）不会影响已被用户接取且正在进行的任务的结算，管理员可手动结束该任务但不会回退已发放的奖励。

开发与构建

源码位于插件的 src 目录，构建命令为：

npm run build

开发时建议本地引入 monetary 插件以便调试扣款/发放逻辑。

贡献与许可

欢迎提交 issue 与 PR。遵循 MIT 许可证。

更多实现细节请参阅源码：src/index.ts。