homeagent-sdk/docs/guide/first-plugin.md

第一个 Go 插件

以下是一个能直接跑起来的最小插件：注册一个工具、声明一项配置、处理停止与卸载。

1. 生成工程

hmapdev init myplugin
cd myplugin

生成的结构：

myplugin/
├── plg.json       — 插件元信息（名称、版本、入口、目标平台）
├── plugin.go      — 插件实现
├── go.mod         — 模块定义
├── README.md
└── thirdpart/     — 外部源码存放目录（可选）

hmapdev build 时会在构建目录自动生成子进程运行时（z_proc_gen.go 等）， 不需要手工创建，也不要提交。

2. 插件实现

插件的全部契约是一个 Plugin 接口（API 参考）：

方法	何时调用
Name() string	内核需要标识这个插件时
Start(*sdk.PluginSDK) error	插件加载后。在这里注册工具、通道、配置
Stop() error	插件停止时（重载、禁用、内核退出都会触发）

再加一个工厂函数。名字必须是 NewPluginFactory —— 生成的运行时按这个名字调用：

func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) {
    return &Plugin{name: name}, nil
}

!!! warning "不要写成 NewPlugin" 生成的子进程运行时调用的入口是 NewPluginFactory。仓库里有 3 个早期示例 同时保留了两个名字（NewPlugin 只是遗留别名），但新插件只写 NewPluginFactory 即可。写错名字的后果是编译能过、加载时找不到入口。

3. 一个完整的例子

这是一个「打招呼」工具，带一项配置：

package main

import (
	"fmt"

	"gitcode.com/JianFeeeee/homeagent-sdk/sdk"
)

type Plugin struct {
	name string
	sdk  *sdk.PluginSDK
}

func (p *Plugin) Name() string { return p.name }

func (p *Plugin) Start(s *sdk.PluginSDK) error {
	p.sdk = s

	// ① 声明配置项：内核会把它渲染到 WebUI 设置页
	s.Settings().RegisterDef(sdk.ConfigDef{
		Key:         "plugin.myplugin.greeting",
		Default:     "hello",
		Type:        "string",
		DisplayName: "问候语",
		Description: "打招呼时使用的前缀",
		Category:    "myplugin",
	})

	// ② 注册工具：模型看到 Description 后决定是否调用
	tp := p.name + "_"
	s.RegisterTool(tp+"hello", sdk.ToolDef{
		Name:        tp + "hello",
		Description: "向指定的人打招呼",
		Parameters: map[string]interface{}{
			"type": "object",
			"properties": map[string]interface{}{
				"who": map[string]interface{}{
					"type":        "string",
					"description": "要打招呼的对象",
				},
			},
			"required": []string{"who"},
		},
	}, p.handleHello)

	// ③ 卸载（插件被删除）前清理自己产生的数据。
	//    注意与 Stop 的区别：Stop 在每次重载时也会触发。
	s.RegisterOnRemoveHandler(func() {
		fmt.Printf("[%s] 清理数据\n", p.name)
	})

	return nil
}

func (p *Plugin) Stop() error { return nil }

func (p *Plugin) handleHello(args map[string]interface{}) (interface{}, error) {
	who, _ := args["who"].(string)

	greeting := "hello"
	if v, err := p.sdk.Settings().Get("plugin.myplugin.greeting"); err == nil && v != "" {
		greeting = v
	}

	return map[string]interface{}{
		"content": fmt.Sprintf("%s, %s!", greeting, who),
	}, nil
}

func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) {
	return &Plugin{name: name}, nil
}

4. 工具返回值的两条约定

ToolHandler 返回 (interface{}, error)，模型侧看到的是一条 tool message：

• 正常结果：返回一个 map，把要展示给模型的文本放在 content 字段。 未识别的字段也会一并传给模型，可以放结构化数据。
• 业务失败：返回 map[string]interface{}{"isError": true, "content": "原因"} 并返回 nil error。这样模型能看到失败原因并自行调整； 若返回 Go 的 error，那是工具调用本身出错，语义不同。

func errorResult(msg string) map[string]interface{} {
	return map[string]interface{}{"isError": true, "content": msg}
}

5. 构建与安装

hmapdev build            # 默认产出多平台 bundle
# → dist/myplugin_bundle.hmap

hmapdev build --no-bundle  # 只构建当前平台
# → dist/myplugin_linux_amd64.hmap

安装到内核：在 WebUI 的插件管理页上传 .hmap，或从 URL / 本地路径安装。 详见 打包与发布。

下一步

• 能力边界 —— 哪些 API 外部插件能用
• 工具（Tools） —— ToolDef 的完整字段
• 记忆（Memory） —— 让插件读写长期记忆
• 示例插件 —— example/memo 是个完整的可读实现