mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-06 09:17:31 +00:00
refactor(plugins): 按「内置插件判定标准」收敛内置清单 16 → 11
## 判定标准（写进 all.go 与 ARCHITECTURE） **只有必须使用内部 SDK 能力（公开 SDK 没有的接口面）的插件，才留在 编译期内置清单**；其余一律外置为 .hmap 插件，独立编译、独立发版。 依据是 internal/plugin/proc/capability.go 的 withheldCapabilities： 内部 SDK 的 TerminalAPI/TrackerAPI/StatusAPI/SupervisorAPI/AdapterAPI/ SelftestAPI/ToolAPI/Publish 等能力面，外部插件在类型层就不存在。 需要它们的插件外置后功能会**静默消失**（不报错），必须内置； 只要公开能力的插件，留在内核里是白付重编成本。 ## 内置 11 个（all.go 单一权威清单） cli webui TerminalAPI/Tracker/Status/Supervisor/Adapter agentcli EventPublish（终端输出走 Publish，公开 SDK 无此方法） healthcheck SelftestAPI pluginmgr failback 恢复链必需 seq ToolAPI remotedevice RegisterChannel clawhubadapter InjectInputSync cfgmgr skillmgr seemedia（保留） ## 外置 8 个（源码保留，.hmap 由 SDK 仓 example/ 提供） timer（此前）ai_image files cmd kbtree localuse mcp multimodal ## 同步修正 - kbtree 归位：它一直是编译期内置插件，却长期被 main.go 单独导入， 游离在 all.go 清单之外（文档盘点因此数错）。现移入 all.go， main.go 不再单独导入任何插件，并加注释禁止该做法。 - integration_test：外置插件的 7 个用例（cmd_run/terminal_*）加 requireExternalTool 跳过保护——用例保留（行为判据仍有价值）， 在纯内置装配下 Skip，不造假失败。 - 全部文档同步 11 个的清单与判定标准（中英四份 + 两份 README）。 ## 已核实不做的事 - 保留的 11 个内置插件无一在代码里硬依赖被外置的插件： cli 对 terminal_* 是 ExecuteTool 按名动态调用（运行时依赖）； healthcheck/seq 只在白名单与示例文本里出现；webui 只订阅事件。 - kernelmod/（内核模块）与 plugins/（插件）严格区分： kernelmod/multimodal 是内核装配模块，与外置的 multimodal 插件无关。 验证：go build ./... 全绿；go test ./internal/plugins/... 全绿； webui 新增 5 条命令历史渲染回归判据（TestCmdHistory*）全绿。
This commit is contained in:
root
@ -20,19 +20,73 @@ package plugins
|
||||
//
|
||||
// ⚠️ 不要再把 timer 加回这里：父子两份同时存在会导致同名工具注册冲突，
|
||||
// 而「谁赢」取决于加载顺序 —— 那是最难排查的一类故障。
|
||||
//
|
||||
// ## 判定标准：只有「必须用内部 SDK 能力」的才留在本清单（2026-10-19）
|
||||
//
|
||||
// 内部 SDK（internal/sdk）比公开 SDK（third_party/homeagent-sdk/sdk）
|
||||
// 多出一批**不对外授予**的能力面。外部插件用的是 proc 桥的收窄能力集，
|
||||
// 这些接口在类型层就不存在（见 internal/plugin/proc/capability.go 的
|
||||
// withheldCapabilities）。所以：
|
||||
//
|
||||
// 插件需要 withheld 里的能力 ⇒ **必须内置**（外置会静默缺功能）
|
||||
// 插件只用公开 SDK 能力 ⇒ **应当外置**（.hmap 安装，独立演进）
|
||||
//
|
||||
// 正例（留内置，各有非它不可的理由）：
|
||||
// cli / webui TerminalAPI/TrackerAPI/StatusAPI/SupervisorAPI/AdapterAPI
|
||||
// healthcheck SelftestAPI（能构造虚拟内核实例）
|
||||
// pluginmgr failback 恢复链必需（webui/pluginmgr/recoverydiag）
|
||||
// seq ToolAPI（工具表直接操作）
|
||||
// remotedevice RegisterChannel（内核 IO 通道注册面）
|
||||
// clawhubadapter InjectInputSync（OC 主动注入）
|
||||
// agentcli ★ EventPublish —— 见下
|
||||
// cfgmgr / skillmgr / seemedia （保留）
|
||||
//
|
||||
// 反例（已外置，因为它们只要公开能力）：
|
||||
// cmd 仅 internal/plugin 的 RegisterFactory → 换成 NewPluginFactory 即可
|
||||
// kbtree 仅 s.Knowledge() + s.Settings()
|
||||
// localuse 仅 RegisterTool + Settings
|
||||
// mcp 仅 RegisterTool + Settings
|
||||
// multimodal 仅 RegisterTool + Settings
|
||||
//
|
||||
// ## ★ agentcli 为什么不能外置（2026-10-19 核实）
|
||||
//
|
||||
// 它靠 s.Publish(&sdk.Event{Type: EventTerminalOutput, ...}) 上报
|
||||
// 终端输出与生命周期（创建/关闭/退出）。而 **EventPublish 在
|
||||
// withheldCapabilities 里被明确扣留**，公开 SDK 连 Publish 方法都没有 ——
|
||||
// 外置后终端输出会静默消失：WebUI 的终端面板、CLI 的 /terminal，
|
||||
// 全都失去数据源，而且**不报错**。
|
||||
//
|
||||
// 想让 agentcli 外置，前提是先把「终端输出」从事件改为公开的输出通道
|
||||
// （RegisterOutputChannel 是公开能力）。在那之前必须内置。
|
||||
|
||||
// ## ai_image / files 已移出本清单（2026-10-19）
|
||||
//
|
||||
// 与 timer 同理：它们是**纯工具型**插件（agi_image_generate / files_read 等），
|
||||
// 只在该被调用时做事，没有任何「外部事件驱动主动注入」的行为，
|
||||
// 因此没有必须常驻的理由，也没有随内核发版的必要。
|
||||
//
|
||||
// 二者都由 SDK 仓 `example/` 下的同版本外部插件提供（ai_image 1.3.0、
|
||||
// files 1.0.0），工具名与配置表不变（config_ai_image / config_files），
|
||||
// 存量配置无需迁移。
|
||||
//
|
||||
// ⚠️ 同一个坑：不要为「怕插件没装」而把内置版加回来。两份并存时
|
||||
// loadOne 先查 factories ⇒ 内置版永远赢，外部版**装了也不生效**，
|
||||
// 而且 plugin_status 会显示 builtin=true（见 PLUGIN_DEV.md 的同款说明）。
|
||||
//
|
||||
// ## kbtree 已归位到本清单（2026-10-19）
|
||||
//
|
||||
// 它本就是一个注册了 RegisterFactory 的编译期内置插件，却一直被
|
||||
// `cmd/homed/main.go` 单独空白导入 —— 绕过了「内置插件清单」这个唯一入口。
|
||||
// 后果：任何按 all.go 盘点内置插件的工具/文档都会漏掉它（本次文档校正
|
||||
// 就踩了这个坑：先把数量写成 17，实际运行时是 18）。
|
||||
// 归位后 main.go 不再单独导入它。
|
||||
|
||||
import (
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/agentcli"
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/ai_image"
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/cfgmgr"
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/clawhubadapter"
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/cli"
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/cmd"
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/files"
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/healthcheck"
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/localuse"
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/mcp"
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/multimodal"
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/pluginmgr"
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/remotedevice"
|
||||
_ "github.com/JianFeeeee/HomeAgent/internal/plugins/seemedia"
|
||||
|
||||
Reference in New Issue
Block a user