3 Commits

Author	SHA1	Message	Date
JianFeeeee	74a24f93d7	feat(memory): 媒体 GC 与描述生成两条后台循环 ... 补齐媒体记忆的最后两块：容量上限真正生效，描述文本成为持久语义记忆。 ## mediaGCLoop：让容量上限不再形同虚设 CAS 的 GC 只在被显式调用时执行，Put 路径不触发它。此前配置项 core.memory.media.max_mb 注册了却没有任何调用方——一次 see_video 抽 10 帧， 帧本身在工具结果被 Prune 后就没人引用了，若无人清理会一直堆在磁盘上。 现在按 gc_interval（默认 6h）周期调 GC(gc_min_age)。两个不变量： - 有引用的内容永不删除，即使超容量（宁可超限也不断引用） - gc_min_age（默认 1h）保护刚 Put 还没来得及 AddRef 的项——它们 refcount 也是 0 ## mediaDescribeLoop：描述才是能活过 GC 的那部分 blob 会被容量 GC 淘汰，而描述留在 media 表里，并经 mediaSummaryForEvent 写进 L0 事件、随归档进 L2 文档、经蒸馏进 L3 图库。于是「那张紫蓝红三色 带图」在原始字节早已被清掉之后仍然可被检索到。 复用既有的视觉回退链（resolveModalFallback + chatModalFallbackBatch）， 不新造一套模型调用。 三个刻意的决定： - **走后台而非入库时同步**：视觉模型一次调用生产实测 9.6s。放在对话 路径上会让每张图都给回复加十几秒，而描述的价值是几个月后还能检索到， 不是这一轮——这一轮模型本来就直接看着图。 - **逐条而非批量**：批量拿回来是一整段文字，无法可靠切分回各自的 digest（模型未必按序号输出，也可能把两张图合并成一句）。宁可多几次 往返也要保证「描述 ↔ digest」的对应关系确定。 - **默认关闭**（describe_on_ingest=false）：它消耗视觉模型配额。开启后 每 30s 最多处理 4 条，不跟对话抢额度。 失败处理分三类： - 网络抖动/配额 → 不标记，下轮重试 - 空回复 → 视作失败（上游剥离媒体时通常回空，与 modalfallback 同理） - 不可描述（kind=other、blob 已丢失）→ 标记 described_by=unsupported/ content-missing，退出队列 ## 顺带修掉 Pending 的一个真缺陷 测试写出来才发现：Pending 原先只看 `description = ''`，于是被标记为 described_by=unsupported 但 description 仍空的项**每轮都会被重新取出来 重试**，永久占着 LIMIT 的名额，真正需要描述的新项永远轮不到。 改为同时要求 described_by 也为空。 这是「先写断言再看它是否成立」抓到的——原本我以为标记一下就够了。 ## 测试 medialoop_test.go 7 例：两条循环在禁用时立即返回（nil store / 零间隔 / describe 关闭三种形态，不留空转 goroutine）、GC 清孤儿保留有引用项、 minAge 保护新项、无可用源时不误标记、不可描述大类被标记后退出队列。 media_test.go 补 1 例专测 Pending 的排除逻辑。 全仓 go build / go vet / go test 通过，SDK 冻结 diff = 0。	2026-09-04 22:00:03 +08:00
JianFeeeee	f855893d1c	feat(memory): 媒体接入 L0/L2——digest 挂到对话事件，归档时引用随之转移 ... 在 a822674 的 CAS 层之上把媒体真正接进记忆链路。此前 CAS 只是个孤立的 存储包，没有任何写入方。 ## 媒体进入对话有两条路，两条都只把文字留给记忆 1. 用户直接发图 → processMediaInput → mediaToBlocks ContextEvent.Input 只存 alt 文本（"[从 qq 收到了 image]"）， base64 随 message 数组发给模型后就丢了。 2. 插件注入 → SetToolBlocks → process.go 的 mediaMsg ToolResultItem.Output 只存那句 "[已将图片注入后续对话] /tmp/x.png"。 于是下一轮起，模型能看到的只剩一句路径或一句 alt。那个文件被删、被覆盖， 或者本来就是 /tmp 下的临时产物，连线索都断了。 现在两条路在同一处收口（captureBlockMedia）：从 ContentBlock 的 data URL 取出字节存进 CAS，digest 挂到当轮 ContextEvent。 ## 改动 internal/agent/core/mediaref.go（新） - captureBlockMedia：ContentBlock → CAS。只处理 data URL——http(s) URL 拿不到字节就无法内容寻址，而「下载它再存」会把一次对话变成一次网络 请求（超时、鉴权、SSRF 全来了），不在本层解决。 - stage/drainMediaDigests：媒体在 process() 期间被捕获，而承载它的 ContextEvent 要等 process() 返回后才 Append——此刻还没有 owner_id， 故先缓存。与既有 pendingMedia 同一手法，同受 a.mu 保护。 - bindEventMedia：双向落地。evt.Media 让事件记得引了什么（随 context.json 持久化），media_refs 让 CAS 知道谁在引用（GC 的判断依据）。 只写一边的话，要么 GC 误删仍被引用的内容，要么孤儿永远清不掉。 - mediaSummaryForEvent：把已有描述拼成一行写进 Input。这是方案 C 的 落点——**描述文本才是持久语义记忆，blob 只是缓存**。blob 可能被容量 GC 淘汰，但描述会一直留在 L0/L2/L3 的文本里，让「那张紫蓝红三色带图」 几个月后仍可被检索。 ContextEvent 新增 ID 与 Media 两个字段，都是 omitempty： - ID 懒生成，只有真要挂媒体时才赋值。绝大多数对话没有媒体，全量生成 会让每条事件都多一个字段进 context.json。 - 存量 context.json 读回来两字段皆空，不影响任何既有行为（有测试）。 RelevanceContext.Prune 归档时转移引用（transferMediaRefs）： **先挂到归档文档、再注销原事件引用**。顺序不能反——先销后挂会让引用 计数瞬时归零，若此刻后台 GC 正在跑就会把仍被记忆引用的内容当孤儿清掉。 为此把 Prune 内的局部类型 scored 提为包级 scoredEvent（局部类型无法 出现在方法签名上）。 media 包新增 OwnerContext/OwnerDocument/OwnerGraphSentence 常量： owner_kind 进了主键，拼错一个字符就是一条永远对不上的孤立引用—— AddRef 不报错，DropOwner 也永远匹配不到。 ## 配置 core.memory.media.enabled（默认 true）、.dir、.max_mb（2048）、 .gc_interval（6h）、.gc_min_age（1h）。 关闭后全链路静默跳过，对话行为与本特性上线前完全一致（有测试）。 mediaStore 为 nil 时同理——它是记忆增强，不是对话必需品，开不起来 只记一条 warning 不阻止启动。 ## 测试（11 例） 入库与 MIME 归类、http URL 跳过、nil store 全链路 no-op、音视频混合、 stage/drain 清空语义、懒生成 ID、描述作为持久记忆、**归档转移期间内容 始终可读且 refcount 不归零**、无媒体存储时归档照常、context.json 向后兼容往返。 全仓 go build / go vet / go test 通过，SDK 冻结 diff = 0。 ## 尚未接入 L3 图库的 graph_sentence owner（常量已备好，无写入方）、 描述生成的后台任务（Pending() 已就绪，尚无消费者）、 媒体 GC 的定时触发（配置项已注册，尚未接 ticker）。	2026-09-04 20:53:32 +08:00
JianFeeeee	a82267484a	feat(memory): 内容寻址媒体存储（CAS）——图记忆支持二进制多媒体节点的底座 ... 此前四层记忆全是纯文本载体，没有任何一层能存二进制： L0 ContextEvent — Input/Response/ToolResults[].Output 全 string L1 text.Event — 同上 L2 document.Doc — Summary/Content/Tags 全 string L3 图库 — sentences.text TEXT UNIQUE，节点身份就是那串文本 于是 multimodal 插件注入的图只在本轮对话内可见（走 message 数组，不经 记忆），下一轮起只剩 ToolResultItem.Output 里那句 "[已将图片注入后续对话] /tmp/x.png"——一条路径字符串。那个文件被删或 被覆盖之后连线索都断了。 ## 为何内容寻址而不是存路径 - 路径会失效。/tmp 下的探针图、下载缓存、别的进程的临时产物，记忆里 留个路径等于留个悬空指针。 - 同一内容常被反复注入（连问几轮同一张截图、see_video 相邻帧高度相似）， 按 sha256 寻址天然去重。 - 内容即身份，与 L3 图库 sentences.text UNIQUE 思路一致：文本节点用文本 本身做身份，媒体节点用内容摘要做身份。 ## 结构 元数据（SQLite media.db）与内容（磁盘 blobs/ 两级前缀分桶）分离，不把 blob 塞进库：单张图动辄几 MB，塞进去让每次 VACUUM/备份都拖着几百 MB 走， WAL 也会迅速膨胀。 media(digest PK, kind, mime, size, width, height, origin_path, tool, description, described_by, ref_count, first_seen, last_seen) media_refs(digest, owner_kind, owner_id, created_at, PK 三列) digest 既是主键也是文件名，所以没有 Path 字段——路径由 digest 推导， 不落库（落了就又是个会失效的引用）。origin_path 仅供人类溯源，注释里 明确标注不可用于读取。owner_kind 预留 context/document/graph_sentence。 ## 几处刻意的决定 - Get 强制校验 digest：CAS 的全部保证建立在「文件名 == 内容摘要」上， 位翻转或外部误改必须被发现——把损坏的图喂给模型只会得到无从追溯的幻觉。 - 先写 .tmp 再 rename：中途崩溃不留半个 blob 被当成完整内容读走。 - AddRef 幂等：只有真插进 media_refs 才递增，否则计数虚高会让 GC 永远 不敢清。DropRef 用 MAX(0,...) 兜底防负数。 - Put 的空描述不冲掉已有描述（先到的可能来自更强的模型），但尺寸/工具名 这类前一次缺失的信息会被补写。Describe 是显式操作，允许覆盖。 - GC 两段 + minAge 保护：刚 Put 还没 AddRef 的项 refcount 也是 0，minAge 防「落地后还没挂上就被清掉」。有引用的项永不删除，即使超容量——宁可 超限也不断引用。 ## 测试 21 例，覆盖去重 / MIME 归类 / 损坏检测 / 无残留临时文件 / AddRef 幂等 / 计数不为负 / DropOwner / GC 保留有引用项 / minAge 保护 / 容量淘汰 / 描述覆盖与补写策略 / Search 按描述与 kind 过滤 / Pending / data URL 往返 / Stats / 跨重启持久化。 本 commit 只加存储层，尚未接入 L0/L2/L3 与描述生成。	2026-09-04 11:03:36 +08:00