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` +§协议通道纪律(正误代码对比)
This commit is contained in:
JianFeeeee
2026-10-17 16:34:29 +08:00
parent c2474f57a2
commit 0111ac3a7a
36 changed files with 5059 additions and 227 deletions

View File

@ -0,0 +1,126 @@
package main
// 示例插件的**协议通道纪律**判据(2026-10-16)。
//
// ## 为什么必须有这条
//
// 示例插件是**子进程插件**(`package main` + `plugin.bin`),它们的
// **stdout 是 JSON-RPC 协议通道**。用 `fmt.Printf` 打日志 ⇒ 裸文本进入
// 协议流 ⇒ 内核报「收到非法 JSON 帧」并丢弃该日志。
//
// ## 这是**生产环境正在发生**的缺陷(不是理论问题)
//
// 实测 `journalctl -u homeagent`:**1038 条**非法帧报错,来源:
//
// huawei_smarthome 720 / weather 113 / rss 103 / calendar 102
//
// weather / rss / calendar 正是本仓示例插件 ⇒ 已全部修为 log.Printf。
//(huawei_smarthome 是第三方插件,源码不在本仓 —— 内核侧的可定位报错
// 就是为它那类情况准备的。)
//
// ## 判据形态:源码扫描(这里是**恰当**的)
//
// 每个示例插件是**独立 Go module**(21 个 go.mod),无法在一个测试进程里
// 全部编译 ⇒ 只能扫源码。断言的是"某个模式是否出现",属于
// "符号/模式存在性"那一类(对比:断言接线/顺序时源码扫描会骗人)。
//
// ★ 必须**先剥注释**:示例插件里可能**刻意**提到 fmt.Printf 来讲这个坑。
import (
"os"
"path/filepath"
"strings"
"testing"
)
// ★★★ 判据:所有子进程示例插件**不得**往 stdout 打印。
func TestExamplePluginsDoNotWriteStdout(t *testing.T) {
exDir := filepath.Join("..", "..", "example")
entries, err := os.ReadDir(exDir)
if err != nil {
t.Skipf("读不到 example 目录: %v", err)
}
checked := 0
for _, e := range entries {
if !e.IsDir() {
continue
}
name := e.Name()
// 只查**子进程**插件(有 plugin.go 且以 package main 开头)
var files []string
fis, err := os.ReadDir(filepath.Join(exDir, name))
if err != nil {
continue
}
for _, fi := range fis {
if fi.IsDir() || !strings.HasSuffix(fi.Name(), ".go") ||
strings.HasSuffix(fi.Name(), "_test.go") {
continue
}
files = append(files, filepath.Join(exDir, name, fi.Name()))
}
isSubprocess := false
for _, f := range files {
b, _ := os.ReadFile(f)
if strings.HasPrefix(string(b), "package main") {
isSubprocess = true
break
}
}
if !isSubprocess {
continue
}
for _, f := range files {
b, err := os.ReadFile(f)
if err != nil {
continue
}
code := stripTemplateComments(string(b))
for _, pat := range []string{"fmt.Printf(", "fmt.Println(", "fmt.Print(", "os.Stdout"} {
if !strings.Contains(code, pat) {
continue
}
// 找出具体行号(便于修)
for i, ln := range strings.Split(code, "\n") {
if strings.Contains(ln, pat) {
t.Errorf("★ %s:%d 含 `%s` —— 子进程插件的 **stdout 是 "+
"JSON-RPC 协议通道**,内核会报「收到非法 JSON 帧」并"+
"丢弃该日志。\n 修法:改成 log.Printf(默认 stderr)。\n 行: %s",
filepath.Join(name, filepath.Base(f)), i+1, pat, strings.TrimSpace(ln))
}
}
}
}
checked++
}
if checked == 0 {
t.Fatal("没找到任何子进程示例插件 —— 判据会永远绿(请检查目录名/结构)")
}
t.Logf("检查了 %d 个子进程示例插件", checked)
}
// ★★★ 判据:**反向钉住** —— 必须有示例插件真的在用 log.Printf。
//
// ★ 为什么需要:上面那条可以靠"把所有日志删光"通过,但那样示例就
//
// 失去了"示范正确做法"的意义。这条确保至少有几个插件在用 log.Printf。
func TestExamplePluginsUseStderrLogging(t *testing.T) {
exDir := filepath.Join("..", "..", "example")
want := []string{"weather", "rss", "calendar"}
for _, name := range want {
p := filepath.Join(exDir, name, "plugin.go")
b, err := os.ReadFile(p)
if err != nil {
t.Errorf("读 %s: %v", p, err)
continue
}
src := string(b)
if !strings.Contains(src, "log.Printf") {
t.Errorf("★ %s 没有用 log.Printf —— 它原先用 fmt.Printf 写 stdout,"+
"实测生产环境累计 113/103/102 条非法帧报错。", name)
}
if !strings.Contains(src, `"log"`) {
t.Errorf("★ %s 用了 log.Printf 但没 import \"log\"", name)
}
}
}