homeagent-sdk

jianf/homeagent-sdk

Fork 0

mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-10-31 14:27:30 +00:00

Commit Graph

Author	SHA1	Message	Date
JianFeeeee	0111ac3a7a	fix(sdk): 协议通道纪律 + hmapdev 模板升级 + 示例插件 stdout 污染 ## 核心缺陷：插件往 stdout 打日志 = 污染 JSON-RPC 协议通道子进程插件与内核用 stdout 传 NDJSON 帧，stderr 才是日志通道。脚手架模板（及 4 个示例插件）用 `fmt.Printf` 打日志 ⇒ 内核收到非 JSON 文本： [proc] weather 收到非法 JSON 帧（21 字节）: invalid character 'i' 生产实测 1038 条（huawei_smarthome 720 / weather 113 / rss 103 / calendar 102）。后果不只是日志噪音：那一行日志被丢弃，插件看起来"没启动"。修法： - hmapdev 模板 `fmt.Printf` → `log.Printf`（9 处） - 示例插件 4 个 14 处：ai_image(2) calendar(5) rss(4) weather(3) + 补 "log" import - 内核侧（主仓）同步让报错可定位：内容摘要 + 可能原因 + 修法判别法：`package main` = 子进程（协议通道，禁用 stdout 打日志）；普通库包 = 进程内插件（编译进内核，写真实终端，不是缺陷）—— `internal/plugins/cli` 的 `fmt.Println` 属后者。 ## hmapdev - `cmd_build.go` +136：平台产物精确匹配（`--target` 是append 语义，原脚本 `ls dist/.hmap \| head -1` 会按字典序抓到 amd64，导致 arm64 包里装的是 x86-64 二进制，且退出码 0、校验和通过） - `cmd_init.go` +46：脚手架 stdio 纪律 - `templates/proc_main.go.tmpl`：补齐 mgrStop/mgrStart/mgrIsRuntimeStopped 三态能力（插件管理器运行态停启） - `templates/plg.json.tmpl` 删除（合并进 cmd_init） ## 判据 - `scaffold_stdout_test.go`（3 条）：扫模板生成的代码不得写 stdout。 ★ 判据自身先假红过一次：模板的注释里就写了 `fmt.Printf`* ⇒ 必须 `stripTemplateComments()` 之后才判 - `example_stdout_test.go`（2 条）：扫全部 20 个子进程示例插件，报错给文件:行号；变异咬住并给出准确行号 - `package_examples_test.go`（2 条）：执行真实打包脚本（第一版测的是 hmapdev 而不是脚本 ⇒ 变异不咬） - `cmd_build` / `cmd_init` 新判据 ## 其他 - sdk/settings.go +15（三态能力透传） - `docs/versions.md` +§示例插件协议通道纪律（含生产 1038 条实测表格） - `skills/homeagent-plugin-dev/SKILL.md` +§协议通道纪律（正误代码对比）	2026-10-17 16:34:29 +08:00
JianFeeeee	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

Author

SHA1

Message

Date

JianFeeeee

0111ac3a7a

fix(sdk): 协议通道纪律 + hmapdev 模板升级 + 示例插件 stdout 污染

## 核心缺陷：插件往 stdout 打日志 = 污染 JSON-RPC 协议通道

子进程插件与内核用 stdout 传 NDJSON 帧，stderr 才是日志通道。
脚手架模板（及 4 个示例插件）用 `fmt.Printf` 打日志 ⇒ 内核收到非 JSON 文本：

    [proc] weather 收到非法 JSON 帧（21 字节）: invalid character 'i'

**生产实测 1038 条**（huawei_smarthome 720 / weather 113 / rss 103 / calendar 102）。
后果不只是日志噪音：那一行日志被**丢弃**，插件看起来"没启动"。

修法：
- hmapdev 模板 `fmt.Printf` → `log.Printf`（9 处）
- 示例插件 4 个 14 处：ai_image(2) calendar(5) rss(4) weather(3)
  + 补 "log" import
- 内核侧（主仓）同步让报错可定位：内容摘要 + 可能原因 + 修法

判别法：`package main` = 子进程（协议通道，禁用 stdout 打日志）；
普通库包 = 进程内插件（编译进内核，写真实终端，**不是**缺陷）——
`internal/plugins/cli` 的 `fmt.Println` 属后者。

## hmapdev

- `cmd_build.go` +136：平台产物精确匹配（`--target` 是**append** 语义，
  原脚本 `ls dist/*.hmap | head -1` 会按字典序抓到 amd64，
  **导致 arm64 包里装的是 x86-64 二进制**，且退出码 0、校验和通过）
- `cmd_init.go` +46：脚手架 stdio 纪律
- `templates/proc_main.go.tmpl`：补齐 mgrStop/mgrStart/mgrIsRuntimeStopped
  三态能力（插件管理器运行态停启）
- `templates/plg.json.tmpl` 删除（合并进 cmd_init）

## 判据

- `scaffold_stdout_test.go`（3 条）：扫模板生成的代码不得写 stdout。
  ★ 判据自身先假红过一次：**模板的注释里就写了 `fmt.Printf`** ⇒
  必须 `stripTemplateComments()` 之后才判
- `example_stdout_test.go`（2 条）：扫全部 20 个子进程示例插件，
  报错给**文件:行号**；变异咬住并给出准确行号
- `package_examples_test.go`（2 条）：**执行真实打包脚本**
  （第一版测的是 hmapdev 而不是脚本 ⇒ 变异不咬）
- `cmd_build` / `cmd_init` 新判据

## 其他

- sdk/settings.go +15（三态能力透传）
- `docs/versions.md` +§示例插件协议通道纪律（含生产 1038 条实测表格）
- `skills/homeagent-plugin-dev/SKILL.md` +§协议通道纪律（正误代码对比）

2026-10-17 16:34:29 +08:00

JianFeeeee

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

2 Commits