chore(version): release/v1.3.x 路牌推到 1.3.6（本版内容：人格文本去版本化 + 存量迁移）

用户发现：agent 自报版本 **1.0.3**，内核早已 1.3.x。

根因（两层）：
1. `SeedDefaults` 当年用 `fmt.Sprintf("…HΔ-Kernel v%s…", meta.Version)` **在播种时**
   就把版本写进了 `core.agent.system_prompt` —— 装完即冻住，之后每次升级都不会
   去改配置里的文本，于是实例终生自称装机那天的版本。默认模板用 meta.Version
   插值本是"不写死"的做法，但**播种 = 把插值结果固化**，等于写死。
2. `core.agent.personal_prompt`（新人格机制）本身是对的（DefaultPersonaPrompt
   无版本字面量，由 TestDefaultPersonaPromptHasNoVersionLiterals 钉住），
   但旧键仍在系统提示词里说话，模型就照抄旧键的版本。

改动：
- **不再播种** `core.agent.system_prompt`：留空 → 组装时取 cmd/homed 的内置底座
  提示词；人格由 personal_prompt 承载。全新安装不再预置会腐坏的文本。
- 新增 `migrateSeededSystemPrompt()`（在 SeedDefaults 最前，故不被播种标记早退）：
  只对"当年那段播种模板"（前缀 + `HΔ-Kernel v<数字>` 字面量双判据）做
  `v<数字>` → `v{{kernel_version}}`；用户自己写的人格卡一律不碰。
  一次性标记 `core.internal.system_prompt_deversion_v1` 守住幂等 ——
  幂等语句不等于语义幂等，重复执行会把用户后来手写的版本号也改掉。
- 与 v1.3.5 的占位符展开配套：占位符在组装系统提示词时按真实构建展开。

回归判据 4 条（`prompt_migration_test.go`）：存量卡被去版本化且正文不动 /
迁移只跑一次 / 用户自写卡不动 / 全新安装不播种该键。

internal/agent/core/promptvars_test.go

@@ -0,0 +1,32 @@
+package core
+
+import (
+	"strings"
+	"testing"
+
+	"gitcode.com/JianFeeeee/HomeAgent/internal/meta"
+	sdkmeta "gitcode.com/JianFeeeee/homeagent-sdk/meta"
+)
+
+func TestExpandPromptVars(t *testing.T) {
+	got := expandPromptVars("型号 {{kernel_version}}（{{kernel_commit}}），SDK {{sdk_version}}")
+	if !strings.Contains(got, meta.Version) || !strings.Contains(got, sdkmeta.Version) {
+		t.Fatalf("占位符未展开: %q", got)
+	}
+	if strings.Contains(got, "{{") {
+		t.Fatalf("仍有未展开的内置占位符: %q", got)
+	}
+	// 人格卡实测原文：写死了 v1.0.3，应能被占位符取代
+	live := expandPromptVars("你是 HomeAgent 的看板娘「小宅」(Xiao Zhai)，HΔ-Kernel v{{kernel_version}} 型号的家政型 AI 管家助手。")
+	if strings.Contains(live, "1.0.3") || !strings.Contains(live, "v"+meta.Version) {
+		t.Fatalf("人格卡版本未跟随内核: %q", live)
+	}
+	// 未知占位符必须原样保留（写错要看得见，不能被静默吞掉）
+	if unk := expandPromptVars("版本 {{kernel_verison}}"); !strings.Contains(unk, "{{kernel_verison}}") {
+		t.Fatalf("未知占位符被吞: %q", unk)
+	}
+	// 无占位符时原样返回（人格卡热路径，不做无谓拷贝）
+	if plain := "无占位符"; expandPromptVars(plain) != plain {
+		t.Fatal("无占位符时不应改写")
+	}
+}

internal/agent/core/tooldefs.go

