Opanel Extension Dev

OPanel 扩展开发

按照目标 OPanel 版本的公开 API 开发扩展。以用户指定的版本和当前仓库源码为准，不凭记忆补全 API，也不要把 OPanel 本体插件/模组开发方式套用到扩展项目。

确认上下文

1. 查找并遵守当前仓库的 AGENTS.md、构建约定和验证要求。
2. 检查已有的 build.gradle、extension.json、入口类和 src/main/resources/web，优先延续现有结构。
3. 明确目标 OPanel 版本。按以下优先级确定事实：
   • 用户明确指定的目标版本；
   • 目标仓库中的 api/ 源码、Javadoc、example-extension/ 和构建配置；
   • 用户给出的扩展开发指南；
   • 其他资料或模型记忆。
4. 若在 OPanel 主仓库中工作，先检查 api/src/main/java/cn/opanel/api 与 example-extension。若在独立扩展仓库中工作，核对目标版本实际发布的 opanel-api artifact。
5. 遇到指南、示例与源码不一致时，说明差异并采用目标运行版本的 API，不静默猜测。

参考指南的基线是 OPanel 2.2.0-pre5 及以上、JDK 14 及以上，并示例使用 Javalin 5.6.4。这些是该指南分支的基线，不代表所有未来版本；实现前仍要核对目标版本。

建立项目

独立 Gradle 项目使用 Java 插件，并把 OPanel API 声明为 compileOnly：

plugins {
    id 'java'
}

repositories {
    mavenCentral()
}

dependencies {
    compileOnly 'cn.opanel:opanel-api:<OPanel version>'
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(14)
    }
}

• 将 <OPanel version> 替换为目标服务端实际版本，不保留占位符。
• 在 OPanel 多模块仓库内开发示例扩展时，优先使用 compileOnly(project(":api"))。
• 仅在注册后端路由时添加与目标 OPanel 匹配的 Javalin compileOnly 依赖；指南基线为 io.javalin:javalin:5.6.4。
• 不要把 opanel-api 或 OPanel 提供的 Javalin 打进扩展 JAR。扩展自己的运行时第三方依赖必须随 JAR 提供；需要 Shadow 时，检查最终 JAR 与类加载冲突。

编写元数据

创建 src/main/resources/extension.json：

{
  "extId": "example-extension",
  "version": "1.0.0",
  "name": "Example Extension",
  "description": "An example OPanel extension.",
  "author": "Author Name",
  "pages": [
    {
      "name": "Example Page",
      "url": "/"
    }
  ]
}

保留并填写五个基础字段；按需添加 pages。extId 必须在所有已安装扩展中唯一；兼容当前实现时使用不超过 64 个字符的小写 kebab-case：[a-z0-9]+(?:-[a-z0-9]+)*。不要用显示名称、空格或下划线充当 ID。

pages 是可选的侧边栏页面注册数组；省略或设为 null 时不注册页面。每一项包含：

• name：侧边栏直接显示的非空页面名称。
• url：扩展 Web 根目录内的页面路径。必须非空、以单个 / 开头，且不能是绝对 URL、// 开头的 URL、反斜杠路径或包含 .. 路径段的路径。不要填写 /panel/ext/<extId> 前缀。

OPanel 将每项转换为 /panel/ext/<extId><url>，并显示在侧边栏的“扩展”分组中；同一扩展的页面保持数组声明顺序。例如，extId 为 example-extension、url 为 /reports/ 时，面板链接为 /panel/ext/example-extension/reports/。只为确实存在的扩展页面注册入口；pages 不会自动创建 HTML，也不是页面访问白名单。

实现入口与生命周期

一个扩展 JAR 必须恰好包含一个 @Extension 入口类：

package com.example.extension;

import cn.opanel.api.Extension;
import cn.opanel.api.ExtensionLoad;
import cn.opanel.api.ExtensionUnload;
import cn.opanel.api.OPanelAPI;

@Extension
public final class Main {
    private OPanelAPI api;

    @ExtensionLoad
    public void load(OPanelAPI api) {
        this.api = api;
        api.logInfo("Example extension loaded");
    }

