mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-30 06:13:14 +00:00
29c61f0e07
## 为什么需要
HomeAgent 插件开发的知识（hmapdev 工具链、SDK 版本坑、plg.json、
plugin.bin 部署、内置 vs 独立二进制）此前只存在于**某个 agent 的对话历史**里。
本机四个 agent（pi / claude / codex / .agents）都不会开发插件，
因为它们**没有任何渠道**拿到这些知识。
知识属于 SDK（与工具链同源、随 SDK 版本走），所以：
- 源：`skills/`（随 SDK 仓分发）
- 装：`hmapdev skill install`
## 命令
hmapdev skill list 列出活跃 SDK 里的 skills
hmapdev skill install [name...] 装到各 agent 的 skills 目录
hmapdev skill path 显示源目录与来源
安装目标（**只装这些**，不认识的目录不创建）：
~/.pi/agent/skills ~/.claude/skills
~/.codex/skills ~/.agents/skills
## 两条策略，与别处**故意相反**
1. **总是覆盖**。skill 是**工具生成物**，不是用户数据。保留用户改过的版本
会让它与工具链脱节 —— 而工具链的命令面会随版本变。
（对比：`hmapdev build` 写出的适配器更新会**保护**用户修改，
因为那是运行时代码；skill 只是说明文档。）
2. **不扫 glob 自动发现**。不认识的目录建出来也没用，
还会让用户以为装上了。
## 源目录：仓库优先，store 回退
store（`~/.homeagent/hmapdev/sdk/<v>/`）是 `sdk install` 复制的**副本**。
而 skill 是纯文档、加它不需要动 SDK 的编译产物 ——
「改了 skill 却要重装 SDK 才能生效」对日常维护不合理。
故优先用 hmapdev **自身所在仓库**的 `skills/`（靠可执行文件位置反推，
并校验 go.mod 的 module 是 homeagent-sdk），落空才回退 store。
## 判据 9 条（cmd_skill_test.go）
覆盖：目标无重复/不逃出 home、**真实仓库**里 skills/ 的布局合规、
隐藏目录与普通文件不算 skill、幂等、覆盖用户修改、跳过未知目标、
真实入口 `cmdSkillInstall` 覆盖用户修改、未知 skill 名不静默。
### 写判据时踩的三个坑
1. **`TestSkillSourceHasValidLayout` 原用 `t.TempDir()`** ⇒ 那个目录是空的，
判据永远红，且红得毫无意义（"文件不存在"是真的，但真实文件在 SDK 仓里）。
改为指向**真实仓库**。
2. **fixture 造错**：我 `MkdirAll` 出一个叫 `README.md` 的**目录**，
于是实现"正确地"把它当 skill，判据却报「把 README.md 当成了 skill」。
是 fixture 错，不是实现错。
3. ★ **`TestSkillInstallOverwritesUserEdit` 只验 `copyDir`、没走真实入口**
⇒ 我把 `cmdSkillInstall` 里的 copyDir 换成「已存在就跳过」，
**判据依然全绿**。变异测试抓出来的。补 `TestCmdSkillInstallOverwritesUserEdit`
走真实入口后，变异立刻变红。
## 实测
删掉三处 skill 后 `hmapdev skill install` 一条命令装回四处，
四处 md5 与源一致，二次安装结果不变（幂等）。
## 门禁
- `go test ./...`（hmapdev 独立 module）：ok，0 FAIL
- `go build ./...`：ok
- 9 条判据全通过，变异测试确认能抓回归
84 lines
2.4 KiB
Go
84 lines
2.4 KiB
Go
package main
|
||
|
||
import (
|
||
"fmt"
|
||
"io"
|
||
"os"
|
||
"runtime"
|
||
|
||
"gitcode.com/JianFeeeee/homeagent-sdk/meta"
|
||
)
|
||
|
||
func main() {
|
||
if len(os.Args) < 2 {
|
||
help()
|
||
return
|
||
}
|
||
switch os.Args[1] {
|
||
case "init":
|
||
cmdInit(os.Args[2:])
|
||
case "build":
|
||
cmdBuild(os.Args[2:])
|
||
case "clean":
|
||
cmdClean(os.Args[2:])
|
||
case "debug":
|
||
cmdDebug(os.Args[2:])
|
||
case "sdk":
|
||
cmdSDK(os.Args[2:])
|
||
case "skill":
|
||
cmdSkill(os.Args[2:])
|
||
case "version", "-v", "--version":
|
||
printVersion()
|
||
default:
|
||
help()
|
||
}
|
||
}
|
||
|
||
// printVersion 输出工具链自身的版本身份。
|
||
//
|
||
// 为何必须有：此前工具链不报版本，而插件产物与内核是**协议绑定**的——
|
||
// 手里是哪一版工具链、能不能配当前内核，只能靠翻文件名或猜。
|
||
// 版本号来自 meta.Version（与 SDK 发布同源，由 -ldflags -X 注入）；
|
||
// lnflags 未注入时它是源码里的默认值，此时提示它可能是开发构建。
|
||
func printVersion() {
|
||
printVersionTo(os.Stdout)
|
||
}
|
||
|
||
// printVersionTo 把版本身份写到 w（抽出来是为了能被测试钉住）。
|
||
func printVersionTo(w io.Writer) {
|
||
fmt.Fprintf(w, "hmapdev %s\n", meta.Version)
|
||
fmt.Fprintf(w, " SDK 模块: %s\n", "gitcode.com/JianFeeeee/homeagent-sdk")
|
||
if meta.Commit != "" && meta.Commit != "unknown" {
|
||
fmt.Fprintf(w, " 构建提交: %s\n", meta.Commit)
|
||
}
|
||
if meta.BuildTime != "" && meta.BuildTime != "unknown" {
|
||
fmt.Fprintf(w, " 构建时间: %s\n", meta.BuildTime)
|
||
}
|
||
fmt.Fprintf(w, " 构建用 Go: %s\n", runtime.Version())
|
||
fmt.Fprintf(w, " 可执行文件: %s\n", os.Args[0])
|
||
}
|
||
|
||
func help() {
|
||
fmt.Print(`HomeAgent Plugin Dev Tool
|
||
|
||
Usage:
|
||
hmapdev version Print toolchain version
|
||
hmapdev init <name> Scaffold a new plugin project
|
||
hmapdev init <name> --lua Create Lua plugin
|
||
hmapdev init <name> --type remotedevice
|
||
Create C remote device adapter
|
||
hmapdev build [flags] Compile and package plugin
|
||
hmapdev clean Clean build/dist artifacts
|
||
hmapdev debug [dir] Interpret and debug plugin source
|
||
hmapdev sdk <command> Manage SDK versions
|
||
hmapdev skill <command> Install plugin-dev skills into agent skill dirs
|
||
|
||
Flags:
|
||
--outdir Output directory (default: dist)
|
||
--target Target OS/arch (e.g. linux/amd64), repeatable
|
||
--lua Create Lua plugin (for init)
|
||
--type Project type: "remotedevice" (for init)
|
||
-t Alias for --type
|
||
`)
|
||
}
|