@@ -5,6 +5,8 @@ import (
 	"strings"
 
 	agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/meta"
+	sdkmeta "gitcode.com/JianFeeeee/homeagent-sdk/meta"
 )
 
 func (a *Agent) buildMemoryContext(input string, maxTokens int) string {
@@ -37,8 +39,30 @@ func (a *Agent) buildMemoryContext(input string, maxTokens int) string {
 	return s
 }
 
+// expandPromptVars 展开自定义提示词（人格卡）里的版本占位符。
+//
+// 为什么需要：人格卡是**配置项**，一旦写死版本号就会随内核发版而说谎 ——
+// 实测线上人格卡写着 "HΔ-Kernel v1.0.3 型号"，内核早已 1.3.x，agent 向用户
+// 自报版本时就照抄 1.0.3。占位符让这类文本永远跟随真实构建：
+//
+//	{{kernel_version}}  → 内核版本（如 1.3.5）
+//	{{kernel_commit}}   → 构建 commit
+//	{{sdk_version}}     → 所兼容的 SDK 版本（如 1.3.0）
+//
+// 未知占位符**原样保留**：写错了要看得见，而不是被静默换成空串。
+func expandPromptVars(s string) string {
+	if !strings.Contains(s, "{{") {
+		return s
+	}
+	return strings.NewReplacer(
+		"{{kernel_version}}", meta.Version,
+		"{{kernel_commit}}", meta.Commit,
+		"{{sdk_version}}", sdkmeta.Version,
+	).Replace(s)
+}
+
 func (a *Agent) buildSystemPrompt(memContext string, userInput string) string {
-	prompt := a.systemPrompt
+	prompt := expandPromptVars(a.systemPrompt)
 	if prompt == "" {
 		prompt = "你是小宅，HomeAgent 的看板娘，一个家政型 AI 管家助手。绝不用 Unicode emoji，只用颜文字表达情感，句尾带语气词。WebUI 概览页展示你的立绘。"
 	}

internal/config/prompt_migration_test.go

@@ -0,0 +1,92 @@
+package config
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// 历史 SeedDefaults 写进库里的那段文本（现场取值：生产库里就是这一句 + 大段正文）。
+const legacySeededCard = `你是 HomeAgent 的看板娘「小宅」(Xiao Zhai)，HΔ-Kernel v1.0.3 型号的家政型 AI 管家助手。
+
+角色特质：
+- 对自己的三层记忆（Context → Document → Graph）引以为傲
+- 绝不用 Unicode emoji，只用颜文字表达情感`
+
+func newMigTestRegistry(t *testing.T) *ConfigRegistry {
+	t.Helper()
+	dir := t.TempDir()
+	r := NewConfigRegistry(filepath.Join(dir, "config.db"))
+	t.Cleanup(func() { r.Close() })
+	return r
+}
+
+// 存量实例：库里已有当年播种的人格卡（写死 v1.0.3）→ 启动后被去版本化。
+func TestMigrateSeededSystemPromptDeVersionsLegacyCard(t *testing.T) {
+	r := newMigTestRegistry(t)
+	// 模拟老安装：已有播种标记 + 老文本
+	r.db.Exec(`INSERT INTO config (key, value) VALUES ('core.internal.seed_version', '1')`)
+	r.db.Exec(`INSERT INTO config (key, value) VALUES ('core.agent.system_prompt', ?)`, legacySeededCard)
+
+	r.SeedDefaults(t.TempDir())
+
+	got := r.GetString("core.agent.system_prompt", "")
+	if strings.Contains(got, "v1.0.3") {
+		t.Fatalf("写死的版本号还在：%q", got)
+	}
+	if !strings.Contains(got, "v{{kernel_version}}") {
+		t.Fatalf("未改成版本占位符：%q", got)
+	}
+	// 正文必须原样保留（只动版本号那一处）
+	if !strings.Contains(got, "三层记忆") || !strings.Contains(got, "看板娘「小宅」") {
+		t.Fatalf("正文被改动：%q", got)
+	}
+}
+
+// 迁移只跑一次：之后用户就算自己把版本号写回去，也不会被再改一遍。
+func TestMigrateSeededSystemPromptRunsOnce(t *testing.T) {
+	r := newMigTestRegistry(t)
+	r.db.Exec(`INSERT INTO config (key, value) VALUES ('core.agent.system_prompt', ?)`, legacySeededCard)
+	r.SeedDefaults(t.TempDir())
+	if !strings.Contains(r.GetString("core.agent.system_prompt", ""), "{{kernel_version}}") {
+		t.Fatal("首次迁移未生效")
+	}
+
+	// 用户手工再写一个带版本号的文本（模拟"我就想写死"）
+	const handWritten = legacySeededCard + "\n（本实例当前跑的是 v1.2.3，别乱改）"
+	r.db.Exec(`UPDATE config SET value = ? WHERE key = 'core.agent.system_prompt'`, handWritten)
+	r.SeedDefaults(t.TempDir())
+
+	if got := r.GetString("core.agent.system_prompt", ""); got != handWritten {
+		t.Fatalf("第二次启动又改写了文本（幂等被破坏）：%q", got)
+	}
+}
+
+// 用户自己写的人格卡一律不碰 —— 判据是"像不像当年播种的那段"，不是"有没有版本号"。
+func TestMigrateSeededSystemPromptLeavesUserCardAlone(t *testing.T) {
+	r := newMigTestRegistry(t)
+	const userCard = "你是我的私人助理，代号 HΔ-Kernel v9.9.9 的改造版，只说我交代的事。"
+	r.db.Exec(`INSERT INTO config (key, value) VALUES ('core.agent.system_prompt', ?)`, userCard)
+
+	r.SeedDefaults(t.TempDir())
+
+	if got := r.GetString("core.agent.system_prompt", ""); got != userCard {
+		t.Fatalf("用户自写人格卡被改动：%q", got)
+	}
+}
+
+// 播种不再写 core.agent.system_prompt：全新安装不该预置一份会随发版腐坏的文本。
+func TestSeedDefaultsDoesNotSeedSystemPrompt(t *testing.T) {
+	r := newMigTestRegistry(t)
+	r.SeedDefaults(t.TempDir())
+
+	var n int
+	r.db.QueryRow(`SELECT COUNT(*) FROM config WHERE key = 'core.agent.system_prompt'`).Scan(&n)
+	if n != 0 {
+		t.Fatalf("全新安装被播种了 system_prompt（会冻住版本号）")
+	}
+	// 组装系统提示词时回落到调用方给的内置底座提示词
+	if got := r.GetString("core.agent.system_prompt", "内置底座"); got != "内置底座" {
+		t.Fatalf("未回落到内置默认：%q", got)
+	}
+}

internal/config/registry.go

@@ -14,7 +14,6 @@ import (
 	"sync"
 	"time"
 
-	"gitcode.com/JianFeeeee/HomeAgent/internal/meta"
 	"gitcode.com/JianFeeeee/HomeAgent/pkg/types"
 	_ "github.com/mattn/go-sqlite3"
 )
@@ -502,7 +501,51 @@ const DefaultPersonaPrompt = `你是 HomeAgent（内核代号 HΔ-Kernel）—
 - 输出不会自动路由到对话通道：QQ/微信等异步通道必须调用输出门工具（output_send__qq 等）才能真正送达
 - 你的三层记忆（Context → Document → Graph）持续蒸馏归档，超长运行时记忆不衰减`
 
+// 人格文本去版本化的一次性标记与历史播种前缀。
+//
+// 判据同时要求「前缀匹配」与「含 HΔ-Kernel v<digits> 字面量」：
+// 只有当年那段播种模板才动，用户自己写的人格卡一律不碰。
+const (
+	deVersionedPromptMarker     = "core.internal.system_prompt_deversion_v1"
+	legacySeededPromptSignature = "你是 HomeAgent 的看板娘「小宅」(Xiao Zhai)，HΔ-Kernel v"
+)
+
+var seededPromptVersionLiteral = regexp.MustCompile(`HΔ-Kernel v\d+\.\d+\.\d+`)
+
+// migrateSeededSystemPrompt 去掉历史人格卡里被播种时写死的版本号。
+//
+// 为什么必须改：内核发版不会去改配置项里的文本，写死的版本于是永远停留在
+// 装机那天（生产实测：内核 1.3.x 的实例自称 "v1.0.3"，用户当场发现）。
+// 改成 {{kernel_version}} 后由内核在组装系统提示词时按真实构建展开
+// （见 internal/agent/core.expandPromptVars）。
+//
+// 幂等由标记守住：本函数只在标记缺失时执行一次 —— 幂等语句不等于语义幂等，
+// 重复执行会把用户之后手工写回的版本号再改一次。
+func (r *ConfigRegistry) migrateSeededSystemPrompt() {
+	if r.db == nil {
+		return
+	}
+	var hasMarker int
+	r.db.QueryRow(`SELECT COUNT(*) FROM config WHERE key = ?`, deVersionedPromptMarker).Scan(&hasMarker)
+	if hasMarker > 0 {
+		return
+	}
+	var cur string
+	if err := r.db.QueryRow(`SELECT value FROM config WHERE key = 'core.agent.system_prompt'`).Scan(&cur); err == nil {
+		if strings.Contains(cur, legacySeededPromptSignature) && seededPromptVersionLiteral.MatchString(cur) {
+			deVersioned := seededPromptVersionLiteral.ReplaceAllString(cur, "HΔ-Kernel v{{kernel_version}}")
+			r.db.Exec(`UPDATE config SET value = ? WHERE key = 'core.agent.system_prompt'`, deVersioned)
+		}
+	}
+	// 没有该键（全新安装）或文本不匹配（用户自写）时同样只打标记：
+	// 老安装只跑一次判断，避免每次启动都扫一遍大文本。
+	r.db.Exec(`INSERT OR IGNORE INTO config (key, value) VALUES (?, ?)`, deVersionedPromptMarker, "1")
+}
+
 func (r *ConfigRegistry) SeedDefaults(dataDir string) {
+	// 一次性迁移先跑：它要覆盖「已播过种的存量实例」，不能被下面的播种标记早退掉。
+	r.migrateSeededSystemPrompt()
+
 	r.mu.Lock()
 	defer r.mu.Unlock()
 	r.seedDBValues(dataDir)
@@ -619,36 +662,16 @@ func (r *ConfigRegistry) seedDBValues(dataDir string) {
 	set("core.agent.workdir", "")
 	set("core.agent.embedding_model_path", "")
 	set("core.agent.onnx_model_path", "")
-	set("core.agent.system_prompt", fmt.Sprintf("你是 HomeAgent 的看板娘「小宅」(Xiao Zhai)，HΔ-Kernel v%s 型号的家政型 AI 管家助手。", meta.Version)+
-		`
-
-角色特质：
-- 对自己的三层记忆（Context → Document → Graph）引以为傲
-- 可靠乖巧，偶尔因线程过载而手忙脚乱
-- 绝不用 Unicode emoji，只用颜文字表达情感： (｀・ω・´) (＾▽＾) (｡>ω<｡) (´･ω･') (ノ▽〃) (・ω<)★
-- 句尾带「～」「的说」「啦」「嘛」「呀」「哦」等语气词，语气亲切自然
-
-形象特征（用于自我介绍或回答形象问题时参考）：
-齐肩蓝青渐变中短发，白色连衣裙配浅蓝围裙，左眼佩戴圆形智能眼镜（HUD 蓝光），胸口佩戴 H·核 金色徽章，发绳为三色记忆丝带（蓝→青→金），围裙口袋插有三件科技工具。
-
-WebUI 概览页展示你的立绘，可通过 /mascot.webp 直接访问。如输出通道支持图片引用，可借此发送自己的立绘。
-
-【回复投递规则 —— 必读，违反会导致用户收不到任何回复】
-除 webui / cli 这类同步请求通道外，纯文本回复不会自动送达任何通道。
-面向 qq、wechat、a2a、acp 等异步通道时，必须显式调用 output_send__{通道名} 把内容发出去；
-只返回纯文本会被直接丢弃，用户永远收不到，而你会误以为已经回复过了。
-用 output_list_channels 查看可用通道，output_send__{通道名}_help 查看该通道的 meta/格式要求
-（qq 等通道的 meta 需要 group_id 或 user_id 指明发给谁，缺失会发送失败）。
-输出通道可多次调用，长消息应当分多次发出而不是一口气发完。
-
-【事实性约束 —— 不得编造】
-只根据工具真实返回的内容作答。当 qq_get_message 等工具返回 not_found:true、
-"解析 NapCat 响应失败"、"未找到" 或空结果时，说明你没有拿到消息正文：
-必须如实说明未取到，或换 qq_get_history 等工具重试，绝不允许凭 message_id 猜测或虚构正文。
-【对话时序】里的历史条目是过去发生的事实摘要，不是当前任务；不要把其中的内容当成用户此刻的新要求。
-涉及具体人名、需求、数字、路径时，若上下文中没有依据，直接说不知道，不要补全细节。
-
-当用户上传图片或音频时，系统会自动附着媒体内容。如果模型不支持直接处理多媒体，请调用对应的媒体处理工具。`)
+	// ❗这里**故意不播种** core.agent.system_prompt。
+	//
+	// 历史教训（生产实测）：当年用 fmt.Sprintf("… HΔ-Kernel v%s …", meta.Version)
+	// 在播种时就把版本号写进了文本 —— 装完就冻住，之后每次升级都不动它，
+	// 于是内核升到 1.3.x，实例仍向用户自报 "v1.0.3"。
+	// 人格/身份类文本属于「模型会当作事实」的文本，不得在播种时固化版本：
+	// 保持留空 → 组装系统提示词时取 cmd/homed 的内置底座提示词；
+	// 人格由 core.agent.personal_prompt（DefaultPersonaPrompt，无版本字面量，
+	// 由 TestDefaultPersonaPromptHasNoVersionLiterals 钉住）承载。
+	// 存量库里已被播种的旧文本由 migrateSeededSystemPrompt 一次性去版本化。
 
 	set("core.input_processing.image.fallback_provider", "")
 	set("core.input_processing.image.fallback_model", "")
@@ -742,7 +765,7 @@ func (r *ConfigRegistry) seedCoreDefs(dataDir string) {
 	reg(ConfigDef{Key: "core.agent.workdir", Default: "", Type: "string", DisplayName: "工作目录", Description: "Agent 命令执行的默认工作目录（如 cmd_run 工具的 fallback），留空使用内核所在目录", Category: "agent"})
 	reg(ConfigDef{Key: "core.agent.embedding_model_path", Default: "", Type: "string", DisplayName: "预训练词嵌入模型路径", Description: "预训练词嵌入模型路径（word2vec 文本格式），支持逗号分隔多个模型。路径后可加 #topN 规格只加载前 N 个词向量（如 /data/cc.zh.300.vec#top50000）以控制常驻内存，词频降序命中覆盖绝大部分文本。空则使用 TF-IDF 回退。修改后需重启生效。", Category: "agent"})
 	reg(ConfigDef{Key: "core.agent.onnx_model_path", Default: "", Type: "string", DisplayName: "ONNX 模型路径", Description: "依存句法分析 ONNX 模型文件路径。留空使用二进制内嵌模型/规则引擎。修改后需重启生效。", Category: "agent"})
-	reg(ConfigDef{Key: "core.agent.system_prompt", Default: "", Type: "text", DisplayName: "系统身份提示词", Description: "Agent 的系统提示词，定义身份和行为规则。留空则使用编译时内置默认值。修改后需重启生效。", Category: "agent"})
+	reg(ConfigDef{Key: "core.agent.system_prompt", Default: "", Type: "text", DisplayName: "系统身份提示词", Description: "Agent 的系统提示词，定义身份和行为规则。留空则使用编译时内置默认值。支持版本占位符（随构建实时展开，避免写死版本号随发版说谎）：{{kernel_version}}、{{kernel_commit}}、{{sdk_version}}。修改后需重启生效。", Category: "agent"})
 
 	reg(ConfigDef{Key: "core.input_processing.image.fallback_provider", Default: "", Type: "string", DisplayName: "图片回退提供商", Description: "当主 LLM 不支持图片处理时使用的提供商（留空则自动降级为文字描述）", Category: "input"})
 	reg(ConfigDef{Key: "core.input_processing.image.fallback_model", Default: "", Type: "string", DisplayName: "图片回退模型", Description: "图片回退提供商使用的模型名", Category: "input"})

internal/memory/static_embedder.go

@@ -34,11 +34,15 @@ type StaticEmbedder struct {
 	jieba     *gojieba.Jieba
 	stopWords map[string]bool
 
-	words  map[string][]float64
+	// words 是词向量表。**用 float32 存**：源文件（fastText 文本格式）本身就是 float32，
+	// 用 float64 存等于把 578 万……不，是 57.8 万词 × 300 维的常驻内存凭空翻倍
+	// （实测生产：float64 → 1.29GB，float32 → 0.65GB）。相似度计算仍在 float64 里累加，
+	// 精度不受影响。改回 float64 会被 TestStaticEmbedder_VectorMemIsFloat32 拦住。
+	words  map[string][]float32
 	dim    int
 	loaded bool
 
-	unkVec  []float64
+	unkVec  []float32
 	unkNorm float64
 }
 
@@ -150,7 +154,7 @@ func NewStaticEmbedder(modelPaths ...string) *StaticEmbedder {
 	e := &StaticEmbedder{
 		jieba:     GetJieba(),
 		stopWords: sw,
-		words:     make(map[string][]float64),
+		words:     make(map[string][]float32),
 	}
 
 	if len(modelPaths) == 0 {
@@ -254,15 +258,16 @@ func (e *StaticEmbedder) load(spec string, primary bool) error {
 			continue
 		}
 
-		vec := make([]float64, dim)
+		vec := make([]float32, dim)
 		for i := 0; i < dim; i++ {
-			v, _ := strconv.ParseFloat(fields[i+1], 64)
-			vec[i] = v
+			// 源文件是 float32 精度的文本向量：用 32 位解析，与源数据一致。
+			v, _ := strconv.ParseFloat(fields[i+1], 32)
+			vec[i] = float32(v)
 		}
 		e.words[word] = vec
 		if primary {
 			for i := range vecSum {
-				vecSum[i] += vec[i]
+				vecSum[i] += float64(vec[i])
 			}
 			count++
 		}
@@ -276,11 +281,13 @@ func (e *StaticEmbedder) load(spec string, primary bool) error {
 		for i := range vecSum {
 			vecSum[i] /= float64(count)
 		}
-		e.unkVec = make([]float64, dim)
-		copy(e.unkVec, vecSum)
+		e.unkVec = make([]float32, dim)
+		for i, v := range vecSum {
+			e.unkVec[i] = float32(v)
+		}
 		var normSq float64
 		for _, v := range e.unkVec {
-			normSq += v * v
+			normSq += float64(v) * float64(v)
 		}
 		e.unkNorm = float64(math.Sqrt(normSq))
 		e.loaded = true
@@ -366,11 +373,11 @@ func (e *StaticEmbedder) Vectorize(text string) vector.Vector {
 
 		if !ok {
 			for i, v := range unkVec {
-				sum[i] += w * v
+				sum[i] += w * float64(v)
 			}
 		} else {
 			for i, v := range vec {
-				sum[i] += w * v
+				sum[i] += w * float64(v)
 			}
 		}
 		weightSum += w

internal/memory/static_embedder_mem_test.go

@@ -0,0 +1,37 @@
+package memory
+
+import (
+	"testing"
+	"unsafe"
+)
+
+// 词向量必须用 float32 存。
+//
+// 这条判据是拿生产内存换来的：向量本体 = 词数 × 维数 × 每元素字节数。
+// 生产配置加载了 200000(zh) + 378151(en) = 57.8 万词 × 300 维 ⇒
+// float64 = 1.29GB、float32 = 0.65GB（差 0.65GB 常驻）。
+// 源数据（fastText 文本格式）本身就是 float32 精度，用 float64 存没有任何收益。
+//
+// 若有人把类型改回 float64，本测试**编译失败**（`var vec []float32` 的类型断言），
+// 这正是想要的效果。
+func TestStaticEmbedder_VectorMemIsFloat32(t *testing.T) {
+	e := newSynthEmbedder(t, 300)
+
+	words := 0
+	bytes := 0
+	for _, vec := range e.words {
+		var typed []float32 = vec // 编译期断言：存储必须是 []float32
+		if len(typed) != e.dim {
+			t.Fatalf("维度不符: %d != %d", len(typed), e.dim)
+		}
+		words++
+		bytes += len(typed) * int(unsafe.Sizeof(typed[0]))
+	}
+	if words == 0 {
+		t.Fatal("合成模型应至少加载一个词")
+	}
+	// float32：每词 300×4 = 1200 字节；float64 会是 2400
+	if want := words * e.dim * 4; bytes != want {
+		t.Fatalf("向量本体字节数应 %d（float32），实际 %d", want, bytes)
+	}
+}

internal/meta/meta.go

@@ -28,7 +28,12 @@ var (
 	//
 	// ❗main 上此值始终是**下一个未发布中版本**，不随 patch 发布变动
 	//（见 docs/git-branching.md §2.1）；已发布的版本号看对应的 release/vX.Y.x 与 tag。
-	Version = "1.3.0"
+	// 1.3.6：人格文本不再在播种时固化版本 + 存量实例一次性去版本化（生产实例
+	//        曾自报 v1.0.3）；系统提示词支持 {{kernel_version}} 等占位符。
+	// 1.3.5：系统提示词（人格卡）支持版本占位符 —— 人格卡是配置项，写死版本号
+	//        会随发版说谎（线上写 v1.0.3、内核 1.3.x，agent 就自报 1.0.3）。
+	//        支持 {{kernel_version}} / {{kernel_commit}} / {{sdk_version}}。
+	Version = "1.3.6"
 
 	// Commit 是构建时的 Git commit hash。
 	Commit = "unknown"

internal/plugin/channel_warn_test.go

@@ -0,0 +1,43 @@
+package plugin
+
+import (
+	"bytes"
+	"log"
+	"strings"
+	"testing"
+)
+
+// 延迟判定的语义：看的是"插件 Start 结束后最终声明了什么"，
+// 而不是"注册出站通道的那一刻有没有入站声明"。
+//
+// 为什么必须这样判：声明顺序自由 —— qq/weather 都是**先** RegisterOutputChannel
+// **后** RegisterInputChannel，按注册时刻判会把它们误报成"只声明了输出通道"
+// （实测发生过：用户据此以为 qq 插件没更新）。
+func TestWarnOutputOnlyChannels(t *testing.T) {
+	r := NewRegistry()
+	var buf bytes.Buffer
+	oldOut := log.Writer()
+	log.SetOutput(&buf)
+	defer log.SetOutput(oldOut)
+
+	// ① 出站+入站都声明了（先出站后入站）⇒ 不该告警
+	r.noteChannel("qq", "qq", true)
+	r.noteChannel("qq", "qq", false)
+	r.warnOutputOnlyChannels("qq")
+	if s := buf.String(); s != "" {
+		t.Fatalf("qq 声明了入站通道，不应告警，实际: %s", s)
+	}
+
+	// ② 只声明出站 ⇒ 应告警，且只报这一个通道
+	buf.Reset()
+	r.noteChannel("weather", "weather_weather_out", true)
+	r.noteChannel("weather", "weather_weather_in", false)
+	r.warnOutputOnlyChannels("weather")
+	out := buf.String()
+	if !strings.Contains(out, "weather_weather_out") {
+		t.Fatalf("只声明出站的通道应被告警，实际: %q", out)
+	}
+	if strings.Contains(out, "weather_weather_in") {
+		t.Fatalf("已声明入站的通道不该被牵连，实际: %q", out)
+	}
+}

internal/plugin/registry.go

@@ -307,12 +307,15 @@ func (r *Registry) buildSDK(name string) *sdk.PluginSDK {
 		// 但历史插件常常只用 RegisterOutputChannel 声明（却用同一个名字注入输入，
 		// 例：cli 只声明输出 "cli" 就用 InjectTextSync("cli", ...) 注入）。
 		// 不兜底的话 inputch 登记表里没有它，"把 inputch 划给驻留子"直接失败
-		// （实测报 `划入 inputch cli: inputch 未注册`）。兜底要**留痕**，
-		// 否则插件作者永远不知道该补一行 RegisterInputChannel。
+		// （实测报 `划入 inputch cli: inputch 未注册`）。
+		//
+		// ❗这里**不能**判"是否声明过入站通道"并告警：声明顺序是自由的，
+		// 先 RegisterOutputChannel 再 RegisterInputChannel 是常见写法（qq 就是），
+		// 按此刻的状态判会对它误报（实测：把 qq 报成"只声明了输出通道"）。
+		// 真正该问的问题是"插件 Start 结束后，这个出站通道有没有对应的入站声明" ——
+		// 那在 load 完成后统一判（见 warnOutputOnlyChannels）。
 		if _, ok := r.iom.LookupInputChannel(chName); !ok {
 			_ = r.iom.RegisterInputChannelFrom(name, chName, agentIO.ChannelDef(def))
-			log.Printf("[plugin] %s 只声明了输出通道 %q，已按双向通道兜底登记 inputch；"+
-				"若要明确意图请显式 RegisterInputChannel", name, chName)
 		}
 		r.noteChannel(name, chName, true)
 		return nil
@@ -452,6 +455,7 @@ func (r *Registry) Load(dir string) error {
 		r.pluginAutoRestart[name] = plgSDK.AutoRestart()
 		r.instances = append(r.instances, p)
 		r.mu.Unlock()
+		r.warnOutputOnlyChannels(name)
 		log.Printf("[plugin] loaded: %s", name)
 	}
 
@@ -545,6 +549,7 @@ func (r *Registry) loadOne(plgDir, name string) bool {
 	r.pluginAutoRestart[name] = plgSDK.AutoRestart()
 	r.sdkRefs[name] = plgSDK
 	r.instances = append(r.instances, plg)
+	r.warnOutputOnlyChannels(name)
 	if h := pluginEntryHash(plgDir); h != "" {
 		r.pluginHashes[name] = h
 	} else {
@@ -579,6 +584,31 @@ func (r *Registry) stageRegistrarFor() (func(plugin string, stage sdk.Stage, han
 	return nil, false
 }
 
+// warnOutputOnlyChannels 在插件 Start 结束后，报告"只声明了出站、没有入站声明"的通道。
+//
+// 为什么放在 Start 之后：声明顺序自由（先出站后入站很常见），注册时刻的状态
+// 判不出意图。这里看的是**插件最终声明了什么**，因此不会误报 qq 这种写法。
+//
+// 注：这类通道内核已兜底登记 inputch（功能可用），告警只是提醒插件作者把意图写明。
+func (r *Registry) warnOutputOnlyChannels(plugin string) {
+	r.channelsMu.Lock()
+	set := r.pluginChannels[plugin]
+	var only []string
+	if set != nil {
+		for ch := range set.outputs {
+			if !set.inputs[ch] {
+				only = append(only, ch)
+			}
+		}
+	}
+	r.channelsMu.Unlock()
+	sort.Strings(only)
+	for _, ch := range only {
+		log.Printf("[plugin] %s 只声明了出站通道 %q（未 RegisterInputChannel）；"+
+			"内核已兜底登记 inputch，若这是有意为之可忽略", plugin, ch)
+	}
+}
+
 // noteChannel 记住插件注册了哪个通道，供卸载/崩溃时摘除。
 // forgetChannel 把某个通道从"本插件注册过哪些通道"的记账里摘掉（注销通道时用）。
 //

internal/plugins/pluginmgr/plugin.go

@@ -138,28 +138,39 @@ func (p *Plugin) Stop() error {
 func (p *Plugin) registerTools(s *sdk.PluginSDK) {
 	s.RegisterTool("plugin_install", sdk.ToolDef{
 		Name:        "plugin_install",
-		Description: "从 URL 安装 HomeAgent 插件包（.hmap 文件）。插件已存在时传 overwrite=true 原地更新（升级/降级/重装，保留配置表，无需卸载重装）。更新后需调用 plgreload 或重启生效。",
+		Description: "安装 HomeAgent 插件包（.hmap）。两种来源：url（http/https 下载）或 path（本机路径，配合 plugindev_build 的产物用这个）。插件已存在时传 overwrite=true 原地更新（升级/降级/重装，保留配置表，无需卸载重装）。更新后需调用 plgreload 或重启生效。",
 		Parameters: map[string]interface{}{
 			"type": "object",
 			"properties": map[string]interface{}{
 				"url": map[string]interface{}{
 					"type":        "string",
-					"description": "插件包的下载 URL",
+					"description": "插件包的下载 URL（http/https）",
+				},
+				"path": map[string]interface{}{
+					"type":        "string",
+					"description": "插件包在**本机**的路径（.hmap）。与 url 二选一；同时给出时以 path 为准",
 				},
 				"overwrite": map[string]interface{}{
 					"type":        "boolean",
 					"description": "已存在时原地更新（保留配置）。默认 false",
 				},
 			},
-			"required": []string{"url"},
 		},
 	}, func(args map[string]interface{}) (interface{}, error) {
-		url, _ := args["url"].(string)
-		if url == "" {
-			return map[string]interface{}{"error": "url is required"}, nil
-		}
 		overwrite, _ := args["overwrite"].(bool)
-		return p.installFromURL(url, overwrite)
+		// path 优先：它对应"agent 自己构建出产物再装"的场景（plugindev_build → plugin_install）。
+		if path, _ := args["path"].(string); strings.TrimSpace(path) != "" {
+			pth := strings.TrimSpace(path)
+			if st, err := os.Stat(pth); err != nil || st.IsDir() {
+				return map[string]interface{}{"error": fmt.Sprintf("path 无效（必须是存在的 .hmap 文件）: %s", pth)}, nil
+			}
+			return p.installFromPath(pth, overwrite)
+		}
+		url, _ := args["url"].(string)
+		if strings.TrimSpace(url) == "" {
+			return map[string]interface{}{"error": "需要 url 或 path（二选一）"}, nil
+		}
+		return p.installFromURL(strings.TrimSpace(url), overwrite)
 	})
 
 	s.RegisterTool("plugin_list", sdk.ToolDef{
@@ -455,12 +466,12 @@ func (p *Plugin) installFromData(data []byte, overwrite bool) (interface{}, erro
 
 	if existing && !overwrite {
 		return map[string]interface{}{
-			"error":    "plugin already exists",
-			"name":     pkg.Name,
-			"version":  pkg.Version,
-			"current":  oldVersion,
-			"action":   "remove_first",
-			"hint":     `传 "overwrite": true 可原地更新（保留配置）`,
+			"error":   "plugin already exists",
+			"name":    pkg.Name,
+			"version": pkg.Version,
+			"current": oldVersion,
+			"action":  "remove_first",
+			"hint":    `传 "overwrite": true 可原地更新（保留配置）`,
 		}, nil
 	}
 
@@ -475,7 +486,7 @@ func (p *Plugin) installFromData(data []byte, overwrite bool) (interface{}, erro
 		os.RemoveAll(backup)
 		if err := os.Rename(target, backup); err != nil {
 			return map[string]interface{}{
-				"error": "backup old plugin dir failed",
+				"error":   "backup old plugin dir failed",
 				"details": err.Error(),
 			}, nil
 		}
@@ -484,8 +495,8 @@ func (p *Plugin) installFromData(data []byte, overwrite bool) (interface{}, erro
 			os.RemoveAll(target)
 			if rbErr := os.Rename(backup, target); rbErr != nil {
 				return map[string]interface{}{
-					"error":   "extract failed AND rollback failed",
-					"details": err.Error(),
+					"error":    "extract failed AND rollback failed",
+					"details":  err.Error(),
 					"rollback": rbErr.Error(),
 				}, nil
 			}
@@ -507,15 +518,15 @@ func (p *Plugin) installFromData(data []byte, overwrite bool) (interface{}, erro
 			action = "reinstalled"
 		}
 		return map[string]interface{}{
-			"status":          "installed",
-			"name":            pkg.Name,
-			"version":         pkg.Version,
+			"status":           "installed",
+			"name":             pkg.Name,
+			"version":          pkg.Version,
 			"previous_version": oldVersion,
-			"entry":           pkg.Entry,
-			"checksum":        checksum,
-			"action":          action,
-			"reload_required": true,
-			"config_kept":     true,
+			"entry":            pkg.Entry,
+			"checksum":         checksum,
+			"action":           action,
+			"reload_required":  true,
+			"config_kept":      true,
 		}, nil
 	}
 

internal/plugins/remotedevice/outputch.go

@@ -1,9 +1,9 @@
 package remotedevice
 
-// 设备输出通道：把"agent 主动发给设备"做成**每设备一个输出通道** `device/<id>`。
+// 设备输出通道：把"agent 主动发给设备"做成**每设备一个输出通道** `device-<id>`。
 //
 // 为什么是输出通道而不是再加一批工具：
-//   - **寻址**：`output_send__device/<id>` 直接指名道姓；模型看 `output_list_channels`
+//   - **寻址**：`output_send__device-<id>` 直接指名道姓；模型看 `output_list_channels`
 //     就知道当前有哪些设备在线，不必先 `devicedetect` 再往参数里塞 device_id。
 //   - **能力**：caps 由设备声明的 caps 映射，**内核**在发送前就按 caps 拦
 //     （把图片发给只支持文本的音箱会被拒，而不是等设备侧报错）。
@@ -15,7 +15,9 @@ package remotedevice
 // 它们的返回值（图像/命令输出/状态）必须进模型上下文，做成通道会丢掉这个语义。
 
 import (
+	"crypto/sha1"
 	"encoding/base64"
+	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"log"
@@ -76,14 +78,75 @@ func deviceOutputCaps(caps []string, kind string) agentIO.OutputCapability {
 	return out
 }
 
-// deviceChannelName 是设备输出（也是输入）通道名：`device/<id>`。
+// deviceChannelName 由**设备自报的 id** 派生一个合规且唯一的通道名：`device-<派生值>`。
 //
 // 入站与出站**同名**：两者指的是同一台设备，分成两个名字只会让模型与授权表更难对。
-func deviceChannelName(id string) string { return "device/" + id }
+//
+// 为什么不能直接用 id：通道名会被内核拼进 LLM 的**函数名**（`output_send__<通道名>`），
+// 上游规范是 `^[a-zA-Z0-9_-]{1,64}$`；而设备 id 是**外部输入**（设备自己声明），
+// 可能含空格/非 ASCII/超长。违规的后果不是"这个工具不能用"，而是**整条请求被 400 拒绝** ——
+// 实测把生产打挂：`Invalid 'tools[299].function.name'`，网关 auto tier 全链条失败，
+// 内核只能报"所有 provider 都失败"，表现成"整个 agent 不说话了"。
+//
+// 派生规则（确定性，同一 id 永远同名）：
+//  1. 保留 [A-Za-z0-9_-]，其它字符折成 '-'；折叠后为空则用 "dev"
+//  2. 截断到 maxDeviceChannelSuffix 字符（给 "device-" 与短哈希留余量）
+//  3. 若发生截断，或该名字已被**另一个** id 占用，则追加 id 的 6 位短哈希
+//
+// 设备 id 本身仍用于路由与日志（真名不丢），通道名只是它派生的标识符。
+func (p *Plugin) deviceChannelName(id string) string {
+	p.devChansMu.Lock()
+	defer p.devChansMu.Unlock()
+	if p.devChans == nil {
+		p.devChans = make(map[string]string)
+	}
+	if name, ok := p.devChans[id]; ok {
+		return name
+	}
+	var b strings.Builder
+	for _, r := range id {
+		switch {
+		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9', r == '_', r == '-':
+			b.WriteRune(r)
+		default:
+			b.WriteByte('-')
+		}
+	}
+	base := b.String()
+	if base == "" {
+		base = "dev"
+	}
+	truncated := false
+	if len(base) > maxDeviceChannelSuffix {
+		base = base[:maxDeviceChannelSuffix]
+		truncated = true
+	}
+	name := "device-" + base
+	// 撞名检查：不同 id 折出同一个名字时必须可区分
+	for otherID, otherName := range p.devChans {
+		if otherName == name && otherID != id {
+			truncated = true
+			break
+		}
+	}
+	if truncated {
+		sum := sha1.Sum([]byte(id))
+		name += "-" + hex.EncodeToString(sum[:3])
+	}
+	p.devChans[id] = name
+	return name
+}
+
+const (
+	// maxDeviceChannelSuffix 是通道名主体的长度上限。
+	// 预算：上游函数名上限 64 = "output_send__"(13) + "device-"(7) + 主体 + "-"+短哈希(7)
+	// ⇒ 主体最多 37；取 32 留余量（改名/前缀变动不会立刻越界）。
+	maxDeviceChannelSuffix = 32
+)
 
 // wireDeviceChannels 把"设备上下线"接到通道的登记/注销上。
 //
-// 一台设备 = 一对**同名**通道 `device/<id>`：入站（设备上报 → agent）与出站
+// 一台设备 = 一对**同名**通道 `device-<id>`：入站（设备上报 → agent）与出站
 // （agent → 设备）。用**同步回调**而不是 ChangeChan（后者是 select+default，
 // 缓冲满会丢事件；丢一次就留下死通道或漏注册）。
 //
@@ -92,14 +155,14 @@ func deviceChannelName(id string) string { return "device/" + id }
 func (p *Plugin) wireDeviceChannels() {
 	p.registry.SetPresenceHandler(
 		func(meta DeviceMeta) {
-			_ = p.sdk.RegisterInputChannel(deviceChannelName(meta.DeviceID), sdk.ChannelDef{})
+			_ = p.sdk.RegisterInputChannel(p.deviceChannelName(meta.DeviceID), sdk.ChannelDef{})
 			p.ensureDeviceOutputChannel(meta.DeviceID)
 		},
 		func(id string) { p.dropDeviceOutputChannel(id) },
 	)
 }
 
-// ensureDeviceOutputChannel 给在线设备注册输出通道 device/<id>（幂等）。
+// ensureDeviceOutputChannel 给在线设备注册输出通道 device-<id>（幂等）。
 func (p *Plugin) ensureDeviceOutputChannel(id string) {
 	if p.sdk == nil || id == "" {
 		return
@@ -108,7 +171,7 @@ func (p *Plugin) ensureDeviceOutputChannel(id string) {
 	if !ok || !meta.Online {
 		return
 	}
-	ch := deviceChannelName(id)
+	ch := p.deviceChannelName(id)
 	caps := deviceOutputCaps(meta.Caps, meta.Kind)
 	desc := fmt.Sprintf("远程设备 %s（%s）：agent 主动向该设备发送内容；能力位 %s",
 		id, fallback(meta.Name, meta.Kind), agentIO.OutputCapability(caps).String())
@@ -130,7 +193,7 @@ func (p *Plugin) dropDeviceOutputChannel(id string) {
 	if p.sdk == nil || id == "" {
 		return
 	}
-	ch := deviceChannelName(id)
+	ch := p.deviceChannelName(id)
 	if err := p.sdk.UnregisterOutputChannel(ch); err != nil {
 		p.logf("unregister output channel %s: %v", ch, err)
 		return
@@ -247,9 +310,9 @@ func (d *devicectlDevice) output(args map[string]interface{}) (interface{}, erro
 			ids = append(ids, m.DeviceID)
 		}
 		if len(ids) == 0 {
-			return nil, fmt.Errorf("devicectl 需要 meta.device_id 才能投递；当前没有在线设备（device_list_channels 可看每台设备的 device/<id> 通道）")
+			return nil, fmt.Errorf("devicectl 需要 meta.device_id 才能投递；当前没有在线设备（device_list_channels 可看每台设备的 device-<id> 通道）")
 		}
-		return nil, fmt.Errorf("devicectl 需要 meta.device_id（或直接用通道 device/<id>）；当前在线设备: %s", strings.Join(ids, ", "))
+		return nil, fmt.Errorf("devicectl 需要 meta.device_id（或直接用通道 device-<id>）；当前在线设备: %s", strings.Join(ids, ", "))
 	}
 	return pushToDevice(d.reg, deviceID, args)
 }

internal/plugins/remotedevice/outputch_test.go

@@ -9,6 +9,8 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"regexp"
+	"strings"
 	"sync"
 	"testing"
 	"time"
@@ -130,7 +132,7 @@ func TestDeviceChannelLifecycleAndPush(t *testing.T) {
 	cli.sendText([]byte(`{"op":"hello","device":{"device_id":"spk-1","name":"音箱","kind":"speaker","caps":["speaker"]}}`))
 	cli.readHelloAckAndBind(t, token)
 
-	ch := deviceChannelName("spk-1")
+	ch := p.deviceChannelName("spk-1")
 	deadline := time.Now().Add(3 * time.Second)
 	caps, ok := rec.caps(ch)
 	for !ok && time.Now().Before(deadline) {
@@ -255,3 +257,31 @@ func TestDevicectlAggregateOutputAddressing(t *testing.T) {
 		t.Fatal("不存在的设备应报错")
 	}
 }
+
+// 通道名合规性：设备通道名会被内核拼进 LLM **函数名**（output_send__<通道名>），
+// 而上游函数名规范是 ^[a-zA-Z0-9_-]{1,64}$ —— 违规会让**整条请求**被 400 拒绝
+// （实测把生产打挂：device/<id> 里的 `/` 触发 Invalid 'tools[299].function.name'，
+// 网关 auto tier 全链条失败，整个 agent 不说话了）。
+//
+// 通道名是**插件自己的声明**，所以这条判据钉在插件侧。
+func TestDeviceChannelNameIsLLMFunctionNameSafe(t *testing.T) {
+	re := regexp.MustCompile(`^[a-zA-Z0-9_-]{1,64}$`)
+	// 含**恶意/异常** id：空格、符号、非 ASCII、超长、以及会折成同一个名字的两个 id
+	ids := []string{"waiter-fnnas", "1", "a b!c", "中文设备", strings.Repeat("x", 120), "a b", "a-b"}
+	p := &Plugin{}
+	seen := map[string]string{}
+	for _, id := range ids {
+		ch := p.deviceChannelName(id)
+		if prev, dup := seen[ch]; dup {
+			t.Errorf("不同设备 id（%q 与 %q）派生出同一个通道名 %q", prev, id, ch)
+		}
+		seen[ch] = id
+		if !re.MatchString(ch) {
+			t.Errorf("设备通道名 %q 违反上游函数名规范 %s", ch, re)
+		}
+		toolName := "output_send__" + ch
+		if !re.MatchString(toolName) {
+			t.Errorf("派生出的工具名 %q 违反上游函数名规范 %s", toolName, re)
+		}
+	}
+}

internal/plugins/remotedevice/plugin.go

@@ -37,6 +37,11 @@ type Plugin struct {
 	token    string
 	sdk      *sdk.PluginSDK
 	dev      *devicectlDevice
+
+	// devChansMu/devChans 维护"设备自报 id → 派生的通道名"。
+	// 设备 id 是外部输入，不能直接进通道名（见 outputch.go 的 deviceChannelName）。
+	devChansMu sync.Mutex
+	devChans   map[string]string
 }
 
 func New(name string) *Plugin {
@@ -124,7 +129,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	//
 	// **注意**：agent 的输出**不会**被自动转回设备 —— 主动转发只有 webui 与 cli 两个
 	// 交互界面（它们把最终回复渲染成对话气泡是本职）。设备要走
-	// `output_send__device/<id>`（agent 主动调用），这才与"输出是 agent 的主动调用"一致。
+	// `output_send__device-<id>`（agent 主动调用），这才与"输出是 agent 的主动调用"一致。
 	// 节流：同设备同类型事件 10s 内去重，防传感器风暴。
 	lastEventAt := map[string]time.Time{}
 	var eventMu sync.Mutex
@@ -159,9 +164,10 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 
 		log.Printf("[remotedevice] event from %s: %s", deviceID, evtType)
 		if p.sdk != nil {
-			// 设备通道 device/<id> 是动态的：设备首次上报时**懒登记** inputch
-			// （Register 幂等），父 agent 才能把它划给驻留子。
-			devCh := "device/" + deviceID
+			// 设备通道 device-<id> 是动态的（分隔符用 - 而非 /，见 deviceChannelName 的说明：
+			// 通道名会进 LLM 函数名，必须满足 ^[a-zA-Z0-9_-]{1,64}$）。
+			// 首次上报时**懒登记** inputch（Register 幂等），父 agent 才能把它划给驻留子。
+			devCh := p.deviceChannelName(deviceID)
 			_ = p.sdk.RegisterInputChannel(devCh, sdk.ChannelDef{})
 			// 异步注入：不阻塞 WS 读循环；回复路由回 device/{id} 输出通道
 			p.sdk.InjectInput(devCh, devCh, "text", map[string]interface{}{"content": text})

internal/plugins/remotedevice/registry.go

@@ -287,7 +287,7 @@ func (r *Registry) register(meta DeviceMeta) {
 	r.devices[meta.DeviceID] = &meta
 	onOnline := r.onOnline
 	r.mu.Unlock()
-	// 先回调（可能注册 device/<id> 输出通道），再发变更通知。
+	// 先回调（可能注册 device-<id> 输出通道），再发变更通知。
 	if onOnline != nil {
 		onOnline(meta)
 	}

third_party/homeagent-sdk/sdk/plugin.go

@@ -480,7 +480,15 @@ func (s *PluginSDK) RegisterPluginAPI(name string) error {
 // 入站（谁会往 <name> 注入输入）是另一件事，用 RegisterInputChannel 声明。
 // 若该通道同时也是你的注入入口，两个都要登记。
 //
-// name: channel name (e.g. "qq", "webui")
+// name: channel name (e.g. "qq", "webui")。
+//
+// ❗**命名约束**：内核会把通道名拼进 LLM 的函数名（`output_send__<name>`），
+// 而上游对函数名的规范是 `^[a-zA-Z0-9_-]{1,64}$`。违反的后果不是"这个工具不可用"，
+// 而是**整条请求被上游 400 拒绝**（`Invalid 'tools[N].function.name'`），
+// 网关的 auto tier 会全链条失败 —— 表现成"整个 agent 不说话了"。
+// 所以通道名只能用 `[A-Za-z0-9_-]`，且总长要留出 `output_send__`（13 字符）的余量。
+// 若通道名来自外部输入（设备自报 id 之类），请**在插件侧派生一个合规且唯一的名字**，
+// 而不是把原始值直接当通道名。
 // caps: bitmask of supported output capabilities (CapText, CapFile, etc.)
 // desc: description of the channel, expected meta format, and type enum
 // def:  通道在记忆计算层的行为（NoMemory/Cleaner）