# 从零开发 HomeAgent QQ 插件（v1.2.x 版）本文配套 **内核 1.2.x / SDK 1.2.0 / 子进程 RPC 协议 2**。如果你读过旧版（plugindev / `plugin.so` / C ABI 时期）的那篇文章，请以本篇为准——那一版的工具链名、产物格式、通信机制已整体更换。 > **三个关键变化先记住** > 1. 工具链 `plugindev` → **`hmapdev`**（SDK 存储目录也从 `~/.homeagent/plugindev/sdk` 迁到 `~/.homeagent/hmapdev/sdk`，旧目录会自动沿用） > 2. 插件产物 `plugin.so` → **`plugin.bin`**，外部插件是**独立子进程**，不再是 `dlopen` 进来的动态库 > 3. 通信机制：**stdio JSON-RPC（控制面）+ 共享内存段（数据面）+ 事件环（通知面）**，协议版本 **2** --- ## 一、三层工具概览 - **`hmapdev`**（SDK 仓库 `tools/hmapdev/`）— 本地脚手架 + 交叉编译 + 打包，支持 Go 和 Lua 插件 - **`pluginmgr`**（homed 内置插件）— HTTP API 安装/卸载/查看，默认 `127.0.0.1:9876` - **`plgreload`**（Agent 内核内置工具）— 按入口文件 hash **增量**热重载三者分工要说清：`plgreload` 只在入口文件内容变化时才动，而插件进程被 kill 时二进制恰恰没变，它不会重启——那种情况要用 **`plugin_restart`**。 --- ## 二、安装 hmapdev `hmapdev` 提供预编译二进制，无需安装 Go 工具链即可打包（交叉编译是纯 Go，`CGO_ENABLED=0`）： - **Linux x86_64** — `hmapdev_linux_amd64.tar.gz` - **macOS x86_64 / arm64** — `hmapdev_darwin_*.tar.gz` ```bash wget https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/v1.2.0/hmapdev_linux_amd64.tar.gz tar xzf hmapdev_linux_amd64.tar.gz sudo mv hmapdev /usr/local/bin/ ``` 也可从 SDK 仓库源码构建（需 Go 1.25+）： ```bash git clone https://gitcode.com/JianFeeeee/homeagent-sdk.git cd homeagent-sdk/tools/hmapdev go build -o hmapdev . ``` SDK 版本管理（`hmapdev init` 需要一份已安装的 SDK）： ```bash hmapdev sdk latest # 查看远程最新版本号 hmapdev sdk install v1.2.0 # 下载指定版本 hmapdev sdk use v1.2.0 # 切换激活版本 hmapdev sdk list / current / path ``` > **SDK 版本号规则**：SDK 跟随内核**中版本**，patch 位恒为 `.0`。所以面向内核 1.2.x 线的 SDK 就是 **1.2.0**，不存在 1.2.1。内核发 patch 只做 bugfix、不碰公开接口，所以 SDK 不跟版，插件也不需要跟版。 --- ## 三、创建项目 ```bash hmapdev init qqbot # Go 插件 hmapdev init qqbot --lua # Lua 插件 ``` 项目结构： ``` qqbot/ ├── plg.json # 插件元信息 ├── plugin.go # 插件代码 ├── go.mod # Go 模块 ├── README.md ├── thirdpart/ # 可选：外部 Go 源码目录 ├── build/ # 交叉编译输出（纯 Go，无 cgo） │ └── plugin.bin # 子进程插件产物 └── dist/ # 打包输出 └── qqbot_linux_amd64.hmap ``` `plg.json`： ```json { "name": "qqbot", "name_zh": "QQ 机器人", "name_en": "QQ Bot", "version": "0.1.0", "description": "通过 NapCat 收发 QQ 消息", "author": "你的名字", "entry": "plugin.bin", "sdk": "1.2.0", "tags": ["qq", "messaging"], "targets": "linux/amd64,darwin/arm64" } ``` 两个容易踩的点： - `entry` 是 **`plugin.bin`**（不是 `plugin.so`） - `sdk` 必须是**完整版本号**（如 `1.2.0`）。工具链据此在本地 SDK 存储里选版本，未命中会明确报错并给出安装命令——不会静默用错版本 `go.mod` 带一条 `replace` 指向当前激活的本地 SDK（SDK 模块不在公共 proxy 上，所以必须 replace；`hmapdev init` 会自动写好）： ``` module qqbot go 1.25.0 require gitcode.com/JianFeeeee/homeagent-sdk v1.2.0 replace gitcode.com/JianFeeeee/homeagent-sdk => ~/.homeagent/hmapdev/sdk/v1.2.0 ``` `hmapdev build` 每次也会按 `plg.json` 的 `sdk` 版本把 require/replace 同步到本地 SDK 存储里对应的那份。 `plugin.go` 骨架实现 `sdk.Plugin` 接口（`Name()` / `Start()` / `Stop()`）并导出 `NewPlugin` 工厂函数。 --- ## 四、SDK 核心 API 插件在 `Start()` 中拿到 `*sdk.PluginSDK`，通过它注册能力： ```go // 配置项 s.Settings().RegisterDef(sdk.ConfigDef{...}) s.Settings().Get(key) / Set(key, val) / List(prefix) s.Settings().GetCore(key) / SetCore(key, val) // 读/写全局 config 表 s.Settings().GetPlugin(plugin, key) // 读其他插件配置 // 工具（LLM 可调用） s.RegisterTool(name, sdk.ToolDef{Name, Description, Parameters}, handler) // 输出通道（LLM 回复路由到此通道发出） s.RegisterOutputChannel(name, caps, desc, sdk.ChannelDef{...}, handler) // 输入通道（声明外部消息源） s.RegisterInputChannel(name, sdk.ChannelDef{...}) // 注入文本到 Agent 管道 s.InjectText(source, channel, text) // 普通注入（带记忆） s.InjectInterruptText(source, channel, text) // 中断注入（立即处理） s.InjectTextNoMemory(source, channel, text) // 注入但不记记忆 // v1.2.0 起可用 Opts 变体显式声明记忆/裁剪行为： // s.InjectTextOpts(source, channel, text, sdk.InjectOptions{NoMemory:true, ContextPolicy:...}) // 生命周期钩子 s.RegisterStage(stage, handler) // 全局阶段 s.RegisterStage(stage, handler, sdk.StageScopeOwnTools) // 仅自己的工具 // 其他能力 s.Memory() // 图记忆 s.TextMemory() // 文本记忆 s.DocMemory() // 文档记忆 s.Knowledge() // 知识库 s.LLM() // LLM 调用 s.Social() // 社交图谱 s.Events() // 内核事件订阅 s.SetAutoRestart(true) // 崩溃后自动重载（默认 true） ``` **七个阶段钩子**： | 阶段 | 时机 | |---|---| | `StageOnInput` | 用户输入到达 | | `StagePreAction` | 即将执行 Action | | `StagePostAction` | Action 执行完毕 | | `StageBeforeToolcall` | LLM 请求调用工具前 | | `StageAfterToolcall` | 工具返回结果后 | | `StageBeforeOutput` | 即将输出给用户 | | `StageAfterOutput` | 输出完毕 | **两个值得注意的设计**： - `SettingsAPI` 只有 `Get/Set`，**没有** `GetString/GetInt/GetBool`。需要自行类型断言，或者写泛型辅助函数（下面的 `getSetting`） - `ChannelDef{NoMemory, Cleaner}` 控制的是**计算层**（向量/关键词/蒸馏），不改原文。`NoMemory=true` 适合 QQ 群消息、RSS 这类噪声源；`Cleaner` 是计算层的过滤函数，原文始终保留。v1.2.0 起 `ChannelDef` 还多了 `ContextPolicy` --- ## 五、配置项注册 ```go s.Settings().RegisterDef(sdk.ConfigDef{ Key: "plugin.qqbot.listen", Default: "0.0.0.0:25580", Type: "string", DisplayName: "监听地址", Description: "Webhook HTTP 监听地址", Category: "qqbot", }) s.Settings().RegisterDef(sdk.ConfigDef{ Key: "plugin.qqbot.napcat_url", Default: "http://127.0.0.1:3000", Type: "string", DisplayName: "NapCat 地址", Category: "qqbot", }) ``` 带选项的配置项（下拉框）： ```go s.Settings().RegisterDef(sdk.ConfigDef{ Key: "plugin.qqbot.dm_policy", Default: "open", Type: "string", DisplayName: "私聊策略", Description: "open / allowlist / disabled", Category: "qqbot", Options: []string{"open", "allowlist", "disabled"}, }) ``` 配置有两张表，别搞混： - **插件专用表** `config_`：`Get(key)` / `Set(key, val)`，键名是简单字符串 - **全局核心表** `config`：`GetCore(key)` / `SetCore(key, val)`，键名约定 `plugin..`，CLI 的 `settings set plugin..` 写的就是这张表插件若想同时兼容 WebUI（写插件表）和 CLI（写核心表），应在 `Get()` 失败时回退到 `GetCore("plugin.." + key)`： ```go func getSetting[T string | int64 | float64](s sdk.SettingsAPI, name, key string, fallback T) T { if v, err := s.Get(key); err == nil && v != nil { if t, ok := v.(T); ok { return t } } if v, err := s.GetCore("plugin." + name + "." + key); err == nil && v != nil { if t, ok := v.(T); ok { return t } } return fallback } ``` --- ## 六、工具注册 ```go s.RegisterTool("qqbot_get_groups", sdk.ToolDef{ Name: "qqbot_get_groups", Description: "获取 QQ 群列表，可按关键词搜索群名", Parameters: map[string]interface{}{ "type": "object", "properties": map[string]interface{}{ "keyword": map[string]interface{}{ "type": "string", "description": "搜索关键词，不传则返回全部群", }, }, }, }, func(args map[string]interface{}) (interface{}, error) { return p.napcat("get_group_list", map[string]interface{}{}) }) ``` 工具名约定 `"_"`。返回值是一个 `map`，文本放在 `content` 键；出错时加 `isError: true`。与 NapCat 通信的辅助函数（实际项目通常拆成两个）： ```go // rawNapcat 返回原始 JSON 字符串 func (p *Plugin) rawNapcat(action string, params map[string]interface{}) (string, error) { data, _ := json.Marshal(params) url := fmt.Sprintf("%s/%s", p.napcatURL, action) resp, err := p.httpClient.Post(url, "application/json", bytes.NewReader(data)) if err != nil { return "", fmt.Errorf("napcat %s: %w", action, err) } defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) return string(body), nil } // napcat 返回解析后的 interface{} func (p *Plugin) napcat(action string, params map[string]interface{}) (interface{}, error) { raw, err := p.rawNapcat(action, params) if err != nil { return nil, err } var result interface{} json.Unmarshal([]byte(raw), &result) return result, nil } ``` --- ## 七、输出通道注册这一节是理解 HomeAgent 路由的关键：**内核不自动回复任何消息**。插件注册输出通道后，内核为它自动生成两个 LLM 工具——`output_send__` 和 `output_send___help`——LLM 想回复时必须显式调用。 ```go s.RegisterOutputChannel("qqbot", sdk.CapText|sdk.CapFile|sdk.CapImage|sdk.CapAudio, `发送QQ群聊/私聊消息，支持文字、语音、图片、文件。 meta JSON 格式： { "group_id": 123456, "user_id": 123456, "reply_to": 12345 } type 枚举: text（文字）/ voice（语音转文字后发送）/ image（图片URL）/ file（文件URL）`, sdk.ChannelDef{NoMemory: false}, p.handleChannelOutput, ) ``` `caps` 是位掩码：`CapText(1)` / `CapFile(2)` / `CapImage(4)` / `CapAudio(8)` / `CapStructured(16)`。 handler 的职责就是把 payload 投递出去： ```go func (p *Plugin) handleChannelOutput(args map[string]interface{}) (interface{}, error) { payload, _ := args["payload"].(string) msgType, _ := args["type"].(string) metaStr, _ := args["meta"].(string) var meta struct { GroupID int64 `json:"group_id"` UserID int64 `json:"user_id"` ReplyTo int64 `json:"reply_to"` } json.Unmarshal([]byte(metaStr), &meta) params := map[string]interface{}{"message": payload} if msgType == "image" { params["message"] = fmt.Sprintf("[CQ:image,file=%s]", payload) } if meta.GroupID != 0 { return p.napcat("send_group_msg", params) } if meta.UserID != 0 { return p.napcat("send_private_msg", params) } return nil, fmt.Errorf("需要 group_id 或 user_id") } ``` > **对比 v0.9.0 时代的一个实质改进**：C ABI 时期 `output_send` 受「cgo 不可嵌套」限制，只能异步 fire-and-forget，永远返回 `{status:queued}` + `err=nil`——模型收到「已发送」而消息实际可能没送达（现网 7 天内出现过 2 次）。现在走 RPC 同步等真实结果，**三态回报 sent / error / unconfirmed**。 --- ## 八、接收外部消息插件在自己的 HTTP 端口上收 NapCat 的 webhook，解析后注入 Agent 管道： ```go func (p *Plugin) Start(s *sdk.PluginSDK) error { s.SetAutoRestart(true) p.sdk = s // 注册配置、工具、输出通道…… // before_toolcall 阶段钩子：高危操作确认（仅自己的工具） s.RegisterStage(sdk.StageBeforeToolcall, p.beforeOwnToolcall, sdk.StageScopeOwnTools) mux := http.NewServeMux() mux.HandleFunc("/", p.handleWebhook) p.srv = &http.Server{Addr: p.listenAddr, Handler: mux} go p.srv.ListenAndServe() return nil } func (p *Plugin) handleWebhook(w http.ResponseWriter, r *http.Request) { body, _ := io.ReadAll(r.Body) var evt struct { PostType string `json:"post_type"` MessageType string `json:"message_type"` MessageID int64 `json:"message_id"` UserID int64 `json:"user_id"` GroupID int64 `json:"group_id"` RawMessage string `json:"raw_message"` Sender *struct { Nickname string `json:"nickname"` Card string `json:"card,omitempty"` } `json:"sender,omitempty"` } json.Unmarshal(body, &evt) if evt.PostType != "message" { return } // 策略检查 if evt.MessageType == "private" && !p.isDMAllowed(evt.UserID) { return } if evt.MessageType == "group" { if !p.isGroupAllowed(evt.GroupID) { return } if !p.isAtBot(evt.RawMessage) { return // 群消息必须 @ 机器人 } } nickname := "" if evt.Sender != nil { nickname = evt.Sender.Nickname if evt.Sender.Card != "" { nickname = evt.Sender.Card } } // 存消息、分配本地 id p.mu.Lock() localID := p.nextID p.nextID++ p.messages = append(p.messages, msg) p.mu.Unlock() tp := p.name + "_" outputTool := "output_send__" + p.name var interrupt string if evt.MessageType == "group" { interrupt = fmt.Sprintf( "来自%s的群聊消息，通过id%d使用%sget_message工具获取消息正文。"+ "如果消息包含引用回复，使用%sget_history（group_id=%d）拉取最近消息以确认引用上下文。"+ "必须使用%s工具回复该群聊（用%s_help查看JSON格式要求），系统不会自动发送回复", nickname, localID, tp, tp, evt.GroupID, outputTool, outputTool) } else { interrupt = fmt.Sprintf( "来自%s的私聊消息，通过id%d使用%sget_message工具获取消息正文。"+ "必须使用%s工具回复对方（用%s_help查看JSON格式要求），系统不会自动发送回复", nickname, localID, tp, outputTool, outputTool) } if p.adminID > 0 && evt.UserID == p.adminID { interrupt = "【重要！老大消息】" + interrupt } p.sdk.InjectInterruptText(p.name, p.name, interrupt) } ``` 注意注入文案里的两句话：**「必须使用 output_send__qq 工具回复」** 和 **「系统不会自动发送回复」**。这不是客套话——内核确实不做自动路由，注入只负责把消息推进管道，回不回、怎么回由 LLM 决定。 ### 阶段钩子：高危操作要 confirm ```go func (p *Plugin) beforeOwnToolcall(ctx *sdk.StageContext) error { ctx.Lock() defer ctx.Unlock() if len(ctx.ToolCalls) == 0 { return nil } tc := &ctx.ToolCalls[0] if tc.Name == p.name+"_group_manage" { cmd, _ := tc.Arguments["command"].(string) if requiresConfirmGroupCommand(cmd) { if ok, _ := tc.Arguments["confirm"].(bool); !ok { msg := fmt.Sprintf("QQ群管理命令 %s 属于高风险操作，必须显式传入 confirm=true 后才能执行", cmd) ctx.Response = &msg return nil } } } return nil } ``` 这类检查放在插件层，不依赖 LLM 的纪律性——即使 prompt injection 骗过了模型，插件层的闸门依然拦得住。 --- ## 九、编译与部署 ```bash cd qqbot hmapdev build ``` 输出： ``` build/plugin.bin # 子进程产物（纯 Go，无 cgo） dist/qqbot_linux_amd64.hmap # ZIP：plugin.json + plugin.bin ``` 多目标交叉编译： ```bash hmapdev build --target windows/amd64 --target darwin/arm64 hmapdev build --target all ``` > **Windows 目标不支持**。协议 2 的统一共享内存区未移植 Windows——内核本身也放弃了 Windows 原生支持，改走 WSL2。这是刻意的收敛，不是遗漏。 Lua 插件（无需 Go 工具链）： ```bash hmapdev init qqbot --lua hmapdev build --target lua ``` ### 部署方式一：经 pluginmgr HTTP API 安装 ```bash # 从 URL 安装 curl -X POST http://127.0.0.1:9876/plugins \ -H "Content-Type: application/json" \ -d '{"url":"http://example.com/qqbot_linux_amd64.hmap"}' # 从本地路径安装 curl -X POST http://127.0.0.1:9876/plugins \ -H "Content-Type: application/json" \ -d '{"path":"/path/to/dist/qqbot_linux_amd64.hmap"}' ``` 方式二：开发模式直接铺产物 ```bash mkdir -p /plugins/qqbot cp build/plugin.bin /plugins/qqbot/plugin.bin cp plugin.json /plugins/qqbot/plugin.json systemctl restart homeagent ``` 其他管理操作： ```bash curl http://127.0.0.1:9876/plugins # 列表 curl http://127.0.0.1:9876/plugins/qqbot # 详情 curl -X DELETE http://127.0.0.1:9876/plugins/qqbot # 卸载 ``` 安装后要**热重载**才生效；重载不走 HTTP，用内核内置的 `plgreload` 工具（或 `plugin_restart`，见下节）。 ### `plgreload` 与 `plugin_restart` 的分工 - **`plgreload`**：扫描插件目录变更，按**入口文件 hash 增量**重载。文件真变了它才动 - **`plugin_restart`**：无条件重启单个插件。适用于「插件进程已死但 crash_count 已达自动重启上限」，或「换了 plugin.bin 要立即生效」 - **`plugin_list`**：看 `loaded` / `alive` / `pid` / `crash_count` / `channel` - **`plugin_status`**：全量运行期快照 + dead/unhealthy 汇总。**工具调不通时第一个该跑的就是它** --- ## 十、配置 NapCat NapCat 支持 Windows / Linux / Docker，配置方式相同——把 webhook 指向插件的监听地址： ```json { "httpPostUrls": ["http://插件IP:25580/"] } ``` 插件与 NapCat 之间走 HTTP，不绑定操作系统。NapCat 收到消息 POST 到插件 webhook，插件调用 NapCat 的 OneBot v11 HTTP API 发回复。 --- ## 十一、QA **Q：装完插件工具没出现？** 先跑 `plugin_status` 确认进程 `alive`。若 `alive=false`，看 `crash_count`——达到上限后不会再自动重启，需要 `plugin_restart`。 **Q：改了 plugin.bin 但跑的还是旧代码？** `plgreload` 按入口文件 hash 判断，理论上会重载；如果进程是被 kill 的（二进制没变），它不会动，用 `plugin_restart`。 **Q：从旧版本升级要注意什么？** 1.0.0 换掉了 C ABI，1.2.0 把协议升到 2，两次都**不兼容**：存量外部插件必须用配套 `hmapdev` 重编为 `plugin.bin`，且与内核**同批**安装（不支持滚动升级）。 **Q：`sdk` 字段写 `1.2` 行不行？** 不行，必须写**完整版本号**（`1.2.0`）。工具链据此选 SDK，未命中会直接报错并给出安装命令。 **Q：参数拿到的类型不对？** `SettingsAPI` 只返回 `interface{}`，需要类型断言。数值在 JSON 里是 `float64`，整数也可能以 `float64` 回来——上面的 `getSetting` 泛型辅助函数可以兜住大部分情况。 **Q：从哪里看完整的 QQ 插件实现？** `example/qq/plugin.go` 含全部功能：文件收发、语音、图片、群管理、RCON 转发。 --- ## 十二、和旧版的差异速查 | 项目 | 旧版（≤0.9.0） | 现在（1.2.x） | |---|---|---| | 工具链 | `plugindev` | **`hmapdev`** | | SDK 存储 | `~/.homeagent/plugindev/sdk` | **`~/.homeagent/hmapdev/sdk`** | | 产物 | `plugin.so` | **`plugin.bin`** | | 加载方式 | `dlopen` 动态库，同进程 | **子进程**，stdio RPC + 共享内存 | | 协议 | C ABI（`CABINum`） | **RPC 协议 2** | | Stage 写回 | 副本模型，lost update 35.8~36.8% | **共享内存，丢失率 0%** | | 插件崩溃 | 带崩整个 homed | **子进程独立崩溃 + 退避自动重启** | | 超时取消 | 假取消，goroutine 永久卡住 | **`Process.Kill()` 真取消** | | 注入语义 | 隐式（总是记记忆、不裁剪） | **`InjectOptions` 显式声明** | | 热重载 | 换 `.so` 必须重启 homed | **换 `plugin.bin` 即生效** | --- 项目地址：[gitcode.com/JianFeeeee/HomeAgent](https://gitcode.com/JianFeeeee/HomeAgent) SDK 地址：[gitcode.com/JianFeeeee/homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk) 适配：内核 1.2.2 ｜ SDK 1.2.0 ｜插件协议 2