feat(hmapdev): 项目声明 SDK 版本，工具链据此自动选（plg.json 的 sdk 字段）

此前项目里没有任何「我要哪版 SDK」的声明：go.mod 的 require 是个 Go 模块版本，
而工具链实际用的是存储里的 current——谁改过 current 就拿谁的版本编，出错时
表现为莫名其妙的编译错误（本轮就踩过：存储里只有陈旧的 v0.8.0，模板项目
首次构建报 undefined: sdk.InjectOptions）。

- `plg.json` 新增 `sdk` 字段：本插件针对的 SDK 版本。`hmapdev init` 生成时写入
  **完整版本号**（如 "1.2.0"）。
- `hmapdev build` 按声明的版本在本地 SDK 存储里定位：命中则用它并把 go.mod 的
  require/replace 同步到该版本；未命中则报**可执行**的错误（列出已装版本 +
  `hmapdev sdk install vX.Y.Z`），绝不静默退化成 current。
- **区间写法（"1.2"）被拒绝**并说明规矩：SDK 版本跟随内核中版本、patch 位恒为 .0，
  一条内核线只有一个 SDK 版本（写区间会让人误以为同一条线里还能挑不同 SDK）。
- 产物 `plugin.json` 记录实际选中的版本（`sdk`），便于追溯「这个 .hmap 是哪版编的」。
- 显式 `--sdk-path` / `plg.json sdk_path` 优先（本机改 SDK 联调的路径），此路径下也尽力记录版本。
- 存量项目（plg.json 无 sdk 字段）行为不变，向后兼容。

顺带修一处自相矛盾：解析出 1.2.0 之外的版本时，原先只改 replace 而 require 保持旧版本，
一旦有人删掉 replace 就会静默用回旧 SDK 编译（`go list -m` 报的也是假版本）。

验证：单测 10 例（精确命中/带 v 前缀目录/区间写法被拒并说明规矩/未命中给可执行命令/
空存储给安装指引/非法值拒绝/杂项目录不干扰）+ 反向验证（把版本比较退化成字典序，
「1.2.x 取最新」用例立刻变红，证明判据能发现缺陷）。
E2E：init → plg.json `"sdk": "1.2.0"`；build → 精确解析、go.mod require/replace 一致、
产物 plugin.json 记录 sdk；声明不存在的版本 → 可执行报错；无 sdk 字段 → 照旧构建。

tools/hmapdev/cmd_build.go

@@ -79,6 +79,22 @@ func cmdBuild(args []string) {
 		return
 	}
 
+	// 项目可在 plg.json 里声明 sdk（中版本或完整版本，如 "1.2" / "1.2.1"）；
+	// 显式 --sdk-path / plg.json 的 sdk_path 优先 —— 那是直指源码目录，
+	// 常用于本机改 SDK 的联调场景。
+	if sdkPath == "" && strings.TrimSpace(plg.SDK) != "" {
+		dir, ver, err := ResolveSDKForProject(plg.SDK)
+		if err != nil {
+			fmt.Printf("error: %v\n", err)
+			os.Exit(1)
+		}
+		sdkPath, plg.ResolvedSDK = dir, ver
+		fmt.Printf("[hmapdev] SDK %s（项目声明 sdk=%s）\n", ver, plg.SDK)
+	} else if sdkPath != "" && plg.ResolvedSDK == "" {
+		// 走的是显式路径：尽力记录它是哪版（读不到就不记，不因此失败）
+		plg.ResolvedSDK = normalizeSDKVersion(readMetaVersion(sdkPath))
+	}
+
 	// Ensure go.mod exists with correct SDK path
 	sdkModule := ensureGoMod(plg, sdkPath)
 
@@ -269,6 +285,10 @@ func writePluginJSON(plg *PlgConfig, platforms []string, entry string) {
 	if len(plg.Tags) > 0 {
 		m["tags"] = plg.Tags
 	}
+	// 记录「用哪版 SDK 编的」：插件产物与内核协议绑定，出问题时这是第一个要看的字段。
+	if plg.ResolvedSDK != "" {
+		m["sdk"] = plg.ResolvedSDK
+	}
 	data, _ := json.MarshalIndent(m, "", "  ")
 	os.WriteFile("plugin.json", data, 0644)
 }
@@ -370,7 +390,28 @@ func ensureGoMod(plg *PlgConfig, sdkPath string) string {
 		}
 		keep = append(keep, line)
 	}
