PML 2 插件开发指南

插件系统埋点说明

本文档介绍 PML 2 插件系统的全部埋点。

一、插件事件触发点 (Trigger)

插件通过 YAML 中的 triggers.on 订阅以下事件。事件携带的数据可通过模板 {{ctx.data.字段名}} 在动作参数中引用。

事件总览

事件名	触发时机	触发位置	携带数据	执行方式
`app.startup`	主窗口初始化完成、应用启动时	`MainWindow.axaml.cs`	`version`, `os`	await
`app.exit`	应用退出时 (日志释放前)	`App.axaml.cs`	`version`, `os`	await
`app.update.available`	检测到有新版本时	`MainWindow.axaml.cs`	`currentVersion`, `latestVersion`	fire-and-forget
`user.login`	用户登录成功时	`LoginPage.axaml.cs`	`username`, `group`	fire-and-forget
`user.logout`	用户确认登出后、应用重启前	`UserCenterPage.axaml.cs`	`username`	await
`proxy.start`	启动隧道 (创建带 mefrpc 命令的终端标签页) 时	`TerminalPage.axaml.cs`	`proxyName`, `command`	fire-and-forget
`proxy.stop`	关闭终端标签页 (与 `proxy.start` 配对) 时	`TerminalPage.axaml.cs`	`proxyName`	fire-and-forget
`page.navigate`	切换主界面页面时	`MainPageFrameViewModel.cs`	`page`	fire-and-forget
`plugin.install`	插件文件安装成功时	`PluginService.cs`	`file`	fire-and-forget
`plugin.uninstall`	插件卸载成功时	`PluginService.cs`	`pluginId`, `pluginName`	fire-and-forget
`plugin.enable`	插件启用时	`PluginService.cs`	`pluginId`	fire-and-forget
`plugin.disable`	插件禁用时	`PluginService.cs`	`pluginId`	fire-and-forget

事件详情

app.startup / app.exit

应用生命周期事件。app.startup 在主窗口加载、隐私政策检查完成后触发； app.exit 在进程退出前触发，会等待插件动作执行完毕才释放日志资源。

数据字段	说明	示例
`version`	应用版本号	`26.2.0`
`os`	操作系统平台	`Win32NT` / `Unix`

app.update.available

启动后首次检查到新版本时触发 (每次运行只触发一次) 。

数据字段	说明
`currentVersion`	当前版本
`latestVersion`	检测到的最新版本

user.login / user.logout

数据字段	说明
`username`	登录/登出的用户名
`group`	用户组 (仅 `user.login`)

user.logout 之后应用会立即重启，因此采用 await 方式执行，保证插件动作 (如通知、上报) 能完整执行。

proxy.start / proxy.stop

数据字段	说明
`proxyName`	隧道/终端标签页名称
`command`	启动命令 (仅 `proxy.start`)

page.navigate

page 字段取值: Home、CreateProxy、ManageProxy、NodesMonitoring、UserCenter、 Settings、About、Terminal、Update、Theme、Plugin

plugin.install / plugin.uninstall / plugin.enable / plugin.disable

插件自身管理事件。注意: 插件可以订阅这些事件实现联动，但订阅 plugin.uninstall 的插件在自身被卸载后不会再收到后续事件。

二、插件 YAML 写法

插件文件位于 Config/Plugins/*.yaml，支持热重载 (文件变更后 1 秒内自动重载) 。

id: my-plugin
name: 示例插件
description: 隧道启动时发送通知
author: 作者名
version: "1.0"

triggers:
  - on: proxy.start                          # 订阅的事件名
    condition: "ctx.data.proxyName != ''"    # 可选，条件表达式
    actions:
      - name: notify
        params:
          msg: "隧道 {{ctx.data.proxyName}} 已启动"

functions:
  my_func:                                   # 可复用函数，用 call_function 调用
    - name: log
      params:
        msg: "hello"

内置指令 (actions)

指令	参数	说明
`log`	`msg`	写日志 (控制台 + 应用日志文件，模块为"插件")
`notify`	`msg`	发送系统通知 (标题为 `插件ID \| PML 2`)
`http_request`	`url`, `method`(默认 GET), `body`	发 HTTP 请求，响应体写入 `ctx.variables.http_response`
`python_run`	`script`, `input`	调用 Python 脚本 (需 PATH 中有 `python3`) ，返回的 JSON 合并进变量
`call_function`	`func`, `args`	调用 `functions` 中定义的函数
`conditional`	`condition`, `if_true`	条件执行一组动作

模板变量

参数中的 {{...}} 会在执行前替换:

{{ctx.data.xxx}} —— 事件携带的数据
{{ctx.variables.xxx}} —— 执行过程中产生的变量 (如 http_response)

Edit this pageorReport an issue

插件开发综述

本文将粗略介绍 PML 2 的插件系统。

插件系统运算符说明

本文档介绍 PML 2 插件系统的运算符。