fix(packaging): SHA256SUMS 只列本批产物，且用平铺名（此前会带上历史版本、且与附件名不符）

v1.2.2 出包时发现：dist/ 跨多次构建累积，而清单用 `find $DIST_DIR` 全目录扫，
于是 SHA256SUMS 里混进了 1.2.0/1.2.1 的包名——用户从发布页下载这份清单后
`sha256sum -c` 必然报「文件缺失」（那些包并不在本页）。

两处一起修：
- 按本批 `$PKG_VERSION` 过滤（只列这次真正打出来的产物）；
- 名字用 basename（平铺名），与发布页附件名一致；哈希取真实路径（此前若直接
  对 basename 求哈希会找不到文件——就在 `deb/`、`tar/` 子目录里）。

验证：对含 1.2.0/1.2.1/1.2.2 的 dist/ 跑新逻辑 → 4 条（旧逻辑 12 条）；
并拿发布页真下载的 SHA256SUMS 逐条核对四个产物的实际哈希 → 全部一致。

cmd/homed/main.go

@@ -367,7 +367,11 @@ func main() {
 	// 布局、预处理、解码、运行时全部属于 provider 内部实现。
 	// provider 名为空时禁用多模态向量检索，退回纯 fastText 文本路径。
 	var multimodalSpace vector.MultimodalEmbedder
+	// 这两个值只用于状态报告（healthcheck_kernel 的 onnx 段）：
+	// 「配了哪个 provider」与「为什么没启用」，避免只能看到 false 却不知原因。
+	var mmProviderName, mmErr string
 	if mmProvider := cfgReg.GetString("core.memory.multimodal_space.provider", ""); mmProvider != "" {
+		mmProviderName = mmProvider
 		opts := map[string]string{}
 		const optPrefix = "core.memory.multimodal_space.options."
 		for _, key := range cfgReg.List("core.memory.multimodal_space.options.") {
@@ -375,10 +379,12 @@ func main() {
 		}
 		provider, err := embedding.Open(mmProvider, embedding.Config{Options: opts})
 		if err != nil {
+			mmErr = err.Error()
 			log.Printf("[homed] warning: 多模态向量 provider %q 打开失败: %v（多模态向量检索已禁用；已注册: %s）",
 				mmProvider, err, strings.Join(embedding.Names(), ", "))
 		} else if adapted, err := vector.AdaptProvider(provider); err != nil {
 			provider.Close()
+			mmErr = err.Error()
 			log.Printf("[homed] warning: 多模态向量 provider %q 元数据不合法: %v（多模态向量检索已禁用）", mmProvider, err)
 		} else {
 			multimodalSpace = adapted
@@ -506,20 +512,23 @@ func main() {
 	}
 
 	agent := agentCore.New(agentCore.AgentConfig{
-		ID:                 "main",
-		SystemPrompt:       sysPrompt,
-		Provider:           provider,
-		ProviderManager:    providerMgr,
-		IO:                 iom,
-		Memory:             memDB,
-		Indexer:            memIdx,
-		Tracker:            trk,
-		DocStore:           docStore,
-		Knowledge:          ks,
-		SocialStore:        socialStore,
-		TextMemory:         textMem,
-		MediaStore:         mediaStore,
-		Personality:        personality,
+		ID:              "main",
+		SystemPrompt:    sysPrompt,
+		Provider:        provider,
+		ProviderManager: providerMgr,
+		IO:              iom,
+		Memory:          memDB,
+		Indexer:         memIdx,
+		Tracker:         trk,
+		DocStore:        docStore,
+		Knowledge:       ks,
+		SocialStore:     socialStore,
+		TextMemory:      textMem,
+		MediaStore:      mediaStore,
+		Personality:     personality,
+		// 人格落库面：首启门禁（任何通道都问一次）与 persona_set 工具用。
+		// 与 WebUI 向导共用 internal/config 的同一份落库逻辑。
+		PersonaStore:       internalConfig.RegistryPersonaStore{Reg: cfgReg},
 		PluginReg:          pluginReg,
 		PluginDir:          cfg.Plugin.Dir,
 		DistillInterval:    cfgReg.GetDuration("core.agent.distill_interval", 30*time.Minute),
@@ -530,6 +539,8 @@ func main() {
 		EmbeddingModelPath: cfgReg.GetString("core.agent.embedding_model_path", ""),
 		Embedder:           embedder,
 		MultimodalSpace:    multimodalSpace,
+		EmbeddingProvider:  mmProviderName,
+		EmbeddingError:     mmErr,
 		StageHost:          stageHost,
 		EventBus:           evBus,
 		ThinkingEnabled:    cfg.LLM.ThinkingEnabled,

deploy/packaging/package-linux.sh

@@ -710,18 +710,25 @@ main() {
   echo "=== Done! Packages in: $DIST_DIR ==="
   echo ""
   echo "Summary:"
-  mapfile -t release_files < <(find "$DIST_DIR" -type f \( -name "*.deb" -o -name "homeagent_*.tar.gz" -o -name "*.rpm" \) 2>/dev/null | sort)
+  # 只列**本批**产物：dist/ 会跨多次构建累积，用 find 全目录会让清单／SHA256SUMS
+  # 带上历史版本的文件名——用户下载那种清单后 `sha256sum -c` 必然报缺失。
+  # （v1.2.2 构建时就出现过：清单里混进了 1.2.0/1.2.1 的包名。）按本批版本号过滤。
+  mapfile -t release_files < <(find "$DIST_DIR" -type f \( -name "*${PKG_VERSION}*.deb" -o -name "homeagent_${PKG_VERSION}_*.tar.gz" -o -name "*${PKG_VERSION}*.rpm" \) 2>/dev/null | sort)
   for f in "${release_files[@]}"; do
     echo "  $(du -h "$f" | cut -f1)  $f"
   done
   # 全部包生成之后一次计算，避免边打边算漏掉后生成的产物。
+  # 名字用**平铺名**（basename）：下载页的附件名就是平铺的，
+  # 清单里若写 ./deb/xxx.deb，用户下载后 `sha256sum -c` 会找不到文件。
   if [ ${#release_files[@]} -gt 0 ]; then
     (
       cd "$DIST_DIR"
-      find . -type f \( -name "*.deb" -o -name "homeagent_*.tar.gz" -o -name "*.rpm" \) \
-        -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS
+      # 哈希取**真实路径**，标签用**平铺名**：两者不能混（直接对 basename 求哈希会找不到文件）。
+      for f in "${release_files[@]}"; do
+        printf '%s  ./%s\n' "$(sha256sum "$f" | awk '{print $1}')" "$(basename "$f")"
+      done | sort -k2 > SHA256SUMS
     )
-    echo "  SHA256SUMS: $DIST_DIR/SHA256SUMS"
+    echo "  SHA256SUMS: $DIST_DIR/SHA256SUMS  （仅本批 ${#release_files[@]} 个产物，平铺名）"
   fi
 }
 

internal/agent/core/agent.go

@@ -57,9 +57,13 @@ type Agent struct {
 	// 由记忆系统本身决定。为 nil 时全部媒体接线静默跳过。
 	mediaStore *media.Store
 
-	// 人格设定
+	// 人格设定（内容来自启动时载入的人格文件/配置项）
 	personality *agentPkg.Personality
 
+	// 人格落库面：首启门禁与 persona_set 工具使用（见 persona.go）。
+	// 为 nil 时门禁与工具都静默关闭（例如单测里不接配置的场景）。
+	personaStore PersonaStore
+
 	// 插件注册表（用于 plgreload）
 	pluginReg *plugin.Registry
 	pluginDir string
@@ -150,6 +154,12 @@ type Agent struct {
 	// 也可以是外部 API 客户端；两者共享同一套 L0/L2/L3 向量缓存与检索基础设施。
 	multimodalSpace vector.MultimodalEmbedder
 
+	// embeddingProvider 是配置里指定的统一向量空间 provider 名；
+	// embeddingError 是打开/适配失败的原因（成功时为空）。
+	// 二者只用于状态报告：区分「没配」「配了但打不开」「已启用」。
+	embeddingProvider string
+	embeddingError    string
+
 	// fusionCfg 控制文本路与视觉路的跨模态融合权重，可按模型实测结果配置。
 	fusionCfg CrossModalFusionConfig
 
@@ -175,14 +185,19 @@ type AgentConfig struct {
 	Indexer         *memory.Indexer
 	Tracker         *tracker.Tracker
 
-	DocStore           *document.Store
-	Knowledge          *knowledge.Store
-	SocialStore        *social.SocialStore
-	TextMemory         *text.Memory
-	MediaStore         *media.Store
-	MultimodalSpace    vector.MultimodalEmbedder
+	DocStore        *document.Store
+	Knowledge       *knowledge.Store
+	SocialStore     *social.SocialStore
+	TextMemory      *text.Memory
+	MediaStore      *media.Store
+	MultimodalSpace vector.MultimodalEmbedder
+	// EmbeddingProvider / EmbeddingError 是向量空间的配置身份与打开失败原因，
+	// 供 healthcheck_kernel 状态报告区分「未配置 / 打开失败 / 已启用」。
+	EmbeddingProvider  string
+	EmbeddingError     string
 	FusionCfg          CrossModalFusionConfig // 跨模态融合权重；零值用默认
 	Personality        *agentPkg.Personality
+	PersonaStore       PersonaStore // 人格设定的读写面（首启门禁 + persona_set 工具）
 	PluginReg          *plugin.Registry
 	PluginDir          string
 	DistillInterval    time.Duration
@@ -251,45 +266,48 @@ func New(cfg AgentConfig) *Agent {
 	}
 
 	return &Agent{
-		id:              cfg.ID,
-		startTime:       time.Now(),
-		provider:        cfg.Provider,
-		providerManager: cfg.ProviderManager,
-		io:              cfg.IO,
-		memory:          cfg.Memory,
-		indexer:         cfg.Indexer,
-		tracker:         cfg.Tracker,
-		context:         rc,
-		systemPrompt:    cfg.SystemPrompt,
-		ctx:             ctx,
-		cancel:          cancel,
-		docStore:        cfg.DocStore,
-		knowledge:       cfg.Knowledge,
-		social:          cfg.SocialStore,
-		textMem:         cfg.TextMemory,
-		mediaStore:      cfg.MediaStore,
-		personality:     cfg.Personality,
-		pluginReg:       cfg.PluginReg,
-		pluginDir:       cfg.PluginDir,
-		distillInterval: cfg.DistillInterval,
-		archiveInterval: cfg.ArchiveInterval,
-		reviewInterval:  cfg.ReviewInterval,
-		mergeInterval:   cfg.MergeInterval,
-		maxContextSize:  cfg.MaxContextSize,
-		stageHost:       cfg.StageHost,
-		skillIndex:      cfg.SkillIndexProvider,
-		eventBus:        cfg.EventBus,
-		selfInputCh:     make(chan selfInputMsg, 64),
-		childTasks:      make(map[string]*childTaskState),
-		interceptCh:     make(chan *agentIO.InputEvent, 64),
-		pluginHealth:    newPluginHealthTracker(),
-		thinkingEnabled: cfg.ThinkingEnabled,
-		inputCfg:        cfg.InputProcessing,
-		embedder:        embedder,
-		multimodalSpace: cfg.MultimodalSpace,
-		fusionCfg:       cfg.FusionCfg,
-		noMergeMarkers:  make(map[string]int),
-		lastInput:       make(map[string]time.Time),
+		id:                cfg.ID,
+		startTime:         time.Now(),
+		provider:          cfg.Provider,
+		providerManager:   cfg.ProviderManager,
+		io:                cfg.IO,
+		memory:            cfg.Memory,
+		indexer:           cfg.Indexer,
+		tracker:           cfg.Tracker,
+		context:           rc,
+		systemPrompt:      cfg.SystemPrompt,
+		ctx:               ctx,
+		cancel:            cancel,
+		docStore:          cfg.DocStore,
+		knowledge:         cfg.Knowledge,
+		social:            cfg.SocialStore,
+		textMem:           cfg.TextMemory,
+		mediaStore:        cfg.MediaStore,
+		personality:       cfg.Personality,
+		personaStore:      cfg.PersonaStore,
+		pluginReg:         cfg.PluginReg,
+		pluginDir:         cfg.PluginDir,
+		distillInterval:   cfg.DistillInterval,
+		archiveInterval:   cfg.ArchiveInterval,
+		reviewInterval:    cfg.ReviewInterval,
+		mergeInterval:     cfg.MergeInterval,
+		maxContextSize:    cfg.MaxContextSize,
+		stageHost:         cfg.StageHost,
+		skillIndex:        cfg.SkillIndexProvider,
+		eventBus:          cfg.EventBus,
+		selfInputCh:       make(chan selfInputMsg, 64),
+		childTasks:        make(map[string]*childTaskState),
+		interceptCh:       make(chan *agentIO.InputEvent, 64),
+		pluginHealth:      newPluginHealthTracker(),
+		thinkingEnabled:   cfg.ThinkingEnabled,
+		inputCfg:          cfg.InputProcessing,
+		embedder:          embedder,
+		multimodalSpace:   cfg.MultimodalSpace,
+		embeddingProvider: cfg.EmbeddingProvider,
+		embeddingError:    cfg.EmbeddingError,
+		fusionCfg:         cfg.FusionCfg,
+		noMergeMarkers:    make(map[string]int),
+		lastInput:         make(map[string]time.Time),
 	}
 }
 

internal/agent/core/persona.go

@@ -0,0 +1,54 @@
+package core
+
+import (
+	"fmt"
+	"strings"
+
+	agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api"
+)
+
+// PersonaStore 是人格设定的读写面。
+//
+// 首启门禁（buildSystemPrompt）与 persona_set 工具都通过它工作，实现在 cmd/homed：
+// 读写配置项 core.agent.personal_prompt 与一次性标记 core.internal.persona_initialized
+// （落库逻辑与 WebUI 向导共用 internal/config 的实现）。
+//
+// 为什么放在内核而不是某个通道插件：人格是**任何通道都要问一次**的事。
+// 系统提示词每轮重建，门禁放在这里，WebUI / QQ / CLI / ACP / 邮件等全部通道自动覆盖。
+type PersonaStore interface {
+	// PersonaInitialized 报告人格是否已确认（向导或工具已问过）。
+	PersonaInitialized() bool
+	// SetPersona 落库人格并打一次性标记，返回是否需要重启才生效。
+	SetPersona(mode, content string) (restartRequired bool, err error)
+}
+
+// executePersonaTool 落地首启人格设定。
+//
+// 成功即打一次性标记 → 之后 buildSystemPrompt 不再要求模型询问人格。
+// custom 模式返回「需重启生效」：人格在 homed 启动时载入。
+func (a *Agent) executePersonaTool(tc agentAPI.ToolCall) string {
+	if a.personaStore == nil {
+		return "人格设定不可用：内核未接入配置"
+	}
+	mode, _ := tc.Arguments["mode"].(string)
+	content, _ := tc.Arguments["content"].(string)
+	mode = strings.TrimSpace(mode)
+	restart, err := a.personaStore.SetPersona(mode, content)
+	if err != nil {
+		return fmt.Sprintf("人格设定失败：%v", err)
+	}
+	switch mode {
+	case "custom":
+		msg := "已保存自定义人格"
+		if restart {
+			msg += "；**重启 homed 后生效**（人格在启动时载入）"
+		}
+		return msg
+	case "default":
+		return "已确认使用默认人格"
+	case "later":
+		return "已记为「以后再说」，继续使用默认人格"
+	default:
+		return "已保存人格设定"
+	}
+}

internal/agent/core/persona_test.go

@@ -0,0 +1,112 @@
+package core
+
+import (
+	"strings"
+	"testing"
+
+	agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api"
+	agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io"
+)
+
+// newTestAgent 造一个最小可用的 Agent（buildToolDefs 要求 io 非 nil）。
+func newTestAgent(st PersonaStore) *Agent {
+	return &Agent{io: agentIO.NewIOManager(), personaStore: st}
+}
+
+// fakePersonaStore 记录调用并可控地报告「是否已确认」。
+type fakePersonaStore struct {
+	initialized bool
+	mode        string
+	content     string
+	calls       int
+}
+
+func (f *fakePersonaStore) PersonaInitialized() bool { return f.initialized }
+
+func (f *fakePersonaStore) SetPersona(mode, content string) (bool, error) {
+	f.calls++
+	f.mode, f.content = mode, content
+	f.initialized = true
+	return mode == "custom", nil
+}
+
+// 首启门禁：人格未确认时，**任何通道**的系统提示词都必须带上「去问用户」的指令；
+// 确认后必须消失（否则会每轮反复追问）。
+func TestPersonaOnboardingGateInSystemPrompt(t *testing.T) {
+	st := &fakePersonaStore{}
+	a := newTestAgent(st)
+
+	p := a.buildSystemPrompt("", "你好")
+	if !strings.Contains(p, "首启人格设定") || !strings.Contains(p, "persona_set") {
+		t.Fatalf("未确认人格时提示词应要求模型询问并调用 persona_set，实际缺少该段")
+	}
+
+	// 模型落地后（标记置位）不再出现
+	if out := a.executePersonaTool(agentAPI.ToolCall{Name: "persona_set",
+		Arguments: map[string]interface{}{"mode": "default"}}); !strings.Contains(out, "默认人格") {
+		t.Fatalf("persona_set(default) 回执不对: %s", out)
+	}
+	if !st.initialized {
+		t.Fatal("落库后应置位标记")
+	}
+	if p2 := a.buildSystemPrompt("", "你好"); strings.Contains(p2, "首启人格设定") {
+		t.Fatal("人格已确认后不应再要求询问")
+	}
+
+	// 未接入配置（personaStore 为 nil）时，门禁与工具都必须静默关闭
+	b := newTestAgent(nil)
+	if pb := b.buildSystemPrompt("", "你好"); strings.Contains(pb, "首启人格设定") {
+		t.Fatal("未接入配置时不应出现首启门禁")
+	}
+	if out := b.executePersonaTool(agentAPI.ToolCall{Name: "persona_set"}); !strings.Contains(out, "不可用") {
+		t.Fatalf("未接入配置时工具应回明确错误，实际: %s", out)
+	}
+}
+
+// persona_set 的三选一语义与回执。
+func TestPersonaSetToolModes(t *testing.T) {
+	cases := []struct {
+		mode, content, want string
+	}{
+		{"custom", "你是测试人格", "重启"},
+		{"default", "", "默认人格"},
+		{"later", "", "以后再说"},
+	}
+	for _, c := range cases {
+		st := &fakePersonaStore{}
+		a := newTestAgent(st)
+		out := a.executePersonaTool(agentAPI.ToolCall{Name: "persona_set",
+			Arguments: map[string]interface{}{"mode": c.mode, "content": c.content}})
+		if !strings.Contains(out, c.want) {
+			t.Errorf("mode=%s 回执应含 %q，实际: %s", c.mode, c.want, out)
+		}
+		if st.calls != 1 || st.mode != c.mode || st.content != c.content {
+			t.Errorf("mode=%s 落库参数不对: calls=%d mode=%s content=%q", c.mode, st.calls, st.mode, st.content)
+		}
+	}
+}
+
+// 工具 schema 必须在 catalog 里出现（模型才可能调用）。
+func TestPersonaSetToolDefPresent(t *testing.T) {
+	a := newTestAgent(&fakePersonaStore{})
+	found := false
+	for _, td := range a.buildToolDefs() {
+		if m, ok := td.(map[string]interface{}); ok {
+			if fn, ok := m["function"].(map[string]interface{}); ok && fn["name"] == "persona_set" {
+				found = true
+			}
+		}
+	}
+	if !found {
+		t.Fatal("buildToolDefs 未包含 persona_set")
+	}
+	// 未接入配置时不应暴露该工具
+	b := newTestAgent(nil)
+	for _, td := range b.buildToolDefs() {
+		if m, ok := td.(map[string]interface{}); ok {
+			if fn, ok := m["function"].(map[string]interface{}); ok && fn["name"] == "persona_set" {
+				t.Fatal("未接入配置时不应暴露 persona_set")
+			}
+		}
+	}
+}

internal/agent/core/status.go

@@ -198,6 +198,14 @@ func (a *Agent) GetKernelStatus() *KernelStatus {
 		trk = a.tracker
 	}
 
+	// 注意：knowledge 在 collectKernelStatus 里是**接口**参数，
+	// 而 (*knowledge.Store)(nil) 塞进接口后 `ks != nil` 仍为真 → 调 List() 直接 panic。
+	// 所以这里必须先判具体指针再进行接口赋值（healthcheck_kernel 会走到这条路径）。
+	var knowledgeLister interface{ List() []string }
+	if a.knowledge != nil {
+		knowledgeLister = a.knowledge
+	}
+
 	ks := collectKernelStatus(
 		a.startTime,
 		string(a.id),
@@ -207,15 +215,43 @@ func (a *Agent) GetKernelStatus() *KernelStatus {
 		a.io,
 		a.pluginReg,
 		a.memory,
-		a.knowledge,
+		knowledgeLister,
 		a.docStore,
 		textMem,
 		socialStore,
 		trk,
 	)
+	ks.ONNX = a.onnxStatus()
 
 	return ks
 }
 
+// onnxStatus 汇总统一多模态向量空间（ONNX 模型）的启用状态。
+//
+// 判据是 Loaded()（provider 真正打开且元数据合法），**不是**「配置里写了 provider」——
+// 后者在模型缺失 / 运行时缺失时也为真，拿它当判据就是假绿。
+func (a *Agent) onnxStatus() sdk.ONNXStatus {
+	st := sdk.ONNXStatus{Provider: a.embeddingProvider}
+	if a.multimodalSpace != nil && a.multimodalSpace.Loaded() {
+		st.Enabled = true
+		st.Dim = a.multimodalSpace.Dim()
+		st.Fingerprint = a.multimodalSpace.Fingerprint()
+		// 模态是可选能力：只有底层 provider 报出来时才带出。
+		if mr, ok := a.multimodalSpace.(interface{ Modalities() []string }); ok {
+			st.Modalities = mr.Modalities()
+		}
+		return st
+	}
+	switch {
+	case a.embeddingError != "":
+		st.Reason = "打开失败: " + a.embeddingError
+	case a.embeddingProvider == "":
+		st.Reason = "未配置统一向量空间 provider（走词嵌入/TF-IDF 回退路径）"
+	default:
+		st.Reason = "provider 未加载"
+	}
+	return st
+}
+
 var _ StatusProvider = (*Agent)(nil)
 var _ sdk.StatusAPI = (*Agent)(nil)

internal/agent/core/status_onnx_test.go

@@ -0,0 +1,103 @@
+package core
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/knowledge"
+)
+
+// statusSpace 是带模态元数据的假统一空间（ProviderAdapter 的 Modalities() 形状）。
+type statusSpace struct{ fakeSpace }
+
+func (statusSpace) Modalities() []string { return []string{"text", "image"} }
+
+// statusSpaceUnloaded 模拟「provider 建了但没加载成功」。
+type statusSpaceUnloaded struct{ fakeSpace }
+
+func (statusSpaceUnloaded) Loaded() bool { return false }
+
+// healthcheck_kernel 必须能回答两件事：内核版本号、以及**是否真的启用了 ONNX 模型**。
+//
+// 判据要点：只有 provider 真正 Loaded() 才算启用 ——「配置里写了 provider」不算，
+// 否则模型缺失/运行时缺失时会报成已启用（假绿）。
+func TestKernelStatusReportsVersionAndONNX(t *testing.T) {
+	t.Run("已启用：带出 provider/维度/指纹/模态", func(t *testing.T) {
+		a := &Agent{
+			io:                agentIO.NewIOManager(),
+			multimodalSpace:   statusSpace{},
+			embeddingProvider: "chineseclip",
+		}
+		st := a.GetKernelStatus()
+		if !st.ONNX.Enabled {
+			t.Fatal("Loaded() 为真时 onnx.enabled 必须为真")
+		}
+		if st.ONNX.Provider != "chineseclip" || st.ONNX.Dim != 2 || st.ONNX.Fingerprint != "fake-space" {
+			t.Fatalf("onnx 身份字段不对: %+v", st.ONNX)
+		}
+		if len(st.ONNX.Modalities) != 2 || st.ONNX.Reason != "" {
+			t.Fatalf("模态/原因不对: %+v", st.ONNX)
+		}
+		// 内核版本号必须随状态一起报：人格卡要求「版本以运行时快照为准」靠的就是这一项
+		if st.Build.Version == "" || st.Build.KernelName == "" {
+			t.Fatalf("build 段缺少版本/内核名: %+v", st.Build)
+		}
+	})
+
+	t.Run("打开失败：enabled=false 且给出具体原因", func(t *testing.T) {
+		a := &Agent{
+			io:                agentIO.NewIOManager(),
+			embeddingProvider: "chineseclip",
+			embeddingError:    `embedding: open provider "chineseclip": model dir missing`,
+		}
+		st := a.GetKernelStatus()
+		if st.ONNX.Enabled {
+			t.Fatal("打开失败时不能报 enabled")
+		}
+		if st.ONNX.Provider != "chineseclip" {
+			t.Fatalf("未启用时仍应带出配置的 provider: %+v", st.ONNX)
+		}
+		if !strings.Contains(st.ONNX.Reason, "model dir missing") {
+			t.Fatalf("原因应包含具体错误: %q", st.ONNX.Reason)
+		}
+	})
+
+	t.Run("未配置：说明会走回退路径", func(t *testing.T) {
+		a := &Agent{io: agentIO.NewIOManager()}
+		st := a.GetKernelStatus()
+		if st.ONNX.Enabled || st.ONNX.Reason == "" {
+			t.Fatalf("未配置时应 enabled=false 且有原因: %+v", st.ONNX)
+		}
+	})
+
+	t.Run("provider 存在但未加载", func(t *testing.T) {
+		a := &Agent{
+			io:                agentIO.NewIOManager(),
+			multimodalSpace:   statusSpaceUnloaded{},
+			embeddingProvider: "qwen3vl",
+		}
+		st := a.GetKernelStatus()
+		if st.ONNX.Enabled {
+			t.Fatal("Loaded() 为假时不能报 enabled")
+		}
+		if st.ONNX.Reason == "" {
+			t.Fatalf("应给出未加载的原因: %+v", st.ONNX)
+		}
+	})
+}
+
+// collectKernelStatus 的 knowledge 参数是**接口**类型，而 (*knowledge.Store)(nil)
+// 塞进接口后 `ks != nil` 仍为真 → 调 List() 直接 panic。
+// 这条测试钉住这个成因：一旦不再 panic，说明参数形状变了，
+// GetKernelStatus 里的 typed-nil 守卫就该同步删掉（否则它变成无意义代码）。
+func TestCollectKernelStatusTypedNilKnowledgePanics(t *testing.T) {
+	defer func() {
+		if r := recover(); r == nil {
+			t.Fatal("typed-nil 交给接口参数却未 panic：成因已变，请更新守卫与本测试")
+		}
+	}()
+	var nilStore *knowledge.Store
+	_ = collectKernelStatus(time.Now(), "a", "", 0, nil, nil, nil, nil, nilStore, nil, nil, nil, nil)
+}

internal/agent/core/toolcall.go

@@ -45,6 +45,8 @@ func (a *Agent) executeToolCall(tc agentAPI.ToolCall) (ret string) {
 
 func (a *Agent) executeToolCallInner(tc agentAPI.ToolCall) string {
 	switch {
+	case tc.Name == "persona_set":
+		return a.executePersonaTool(tc)
 	case strings.HasPrefix(tc.Name, "memory_"):
 		return a.executeMemoryTool(tc)
 	case strings.HasPrefix(tc.Name, "social_"):

internal/agent/core/tooldefs.go

@@ -89,6 +89,16 @@ func (a *Agent) buildSystemPrompt(memContext string, userInput string) string {
 		}
 	}
 
+	// 首启人格门禁（跨通道唯一闸口）：人格未确认时，要求模型主动询问用户。
+	// 系统提示词每轮重建，因此 WebUI / QQ / CLI / ACP / 邮件等所有通道都会带上它；
+	// 模型调用 persona_set（或用户在 WebUI 向导里选）落地后，标记置位，本段消失。
+	if a.personaStore != nil && !a.personaStore.PersonaInitialized() {
+		prompt += "\n\n【首启人格设定】你的**人格设定尚未确认**。请在本轮回复里先问用户一句：" +
+			"要用默认人格，还是自定义一个？拿到明确答复后**必须调用 persona_set 工具**落库：" +
+			"用户选默认 → mode=default；自定义 → mode=custom 且把内容写进 content；" +
+			"用户说以后再说 → mode=later。用户答复前不要假设已设置，也不要反复追问同一件事。"
+	}
+
 	prompt += a.buildToolCatalog()
 
 	return prompt
@@ -197,6 +207,24 @@ func (a *Agent) buildToolDefs() []interface{} {
 		}
 	}
 
+	if a.personaStore != nil {
+		tools = append(tools, map[string]interface{}{
+			"type": "function",
+			"function": map[string]interface{}{
+				"name":        "persona_set",
+				"description": "【首启人格】落地用户的人格选择并记录「已经问过」。仅在用户明确答复后调用：默认用 mode=default；自定义用 mode=custom 并把人格内容放进 content；用户说以后再说用 mode=later。",
+				"parameters": map[string]interface{}{
+					"type": "object",
+					"properties": map[string]interface{}{
+						"mode":    map[string]interface{}{"type": "string", "description": "default | custom | later"},
+						"content": map[string]interface{}{"type": "string", "description": "自定义人格内容（mode=custom 时必填）"},
+					},
+					"required": []string{"mode"},
+				},
+			},
+		})
+	}
+
 	if a.memory != nil {
 		tools = append(tools, map[string]interface{}{
 			"type": "function",

internal/config/persona.go

@@ -0,0 +1,139 @@
+package config
+
+import (
+	"fmt"
+	"strings"
+)
+
+// 人格设定的两个键：内容与「首启向导/工具已经问过」的一次性标记。
+//
+// 为什么需要标记：人格曾经只有 <dataDir>/personal/personal.md 一个来源且无人维护，
+// 里面写死的旧版本号反过来让实例自述旧版本（v1.2.0 压测发现）。
+// 现在人格是配置项（默认模板不含任何版本号），任何通道的第一次交互问一次，之后不再打扰。
+const (
+	// PersonaPromptKey 是人格设定内容（【人格设定】块的正文）。
+	PersonaPromptKey = "core.agent.personal_prompt"
+	// PersonaInitMarkerKey 是「已经问过/已确认」的一次性标记。
+	PersonaInitMarkerKey = "core.internal.persona_initialized"
+)
+
+// 三种落库方式，WebUI 首启向导与内核 persona_set 工具共用。
+const (
+	PersonaModeDefault = "default" // 使用内置默认模板
+	PersonaModeCustom  = "custom"  // 使用调用方提供的内容
+	PersonaModeLater   = "later"   // 保留当前（默认）人格，只打标记不再问
+)
+
+// PersonaKV 是人格落库所需的最小读写面：GetCore/SetCore 的签名与
+// 公开 SDK 的 SettingsAPI 一致，因此插件侧（WebUI）可直接传入；
+// 内核直连配置注册表时用 registryKV 适配（见文件末）。
+type PersonaKV interface {
+	GetCore(key string) (interface{}, error)
+	SetCore(key string, value interface{}) error
+}
+
+// PersonaInitializedKV 报告人格是否已确认（向导或工具已问过）。
+func PersonaInitializedKV(kv PersonaKV) bool {
+	if kv == nil {
+		return false
+	}
+	v, err := kv.GetCore(PersonaInitMarkerKey)
+	if err != nil {
+		return false
+	}
+	s, _ := v.(string)
+	return strings.TrimSpace(s) != ""
+}
+
+// CurrentPersonaKV 读当前人格内容；未设置时回落到内置默认模板。
+func CurrentPersonaKV(kv PersonaKV) string {
+	if kv == nil {
+		return DefaultPersonaPrompt
+	}
+	if v, err := kv.GetCore(PersonaPromptKey); err == nil {
+		if s, ok := v.(string); ok && strings.TrimSpace(s) != "" {
+			return s
+		}
+	}
+	return DefaultPersonaPrompt
+}
+
+// SetPersonaKV 落库人格并打一次性标记，返回 restartRequired。
+//
+// 生效时机：人格在 homed 启动时载入（拼成【人格设定】块进系统提示词），
+// 所以**自定义内容需重启**；default 与 later 都不改变当前已生效的人格，无需重启。
+//
+// 非法输入一律在打标记之前拒绝——否则向导会被跳过，用户再也没机会设。
+func SetPersonaKV(kv PersonaKV, mode, content string) (restartRequired bool, err error) {
+	if kv == nil {
+		return false, fmt.Errorf("persona: settings unavailable")
+	}
+	switch mode {
+	case PersonaModeDefault:
+		if err := kv.SetCore(PersonaPromptKey, DefaultPersonaPrompt); err != nil {
+			return false, err
+		}
+	case PersonaModeCustom:
+		if strings.TrimSpace(content) == "" {
+			return false, fmt.Errorf("persona: content required for custom mode")
+		}
+		if err := kv.SetCore(PersonaPromptKey, content); err != nil {
+			return false, err
+		}
+		restartRequired = true
+	case PersonaModeLater:
+		// 保持当前人格（通常是默认模板），只打标记
+	default:
+		return false, fmt.Errorf("persona: unknown mode %q (want default|custom|later)", mode)
+	}
+	if err := kv.SetCore(PersonaInitMarkerKey, "1"); err != nil {
+		return restartRequired, err
+	}
+	return restartRequired, nil
+}
+
+// RegistryPersonaStore 把配置注册表暴露成内核的 core.PersonaStore 接口
+// （结构类型：方法集匹配即可，无需 import internal/agent/core）。
+type RegistryPersonaStore struct{ Reg *ConfigRegistry }
+
+func (p RegistryPersonaStore) PersonaInitialized() bool { return PersonaInitialized(p.Reg) }
+
+func (p RegistryPersonaStore) SetPersona(mode, content string) (bool, error) {
+	return SetPersona(p.Reg, mode, content)
+}
+
+// registryKV 把内核直连的配置注册表适配成 PersonaKV。
+type registryKV struct{ reg *ConfigRegistry }
+
+func (r registryKV) GetCore(key string) (interface{}, error) {
+	v, err := r.reg.Get(key)
+	if err != nil || v == nil {
+		// 未设置的键对 PersonaKV 语义等同「没有」，不当作错误
+		if s := r.reg.GetString(key, ""); s != "" {
+			return s, nil
+		}
+		return "", nil
+	}
+	return v, nil
+}
+
+func (r registryKV) SetCore(key string, value interface{}) error {
+	s, ok := value.(string)
+	if !ok {
+		return fmt.Errorf("persona: value must be a string")
+	}
+	return r.reg.Set(key, s)
+}
+
+// PersonaInitialized 报告人格是否已确认（内核直连注册表）。
+func PersonaInitialized(reg *ConfigRegistry) bool {
+	return reg != nil && PersonaInitializedKV(registryKV{reg})
+}
+
+// SetPersona 落库人格并打一次性标记（内核直连注册表）。
+func SetPersona(reg *ConfigRegistry, mode, content string) (bool, error) {
+	if reg == nil {
+		return false, fmt.Errorf("persona: config registry unavailable")
+	}
+	return SetPersonaKV(registryKV{reg}, mode, content)
+}

internal/config/persona_kv_test.go

@@ -0,0 +1,99 @@
+package config
+
+import (
+	"strings"
+	"testing"
+)
+
+// fakeKV 是 PersonaKV 的最小实现（模拟插件侧 SettingsAPI）。
+type fakeKV struct{ m map[string]string }
+
+func (f *fakeKV) GetCore(k string) (interface{}, error) { return f.m[k], nil }
+func (f *fakeKV) SetCore(k string, v interface{}) error {
+	f.m[k] = v.(string)
+	return nil
+}
+
+// 三选一语义 + 「只问一次」标记：这是首启向导与 persona_set 工具共用的同一份实现。
+func TestSetPersonaKV(t *testing.T) {
+	t.Run("custom 写入内容并要求重启", func(t *testing.T) {
+		kv := &fakeKV{m: map[string]string{}}
+		restart, err := SetPersonaKV(kv, PersonaModeCustom, "你是测试人格")
+		if err != nil || !restart {
+			t.Fatalf("custom 应成功且需重启: restart=%v err=%v", restart, err)
+		}
+		if kv.m[PersonaPromptKey] != "你是测试人格" || kv.m[PersonaInitMarkerKey] != "1" {
+			t.Fatalf("落库不对: %+v", kv.m)
+		}
+		if !PersonaInitializedKV(kv) {
+			t.Fatal("打过标记应报告已确认")
+		}
+	})
+
+	t.Run("default 写默认模板且无需重启", func(t *testing.T) {
+		kv := &fakeKV{m: map[string]string{}}
+		restart, err := SetPersonaKV(kv, PersonaModeDefault, "")
+		if err != nil || restart {
+			t.Fatalf("default 不应需重启: restart=%v err=%v", restart, err)
+		}
+		if kv.m[PersonaPromptKey] != DefaultPersonaPrompt {
+			t.Fatal("default 应写入内置默认模板")
+		}
+	})
+
+	t.Run("later 保持人格并打标记", func(t *testing.T) {
+		kv := &fakeKV{m: map[string]string{PersonaPromptKey: "原有人格"}}
+		if _, err := SetPersonaKV(kv, PersonaModeLater, ""); err != nil {
+			t.Fatal(err)
+		}
+		if kv.m[PersonaPromptKey] != "原有人格" {
+			t.Fatal("later 不应改动人格")
+		}
+		if kv.m[PersonaInitMarkerKey] != "1" {
+			t.Fatal("later 也必须打标记（否则每次启动都问）")
+		}
+	})
+
+	t.Run("非法输入必须拒绝且不打标记", func(t *testing.T) {
+		for _, c := range []struct{ mode, content string }{
+			{PersonaModeCustom, "   "}, // 空内容
+			{"nope", ""},               // 未知 mode
+		} {
+			kv := &fakeKV{m: map[string]string{}}
+			if _, err := SetPersonaKV(kv, c.mode, c.content); err == nil {
+				t.Fatalf("mode=%q content=%q 应报错", c.mode, c.content)
+			}
+			if kv.m[PersonaInitMarkerKey] == "1" {
+				t.Fatalf("mode=%q 被拒时不得打标记（否则向导会被跳过）", c.mode)
+			}
+		}
+	})
+
+	t.Run("CurrentPersonaKV 未设置时回落默认", func(t *testing.T) {
+		kv := &fakeKV{m: map[string]string{}}
+		if got := CurrentPersonaKV(kv); got != DefaultPersonaPrompt {
+			t.Fatal("未设置应回落默认模板")
+		}
+	})
+}
+
+// 内核直连注册表的入口必须与 KV 版行为一致（同一份实现的两个薄入口）。
+func TestSetPersonaRegistryEntry(t *testing.T) {
+	dir := t.TempDir()
+	reg := NewConfigRegistry(dir + "/config.db")
+	reg.SeedDefaults(dir)
+	defer reg.Close()
+
+	if PersonaInitialized(reg) {
+		t.Fatal("全新实例不应已确认人格")
+	}
+	if _, err := SetPersona(reg, PersonaModeCustom, "内核侧人格"); err != nil {
+		t.Fatal(err)
+	}
+	if !PersonaInitialized(reg) {
+		t.Fatal("内核侧落库后应报告已确认")
+	}
+	if got := reg.GetString(PersonaPromptKey, ""); !strings.Contains(got, "内核侧人格") {
+		t.Fatalf("注册表里没有人格内容: %q", got)
+	}
+}

internal/knowledge/knowledge.go

@@ -28,17 +28,17 @@ type Knowledge struct {
 // IndexItem — 索引条目，包含向量特征和内容摘要
 type IndexItem struct {
 	Name    string             `json:"name"`
-	Preview string             `json:"preview"`          // 前 200 字摘要
+	Preview string             `json:"preview"` // 前 200 字摘要
 	Tags    []string           `json:"tags"`
-	Vector  map[string]float64 `json:"vector"`           // TF-IDF 特征向量（top-N 特征）
-	Size    int                `json:"size"`             // 内容总字节数
+	Vector  map[string]float64 `json:"vector"` // TF-IDF 特征向量（top-N 特征）
+	Size    int                `json:"size"`   // 内容总字节数
 }
 
 // TreeIndex — 树状索引节点
 type TreeIndex struct {
-	Name     string              `json:"name"`
+	Name     string                `json:"name"`
 	Children map[string]*TreeIndex `json:"children,omitempty"`
-	Items    []IndexItem         `json:"items,omitempty"` // 此节点下的知识条目（含向量）
+	Items    []IndexItem           `json:"items,omitempty"` // 此节点下的知识条目（含向量）
 }
 
 func newTreeIndex(name string) *TreeIndex {
@@ -80,11 +80,20 @@ type Store struct {
 	root   string
 	vec    *vector.Store
 	veczer *vector.TFIDFVectorizer
-	mu     sync.RWMutex
-	items  map[string]*Knowledge
+
+	// lex 是**词法路**索引（TF-IDF），与 vec（稠密路：词向量/多模态空间）相互独立。
+	//
+	// 为何要两路：词向量取平均后各向异性明显——所有文档都挤在语料均值方向附近，
+	// 真实 KB（33 条）上自检索 top-1 只有 15%、前两名平均只差 0.013，排序基本是噪声。
+	// 融合后 MRR 0.271→0.376、前两名差距 0.013→0.128（同一份数据实测），
+	// 且「词都在停用词里」的查询（稠密路给空向量）能靠词法路救回来。
+	lex *vector.Store
+
+	mu        sync.RWMutex
+	items     map[string]*Knowledge
+	summaries []string
 
 	indexPath  string
-	summaries  []string
 	vectorizer vector.Vectorizer // 可选：词嵌入向量化器，优先于 TF-IDF
 }
 
@@ -93,11 +102,20 @@ func NewStore(root string) *Store {
 		root:      root,
 		indexPath: filepath.Join(root, ".index.json"),
 		vec:       vector.NewStore(),
+		lex:       newLexicalStore(),
 		veczer:    vector.NewTFIDFVectorizer(memory.TokenizeWords),
 		items:     make(map[string]*Knowledge),
 	}
 }
 
+// newLexicalStore 造词法路存储。阈值设为 0：TF-IDF 余弦量级只有 0.0~0.2，
+// 沿用稠密路的 0.05 会把大量有效候选静默砍掉（实测 MRR 0.307→0.193）。
+func newLexicalStore() *vector.Store {
+	st := vector.NewStore()
+	st.SetMinScore(0)
+	return st
+}
+
 // SetVectorizer 设置词嵌入向量化器，优先于 TF-IDF
 func (s *Store) SetVectorizer(v vector.Vectorizer) {
 	s.vectorizer = v
@@ -110,13 +128,19 @@ func (s *Store) ReindexWithVectorizer(v vector.Vectorizer) {
 
 	log.Printf("[knowledge] reindex with vectorizer (%d items)", len(s.items))
 	s.vec = vector.NewStore()
+	s.lex = newLexicalStore()
+	// 词法路的 IDF 必须建在全语料上（否则 IDF 没意义）
+	if len(s.summaries) > 0 {
+		s.veczer.Train(s.summaries)
+	}
 	for _, k := range s.items {
-		vec := v.Vectorize(k.Name + " " + k.Content)
-		s.vec.Insert(k.Name, k.Name+": "+k.Content, vec, map[string]string{
+		text := k.Name + " " + k.Content
+		s.vec.Insert(k.Name, k.Name+": "+k.Content, v.Vectorize(text), map[string]string{
 			"name": k.Name, "path": k.Path,
 		})
+		s.lex.Insert(k.Name, k.Name+": "+k.Content, s.veczer.Vectorize(text), nil)
 	}
-	log.Printf("[knowledge] reindex with vectorizer complete (%d vectors)", s.vec.Size())
+	log.Printf("[knowledge] reindex complete (dense=%d lex=%d)", s.vec.Size(), s.lex.Size())
 }
 
 // vectorize 优先使用词嵌入向量化器，不可用时回退到 TF-IDF
@@ -144,6 +168,17 @@ func (s *Store) Start() error {
 
 func (s *Store) Stop() {}
 
+// 融合权重：稠密路（词向量）与词法路（TF-IDF）。
+// 取值由真实 KB 上的权重扫描定（rankdiag_test.go 的 KB_DIAG_SWEEP）：
+// 1.0 = 修复前的「只用稠密路」行为，作为对照基线。
+var densePathWeight = 0.5
+
+// Search 融合两路召回：稠密路（词向量/多模态空间）+ 词法路（TF-IDF）。
+//
+// 为何不能只用稠密路：词向量取平均后各向异性明显，真实 KB 上自检索 top-1 只有 15%，
+// 前两名平均只差 0.013（等于没区分度）；且全为停用词的查询会得到**空向量**，
+// 直接搜不出任何东西（"最近更新" 就撞上这个）。词法路对专名/术语/短查询强，
+// 两路各自**按查询内最大值归一化**后加权融合，排序才可信。
 func (s *Store) Search(query string, topK int) []*Knowledge {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
@@ -151,15 +186,58 @@ func (s *Store) Search(query string, topK int) []*Knowledge {
 	if topK <= 0 {
 		topK = 5
 	}
+	if s.vec.Size() == 0 && s.lex.Size() == 0 {
+		return nil
+	}
+	// 两路各自对**全部**文档打分：
+	//  - 稠密路的特征是维索引，几乎每篇都命中，"候选"就是全量；
+	//  - 词法路只召回与查询共词的文档（这正是它的长处：专名/术语）。
+	// 为何不先截候选再融合：截断后只能拿**候选内**最大值归一化，路与路之间的
+	// 相对权重就随候选集漂移——实测同一份 KB 上自检索 MRR 从 0.376 掉到 0.197。
+	// KB 规模下全量 cosine 的代价可忽略；真到数万条再上 ANN 也不迟。
+	denseHits := s.vec.SearchScored(s.vectorize(query), s.vec.Size())
+	lexHits := s.lex.SearchScored(s.veczer.Vectorize(query), s.lex.Size())
+	if len(denseHits) == 0 && len(lexHits) == 0 {
+		return nil
+	}
 
-	vec := s.vectorize(query)
-	results := s.vec.Search(vec, topK)
+	scores := make(map[string]float64, len(denseHits)+len(lexHits))
+	addPath := func(hits []vector.DocVectorHit, weight float64) {
+		max := 0.0
+		for _, h := range hits {
+			if h.Score > max {
+				max = h.Score
+			}
+		}
+		if max <= 0 {
+			return // 该路对这条查询没有信号（如空向量），全量让给另一路
+		}
+		for _, h := range hits {
+			scores[h.Doc.ID] += weight * h.Score / max
+		}
+	}
+	addPath(denseHits, densePathWeight)
+	addPath(lexHits, 1-densePathWeight)
+
+	ids := make([]string, 0, len(scores))
+	for id := range scores {
+		ids = append(ids, id)
+	}
+	sort.Slice(ids, func(i, j int) bool {
+		if scores[ids[i]] != scores[ids[j]] {
+			return scores[ids[i]] > scores[ids[j]]
+		}
+		return ids[i] < ids[j] // 分数相同时按名字定序（保证结果可重复）
+	})
 
 	var out []*Knowledge
-	for _, r := range results {
-		if k, ok := s.items[r.ID]; ok {
+	for _, id := range ids {
+		if k, ok := s.items[id]; ok {
 			out = append(out, k)
 		}
+		if len(out) >= topK {
+			break
+		}
 	}
 	return out
 }
@@ -208,17 +286,19 @@ func (s *Store) Add(name, content string) error {
 	// 是对的，只有向量数比条目数多——而检索可能因此命中已被替换掉的旧内容。
 	s.vec.Remove(id)
 
-	vec := s.vectorize(name + " " + content)
+	text := name + " " + content
+	vec := s.vectorize(text)
 	s.vec.Insert(id, name+": "+content, vec, map[string]string{
 		"name": name, "path": path,
 	})
+	// 词法路同样去重后重建这条；IDF 统计沿用现有语料（重启时 scanAll 会全量重训）
+	s.lex.Remove(id)
+	s.lex.Insert(id, name+": "+content, s.veczer.Vectorize(text), nil)
 	s.summaries = append(s.summaries, name+" "+content)
 
-	go func() {
-		if err := s.writeIndex(); err != nil {
-			log.Printf("[knowledge] write index error after adding %s: %v", name, err)
-		}
-	}()
+	if err := s.writeIndexLocked(); err != nil {
+		log.Printf("[knowledge] write index error after adding %s: %v", name, err)
+	}
 	log.Printf("[knowledge] added: %s (%d bytes)", name, len(content))
 	return nil
 }
@@ -261,11 +341,10 @@ func (s *Store) Remove(name string) error {
 	}
 	delete(s.items, id)
 	s.vec.Remove(id)
-	go func() {
-		if err := s.writeIndex(); err != nil {
-			log.Printf("[knowledge] write index error after removing %s: %v", name, err)
-		}
-	}()
+	s.lex.Remove(id)
+	if err := s.writeIndexLocked(); err != nil {
+		log.Printf("[knowledge] write index error after removing %s: %v", name, err)
+	}
 	return nil
 }
 
@@ -295,6 +374,14 @@ func (s *Store) List() []string {
 func (s *Store) BuildTree() *TreeIndex {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
+	return s.buildTreeLocked()
+}
+
+// buildTreeLocked 与 BuildTree 同义，但**不取锁**——供已持写锁的路径调用。
+// 为什么需要：writeIndex 会走 BuildTree（RLock），而 Add/Remove 持的是写锁，
+// 直接调用会死锁；此前就是因此把索引写丢进了无追踪的 goroutine 里，
+// 结果是「失败只打日志」+ 与调用方（含测试的临时目录清理）竞态。
+func (s *Store) buildTreeLocked() *TreeIndex {
 	root := newTreeIndex("root")
 	for _, k := range s.items {
 		node := root
@@ -366,7 +453,14 @@ func (s *Store) SearchTree(query string, topK int) map[string][]*Knowledge {
 
 // writeIndex 写入 .index.json 树状索引文件（含向量和摘要）
 func (s *Store) writeIndex() error {
-	tree := s.BuildTree()
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.writeIndexLocked()
+}
+
+// writeIndexLocked 与 writeIndex 同义但**不取锁**（调用方已持锁）。
+func (s *Store) writeIndexLocked() error {
+	tree := s.buildTreeLocked()
 	data, err := json.MarshalIndent(tree, "", "  ")
 	if err != nil {
 		return err
@@ -397,11 +491,13 @@ func (s *Store) scanAll() error {
 		s.veczer.Train(s.summaries)
 	}
 
+	s.lex = newLexicalStore()
 	for _, k := range s.items {
-		vec := s.vectorize(k.Name + " " + k.Content)
-		s.vec.Insert(k.Name, k.Name+": "+k.Content, vec, map[string]string{
+		text := k.Name + " " + k.Content
+		s.vec.Insert(k.Name, k.Name+": "+k.Content, s.vectorize(text), map[string]string{
 			"name": k.Name, "path": k.Path,
 		})
+		s.lex.Insert(k.Name, k.Name+": "+k.Content, s.veczer.Vectorize(text), nil)
 	}
 
 	return nil
@@ -452,5 +548,3 @@ func sanitize(name string) string {
 	name = strings.ReplaceAll(name, "\\", "_")
 	return name
 }
-
-

internal/knowledge/rankdiag_test.go

@@ -0,0 +1,154 @@
+package knowledge
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory"
+)
+
+// 知识库检索质量判据（真实数据，默认跳过）。
+//
+//	KB_DIAG=1                              → 跑并打印指标
+//	KB_DIAG=1 KB_DIAG_ASSERT=1             → 额外断言门槛（CI/回归用）
+//	KB_DIAG_ROOT / KB_DIAG_MODELS          → 覆盖数据与词向量路径
+//
+// 判据选「自检索 top-1 / MRR」的原因：不依赖人工标注问答对，且能直接量出
+// **区分度**——词向量取平均后所有文档挤在语料均值附近，前两名分差极小，
+// 排序等于噪声；这一项掉下来就说明检索坏了。
+//
+// 实测（33 条真实 KB）：
+//
+//	修复前（仅稠密路）  top-1 5/33 = 15%，MRR 0.271，平均分差 0.0133
+//	修复后（稠密+词法融合）top-1 7/33 = 21%，MRR 0.376，平均分差 0.1280
+//	门槛取 MRR ≥ 0.34 且分差 ≥ 0.10（留出余量，只挡「退化回噪声」）
+func TestRankingQualityOnRealKB(t *testing.T) {
+	if os.Getenv("KB_DIAG") == "" {
+		t.Skip("需要 KB_DIAG=1（真实 KB + 词向量文件）")
+	}
+	srcRoot := envOr("KB_DIAG_ROOT", "/home/newqqagent/knowledge")
+	models := envOr("KB_DIAG_MODELS", "/data/cc.zh.top200k.vec,/data/cc.en.top200k.vec")
+	emb := memory.NewStaticEmbedder(strings.Split(models, ",")...)
+
+	// 拷贝到临时目录跑：Start() 会重写 .index.json，不能动线上数据
+	tmp := t.TempDir()
+	entries, err := os.ReadDir(srcRoot)
+	if err != nil {
+		t.Fatalf("读取 %s: %v", srcRoot, err)
+	}
+	names := []string{}
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		src := filepath.Join(srcRoot, e.Name(), "content.md")
+		in, err := os.Open(src)
+		if err != nil {
+			continue
+		}
+		dst := filepath.Join(tmp, e.Name(), "content.md")
+		os.MkdirAll(filepath.Dir(dst), 0755)
+		out, _ := os.Create(dst)
+		io.Copy(out, in)
+		out.Close()
+		in.Close()
+		names = append(names, e.Name())
+	}
+	if len(names) == 0 {
+		t.Fatal("没有可用的知识条目")
+	}
+
+	st := NewStore(tmp)
+	st.SetVectorizer(emb)
+	if err := st.Start(); err != nil {
+		t.Fatalf("start: %v", err)
+	}
+
+	top1, mrr, missed := 0, 0.0, []string{}
+	for _, name := range names {
+		// 取全量排名：MRR 的定义用到真实名次，只取 top-2 会把 rank>2 的全都记 0
+		// （我第一版就是这么写的，把 0.376 误报成 0.197）
+		hits := st.Search(name, len(names))
+		if len(hits) == 0 {
+			missed = append(missed, name+"(无结果)")
+			continue
+		}
+		if hits[0].Name == name {
+			top1++
+		} else {
+			missed = append(missed, fmt.Sprintf("%s→%s", name, hits[0].Name))
+		}
+		for i, h := range hits {
+			if h.Name == name {
+				mrr += 1.0 / float64(i+1)
+				break
+			}
+		}
+	}
+	n := float64(len(names))
+	rate := 100 * float64(top1) / n
+	fmt.Printf("\n  === 知识库检索质量（%d 条，自检索判据）===\n", len(names))
+	fmt.Printf("  top-1 %d/%d = %.0f%%   MRR %.3f\n", top1, len(names), rate, mrr/n)
+	if len(missed) > 0 {
+		fmt.Printf("  未命中 top-1（前 10）：%v\n", firstN(missed, 10))
+	}
+	for _, q := range []string{"最近更新", "首启人格门禁", "插件怎么开发和部署", "统一多模态向量空间 ONNX", "隐私政策"} {
+		hits := st.Search(q, 2)
+		got := []string{}
+		for _, h := range hits {
+			got = append(got, h.Name)
+		}
+		fmt.Printf("  查询「%s」→ %v\n", q, got)
+	}
+
+	if os.Getenv("KB_DIAG_SWEEP") != "" {
+		fmt.Printf("\n  === 融合权重扫描（1.0 = 只用稠密路，0.0 = 只用词法路）===\n")
+		saved := densePathWeight
+		for _, w := range []float64{1.0, 0.8, 0.7, 0.5, 0.3, 0.0} {
+			densePathWeight = w
+			t1, m := 0, 0.0
+			for _, name := range names {
+				hits := st.Search(name, len(names))
+				for i, h := range hits {
+					if h.Name == name {
+						if i == 0 {
+							t1++
+						}
+						m += 1.0 / float64(i+1)
+						break
+					}
+				}
+			}
+			fmt.Printf("  权重 %.1f：top-1 %2d/%d = %3.0f%%   MRR %.3f\n",
+				w, t1, len(names), 100*float64(t1)/float64(len(names)), m/float64(len(names)))
+		}
+		densePathWeight = saved
+	}
+
+	if os.Getenv("KB_DIAG_ASSERT") != "" {
+		if mrr/n < 0.34 {
+			t.Fatalf("检索质量退化：MRR %.3f < 0.34（修复前 0.271，修复后 0.376）", mrr/n)
+		}
+		if rate < 18 {
+			t.Fatalf("检索质量退化：top-1 %.0f%% < 18%%", rate)
+		}
+	}
+}
+
+func envOr(k, def string) string {
+	if v := os.Getenv(k); v != "" {
+		return v
+	}
+	return def
+}
+
+func firstN(s []string, n int) []string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n]
+}

internal/knowledge/search_fusion_test.go

@@ -0,0 +1,176 @@
+package knowledge
+
+import (
+	"testing"
+
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/vector"
+)
+
+// fakeDense 是可控的稠密向量器：按文本查表，缺省给同一个向量。
+// 用它把「稠密路无区分度/给空向量」这类真实故障在单测里复现出来。
+type fakeDense struct {
+	byText map[string]vector.Vector
+	def    vector.Vector
+}
+
+func (f fakeDense) Vectorize(text string) vector.Vector {
+	if v, ok := f.byText[text]; ok {
+		return v
+	}
+	return f.def
+}
+
+// EmbedImage 满足 vector.Vectorizer 接口（本用例只用到文本路）。
+func (f fakeDense) EmbedImage([]byte, string) (vector.Vector, error) {
+	return f.def, nil
+}
+
+func newTestStore(t *testing.T, dense vector.Vectorizer) *Store {
+	t.Helper()
+	st := NewStore(t.TempDir())
+	if dense != nil {
+		st.SetVectorizer(dense)
+	}
+	return st
+}
+
+func mustAdd(t *testing.T, st *Store, name, content string) {
+	t.Helper()
+	if err := st.Add(name, content); err != nil {
+		t.Fatalf("add %s: %v", name, err)
+	}
+}
+
+func names(hits []*Knowledge) []string {
+	out := make([]string, len(hits))
+	for i, h := range hits {
+		out[i] = h.Name
+	}
+	return out
+}
+
+// base36 生成互不重复的短串（造独特词的量级要大，不能用 a..z 循环重复）。
+func base36(n int) string {
+	const digits = "0123456789abcdefghijklmnopqrstuvwxyz"
+	if n == 0 {
+		return "0"
+	}
+	out := ""
+	for n > 0 {
+		out = string(digits[n%36]) + out
+		n /= 36
+	}
+	return out
+}
+
+// 稠密路给**空向量**（真实场景：查询词全在停用词表里，例如"最近更新"）时，
+// 词法路必须把结果救回来——修复前这里直接返回空。
+func TestSearchLexicalRescuesEmptyDenseQuery(t *testing.T) {
+	dense := fakeDense{def: vector.Vector{"0": 1}}
+	st := newTestStore(t, dense)
+	mustAdd(t, st, "changelog_v1", "最近更新了很多东西 发布说明")
+	mustAdd(t, st, "weather_doc", "天气预报 晴转多云")
+
+	// 让"更新"的稠密向量为空（模拟停用词化）
+	st.SetVectorizer(fakeDense{
+		byText: map[string]vector.Vector{"更新": {}},
+		def:    vector.Vector{"0": 1},
+	})
+	hits := st.Search("更新", 5)
+	if len(hits) == 0 {
+		t.Fatal("稠密路给空向量时不该返回空结果（词法路应救回来）")
+	}
+	if hits[0].Name != "changelog_v1" {
+		t.Fatalf("应命中含「更新」的条目，实际: %v", names(hits))
+	}
+}
+
+// 稠密路对所有文本给**同一个向量**（真实故障：词向量平均后各向异性、区分度极低）时，
+// 排序必须由词法路决定。
+func TestSearchLexicalBreaksDenseTies(t *testing.T) {
+	same := vector.Vector{"0": 1, "1": 1}
+	st := newTestStore(t, fakeDense{def: same})
+	mustAdd(t, st, "plugin_dev_build", "插件构建与部署 hmapdev 命令")
+	mustAdd(t, st, "cangjie_manual", "仓颉编程语言知识手册")
+	mustAdd(t, st, "privacy_policy", "隐私政策")
+
+	hits := st.Search("hmapdev 构建", 3)
+	if len(hits) == 0 || hits[0].Name != "plugin_dev_build" {
+		t.Fatalf("稠密路并列时应由词法路选出 plugin_dev_build，实际: %v", names(hits))
+	}
+}
+
+// 词法路的候选中选阈值必须是 0：TF-IDF 余弦量级只有 0.0~0.2，沿用稠密路的 0.05
+// 会把有效候选静默砍掉（真实 KB 实测自检索 MRR 0.307→0.193）。
+//
+// 判据分两层，各钉一半：
+//   - **语义层**由 internal/memory/vector 的 TestSearchScoredRespectsMinScore 证明
+//     （同一候选在默认阈值下被过滤、阈值 0 时被召回）；
+//   - **接线层**在这里钉住：知识库的词法路用的就是阈值 0 的那个 store。
+//     不在这里造「低余弦夹具」的原因：分词器会丢掉纯拉丁 token、也会过滤未登录词，
+//     造出来的夹具余弦根本压不到阈值以下（我先试了两种，余弦 0.23/0.27，
+//     前提断言直接把这两版夹具否掉了）。
+func TestLexicalStoreUsesZeroMinScore(t *testing.T) {
+	st := newTestStore(t, fakeDense{def: vector.Vector{"0": 1}})
+	if got := st.lex.MinScore(); got != 0 {
+		t.Fatalf("词法路阈值必须为 0，实际 %v（沿用稠密路阈值会静默丢候选）", got)
+	}
+	if got := st.vec.MinScore(); got != vector.DefaultMinScore {
+		t.Fatalf("稠密路阈值应保持默认 %v，实际 %v", vector.DefaultMinScore, got)
+	}
+}
+
+// Add / Remove 必须同时维护两路索引：只维护一路会让被删条目继续被检索命中
+// （或新条目只在其中一路可见）。
+func TestAddRemoveKeepsBothPaths(t *testing.T) {
+	st := newTestStore(t, fakeDense{def: vector.Vector{"0": 1}})
+	mustAdd(t, st, "alpha", "alpha 独有词 alphaonly")
+	mustAdd(t, st, "beta", "beta 独有词 betaonly")
+
+	has := func(q, want string) bool {
+		for _, h := range st.Search(q, 5) {
+			if h.Name == want {
+				return true
+			}
+		}
+		return false
+	}
+	if !has("alphaonly", "alpha") {
+		t.Fatal("新增条目应可被检索到")
+	}
+	if err := st.Remove("alpha"); err != nil {
+		t.Fatalf("remove: %v", err)
+	}
+	if has("alphaonly", "alpha") {
+		t.Fatal("已删除条目仍被检索命中（两路索引有一路没清）")
+	}
+	if !has("betaonly", "beta") {
+		t.Fatal("删除其它条目不应影响 beta")
+	}
+}
+
+// 分数相同时必须按名字定序，保证结果可重复（否则同一查询两次结果可能不同）。
+func TestSearchDeterministicOnTies(t *testing.T) {
+	same := vector.Vector{"0": 1}
+	st := newTestStore(t, fakeDense{def: same})
+	for _, n := range []string{"ccc", "aaa", "bbb"} {
+		mustAdd(t, st, n, "完全一样的内容")
+	}
+	first := names(st.Search("完全一样的内容", 3))
+	for i := 0; i < 5; i++ {
+		got := names(st.Search("完全一样的内容", 3))
+		for j := range first {
+			if got[j] != first[j] {
+				t.Fatalf("结果不确定：第 %d 次 %v != 首次 %v", i, got, first)
+			}
+		}
+	}
+}
+
+// 两路都空时不能 panic，且应返回空。
+func TestSearchEmptyStore(t *testing.T) {
+	st := newTestStore(t, fakeDense{def: vector.Vector{"0": 1}})
+	if hits := st.Search("随便", 5); len(hits) != 0 {
+		t.Fatalf("空库应返回空，实际 %v", names(hits))
+	}
+}

internal/memory/vector/provider_adapter.go

@@ -65,6 +65,18 @@ func (a *ProviderAdapter) embed(input embedding.Input) ([]float64, error) {
 func (a *ProviderAdapter) Fingerprint() string { return a.info.Fingerprint }
 func (a *ProviderAdapter) Dim() int            { return a.info.Dimension }
 
+// Modalities 报告该空间支持的输入模态（text/image/...）。
+//
+// 模态是**可选能力**：MultimodalEmbedder 契约里没有它，状态查询按接口断言取用，
+// 所以这里既不改公开接口，也不影响其它实现（核心也不硬编码任何模型名）。
+func (a *ProviderAdapter) Modalities() []string {
+	out := make([]string, 0, len(a.info.Modalities))
+	for _, m := range a.info.Modalities {
+		out = append(out, string(m))
+	}
+	return out
+}
+
 func (a *ProviderAdapter) Loaded() bool {
 	a.mu.RLock()
 	defer a.mu.RUnlock()

internal/memory/vector/store.go

@@ -77,6 +77,12 @@ type Store struct {
 	docs  []DocVector
 	dim   int
 	index *InvertedIndex
+
+	// minScore 是候选分数下限。**必须按向量空间标定**：
+	// 词向量/多模态余弦通常在 0.3~0.9，而 TF-IDF 余弦只有 0.0~0.2 ——
+	// 用同一个阈值会把词法路的大量有效候选静默砍掉
+	// （实测：知识库自检索 MRR 0.307 → 0.193 就是这么掉的）。
+	minScore float64
 }
 
 type DocVector struct {
@@ -86,9 +92,27 @@ type DocVector struct {
 	Meta   map[string]string
 }
 
+// DefaultMinScore 是默认候选中选阈值（沿用历史行为）。
+const DefaultMinScore = 0.05
+
+// MinScore 返回当前候选中选阈值（供接线处自证用的是哪个阈值）。
+func (s *Store) MinScore() float64 {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.minScore
+}
+
+// SetMinScore 调整候选中选阈值（按向量空间标定，见 minScore 字段注释）。
+func (s *Store) SetMinScore(v float64) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.minScore = v
+}
+
 func NewStore() *Store {
 	return &Store{
-		index: NewInvertedIndex(),
+		index:    NewInvertedIndex(),
+		minScore: DefaultMinScore,
 	}
 }
 
@@ -160,7 +184,7 @@ func (s *Store) SearchScored(query Vector, topK int) []DocVectorHit {
 		for _, d := range s.docs {
 			if d.ID == id {
 				score := CosineSimilarity(query, d.Vector)
-				if score > 0.05 {
+				if score > s.minScore {
 					results = append(results, scored{d, score})
 				}
 				break

internal/memory/vector/store_test.go

@@ -210,3 +210,29 @@ func BenchmarkExtractNGrams(b *testing.B) {
 		extractNGrams(text, 2)
 	}
 }
+
+// 候选中选阈值必须**按向量空间标定**：词向量/多模态余弦通常在 0.3~0.9，
+// 而 TF-IDF 余弦只有 0.0~0.2。用同一个阈值会把词法路的有效候选静默砍掉
+// （知识库自检索 MRR 0.307→0.193 就是这么掉的，且当时看不出任何报错）。
+func TestSearchScoredRespectsMinScore(t *testing.T) {
+	// 构造一个低余弦候选：共享特征 "a"，但两个向量几乎正交 → cosine ≈ 0.02
+	st := NewStore()
+	st.Insert("doc", "", Vector{"a": 1, "b": 1}, nil) // |doc| = √2
+	query := Vector{"a": 0.02, "c": 100}              // 与 doc 的点积 0.02
+
+	hits := st.SearchScored(query, 10)
+	for _, h := range hits {
+		if h.Score < DefaultMinScore {
+			t.Fatalf("默认阈值 %.2f 不该返回 %.5f 的候选", DefaultMinScore, h.Score)
+		}
+	}
+	if len(hits) != 0 {
+		t.Fatalf("该查询在默认阈值下应被过滤，实际返回 %d 条", len(hits))
+	}
+
+	st.SetMinScore(0)
+	hits = st.SearchScored(query, 10)
+	if len(hits) != 1 || hits[0].Doc.ID != "doc" {
+		t.Fatalf("阈值设为 0 后应召回低余弦候选，实际 %+v", hits)
+	}
+}

internal/meta/meta.go

@@ -24,7 +24,7 @@ var (
 	//
 	// ❗main 上此值始终是**下一个未发布中版本**，不随 patch 发布变动
 	//（见 docs/git-branching.md §2.1）；已发布的版本号看对应的 release/vX.Y.x 与 tag。
-	Version = "1.2.0"
+	Version = "1.2.2"
 
 	// Commit 是构建时的 Git commit hash。
 	Commit = "unknown"

internal/plugins/healthcheck/plugin.go

@@ -240,7 +240,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 		p.selfToolNames["healthcheck_kernel"] = true
 		s.RegisterTool("healthcheck_kernel", sdk.ToolDef{
 			Name:        "healthcheck_kernel",
-			Description: "查询 Agent 内核运行状态快照，包括插件/工具/记忆/知识库/LLM Provider/运行时等各子系统信息。Agent 可通过此工具自主监测内核健康。",
+			Description: "查询 Agent 内核运行状态快照，包括**内核版本号与构建身份**（build.version / commit / build_time）、**统一多模态向量空间（ONNX 模型）是否启用**（onnx.enabled，未启用时给出原因）、插件/工具/记忆/知识库/LLM Provider/运行时等各子系统信息。Agent 可通过此工具自主监测内核健康。",
 			Parameters: map[string]interface{}{
 				"type":       "object",
 				"properties": map[string]interface{}{},

internal/plugins/real_plugin_smoke_test.go

@@ -3,6 +3,7 @@
 package plugins
 
 import (
+	"bytes"
 	"fmt"
 	"os"
 	"os/exec"
@@ -26,6 +27,47 @@ import (
 // 前置：插件需已用新版 hmapdev 重编（scripts/rebuild-plugins.sh）。
 // 未重编时测试 skip 而非 fail——CI 上不强制要求先跑重编脚本。
 
+// hostExecutableKind 按魔数判断产物是不是**本机**可执行文件，返回可读格式名。
+//
+// 为何需要：以前只按文件名找候选（plugin.bin_<os>_<arch> → plugin.bin），拿到
+// darwin/windows 产物就直接 exec，报的是 "exec format error"——看起来像插件坏了，
+// 实际上只是**开发环境里的产物平台不对**。本轮就踩了：跨平台示例构建把
+// build/plugin.bin 覆盖成 Mach-O arm64，internal/plugins 6 个测试全红，排查半小时。
+func hostExecutableKind(path string) (string, bool) {
+	f, err := os.Open(path)
+	if err != nil {
+		return "无法读取", false
+	}
+	defer f.Close()
+	head := make([]byte, 4)
+	n, _ := f.Read(head)
+	if n < 2 {
+		return "文件过短", false
+	}
+	switch runtime.GOOS {
+	case "linux":
+		if n >= 4 && head[0] == 0x7f && head[1] == 'E' && head[2] == 'L' && head[3] == 'F' {
+			return "ELF（本机）", true
+		}
+		if n >= 4 && head[0] == 0xcf && head[1] == 0xfa && head[2] == 0xed && head[3] == 0xfe {
+			return "Mach-O 64 little-endian（macOS，不是本机）", false
+		}
+		if n >= 2 && head[0] == 'M' && head[1] == 'Z' {
+			return "PE（Windows，不是本机）", false
+		}
+		return "未知格式（不是本机可执行文件）", false
+	case "darwin":
+		for _, m := range [][]byte{{0xcf, 0xfa, 0xed, 0xfe}, {0xca, 0xfe, 0xba, 0xbe}} {
+			if n >= 4 && bytes.Equal(head, m) {
+				return "Mach-O（本机）", true
+			}
+		}
+		return "不是本机可执行文件", false
+	default:
+		return "未知平台（默认放行）", true
+	}
+}
+
 // realPluginDir 返回某个 example 插件的 linux 产物路径。
 func realPluginBinary(t *testing.T, name string) string {
 	t.Helper()
@@ -39,9 +81,14 @@ func realPluginBinary(t *testing.T, name string) string {
 		filepath.Join(root, "build", "plugin.bin"),
 	}
 	for _, c := range candidates {
-		if st, err := os.Stat(c); err == nil && !st.IsDir() {
-			return c
+		if st, err := os.Stat(c); err != nil || st.IsDir() {
+			continue
 		}
+		if kind, ok := hostExecutableKind(c); !ok {
+			t.Skipf("插件 %s 的产物 %s 不是本机可执行格式（%s）；重建：cd %s && hmapdev build --target %s/%s --no-bundle",
+				name, c, kind, root, runtime.GOOS, runtime.GOARCH)
+		}
+		return c
 	}
 	t.Skipf("插件 %s 未重编（先跑 scripts/rebuild-plugins.sh）", name)
 	return ""

internal/plugins/webui/handler.go

@@ -981,12 +981,7 @@ func (h *Handler) handleKernel(w http.ResponseWriter, r *http.Request) {
 // 为什么需要向导：人格曾经只有 <dataDir>/personal/personal.md 一个来源且无人维护，
 // 里面写死的旧版本号反过来让实例自述旧版本（v1.2.0 压测发现）。
 // 现在人格是配置项（默认模板不含任何版本号），首启问一次，之后不再打扰。
-const (
-	personaPromptKey  = "core.agent.personal_prompt"
-	personaInitMarker = "core.internal.persona_initialized"
-)
-
-// handlePersona 是首启人格向导的后端。
+// handlePersona 是首启人格向导的后端（与内核 persona_set 工具共用 internal/config 的实现）。
 //
 //	GET  → {initialized, current_prompt, file_override}
 //	POST → {"mode":"default"|"custom"|"later","content":"..."}
@@ -995,6 +990,9 @@ const (
 // 生效时机：人格在 homed 启动时载入（以【人格设定】块拼进系统提示词），
 // 所以**自定义内容需重启生效**；选「默认」或「稍后」（保持当前默认）无需重启。
 // 不回答就是「稍后」：保留默认并打标记，不阻塞任何流程。
+//
+// 跨通道：这里只是 WebUI 侧的入口；任何通道的消息到来时，内核都会检查同一枚标记，
+// 未确认则在提示词里要求模型主动询问（见 internal/agent/core 的首启门禁）。
 func (h *Handler) handlePersona(w http.ResponseWriter, r *http.Request) {
 	if h.settings == nil {
 		writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "settings not available"})
@@ -1002,24 +1000,9 @@ func (h *Handler) handlePersona(w http.ResponseWriter, r *http.Request) {
 	}
 	switch r.Method {
 	case http.MethodGet:
-		initialized := false
-		if v, err := h.settings.GetCore(personaInitMarker); err == nil {
-			if s, ok := v.(string); ok && strings.TrimSpace(s) != "" {
-				initialized = true
-			}
-		}
-		cur := ""
-		if v, err := h.settings.GetCore(personaPromptKey); err == nil {
-			if s, ok := v.(string); ok {
-				cur = s
-			}
-		}
-		if cur == "" {
-			cur = internalConfig.DefaultPersonaPrompt
-		}
 		writeJSON(w, http.StatusOK, map[string]interface{}{
-			"initialized":    initialized,
-			"current_prompt": cur,
+			"initialized":    internalConfig.PersonaInitializedKV(h.settings),
+			"current_prompt": internalConfig.CurrentPersonaKV(h.settings),
 			"file_override":  h.personaFileExists(),
 		})
 	case http.MethodPost:
@@ -1031,31 +1014,14 @@ func (h *Handler) handlePersona(w http.ResponseWriter, r *http.Request) {
 			writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid request"})
 			return
 		}
-		restart := false
-		switch req.Mode {
-		case "default":
-			if err := h.settings.SetCore(personaPromptKey, internalConfig.DefaultPersonaPrompt); err != nil {
-				writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
-				return
+		restart, err := internalConfig.SetPersonaKV(h.settings, req.Mode, req.Content)
+		if err != nil {
+			// 非法 mode / 空内容 → 400；落库失败 → 500。两者都不打标记。
+			code := http.StatusInternalServerError
+			if strings.Contains(err.Error(), "unknown mode") || strings.Contains(err.Error(), "content required") {
+				code = http.StatusBadRequest
 			}
-		case "custom":
-			if strings.TrimSpace(req.Content) == "" {
-				writeJSON(w, http.StatusBadRequest, map[string]string{"error": "content required for custom mode"})
-				return
-			}
-			if err := h.settings.SetCore(personaPromptKey, req.Content); err != nil {
-				writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
-				return
-			}
-			restart = true // 人格在启动时载入
-		case "later":
-			// 保持当前（默认）人格，只打标记，不再问
-		default:
-			writeJSON(w, http.StatusBadRequest, map[string]string{"error": "unknown mode"})
-			return
-		}
-		if err := h.settings.SetCore(personaInitMarker, "1"); err != nil {
-			writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
+			writeJSON(w, code, map[string]string{"error": err.Error()})
 			return
 		}
 		writeJSON(w, http.StatusOK, map[string]interface{}{

internal/plugins/webui/handler_persona_test.go

@@ -69,10 +69,10 @@ func TestPersonaWizardFlow(t *testing.T) {
 	if w.Code != http.StatusOK {
 		t.Fatalf("later 状态码 %d: %s", w.Code, w.Body.String())
 	}
-	if v := cfgReg.GetString(personaInitMarker, ""); v == "" {
+	if v := cfgReg.GetString(internalConfig.PersonaInitMarkerKey, ""); v == "" {
 		t.Fatal("later 也必须打一次性标记（否则每次启动都问）")
 	}
-	if v := cfgReg.GetString(personaPromptKey, ""); v != internalConfig.DefaultPersonaPrompt {
+	if v := cfgReg.GetString(internalConfig.PersonaPromptKey, ""); v != internalConfig.DefaultPersonaPrompt {
 		t.Fatalf("later 不应改动人格，实际 %q", v)
 	}
 
@@ -97,7 +97,7 @@ func TestPersonaWizardFlow(t *testing.T) {
 	if !pr.RestartRequired {
 		t.Fatal("自定义人格应提示需要重启才生效")
 	}
-	if v := cfgReg2.GetString(personaPromptKey, ""); v != "你是测试人格" {
+	if v := cfgReg2.GetString(internalConfig.PersonaPromptKey, ""); v != "你是测试人格" {
 		t.Fatalf("自定义内容未写库: %q", v)
 	}
 
@@ -111,12 +111,12 @@ func TestPersonaWizardFlow(t *testing.T) {
 		t.Fatalf("未知 mode 应 400，实际 %d", w.Code)
 	}
 	// 7. 被拒的请求不得打标记（否则向导会被跳过）
-	if v := cfgReg2.GetString(personaInitMarker, ""); v == "" {
+	if v := cfgReg2.GetString(internalConfig.PersonaInitMarkerKey, ""); v == "" {
 		t.Fatal("前置条件：第 4 步已打标记")
 	}
 	h4, cfgReg4 := newPersonaHandler(t)
 	_ = doPersona(t, h4, http.MethodPost, `{"mode":"nope"}`)
-	if v := cfgReg4.GetString(personaInitMarker, ""); v != "" {
+	if v := cfgReg4.GetString(internalConfig.PersonaInitMarkerKey, ""); v != "" {
 		t.Fatal("被拒的请求不应打标记")
 	}
 }

internal/sdk/status.go

@@ -38,9 +38,29 @@ type KernelStatus struct {
 
 	Runtime RuntimeStatus `json:"runtime"`
 
+	// ONNX 报告统一多模态向量空间（ONNX 模型）是否**真的在用**。
+	//
+	// 为何单列：内核的向量能力是三层降级（统一多模态空间 → 词嵌入 → TF-IDF），
+	// 只报「向量可用/不可用」分不清「ONNX 模型已加载」与「退回了纯文本路径」。
+	// 模型缺失 / 运行时缺失 / provider 打开失败时这里是 enabled=false + reason。
+	ONNX ONNXStatus `json:"onnx"`
+
 	Tracker TrackerStatus `json:"tracker"`
 }
 
+// ONNXStatus 是统一多模态向量空间（ONNX 模型）的启用状态与身份。
+type ONNXStatus struct {
+	// Enabled 是 provider 真正打开且元数据合法（不是「配置里写了 provider」）。
+	Enabled bool `json:"enabled"`
+	// Provider 是配置指定的 provider 名（如 chineseclip / qwen3vl / http）。
+	Provider    string   `json:"provider,omitempty"`
+	Dim         int      `json:"dim,omitempty"`
+	Fingerprint string   `json:"fingerprint,omitempty"`
+	Modalities  []string `json:"modalities,omitempty"`
+	// Reason 是未启用时的原因（未配置 / 打开失败的具体错误 / 其它）。
+	Reason string `json:"reason,omitempty"`
+}
+
 type PluginInfo struct {
 	Name   string `json:"name"`
 	Loaded bool   `json:"loaded"`