Skip to content

feat(plugin): run TREM-Lite 3 extensions on the desktop build - #32

Open
yayacat wants to merge 16 commits into
ExpTechTW:mainfrom
yayacat:task/實作插件擴充功能+t-muuivbu3-uk5c5s

Hidden character warning

The head ref may contain hidden characters: "task/\u5be6\u4f5c\u63d2\u4ef6\u64f4\u5145\u529f\u80fd+t-muuivbu3-uk5c5s"
Open

yayacat wants to merge 16 commits into
ExpTechTW:mainfrom
yayacat:task/實作插件擴充功能+t-muuivbu3-uk5c5s

Conversation

@yayacat

@yayacat yayacat commented Oct 5, 2026

Copy link
Copy Markdown
Member

摘要

V4(Tauri + React)重寫之後,legacy/ 的擴充功能系統沒有跟著過來,使用者原本的擴充功能在桌面版完全無法使用。這個 PR 把它接回來:載入、簽章驗證、相依性檢查、設定裡的「擴充」頁、.trem 安裝,以及擴充功能自己的視窗。行為以 legacy/ 為基準,對擴充作者的介面寫在新增的 PLUGINS.md。

分支上共 16 個 commit,依主題分成六塊:

1. 載入並執行 TREM-Lite 3 的擴充功能

  • packages/core/src/features/plugin/:PluginLoader 讀 userData/plugins,沿用舊版的 enabled-plugins/loaded-plugins 兩個 localStorage 鍵。
  • CJS require shim 加上一次性預載的 fs/path 記憶體快取,讓舊版同步 fs.readFileSync 的擴充功能能跑;寫入走非同步的 plugin_write。
  • ctx 與舊版同名同義:TREM、events、logger/Logger、MixinManager、info、utils.path/utils.fs、on、require;敏感度等級文字與「初始化失敗,請聯繫擴充作者。」等訊息沿用舊版原文。
  • 載入時機排在其他 feature module 之前(對應舊版 index/require.js),擴充功能才聽得到連線後的第一筆 DataRts。

2. 簽章驗證

  • Rust 端只做檔案 I/O;雜湊與 RSA 驗證在 WebView 內用 WebCrypto:對 LF 正規化後的內容算 SHA-256,用 RSASSA-PKCS1-v1_5 + SHA-256 簽 JSON.stringify(fileHashes),與舊版 crypto.createVerify("SHA256") 的位元組一致。
  • tool/plugin/sign.mjs 是簽章工具;signature.json 與 trem.json 不列入雜湊,dot 檔略過。

3. 設定 → 擴充

  • 列出已安裝的擴充功能與載入/驗證狀態;未簽章的擴充功能要等 10 秒倒數才能啟用。
  • 可以刪除、可以把 .trem 拖進去安裝,也可以直接把資料夾複製進去(下次啟動自動安裝)。
  • 每個擴充功能的細節(說明/作者/敏感度/簽章金鑰/相依/失敗原因)在它自己的那一列下方展開。

4. 相依性

  • dependencies.trem 與其他擴充功能的版本需求,在讀取清單時就檢查(不必等到下次啟動),失敗原因顯示在該擴充功能的展開區。
  • 版本比較支援完整快照標籤:26.1.0-26w40a 比 26.1.0-26w39a 新,26w9a 比 26w39a 舊(週次以數值比較)。
  • =26.1.0 在 26.1.0-26w39a 上不成立(=26.1.0 指的是正式版),>=26.1.0 同理;要相容快照版請寫 >=26.0.0,或直接指名快照。
  • 需求字串允許運算子後面有空白(">= 26.1.0"),== 讀作 =。

