From 87ad88b17466d893c4c3abbcc941238ba6befb8e Mon Sep 17 00:00:00 2001 From: JianFeeeee <109188060+JianFeeeee@users.noreply.github.com> Date: Sat, 25 Jul 2026 14:42:35 +0800 Subject: [PATCH] refactor: centralize ABI metadata into internal/meta/meta.go - internal/meta/meta.go: add ABIVersion, ABIVersionMin, 45 dispatch method IDs, SDKCompatibleVersion (single source of truth) - internal/plugin/cabi/types.go: re-export from meta.go - internal/plugin/cabi/loader.go: reject plugin when version > ABIVersion; pass ABIVersion in Start instead of hardcoded 1 - loader.{go,c}: comments reference meta.go as canonical --- internal/meta/meta.go | 63 +++++++++++++++++++++ internal/plugin/cabi/loader.c | 2 + internal/plugin/cabi/loader.go | 8 ++- internal/plugin/cabi/types.go | 100 +++++++++++++++++---------------- 4 files changed, 123 insertions(+), 50 deletions(-) diff --git a/internal/meta/meta.go b/internal/meta/meta.go index 40e1da6..92e4ee0 100644 --- a/internal/meta/meta.go +++ b/internal/meta/meta.go @@ -1,5 +1,7 @@ // Package meta 收集 HomeAgent 内核的全部元数据。 // 版本号通过 `go build -ldflags` 注入，默认值为 dev 版本。 +// 此文件是 ABI 版本号与 dispatch method ID 的唯一数据源。 +// SDK 仓的 meta/meta.go 应与此保持同步。 package meta var ( @@ -15,9 +17,70 @@ var ( // KernelName 是内核名称。 KernelName = "HomeAgent" + + // SDKCompatibleVersion 是此内核兼容的最低 SDK 版本（semver）。 + SDKCompatibleVersion = "0.8.0" ) // FullVersion 返回完整的版本字符串。 func FullVersion() string { return KernelName + " v" + Version + " (" + Commit + ")" } + +// ---- ABI 版本（C ABI 协议版本，插件与内核通信用） ---- + +const ( + ABIVersion = 1 + ABIVersionMin = 1 +) + +// ---- Dispatch Method IDs ---- +// 核心→插件：这些 ID 通过 CoreAPI.dispatch 传递，标识 SDK 调用。 +// 插件端的 C enum 定义在 plugindev 的 C ABI header 模板中。 +const ( + CoreRegisterTool = 1 + CoreRegisterStage = 2 + CoreRegisterOutputCh = 3 + CoreRegisterPluginAPI = 4 + CoreInjectText = 5 + CoreInjectInterruptText = 6 + CoreInjectTextNoMemory = 7 + CoreSetAutoRestart = 8 + CoreMemoryRecall = 9 + CoreMemoryCommit = 10 + CoreMemoryIntrospect = 11 + CoreMemoryMerge = 12 + CoreMemoryPurge = 13 + CoreDocQuery = 14 + CoreKnowledgeSearch = 15 + CoreSettingsGet = 16 + CoreSettingsSet = 17 + CoreSettingsRegisterDef = 18 + CoreLLMListSources = 19 + CoreLLMSetSource = 20 + CoreSocialGetPerson = 21 + CoreSocialGetNetwork = 22 + CoreSubscribe = 23 + CoreUnsubscribe = 24 + CoreFreeString = 25 + CoreSettingsGetCore = 26 + CoreSettingsSetCore = 27 + CoreSettingsListCore = 28 + CoreSettingsGetPlugin = 29 + CoreSettingsSetPlugin = 30 + CoreSettingsListPlugin = 31 + CoreDocInsert = 32 + CoreDocRemove = 33 + CoreDocStats = 34 + CoreKnowledgeAdd = 35 + CoreKnowledgeList = 36 + CoreLLMCurrentSource = 37 + CoreSocialGetTrait = 38 + CoreSocialGetRelations = 39 + CoreSocialListPersons = 40 + CoreTextMemoryAppend = 41 + CoreSettingsList = 42 + CoreSettingsDefs = 43 + CoreSettingsDump = 44 + CoreSettingsPlugins = 45 +) diff --git a/internal/plugin/cabi/loader.c b/internal/plugin/cabi/loader.c index 7c13312..d1c0cdd 100644 --- a/internal/plugin/cabi/loader.c +++ b/internal/plugin/cabi/loader.c @@ -4,6 +4,8 @@ #include #include +// HOMEAGENT_ABI_VERSION 与 internal/meta/meta.go ABIVersion 同步。 +// C ABI 通过 version/version_min 协商，旧插件不受影响。 #define HOMEAGENT_ABI_VERSION 1 // PluginAPI — provided by the plugin diff --git a/internal/plugin/cabi/loader.go b/internal/plugin/cabi/loader.go index 643d408..e2899ab 100644 --- a/internal/plugin/cabi/loader.go +++ b/internal/plugin/cabi/loader.go @@ -6,6 +6,8 @@ package cabi #cgo LDFLAGS: -ldl #include +// HOMEAGENT_ABI_VERSION 是当前内核的 ABI 版本号，与 internal/meta/meta.go ABIVersion 保持同步。 +// 旧插件使用低版本 ABI 不受影响——C ABI wrapper 通过 version/version_min 字段协商兼容。 #define HOMEAGENT_ABI_VERSION 1 // PluginAPI — provided by the plugin via plugin_init() @@ -94,6 +96,10 @@ func Load(soPath, name string, config map[string]interface{}) (*Handle, error) { C.lib_close(lib) return nil, fmt.Errorf("plugin %s: invalid PluginAPI (version=%d)", name, int(api.version)) } + if int(api.version) > ABIVersion { + C.lib_close(lib) + return nil, fmt.Errorf("plugin %s: ABI version %d > core %d, requires newer HomeAgent core", name, int(api.version), ABIVersion) + } id := atomic.AddInt32(&nextID, 1) ps := &pluginState{id: id, name: name, api: api} @@ -146,7 +152,7 @@ func (h *Handle) FreeCoreAPI() { // Start calls the plugin's Start with a CoreAPI pointer. func (h *Handle) Start(corePtr unsafe.Pointer) error { var cErr *C.char - if ret := int(C.call_start_plugin(h.api, corePtr, C.int(1), &cErr)); ret != 0 { + if ret := int(C.call_start_plugin(h.api, corePtr, C.int(ABIVersion), &cErr)); ret != 0 { errMsg := "" if cErr != nil { errMsg = C.GoString(cErr); C.api_free_string(h.api, cErr) } return fmt.Errorf("start_plugin: %s", errMsg) diff --git a/internal/plugin/cabi/types.go b/internal/plugin/cabi/types.go index c734a57..8b732d5 100644 --- a/internal/plugin/cabi/types.go +++ b/internal/plugin/cabi/types.go @@ -1,56 +1,58 @@ package cabi -// ABI version constants +import "gitcode.com/JianFeeeee/HomeAgent/internal/meta" + +// ABI version constants — single source of truth is meta.go const ( - ABIVersion = 1 - ABIVersionMin = 1 + ABIVersion = meta.ABIVersion + ABIVersionMin = meta.ABIVersionMin ) -// Dispatch method IDs (mirrors the plugin side constants) +// Dispatch method IDs — single source of truth is meta.go const ( - CoreRegisterTool = 1 - CoreRegisterStage = 2 - CoreRegisterOutputCh = 3 - CoreRegisterPluginAPI = 4 - CoreInjectText = 5 - CoreInjectInterruptText = 6 - CoreInjectTextNoMemory = 7 - CoreSetAutoRestart = 8 - CoreMemoryRecall = 9 - CoreMemoryCommit = 10 - CoreMemoryIntrospect = 11 - CoreMemoryMerge = 12 - CoreMemoryPurge = 13 - CoreDocQuery = 14 - CoreKnowledgeSearch = 15 - CoreSettingsGet = 16 - CoreSettingsSet = 17 - CoreSettingsRegisterDef = 18 - CoreLLMListSources = 19 - CoreLLMSetSource = 20 - CoreSocialGetPerson = 21 - CoreSocialGetNetwork = 22 - CoreSubscribe = 23 - CoreUnsubscribe = 24 - CoreFreeString = 25 - CoreSettingsGetCore = 26 - CoreSettingsSetCore = 27 - CoreSettingsListCore = 28 - CoreSettingsGetPlugin = 29 - CoreSettingsSetPlugin = 30 - CoreSettingsListPlugin = 31 - CoreDocInsert = 32 - CoreDocRemove = 33 - CoreDocStats = 34 - CoreKnowledgeAdd = 35 - CoreKnowledgeList = 36 - CoreLLMCurrentSource = 37 - CoreSocialGetTrait = 38 - CoreSocialGetRelations = 39 - CoreSocialListPersons = 40 - CoreTextMemoryAppend = 41 - CoreSettingsList = 42 - CoreSettingsDefs = 43 - CoreSettingsDump = 44 - CoreSettingsPlugins = 45 + CoreRegisterTool = meta.CoreRegisterTool + CoreRegisterStage = meta.CoreRegisterStage + CoreRegisterOutputCh = meta.CoreRegisterOutputCh + CoreRegisterPluginAPI = meta.CoreRegisterPluginAPI + CoreInjectText = meta.CoreInjectText + CoreInjectInterruptText = meta.CoreInjectInterruptText + CoreInjectTextNoMemory = meta.CoreInjectTextNoMemory + CoreSetAutoRestart = meta.CoreSetAutoRestart + CoreMemoryRecall = meta.CoreMemoryRecall + CoreMemoryCommit = meta.CoreMemoryCommit + CoreMemoryIntrospect = meta.CoreMemoryIntrospect + CoreMemoryMerge = meta.CoreMemoryMerge + CoreMemoryPurge = meta.CoreMemoryPurge + CoreDocQuery = meta.CoreDocQuery + CoreKnowledgeSearch = meta.CoreKnowledgeSearch + CoreSettingsGet = meta.CoreSettingsGet + CoreSettingsSet = meta.CoreSettingsSet + CoreSettingsRegisterDef = meta.CoreSettingsRegisterDef + CoreLLMListSources = meta.CoreLLMListSources + CoreLLMSetSource = meta.CoreLLMSetSource + CoreSocialGetPerson = meta.CoreSocialGetPerson + CoreSocialGetNetwork = meta.CoreSocialGetNetwork + CoreSubscribe = meta.CoreSubscribe + CoreUnsubscribe = meta.CoreUnsubscribe + CoreFreeString = meta.CoreFreeString + CoreSettingsGetCore = meta.CoreSettingsGetCore + CoreSettingsSetCore = meta.CoreSettingsSetCore + CoreSettingsListCore = meta.CoreSettingsListCore + CoreSettingsGetPlugin = meta.CoreSettingsGetPlugin + CoreSettingsSetPlugin = meta.CoreSettingsSetPlugin + CoreSettingsListPlugin = meta.CoreSettingsListPlugin + CoreDocInsert = meta.CoreDocInsert + CoreDocRemove = meta.CoreDocRemove + CoreDocStats = meta.CoreDocStats + CoreKnowledgeAdd = meta.CoreKnowledgeAdd + CoreKnowledgeList = meta.CoreKnowledgeList + CoreLLMCurrentSource = meta.CoreLLMCurrentSource + CoreSocialGetTrait = meta.CoreSocialGetTrait + CoreSocialGetRelations = meta.CoreSocialGetRelations + CoreSocialListPersons = meta.CoreSocialListPersons + CoreTextMemoryAppend = meta.CoreTextMemoryAppend + CoreSettingsList = meta.CoreSettingsList + CoreSettingsDefs = meta.CoreSettingsDefs + CoreSettingsDump = meta.CoreSettingsDump + CoreSettingsPlugins = meta.CoreSettingsPlugins )