refactor(memory)!: 块 union 化，彻底淘汰 CAS 第一阶段（生产代码）

块自带负载（MemoryBlock.Data），删 PayloadDigest；检索纯向量，媒体随块同生灭。生产代码全绿；CAS 专属测试将在下一提交随判据重写。 - memory: Data BLOB + migration9；blockColumns 不含 data（召回只比向量）； MediaBlockID 内容派生 ID；BlockByIDPrefix/BlockData 按需加载 - sdk: memory_impl 去 media.Store；MemoryBlockView PayloadDigest→HasData - core: mediaref/graphmedia/crossmodal/medialoop 全部改块语义； captureBlockMedia 直接产块；resolveMediaRefs 按块 ID 解析 - knowledge: 媒体字节随条目目录自带（File+Data），删 mediaGet/mediaPut - webui: graphBlockView/pulse payload_digest→has_data - bootstrap/registry: 去 MediaStore 接线（SetMediaStore 空实现，待⑥删包）
2026-10-15 12:15:16 +00:00 · 2026-10-12 10:13:36 +08:00
parent b15994d964
commit 86572d134d
30 changed files with 806 additions and 864 deletions
--- a/internal/agent/core/mediaref.go
+++ b/internal/agent/core/mediaref.go
@ -1,85 +1,59 @@
 package core

 import (
+	"encoding/base64"
 	"fmt"
 	"log"
 	"strings"
-	"sync/atomic"
 	"time"

 	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
 	"github.com/JianFeeeee/HomeAgent/internal/memory"
-	"github.com/JianFeeeee/HomeAgent/internal/memory/media"
 )

-// blockSeq 保证块 ID 全局唯一（Graph memory_blocks 以 id 为主键）。
-var blockSeq int64
+// 媒体记忆接线：把对话里出现的图片/音频变成一等记忆块。
+//
+// ★ 2026-10-11：块自带负载（CAS 已淘汰）。
+//
+// 此前这里把字节存进独立的内容寻址存储（CAS），块只留一个 digest 指向它。
+// 那是把「媒体的内容」从块里拆出去另建一层——现在媒体字节直接进块的 Data，
+// 与文本块的 Text 对称：一个块要么带文本、要么带字节。
+//
+// 媒体进入对话有两条路：用户直接发图（ContentBlock data URL）、插件注入
+// （SetToolBlocks）。两条都在这里收口成块，挂到当轮 ContextEvent；
+// 事件被 Prune 时块随之迁移到 L2 文档（块本身不变，只换持有层）。
+//
+// 不再生成任何描述文本，也不再往正文写 media marker：图片只按自己的
+// 统一空间向量被检索，描述式索引是将就方案。

