临时权限 · 插件策划案

TEMP APPLY — DESIGN DOCUMENT V1.0.0

把"临时借权限"做成产品:一份写给开发者与决策者的完整设计文档——从痛点分析、竞品对比,到权限租约模型、三级审批管线、回收引擎与发布路线。

版本 v1.0.0 已发布 平台 Paper / Spigot 1.20 – 1.21.x 审批 规则 → AI → 人工 存储 SQLite / MySQL
CHAPTER 01

概述

要解决的问题只有一句话:玩家想要 30 分钟的飞行或一小会儿创造模式,唯一的正规途径是在线私聊管理员;管理员要么守着后台批复,要么给了权限忘了收,埋下永久开放的隐患。

TempApply 的答案是权限租约:每一次授权都是一条带到期时间的记录。玩家像点外卖一样自助下单(含时长、参数与用途说明),系统先做规则校验,可选地交给 AI 预审,最后落到管理员的一次点击;到期那一刻,回收引擎把玩家的状态精确还原到授权前

PRINCIPLE 01一切授权皆有期限

不存在"永久的临时权限"。每条租约有 default-duration 缺省值与 max 硬顶,超出区间的请求直接被前置规则拦截。

PRINCIPLE 02零门槛申请,可解释裁决

申请入口收敛为一个 /apply;理由字段强制追问时面向导逐句引导。拒了要有说法,驳回事由随审批结果回传玩家。

PRINCIPLE 03渐进增强的自动化

不装 License-Key、不开 AI,插件照常工作;开箱能力与增强能力分层,避免"高配才能跑"。

PRINCIPLE 04到期还原,而非粗暴踢出

回收动作按类型定制:创造模式还原因子里之前的生存状态、飞行归还速度、命令额度清零——而不是一刀切传回主城。

CHAPTER 02

竞品分析

同类需求的现有解法可分为三种:纯人工管理权限组限时工具闭源商业申请面板。它们分别输在效率、粒度与透明度上。

方案典型做法时效控制审计留痕玩家门槛管理负担
纯人工管理
(多数中小服现状)
群里 @ 管理员 → 手敲 give / gamemode → 靠人脑记住收回 靠自觉 看脸 极高
LuckPerms 限时权限 lp user … permission settemp 按节点计时 节点级 日志散落 要懂节点名
闭源商业申请面板 付费插件内置 GUI 审批,部分绑定独立 Web 后台 黑盒
TempApply 七类语义模板 + 租约模型 + 规则/AI/人工三级审批 + 统一回收入库 到期必收 全链路留痕 一个命令 一键批

把四个维度拉开距离再看:TempApply 的差异化不在"能不能限时"(LP 已经做到),而在把授权改成完整的申请-裁决-回收闭环,并把其中最耗人的环节(初筛)交给规则与 AI。

易用性 可控性 审计性 扩展性 性能成本
图 2-1 · 五维对比:实线为 TempApply,虚线为"纯人工管理"基线(分值为设计目标评估)

VS MANUAL相较纯人工

  • 收回不再依赖人脑:到期引擎是确定性程序
  • 每一次给权都有记录可查,可追溯"谁批的、为什么"
  • 玩家自助申请,管理员的碎片时间得以解放

VS LUCKPERMS TIMED相较权限组限时

  • 玩家不需要理解"节点名",只需要描述想要什么
  • 回收语义内建:创造还原因子、飞行还速度,而非单纯摘除节点
  • 带审批与理由留痕,LP 的 temp 接口只是底层构件之一
CHAPTER 03

核心玩法设计

整个插件的玩法可以压缩成一句话:权限是一次租借,不是一次赠予。玩家发起租借 → 系统裁决 → 定时归还,三个环节各自有独立的产品设计。

① 申请提交 GUI 菜单 / apply 直提 ② 排队待审 规则初筛 → AI → 人工 ③ 生效中 倒计时开始跑 ④ 到期预警 提前数分钟提醒玩家 ⑤ 自动回收 revoke 还原授权前现场 超时自动驳回 超过 auto-deny-time 未裁决即关闭申请 租期结束可随时再申请新周期,历史记录全部留档
图 3-1 · 权限租约生命周期:主链五阶段 + 一个旁路出口 + 一个闭环回路