-	if alreadyExists {
+	// 同步 require 版本：replace 指向 1.2.1 而 require 还写 1.2.0 是自相矛盾的
+	// —— 有人删掉 replace 就会静默退回旧版本去编（`go list -m` 报的也是假版本）。
+	// 以本次真正选中的版本为准改写 require 行。
+	requireChanged := false
+	if v := normalizeSDKVersion(plg.ResolvedSDK); v != "" {
+		want := "require " + sdkModule + " v" + v
+		for i, line := range keep {
+			t := strings.TrimSpace(line)
+			if !strings.HasPrefix(t, "require ") {
+				continue
+			}
+			parts := strings.Fields(t)
+			if len(parts) >= 3 && parts[1] == sdkModule {
+				indent := line[:len(line)-len(strings.TrimLeft(line, " \t"))]
+				if t != want {
+					keep[i] = indent + want
+					requireChanged = true
+				}
+			}
+		}
+	}
+	if alreadyExists && !requireChanged {
 		return sdkModule
 	}
 	keep = append(keep, replaceLine, "")

tools/hmapdev/cmd_init.go

@@ -34,6 +34,18 @@ type PlgConfig struct {
 	GoVersion   string            `json:"go_version,omitempty"`
 	Replaces    map[string]string `json:"replaces,omitempty"`
 	SourceDirs  []string          `json:"source_dirs,omitempty"`
+
+	// SDK 声明本插件针对的 SDK **接口版本**（中版本或完整版本，如 "1.2" / "1.2.1"）。
+	//
+	// 为何需要：工具链存储里可能装有多个 SDK 版本，而插件产物与内核是协议绑定的——
+	// 不给声明就只能猜（旧行为是直接用 current：谁改过 current 就拿谁的版本编，
+	// 出错时表现为莫名其妙的编译错误）。写中版本表示「只要 1.2 这条接口线，
+	// 补丁由工具链挑最新」（patch 只含工具链/打包修复，接口不变，见 README 版本语义）。
+	SDK string `json:"sdk,omitempty"`
+
+	// ResolvedSDK 是本次构建实际选中的 SDK 版本（build 按 SDK 声明解析后回填），
+	// 只写进产物里的 plugin.json，便于事后追溯「这个 .hmap 是哪版 SDK 编的」。
+	ResolvedSDK string `json:"-"`
 }
 
 // TargetList parses the Targets string into a slice.
@@ -159,6 +171,9 @@ func cmdInit(args []string) {
 		data.SDKModule = sdkMod
 		data.SDKVersion = "v" + sdkVer
 		data.SDKLocalPath = strings.ReplaceAll(sdkRoot, "\\", "/")
+		// 声明**完整版本号**：SDK 版本跟随内核中版本、patch 位恒为 .0，
+		// 一条内核线只对应一个 SDK 版本（build 时按此解析，见 ResolveSDKForProject）。
+		data.Plg.SDK = normalizeSDKVersion(sdkVer)
 	}
 
 	if err := os.MkdirAll(dir, 0755); err != nil {

tools/hmapdev/sdk_resolve.go

@@ -0,0 +1,135 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// sdkVersionEntry 是本地 SDK 存储里的一个版本。
+//
+// Dir 是存储目录名（历史上有 "v0.8.0" 与 "1.2.0" 两种写法都出现过，所以
+// 目录名与规范化版本号要分开存），Version 是去掉 v 前缀的 x.y.z。
+type sdkVersionEntry struct {
+	Dir     string
+	Version string
+}
+
+// normalizeSDKVersion 去掉常见的前缀写法，得到 x.y.z。
+func normalizeSDKVersion(v string) string {
+	return strings.TrimPrefix(strings.TrimSpace(v), "v")
+}
+
+// parseSDKVersion 解析 x.y.z / x.y（后者补 0）。
+func parseSDKVersion(v string) (maj, min, patch int, ok bool) {
+	v = normalizeSDKVersion(v)
+	parts := strings.Split(v, ".")
+	if len(parts) < 2 || len(parts) > 3 {
+		return 0, 0, 0, false
+	}
+	nums := make([]int, 0, 3)
+	for _, p := range parts {
+		n, err := strconv.Atoi(p)
+		if err != nil || n < 0 {
+			return 0, 0, 0, false
+		}
+		nums = append(nums, n)
+	}
+	for len(nums) < 3 {
+		nums = append(nums, 0)
+	}
+	return nums[0], nums[1], nums[2], true
+}
+
+// compareSDKVersion 比较两个 x.y.z（a<b 返回 -1，相等 0，a>b 返回 1）。
+func compareSDKVersion(a, b string) int {
+	amaj, amin, apat, aok := parseSDKVersion(a)
+	bmaj, bmin, bpat, bok := parseSDKVersion(b)
+	if !aok || !bok {
+		return strings.Compare(normalizeSDKVersion(a), normalizeSDKVersion(b))
+	}
+	for _, d := range [][2]int{{amaj, bmaj}, {amin, bmin}, {apat, bpat}} {
+		switch {
+		case d[0] < d[1]:
+			return -1
+		case d[0] > d[1]:
+			return 1
+		}
+	}
+	return 0
+}
+
+// listInstalledSDKs 列出存储里已安装的 SDK，按版本升序。
+func listInstalledSDKs() []sdkVersionEntry {
+	store := sdkStore()
+	entries, err := os.ReadDir(store)
+	if err != nil {
+		return nil
+	}
+	var out []sdkVersionEntry
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		name := e.Name()
+		if name == "current" || strings.HasPrefix(name, ".") {
+			continue
+		}
+		v := normalizeSDKVersion(name)
+		if _, _, _, ok := parseSDKVersion(v); !ok {
+			continue // 非版本目录（用户放别的东西进去时不误判）
+		}
+		out = append(out, sdkVersionEntry{Dir: name, Version: v})
+	}
+	sort.Slice(out, func(i, j int) bool { return compareSDKVersion(out[i].Version, out[j].Version) < 0 })
+	return out
+}
+
+// ResolveSDKForProject 按项目声明的 SDK 版本（plg.json 的 "sdk" 字段）在本地存储里定位 SDK。
+//
+// 声明必须是**完整版本号**（x.y.z，如 "1.2.0"）：SDK 的版本纪律是「跟随内核中版本，
+// patch 位恒为 .0」（内核的 patch 不碰公开接口 → SDK 不跟版），所以一条内核线
+// 只对应一个 SDK 版本号，写 "1.2" 这种区间写法既不必要、又容易让人以为
+// 「同一条线里还能挑不同 SDK」。工具链直接拒它，顺便把这条规矩说清楚。
+//
+// 找不到时必须报**可执行**的错误：列出已装版本 + 可直接粘贴的安装命令 ——
+// 只说 "not found" 会让人以为是工具链坏了。
+func ResolveSDKForProject(declared string) (dir, version string, err error) {
+	declared = normalizeSDKVersion(declared)
+	if strings.Count(declared, ".") != 2 {
+		return "", "", fmt.Errorf(
+			"plg.json 的 sdk 字段 %q 必须是完整版本号（如 \"1.2.0\"）——\n"+
+				"      SDK 版本跟随内核中版本、patch 位恒为 .0，一条内核线只有一个 SDK 版本", declared)
+	}
+	maj, min, pat, ok := parseSDKVersion(declared)
+	if !ok {
+		return "", "", fmt.Errorf("plg.json 的 sdk 字段 %q 不是合法版本号（写法：\"1.2.0\"）", declared)
+	}
+
+	installed := listInstalledSDKs()
+	for i := range installed {
+		e := installed[i]
+		emaj, emin, epat, _ := parseSDKVersion(e.Version)
+		if emaj == maj && emin == min && epat == pat {
+			return filepath.Join(sdkStore(), e.Dir), e.Version, nil
+		}
+	}
+
+	// 未命中：给出可执行的下一步
+	var have []string
+	for _, e := range installed {
+		have = append(have, e.Version)
+	}
+	avail := "（存储里还没有任何 SDK）"
+	if len(have) > 0 {
+		avail = "已安装：" + strings.Join(have, ", ")
+	}
+	return "", "", fmt.Errorf(
+		"项目声明 sdk=%s，但本地 SDK 存储里没有这个版本；%s\n"+
+			"      安装：hmapdev sdk install v%s\n"+
+			"      查看：hmapdev sdk list",
+		declared, avail, declared)
+}

tools/hmapdev/sdk_resolve_test.go

@@ -0,0 +1,103 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// withSDKStore 把 SDK 存储指到临时目录（sdkStore 读 HOME），并造出给定版本目录。
+func withSDKStore(t *testing.T, versions ...string) {
+	t.Helper()
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	store := filepath.Join(home, ".homeagent", sdkDirName)
+	if err := os.MkdirAll(store, 0755); err != nil {
+		t.Fatal(err)
+	}
+	for _, v := range versions {
+		if err := os.MkdirAll(filepath.Join(store, v), 0755); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+// 项目声明中版本 → 挑该接口线里最新的补丁；声明完整版本 → 精确命中。
+//
+// 为什么允许中版本是关键判据：patch 位只含工具链/打包修复（接口不变），
+// 让项目声明 "1.2" 而不是死钉 "1.2.0"，才能既跟得上工具链修复又不跨接口线。
+func TestResolveSDKForProject(t *testing.T) {
+	t.Run("区间写法（1.2）被拒并说明版本纪律", func(t *testing.T) {
+		// 判据：SDK 的 patch 位恒为 .0 → 一条内核线只有一个 SDK 版本，
+		// 区间写法会让人误以为「同一条线里还能挑版本」，所以直接拒。
+		withSDKStore(t, "1.2.0")
+		_, _, err := ResolveSDKForProject("1.2")
+		if err == nil {
+			t.Fatal("1.2 这种区间写法应被拒绝")
+		}
+		for _, want := range []string{"完整版本号", "patch 位恒为 .0"} {
+			if !strings.Contains(err.Error(), want) {
+				t.Fatalf("拒绝理由里应说清规矩（缺少 %q）: %v", want, err)
+			}
+		}
+	})
+
+	t.Run("完整版本精确命中", func(t *testing.T) {
+		withSDKStore(t, "1.2.0", "1.3.0")
+		_, ver, err := ResolveSDKForProject("1.2.0")
+		if err != nil || ver != "1.2.0" {
+			t.Fatalf("精确命中失败: ver=%s err=%v", ver, err)
+		}
+	})
+
+	t.Run("存储目录带 v 前缀也能命中", func(t *testing.T) {
+		withSDKStore(t, "v1.2.0")
+		dir, ver, err := ResolveSDKForProject("1.2.0")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if ver != "1.2.0" || !strings.HasSuffix(dir, "v1.2.0") {
+			t.Fatalf("带 v 前缀的目录名未被识别: dir=%s ver=%s", dir, ver)
+		}
+	})
+
+	t.Run("未命中要给出可执行命令与已装清单", func(t *testing.T) {
+		withSDKStore(t, "1.2.0")
+		_, _, err := ResolveSDKForProject("2.0.0")
+		if err == nil {
+			t.Fatal("应报错")
+		}
+		msg := err.Error()
+		for _, want := range []string{"sdk=2.0.0", "hmapdev sdk install", "hmapdev sdk list", "1.2.0"} {
+			if !strings.Contains(msg, want) {
+				t.Fatalf("错误信息缺少 %q（要可执行，不能只说 not found）:\n%s", want, msg)
+			}
+		}
+	})
+
+	t.Run("空存储也能给出安装指引", func(t *testing.T) {
+		withSDKStore(t)
+		_, _, err := ResolveSDKForProject("1.2.0")
+		if err == nil || !strings.Contains(err.Error(), "hmapdev sdk install v1.2.0") {
+			t.Fatalf("空存储时应提示装哪个版本: %v", err)
+		}
+	})
+
+	t.Run("非法声明直接拒绝", func(t *testing.T) {
+		withSDKStore(t, "1.2.0")
+		for _, bad := range []string{"abc", "1", "1.2", "1.2.3.4", "-1.2.0"} {
+			if _, _, err := ResolveSDKForProject(bad); err == nil {
+				t.Fatalf("非法版本 %q 应被拒绝（宁可报错也不许当通配符）", bad)
+			}
+		}
+	})
+
+	t.Run("非版本目录不参与匹配", func(t *testing.T) {
+		withSDKStore(t, "1.2.0", "backup-old", ".hidden", "current")
+		_, ver, err := ResolveSDKForProject("1.2.0")
+		if err != nil || ver != "1.2.0" {
+			t.Fatalf("杂项目录不应干扰: ver=%s err=%v", ver, err)
+		}
+	})
+}

tools/hmapdev/templates.go

@@ -9,6 +9,7 @@ const tmplPlgJSON = `{
   "description": "{{.Plg.Description}}",
   "author": "{{.Plg.Author}}",
   "entry": "{{.Plg.Entry}}",
+  "sdk": "{{.Plg.SDK}}",
   "tags": [{{range $i, $t := .Plg.Tags}}{{if $i}}, {{end}}"{{$t}}"{{end}}],
   "targets": "{{.Plg.Targets}}"
 }