-func newBlockID() string {
-	return fmt.Sprintf("blk_%d_%d", time.Now().UnixNano(), atomic.AddInt64(&blockSeq, 1))
-}
-
-// blockModalityOf 把 CAS 媒体大类映射为一等记忆块模态。
-func blockModalityOf(k media.Kind) memory.BlockModality {
-	switch k {
-	case media.KindImage:
+// blockModalityFromMIME 按 MIME 大类推断块的模态。
+func blockModalityFromMIME(mime string) memory.BlockModality {
+	switch {
+	case strings.HasPrefix(mime, "image/"):
 		return memory.BlockImage
-	case media.KindVideo:
+	case strings.HasPrefix(mime, "video/"):
 		return memory.BlockVideo
-	case media.KindAudio:
+	case strings.HasPrefix(mime, "audio/"):
 		return memory.BlockAudio
 	default:
 		return memory.BlockText
 	}
 }

-// blockFromDigest 把一份已入库媒体变成一等记忆块。
-// 块携带 digest/向量/fingerprint；CAS 只提供字节与元数据，不参与生命周期。
-func (a *Agent) blockFromDigest(digest string) (memory.MemoryBlock, bool) {
-	if a.mediaStore == nil || digest == "" {
-		return memory.MemoryBlock{}, false
-	}
-	it, err := a.mediaStore.Stat(digest)
-	if err != nil || it == nil {
-		return memory.MemoryBlock{}, false
-	}
-	return memory.MemoryBlock{
-		ID:            newBlockID(),
-		Modality:      blockModalityOf(it.Kind),
-		PayloadDigest: it.Digest,
-		MIME:          it.MIME,
-		Size:          it.Size,
-		Width:         it.Width,
-		Height:        it.Height,
-		Vector:        it.Vec,
-		Fingerprint:   it.VecModel,
-		Tool:          it.Tool,
-		CreatedAt:     it.FirstSeen,
-	}, true
-}
-
-// 媒体记忆接线：把对话里出现的图片/音频落进内容寻址存储（CAS），
-// 并让 L0 的 ContextEvent 直接持有一等记忆块。
+// captureBlockMedia 把 blocks 里的 data URL 媒体变成一等记忆块，返回块列表。
 //
-// 媒体进入对话有两条路：用户直接发图（ContentBlock data URL）、插件注入
-// （SetToolBlocks）。两条都在这里收口：从 data URL 取出字节存进 CAS，
-// 用其向量构造一等记忆块挂到当轮 ContextEvent 上；事件被 Prune 时
-// 块随之迁移到 L2 文档。
+// 只处理 data URL：http(s) URL 拿不到字节，而"下载它再存"会把一次对话变成
+// 一次网络请求（超时、鉴权、SSRF 全来了），不在本层解决。
 //
-// 不再生成任何描述文本，也不再往正文写 media marker：图片只按自己的
-// 统一空间向量被检索，描述式索引是将就方案。
-
-// captureBlockMedia 把 blocks 里的 data URL 媒体落进 CAS，返回 digest 列表。
-//
-// 只处理 data URL：http(s) URL 拿不到字节就无法做内容寻址，
-// 而"下载它再存"会把一次对话变成一次网络请求（超时、鉴权、SSRF 全来了），
-// 不在本层解决。
-func (a *Agent) captureBlockMedia(blocks []agentAPI.ContentBlock, tool string) []string {
-	if a.mediaStore == nil || len(blocks) == 0 {
+// 块 ID 由内容派生（memory.MediaBlockID）：同内容 ⇒ 同 ID ⇒ 落库时
+// ON CONFLICT 天然去重（这正是内容寻址当年的好处，但现在由块 ID 直接提供，
+// 不需要一层独立的寻址存储）。
+func (a *Agent) captureBlockMedia(blocks []agentAPI.ContentBlock, tool string) []memory.MemoryBlock {
+	if len(blocks) == 0 {
 		return nil
 	}

-	var digests []string
+	var out []memory.MemoryBlock
 	for _, b := range blocks {
 		var url string
 		switch {
@ -91,106 +65,124 @@ func (a *Agent) captureBlockMedia(blocks []agentAPI.ContentBlock, tool string) [
 			continue
 		}

-		mime, data, ok := media.ParseDataURL(url)
+		mime, data, ok := parseDataURL(url)
 		if !ok {
 			continue // http(s) URL 或格式不认，跳过
 		}

-		d, err := a.mediaStore.Put(data, media.Item{
-			MIME: mime,
-			Tool: tool,
-		})
-		if err != nil {
-			// 媒体存不进去不该让对话失败——它是记忆增强，不是对话必需品
-			log.Printf("[media] 落盘失败 (tool=%s mime=%s): %v", tool, mime, err)
-			continue
+		block := memory.MemoryBlock{
+			ID:        memory.MediaBlockID(mime, data),
+			Modality:  blockModalityFromMIME(mime),
+			Data:      data,
+			MIME:      mime,
+			Size:      int64(len(data)),
+			Tool:      tool,
+			CreatedAt: time.Now(),
 		}
-
-		// 入库即算一次多模态坐标并缓存（多模态空间可用时）。
-		// 之后 doc_query / memory_recall / 内部召回直接复用 SetVec 的缓存坐标，
-		// 不重复跑 ONNX；模型切换由启动时的 reembedStaleMedia 补算。
-		a.embedMediaOnIngest(d, mime, data)
-		digests = append(digests, d)
+		// 入库即算一次多模态坐标（多模态空间可用且为图像时）。
+		// 之后块召回直接用它；换模型由启动时的 reembedStaleMedia 补算。
+		a.embedBlockOnIngest(&block)
+		out = append(out, block)
 	}
-	return digests
-}
-
-// embedMediaOnIngest 给刚入库的图片立即计算多模态坐标并缓存。
-// 只在 多模态空间可用且为图像时执行；音频/未配置时静默跳过（保持既有行为）。
-func (a *Agent) embedMediaOnIngest(digest, mime string, data []byte) {
-	if a.multimodalSpace == nil || !a.multimodalSpace.Loaded() {
-		return
-	}
-	if !strings.HasPrefix(mime, "image/") {
-		return
-	}
-	vec, err := a.multimodalSpace.EmbedImageDense(data, mime)
-	if err != nil {
-		log.Printf("[media] 入库嵌入失败 %s: %v", shortDigest(digest), err)
-		return
-	}
-	if err := a.mediaStore.SetVec(digest, vec, a.multimodalSpace.Fingerprint()); err != nil {
-		log.Printf("[media] 入库写向量失败 %s: %v", shortDigest(digest), err)
-	}
-}
-
-// stageMediaDigests 累积本轮捕获的 digest，等 ContextEvent 建好后一起挂上。
-//
-// 为何要缓存而不是当场建块：媒体在 process() 执行期间被捕获，而承载它的
-// ContextEvent 要等 process() 返回后才 Append——此刻还没有 owner_id。
-// 与既有的 a.pendingMedia 同一手法（均由 schedulerLoop goroutine 独占读写）。
-func (a *Agent) stageMediaDigests(digests ...string) {
-	if len(digests) == 0 {
-		return
-	}
-	a.pendingMediaDigests = append(a.pendingMediaDigests, digests...)
-}
-
-// drainMediaDigests 取出并清空本轮累积的 digest。
-func (a *Agent) drainMediaDigests() []string {
-	if len(a.pendingMediaDigests) == 0 {
-		return nil
-	}
-	out := a.pendingMediaDigests
-	a.pendingMediaDigests = nil
 	return out
 }

-// bindEventMedia 把本轮捕获的媒体变成一等记忆块，直接挂到 ContextEvent 上。
+// embedBlockOnIngest 给刚捕获的块立即计算多模态坐标。
+// 只在多模态空间可用且为图像时执行；音频/未配置时静默跳过（保持既有行为）。
+func (a *Agent) embedBlockOnIngest(b *memory.MemoryBlock) {
+	if b == nil || a.multimodalSpace == nil || !a.multimodalSpace.Loaded() {
+		return
+	}
+	if !strings.HasPrefix(b.MIME, "image/") {
+		return
+	}
+	vec, err := a.multimodalSpace.EmbedImageDense(b.Data, b.MIME)
+	if err != nil {
+		log.Printf("[media] 入库嵌入失败 %s: %v", shortID(b.ID), err)
+		return
+	}
+	b.Vector = vec
+	b.Fingerprint = a.multimodalSpace.Fingerprint()
+}
+
+// stageMediaBlocks 累积本轮捕获的块，等 ContextEvent 建好后一起挂上。
 //
-// 块存储在事件自身（随 context.json 持久化），不再写 media_refs：
-// 存活与否由“三层记忆块是否持有这个 digest”决定，不维护引用账本。
-func (a *Agent) bindEventMedia(evt *ContextEvent, digests []string) {
-	if a.mediaStore == nil || evt == nil || len(digests) == 0 {
+// 为何要缓存而不是当场挂：块在 process() 执行期间被捕获，而承载它的
+// ContextEvent 要等 process() 返回后才 Append——此刻还没有 owner。
+// 与既有的 a.pendingMedia 同一手法（均由 schedulerLoop goroutine 独占读写）。
+func (a *Agent) stageMediaBlocks(blocks ...memory.MemoryBlock) {
+	if len(blocks) == 0 {
+		return
+	}
+	a.pendingMediaBlocks = append(a.pendingMediaBlocks, blocks...)
+}
+
+// drainMediaBlocks 取出并清空本轮累积的块。
+func (a *Agent) drainMediaBlocks() []memory.MemoryBlock {
+	if len(a.pendingMediaBlocks) == 0 {
+		return nil
+	}
+	out := a.pendingMediaBlocks
+	a.pendingMediaBlocks = nil
+	return out
+}
+
+// bindEventMedia 把本轮捕获的块挂到 ContextEvent 上。
+//
+// 块存储在事件自身（随 context.json 持久化），不维护引用账本：
+// 存活与否由持有它的层决定。
+func (a *Agent) bindEventMedia(evt *ContextEvent, blocks []memory.MemoryBlock) {
+	if evt == nil || len(blocks) == 0 {
 		return
 	}
 	if evt.ID == "" {
 		evt.ID = newEventID()
 	}
-	for _, d := range digests {
-		b, ok := a.blockFromDigest(d)
-		if !ok {
-			log.Printf("[media] 块构造失败 (%s)", shortDigest(d))
-			continue
-		}
-		evt.Blocks = append(evt.Blocks, b)
-	}
+	evt.Blocks = append(evt.Blocks, blocks...)
 }

-// mediaLabel 渲染一行媒体标签，供提示词告知"这条记忆带着哪份媒体"。
+// blockLabel 渲染一行媒体块标签，供提示词告知"这条记忆带着哪份媒体"。
 //
-// 不再包含任何生成的描述文本：图片只按自己的向量被检索，标签仅提供
-// MIME 与短 digest，让模型知道有这份媒体、可据 digest 取回字节。
-// 查不到返回空串：内容可能已被删除，不该造出一条指向虚无的标签。
-func mediaLabel(it *media.Item) string {
-	if it == nil {
+// 不含任何生成的描述文本：图片按自己的向量被检索，标签仅提供 MIME 与
+// 短块 ID，让模型知道有这份媒体、并可据此取回（块 ID 是它的唯一身份）。
+func blockLabel(b *memory.MemoryBlock) string {
+	if b == nil {
 		return ""
 	}
-	label := string(it.Kind)
-	if it.MIME != "" {
-		label = it.MIME
+	label := string(b.Modality)
+	if b.MIME != "" {
+		label = b.MIME
 	}
-	return fmt.Sprintf("[%s %s]", label, shortDigest(it.Digest))
+	return fmt.Sprintf("[%s %s]", label, shortID(b.ID))
+}
+
+// parseDataURL 从 data:<mime>;base64,<data> 解出 MIME 与原始字节。
+//
+// 自 CAS 淘汰后，这段解析归内核媒体接线自己持有（原在 media 包）。
+func parseDataURL(url string) (mime string, data []byte, ok bool) {
+	const prefix = "data:"
+	if !strings.HasPrefix(url, prefix) {
+		return "", nil, false
+	}
+	rest := url[len(prefix):]
+	comma := strings.IndexByte(rest, ',')
+	if comma < 0 {
+		return "", nil, false
+	}
+	head := rest[:comma]
+	payload := rest[comma+1:]
+	if !strings.HasSuffix(strings.ToLower(head), ";base64") {
+		return "", nil, false
+	}
+	mime = head[:len(head)-len(";base64")]
+	if mime == "" || payload == "" {
+		return "", nil, false
+	}
+	decoded, err := base64.StdEncoding.DecodeString(payload)
+	if err != nil {
+		return "", nil, false
+	}
+	return mime, decoded, true
 }

 // newEventID 生成 ContextEvent 的稳定标识。
@ -202,9 +194,10 @@ func newEventID() string {
 	return fmt.Sprintf("evt_%d", time.Now().UnixNano())
 }

-func shortDigest(d string) string {
-	if len(d) > 12 {
-		return d[:12]
+// shortID 把块 ID 截短供日志/提示词使用。
+func shortID(id string) string {
+	if len(id) > 20 {
+		return id[:20]
 	}
-	return d
+	return id
 }