jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-10-03 15:53:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: sync PLUGIN_DEV.md with SDK toolchain updates

Browse Source 
- Fix project structure: remove main.go, add auto-generated bridge files note
- Clarify plg.json (targets) vs plugin.json (entry/platforms) distinction
- Add --bundle multi-platform build section
- Add plugindev sdk version management subcommands
- Update entry point section: NewPlugin is in plugin.go, no separate main.go
- Sync zh and en versions
This commit is contained in:
jianf
2026-07-19 12:32:56 +08:00
parent 22c62e26ff
commit c1d14681bf
2 changed files with 107 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
docs/en/PLUGIN_DEV.md
View File

@ -49,6 +49,21 @@ go build -o plugindev
# Add plugindev to PATH or use directly # Add plugindev to PATH or use directly
``` ```
### SDK Version Management
`plugindev sdk` manages local SDK versions:
```bash
plugindev sdk list # list installed SDK versions
plugindev sdk current # show current SDK version
plugindev sdk latest # show latest available version
plugindev sdk install v0.7.1 # install a specific version
plugindev sdk use v0.7.1 # switch to a version
plugindev sdk path # show current SDK path
```
SDK is stored at `~/.homeagent/plugindev/sdk/<version>/`; `plugindev init` reads the current SDK version for `go.mod`.
### Creating a Go Plugin ### Creating a Go Plugin
```bash ```bash
@ -81,13 +96,15 @@ plugindev build
``` ```
myplugin/ myplugin/
├── plg.json — Plugin metadata (name, version, entry, target platform) ├── plg.json — Plugin metadata (name, version, entry, target platforms)
├── main.go — Entry point (compiled for non-Windows or non-cgo) ├── plugin.go — Plugin implementation (Plugin interface + NewPlugin export)
├── plugin.go — Plugin implementation (Plugin interface)
├── go.mod — Go module definition ├── go.mod — Go module definition
└── README.md — Documentation ├── README.md — Documentation
└── thirdpart/ — Optional external source code directory
``` ```
C ABI bridge files (`z_bridge_gen.go` + `z_entry.c`) are auto-generated at build time.
**Lua plugin**: **Lua plugin**:
``` ```
@ -108,29 +125,45 @@ plugindev build
``` ```
Execution process: Execution process:
1. Reads `plg.json` to determine target platform 1. Reads `plg.json` `targets` field to determine target platforms
2. **Go plugin**: Runs `go build -buildmode=c-shared` (produces `.so` + C ABI header) 2. Auto-generates C ABI bridge code (`z_bridge_gen.go` + `z_entry.c`)
3. **Lua plugin**: Packages source code directly, no compilation needed 3. **Go plugin**: Runs `go build -buildmode=c-shared` (produces `.so` / `.dylib` / `.dll`)
4. Generates `plugin.json` manifest file 4. **Lua plugin**: Packages source code directly, no compilation needed
5. Packages as `.hmap` distribution (zip format, containing `plugin.json` + platform binary) 5. Generates `plugin.json` output manifest
6. Packages as `.hmap` distribution (zip format, containing `plugin.json` + binary)
The `platforms` field in `plugin.json` declares supported platforms; the build includes the corresponding binary: ### plg.json (project config) vs plugin.json (output manifest)
| Platform | Binary name | | File | Purpose | Key fields |
|----------|-------------| |------|---------|------------|
| `plg.json` | Project metadata, maintained by developer | `targets` — build targets (e.g. `"linux/amd64,windows/amd64"`) |
| `plugin.json` | Build artifact manifest, auto-generated | `entry` — entry filename; `platforms` — declared platforms |
Each target produces a separate `.hmap`; binary name by platform:
| Platform | Binary |
|----------|--------|
| Linux | `plugin.so` | | Linux | `plugin.so` |
| macOS | `plugin.dylib` | | macOS | `plugin.dylib` |
| Windows | `plugin.dll` | | Windows | `plugin.dll` |
> Use `--bundle` to build a multi-platform bundle — the resulting `.hmap` contains binaries for all platforms. ### Multi-platform bundle: --bundle
> During installation, the kernel automatically selects the correct binary for the current OS, skipping others.
```bash
plugindev build --bundle
```
Builds linux/amd64 + darwin/amd64 + windows/amd64 in one pass, producing a single `.hmap`
with all platform binaries. The output manifest includes a `platforms` field.
The kernel auto-selects the correct binary during installation.
Output in `dist/` directory: Output in `dist/` directory:
``` ```
dist/ dist/
├── myplugin_linux_amd64.hmap # Go plugin Linux version ├── myplugin_linux_amd64.hmap # Single platform: Linux
├── myplugin_windows_amd64.hmap # Go plugin Windows version ├── myplugin_windows_amd64.hmap # Single platform: Windows
├── myplugin_darwin_amd64.hmap # Go plugin macOS version ├── myplugin_darwin_amd64.hmap # Single platform: macOS
├── myplugin_bundle.hmap # Multi-platform bundle
└── myplugin_lua.hmap # Lua plugin └── myplugin_lua.hmap # Lua plugin
``` ```
@ -197,21 +230,17 @@ func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, e
### Entry Point ### Entry Point
`main.go` provides the `NewPlugin` export function, which is the entry point when the kernel loads the plugin: `plugindev init` generates `plugin.go` with the `NewPlugin` export function directly,
which is the entry point when the kernel loads the plugin:
```go ```go
//go:build !windows || !cgo
package main
import "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) { func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) {
return NewPluginFactory(name, config) return &Plugin{name: name}, nil
} }
``` ```
For `-buildmode=c-shared`, `plugindev build` auto-generates C ABI bridge code (`z_bridge_gen.go` + `z_entry.c`), no manual handling needed. At build time, `plugindev build` auto-generates C ABI bridge code (`z_bridge_gen.go` + `z_entry.c`),
shared by both Windows DLL and Linux/macOS .so builds. No manual bridge code needed.
### PluginSDK Core API ### PluginSDK Core API

