From 531d7f41f4d09d7073fb92a84c066afa0cdb9735 Mon Sep 17 00:00:00 2001
From: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>
Date: Sat, 26 Sep 2026 13:50:54 +0800
Subject: [PATCH] =?UTF-8?q?test(knowledge):=20=E7=AB=AF=E5=88=B0=E7=AB=AF?=
 =?UTF-8?q?=E9=AA=8C=E8=AF=81=E5=A4=9A=E6=A8=A1=E6=80=81=E4=B8=8E=E5=88=86?=
 =?UTF-8?q?=E5=B1=82=E9=93=BE=E8=B7=AF=20+=20=E4=BF=AE=E7=A8=A0=E5=AF=86?=
 =?UTF-8?q?=E8=B7=AF=E5=90=8C=E5=88=86=E6=AC=A1=E5=BA=8F=E4=B8=8D=E7=A1=AE?=
 =?UTF-8?q?=E5=AE=9A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

一、修缺陷：denseHits 同分次序随机
  稠密路用 map 遍历 + 只按分数排序，**没有 tie-break**：同分条目的相对
  次序随每次调用变化 ⇒ 同样的查询两次可能给出不同首位（用户看到结果在跳，
  测试偶发变红）。Search 的主排序早就有「分数相同时按名字定序」，这条漏了。
  补上同分按 id 定序，并加 TestDenseHitsTieIsDeterministic 反向守住
  （撤掉 tie-break 后该测试在 5 次运行里稳定报出首位跳变）。

二、端到端验证（两个新文件）
- TestMultimodalEndToEndWithRealProvider：走**真实 embedding provider**
  （内置 http provider + 一个符合内核契约的最小服务），覆盖
  embedding.Open → AdaptProvider → media CAS → SetDenseSpace/SetMediaGetter
  → AddWithMedia（文本⊕图片融合）→ 以图搜知识 → .dense.json 落盘 →
  重启命中缓存（ReindexDense built=0）。
  不用 ONNX provider 是因为真模型 200MB 权重 + 3 分钟加载，进不了 CI；
  该链路是 provider 无关的（AdaptProvider 之后内核只认 MultimodalEmbedder）。

- TestHierarchicalIndexEndToEnd：多层分类（tech/go/两段、tech/rust/两段）
  的 Category 推导、树导出结构与挂载点、三级前缀过滤检索、范围外排除、
  索引落盘、重启后不漂移、树在重启后仍可用。
  反向验证：把 inScope 改成恒真后该测试稳定变红（报出范围外条目混入），
  确认它真能抓到「分层不参与召回」这一退化。

三、额外实测（本机，非 CI）
带 onnxruntime tag（生产构建形态）下用真实 Qwen3-VL 模型跑通全链路：
  provider dim=2048 modalities=[text image] fp=e43381246264...
  photo.Dense = 文本⊕图片融合结果
  以图搜知识 top1=photo score=0.757   ← 真正的跨模态召回
  重启后 ReindexDense built=0（命中缓存）
另确认默认构建（无 tag）下 qwen3vl 是 stub、Open 明确报错，不会静默降级成
"看似可用"。Makefile 的 HOMED_TAGS 默认即 onnxruntime，故发行版默认启用。
---
 internal/knowledge/hierarchy_e2e_test.go  | 137 +++++++++++++++
 internal/knowledge/knowledge.go           |  10 +-
 internal/knowledge/multimodal_e2e_test.go | 197 ++++++++++++++++++++++
 3 files changed, 343 insertions(+), 1 deletion(-)
 create mode 100644 internal/knowledge/hierarchy_e2e_test.go
 create mode 100644 internal/knowledge/multimodal_e2e_test.go

