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)

編輯此頁或回報問題

外掛開發綜述

本文將概略介紹 PML 2 的外掛系統。

外掛系統運算子說明

本文件介紹 PML 2 外掛系統的運算子。