mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-10-15 12:15:16 +00:00
refactor(memory)!: 删除 CAS 包与第二套召回（块 union 化第四阶段：收尾）
块 union 化前三阶段已让块自带负载、回填存量字节。本提交拆掉 CAS 本身： `internal/memory/media/`（2100 行）+ `QueryMediaScored`（第二套召回） + `media_refs`/`ref_count` 引用账本 + `internal/sdk/media.go`（MediaAPI） + `SDKConfig.Media` / `SetMediaStore` 接线。删完 CAS 才真正不存在。 ## 为何可删（不是"先删了再说"） - **MediaAPI 在生产早已是死的**：`SDKConfig.Media` 自86572d13起从未被设置， `sdk.Media()` 恒为 nil，插件 digest 路径一直走"内容寻址库不可用"分支。 删的是死代码，不是活路径。 - **第二套召回确无调用方**：`QueryMediaScored` 仅被 media 包自身的测试引用， 跨包引用为 0（块召回走 `RecallBlocks`）。 - **heldMediaDigests 补丁**（crossmodal 靠它防召回"无处可归的媒体"） 已在86572d13删除 —— 两套存储才需要的那种补丁，随存储一起没了。 ## 替代路径：块引用取代 digest 插件取媒体从 `sdk.Media().Get(digest)` 改为 `sdk.Memory().MediaBytes(ref)`： - **新增 `MemoryAPI.MediaBytes(ref) (data, mime, ok, err)`**（内置接口，非 pubsdk）： 按块引用（完整块 ID 或唯一前缀）取字节；`ok=false` 而非 error —— "这个引用没有媒体"是调用方能处理的常态。 - **seemedia / multimodal**：`digest` 参数语义改为**媒体块引用**，工具描述同步。 path/url 两条来源不变（生产实际只用这两条）。 - **webui 知识上传**：媒体字节不再 Put 进 CAS 再拿 digest，而是作为 `KnowledgeMediaRef.Data` 随引用携带，由 knowledge.Write 落进条目目录 （与 content.md 同生共灭，Remove 的 RemoveAll 天然清掉）。 - **回填命令去依赖**：cmd/homed-media-backfill 不再 import 待删的 media 包， 改为直接读**冻结的历史布局** blobs/<d[:2]>/<d[2:]> 并自校验 sha256。 依赖待删代码的迁移工具会在删包那刻失效 —— 迁移必须比被迁移的东西活得久。 ## 判据（全部做过变异测试） - `TestMemoryBytes_ByBlockRef`：完整 ID / 唯一前缀可取回且逐字节一致； 不存在→ok=false；过短前缀（歧义）→ok=false；无负载块→ok=false；空引用不 panic。 变异（不校验 ok，把不存在当有）当场被 3 条断言抓住。 - `TestE2EMediaBytesAgainstBackfilledDB`（-tags e2e，读真回填库）： 10/10 块经 MediaBytes 取回的字节与块 data 的 sha256 完全一致。 - `TestKnowledgeUploadedMediaRetrievable` 重写为**条目目录自带字节**判据 （不再是"向存储按 digest 读回"）；`TestKnowledgeUploadMediaNeedsNoStore` 改为"上传无外部存储依赖也必须成功"（旧的 503 语义已随 CAS 消失）。 ## 静态确认 `QueryMediaScored` / `internal/memory/media` import / `MediaAPI` / `sdk.Media()` / `SetMediaStore` / `heldMediaDigests` 全仓均为 0 处 （仅剩 medialoop.go 一句历史注释）。 回归：memory / sdk / agent-core / knowledge / plugin / webui / seemedia / multimodal 八包全绿；全仓生产编译 GREEN。
This commit is contained in:
JianFeeeee
59
internal/sdk/e2e_mediabytes_test.go
Normal file
59
internal/sdk/e2e_mediabytes_test.go
Normal file
@ -0,0 +1,59 @@
|
||||
//go:build e2e
|
||||
|
||||
package sdk
|
||||
|
||||
import (
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"os"
|
||||
"testing"
|
||||
|
||||
"github.com/JianFeeeee/HomeAgent/internal/memory"
|
||||
)
|
||||
|
||||
// 真实数据 e2e：CAS 淘汰后插件经 MediaBytes 取回的字节必须与回填库中
|
||||
// 块 data 的 sha256 一致（也就是说：插件真拿到了那张图，不是空/错字节）。
|
||||
func TestE2EMediaBytesAgainstBackfilledDB(t *testing.T) {
|
||||
dbPath := os.Getenv("E2E_DB")
|
||||
if dbPath == "" {
|
||||
t.Skip("E2E_DB 未设置")
|
||||
}
|
||||
g, err := memory.NewGraphDB(dbPath)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
defer g.Close()
|
||||
m := NewGraphMemoryWithPlugin("e2e", g)
|
||||
|
||||
ids, err := g.SampleFilledBlockIDs(10)
|
||||
if err != nil || len(ids) == 0 {
|
||||
t.Skipf("没有已回填块: %v", err)
|
||||
}
|
||||
ok := 0
|
||||
for _, id := range ids {
|
||||
want, err := g.BlockData(id)
|
||||
if err != nil || len(want) == 0 {
|
||||
t.Errorf("BlockData(%s): %v", id, err)
|
||||
continue
|
||||
}
|
||||
wantSum := sha256.Sum256(want)
|
||||
data, mime, got, err := m.MediaBytes(id)
|
||||
if err != nil || !got {
|
||||
t.Errorf("MediaBytes(%s): ok=%v err=%v", id, got, err)
|
||||
continue
|
||||
}
|
||||
gotSum := sha256.Sum256(data)
|
||||
if hex.EncodeToString(gotSum[:]) != hex.EncodeToString(wantSum[:]) {
|
||||
t.Errorf("%s 字节不一致", id)
|
||||
continue
|
||||
}
|
||||
if mime == "" {
|
||||
t.Errorf("%s MIME 为空", id)
|
||||
}
|
||||
ok++
|
||||
}
|
||||
t.Logf("MediaBytes e2e：%d/%d 块字节与块 data 完全一致", ok, len(ids))
|
||||
if ok == 0 {
|
||||
t.Fatal("一个块都没能通过 MediaBytes 取回")
|
||||
}
|
||||
}
|
||||
@ -1,79 +0,0 @@
|
||||
package sdk
|
||||
|
||||
import (
|
||||
"errors"
|
||||
|
||||
"github.com/JianFeeeee/HomeAgent/internal/memory/media"
|
||||
)
|
||||
|
||||
// ErrMediaUnavailable 表示媒体存储未接线（宿主没注入 media.Store）。
|
||||
// 单独成一个哨兵：调用方需要区分"没配"与"读失败"，前者不该重试。
|
||||
var ErrMediaUnavailable = errors.New("media: 媒体存储不可用")
|
||||
|
||||
// MediaAPI 是内置插件使用的媒体存储接口（内核侧扩展，非公开 SDK 契约）。
|
||||
//
|
||||
// 存在的理由：多模态链路的一切都以**内容寻址**为锚——media.Store 按
|
||||
// sha256 去重落盘，向量按 digest 存在同一条记录上，知识/文档/记忆块都只
|
||||
// 存「引用」不存字节。而 WebUI 的上传（handleChatFile）历史上只把文件
|
||||
// 落在 uploads/ 目录、直接读字节拼 data URL，**从不入 CAS**，于是拿不到
|
||||
// digest，也就无法把图挂到知识条目上。
|
||||
//
|
||||
// 为什么是 internal/sdk 而不是公开 SDK：同上 KnowledgeAPI 多模态方法的
|
||||
// 理由——third_party/homeagent-sdk/sdk/ 受接口冻结约束，diff 必须恒为 0。
|
||||
type MediaAPI interface {
|
||||
// Put 把字节存入 CAS，返回内容 digest。同一内容重复 Put 幂等
|
||||
// （不重复落盘，只刷新 last_seen）。
|
||||
Put(data []byte, mime, tool string) (string, error)
|
||||
// Stat 读元数据，不读内容。
|
||||
Stat(digest string) (MediaInfo, error)
|
||||
// Get 读回内容并校验 digest。
|
||||
Get(digest string) ([]byte, error)
|
||||
}
|
||||
|
||||
// MediaInfo 是媒体元信息的只读视图。
|
||||
//
|
||||
// 刻意与 media.Item 分离（而非直接别名）：那会把 origin_path / first_seen
|
||||
// 等溯源字段一并暴露给插件层，而插件只需要"这条媒体是什么、怎么取回"。
|
||||
type MediaInfo struct {
|
||||
Digest string `json:"digest"`
|
||||
Kind string `json:"kind"`
|
||||
MIME string `json:"mime"`
|
||||
Size int64 `json:"size"`
|
||||
}
|
||||
|
||||
type mediaImpl struct{ ms *media.Store }
|
||||
|
||||
// NewMedia 构造媒体存储接口。ms 为 nil 时各方法安全降级（返回 error / 空值）。
|
||||
func NewMedia(ms *media.Store) MediaAPI { return &mediaImpl{ms: ms} }
|
||||
|
||||
func (m *mediaImpl) Put(data []byte, mime, tool string) (string, error) {
|
||||
if m.ms == nil {
|
||||
return "", nil
|
||||
}
|
||||
return m.ms.Put(data, media.Item{MIME: mime, Tool: tool})
|
||||
}
|
||||
|
||||
func (m *mediaImpl) Stat(digest string) (MediaInfo, error) {
|
||||
if m.ms == nil {
|
||||
return MediaInfo{}, ErrMediaUnavailable
|
||||
}
|
||||
it, err := m.ms.Stat(digest)
|
||||
if err != nil {
|
||||
return MediaInfo{}, err
|
||||
}
|
||||
return MediaInfo{
|
||||
Digest: it.Digest,
|
||||
Kind: string(it.Kind),
|
||||
MIME: it.MIME,
|
||||
Size: it.Size,
|
||||
}, nil
|
||||
}
|
||||
|
||||
func (m *mediaImpl) Get(digest string) ([]byte, error) {
|
||||
if m.ms == nil {
|
||||
return nil, ErrMediaUnavailable
|
||||
}
|
||||
return m.ms.Get(digest)
|
||||
}
|
||||
|
||||
var _ MediaAPI = (*mediaImpl)(nil)
|
||||
@ -38,6 +38,15 @@ type MemoryAPI interface {
|
||||
//
|
||||
// 属内置接口（非 pubsdk），与 GraphData 同理，不影响外部插件。
|
||||
BlocksChangedSince(since time.Time, limit int) ([]MemoryBlockView, error)
|
||||
// MediaBytes 按**块引用**取回媒体块的字节与 MIME。
|
||||
//
|
||||
// ★ 这是 CAS 淘汰后插件取媒体的唯一入口：块 ID 就是媒体的身份
|
||||
// （内容派生 blk_media_<hash>），不再有独立的 digest 寻址层。
|
||||
// ref 可以是完整块 ID，也可以是唯一前缀（模型/跨进程只带短引用）。
|
||||
//
|
||||
// 取不到（无唯一对应块、或块无负载）时返回 (nil, "", false, nil) ——
|
||||
// 「这个引用没有媒体」是调用方能自己处理的常态，不是错误。
|
||||
MediaBytes(ref string) (data []byte, mime string, ok bool, err error)
|
||||
}
|
||||
|
||||
type Entity = pubsdk.Entity
|
||||
|
||||
@ -4,6 +4,7 @@ import (
|
||||
"bytes"
|
||||
"fmt"
|
||||
"log"
|
||||
"strings"
|
||||
"sync/atomic"
|
||||
"time"
|
||||
|
||||
@ -256,6 +257,32 @@ func (m *graphMemory) BlocksChangedSince(since time.Time, limit int) ([]MemoryBl
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// MediaBytes 实现 MemoryAPI：按块引用取回媒体字节与 MIME。
|
||||
//
|
||||
// ★ CAS 淘汰后插件取媒体的唯一入口。块 ID 就是媒体身份
|
||||
// （内容派生 blk_media_<hash>）；ref 可为完整 ID 或唯一前缀。
|
||||
// 负载不在 blockColumns 里（召回只比向量），所以先解析引用再单取 data。
|
||||
func (m *graphMemory) MediaBytes(ref string) ([]byte, string, bool, error) {
|
||||
if m.db == nil || strings.TrimSpace(ref) == "" {
|
||||
return nil, "", false, nil
|
||||
}
|
||||
b, ok, err := m.db.BlockByIDPrefix(ref)
|
||||
if err != nil {
|
||||
return nil, "", false, err
|
||||
}
|
||||
if !ok {
|
||||
return nil, "", false, nil
|
||||
}
|
||||
data, err := m.db.BlockData(b.ID)
|
||||
if err != nil {
|
||||
return nil, "", false, err
|
||||
}
|
||||
if len(data) == 0 {
|
||||
return nil, "", false, nil
|
||||
}
|
||||
return data, b.MIME, true, nil
|
||||
}
|
||||
|
||||
// ---------- 文本记忆 ----------
|
||||
|
||||
type textMemoryImpl struct {
|
||||
|
||||
@ -400,3 +400,70 @@ func TestTextMemory_AttachmentsIgnoredNotFaked(t *testing.T) {
|
||||
t.Errorf("文本层不该凭空造出附件（没有块存储可挂）: %+v", last.Attachments)
|
||||
}
|
||||
}
|
||||
|
||||
// ---------- MediaBytes：CAS 淘汰后插件取媒体的唯一路径 ----------
|
||||
|
||||
// 判据（不变量，不是"函数被调过"）：
|
||||
// 1. 按完整块 ID 取回字节与 MIME，逐字节一致
|
||||
// 2. 按唯一前缀也能取回（跨进程/跨层只带短引用是常态）
|
||||
// 3. 引用不存在 → ok=false 而非 error（"没这个媒体"是调用方能处理的常态）
|
||||
// 4. 过短前缀（歧义风险）→ ok=false；宁可不解析也不挂错媒体
|
||||
// 5. 文本块（无负载）→ ok=false，不返回空切片冒充"有字节"
|
||||
func TestMemoryBytes_ByBlockRef(t *testing.T) {
|
||||
g, _, _ := newTestStores(t)
|
||||
payload := []byte("PNGDATA-0123456789")
|
||||
b := mediaBlock("image/png", payload)
|
||||
if err := g.PutMemoryBlocks([]memory.MemoryBlock{b}); err != nil {
|
||||
t.Fatalf("PutMemoryBlocks: %v", err)
|
||||
}
|
||||
m := NewGraphMemoryWithPlugin("test", g)
|
||||
|
||||
// 1. 完整块 ID
|
||||
data, mime, ok, err := m.MediaBytes(b.ID)
|
||||
if err != nil {
|
||||
t.Fatalf("MediaBytes(全 ID): %v", err)
|
||||
}
|
||||
if !ok {
|
||||
t.Fatal("完整块 ID 应能取回字节")
|
||||
}
|
||||
if string(data) != string(payload) {
|
||||
t.Errorf("字节 = %q，期望 %q", data, payload)
|
||||
}
|
||||
if mime != "image/png" {
|
||||
t.Errorf("MIME = %q，期望 image/png", mime)
|
||||
}
|
||||
|
||||
// 2. 唯一前缀（blk_media_ + 前 4 位 hex 已 ≥12 字符）
|
||||
prefix := b.ID[:len("blk_media_")+4]
|
||||
data2, _, ok2, err := m.MediaBytes(prefix)
|
||||
if err != nil || !ok2 {
|
||||
t.Fatalf("唯一前缀应能取回字节: ok=%v err=%v", ok2, err)
|
||||
}
|
||||
if string(data2) != string(payload) {
|
||||
t.Errorf("前缀取回字节不一致: %q", data2)
|
||||
}
|
||||
|
||||
// 3. 不存在的引用 → ok=false, err=nil
|
||||
if _, _, ok3, err := m.MediaBytes("blk_media_deadbeef0000"); err != nil || ok3 {
|
||||
t.Errorf("不存在的引用应 ok=false err=nil，实为 ok=%v err=%v", ok3, err)
|
||||
}
|
||||
|
||||
// 4. 过短前缀 → ok=false
|
||||
if _, _, ok4, err := m.MediaBytes("blk_"); err != nil || ok4 {
|
||||
t.Errorf("过短前缀应不解析，实为 ok=%v err=%v", ok4, err)
|
||||
}
|
||||
|
||||
// 5. 文本块（无负载）→ ok=false
|
||||
textBlock := memory.MemoryBlock{ID: "blk_src_abc123def456", Modality: memory.BlockText, Text: "纯文本"}
|
||||
if err := g.PutMemoryBlocks([]memory.MemoryBlock{textBlock}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if _, _, ok5, err := m.MediaBytes(textBlock.ID); err != nil || ok5 {
|
||||
t.Errorf("无负载的块应 ok=false，实为 ok=%v err=%v", ok5, err)
|
||||
}
|
||||
|
||||
// 6. 空引用 → ok=false，不 panic
|
||||
if _, _, ok6, _ := m.MediaBytes(" "); ok6 {
|
||||
t.Error("空引用应 ok=false")
|
||||
}
|
||||
}
|
||||
|
||||
@ -154,7 +154,6 @@ type PluginSDK struct {
|
||||
textMem TextMemoryAPI
|
||||
docMem DocMemoryAPI
|
||||
know KnowledgeAPI
|
||||
media MediaAPI
|
||||
llm LLMAPI
|
||||
|
||||
iom *agentIO.IOManager
|
||||
@ -185,10 +184,8 @@ func (s *PluginSDK) TextMemory() TextMemoryAPI { return s.textMem }
|
||||
func (s *PluginSDK) DocMemory() DocMemoryAPI { return s.docMem }
|
||||
func (s *PluginSDK) Knowledge() KnowledgeAPI { return s.know }
|
||||
|
||||
// Media 返回媒体存储（CAS）。多模态链路的锚：Put 拿 digest，Get 取回字节。
|
||||
// 内置插件用；公开 SDK 契约不含此方法（见 MediaAPI 的注释）。
|
||||
func (s *PluginSDK) Media() MediaAPI { return s.media }
|
||||
func (s *PluginSDK) LLM() LLMAPI { return s.llm }
|
||||
// LLM 返回大模型源。媒体字节请走 Memory().MediaBytes(ref)（CAS 已淘汰）。
|
||||
func (s *PluginSDK) LLM() LLMAPI { return s.llm }
|
||||
|
||||
// ioAdapter 桥接 IOManager 到公共 SDK 的 IOInjector 接口，
|
||||
// 确保外部插件通过 s.InjectText() 等方法的调用能被路由到内核 IO 层。
|
||||
@ -304,7 +301,6 @@ type SDKConfig struct {
|
||||
TextMemory TextMemoryAPI
|
||||
DocMemory DocMemoryAPI
|
||||
Knowledge KnowledgeAPI
|
||||
Media MediaAPI
|
||||
LLM LLMAPI
|
||||
Settings SettingsAPI
|
||||
RegTool ToolRegistrar
|
||||
@ -351,7 +347,6 @@ func New(name string, cfg SDKConfig) *PluginSDK {
|
||||
textMem: cfg.TextMemory,
|
||||
docMem: cfg.DocMemory,
|
||||
know: cfg.Knowledge,
|
||||
media: cfg.Media,
|
||||
llm: cfg.LLM,
|
||||
|
||||
iom: cfg.IOManager,
|
||||
|
||||
Reference in New Issue
Block a user