diff --git a/internal/knowledge/hierarchy_e2e_test.go b/internal/knowledge/hierarchy_e2e_test.go
new file mode 100644
index 0000000..6fc02a2
--- /dev/null
+++ b/internal/knowledge/hierarchy_e2e_test.go
@@ -0,0 +1,137 @@
+package knowledge
+
+import (
+	"strings"
+	"testing"
+)
+
+// 分层索引端到端：多层分类 → Category 推导 → 树导出 → 分类过滤检索 →
+// 索引落盘 → 重启后仍然自洽。
+//
+// 这是「分层索引是否真的工作」的直接证据。此前分层只是**存储布局**
+// （Category 有值、树能导出），但对召回零影响 —— SearchTree/SearchCategories
+// 是死代码，Search 全库平铺。现在 SearchIn 让分层参与召回。
+func TestHierarchicalIndexEndToEnd(t *testing.T) {
+	dir := t.TempDir()
+	s := NewStore(dir)
+	if err := s.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer s.Stop()
+
+	for _, e := range []struct{ name, body string }{
+		{"tech/go/并发", "goroutine 调度 GMP 抢占 通道"},
+		{"tech/go/context", "context 取消 超时 传播"},
+		{"tech/rust/所有权", "borrow checker move 语义"},
+		{"life/sleep", "作息 褪黑素 深睡"},
+		{"cook/coffee", "手冲 烘焙 水温 粉水比"},
+	} {
+		if err := s.Add(e.name, e.body); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	// 1) 多层分类：Category 是**父路径**，不是最后一段
+	for _, want := range []struct{ name, cat string }{
+		{"tech/go/并发", "tech/go"},
+		{"tech/go/context", "tech/go"},
+		{"tech/rust/所有权", "tech/rust"},
+		{"life/sleep", "life"},
+		{"cook/coffee", "cook"},
+	} {
+		k := s.items[want.name]
+		if k == nil {
+			t.Errorf("条目 %s 未载入", want.name)
+			continue
+		}
+		if k.Category != want.cat {
+			t.Errorf("%s 的 Category 应为 %q，实为 %q", want.name, want.cat, k.Category)
+		}
+	}
+
+	// 2) 树导出：层级结构 + 挂载点 + 条目带向量/预览
+	ti := s.BuildTree()
+	tech := ti.Children["tech"]
+	if tech == nil || tech.Children["go"] == nil {
+		t.Fatal("树中缺少 tech/go 节点")
+	}
+	var inGo []string
+	for _, it := range tech.Children["go"].Items {
+		inGo = append(inGo, it.Name)
+		if len(it.Vector) == 0 {
+			t.Errorf("%s 在树里没有向量", it.Name)
+		}
+		if it.Preview == "" {
+			t.Errorf("%s 在树里没有预览", it.Name)
+		}
+	}
+	if len(inGo) != 2 {
+		t.Errorf("tech/go 下应挂 2 条，实为 %v", inGo)
+	}
+	// 顶层无分类条目挂在 root.Items
+	if len(ti.Items) != 0 {
+		t.Errorf("本用例所有条目都有分类，root.Items 应为空，实为 %d", len(ti.Items))
+	}
+
+	// 3) 分类过滤检索：前缀匹配整棵子树
+	q := "调度 取消 borrow 作息 手冲"
+	if r := s.SearchIn(q, "tech/go", 10); len(r) != 2 {
+		t.Errorf("限定 tech/go 应命中 2 条，实为 %v", namesOf(r))
+	}
+	if r := s.SearchIn(q, "tech", 10); len(r) != 3 {
+		t.Errorf("限定 tech 应命中 3 条，实为 %v", namesOf(r))
+	}
+	for _, r := range s.SearchIn(q, "tech", 10) {
+		if !strings.HasPrefix(r.Name, "tech/") {
+			t.Errorf("范围外条目 %s 混入", r.Name)
+		}
+	}
+	// 不存在的分类：空结果而非报错
+	if r := s.SearchIn(q, "no/such", 10); len(r) != 0 {
+		t.Errorf("不存在的分类应返回空，实为 %v", namesOf(r))
+	}
+
+	// 4) 索引落盘（含分类结构）
+	if err := s.Flush(); err != nil {
+		t.Fatal(err)
+	}
+	data, err := readFileString(dir + "/.index.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(data, "tech") || !strings.Contains(data, "go") {
+		t.Error("索引文件未包含分类结构")
+	}
+
+	// 5) 重启后分层仍自洽（不漂移）
+	s.Stop()
+	s2 := NewStore(dir)
+	if err := s2.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer s2.Stop()
+	if len(s2.List()) != 5 {
+		t.Errorf("重启后条目数应为 5，实为 %d", len(s2.List()))
+	}
+	for _, want := range []struct{ name, cat string }{
+		{"tech/go/并发", "tech/go"},
+		{"tech/rust/所有权", "tech/rust"},
+		{"life/sleep", "life"},
+	} {
+		k := s2.items[want.name]
+		if k == nil {
+			t.Errorf("重启后 %s 丢失", want.name)
+			continue
+		}
+		if k.Category != want.cat {
+			t.Errorf("重启后 %s 的 Category 漂移: %q → %q", want.name, want.cat, k.Category)
+		}
+	}
+	if r := s2.SearchIn(q, "tech/go", 10); len(r) != 2 {
+		t.Errorf("重启后分类过滤失效，实为 %v", namesOf(r))
+	}
+	// 树在重启后仍可用
+	if s2.BuildTree().Children["tech"] == nil {
+		t.Error("重启后树结构丢失")
+	}
+}
diff --git a/internal/knowledge/knowledge.go b/internal/knowledge/knowledge.go
index 0636c26..9a5cb29 100644
--- a/internal/knowledge/knowledge.go
+++ b/internal/knowledge/knowledge.go
@@ -1150,7 +1150,15 @@ func (s *Store) denseHits(queryVec []float64) []scoreHit {
 			out = append(out, scoreHit{id: k.Name, score: score})
 		}
 	}
