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	b6a6168e65	chore(module)!: module 路径随托管地迁移 gitcode → github 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 产物	2026-10-09 07:25:25 +08:00
JianFeeeee	cb7999ca71	feat: sdk NoMemory/Cleaner + example build fixes - sdk/plugin.go: ToolDef adds NoMemory/Cleaner fields - sdk/plugin_test.go: unit tests for NoMemory/Cleaner - all example plugins: NoMemory/Cleaner annotated for each tool - plugindev/templates.go: template shows NoMemory/Cleaner pattern - plugindev/cmd_build.go: fix ensureGoMod, buildBundle/buildTarget sdkPath param, NewPluginFactory - example/go.mod: add external dependency declarations (chromedp, gofeed) - add main.go stubs for all example plugins	2026-07-25 11:17:21 +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

b6a6168e65

chore(module)!: module 路径随托管地迁移 gitcode → github

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 产物

2026-10-09 07:25:25 +08:00

JianFeeeee

cb7999ca71

feat: sdk NoMemory/Cleaner + example build fixes

- sdk/plugin.go: ToolDef adds NoMemory/Cleaner fields
- sdk/plugin_test.go: unit tests for NoMemory/Cleaner
- all example plugins: NoMemory/Cleaner annotated for each tool
- plugindev/templates.go: template shows NoMemory/Cleaner pattern
- plugindev/cmd_build.go: fix ensureGoMod, buildBundle/buildTarget sdkPath param, NewPluginFactory
- example/go.mod: add external dependency declarations (chromedp, gofeed)
- add main.go stubs for all example plugins

2026-07-25 11:17:21 +08:00

3 Commits