mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-15 12:15:11 +00:00
docs+plugindev: README 同步子进程架构,scaffold 修 entry 与 go.sum 死路
三类问题,都会让新用户第一次上手就走错:
1. README 仍写 plugin.so
plugin.json 示例的 entry、entry 字段说明、.hmap 包格式三处描述的都是
已退场的 C ABI 产物。改为 plugin.bin,并补 bundle 模式下
plugin.bin.<goos>.<goarch> 的命名与安装时挑平台的行为。
2. cmd_init.go 的 entry := "plugin.so"
scaffold 出来的 plg.json 带着一个已退场的 entry 值。build 实际不看这个
值(只用它区分 Lua),但跟着模板走会误以为自己在做 C ABI 插件。
3. 生成的项目第一次 build 必定失败
go.mod 只 require 一个 gitcode 模块版本号且不生成 go.sum。gitcode 不在
proxy.golang.org 上,于是:
go build → missing go.sum entry
go mod tidy → 去公共 proxy 拉一个不存在的条目,超时
原来 cmdBuild 里那句 `go mod download <mod>` 走的正是这条死路,失败后
只打一行 warn 就继续编译,紧接着死在同一个错误上——用户看到两段无关报错。
修法分两处:
- 生成的 go.mod 直接写指向本机 SDK 的 replace(replace 到目录时 go 不
需要也不校验 go.sum)
- 新增 ensureSDKResolvable:三级策略(已有本地 replace → 探测本机 SDK
并写入 → 兜底 go mod tidy 带 -mod=mod,失败给可操作提示)。存量项目
go.mod 无 replace 时走第二级救回。
bin/ 5 个预编译二进制不再进仓库(改为 release 附件):
5 个平台各 26-28MB,每次重编都在 git 历史里再叠一份,而它们本质是可从源码
复现的产物。README 的下载说明同步改为 release 附件 URL + 从源码编译。
This commit is contained in:
25
README.md
25
README.md
@ -142,13 +142,21 @@ func New(name string, sett SettingsAPI, regTool ToolRegistrar, regStage StageReg
|
||||
|
||||
## plugindev 工具链
|
||||
|
||||
`plugindev` 提供插件开发全流程支持。仓库 `bin/` 提供各平台预制二进制(linux/darwin/windows × amd64/arm64),下载后直接加入 PATH 即可:
|
||||
`plugindev` 提供插件开发全流程支持。预编译二进制作为 **release 附件**分发(linux/darwin/windows × amd64/arm64),从
|
||||
[Releases](https://gitcode.com/JianFeeeee/homeagent-sdk/releases) 下载后加入 PATH 即可:
|
||||
|
||||
```bash
|
||||
curl -o plugindev https://gitcode.com/JianFeeeee/homeagent-sdk/-/raw/main/bin/plugindev_linux_amd64
|
||||
# 从 release 附件下载(以 v1.0.0 / linux amd64 为例)
|
||||
curl -Lo plugindev https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/v1.0.0/plugindev_linux_amd64
|
||||
chmod +x plugindev
|
||||
|
||||
# 或从源码自己编
|
||||
cd tools/plugindev && go build -o plugindev .
|
||||
```
|
||||
|
||||
> 二进制不再随仓库分发(旧的 `bin/` 目录已停用):5 个平台各 26-28MB,
|
||||
> 每次重编都在 git 历史里再叠一份,而它们本质是可从源码复现的产物。
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `plugindev init <name> [--lua]` | 初始化插件项目(生成 plg.json、plugin.go 或 main.lua、go.mod、README.md) |
|
||||
@ -180,7 +188,7 @@ chmod +x plugindev
|
||||
"version": "1.0.0",
|
||||
"description": "天气查询插件",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
"entry": "plugin.bin",
|
||||
"tags": ["weather", "forecast"],
|
||||
"targets": "linux/amd64,windows/amd64",
|
||||
"outdir": "dist",
|
||||
@ -202,7 +210,7 @@ chmod +x plugindev
|
||||
| `version` | string | 版本号 |
|
||||
| `description` | string | 插件描述 |
|
||||
| `author` | string | 作者 |
|
||||
| `entry` | string | 入口文件(`plugin.so` / `plugin.dll` / `main.lua`) |
|
||||
| `entry` | string | 入口文件(`plugin.bin` / `main.lua`)。v1.0.0 起 Go 插件统一为 `plugin.bin`,不再区分平台后缀 |
|
||||
| `tags` | string[] | 标签 |
|
||||
| `targets` | string | 构建目标,逗号分隔(如 `linux/amd64,windows/amd64`,Lua 插件为 `lua`) |
|
||||
| `outdir` | string | 输出目录(默认 `dist`) |
|
||||
@ -217,11 +225,14 @@ chmod +x plugindev
|
||||
`.hmap` 为 ZIP 归档,包含:
|
||||
|
||||
- `plugin.json` — 插件元数据
|
||||
- `plugin.so` — Go 编译产物(Linux)
|
||||
- `plugin.dll` — Go 编译产物(Windows)
|
||||
- `plugin.dylib` — Go 编译产物(macOS,bundle 模式)
|
||||
- `plugin.bin` — Go 编译产物(单平台构建)
|
||||
- `plugin.bin.<goos>.<goarch>` — 多平台 bundle 模式下每平台一份,
|
||||
安装时 pluginmgr 挑当前平台那份重命名为 `plugin.bin`
|
||||
- `main.lua` — Lua 插件入口(Lua 插件时)
|
||||
|
||||
> v1.0.0 起不再使用 `plugin.so`/`plugin.dll`/`plugin.dylib`——进程边界即 ABI 边界,
|
||||
> 不存在平台特定的动态库区分。旧产物新内核不会加载,会给出明确的重编提示。
|
||||
|
||||
## 插件生命周期
|
||||
|
||||
### 入口函数
|
||||
|
||||
Reference in New Issue
Block a user