From f3d87ec35f4d759d0f3f1a7a43abea06bbe5e54d Mon Sep 17 00:00:00 2001
From: root <root@qq.com>
Date: Sun, 2 Aug 2026 15:23:22 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E7=94=9F=E5=91=BD=E5=91=A8=E6=9C=9F?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3=E8=A1=A5=E5=85=A8=20onRemove=EF=BC=88?=
 =?UTF-8?q?=E5=88=A0=E9=99=A4=E6=B8=85=E7=90=86=EF=BC=89=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README.md/README_EN.md：新增删除清理（onRemove）小节——语义（仅卸载
  触发、重载/禁用不触发，Stop 之后执行）、内核配套清理（工具注册/disabled/
  配置项定义 plugin.<name>.*/配置表 config_<name>）、示例清单与代码片段
- plugindev 模板 README.md.tmpl：新增 Lifecycle 段（RegisterStopHandler 每次
  停止、RegisterOnRemoveHandler 仅卸载）
---
 README.md                                | 14 ++++++++++++++
 README_EN.md                             | 14 ++++++++++++++
 tools/plugindev/templates/README.md.tmpl |  5 +++++
 3 files changed, 33 insertions(+)

diff --git a/README.md b/README.md
index eda29a8..7b0cfcd 100644
--- a/README.md
+++ b/README.md
@@ -253,6 +253,20 @@ return plugin
 - `Stop() error` — 插件停止，释放资源
 - `sdk.RegisterStopHandler(fn func())` — 注册停止清理回调。内核（内置插件）或 z_bridge（外部插件）会在调用插件 `Stop()` **之前**统一执行已注册的 handler（后注册先执行，执行后清空、幂等）。适合做持久化落盘、取消后台任务等清理：此时插件内存状态仍然新鲜，避免在 `Stop()` 阶段以陈旧状态写回导致数据复活。
 
+### 删除清理（onRemove）
+
+`Stop`/`RegisterStopHandler` 在插件**停止**（含重载、禁用）时执行；`RegisterOnRemoveHandler` 仅在插件被**卸载（删除）**时执行一次，重载/禁用不触发：
+
+- `sdk.RegisterOnRemoveHandler(fn func())` — 注册删除清理回调。内核在 `RemovePlugin` 流程中、插件 `Stop()` **之后**执行（后注册先执行，执行后清空、幂等）。用于删除插件自身创建的持久化文件（数据/缓存/状态文件）。
+- 内核卸载时一并清理：工具注册、`disabled_plugins` 记录、插件配置项定义（`plugin.<name>.*`）与插件配置表（`config_<name>`），卸载后插件配置区完全消失。
+- 示例：`example/calendar`（删 events.json）、`example/memo`（删 memos.json）、`example/rss`（删订阅数据目录）、`example/weather`（删缓存目录）；`plugindev` 模板含 onRemove 演示。
+
+```go
+sdk.RegisterOnRemoveHandler(func() {
+    os.Remove(filepath.Join(dataDir, "events.json"))
+})
+```
+
 ### 自动重启
 
 ```go
diff --git a/README_EN.md b/README_EN.md
index 5ffcceb..5531ab4 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -210,6 +210,20 @@ Supports both **Go** and **Lua** plugin languages.
 - `Stop() error` — Plugin shutdown, release resources
 - `sdk.RegisterStopHandler(fn func())` — Register a shutdown cleanup callback. The kernel (for built-in plugins) or z_bridge (for external plugins) runs all registered handlers **before** calling the plugin's `Stop()` (LIFO order, cleared after running — idempotent). Use it for persistence and cancelling background work: plugin memory is still fresh at that point, avoiding stale-state write-backs that resurrect deleted data.
 
+### Remove Cleanup (onRemove)
+
+`Stop` / `RegisterStopHandler` run whenever the plugin **stops** (including reload and disable); `RegisterOnRemoveHandler` runs **only once when the plugin is uninstalled (removed)** — never on reload or disable:
+
+- `sdk.RegisterOnRemoveHandler(fn func())` — Register a remove cleanup callback. The kernel runs it **after** the plugin's `Stop()` in the `RemovePlugin` flow (LIFO order, cleared after running — idempotent). Use it to delete persistent files the plugin created itself (data/cache/state files).
+- The kernel also cleans up on uninstall: tool registrations, the `disabled_plugins` record, the plugin's config definitions (`plugin.<name>.*`) and its config table (`config_<name>`) — the plugin's config section disappears completely after removal.
+- Examples: `example/calendar` (removes events.json), `example/memo` (removes memos.json), `example/rss` (removes the subscription data dir), `example/weather` (removes the cache dir); the `plugindev` template includes an onRemove demo.
+
+```go
+sdk.RegisterOnRemoveHandler(func() {
+    os.Remove(filepath.Join(dataDir, "events.json"))
+})
+```
+
 ### Auto-Restart
 
 ```go
diff --git a/tools/plugindev/templates/README.md.tmpl b/tools/plugindev/templates/README.md.tmpl
index 45cfe8f..aa3a935 100644
--- a/tools/plugindev/templates/README.md.tmpl
+++ b/tools/plugindev/templates/README.md.tmpl
@@ -17,3 +17,8 @@ curl -X POST http://localhost:8080/api/v1/plugins \
   -H "Content-Type: application/octet-stream" \
   --data-binary @dist/<name_en_snake>_linux_amd64.hmap
 ```
+
+## Lifecycle
+
+- `RegisterStopHandler` — runs on every stop (including reload/disable), before `Stop()`.
+- `RegisterOnRemoveHandler` — runs **only on uninstall (remove)**, after `Stop()`; clean up the plugin's own data files here. Reload/disable do NOT trigger it. See the onRemove demo in `main.go`.