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
2026-10-12 16:52:43 +08:00
parent 2585bc67ef
commit 9f7d91c219
24 changed files with 373 additions and 2374 deletions

View File

@ -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")
}
}