|
|
29c61f0e07
|
feat(hmapdev): skill 子命令 —— 插件开发知识随 SDK 分发
## 为什么需要
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 条判据全通过，变异测试确认能抓回归
|
2026-09-28 11:23:58 +08:00 |
|
|
|
83a54f321e
|
fix(hmapdev): 工具链能报出版本（此前 -ldflags -X meta.Version 静默无效）
两个缺口叠加：既没有 `version` 子命令，构建时的
`-ldflags "-X gitcode.com/JianFeeeee/homeagent-sdk/meta.Version=…"` 也因为
**meta 包根本没被工具链引用**而完全不生效（链接器不会保留未被引用的符号，
rodata 里连那个字符串都没有）——于是「手里是哪一版 hmapdev」无从判断，
而插件产物与内核是协议绑定的，这恰恰是最需要判断的一件事（v0.8.0 SDK 陈旧目录
导致模板编译失败那次就是靠猜）。
- main.go 引用 meta 包并新增 `version`（以及 `-v/--version`）子命令，
输出工具链版本 / SDK 模块 / 构建提交 / 构建时间 / 构建用 Go / 可执行文件路径；
- 未注入（源码默认值）时也照常报，unknown 字段不打印（避免噪声）；
- usage 里补上 `hmapdev version`；
- 加测试钉住两件事：注入值必须出现在输出里（-X 一旦失效立刻变红）、
未注入时也要能报出源码默认版本。
验证：`go build` 默认输出 1.3.0（主干默认值）；`-X …meta.Version=1.2.1
-X …meta.Commit=abc1234` 后输出 1.2.1 + 提交号，且二进制内精确匹配到该串
（说明注入真的进了镜像）；`go test -run PrintVersion` 2/2 PASS。
|
2026-09-12 15:08:56 +08:00 |
|
|
|
b237787c90
|
refactor(toolchain)!: 工具链 plugindev 更名为 hmapdev，module path 改回 gitcode
- 目录 tools/plugindev → tools/hmapdev，可执行文件名/平台产物名同步
（hmapdev_linux_amd64 等；包格式仍叫 .hmap）
- module path github.com/JianFeeeee/homeagent-sdk/tools/... → gitcode.com/...
（与仓库实际托管一致；核心仓不依赖该 path，改动无外部影响）
- SDK 存储目录 ~/.homeagent/plugindev/sdk → ~/.homeagent/hmapdev/sdk
新目录不存在而旧目录存在时沿用旧目录 → 已装 SDK 版本不会丢失
- 命令表/usage/--help/生成项目 README/示例 README/NSIS 安装器/
package/build.sh/build-examples.sh 全部同步；PLUGINDEV 环境变量保留兼容
- sdk/ 目录零改动（公开接口不变）
验证：
- go build ./... ok；go test ./tools/hmapdev/ ok（含模板接线守卫 TestProcTemplate_CoversAllCoreMethods）
- bash -n package/{build,build-examples}.sh ok
- 端到端：hmapdev init demo && hmapdev build → dist/demo_bundle.hmap（linux+darwin）
- 本机安装 /usr/local/bin/hmapdev，旧名以软链保留；sdk list/current 正常
|
2026-09-12 12:30:20 +08:00 |
|
