From 7e371c1304fa62c781f4ac313f93f9381a9f5ced Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Mon, 19 Oct 2026 15:34:45 +0800 Subject: [PATCH] =?UTF-8?q?docs(plugin-dev):=20=E8=A1=A5=E8=AE=B0=E3=80=8C?= =?UTF-8?q?=E8=A3=85=E4=B8=8A=E2=89=A0=E7=94=9F=E6=95=88=E3=80=8D=E2=80=94?= =?UTF-8?q?=E2=80=94=E6=97=A7=E5=86=85=E6=A0=B8=E4=B8=8A=E8=A3=85=20timer?= =?UTF-8?q?=20=E4=BB=8D=E8=B5=B0=E5=86=85=E7=BD=AE=E5=B7=A5=E5=8E=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit loadOne 先查 factories[name]，命中就不再读 plugin.bin；旧内核里内置 timer 工厂还在，所以落盘安装后 plugin_status 仍是 builtin=true / tools=[timer_set]，外部版本要等内核升级重启（工厂消失）才真正接管。plgreload 在这中间是空动作。 这样「先装插件再升级内核」的顺序约束才有可执行的含义：先落盘，再换二进制重启。 (cherry picked from commit 9e72898170386526425f8abe474d0f9622242422) --- assets/docs/en/PLUGIN_DEV.md | 8 ++++++++ assets/docs/zh/PLUGIN_DEV.md | 6 ++++++ 2 files changed, 14 insertions(+) diff --git a/assets/docs/en/PLUGIN_DEV.md b/assets/docs/en/PLUGIN_DEV.md index bb1dc864..7f59c204 100644 --- a/assets/docs/en/PLUGIN_DEV.md +++ b/assets/docs/en/PLUGIN_DEV.md @@ -848,6 +848,14 @@ Internal: records are stored in SQLite `disabled_plugins` table (`name`, `disabl > **fails silently**: no error, the tools simply vanish (the LLM cannot see them, which > surfaces as "reminders are gone" with nothing in the logs to explain it). > +> ⚠ **Installed is not the same as in effect**: on the **old kernel**, installing the timer +> plugin still goes through the built-in factory (`loadOne` checks `factories[name]` first and +> never reaches `plugin.bin`), so the external build is not loaded at all — +> `plugin_status("timer")` keeps reporting `builtin=true`, `tools=["timer_set"]`. The +> hand-over only happens **after the kernel upgrade restarts** (the factory is gone, so the +> external bin finally loads). Correct sequence: install to disk first, then swap the binary +> and restart — the `plgreload` in between is a no-op. +> > The external version is also a strict superset: the built-in one only had `timer_set`, and > in-flight countdowns were lost on restart; the external one adds `timer_list` / `timer_cancel` > and persists pending timers across restarts. diff --git a/assets/docs/zh/PLUGIN_DEV.md b/assets/docs/zh/PLUGIN_DEV.md index 3bec0242..b9d1f9a6 100644 --- a/assets/docs/zh/PLUGIN_DEV.md +++ b/assets/docs/zh/PLUGIN_DEV.md @@ -837,6 +837,12 @@ pmgr.ReloadPlugins() // 重载所有插件 > 工具全部不存在——而且**不会报错**，只是工具悄无声息地消失（LLM 看不到它们， > 于是表现为「定时提醒这个功能不见了」，日志里没有任何线索）。 > +> ⚠ **「装上去」不等于「生效」**：在**旧内核**上安装 timer 插件时，插件装载会优先走 +> 内置工厂（`loadOne` 先查 `factories[name]`，命中就不再去看 `plugin.bin`），外部版本 +> 根本不会被加载——`plugin_status("timer")` 依然是 `builtin=true`、`tools=["timer_set"]`。 +> 真正的接管发生在**升级内核并重启之后**（内置工厂已不存在，才会动态加载外部 bin）。 +> 所以正确姿势是「先落盘安装 → 再换二进制重启」，中间那次 `plgreload` 是空动作。 +> > 顺带说明外部版比原内置版更强：内置版只有 `timer_set`，进程重启即在途倒计时全丢； > 外部版额外提供 `timer_list` / `timer_cancel`，且待触发列表跨重启保留。