七张权卡:一类权限一种语义

七类类型不是同一个开关的七个马甲——每类都定义了独立的授权动作归还动作,参数面也完全不同:

类型典型场景关键参数(节选)形态
bot召唤一个临时机器人替身看家、陪跑任务spawn / remove 指令模板占位符、同人并发上限、强制理由持续存在
fly建筑高空作业、长途赶路观光默认 60 min → 上限 120 min、飞行速度 1–5 档持续
tp直达队友身边、跳转指定坐标或出生点目标三选一:coordinates / player / spawn瞬时
creative大型建筑白盒施工高危方块黑名单、log-actions 行为留痕持续·高风险
give应急领取建材工具等物资单次数额上限、下界合金/金苹果等高危清单拦截瞬时发放
cmd临时放行某条受限指令的使用额度按次扣减计数、封禁清单(stop / reload / op / *计次消耗
pvp在某片区域开启限时切磋授权粒度为区域名,预置 WorldGuard 对接点区域内持续

唯一的例外是 give:物品一经发放即归属玩家所有,因此它天然没有回收语义——这也是它的高危清单最严格的原因。其余六类到期统一进入还原流程。

CHAPTER 04

功能需求

功能拆成六个模块:申请通道、审批工作台、回收引擎、通知中枢、AI 审核、数据存储。前两者面向日常使用,后四者决定系统可靠性与扩展性。

MODULE A申请通道

  • /apply 菜单逐类型浏览说明与限额
  • 命令行 key=value 参数直通车
  • 强制理由时向导逐步追问

MODULE B审批工作台

  • /tadmin 待审队列 + 详情五要素
  • 批准 / 驳回(附事由)一键完成
  • instaapprove 即批节点供值班号

MODULE C回收引擎

  • 集中调度器按到期时间精准触发
  • 每类授权登记专属还原动作
  • 上线补查,防止停机跨天泄漏

MODULE D通知中枢

  • 游戏内提醒推给 notify 组管理员
  • SMTP 邮件支持 QQ/163/Gmail 预设
  • QQ 群机器人按群/频道白名单推送

MODULE EAI 审核

  • License-Key 激活后才可开启
  • 六家模型预设 + custom 端点
  • 仅作预审建议,最终仍归人工

MODULE F数据存储

  • SQLite 默认零配置起步
  • MySQL 一键切换适配集群
  • 版本升级自动迁移表结构

命令速查

命令用途所需权限
/apply打开 GUI 申请菜单tempapply.use(所有人)
/apply <type> [k=v ...] [duration=m] [reason=...]带参数直接提交申请tempapply.use
/tadmin打开管理台,默认展示待审列表tempapply.admin(OP)
/tadmin approve <id>批准对应申请,立即生效并开始计时tempapply.admin
/tadmin deny <id> [驳回理由]驳回并把事由反馈给申请人tempapply.admin
别名:apply ≡ tapply / tempapply · tadmin ≡ taadmin / applyadmin
CHAPTER 05

性能设计

一个常驻后台的申请系统最容易在两处失控:每 tick 的轮询主线程上的 IO。TempApply 用三条硬约束把两者都关在门外。

CONSTRAINT 01不做高频轮询

到期检测不挂 PlayerMoveEvent 这类每帧事件。集中调度器只持有"最近到期时间",到点才醒,空闲期零开销。

CONSTRAINT 02事件面极窄

全程只监听三类低频事件:玩家上线补查、聊天向导会话窗口内的发言、命令本身。离开向导即静默。

CONSTRAINT 03出网全部异线程

SMTP 邮件、QQ 推送、AI 请求都在异步线程完成;主线程仅做状态翻转与库存操作,卡顿无处藏身。

到期检测方案触发时机代价特征结论
移动事件轮询(常见劣质实现) 每次玩家移动都比对全部授权 O(在线人数 × 租约数)/tick 否决
TempApply 集中调度器 仅有新授权或临近到期时唤醒一次 O(待触发数),平摊≈0 采用

存储层同样遵守保守原则:SQLite 默认足够(典型服每周写入量级不过数千行),MySQL 仅作大规模部署的可选件;所有状态变更走批量事务提交,避免逐条刷盘。

CHAPTER 06

命令与权限设计

命令面向两类人各留一条路:玩家要一眼看懂,管理员要一步到位。权限节点遵循最小授予原则,危险能力默认关闭。

权限节点含义默认
tempapply.use使用 /apply 提交申请所有人
tempapply.admin使用 /tadmin 审批台及子命令OP
tempapply.notify接收游戏内新申请 / 到期提醒OP
tempapply.bypass.limit无视并发数量限制提交申请OP
tempapply.bypass.duration无视单次时长上限OP
tempapply.admin.instaapprove详情页出现"即时批准"按钮关闭

未接入权限插件时按上表默认值工作;检测到 LuckPerms 后自动走其节点查询(soft-depend,非硬绑定),方便用组策略批量管理审批组。

CHAPTER 07

配置文件

配置按"存储 → 权限类型 → 自动化 → 通知 → 全局"五大块组织,每个权限类型的时长、上限、黑白名单自成一体,互不干扰。

# TempApply 主配置 · 节选示意(完整键位以发布包 config.yml 为准)
storage:
  type: sqlite                       # sqlite / mysql

permissions:
  fly:
    default-duration: 60            # 缺省时长(分钟)
    max-duration: 120               # 单次硬顶
    max-speed: 5
  creative:
    risk-level: HIGH
    blocked-items: [...]            # 违禁物品黑名单
    log-actions: true
  give:
    max-item-amount: 64
    high-risk-items: [...]         # 下界合金·金苹果·图腾等
  cmd:
    blocked-commands: ["stop", "reload", "op", "*"]

license-key:
  enabled: true
ai-review:
  enabled: false                    # License-Key 激活后可开启
  provider: deepseek               # deepseek/openai/zhipu/qwen/moonshot/siliconflow/custom
  protocol: openai-chat            # openai-chat/anthropic-messages/google-gemini

notify:
  mail:
    provider: qq                   # qq / 163 / gmail
    admin-emails: ["..."]
  qq-bot:
    group-openids: ["..."]

general:
  language: zh_CN
  auto-deny-time: 24h              # 超时未裁决自动驳回
  notify-before-expire: 5m         # 到期前预告

热路径参数(时长、上限、黑白名单)改动无需重启核心逻辑,配合 /tadmin 即可验证效果;涉及存储切换的调整则建议低峰操作。

CHAPTER 08

开发计划

四个里程碑走完从概念到发布的全程。目前 M0–M3 已全部达成,v1.0.0 已正式发布

MILESTONE M0设计定稿 已完成

痛点调研、竞品三维对比、七类语义与租约模型评审冻结,产出本文档初版。

MILESTONE M1核心管线 已完成

申请-审批-回收闭环跑通:ApplyService 生命周期、抽象 PermissionType 七实现、SQLite 存储与中文文案。

MILESTONE M2双通道体验 已完成

GUI 菜单与聊天向导双入口落地;邮件 / QQ 群通知上线;并发与时长的限流体系生效。

MILESTONE M3AI 与发布 已完成 · v1.0.0

License-Key 解锁 AI 预审管线(六厂商预设);paper / spigot 双构建;文档站三页同步上线。

CHAPTER 09

风险与应对

逐项评估五类主要风险的概率与影响,并为每一项给出已经内建的缓解机制。

风险概率影响已内建的应对
借创造模式搬运违禁物品 黑名单前置拦截 + log-actions 全程留痕 + 驳回事由回传形成申诉闭环
AI 预审误放行高危申请 AI 只出建议不直接给权,管理员终审兜底;漂移回看定期校准判断标准
邮件 / QQ 凭据配错静默丢失 发送失败自动回落游戏内 notify 提醒,任何申请都不会成为孤儿单
停机跨天错过到期回收点 玩家上线逐一补查 + 服务启动全量对账,双保险清理越期授权
大型服 MySQL 抖动拖慢审批 批量事务合并写盘,必要时一键切回本地 SQLite 维持运转