5. 擴充功能視窗

  • 舊版的 open-plugin-window、send-to-plugin-window、broadcast-to-plugin-windows、close-plugin-window/close-plugin-windows、get-plugin-windows、reload/all-reload、openDevtool、toggleFullscreen、hide、開各種資料夾、minimize-window/maximize-window/restore-window 都有對應。
  • 視窗由 Tauri 建立,頁面由應用程式自訂協定提供(Windows 為 http://trem-plugin.localhost/),頁面拿得到 require("electron")、ipcRenderer、process,相對路徑的 require("./js/map.js") 也能用。
  • 頁面的例外、未接住的 Promise,以及載入失敗的資源(例如連不上 CDN)都會寫進應用程式日誌。

6. 相容性

  • 導覽列保留舊版的 #setting/#focus id 與 .nav-bar-location 樣式,讓以 insertAdjacentElement 插入按鈕的擴充功能(例如 weather、websocket)能運作。

Platform

Platform: desktop

擴充功能的載入、.trem 安裝與擴充功能視窗都只在 Tauri 桌面版;網頁版在擴充頁顯示「不支援」並說明原因。

使用者更新日誌條目

New

  • New(zh-Hant): 桌面版可以再安裝並執行 TREM-Lite 3 的擴充功能,設定裡新增「擴充」頁,可以啟用、停用、刪除,也能把 .trem 直接拖進去安裝。
  • New(en-US): The desktop build runs TREM-Lite 3 extensions again, with an Extensions page in settings to enable, disable, remove, or drop a .trem onto.

Fix

  • Fix(zh-Hant): 擴充功能可以再開自己的視窗(例如天氣地圖),視窗不再是一片空白,也不會讓主視窗卡住。
  • Fix(en-US): An extension can open its own window again (the weather map, for one) without a blank page or a frozen main window.

驗證

本機(Windows 11、debug profile)實際跑過的:

檢查 結果
bun run typecheck(packages/core) 通過
bun run lint(packages/core) 通過(只有既有的 packages/core/src/preview.tsx:100:10 react-refresh warning)
bun run build:web 通過(apps/web 產出 dist,約 21 秒)
cargo check 通過,無 warning
cargo fmt --check plugin.rs、plugin_window.rs 乾淨;http_proxy.rs/logging.rs/updater.rs/window.rs 的差異與 upstream/main 相同,不是這個 PR 造成的(未一併格式化,以免混入無關修改)
cargo test 36 passed / 13 failed;同樣 13 個測試在未修改的 main(274bafc2)上以相同方式失敗,全部落在 http_cache/http_proxy/logging/ml_intensity,與這個 PR 無關
bun tool/plugin/selftest.ts ALL PASS(簽章、雜湊順序、LF 正規化、.trem 解壓縮、版本比較,共 30 項)
tool/check/commits.sh 每個 commit 都通過

沒有跑過:tauri build --no-bundle(完整 release 建置)、macOS 與 Linux 實機。擴充功能視窗的協定在非 Windows 平台走 trem-plugin://,程式碼有處理但沒有實測。

已知限制

  • macOS/Linux 未實機驗證。
  • 擴充功能視窗裡的頁面沒有檔案系統;openTempFolder 在 V4 指向擴充功能自己的資料夾(舊版會先複製一份到 plugins-temp)。
  • @electron/remote 不支援,require 會直接拋出說明;用它在主行程開視窗的擴充功能無法執行。
  • TREM.class 不含 DataManager/ReportManager/FocusManager/EewAreaManager/BoxManager/ReplayControler/WindowControler,這些工作在 V4 由 features/ 與 Rust 分擔。
  • tool/plugin/package.mjs(把資料夾打包成 .trem)還沒做;安裝端已經支援。

@yayacat
yayacat force-pushed the task/實作插件擴充功能+t-muuivbu3-uk5c5s branch 3 times, most recently from f0b117b to e086f34 Compare October 5, 2026 19:20
@yayacat
yayacat requested review from a team and whes1015 October 6, 2026 03:17
yayacat added 16 commits October 7, 2026 09:53
Platform: desktop

New(zh-Hant): 設定多了「擴充」頁,可以安裝、啟用與移除擴充功能,未簽章的擴充功能要先確認才會執行
New(en-US): Settings gains an Extensions page to install, enable and remove extensions, and an unverified one asks for confirmation before it runs
The 擴充 page is rendered by the settings webview, and that webview never
started the extension host, so `pluginLoader()` was null and the page fell
back to "擴充功能只能在桌面版執行。" on the desktop build.

The settings window now builds the same loader in a management mode: it
scans, verifies, installs, removes and records what is enabled, but starts
nothing — a plugin reaches for the map, the station feed and the audio
engine, and those belong to the main window. Enabling one therefore takes
effect at the next start, which is what V3 did as well, and the page says so.

Platform: desktop

Fix(zh-Hant): 設定 → 擴充 不再顯示「不支援」,會列出已安裝的擴充功能
Fix(en-US): the extensions page lists installed extensions instead of reporting the desktop build as unsupported
The published manifests were checked against the plugin store instead of against
this loader: `description` is a locale table (`{ "zh_tw": … }`) and `author` is
an array, so rendering them straight into React would have thrown for every real
plugin. `resources` and `link` are typed as well now.

A `.trem` zipped on Windows — `Compress-Archive`, 「傳送到 → 壓縮的資料夾」 — names its
entries with `\`, which the unpacker did not accept as a separator, so such an
archive was rejected as missing its own `info.json`. Unpacking moved to
`package.ts`, which normalises the separators, and the self-test covers both a
wrapped and a flat archive.

Platform: desktop
Fix(zh-Hant): 修正擴充功能的說明與作者顯示,並支援 Windows 壓縮工具製作的安裝包
Fix(en-US): Read the shapes the plugin store actually publishes and accept .trem archives made by Windows zip tools
The 擴充 page offered three ways in and only one of them worked.

- A plain browser showed the whole install UI. `initPlugins` and
  `initPluginAdmin` now stop without plugin storage, and the page keys its
  不支援 branch off the storage rather than off a loader a browser had built
  anyway.
- Dropping a `.trem` on the page did nothing. Tauri handling the OS-level file
  drop is what keeps HTML5 drop events from firing on Windows, so the settings
  window is created with `dragDropEnabled: false`.
- A `.trem` copied into the plugin folder was invisible: the folder held an
  archive where the host expects unpacked directories. The host now installs
  what it finds there at boot — V3's `index/plugin_init.js` did the same with
  its bundled package — and discards the archive once it is in, so a package
  that fails stays put with its reason in the log.

Platform: desktop
Fix(zh-Hant): 修正擴充功能的安裝:拖曳 .trem 現在有效,複製到擴充功能資料夾的套件會在下次啟動時自動安裝,網頁版正確顯示為不支援。
Fix(en-US): Fixed extension install: dropping a .trem works, a package copied into the plugin folder is installed at the next start, and the browser build reports itself unsupported.
Platform: desktop

Fix(zh-Hant): 設定 → 擴充 會顯示已啟用的擴充功能載入失敗的原因,不再只說初始化失敗。
Fix(en-US): The extensions page now shows why an enabled extension failed to load.
The 擴充 page said nothing about whether an extension could actually run.

`validateDependencies` was only ever reached from `start()`, and the settings
window never starts anything — it lists, verifies, installs and removes. A
plugin whose manifest asked for a newer TREM-Lite, or for another plugin that
is not installed, looked exactly like a healthy one until the next boot, and
then failed in a log the user does not read.

The check now runs at the end of `scan()`, once every manifest is in hand (a
plugin may depend on one that sorts after it), and the row names the verdict
and the requirement it came from.

Platform: desktop
Fix(zh-Hant): 設定 → 擴充 會直接標示相依性問題:缺少的擴充功能或版本不符,不必等到下次啟動才知道。
Fix(en-US): The extensions page now reports dependency problems — a missing extension or a version mismatch is named there instead of surfacing at the next start.
Every extension with a panel of its own asked for a window the same way —
`require("electron")`, then `ipcRenderer.send("open-plugin-window", …)` — and
got a named error saying Electron was not available. V3 answered that channel
by handing the renderer a second Electron window; that is not something to
reuse, so the window is a real Tauri window and the page is served from a
scheme of the app's own.

- `plugin_window.rs` serves exactly one plugin folder over `trem-plugin://`
  (`http://trem-plugin.localhost/` on Windows, where a custom scheme is an
  http origin), injects a bootstrap providing `require("electron")`,
  `require("./relative")` and `process`, and dispatches every channel V3
  answered: `open-plugin-window`, `send-to-plugin-window`,
  `broadcast-to-plugin-windows`, `close-plugin-window` and its plural,
  `get-plugin-windows`, `reload` and `all-reload`, `openDevtool`,
  `toggleFullscreen`, `hide`, the folder openers, and the window controls. One
  window per plugin, labelled `plugin-<name>`; closing it emits
  `plugin-window-closed` to the main window.
- `electron.ts` is the main window's half: an `ipcRenderer` whose `send` goes
  through the same dispatcher, so `send-to-plugin-window` reaches the plugin's
  window without the plugin having to know a window id — which is how the
  published extensions already write it.
- A plugin window gets a capability of its own
  (`capabilities/plugin-window.json`): the default one covers the app's three
  windows and nothing else, so without it the page could not talk back.

`PLUGINS.md` documents both halves and no longer refuses `electron` in the
module table.

Platform: desktop
New(zh-Hant): 擴充功能可以開啟自己的視窗,用舊版的 ipcRenderer 通道傳資料給它,並在視窗關閉時收到通知。
New(en-US): Extensions can open windows of their own, send data to them over the V3 ipcRenderer channels, and hear about it when one closes.
A V3 extension that adds a button to the nav — weather and websocket both do —
looks up `#focus` and inserts its own node after it:

    document.querySelector("#focus").insertAdjacentElement("afterend", button)

V4 renders that row from React, so the button had no id, the lookup returned
null, and the extension's own `onLoad()` threw on the very next line. The row
was reachable, but nothing an extension could hang itself off.

The two ids legacy/src/view/index.html gave those buttons (`#setting`,
`#focus`) are back on the React buttons, and `.nav-bar-location` — the class an
injected node carries — is styled with the geometry of nav_bar/box.css, so a
button an extension adds sits in the row like the buttons beside it.

Platform: desktop
Fix(zh-Hant): 舊版擴充功能可以再把按鈕加進左下角的按鈕列,插進去的按鈕外觀與旁邊一致。
Fix(en-US): V3 extensions can add their button to the bottom-left row again, styled like the buttons beside it.
The six plugin_window_* commands were synchronous, so Tauri ran them
inline on the thread the IPC arrived on -- the main thread, inside
WebView2's own message callback. WebviewWindowBuilder::build then created
a window and a second WebView2 controller back inside that callback,
which froze the app the moment an extension opened its window and left
the new window blank because its navigation never got the event loop.

Declaring the commands async moves window creation onto the async
runtime, where the message is posted to the event loop instead.

Also make a blank window diagnosable:
- BOOTSTRAP reports script errors, unhandled rejections and failed
  resources (with file and line) over a new __page-error channel
- serve() logs every request it answers as well as every failure,
  instead of staying silent
- PLUGINS.md documents both.

Platform: desktop
Fix(zh-Hant): 擴充功能開啟自己的視窗時,應用程式不再整個卡住,視窗也不會再是一片空白。
Fix(en-US): Opening an extension's own window no longer freezes the app, and the window no longer stays blank.
Fix(zh-Hant): 擴充功能視窗裡的錯誤現在會寫進日誌,附上檔案與行號,方便回報給擴充作者。
Fix(en-US): Errors raised inside an extension's window are logged with the file and line, so they can be reported to its author.
A dependency on `>=26.1.0-26w40a` was satisfied by `26.1.0-26w39a`:
compareVersions only looked at the channel (release > -rc > -pre >
anything else) and, when both sides were snapshots, at nothing at all,
because `26w39a` does not split into two dot-separated segments.

Two more comparisons went wrong the same way -- `1.2.3-rc.10` sorted
below `1.2.3-rc.9`, since the segment was compared as text, and
`=26.1.0` was accepted on a `26.1.0-26w39a` build, since the two were
treated as the same version. `">= 26.0.0"`, which authors write, never
held at all: the requirement was split on every space, so `">="` was
validated as a requirement of its own.

- compare pre-release segments properly: snapshots by year/week/letter,
  digit-only segments as numbers, and the shorter list first
- keep V3's channel order, so `26.1.0` stays newer than `26.1.0-26w39a`
  and `=26.1.0` / `>=26.1.0` still refuse a snapshot build
- read a requirement as operator + version, allowing the space after the
  operator and `==` spelled for `=`
- extend tool/plugin/selftest.ts, the runnable check, with the cases
- PLUGINS.md documents the ordering, including the "step down one
  milestone" advice for requirements that must accept snapshot builds

Platform: all
Fix(zh-Hant): 相依性的版本比較改用完整的快照標籤:`>=26.1.0-26w40a` 不再被 26w39a 的版本滿足,`=26.1.0` 在快照版上也不予通過。
Fix(en-US): Dependency requirements compare the whole snapshot tag now: `>=26.1.0-26w40a` is no longer satisfied by a 26w39a build, and `=26.1.0` no longer passes on one.
Fix(zh-Hant): 寫成 `>= 26.0.0`(運算子後面有空白)的相依性也可以正確解讀。
Fix(en-US): A requirement written as `>= 26.0.0`, with a space after the operator, is read correctly.
The 詳細資料 section listed every extension a second time, further down
the page, in one card with nothing between the entries: two extensions'
facts were told apart only by the name on the left, and the right-aligned
block ran past the edge of the card once a requirement was long.

The details belong to the extension they describe, so each row carries
them and shows them when it is opened — the name and a chevron are the
button, and the row keeps its badges and its buttons.

- one wrapper per extension, so the card still separates the rows and the
  body sits inside the same group, indented to the name
- the reason an extension is not running comes first in the body: it is
  the only line there that asks the reader to do something
- an extension that is enabled but not loaded now says 未載入 in the row
  as well, so a refusal is visible before it is unfolded
- drop .settings-extension-detail, which only the old list used

Platform: desktop
New(zh-Hant): 設定的「擴充」頁改成在每個擴充功能自己的列底下展開詳細資料,不再集中到頁面下方的另一張卡片。
New(en-US): On the Extensions settings page, an extension's details unfold under its own row instead of appearing in a second card further down the page.
New(zh-Hant): 已啟用卻沒有載入的擴充功能,會在列上直接標示「未載入」。
New(en-US): An extension that is enabled but was not loaded is marked 未載入 on its row now.
`plugin.rs` and `plugin_window.rs` came in with lines rustfmt would
rewrite (the long `plugin_window_ipc` channel list and the `serve`
signature among them). Nothing but whitespace changes; the other files
`cargo fmt --check` reports are unchanged from `upstream/main` and are
left alone.
`open_devtools` belongs to the `devtools` feature, so it is compiled
only when devtools exist: `lib.rs` guards its own call with
`#[cfg(debug_assertions)]`. The `openDevtool` arm of
`plugin_window_ipc` called it unconditionally, so every release build
stopped at

    error[E0599]: no method named `open_devtools` found for struct
    `tauri::WebviewWindow<R>` in the current scope
      --> src/plugin_window.rs:708:24

A debug `cargo check` never sees it, because a debug build has the
method -- which is how it got past this branch, and the CI build matrix
is the first thing that compiles the app the way it ships. The arm
keeps answering a plugin that asks; it just does nothing where there
are no devtools.

Platform: desktop
Fix(zh-Hant): 正式版本的建置恢復正常,擴充功能呼叫開啟開發者工具不會再讓編譯失敗。
Fix(en-US): Release builds compile again; an extension asking to open devtools no longer breaks them.
V3 documented `ctx.require("../other-plugin/util")`, so the only way to
share code between extensions was to reach across plugin folders by
relative path. A bare specifier was refused outright -- it is a name, not
a path, and in V3 it fell through to Node's `require`, which resolved from
core/ and never found anything. That refusal also carried the whole npm
story, so `require("other-plugin")` and `require("lodash")` were the same
error.

The tree already holds every installed plugin, so a bare name is another
plugin's own folder. It resolves to that folder's `index.js` -- the same
file the host loads as the plugin itself, so the asker gets the module the
host treated as that plugin, not whatever a `package.json` `main` happens
to point at.

Two things had to hold for that to be safe. A name must be able to *be* a
name: `/^[a-z0-9][a-z0-9-]*$/`, so `react-dom/client` and `lodash.merge`
stay packages rather than being mistaken for directories. And the module
has to be evaluated by the runtime that owns its folder -- `fs` resolves
relative paths against `pluginDir` and writes are attributed to `plugin`,
so evaluating one plugin's file with another's runtime would hand it the
wrong directory. `RuntimeOptions.lookup` asks the loader for that runtime,
which answers from the plugins it is already running; `dependencyOrder`
put the dependency first, which is what makes the name resolve. A plugin
that is installed but disabled or unlisted now gets a message naming
`dependencies` instead of a silent `undefined`.

The `../other-plugin/util` path form crosses the same boundary and is
routed the same way, so it keeps the owner's folder too.

Platform: desktop
New(zh-Hant): 擴充功能可以用另一個擴充功能的名稱載入它,例如 require("other-plugin"),不必再自己用相對路徑拼出對方資料夾裡的路徑。
New(en-US): An extension can require another by name -- require("other-plugin") -- instead of spelling out a relative path into the other plugin's folder.
New(zh-Hant): 被載入的檔案以自己的身分執行,它裡面的相對路徑與寫入都算在擁有它的擴充功能上。
New(en-US): A module loaded across extensions runs as its own owner: relative paths and writes belong to the plugin that owns the file.
@yayacat
yayacat force-pushed the task/實作插件擴充功能+t-muuivbu3-uk5c5s branch from 0a3b378 to d4683eb Compare October 7, 2026 02:21

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant