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

第一个 Lua 插件

Lua 插件适合轻量、快速原型：不需要 Go 编译环境，改完重启内核即可生效。 但它有一个必须理解的限制 —— 执行模型是被动回调。

执行模型（先读这段）

Lua 插件跑在内核进程内的 gopher-lua 解释器里（单 Lua 状态 + 互斥锁）：

• 被动回调：main.lua 只在加载时执行一次。此后工具、阶段钩子、 输入输出通道全部由内核事件驱动回调你的 Lua 函数。插件不能自己启动后台任务。
• 没有并发：Lua 侧没有 goroutine、协程调度，也没有 os / io 库和 socket 监听。 唯一主动出站通道是 sdk.http.get/post（同步请求）。
• 任何阻塞循环都会持锁卡死该插件的全部调用。

!!! warning "要常驻服务就用 Go 插件" 需要监听端口、后台轮询、定时任务的，请用 Go 插件 （可自行启动 goroutine）。Lua 侧的等价做法是事件驱动：把逻辑挂在 工具、阶段钩子或通道回调上。

生成工程

hmapdev init myluaplugin --lua
cd myluaplugin

结构：

myluaplugin/
├── plg.json    — entry: "main.lua", targets: "lua"
├── main.lua    — 插件实现
├── sdk.lua     — SDK 模拟层（支持独立测试）
└── README.md

一个完整的插件

-- main.lua
local plugin = {
  name = "myluaplugin"
}

function plugin.start(sdk)
  sdk.log("info", "myluaplugin starting...")

  sdk.register_tool("myluaplugin_hello", {
    description = "向指定的人打招呼",
    parameters = {
      type = "object",
      properties = {
        who = { type = "string", description = "要打招呼的对象" }
      },
      required = { "who" }
    }
  }, function(args)
    return { content = "hello, " .. (args.who or "world") .. "!" }
  end)

  sdk.log("info", "myluaplugin started")
end

function plugin.stop()
  sdk.log("info", "myluaplugin stopped")
end

return plugin

本地测试

sdk.lua 是纯 Lua 的 SDK 模拟实现，可以直接用解释器跑：

lua main.lua
# [lua-plugin] info: myluaplugin starting...
# [lua-plugin] register_tool: myluaplugin_hello
# [lua-plugin] info: myluaplugin started

在内核里运行时，sdk.* 由 Go 层注入，sdk.lua 里所有 -- !impl 标记的函数 会被替换成真实实现。

API 约定的两点

• 注册类函数调用即时报错（抛 Lua error）—— 注册失败不会静默。
• 数据类函数统一返回 (result, err)，err 为 nil 表示成功。 核心未装配的子系统（如 SocialAPI）返回空值而非报错。

Lua 侧的 sdk.* 能力与外部 Go 插件对齐至 SDK 1.3.0（需内核 1.4.0+）。

!!! note "历史提醒" 1.1–1.3 期间，媒体 / 注入标志位 / 优先级能力只在 Go 侧有，Lua 侧静默缺失。 现已全量对齐，并由 internal/plugin/lua_surface_test.go 的契约测试守住 「sdk.lua 承诺的每个函数都有运行时绑定」。

构建

hmapdev build          # → dist/myluaplugin_lua.hmap

Lua 插件直接打包源码，不经过编译。

下一步

• 能力边界 —— Lua 与 Go 外部插件的能力面一致
• 打包与发布
• 示例 —— example/luademo 是 Lua 版参考实现