mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-10-15 12:15:16 +00:00
9f7d91c219
块 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。
73 lines
3.0 KiB
Go
73 lines
3.0 KiB
Go
package sdk
|
||
|
||
import (
|
||
"time"
|
||
|
||
pubsdk "github.com/JianFeeeee/homeagentsdk/sdk"
|
||
)
|
||
|
||
// MemoryBlockView 是块的最小只读视图（供星图轮询端点）。
|
||
//
|
||
// ★ 不直接用 memory.MemoryBlock：那是内核内部类型，而本包是**插件边界**。
|
||
// SDK 接口只暴露端点真正要用的字段（原来是先 GraphData 全量再转成
|
||
// graphBlockView 做同样的事，只是绕了一圈）。
|
||
type MemoryBlockView struct {
|
||
ID string `json:"id"`
|
||
Modality string `json:"modality"`
|
||
Text string `json:"text,omitempty"`
|
||
HasData bool `json:"has_data"` // 媒体负载在块内（CAS 淘汰后），只报有无不回显内容
|
||
MIME string `json:"mime,omitempty"`
|
||
Source string `json:"source,omitempty"`
|
||
Tool string `json:"tool,omitempty"`
|
||
Scene string `json:"scene,omitempty"`
|
||
CreatedAt time.Time `json:"created_at"`
|
||
UpdatedAt time.Time `json:"updated_at"`
|
||
}
|
||
|
||
// MemoryAPI 是内置插件使用的全量图记忆接口。
|
||
type MemoryAPI interface {
|
||
pubsdk.MemoryAPI
|
||
// GraphData 返回整个知识图谱的完整快照。
|
||
GraphData() (map[string]interface{}, error)
|
||
// BlocksChangedSince 返回自 since 之后创建或更新过的块（供星图轻量轮询）。
|
||
//
|
||
// ★ 为何单开一个方法而不复用 GraphData：后者是全量快照（生产实测
|
||
// 3190 块 + 2692 边，JSON 约 3.3MB、135ms），而轮询端点只想知「有新东西」。
|
||
// 原先 pulse 端点是先取全量再过滤 —— 实测与全量端点同价（145ms），
|
||
// 「轻量端点」名不副实。库侧 SQL 过滤后响应体差两个数量级。
|
||
//
|
||
// 属内置接口（非 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
|
||
type Relation = pubsdk.Relation
|
||
type Triple = pubsdk.Triple
|
||
|
||
// TextMemoryAPI 是内置插件使用的全量文本记忆接口。
|
||
type TextMemoryAPI interface {
|
||
pubsdk.TextMemoryAPI
|
||
// RecentEvents 返回最近 n 条记忆事件。
|
||
RecentEvents(n int) ([]TextEvent, error)
|
||
// Stats 返回文本记忆的运行统计。
|
||
Stats() map[string]interface{}
|
||
}
|
||
|
||
type TextEvent = pubsdk.TextEvent
|
||
|
||
// MediaAttachment 是记忆附件（媒体）在插件边界上的表示。
|
||
// 与公共 SDK 同一类型，内置插件与外部插件用同一套字段。
|
||
type MediaAttachment = pubsdk.MediaAttachment
|
||
|
||
type DocMemoryAPI = pubsdk.DocMemoryAPI
|
||
type Doc = pubsdk.Doc
|