From a2cba0ceb1e20028c19bcae02ca6ef516daa99cd Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Thu, 24 Sep 2026 12:10:10 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=AD=A3=20PluginMgr=20?= =?UTF-8?q?=E7=9A=84=E8=83=BD=E5=8A=9B=E6=8F=8F=E8=BF=B0=20+=20=E6=8C=A1?= =?UTF-8?q?=E4=BD=8F=E6=96=B0=E6=96=87=E6=A1=A3=E7=AB=99=E7=9B=AE=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 更正一处实测证伪的断言 `assets/docs/{zh,en}/PLUGIN_DEV.md` 都写着「`PluginMgr()` 仅内置插件可用， 外部动态插件无法直接调用」——**这是错的**。 建 SDK 文档站时对照 `hmapdev` 桥接模板实测： - `proc_main.go.tmpl:692` 显式 `base.SetPluginMgrAPI(procPluginMgr{})`，即桥接运行时 **为外部插件注入了** PluginMgr； - 公开 `sdk/plugin.go:282` 的注释本身就写着「PluginMgrAPI 提供插件管理能力 （外部插件可调用）」。 真正的区别是**方法数**，不是有无： | 接口 | 位置 | 方法数 | |---|---|---| | `sdk.PluginMgrAPI` | 公开 SDK | 3（ReloadOne / ListLoadedPlugins / IsPluginDisabled）| | `internal/sdk.PluginManager` | 内核内部 | 9（另有 Enable/Disable/Remove/ReloadPlugins/IsBuiltinPlugin 等）| 两个接口名字相似但**不是同一个**，这正是混淆的来源。已在中英两版改写为准确描述， 并保留原有的「内置插件 API」代码块（那段示例用的确实全是内部面，加注说明）。 ## 挡住新文档站目录 SDK 仓新增了 `docs/`（mkdocs 站点源码）与 `mkdocs.yml`。它们与 `README*`、`tools/` 同类——属于 SDK 仓，核心仓不该跟踪。规则带前导路径限定，核心仓自己的 `docs/` 不受影响（实测 `git check-ignore` 命中，工作区不再出现这两个路径）。 SDK 仓同批提交 0a6e2b7（文档站本体）。 --- .gitignore | 5 +++++ assets/docs/en/PLUGIN_DEV.md | 9 ++++++++- assets/docs/zh/PLUGIN_DEV.md | 7 ++++++- 3 files changed, 19 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 81aa43e..caba830 100644 --- a/.gitignore +++ b/.gitignore @@ -36,6 +36,11 @@ third_party/homeagent-sdk/scripts/ third_party/homeagent-sdk/.gitignore third_party/homeagent-sdk/README* third_party/homeagent-sdk/example/ +# 文档站（mkdocs.yml + docs/ + 生成器）属于 SDK 仓，与 README* / tools/ 同理。 +# 注意 docs/ 带前导路径限定，够精确：本仓自己的 docs/ 不受影响。 +third_party/homeagent-sdk/docs/ +third_party/homeagent-sdk/mkdocs.yml +third_party/homeagent-sdk/site_build/ .codegraph/ # codegraph 本地索引配置（含嵌套 SDK 仓放行，仅本地生效） diff --git a/assets/docs/en/PLUGIN_DEV.md b/assets/docs/en/PLUGIN_DEV.md index d135b16..3b0063d 100644 --- a/assets/docs/en/PLUGIN_DEV.md +++ b/assets/docs/en/PLUGIN_DEV.md @@ -790,7 +790,14 @@ pmgr.ReloadPlugins() // Reload all plugins Internal: records are stored in SQLite `disabled_plugins` table (`name`, `disabled_at`, `disabled_by`). Disabling takes effect immediately (plugin stops receiving input); full removal requires a restart. -> **Note**: `PluginMgr()` is only available to built-in plugins; external dynamic plugins cannot call it directly. +> **Note**: `PluginMgr()` returns an interface with **only 3 methods** (`ReloadOne` / +> `ListLoadedPlugins` / `IsPluginDisabled`). Enable/disable/remove/reload-all +> (`EnablePlugin` / `DisablePlugin` / `RemovePlugin` / `ReloadPlugins`) and the +> built-in check (`IsBuiltinPlugin`) exist only on the kernel-internal +> `internal/sdk.PluginManager` — external plugins cannot reach them. To reload from +> an external plugin, use `ReloadOne`. +> The two interfaces have similar names but are **not the same**: +> `sdk.PluginMgrAPI` (public, 3 methods) vs `internal/sdk.PluginManager` (internal, 9). --- diff --git a/assets/docs/zh/PLUGIN_DEV.md b/assets/docs/zh/PLUGIN_DEV.md index 1004df4..ef7603f 100644 --- a/assets/docs/zh/PLUGIN_DEV.md +++ b/assets/docs/zh/PLUGIN_DEV.md @@ -783,7 +783,12 @@ pmgr.ReloadPlugins() // 重载所有插件 内部机制：禁用记录存储在 SQLite `disabled_plugins` 表（`name`, `disabled_at`, `disabled_by`），禁用立即生效（插件不再接收输入），完全卸载需重启内核。 -> **注意**：`PluginMgr()` 仅内置插件可用，外部动态插件无法直接调用。 +> **注意**：`PluginMgr()` 返回的接口**只有 3 个方法**（`ReloadOne` / `ListLoadedPlugins` / +> `IsPluginDisabled`）。启用/禁用/卸载/重载全部（`EnablePlugin` / `DisablePlugin` / +> `RemovePlugin` / `ReloadPlugins`）以及内置插件判定（`IsBuiltinPlugin`）只在内核内部 +> 的 `internal/sdk.PluginManager` 上，外部插件拿不到——需重载插件请调 `ReloadOne`。 +> 两个接口叫相似的名字但**不是同一个**：`sdk.PluginMgrAPI`（公开，3 方法）与 +> `internal/sdk.PluginManager`（内部，9 方法）。 ---