Skip to content

Latest commit

 

History

History
104 lines (73 loc) · 5.76 KB

PLUGIN.md

File metadata and controls

104 lines (73 loc) · 5.76 KB

HiPer Bridge 扩展插件开发说明

当前插件规范版本：1

为了提供某些非 HiPer / HiPer Bridge 本职工作的扩展能力，HiPer Bridge 提供了一个使用 JSON 进行描述的插件功能。方便某些特殊工具通过 HiPer 的组网功能进行扩展（诸如自动启动，游戏联机重定向等功能）

为了避免简化操作带来的危险行为感知上的麻痹，HiPer Bridge 不会提供简易的图形页面来安装/卸载插件，仅提供自动更新能力。

警告：由于插件权限非常强大，虽然 HiPer Bridge 已经尽力制约了脚本的权限范围，但是并不能完全保证用户的使用安全，所以请不要随意使用来路不明的插件，以免出现安全性问题！

插件及其插件结构

所有插件均以文件夹方式存储在 HiPer 安装目录下的 plugins 文件夹

其必需的文件结构如下：

.
|- plugin.json -- 插件的描述信息

plugin.json 插件元数据描述文件结构

为了简化插件解析流程，插件元数据描述文件结构会较为复杂且多余，目前暂时不会有简化编写流程的计划。

{
    "_version": 1,                                      // 插件元数据描述文件的对应结构版本，必需，目前是 1
    "id": "com.example.plugin",                         // 插件唯一标识，必需
    "name": "",                                         // 插件名称，可选
    "plugin_version": "1.0.0",                          // 插件的版本号，可选，用于和更新链接进行比对
    "update_url": "https://example.com/update.json",    // 查询更新的链接，可选，其响应的数据见下文描述
    "scripts": [{                                       // 一个脚本数组，用于存储不同条件下需要执行的终端指令
        "on": "launch",                                 // 触发事件的条件，必需，可选值见下文描述
        "system": "windows",                            // 触发该脚本的系统平台，可选，默认不限，可选值见下文描述
        "arch": "x86_64",                               // 触发该脚本所需的架构，可选，默认不限，可选值见下文描述
        "debug": true,                                  // 仅 Windows：是否显示命令行窗口（查看输出）
        "commands": [                                   // 指令数组，内部的指令都将按顺序被直接写入到 STDIN 写入流中
            "echo Started!"
        ]
    }]
}

关于事件触发和指令执行

在事件触发时，HiPer Bridge 会从插件元数据中的 scripts 找出全部符合触发条件（事件，系统，架构）的脚本，然后按顺序触发且并行执行所有匹配脚本。

注意事件因为存在长期执行而不会被 HiPer Bridge 终止，所以需要在某些对应的停止事件里自行对脚本仍在执行的程序进行终止（例如在 launch 事件启动的程序可以在 stopped 事件里被停止），否则脚本产生的程序会积累在后台占用资源。

指令执行时，将会根据系统打开对应的终端程序（如 Windows 上的 cmd.exe，Linux 上的 bash，MacOS 上的 zsh），且当前工作目录会被设定为当前的插件所在目录。而 commands 字段中每个指令将被直接写入到写入流中。

关于插件更新

如果需要实现插件的自动更新，插件元数据文件必须同时提供合法的 plugin_version 和 update_url 字段，否则自动更新均不会工作。

准备完成后，HiPer Bridge 会尝试以 GET 方式请求对应的更新链接，其返回的数据应当是如下格式的 JSON 文件：

{
    "version": "",                              // 当前插件的最新版本号，将会和本地的 plugin_version 比对，如果不等则会触发更新
    "downloads": [{                             // 插件包的文件清单，HiPer Bridge 将会按顺序选择第一个匹配的文件下载更新
        "system": "windows",                    // 文件对应操作系统，可选，默认全系统
        "arch": "x86_64",                       // 文件对应系统架构，可选，默认全架构
        "url": "https://example.com/update.zip",// 文件对应的下载链接，必须是直链
    }]
}

在正确找到版本且正确下载到更新用的压缩文件包后，HiPer Bridge 会先触发旧版插件的 plugin-update 事件脚本，待执行完成后将压缩包内的文件直接覆盖旧版文件夹。操作完成后将读取新插件元数据文件并触发 plugin-updated 事件脚本，执行完成后插件即完成更新。

可选值清单

事件清单

事件ID 事件描述
hb-launch 在 HiPer Bridge 本体启动时触发，注意这个有可能会影响到自动更新功能的工作
hb-exit 在 HiPer Bridge 本体即将结束时触发
plugin-update 在插件更新文件已经下载完成开始更新前触发，可以在这里做某些旧版交接工作
plugin-updated 在插件更新完成时触发，注意此处将使用新版本的插件描述文件
launch 在 HiPer 启动时触发
joined 在 HiPer 已获取到入网 IP 时触发
stopped 在 HiPer 正常/非正常停止运行时触发
crashed 在 HiPer 因非正常原因停止运行时触发，这将会比 stopped 晚触发

系统平台清单

考虑到目前 HiPer Bridge 可以构建到的目标平台，只提供以下系统支持：

  • windows
  • linux

后续 HiPer Bridge 跟进平台支持后，此处会一并更新文档。

系统架构清单

考虑到目前 HiPer Bridge 可以构建到的目标平台，只提供以下架构支持：

  • x86
  • x86_64
  • aarch64

后续 HiPer Bridge 跟进平台架构支持后，此处会一并更新文档。