refactor: lifecycle (#39)

* fix: release partially loaded native libraries on init failure

Co-authored-by: Copilot <copilot@github.com>

* refactor: rename Init to Initialize and Release to Shutdown for clarity

* refactor: make Init idempotent by removing ErrAlreadyInitialized

* refactor: rename Init to Initialize in TestMain for consistency

* refactor: make Release idempotent by removing ErrNotInitialized

Co-authored-by: Copilot <copilot@github.com>

* refactor: centralize native symbol registration and cleanup

- move native symbol bindings into Entry tables
- clear registered function vars after successful unload
- update api-check for Entry-based registrations

Co-authored-by: Copilot <copilot@github.com>

* fix: change library name variables to constants

Co-authored-by: Copilot <copilot@github.com>

* docs: update CHANGELOG

* docs: add concurrency safety notes to Init, IsInited, and Release functions

Co-authored-by: Copilot <copilot@github.com>

---------

Co-authored-by: Copilot <copilot@github.com>

Author: dongwlin

CHANGELOG.md

@@ -113,6 +113,9 @@
 - `Init()` 不再隐式应用默认全局配置，仅在显式传入对应 `WithXxx` 时才会调用设置。
 - `defaultInitConfig()` 已移除，`Init()` 现在直接使用 `initConfig{}` 初始化。
 - `WithPluginPaths` 会对输入切片进行拷贝，避免外部后续修改影响已构建的选项。
+- `Init()` 与 `Release()` 现为幂等操作：重复初始化或在未初始化状态下释放都会直接返回 `nil`；原导出的 `ErrAlreadyInitialized`、`ErrNotInitialized` 已移除。
+- `Init()` 过程中若某个原生库加载失败，会自动释放此前已成功加载的库，避免残留半初始化状态。
+- `LibraryLoadError` 现在会稳定包含库名与尝试加载的完整路径，便于排查动态库装载问题。
 
 #### Toolkit
 

internal/buffer/main_test.go

@@ -8,7 +8,7 @@ import (
 )
 
 func TestMain(m *testing.M) {
-	native.Init("")
+	native.Initialize("")
 
 	os.Exit(m.Run())
 }

internal/native/agent_client.go

@@ -10,6 +10,8 @@ import (
 
 var maaAgentClient uintptr
 
+const maaAgentClientName = "MaaAgentClient"
+
 var (
 	MaaAgentClientCreateV2                 func(identifier uintptr) uintptr
 	MaaAgentClientCreateTcp                func(port uint16) uintptr
@@ -28,14 +30,32 @@ var (
 	MaaAgentClientGetCustomActionList      func(client uintptr, buffer uintptr) bool
 )
 
+var agentClientEntries = []Entry{
+	{&MaaAgentClientCreateV2, "MaaAgentClientCreateV2"},
+	{&MaaAgentClientCreateTcp, "MaaAgentClientCreateTcp"},
+	{&MaaAgentClientDestroy, "MaaAgentClientDestroy"},
+	{&MaaAgentClientIdentifier, "MaaAgentClientIdentifier"},
+	{&MaaAgentClientBindResource, "MaaAgentClientBindResource"},
+	{&MaaAgentClientRegisterResourceSink, "MaaAgentClientRegisterResourceSink"},
+	{&MaaAgentClientRegisterControllerSink, "MaaAgentClientRegisterControllerSink"},
+	{&MaaAgentClientRegisterTaskerSink, "MaaAgentClientRegisterTaskerSink"},
+	{&MaaAgentClientConnect, "MaaAgentClientConnect"},
+	{&MaaAgentClientDisconnect, "MaaAgentClientDisconnect"},
+	{&MaaAgentClientConnected, "MaaAgentClientConnected"},
+	{&MaaAgentClientAlive, "MaaAgentClientAlive"},
+	{&MaaAgentClientSetTimeout, "MaaAgentClientSetTimeout"},
+	{&MaaAgentClientGetCustomRecognitionList, "MaaAgentClientGetCustomRecognitionList"},
+	{&MaaAgentClientGetCustomActionList, "MaaAgentClientGetCustomActionList"},
+}
+
 func initAgentClient(libDir string) error {
 	libName := getMaaAgentClientLibrary()
 	libPath := filepath.Join(libDir, libName)
 
 	handle, err := openLibrary(libPath)
 	if err != nil {
 		return &LibraryLoadError{
-			LibraryName: "MaaAgentClient",
+			LibraryName: maaAgentClientName,
 			LibraryPath: libPath,
 			Err:         err,
 		}
@@ -62,23 +82,24 @@ func getMaaAgentClientLibrary() string {
 }
 
 func registerAgentClient() {
-	purego.RegisterLibFunc(&MaaAgentClientCreateV2, maaAgentClient, "MaaAgentClientCreateV2")
-	purego.RegisterLibFunc(&MaaAgentClientCreateTcp, maaAgentClient, "MaaAgentClientCreateTcp")
-	purego.RegisterLibFunc(&MaaAgentClientDestroy, maaAgentClient, "MaaAgentClientDestroy")
-	purego.RegisterLibFunc(&MaaAgentClientIdentifier, maaAgentClient, "MaaAgentClientIdentifier")
-	purego.RegisterLibFunc(&MaaAgentClientBindResource, maaAgentClient, "MaaAgentClientBindResource")
-	purego.RegisterLibFunc(&MaaAgentClientRegisterResourceSink, maaAgentClient, "MaaAgentClientRegisterResourceSink")
-	purego.RegisterLibFunc(&MaaAgentClientRegisterControllerSink, maaAgentClient, "MaaAgentClientRegisterControllerSink")
-	purego.RegisterLibFunc(&MaaAgentClientRegisterTaskerSink, maaAgentClient, "MaaAgentClientRegisterTaskerSink")
-	purego.RegisterLibFunc(&MaaAgentClientConnect, maaAgentClient, "MaaAgentClientConnect")
-	purego.RegisterLibFunc(&MaaAgentClientDisconnect, maaAgentClient, "MaaAgentClientDisconnect")
-	purego.RegisterLibFunc(&MaaAgentClientConnected, maaAgentClient, "MaaAgentClientConnected")
-	purego.RegisterLibFunc(&MaaAgentClientAlive, maaAgentClient, "MaaAgentClientAlive")
-	purego.RegisterLibFunc(&MaaAgentClientSetTimeout, maaAgentClient, "MaaAgentClientSetTimeout")
-	purego.RegisterLibFunc(&MaaAgentClientGetCustomRecognitionList, maaAgentClient, "MaaAgentClientGetCustomRecognitionList")
-	purego.RegisterLibFunc(&MaaAgentClientGetCustomActionList, maaAgentClient, "MaaAgentClientGetCustomActionList")
+	for _, entry := range agentClientEntries {
+		purego.RegisterLibFunc(entry.ptrToFunc, maaAgentClient, entry.name)
+	}
+}
+
+func releaseAgentClient() error {
+	err := unloadLibrary(maaAgentClient)
+	if err != nil {
+		return err
+	}
+
+	unregisterAgentClient()
+
+	return nil
 }
 
-func unregisterAgentClient() error {
-	return unloadLibrary(maaAgentClient)
+func unregisterAgentClient() {
+	for _, entry := range agentClientEntries {
+		clearFuncVar(entry.ptrToFunc)
+	}
 }

internal/native/agent_server.go

@@ -11,6 +11,8 @@ import (
 
 var maaAgentServer uintptr
 
+const maaAgentServerName = "MaaAgentServer"
+
 var (
 	MaaAgentServerRegisterCustomRecognition func(name string, recognition MaaCustomRecognitionCallback, transArg unsafe.Pointer) bool
 	MaaAgentServerRegisterCustomAction      func(name string, action MaaCustomActionCallback, transArg unsafe.Pointer) bool
@@ -24,14 +26,27 @@ var (
 	MaaAgentServerDetach                    func()
 )
 
+var agentServerEntries = []Entry{
+	{&MaaAgentServerRegisterCustomRecognition, "MaaAgentServerRegisterCustomRecognition"},
+	{&MaaAgentServerRegisterCustomAction, "MaaAgentServerRegisterCustomAction"},
+	{&MaaAgentServerAddResourceSink, "MaaAgentServerAddResourceSink"},
+	{&MaaAgentServerAddControllerSink, "MaaAgentServerAddControllerSink"},
+	{&MaaAgentServerAddTaskerSink, "MaaAgentServerAddTaskerSink"},
+	{&MaaAgentServerAddContextSink, "MaaAgentServerAddContextSink"},
+	{&MaaAgentServerStartUp, "MaaAgentServerStartUp"},
+	{&MaaAgentServerShutDown, "MaaAgentServerShutDown"},
+	{&MaaAgentServerJoin, "MaaAgentServerJoin"},
+	{&MaaAgentServerDetach, "MaaAgentServerDetach"},
+}
+
 func initAgentServer(libDir string) error {
 	libName := getMaaAgentServerLibrary()
 	libPath := filepath.Join(libDir, libName)
 
 	handle, err := openLibrary(libPath)
 	if err != nil {
 		return &LibraryLoadError{
-			LibraryName: "MaaAgentServer",
+			LibraryName: maaAgentServerName,
 			LibraryPath: libPath,
 			Err:         err,
 		}
@@ -58,18 +73,24 @@ func getMaaAgentServerLibrary() string {
 }
 
 func registerAgentServer() {
-	purego.RegisterLibFunc(&MaaAgentServerRegisterCustomRecognition, maaAgentServer, "MaaAgentServerRegisterCustomRecognition")
-	purego.RegisterLibFunc(&MaaAgentServerRegisterCustomAction, maaAgentServer, "MaaAgentServerRegisterCustomAction")
-	purego.RegisterLibFunc(&MaaAgentServerAddResourceSink, maaAgentServer, "MaaAgentServerAddResourceSink")
-	purego.RegisterLibFunc(&MaaAgentServerAddControllerSink, maaAgentServer, "MaaAgentServerAddControllerSink")
-	purego.RegisterLibFunc(&MaaAgentServerAddTaskerSink, maaAgentServer, "MaaAgentServerAddTaskerSink")
-	purego.RegisterLibFunc(&MaaAgentServerAddContextSink, maaAgentServer, "MaaAgentServerAddContextSink")
-	purego.RegisterLibFunc(&MaaAgentServerStartUp, maaAgentServer, "MaaAgentServerStartUp")
-	purego.RegisterLibFunc(&MaaAgentServerShutDown, maaAgentServer, "MaaAgentServerShutDown")
-	purego.RegisterLibFunc(&MaaAgentServerJoin, maaAgentServer, "MaaAgentServerJoin")
-	purego.RegisterLibFunc(&MaaAgentServerDetach, maaAgentServer, "MaaAgentServerDetach")
+	for _, entry := range agentServerEntries {
+		purego.RegisterLibFunc(entry.ptrToFunc, maaAgentServer, entry.name)
+	}
+}
+
+func releaseAgentServer() error {
+	err := unloadLibrary(maaAgentServer)
+	if err != nil {
+		return err
+	}
+
+	unregisterAgentServer()
+
+	return nil
 }
 
-func unregisterAgentServer() error {
-	return unloadLibrary(maaAgentServer)
+func unregisterAgentServer() {
+	for _, entry := range agentServerEntries {
+		clearFuncVar(entry.ptrToFunc)
+	}
 }