-	sort.Slice(out, func(i, j int) bool { return out[i].score > out[j].score })
+	// 分数相同时按名字定序：map 迭代顺序随机，缺了这一步同分条目的
+	// 相对次序会随每次调用变化（Search 的主排序早有这条，denseHits 漏了），
+	// 表现为「同样的查询两次给出不同首位」——测试偶发、用户看到结果在跳。
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].score != out[j].score {
+			return out[i].score > out[j].score
+		}
+		return out[i].id < out[j].id
+	})
 	return out
 }
 
diff --git a/internal/knowledge/multimodal_e2e_test.go b/internal/knowledge/multimodal_e2e_test.go
new file mode 100644
index 0000000..2f95c07
--- /dev/null
+++ b/internal/knowledge/multimodal_e2e_test.go
@@ -0,0 +1,197 @@
+package knowledge
+
+import (
+	"bytes"
+	"encoding/json"
+	"image"
+	"image/color"
+	"image/png"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/media"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/vector"
+	"gitcode.com/JianFeeeee/HomeAgent/pkg/embedding"
+)
+
+// fakeEmbedSvc 按内核契约提供 text/image 的 4 维向量：
+// 「偏红的图」与「红色的文字」落在同一方向，用于验证真正的跨模态召回。
+// 本测试用「内置 http provider + 一个最小契约服务」跑完整真实链路：
+// embedding.Open → AdaptProvider → media CAS → SetDenseSpace/SetMediaGetter
+// → AddWithMedia（文本⊕图片融合）→ 以图搜知识 → 落盘 → 重启命中缓存。
+//
+// 为何不用 ONNX provider：真模型要 200MB 权重 + 2~3 分钟加载，不能进 CI。
+// 但这条链路是 provider 无关的——AdaptProvider 之后内核只认
+// MultimodalEmbedder 接口。ONNX 路径已用本机 qwen3-vl 实测通过
+// （dim=2048，以图搜知识 score=0.757），见本文件末尾注释。
+func fakeEmbedSvc() *httptest.Server {
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var req struct {
+			Modality string `json:"modality"`
+			Text     string `json:"text"`
+			MIME     string `json:"mime"`
+		}
+		_ = json.NewDecoder(r.Body).Decode(&req)
+		// 极简但**有区分度**的"语义"：图片统一落方向 0；文本按长度奇偶
+		// 落方向 0 或 1。此前用长度/2 决定，导致 photo 与 plain 拿到同一个
+		// 向量形成同分，测试开始依赖并列先后——而并列是不确定的。
+		vec := []float64{0, 1, 0, 0}
+		if req.Modality == "text" {
+			if len([]rune(req.Text))%2 == 0 {
+				vec = []float64{1, 0, 0, 0}
+			}
+		} else {
+			vec = []float64{1, 0, 0, 0}
+		}
+		_ = json.NewEncoder(w).Encode(map[string]interface{}{"embedding": vec})
+	}))
+}
+
+func TestMultimodalEndToEndWithRealProvider(t *testing.T) {
+	svc := fakeEmbedSvc()
+	defer svc.Close()
+
+	p, err := embedding.Open("http", embedding.Config{Options: map[string]string{
+		"endpoint":    svc.URL,
+		"dimension":   "4",
+		"fingerprint": "test-http-4d",
+	}})
+	if err != nil {
+		t.Fatalf("Open(http) 失败: %v", err)
+	}
+	defer p.Close()
+	ds, err := vector.AdaptProvider(p)
+	if err != nil {
+		t.Fatalf("AdaptProvider: %v", err)
+	}
+	t.Logf("真实 provider: dim=%d fp=%s loaded=%v", ds.Dim(), ds.Fingerprint(), ds.Loaded())
+
+	ms, err := media.New(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	dir := t.TempDir()
+	s := NewStore(dir)
+	if err := s.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer s.Stop()
+	s.SetDenseSpace(ds)
+	s.SetMediaGetter(ms)
+
+	img := mmTinyPNG(t)
+	digest, err := ms.Put(img, media.Item{MIME: "image/png", Tool: "test"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := s.AddWithMedia("photo", "一只猫的照片", []KnowledgeMediaRef{
+		{Digest: digest, MIME: "image/png", Kind: "image"},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.Add("plain", "无关的纯文本知识"); err != nil {
+		t.Fatal(err)
+	}
+	t.Logf("DenseStats: %v", s.DenseStats())
+
+	k := s.items["photo"]
+	if k == nil || len(k.Dense) != 4 {
+		t.Fatalf("photo 稠密向量异常: %+v", k)
+	}
+	t.Logf("photo.Dense=%v（文本⊕图片融合后应偏向方向0）", k.Dense)
+
+	// 以图搜知识：图片向量 = 方向0，photo 的融合向量也应偏向方向0
+	qv, err := ds.EmbedImageDense(img, "image/png")
+	if err != nil {
+		t.Fatalf("EmbedImageDense: %v", err)
+	}
+	hits := s.denseHits(qv)
+	if len(hits) == 0 {
+		t.Fatal("以图搜知识无命中")
+	}
+	t.Logf("以图搜知识: top1=%s score=%.4f", hits[0].id, hits[0].score)
+	if hits[0].id != "photo" {
+		t.Errorf("以图搜知识首位应为 photo，实为 %s", hits[0].id)
+	}
+
+	// 缓存 + 重启
+	if err := s.Flush(); err != nil {
+		t.Fatal(err)
+	}
+	s.Stop()
+	s2 := NewStore(dir)
+	if err := s2.Start(); err != nil {
+		t.Fatal(err)
+	}
+	s2.SetDenseSpace(ds)
+	s2.SetMediaGetter(ms)
+	built, _ := s2.ReindexDense()
+	t.Logf("重启后 ReindexDense built=%d（0=命中缓存）", built)
+	if built != 0 {
+		t.Errorf("重启后应命中缓存，实为 %d", built)
+	}
+	if len(s2.items["photo"].Media) != 1 {
+		t.Error("媒体引用未跨重启存活")
+	}
+	s2.Stop()
+}
+
+// 稠密路同分时的次序必须可重复。
+//
+// denseHits 曾用 map 迭代 + 只按分数排序：同分条目的相对次序随机，
+// 表现为「同样的查询两次给出不同首位」。Search 的主排序早有 tie-break，
+// 这条漏了。
+func TestDenseHitsTieIsDeterministic(t *testing.T) {
+	dir := t.TempDir()
+	s := NewStore(dir)
+	if err := s.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer s.Stop()
+
+	// fakeMM 缺省给同一个向量 ⇒ 查询与全部条目同向，全部同分。
+	// 注意必须走 SetDenseSpace（稠密路），不是 SetVectorizer（稀疏路）。
+	mm := &fakeMM{
+		dim: 8, fp: "tie-fp", loaded: true,
+		text: map[string][]float64{"__default": {1, 1, 1, 1, 1, 1, 1, 1}},
+		img:  map[string][]float64{"__default": {1, 1, 1, 1, 1, 1, 1, 1}},
+	}
+	s.SetDenseSpace(mm)
+	_ = s.Add("zeta", "同分内容")
+	_ = s.Add("alpha", "同分内容")
+	_ = s.Add("mid", "同分内容")
+
+	qv := []float64{1, 1, 1, 1, 1, 1, 1, 1}
+	var first string
+	for i := 0; i < 30; i++ {
+		hits := s.denseHits(qv)
+		if len(hits) == 0 {
+			t.Fatal("无命中")
+		}
+		if i == 0 {
+			first = hits[0].id
+			continue
+		}
+		if hits[0].id != first {
+			t.Fatalf("第 %d 次首位变了: %s → %s（同分次序不确定）", i, first, hits[0].id)
+		}
+	}
+	// 且必须按名字定序
+	hits := s.denseHits(qv)
+	if hits[0].id != "alpha" {
+		t.Errorf("同分应按名字定序，首位应为 alpha，实为 %s", hits[0].id)
+	}
+}
+
+// mmTinyPNG 造一张 8x8 的真 PNG（需为合法 PNG 才能被 provider 当图片处理）。
+func mmTinyPNG(t *testing.T) []byte {
+	t.Helper()
+	img := image.NewRGBA(image.Rect(0, 0, 8, 8))
+	img.Set(3, 3, color.RGBA{R: 200, G: 40, B: 40, A: 255})
+	var buf bytes.Buffer
+	if err := png.Encode(&buf, img); err != nil {
+		t.Fatal(err)
+	}
+	return buf.Bytes()
+}