    @ExtensionUnload
    public void unload() {
        api.logInfo("Example extension unloaded");
        // 停止扩展创建的线程、定时器并释放其他资源。
        api = null;
    }
}

严格保持以下契约：

• 入口类为 public、非抽象类，并提供 public 无参构造器。
• @ExtensionLoad 恰好一个，签名必须是 public void load(OPanelAPI api)。
• @ExtensionUnload 最多一个，签名必须是 public void unload()。
• 仅在加载完成到卸载开始之间使用传入的 API handle；卸载后调用会失败。
• 不在生命周期回调中执行可能阻塞或改变服务器状态的 API 操作。需要时创建扩展自有 worker，并在 unload() 中可靠关闭。
• 只依赖 cn.opanel.api.* 公共 API；除非任务明确要求修改 OPanel 本体，否则不要从扩展直接导入 net.opanel.* 内部实现。

注册后端路由

通过 OPanelAPI.addHandler 注册扩展命名空间内的相对路径：

import io.javalin.http.HandlerType;

api.addHandler("status", HandlerType.GET, ctx -> {
    ctx.json(java.util.Map.of("ok", true));
});

该路由暴露为 /api/extension/<extId>/status。

• 路径开头的 / 可省略；不要使用反斜杠或父目录片段。
• 使用 Javalin 5 Context/HandlerType 写法，并以目标 OPanel 所用版本为准。
• 当前实现按规范化后的路径保存路由；同一路径再次注册会替换旧 handler。若要在同一路径注册多个 HTTP 方法，先检查目标版本是否支持，不能想当然。
• 把 handler 当成服务器请求线程上的代码：校验输入、明确状态码、避免长时间阻塞，并处理 API 异常。
• 扩展后端位于 OPanel 鉴权范围内。用已登录面板会话测试，不要把它误当作无需鉴权的 Open API。

添加前端页面

把静态 HTML、CSS 和 JavaScript 放在 src/main/resources/web。只要扩展提供前端页面，就必须提供 web/index.html，即使所有侧边栏入口都指向子页面：

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example Extension</title>
  <link rel="stylesheet" href="assets/style.css">
</head>
<body>
  <p>Hello World</p>
  <script src="assets/main.js"></script>
</body>
</html>

• 在 extension.json.pages 中注册需要出现在侧边栏的入口。根页面使用 "url": "/"；目录页面优先使用带结尾斜杠的路径，例如 "url": "/reports/" 对应 web/reports/index.html；文件页面如 "url": "/reports.html" 对应 web/reports.html。
• 面板使用 iframe 加载与当前 /panel/ext/<extId>/... 路径对应的扩展 Web 资源。把页面设计成独立静态应用，不假设能直接使用 OPanel 的 React 组件树、上下文或组件库。
• 静态资源使用相对于当前 HTML 文件的 URL。当前内部资源命名空间为 /api/extension-res/<extId>/...，不要把它写死，除非确实需要绝对地址。
• 前端调用扩展后端时使用 /api/extension/<extId>/...，保留登录 cookie，并处理 401、404 与服务端错误。
• pages 中的查询参数和 URL fragment 会随面板路由传给 iframe；页面路由仍应以目标版本的实际前端路由和资源控制器为准，旧版本可能只支持扩展首页。

监听事件

只在 @Extension 主类中声明事件 handler：

import cn.opanel.api.EventHandler;
import cn.opanel.api.event.PlayerJoinEvent;

@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
    api.logInfo("Player joined: " + event.getPlayer().getName());
}

• 方法必须为 public、非 static、返回 void，且恰好接收一个受支持的事件类型。
• 从目标版本的 cn.opanel.api.event 包或事件分发器确认支持列表；不要仅凭类名猜测。
• 当前参考实现支持 PlayerJoinEvent、PlayerLeaveEvent、PlayerMoveEvent、PlayerGameModeChangeEvent 和 PlayerInventoryChangeEvent。
• handler 在产生事件的线程上同步执行，不保证是 Minecraft 主线程。保持快速、非阻塞；将 I/O 或耗时工作转移到扩展自有 worker，并处理生命周期竞态。