From 47272adffeab3314673541840db6495bc3f4acba Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Mon, 19 Oct 2026 15:26:50 +0800 Subject: [PATCH] =?UTF-8?q?docs(plugin-dev):=20=E6=B3=A8=E6=98=8E=20timer?= =?UTF-8?q?=20=E5=B7=B2=E5=A4=96=E7=BD=AE=EF=BC=8C=E5=B9=B6=E5=86=99?= =?UTF-8?q?=E6=98=8E=E3=80=8C=E5=85=88=E8=A3=85=E6=8F=92=E4=BB=B6=E5=86=8D?= =?UTF-8?q?=E5=8D=87=E7=BA=A7=E5=86=85=E6=A0=B8=E3=80=8D=E7=9A=84=E9=A1=BA?= =?UTF-8?q?=E5=BA=8F=E7=BA=A6=E6=9D=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit timer 移出内置插件后，升级路径上有个静默故障点：若先升级内核、后装 timer 插件， 就会有一段窗口期三个 timer 工具全部不存在 —— 不报错、日志无线索，只是 LLM 视野里工具没了，表现为「定时提醒功能不见了」，极难归因。 在 zh/en 两份 PLUGIN_DEV.md 的「内置插件」表下补注记（原 Timer 示例行就删在这里， 正是读者会产生疑问的位置）： - timer 已改为外部 hmap 插件提供，三个工具与 timer 输入通道均由它注册 - 升级顺序：先装 timer 插件，再升级内核 - 外部版是严格超集：原内置版只有 timer_set 且重启丢在途倒计时， 外部版增加 timer_list / timer_cancel 并跨重启保留待触发列表 assets/docs 是纯文档，无 go:embed、无代码引用，改动不影响构建。 (cherry picked from commit 62332562a80165b6e86af77315c07d18e743e7fa) --- assets/docs/en/PLUGIN_DEV.md | 13 +++++++++++++ assets/docs/zh/PLUGIN_DEV.md | 10 ++++++++++ 2 files changed, 23 insertions(+) diff --git a/assets/docs/en/PLUGIN_DEV.md b/assets/docs/en/PLUGIN_DEV.md index 0b01c684..bb1dc864 100644 --- a/assets/docs/en/PLUGIN_DEV.md +++ b/assets/docs/en/PLUGIN_DEV.md @@ -839,6 +839,19 @@ Internal: records are stored in SQLite `disabled_plugins` table (`name`, `disabl | CLI | `internal/plugins/cli/` | Unix socket listener + synchronous request-response | | WebUI | `internal/plugins/webui/` | HTTP service + dependency injection | +> **timer has been moved out of the built-in plugins** and is now provided as an external +> hmap plugin (all three tools `timer_set` / `timer_list` / `timer_cancel` and the `timer` +> input channel are registered by the external plugin). +> +> ★ **Upgrade order**: install the timer plugin *before* upgrading the kernel. Doing it the +> other way round leaves a window where none of the three timer tools exist — and it +> **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). +> +> 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. + --- *Want to understand the project goals? See [OVERVIEW.md](OVERVIEW.md).* diff --git a/assets/docs/zh/PLUGIN_DEV.md b/assets/docs/zh/PLUGIN_DEV.md index f032857f..3bec0242 100644 --- a/assets/docs/zh/PLUGIN_DEV.md +++ b/assets/docs/zh/PLUGIN_DEV.md @@ -830,6 +830,16 @@ pmgr.ReloadPlugins() // 重载所有插件 | CLI | `internal/plugins/cli/` | Unix socket 监听 + 同步请求响应 | | WebUI | `internal/plugins/webui/` | HTTP 服务 + 依赖注入 | +> **timer 已移出内置插件**，改为外部 hmap 插件提供（`timer_set` / `timer_list` / +> `timer_cancel` 三个工具与 `timer` 输入通道均由外部插件注册）。 +> +> ★ **升级顺序**：先安装 timer 插件，再升级内核。反过来会有一段窗口期三个 timer +> 工具全部不存在——而且**不会报错**，只是工具悄无声息地消失（LLM 看不到它们， +> 于是表现为「定时提醒这个功能不见了」，日志里没有任何线索）。 +> +> 顺带说明外部版比原内置版更强：内置版只有 `timer_set`，进程重启即在途倒计时全丢； +> 外部版额外提供 `timer_list` / `timer_cancel`，且待触发列表跨重启保留。 + --- *了解项目整体目标？查看 [OVERVIEW.md](OVERVIEW.md)。*