mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-15 12:15:11 +00:00
b6a6168e65
SDK 仓已迁到 GitHub 作为权威源，go module 路径同步： `gitcode.com/JianFeeeee/homeagent-sdk` → `github.com/JianFeeeee/homeagentsdk` ## 范围 74 个文件：71 个 Go 源码 + go.mod/go.sum + hmapdev 模板 + CI 与打包脚本。 主仓（HomeAgent）侧对应改动是 6d38a164。本仓这些文件当时**不在工作树上** （见下），所以那次的批量替换扫不到它们——这里是补偿。 ## 为何这批文件当时不在工作树上（事故与恢复） 10-08 07:58 主仓做 checkout/cherry-pick 序列时，把本仓工作树的 20 个文件 误清理了（`example/*/plugin.go` + `plg.json`，10 个示例）。 根因是**结构误判**：本仓是「一目录两仓库」结构下主仓 `third_party/` 里的 **独立 git 仓库**，而主仓 .gitignore 忽略了 `example/`，于是它在主仓 `git status` 里不可见 —— 看着像「不受跟踪的构建产物」，实际是本仓受跟踪的源码。 已全部恢复（`git checkout -- <D 文件>`，只恢复删除、不动迁移改动）， 20 个文件与 HEAD 逐字节一致。 **破坏的连锁后果**：恢复出来的 `plugin.go` 仍写着旧 module 路径， 因为迁移时它们已不在工作树上。所以这次补偿是必须的，不是可选优化。 ## 保留 gitcode 引用 以下位置的 `gitcode` **有意保留**，不要"顺手清掉"： - README.md / docs 里「二进制实际分发地址目前是 gitcode」的说明 - mkdocs.yml 的 gitcode 镜像链接（国内直连更快） - `tools/hmapdev/templates.go` 里「SDK 已从 gitcode 迁到 GitHub」的注释 gitcode 仍是**只读镜像**（源码同步；release 附件暂时仍在那边）。 ## 验证 - 本仓根 module：`go build ./...` + `go test ./...` 全通过 - 全部 20 个 example：`go vet` 通过（补偿前 10 个因旧 module 路径失败） - example/qq：`go test` 通过，且能从源码 build 出可用 plugin 产物
plugindev — 插件开发工具链（Agent 可调用）
把 SDK 的 hmapdev 封装成插件，让 Agent 自己走完「新建插件 → 构建 → 安装」全流程，
不需要人来敲命令行：
plugindev_init 生成工程骨架（等价 hmapdev init <name> [--lua]）
↓ 改 plugin.go
plugindev_build 构建打包（等价在该目录 hmapdev build）→ dist/*.hmap
↓
plugin_install 安装（用 path 指向刚构建出的 .hmap，overwrite=true 表示原地更新）
↓
plgreload 重载生效
工具
| 工具 | 参数 | 说明 |
|---|---|---|
plugindev_status |
— | hmapdev 是否可用/版本/当前 SDK 版本与路径/工作区；排查"为什么不能构建"先用它 |
plugindev_init |
name、lang(go/lua)、dir |
生成工程骨架；插件名必须 [a-zA-Z0-9_-]{1,64} |
plugindev_build |
dir、target |
在工程目录构建打包；产物路径会在返回里给出 |
plugindev_sdk |
action、version、from |
SDK 版本管理（list/current/path/latest/install/use）；from 可指向本地 SDK 源码 |
plugindev_projects |
— | 列出工作区里已有工程与产物 |
配置
| 键 | 默认 | 说明 |
|---|---|---|
hmapdev_path |
自动查找 | 依次尝试：本配置项 → PATH → /usr/local/bin/hmapdev → /root/go/bin/hmapdev |
workspace_dir |
<data_dir>/plugindev |
plugindev_init 生成工程的默认目录 |
build_timeout_sec |
600 | 单次 hmapdev 调用超时 |
前置：装 hmapdev
cd <sdk-repo>/tools/hmapdev && go build -buildvcs=false -o /usr/local/bin/hmapdev .
hmapdev version
安全边界（都在实现里，不只写在文档里）
- 只 exec hmapdev 一个可执行文件，不接受任意命令、不做 shell 拼接；
plugindev_build只接受含plg.json的目录（"看起来是插件工程"才构建）， 避免把这个工具变成对任意目录跑构建；- 子进程全部带超时，输出截断后才返回（构建日志动辄几百 KB，直接回灌会撑爆模型上下文）；
- 工程名约束与内核/上游对"进工具名的标识符"的规则一致（
[a-zA-Z0-9_-]{1,64}）。