6 Commits

Author	SHA1	Message	Date
JianFeeeee	e9856c8f65	feat(media): media.Item 加视觉嵌入字段，Store 加 QueryMedia 跨模态检索 ... 路线 3（完整跨模态检索）的媒体层基础： - Item 新增 Vec []float64（视觉嵌入向量，JSON 序列化存库）和 VecModel （模型标识，用于模型切换后触发重算） - initSchema 加 ALTER TABLE 迁移 vec/vec_model 两列（幂等，列已存在可忽略） - scanItem 扩展读回 vec/vec_model - SetVec(digest, vec, model) 写入向量 - QueryMedia(queryVec, model, topK)：对所有已嵌入媒体做余弦相似度检索， 维度不一致的项自动跳过（防不同模型空间的向量被混算） 混合检索的设计意图：查询可以是图片也可以是文本（经向量化后调用 QueryMedia）， 被查的媒体库里每个 item 也有视觉向量。两者在同一空间比对，谁相似度更高召回谁。 不再区分「图片查询」还是「文本查询」——向量空间的相似度自动决定。	2026-09-07 17:11:10 +08:00
JianFeeeee	28fc833a6f	feat(memory): L3 图库媒体反查 + 修 L2→L3 引用泄漏 ... 媒体记忆四层收尾。方案 A：只做引用，不建媒体实体节点。 ## 为何不把媒体建成图库实体 图库里的实体与关系全部来自**描述文本**的 NLP 提取——描述经 mediaSummaryForEvent 进 L0 事件的 Input，随归档进 L2 文档的 Content， 蒸馏时提取器自然从描述文字里抽出实体和关系。检索能力已经具备。 若再把媒体本身建成节点，节点名只能从描述里取，而描述会被重新生成 （换个视觉模型、补一次描述，名字就变了），于是同一张图会在图谱上留下 多个语义模糊的节点。代价换不来能力。 所以这一层只做一件事：**反查**。图库句子写着「[image a1b2c3d4e5f6] 一张紫蓝红三色带图」，要能从这条句子取回那份字节。 ## CommitWithMedia：新增方法而非改签名 Commit 有 10 个非测试调用点 + 21 个测试调用点。为一个多数调用方都不需要 的返回值改全部签名不划算。新增 CommitWithMedia 返回 map[句子文本]sentences.id，Commit 内部转调同一份落库逻辑。 ## digest 靠正则从文本反解 三元组由 NLP 提取器从纯文本产出（nlp.ToMemoryTriple 只填 Subject/ Relation/Object/Confidence/SentenceText），提取链路上没有任何位置能塞进 结构化的 digest。要贯通就得改 internal/nlp 的整条数据流。而媒体标记本身 是我们自己按固定格式写进文本的，反解是最省的可靠做法。 配套加 media.ResolvePrefix：文本里是 12 位短 digest（完整 64 位会把一行 撑爆且无助人眼辨认），media_refs 主键要完整 digest。 **前缀歧义视为错误而非"取第一个"**：挂错引用会让 GC 删掉仍被引用的内容。 完整但不存在的 digest 也报错，否则调用方会挂一条孤儿引用。 ## 顺带修掉 L2→L3 的引用泄漏 这是上一层（f855893）留下的缺口：我当时只处理了 L0→L2 的引用转移， 漏了 L2→L3 这一跳。archiveColdDocs 调 docStore.Remove(doc.ID) 时不注销 媒体引用——文档一旦消失就再没有任何东西能告诉我们它引用过哪些 digest， media_refs 里那条记录永久悬空、引用计数永不归零，对应 blob 永远不会被 GC 回收。 新增 releaseDocMedia。L2→L3 这一跳是**释放**而非转移，因为图库存的是从 描述文本抽出的实体与关系，不再持有字节；媒体此时已完成使命。 顺序有讲究：必须在 commitTriplesWithMedia 之后释放。那一步已把引用挂到 graph_sentence owner 上，先销后挂会让引用计数瞬时归零，此时若后台 GC 正在跑就会把内容当孤儿清掉。 ## 顺带修 Pending 的排除逻辑遗漏（承上一提交） ## 测试 graphmedia_test.go 11 例。核心是 TestBindSentenceMedia_RoundTrip： 写入 → 提交 → 从句子 id 反查 digest → 取回字节逐字节比对 → 跑 GC(0) 确认被引用的内容不被清。 其余覆盖：正则不误命中普通方括号（[注意]/[TODO] 不能当 digest，否则会拿 假前缀去 ResolvePrefix）、无法补全的 digest 不挂引用、媒体关闭时全链路 静默 no-op、releaseDocMedia 释放后 GC 真能回收、200 个样本的前缀补全 要么唯一命中要么明确报歧义。 TestCommit_StillWorksAfterRefactor 记录一个既有行为：重复提交时 entitiesCreated 不归零，因为 SQLite 的 ON CONFLICT DO UPDATE 也算一行 affected。用 main 分支的 graph.go 单独跑过基线确认与本次重构无关， 该字段只用于日志，故记录现状不改行为。 全仓 go build / go vet / go test 通过，internal/agent/core 与 internal/memory 全部 -race -count=2 通过，SDK 冻结 diff = 0。	2026-09-04 22:52:30 +08:00
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	4ef3371701	test(memory): 媒体存储的压力、冒烟与长稳测试 ... 在 a822674 的 CAS 层之上补齐三类验证。 ## 压力测试（stress_test.go，9 例） 核心不是吞吐数字，而是并发下的不变量。为此写了 checkRefIntegrity： 用 SQL 对比每个 digest 的 ref_count 与 media_refs 实际行数。这条对不上 就意味着 GC 的判断依据是错的——计数偏低会误删有引用的内容，虚高会让 孤儿永远清不掉。所有并发用例收尾都验它。 - 32 goroutine 并发 Put 同一内容 → digest 一致、磁盘只 1 份 - 400 个不同内容并发入库 → 无丢条目、逐条回读无内容串位 - 24 worker × 40 轮引用增删风暴（含故意重复 AddRef 验并发下的幂等） - GC 与读写并发 1.5s → 实测 11508 次 Put / 604 轮 GC，受保护内容零失败 - Describe 与 Search/Pending 并发 → 无 database is locked - 容量上限持续加压 → 上限 256KB 收尾 98KB，有引用项全存活 - 重度 churn 后重开 → 磁盘文件数 == 元数据条数，无双向孤儿 - 4MB 单文件往返（see_video 10 帧 × 2MB 是现实上限附近） - data URL 往返 ×50（SetToolBlocks 给出的实际形态） -race -count=3 干净。 ## 冒烟测试（smoke_test.go，6 场景） 走真实数据路径：真 PNG（自建 IHDR/IDAT/IEND + zlib）、真 data URL、 真 sha256、真 GC、真重启，而不是随机字节。 - 同一张截图连问 5 轮 → 磁盘 1 份、5 个 context 引用 - see_video 6 帧内容各异 → 各存一份、共享一个 owner - 描述落库后按关键词检索命中（方案 C 最关键的一环：blob 可被淘汰， 描述会长期留在记忆里） - L0→L2 归档时引用从 context owner 转到 document owner，期间内容可读 - 别的工具留下的一次性图被 GC 清掉，被记忆引用的一个不少 - 全生命周期跨重启：描述、引用、内容、磁盘一致性全部完好 第一次跑挂在「6 帧只搜到 5 条」，看着像存储丢帧，实际是夹具的 palette[(variant+y*3/h)%5] 只有 5 色，variant=0 与 5 产出逐字节相同的 PNG，被 CAS 正确去重。已把 variant 写进像素保证帧间真不同，并把这段 经过记进注释——误报本身证明了去重在工作，也证明冒烟确实有能力发现 「帧数对不上」这类问题。 冒烟原先是 internal/memory/media/smoke/ 下带 //go:build smoke 的独立 main，得记着加 -tags smoke 才跑得到，那种早晚被忘掉。已搬成普通测试， 随 go test ./... 一起跑，冒烟的意义才真正成立。 ## 长稳测试（soak_test.go，-short 下跳过） 60 秒五路混合负载。实测：put=281885 get=1644084 gc=9142 describe=53875 search=23268 refOps=187926，零失败。收尾 20 个受保护项 内容字节一致、ref_count 全为 1；8MB 上限下实际占用 139KB / 48 条， 说明 28 万次写入产生的孤儿被持续清理，无无界增长。 描述者从 Pending() 取项再 Describe()，GC 随时可能在这两步之间清掉它。 这是正常竞态，故忽略 unknown digest 并注明原因；5 万多次调用没把它 升级成计数错位，印证了 Describe 对已删项返回错误而非静默建条目的选择。 全仓 go build / go vet / go test 通过，SDK 接口冻结 diff 为 0。	2026-09-04 11:29:18 +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