78
docs/zh/PLUGIN_DEV.md
View File

@ -50,6 +50,21 @@ go build -o plugindev
# 将 plugindev 加入 PATH 或直接使用 # 将 plugindev 加入 PATH 或直接使用
``` ```
### SDK 版本管理
`plugindev sdk` 子命令管理本地 SDK 版本：
```bash
plugindev sdk list # 列出已安装的 SDK 版本
plugindev sdk current # 显示当前使用的 SDK 版本
plugindev sdk latest # 显示最新可用版本
plugindev sdk install v0.7.1 # 安装指定版本
plugindev sdk use v0.7.1 # 切换使用版本
plugindev sdk path # 显示当前 SDK 路径
```
SDK 存储在 `~/.homeagent/plugindev/sdk/<version>/`，`plugindev init` 自动读取当前 SDK 版本填充 `go.mod`。
### 创建 Go 插件 ### 创建 Go 插件
```bash ```bash
@ -82,13 +97,15 @@ plugindev build
``` ```
myplugin/ myplugin/
├── plg.json — 插件元信息（名称、版本、入口、目标平台） ├── plg.json — 插件元信息（名称、版本、入口、目标平台 targets）
├── main.go — 入口点（非 Windows 或非 cgo 时编译） ├── plugin.go — 插件实现（Plugin 接口 + 导出函数 NewPlugin）
├── plugin.go — 插件实现（Plugin 接口）
├── go.mod — Go 模块定义 ├── go.mod — Go 模块定义
└── README.md — 说明文档 ├── README.md — 说明文档
└── thirdpart/ — 外部源码存放目录（可选）
``` ```
编译时自动生成 C ABI bridge 文件（`z_bridge_gen.go` + `z_entry.c`），无需手动创建。
**Lua 插件**： **Lua 插件**：
``` ```
@ -109,29 +126,44 @@ plugindev build
``` ```
执行过程： 执行过程：
1. 读取 `plg.json` 确定目标平台 1. 读取 `plg.json` 的 `targets` 字段确定目标平台
2. **Go 插件**：执行 `go build -buildmode=c-shared`（生成 `.so` + C ABI header） 2. 自动生成 C ABI bridge 代码（`z_bridge_gen.go` + `z_entry.c`）
3. **Lua 插件**：直接打包源码，无需编译 3. **Go 插件**：执行 `go build -buildmode=c-shared`（生成 `.so` / `.dylib` / `.dll`）
4. 生成 `plugin.json` 清单文件 4. **Lua 插件**：直接打包源码，无需编译
5. 打包为 `.hmap` 分发包（zip 格式，内含 `plugin.json` + 平台二进制） 5. 生成 `plugin.json` 输出清单
6. 打包为 `.hmap` 分发包（zip 格式，内含 `plugin.json` + 二进制）
`plugin.json` 的 `platforms` 字段声明支持的平台，打包时自动包含对应二进制： ### plg.json（项目配置）vs plugin.json（输出清单）
| 平台 | 二进制文件名 | | 文件 | 用途 | 关键字段 |
|------|-------------| |------|------|---------|
| `plg.json` | 项目元信息，由开发者维护 | `targets` — 构建目标（如 `"linux/amd64,windows/amd64"`）|
| `plugin.json` | 构建产物清单，`plugindev build` 自动生成 | `entry` — 入口文件名；`platforms` — 声明的支持平台 |
每个目标生成单独的 `.hmap`，二进制文件名由平台决定：
| 平台 | 二进制 |
|------|--------|
| Linux | `plugin.so` | | Linux | `plugin.so` |
| macOS | `plugin.dylib` | | macOS | `plugin.dylib` |
| Windows | `plugin.dll` | | Windows | `plugin.dll` |
> 使用 `--bundle` 可一次打包多平台，生成的 `.hmap` 内含所有平台的二进制。 ### 多平台打包：--bundle
> 安装时核心自动选择当前平台的文件，跳过其他平台。
```bash
plugindev build --bundle
```
一次编译 linux/amd64 + darwin/amd64 + windows/amd64，生成包含所有平台二进制的单 `.hmap`，
输出清单自动添加 `platforms` 字段。安装时核心自动选择当前平台的二进制，跳过其他平台。
输出在 `dist/` 目录： 输出在 `dist/` 目录：
``` ```
dist/ dist/
├── myplugin_linux_amd64.hmap # Go 插件 Linux 版 ├── myplugin_linux_amd64.hmap # 单平台：Linux 版
├── myplugin_windows_amd64.hmap # Go 插件 Windows 版 ├── myplugin_windows_amd64.hmap # 单平台：Windows 版
├── myplugin_darwin_amd64.hmap # Go 插件 macOS 版 ├── myplugin_darwin_amd64.hmap # 单平台：macOS 版
├── myplugin_bundle.hmap # 多平台合集
└── myplugin_lua.hmap # Lua 插件 └── myplugin_lua.hmap # Lua 插件
``` ```
@ -198,21 +230,15 @@ func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, e
### 入口点 ### 入口点
`main.go` 提供了 `NewPlugin` 导出函数，它是内核加载插件时的入口： `plugindev init` 生成的 `plugin.go` 中直接包含 `NewPlugin` 导出函数，它是内核加载插件时的入口：
```go ```go
//go:build !windows || !cgo
package main
import "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) { func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) {
return NewPluginFactory(name, config) return &Plugin{name: name}, nil
} }
``` ```
对于 `-buildmode=c-shared`，`plugindev build` 自动生成 C ABI bridge 代码（`z_bridge_gen.go` + `z_entry.c`），无需手动处理。 编译时 `plugindev build` 根据目标平台自动生成 C ABI bridge 代码（`z_bridge_gen.go` + `z_entry.c`），无需手动编写。Windows DLL 和 Linux/macOS .so 共享同一入口。
### PluginSDK 核心 API ### PluginSDK 核心 API