|
|
1a02971f88
|
feat(memory): 千问三段式 ONNX 嵌入补齐——可复现导出脚本 + Go 侧首次完整验证
此前三段式拆分后 ONNX 路径从未从 Go 侧跑通：embedder_onnx_test.go 仍引用
分段前的 API（e.renderInput、TextTower.onnx、旧目录），go vet -tags onnxruntime
直接编译失败。导出脚本只在 /tmp 且硬编码本机路径、从第三个目录拷贝固定形状的
Vision.onnx，完全不可复现。音频会被视觉塔编码，静默往统一空间灌入错误坐标。
本提交补齐这些缺口：
一、可复现导出脚本（scripts/export_qwen3vl_embedding_onnx.py）
- 自动拉取模型（HuggingFace 优先，失败回落 ModelScope，支持 HF_ENDPOINT 镜像）；
- 导出 TokenEmbedding + Transformer + Vision 三段图，图文共用同一 token
embedding、28 层 Transformer、last-token 池化与 fingerprint；
- 双重自检（不可省）：分段 PyTorch vs 完整模型 + 导出后的 ONNX vs 完整模型，
cos < 0.999999 即非零退出——「能加载」不等于「算得对」；
- 默认把 L2 归一化后的冻结参考向量写入产物目录（qwen_reference.json）——
Go 测试据此做逐维冻结回归，且「该目录是哪次导出的」从文件本身可追溯；
- --verify-only 校验既有产物不重新导出，可用来确认线上在用的图没坏。
关键实测结论（已写入 docs/zh/multimodal-space.md 与长期记忆）：
原生多帧视频不可行——Qwen3-VL 视觉塔把 grid_thw 当 Python 值消费
（grid_thw.tolist()），legacy tracer 固化为常量，导出后图中根本没有 grid_thw
输入，换帧数调用直接 Invalid input name: grid_thw。故视觉塔固定 (1,48,48)，
视频由上层抽帧后逐帧按图像编码（同模型/同维度/同 fingerprint），音频明确
unsupported。
二、模态边界（vector.ErrModalityUnsupported）
- 新增 vector.ErrModalityUnsupported：表示「该模态不在本统一空间的原生覆盖
范围内」，与普通错误语义不同——调用方应把它当「永远不会有向量」而非
「本次失败、下次重试」；
- qwen.EmbedImageDense 按 mime 拒绝 audio/* 与 video/*：此前它会拿视觉塔
去解音频字节，往统一空间灌入语义错误的坐标且静默；
- reembedStaleMedia 对 ErrModalityUnsupported 不计失败、不重试、不用别的
模型向量顶替（TestReembedStaleMedia_SkipsUnsupportedWithoutFaking 守住）。
三、Go ONNX 测试首次完整通过
- 重写 embedder_onnx_test.go：修复编译 + 文本冻结回归 + 图像冻结回归 +
两条阴性对照（不同输入必须不同、图像与文本必须不同）+ 不支持模态断言；
- 参考值从产物目录的 qwen_reference.json 读取（不在测试里硬编码浮点）；
- 用线上部署产物实测全部通过（text cos=0.999999940, image cos=0.999999762）。
四、.gitignore 修复
- /scripts/ 此前被列在「运行时产物」下，但它是作者维护的工具目录
（模型导出、侧车、部署校验），deploy/systemd/embed-sidecar.service 直接
引用 scripts/embed_sidecar.py，忽略它会让那份 unit 在别人的机器上指向
不存在的文件。改为只忽略 __pycache__。
五、文档（docs/zh/multimodal-space.md）
- 获取/启用/产物契约/模态边界/验证/资源成本/与现有部署产物的等价性。
验证：go build ./...、go vet ./...、go vet -tags onnxruntime ./...、
go test -short 全部通过；ONNX 标签测试对线上部署产物全部通过。
|
2026-09-11 13:45:25 +08:00 |
|
|
|
5836c2ce5c
|
refactor(memory): 拆除描述式媒体索引，媒体成为一等块并按原生向量融合
背景：此前媒体是靠「生成的描述文本」将就进记忆的——写 marker 进正文、
再由正则反解成 media_refs 与图库里的 type=Media 实体。这条链路有三个
致命缺陷：描述由异步模型生成（未生成前媒体等于不存在）、语义检索实质上
只搜描述文字、图库里的「媒体节点」是描述文本的投影而不是媒体本身。
本提交把这条链路整体拆除，媒体改为按自己的原生向量参与记忆：
一、描述链彻底删除（无残留、无兼容分支）
- media.Item 去掉 Description/DescribedBy 与对应列；
- 删除 Store.Describe / Store.Search / Store.Pending；
- 删除 Agent.mediaDescribeLoop / describePendingMedia 与配置项
core.memory.media.describe_on_ingest；
- SDK 侧 MediaAttachment 去掉 Description（见 SDK 仓独立提交）。
二、marker 机制删除，媒体归属改为结构化块边
- 删除 mediaMarkerLine/parseMediaMarkers/mediaEntityName/mediaTriplesFromText/
extractMediaDigests/sentenceWithMediaMarkers/docMediaContext；
- memory.Triple 新增 MediaDigests 结构化字段；句子文本保持原样，
不再被 marker 污染；
- 块以 sentence --contains--> block / document --contains--> block 结构边
挂到承载节点（新增 documents 表与 document 节点种类）；
- 模型未给原句时用「主谓宾。」拼一句自然语言作落点，不造 marker 文本。
三、旧数据迁移（幂等）
- 新增 GraphDB.MigrateLegacyMediaEntities：把 type=Media 的旧实体按短 digest
还原成原生块、挂回原句子、删除旧实体与描述关系；Agent 启动时执行；
- CleanupOrphanedSentences 同时看关系引用与块边，避免把只靠块存活的句子
连同块边一起删掉。
四、向量融合：媒体按图本身被召回
- 新增 vector.FuseVectors（逐维求和 + L2 归一化）；
- Doc.DenseVec = 文本向量 ⊕ 文档块的媒体向量（同 fingerprint 才融合），
新增 Doc.DenseFP，指纹变化触发重算；
- ContextEvent.DenseVec 同理融合事件块；事件新增 DenseFP，Prune 只在
同一统一空间内比稠密余弦；
- 跨模态视觉路只召回「仍被某层记忆块持有」的媒体，CAS 全库字节不再
直接充当记忆检索结果。
五、同时纳入本分支既有的嵌入基础改造（此前工作区未提交，缺它 HEAD 不可构建）
- internal/tfidf 懒回退包、千问三段式多模态 ONNX 空间的 Go 侧
（qwen/embedder.go、image.go、model_input.go）、CLIP 移除、
sdk.NewStore 分词器签名与调用点、embed 侧车 systemd 单元。
验证：go build ./... 、go vet ./...（含 -tags medialive）均通过；
在 HEAD 的独立 worktree 上重放本次暂存集后 go test -short ./internal/...
全部通过（端口冲突类用例在隔离环境中亦通过）。未提交工作区中与本改造
无关的改动（HarmonyOS、waiter、devicebridge、plan.md 等）。
|
2026-09-11 11:45:24 +08:00 |
|
|
|
dae01f9c06
|
refactor(memory): 移除 media_refs/引用计数，媒体成为一等记忆块
媒体此前是"文本块 + digest 引用 + owner 账本 + 独立 GC"：ContextEvent.Media
记 digest，media_refs 表用 owner_kind/owner_id 保活，ref_count 决定 GC 能否清。
这与文本记忆块的管理方式不一致，也是本次一并纠正的核心偏差。
改为与文本块完全一致的生命周期：
1. 一等记忆块直接由所在层持有
- ContextEvent.Blocks / Doc.Blocks / GraphDB memory_blocks
- 块带 modality/digest/MIME/size/vector/fingerprint，文本、图片、视频同构
- Context→Document→Graph 迁移的是块本身（ID 不变），迁移后清空源容器，
同一块不同时存在于两层
2. 删除平行生命周期账本
- media.Store 去掉 media_refs 表、OwnerKind 常量、RefCount 字段、
AddRef/DropRef/DropOwner/Refs、ref_count 列与索引
- 删除 mediaGCLoop、GC(keep,minAge)、容量上限与 media.gc_* / media.max_mb 配置
- 媒体内容在块被永久删除时一并删除（media.Store.Delete + forgetPayloads），
与"删除文本块即删除内容"同一语义
3. L3 原生结构
- memory_blocks / memory_block_edges（contains/depicts/derived_from）
- 边端点必须是真实图节点，不再用 owner 字符串伪装关系
- BlocksForNode 支持 sentence --contains--> block 反查
4. SDK 与检索同步
- 插件附件/标记直接变成块，不再 AddRef
- 跨模态检索改用 QueryMediaScored（CAS 内不再有孤儿缓存需要过滤）
测试全部改写为块语义：删除 refcount/media_refs/GC 断言，新增块迁移、
单层不变量、Delete 语义与并发删除回归。
注：cmd/homed/main.go 同时携带工作区中既有的 CLIP→Qwen 模型目录接线改动。
|
2026-09-11 10:57:22 +08:00 |
|
|
|
e44164f5bd
|
feat(memory): Graph 原生一等记忆块节点与结构边(§13.12)
媒体/文本在 L3 不再是正文标记反解出的代理实体，而是带原生
modality/digest/MIME/size/vector/fingerprint 的 memory_blocks 节点；
contains/depicts/derived_from 等语义边落在 memory_block_edges，
端点必须是真实图节点（block/entity/sentence），不复用 owner 字符串。
本步只建立存储与查询能力，不接入 media_refs，也不改变 L0/L2 路径。
|
2026-09-11 10:08:59 +08:00 |
|
|
|
96c1d7baae
|
fix(memory): 千问文本塔补齐 tokenizer post_processor 与真实 ONNX 回归
验证 Go 端到端路径时发现：HuggingFace 的 tokenizer.json 带 TemplateProcessing
post_processor，规则是 `$A <|endoftext|>`——即每段输入末尾都会追加一个
`<|endoftext|>`(151643)。它正是图内 last-token 池化的锚点：
- 漏掉它：ONNX 仍能运行（不会报错），但池化取到的是模板末尾的 assistant
起始符，而非 post token，整条嵌入向量与上游不一致；
- 截断语义：HuggingFace 在 truncation=true 时先把正文截到 maxLen-1，
再保留末尾 post token（实测 600×"记忆"→ [511 正文][151643]）。
改动：
1. Tokenizer 新增 encodeModelInput(text, maxLen)：Encode 后追加 post token，
并在超长时先截到 maxLen-1；缺 <|endoftext|> 直接报错（防静默错误）。
2. Embedder.VectorizeDense 改用 encodeModelInput。
3. 测试：
- TestEncodeModelInputPostProcessor：短文本+post token；长文本按 512 截断
且尾 token 为 post token（用 600×"记忆"确保真的触发截断分支）。
- embedder_onnx_test.go（onnxruntime 标签）：用 Python onnxruntime 1.28
生成的冻结参考向量验证完整 Go 路径（模板渲染→BPE→ONNX→L2 normalize），
逐维 diff ≤ 2e-5；同时断言模型输入恰好 23 token 且末尾是 post token。
产物不在时跳过（与 tokenizer_test 相同约定）。
- 修正先前测试误用 400×"记忆"：BPE 把"记忆"合并为单 token，400 次只有
400 token 不触发截断；改用 600 次后确实走到 maxLen-1 分支。
其余（ORT 库路径、指纹纳入 .onnx.data）一并随本提交带上。
验证：go test ./internal/memory/qwen 与 -tags onnxruntime 全绿；
FP32 图与 PyTorch 在短/长/等长批次/真实 padding 批次上余弦均 ≥0.99999994。
|
2026-09-11 03:09:01 +08:00 |
|
|
|
8e88ae789f
|
feat(memory): 千问文本塔 ONNX 嵌入器（onnxruntime 标签，含 stub）
与 internal/memory/clip 同模式：`//go:build onnxruntime` 编真实实现，无标签时
走 stub，默认构建不链接 onnxruntime、行为不变。
加载契约（目录由 core.memory.multimodal_space.model_dir 指定）：
TextTower.onnx + 外部权重分片、tokenizer.json、embed_config.json。
图内已含 last-token 池化，输出即 [batch, dim]；L2 归一化在 Go 侧做。
两个刻意的设计选择：
1. **EmbedImageDense 明确报错，不返回零向量**
导出的是文本塔，视觉塔未导出。返回零向量会让「写入了但检索不到」，
把跨模态检索失效变成静默故障；明确报错则调用方（mediaref.go）log 后
跳过写向量，文本路径不受影响。
2. **Fingerprint 只哈希图文件 + 配置 + 外部权重的文件名与大小**
该目录有 6.5GB 权重分片，启动时全读一遍要几十秒、会阻塞 homeagent 启动。
换模型必然改变文件集合或大小，足以识别切换；代价是理论上存在
「大小相同但内容不同」的漏判，对本地单机部署可接受。已写入注释。
模板渲染（renderInstructionInput）放在无构建标签的 tokenizer.go，因此可被
测试覆盖：参考数据里有该模板串的用例，逐 token 对齐验证——模板差一个字符，
池化取到的「最后一个有效 token」位置就变，向量就不同，且不会报错。
验证：6 个测试全绿；go build ./...（stub）与 go build -tags onnxruntime
（真实实现）均通过。
|
2026-09-11 00:16:45 +08:00 |
|
|
|
e985151da9
|
feat(memory): 千问字节级 BPE 分词器 + 与上游逐条对齐的回归测试
为「千问嵌入模型导出 ONNX 并内嵌」的 Go 侧准备。CLIP 那套 tokenizer 不能复用：
CLIP 是「小写化 + 空白规整 + 词表 BPE」，千问是 **GPT-2 式字节级 BPE**
（先按字节映射到安全 unicode，再对映射结果做合并），中文与空白输入的切分
完全不同。
实现中撞到两个与上游对齐的坑，都由测试暴露：
1. **`\s+(?!\S)` 的语义依赖正则回溯**，不是「等价于 `\s+`」。
`\s+` 先贪婪吃完整段空白，发现后面是非空白导致 `(?!\S)` 失败，于是回退
一个字符，**正好留下末尾一个空白**给前面以 ` ?` / `[^…]?` 开头的分支合并。
这直接决定切分点：`" leading"` 会切成 `" "` + `" leading"`，
而不是 `" "` + `"leading"`。RE2 不支持 lookaround，近似改写必然对不上，
所以改成按分支顺序**显式实现**（含 `\s*[\r\n]+` 的回溯语义）。
实测：近似改写时 26 条里错 3 条，全部是空白串用例。
2. **Go 的 `\s` 只有 ASCII，且 regexp 不支持二进制属性 `\p{White_Space}`**
（只支持 script/category，直接写会报 invalid character class range）。
而上游 Rust regex 的 `\s` 正是 White_Space。改用 `unicode.IsSpace` 作为
唯一判据，避免全角空格/NBSP/行分隔符的切分点漂移。
另外特殊 token（`<|im_start|>` 等 24 个 AddedToken）必须**整体优先匹配**并
按长度降序，否则会被 BPE 拆成子 token，模型收到的输入就变了——且不会报任何错。
验证：`testdata/qwen_tokenizer_reference.json` 由 HuggingFace 真实 tokenizer
生成（26 条用例，覆盖中/英/中英混排/数字/各类空白形态/标点/emoji/特殊 token/
长文本/空串/单字符边界），Go 实现逐条精确对齐。字节↔unicode 映射另测双射性
（有碰撞会让不同字节编成同一 token，静默产生错误输入）。
|
2026-09-11 00:11:58 +08:00 |
|
|
|
b393b7072c
|
fix(ctx): prune 的查询向量改用插件 Cleaner 清洗后的有效内容(§13.8)
ContextPolicy=prune 上线时直接把**原始**工具结果传给 RelevanceContext.Prune，
而 Prune 的入参是**相关性查询向量**——它决定保留/归档哪些上下文事件。于是
ANSI 转义、base64、JSON 包装等噪声全被编进查询向量，打分失真，裁掉本该
保留的事件。
而 ToolDef.Cleaner 的契约本就写着「仅在向量化/jieba/蒸馏时调用」，裁剪正是
在向量化——所以这是**回归契约**，不是新增能力。此前只在构建事件向量
（context.go 的 toolOutputClean）时用了 Cleaner，裁剪查询这一处漏了。
回退规则（Cleaner 是计算层优化，不能因它失效而丢内容）：
- 未注册 Cleaner → 原文
- RPC 失败 → 原文（proc 侧 cleanerProxy 已有此保证）
- 返回空串 → 原文（空串会让查询向量退化成零向量，所有事件相关性相同，
等于随机裁剪）
验证：TestToolOutputForQueryAppliesCleaner（Cleaner 被调用恰好一次且用其
结果；无 Cleaner / nil stageHost 回退原文）、
TestToolOutputForQueryEmptyCleanFallsBack。
顺带把 §13.13 第 5 条（反向大结果）按核实结论结掉为「不做」：核实发现根本
不存在 llm.chat（llm.* 只映射切换 LLM 源），唯一可能返回大结果的 doc.query
没有任何外部插件使用且已被 CapDocMemory 能力门限制。留成永久 TODO 只会误导。
|
2026-09-10 23:59:12 +08:00 |
|
|
|
50ba4a64cb
|
feat(shm): 文档/知识正文入共享内存 + 协议版本 bump 到 2(§13.13)
## 数据面补齐
- doc.insert / doc.insertWithMedia：新增 doc_ref / attachments_ref，
模板序列化后 putValueInArena
- knowledge.add：新增 content_ref（内容是 JSON 字符串，读出后再解一层）
- 抽出通用 resolveJSONRef（resolveBlocks 也改用它），三处共用一套
“共享优先、内联回退”逻辑
## 协议版本 bump：让错配显式失败，而不是静默坏
这是本轮更重要的部分。§13.6/§13.13 改了内核→插件 payload 的承载方式，
两种错配都不会报错、只会静默失效：
- v1 插件只读内联 args（tool/cleaner/output）→ 遇到 v2 内核拿到空参数
- v2 插件发 blocks_ref → v1 内核反序列化时静默忽略（旧内核
io.setToolBlocks 还是桩实现）
现场表现为“输出变空 / 图注入没反应”，极难定位。所以把 ProtocolVersion
与模板 procProtocolVersion 一起 bump 到 2：双方都是等值校验，v1 插件遇上
v2 内核会在建链时明确报“协议版本不匹配…请用配套 plugindev 重编”。
测试里把“错误必须带出重编指令”也断言上了——生产上碰到它的现场就是
“只更新了内核没重编插件”，光报“不匹配”定位不到行动。
testdata 8 个插件的 protocol 同步更新（badprotoplugin 仍用 999 验证拒绝）。
工具链已重建并安装（协议 2，内嵌 blocks_ref/doc_ref/content_ref），
回滚副本 plugindev.bak-20260910-232544。
验证：-race 全绿。新增 KnowledgeAddViaArena(12000B 正文)、
KnowledgeAddInline、DocInsertViaArena、SetToolBlocks 三例 +
真实模板 e2e + 协议不匹配断言强化。
§13.13 第 5 条（反向大结果）范围更大——需把内核→插件的应答路径整体改成
“大结果写段 + 返回 ref”，涉及 callCore 的返回处理与 doc.query/llm.chat 等
所有读大结果的 method。已在 plan.md 标注未做，不冒充完成。
|
2026-09-10 23:26:16 +08:00 |
|
|
|
15d912ef34
|
feat(shm): 媒体块入共享内存 + 实现 setToolBlocks 桩(§13.13)
两个问题叠在一起，先发现的是第二个：
1. **io.setToolBlocks 在内核侧是桩实现**——直接返回“多模态注入待共享段
二进制通道落地”。也就是**子进程插件调 SetToolBlocks 必然失败**（模板
只 log 一行），只有内置插件（multimodal）能用。之前还有测试把这个错误
当作预期行为断言着。
2. 媒体块（injectMedia 系列 + setToolBlocks）把 blocks 内联在 RPC JSON 里，
而本地生成的图/音频是 base64 data URL，一张图可达数 MB。
顺带修掉一条与设计相悖的旧注释：injectMediaParams 写着“data URL 已是
base64 文本、再套一层二进制不会更小，所以走 JSON”。那只算了体积，漏了
两件更重要的事——内联时整份 base64 要在 RPC 报文里再编码/再拷贝一遍；
以及内容本体不在共享段里，插件回调就无法就地改写，只能各持一份拷贝。
共享内存的意义是后者。
实现：
- injectMediaParams 加 BlocksRef；新增 resolveBlocks（共享优先、内联回退）
- 真正实现 MethodIOSetToolBlocks（空块明确报错，不静默成功）
- CoreSDK 接口加 SetToolBlocks，procCore 转调 internal/sdk
- 模板：SetToolBlocks / injectMedia 三兄弟经 putValueInArena 传 blocks_ref；
同步调用用 mediaArgsOwned 拿释放函数，**不能在应答返回前释放槽**，
否则内核读到已释放内存
验证（-race 全绿）：
- TestCoreHandler_SetToolBlocksViaArena / Inline / EmptyRejected
- TestE2E_RealTemplateSetToolBlocksViaArena：真实 SDK 模板编译的插件，
9000 字节 base64 图经 blocks_ref 完整送达
工具链已同步：/usr/local/bin/plugindev 重建为新协议（内嵌 blocks_ref），
回滚副本 plugindev.bak-20260910-224255。注意内核与全部插件必须同批替换
——只换一边会静默坏（新内核+旧插件=输出 payload 变空；新插件+旧内核=
媒体注入静默失效），已记入长期记忆。
|
2026-09-10 22:45:19 +08:00 |
|
|
|
2a4315cfe4
|
docs(plan): 修正 §13.13 判据——按「回调能否就地改写」而非 payload 大小
之前把共享内存的理由写浅了（当成“省管道 / 避免大 payload”）。真实目的是
找回 .so 时代的能力：插件回调（Cleaner / Stage / 工具）与内核同进程时可以
直接就地改写参数与结果；多进程化后若靠 RPC 来回发消息，回调就只能
“读一份、回发一份”，丢失就地改写语义。共享内存是把内容放进段里、回调就地
改、只回描述符。
因此判据应是「插件回调要能就地改写的内容有没有留在段里」，不是 payload 大小。
按新判据核实：回调主线已达成——
- Stage：invokeStage 只发 {Stage, Seq}，插件就地改写，应答只回 DirtyFields 计数
- Cleaner：发 {Scope,Name,Frame,InputLen}，回 TextRef（16B 描述符），内容不随 RPC 走
- tool.invoke：内核标定 Frame，结果 ResultRef，after_toolcall 可在段内再改
未入内存的重新排序，第一条换成 io.setToolBlocks：它直接破坏“结果媒体能被
after_toolcall 就地改写”——插件只能推一份 base64 拷贝过去（ai_image 大图）。
|
2026-09-10 21:47:23 +08:00 |
|
|
|
b09f459aea
|
docs(plan): 修正 §13.5 的错误判断，建账 §13.13 剩余内联路径
§13.5 之前写的「内核侧未接线」是方向性错误：我把分配方认错了。
实际是**插件侧** putInArena 做 arena.alloc + 写入 + 传 text_ref，内核侧
resolveText 读回。分配在插件侧并非缺口——§13.2 的模型就是「插件经 RPC
向内核申请/归还」，内核独占分配器；procCore.InjectText 拿到普通字符串
也是对的，因为共享内存是跨进程的内部实现、不对插件开发者暴露。
新增 §13.13，把「全量数据交互入共享内存」这个总目标的尾巴显式建账，
区分数据面（要入）与控制面（不该入，几十字节搬进去反而多两次 RPC）：
已入：StageContext / 事件环 / tool.invoke / cleaner.invoke /
output.invoke（本次 §13.6）/ io.injectText（§13.5）
未入：① 媒体块 io.injectMedia / injectMediaSync /
injectInterruptMedia / setToolBlocks（本地大图 base64 可达数 MB，
最大一条）② doc.insert / insertWithMedia ③ knowledge.add
④ 插件反向调内核读大结果仍内联
|
2026-09-10 21:34:42 +08:00 |
|
|
|
e2672c56d6
|
feat(shm): 输出通道 payload 走共享内存调用帧(§13.6)
§13.3 给 ToolInvokeParams 加了调用帧，但 OutputInvokeParams 没跟上——
payload 仍内联在 RPC JSON 里。核实后确认这个 lane 只做了半边：注入侧
（injectParams.TextRef + resolveText）可用，输出侧从内核到插件仍是内联。
改法照搬工具调用的 funccall 帧模型：
- OutputInvokeParams 加 Frame/ArgsLen（Args 仅留给直连 RPC 的测试）
- invokeOutput 序列化参数 → Alloc 帧 → 写帧 → 只传偏移描述符 → defer Free
- 帧尾不预留结果区：output 应答很小（"ok"/status map），走 RPC 应答字段即可。
但 OutputInvokeResult 支持插件把大结果写回帧（ResultRef），并识别
sharedRefFlagExpand 单独归还扩容块——与 invokeTool 一致。
- 模板 output.invoke 用 frameInput 从帧读参数，无帧才回退内联 Args
为什么要做：output payload 在真机上可能含图片/文件描述等大字段，内联会
撑爆 stdin/stdout 管道。
验证：
- TestPlugin_OutputPayloadViaArena：9000 字节 payload 经帧完整送达（插件回报
实收长度，不是只看返回值）+ 调用后 arena 归零
- TestE2E_RealTemplateOutputPayloadViaFrame：同上，但用真实 SDK 模板编译的
插件——生产插件走的就是模板，模板不读帧则此改动等于没做
- TestPlugin_OutputChannelReportsRealFailure 仍绿：同步等真实结果、失败必须
上报（§9.4）的语义未被破坏
- go test -race ./internal/plugin/... 全绿
plan.md §13.5 也如实标注：注入 side 内核→插件方向仍未接线（procCore.InjectText
直接传字符串，从不 Alloc/Put 构造 TextRef），不是仅打勾的项。
|
2026-09-10 21:28:56 +08:00 |
|
|
|
b71a88a471
|
chore(shm): 补齐 §13 验证项，删除统一区域遗留死代码
三件事，都是 plan.md §13 里未打勾的项：
1. §13.3「Bench: ToolInvoke 延迟对比」补测（bench_test.go）
改造后原有的 BenchmarkToolInvoke 仍走 legacy 内联 Args，已不代表生产
路径。拆成 inline / frame 两个子基准并各测两个尺寸（-count=3 取中位）：
payload inline（RPC 报文） frame（共享内存帧） 差
16 B 26.4 µs/op 48.0 µs/op +21.6 µs
32 KiB 695.6 µs/op 391.7 µs/op −303.9 µs
取舍随尺寸翻转：小 payload 多付 ~22µs 帧固定开销，大 payload 省掉整份
JSON 编解码与管道拷贝、快 44%。因为线上工具结果动辄几十 KB 且 22µs
相对 LLM 往返 2-8 秒可忽略，所以统一走帧而不按大小分叉（§13.3 第 4 条）
是对的。
2. 删除 §13.1 遗留死代码（evtring.go）
allocEvtRing 自统一共享区域之后从未被调用——旧版它单独建 memfd + eventfd，
现在只有一个 memfd，事件环只是区内的一个 segment（NewEvtRing 操作区内
切片）。留着会让人误以为事件环还有独立段。
3. 修正误导性注释（plugin.go）
仍写着旧 3-fd 布局「3=StageContext, 4=事件环, 5=通知」，与实现
（procExtraFilesForShm 只返回 memfd+evtfd）和 shmpass_unix.go 的权威
注释互相矛盾。
plan.md：§13.1/13.3/13.4/13.8 的验证项按实测打勾，并注明证据（提交号 /
测试名 / 实测数字），不留无依据的勾。
|
2026-09-10 21:18:16 +08:00 |
|
|
|
e218d0f100
|
fix(agent): 工具循环占位不再驱动重复发送，输出回执/子任务结果幂等
生产现象：单轮内 output_send__qq 被调用 34 次、持续 514 秒，直到 QQ 插件
自己的循环保险拒绝发送才停下（problem.md）。根因是多环节叠加，核心侧修四处：
1. 工具轮补位文案（process.go）
通用占位「请根据以上工具结果继续。」对纯输出通道调用是错的：异步通道
（qq/wechat）的回复只能经 output_send__* 交付，所以模型「已完成回复」的
表达形式就是一个工具调用，紧随其后的「请继续」会被读成「还要再做一步」，
而能做的「一步」恰好还是再发一条消息。
改为按上一批工具的性质选文案：全部是 output_send__* 时补
「若你的回复已完成，直接返回纯文本即可结束本轮，无需再调用任何工具。」
同时每轮先移除旧占位再补一条，避免占位在 prompt 前缀里线性累积。
（该占位是 zen 网关「最后一条必须是 user」的传输层附加物，HEAD 版本是
无条件内联追加、从不移除。）
2. 输出成功回执（output.go）
「已通过 [qq] 通道发送: map[status:sent]」这类富回执会被读成「这步成功，
继续下一步」。成功改为只回极简标记。
3. proc 桥标量透传（internal/plugin/proc/plugin.go）
插件返回 "ok" 时不再伪造 {status:sent} 覆盖插件真实返回值，否则只改
output.go 不生效。
4. 子任务结果幂等（spawn.go）
child_result 原先读到即删，而完成通知长期留在持久上下文里
（formatMergedTimeline 每轮重新注入），第二次查询必然得到
「不存在或已过期」这个永久失败信号，模型据此认为任务未完成而反复重试。
改为保留结果 + delivered 标记，重复查询返回明确提示；结果按上限有界淘汰。
顺带：agent.go 去掉文档层显式向量器注入（TF-IDF 已内置为 fallback），
cmd/homed/main.go 同步 document.NewStore 的 tokenizer 参数。
测试：internal/agent/core/tooloop_test.go（5 例）、spawn_test.go（3 例）。
|
2026-09-10 20:36:39 +08:00 |
|
|
|
b096e8ba2c
|
refactor(shm): 变长块分配器 + 工具调用 funccall 调用帧(§13.2/§13.3)
按架构约束推进两步：
1) 分配器收回内核后，定长槽失去了唯一存在理由
（定长槽只是为了绕开"跨进程无法安全变长分配"），
于是 arena 换成**变长块分配器**：first-fit + 邻块合并，
块头 16B（size/state/owner/prevSize）。内核可以按需标定每块大小，
payload 不再受固定槽容量限制（旧上限 16KB）。
- Alloc/Put/Read/Free/ReclaimOwner 全在内核进程内，一把 sync.Mutex
- Free 走块链校验 offset 是已分配块的数据起点 + owner 匹配，
伪造引用不能改动分配器状态
- Read 允许块内偏移（调用帧的结果区就在帧块中间），但不许跨块边界
- arena 4MB，底层 memfd 惰性分配：未触碰的页不占物理内存
2) 工具调用 payload **始终**走共享内存，取消按大小切内联的分支。
按 funccall 模型，内核（caller）标定调用帧交给插件（callee）：
[0, ArgsLen) 参数 JSON
[ArgsLen, Frame.Length) 结果区（内核预留的预算）
结果超出预算时插件才 `arena.alloc` 扩容块，引用上打
sharedRefFlagExpand 让内核单独归还。Cleaner 复用同一帧模型。
ToolInvokeParams.Args / ToolInvokeResult.Result 仅剩给直连 RPC 的
测试（process/bench 不建 Host）；生产路径永远走帧。
测试：
- TestArena_*（分配/归属/回收/并发唯一/耗尽/超限/伪造 offset/
相邻合并/对齐/布局校验）
- TestPlugin_ToolInvokeArgsResultViaArena：大**小** payload 都经帧往返，
结果一致且 arena 归零（"小 payload 同样走调用帧"是本轮行为变更）
- TestPlugin_ArenaAllocFreeAcrossProcess、TestE2E_* 保持通过
- 顺手修 process_test.go 一处预存 doc-comment 分段
|
2026-09-10 18:54:36 +08:00 |
|
|
|
f6f92a8a6e
|
fix(plugins): 修复两处预存缺陷（agentcli 临界区 / localuse 脚本转义）
agentcli cleanupLoop：
持锁期间为每个过期终端 go func 调 term.Close()（内部会 Kill 进程并等
<-t.done），临界区被拉长且与 TerminalSession 退出路径交错。改为持锁
只做筛选与摘除，锁外再逐个关闭。
localuse 脚本转义（两处真实 bug）：
1. AppleScript 注入：handleScreensue 只把 `"` 转义为 `\"`，未转义 `\`。
内容结尾的反斜杠会吃掉闭合引号，使后续内容逃逸出字符串字面量。
改为 escapeAppleScriptString：**先转义反斜杠再转义双引号**（顺序
不可颠倒，否则刚插入的反斜杠会被二次转义）。
2. PowerShell 路径被错误加倍反斜杠：handleScreensee 把 Windows 临时
路径的 `\` 写成 `\\`。但 PowerShell 单引号串里反斜杠是普通字符
（转义符是反引号），加倍会让截图保存到错误路径。
新增 psSingleQuote 统一处理，并把 4 处零散的 `ReplaceAll(x,"'","''")`
收敛到该 helper。
|
2026-09-10 17:56:57 +08:00 |
|
|
|
c03de9878d
|
fix(proc): EvtConsumer 生命周期——消除 host.Close 后的 SIGSEGV
预存缺陷（非本次重构引入，但会稳定复现崩溃）：
Stop() 只 close 了 stop channel，而 Run() 阻塞在 evtfd.Read 里，
根本没有机会检查 stop。调用方在 Stop 后释放 ringData（host.Close
会 munmap 整个区域），Run 一旦从 Read 恢复就会读已解除映射的内存：
**SIGSEGV，recover 捕不到**。实测 TestEventRing_OverflowStillDelivers
约 50% 概率触发。
两次尝试与结论：
1. os.File.SetReadDeadline 无效——eventfd/pipe 经 os.NewFile 包装后
**不会**注册进 Go netpoller（os.NewFile 对非 open 得到的 fd 一律按
非 pollable 处理），Read 是阻塞 syscall，SetReadDeadline 返回错误。
2. 改为 poll(2) 显式加超时（evtpoll_unix.go），消费循环每 100ms 回到
stop 检查。
新增 API 契约：
- Stop() 非阻塞，仅请求退出
- Wait() 阻塞至 Run 退出；**返回后才能释放 ringData**
- drainEvents 每条事件后检查 stop，避免慢 handler 拖延退出
其他：
- evtring_test.go 三个用例改为 defer Wait() → defer Stop()（LIFO 保证
Wait 先于 host.Close 完成）
- 溢出用例的 handler 改为非阻塞投递：写入了 8292 条事件而 channel 只
消费 1 条，阻塞投递会让 drainEvents 卡在 handler 里，Stop 无法退出
|
2026-09-10 17:56:54 +08:00 |
|
|
|
ca584bda3f
|
refactor(shm): 内核独占共享槽池，插件经 RPC 申请/归还(§13.2/§13.3)
推翻前两版跨进程分配器设计，根因是"共享内存里放了只被单一进程
更新的可变游标"：
- v1 在 SuperBlock 放 arenaUsed 游标，内核 CAS bump。但插件模板里
arenaUsed 是**进程本地变量**，两进程各自 bump 必写同一段内存；
arenaReset 还会重置共享游标覆盖对方数据。
- v2 把位图 CAS 下沉到插件模板，正确但把分配器实现泄漏进插件运行时，
且插件必须与内核保持位图布局同步。
新设计（用户明确的架构约束）：内核全权管理共享内存，插件通过
syscall 风格 RPC 申请/归还，内核返回偏移与大小。分配器只存在于内核
进程内，一把 sync.Mutex 即可。共享内存是内部实现，不对插件开发者
暴露——SDK 公开 API 仍是普通字符串/Map。
主要改动：
- arena.go: 定长槽 + 位图，Alloc/Put/Read/Free/ReclaimOwner，内核独占；
槽头记录 owner，Free 校验归属；payload 超槽容量退回内联 RPC
- protocol.go: 新增 arena.alloc / arena.free（CapCore）
- capability.go: 登记两个新 method（checkAllMethodsClassified 要求）
- corehandler.go: 实现 arena.alloc/free；Cleaner 改为内核预分配
请求槽 + 响应槽（插件完全不分配）
- plugin.go: Start 领 ownerID；handleExit 调 ReclaimOwner 回收残留槽
- unified.go: 移除坏的 bump 分配器；arena 基址 8 字节对齐
- 删除 toollane.go: ring 状态机是死代码（从未接线），且把 RPC 已有的
请求 ID 关联/错误传递/ctx 取消重新实现了一遍。控制面保留 RPC，
只把 payload 搬进共享槽。
- 测试: TestArena_*（归属/回收/并发唯一/耗尽/超限/非法引用/布局）+
TestPlugin_ArenaAllocFreeAcrossProcess（真进程申请→写入→随业务
RPC 回传→归还→内核读回一致且池归零）
|
2026-09-10 17:56:50 +08:00 |
|
|
|
cf3c99233b
|
fix(shm): 审核修复——arena 并发安全 + ToolCall ring 抢占 + arenaRead 校验
§13.2: arenaAlloc 改 CAS bump（修复并发覆盖）；arenaRead 增加 generation + arena 边界校验
§13.3: Reserve 从 Store+Load 改 CAS-free→Reserved 状态机抢占帧（修复并发分配重复）；
增加 RESERVED 中间态；SetReading/SetReady 改 CAS 返回 bool；ReleaseFrame 清零跳过 state
§13.5/13.6: 注入方法接入 resolveText（从 arena 读 SharedRef）；cleanerProxy 加 arenaMu 串行化+每次重置
§13.8: ContextPolicy prune topK 改为 maxContextSize-1（不再硬编码 20）
tool.register 校验 context_policy 只允许 none/prune
|
2026-09-10 17:03:32 +08:00 |
|
|
|
2bc813be13
|
feat(shm): InputChannel/OutputChannel lane 基础设施(§13.5/§13.6)
- injectParams 加 TextRef SharedRef（兼容旧 Text 字段）
- resolveText 辅助函数：优先 SharedRef，否则内联 Text
- 核心注入方法待迁移至 resolveText
|
2026-09-10 16:14:17 +08:00 |
|
|
|
9cfdfc9de8
|
feat(shm): arena + ContextPolicy(§13.2/§13.8)
- unified.go: arena 分配器 (alloc/write/read/reset)
- NewHost: 分配空间含 arena
- SDK ToolDef 加 ContextPolicy string
- StageAfterToolcall 后检查 prune 策略触发 RelevanceContext.Prune
|
2026-09-10 15:49:47 +08:00 |
|
|
|
772a494223
|
feat(ctx): ContextPolicy tool 上下文策略(§13.8)
- SDK ToolDef 加 ContextPolicy string（默认 none / 可设 prune）
- StageAfterToolcall 后检查工具 ContextPolicy=prune → RelevanceContext.Prune
- 所有现有测试通过
|
2026-09-10 15:41:23 +08:00 |
|
|
|
5608abdf5a
|
feat(shm): Cleaner 迁移到 SharedRef(§13.4)
- CleanerInvokeParams/Result 的 Text 改为 TextRef SharedRef
- cleanerProxy: 写 text 到 arena，传 SharedRef，读结果 SharedRef
- 插件侧 cleaner.invoke: 从 SharedRef 读 input，清洗后写回 arena 返回 TextRef
- NewHost(): 分配空间含 arena（256KB）
|
2026-09-10 15:30:00 +08:00 |
|
|
|
cf098a1d4f
|
feat(shm): arena allocator for unified region (§13.2)
- SuperBlock 新增 arenaOff/arenaCap/arenaUsed 字段
- arenaAlloc: append-only bump 分配，offset 0 保留给空语义
- arenaWrite: 写入并返回 SharedRef（含 generation）
- arenaRead: 按 SharedRef 切片读取
- arenaReset: 压实后重置游标
|
2026-09-10 14:33:44 +08:00 |
|
|
|
a8e3633174
|
feat(shm): ToolCall ring buffer(§13.3) — 栈帧模型 ring，push/pop 帧状态机
- ToolCallRing: 定长帧 ring buffer (64 frames × 112B)，状态机 FREE→CALLING→READING→READY→FREE
- Reserve: 环形扫描找 FREE 帧，全忙返回 ErrToolCallRingFull 背压
- SharedRef: pack/unpack 辅助函数
- unified.go: arena 分配器（arenaAlloc/arenaWrite/arenaRead）
- 5 个单测覆盖 init/reserve/背压/find/reuse
|
2026-09-10 12:33:58 +08:00 |
|
|
|
ad016e4410
|
feat(shm): 统一共享内存区域(§13.1) — 单 memfd 容纳 SuperBlock+StageContext+EvtRing
- unified.go: SuperBlock 布局 + SharedRef 类型
- NewHost(): 两段 memfd 合并为单一 memfd，fd 3 = 统一区域，fd 4 = eventfd
- 子进程侧: testdata 插件从 SuperBlock 解析 ctxOff/evtOff
- streaming 测试: EvtConsumer 协程在 host.Close 前 Stop+Wait 防 SIGSEGV
|
2026-09-10 11:42:22 +08:00 |
|
|
|
7a328679da
|
feat(proc): Cleaner 跨进程修复(tool/input/output) + 共享内存安全模式 + plan §13
- Cleaner 协议统一为 cleaner.invoke(scope,name,text)，覆盖工具/输入/输出三类
- 新增 ShmSecurityMode (safe/debug/full)，Linux 审计探针，Windows crypto nonce
- plan.md 追加 §13 步骤分组
|
2026-09-10 10:21:50 +08:00 |
|
|
|
580d5f5501
|
feat(doc): dense vector index for unified text+media retrieval
文档层引入稠密向量索引，与媒体检索共享同一多模态空间：
- Doc 加 DenseVec 字段（json:-，运行时计算）
- Consume/QueryScored 优先使用 denseSearchScored（brute-force cosine），
未配置时退化到 TF-IDF 倒排检索
- buildDenseIndex 在 Agent 启动时为全部文档一次性计算稠密向量
- L0 RelevanceContext 支持 denseSpace（Prune 使用稠密余弦），
退化到 fastText 稀疏余弦
vector 包新增 DenseCosine（[]float64 brute-force cosine）。
验证：492 篇文档 brute-force ~300ms，全部测试通过。
|
2026-09-09 18:56:44 +08:00 |
|
|
|
6c2039f5c9
|
feat(vector): pluggable multimodal vector space
核心暴露 MultimodalEmbedder 接口，两条路径共享同一套 L0/L2/L3
向量缓存、media.Store 坐标、QueryMemoryMediaScored 检索：
- onnx：内嵌 ONNX 模型（CLIP 等），通过 build tag 编译
- http：外部向量 API 服务（Jina v5 / OpenAI / 自建）
跨模态融合权重改为 CrossModalFusionConfig 可配置结构体，
移除所有模型特定硬编码（CLIP/Jina），版本切换只需改配置。
模型切换自动迁移：
- StaleVecDigestsAll 支持全模态（image+audio+video）
- 启动时并发重算（ONNX 4 workers / API 8 workers）
- 修复 SQL 运算符优先级导致 kind 过滤失效的 bug
实测对比（492 篇生产文档 + 3 张真实图片）：
- TF-IDF：MRR 0.457（精确匹配快，语义差）
- fastText：MRR 0.530（语义中等，延迟 8ms）
- Jina v5-omni：MRR 0.900（全面领先，延迟 40ms）
- 中文文本→图片：Jina MRR 0.833 vs CLIP 0.611
See docs/embedding-comparison.md for full benchmark.
|
2026-09-09 17:38:34 +08:00 |
|
|
|
6f8056d236
|
refactor(clip): CLIP 收敛为稠密 MultimodalEmbedder，不污染稀疏 Vectorizer/TF-IDF 语义
文本相似度检索是层次化系统：TF-IDF 高频削弱加权（idf<0.1 丢弃）+
倒排剪枝（只召回共享特征者）+ cosine。CLIP 512 维稠密向量若以
map[string]float64 稀疏形式实现 vector.Vectorizer 并塞进 vector.Store，
会让 512 维全部成为倒排 key → 候选集≈全库、剪枝失效，且绕过 TF-IDF
高频削弱，与既有文本检索语义错配。
收敛：
- vector.MultimodalEmbedder 改为独立稠密接口（VectorizeDense/
EmbedImageDense/Fingerprint/Dim/Loaded/Close），不再继承稀疏 Vectorizer
- clip.Embedder 删除稀疏垫片 Vectorize/EmbedImage/denseToVector，
只产出稠密向量；文档/知识/上下文层继续用 TF-IDF/fastText 稀疏路径
- 分层明确：文本→文本走 TF-IDF/fastText；文本↔图像、图像↔图像走
CLIP 稠密 QueryMedia（媒体层独立稠密余弦，原样保留）
|
2026-09-09 10:26:10 +08:00 |
|
|
|
98365f3a55
|
feat(clip): 多模态向量器（CLIP ONNX）——文本/图像 512 维共享空间 + 媒体向量写入与重算
- internal/memory/clip：CLIP ONNX 向量器（onnxruntime 构建标签控制，默认构建不链接 ONNX）
- clip.New(modelDir) 加载 text.onnx/vision.onnx（输出 text_embed/image_embed [batch,512]）
- 实现 vector.Vectorizer + vector.MultimodalEmbedder（Vectorize/EmbedImage + Dense 变体）
- 词级 BPE tokenizer：merges 合并后词末片段带 </w> 查 vocab，与官方 encode 逐 id 对齐
- EmbedImage：解码→resize 224→NCHW→normalize→vision session
- Fingerprint（text+vision 文件 sha256）供模型切换检测
- stub 版（无 onnxruntime 标签）保持默认构建行为不变
- vector/store.go：新增 MultimodalEmbedder 接口
- media.Store：新增 StaleVecDigests(currentModel)——查 vec_model 不匹配/缺失的图片
- agent core：AgentConfig.ClipEmbedder + Agent.clipEmb 接线；
describePendingMedia 描述成功后 EmbedImageDense→SetVec；
新增 reembedStaleMedia 启动补算历史无向量图片
- config：core.memory.media.clip_model_dir（未配置退化为现有 fastText/TF-IDF 行为）
- cmd/homed：读 clip_model_dir 加载 CLIP，失败仅记日志不阻塞启动
测试：TestSmokeLoadAndEncode（文本语义 cat>dog 0.914>physics 0.740）、
TestCrossModalAlignment（red-image vs red-text 0.063>blue -0.009，与 Python 一致）、
TestTokEnd（与官方 encode 逐 id 对齐）、TestStaleVecDigests，含 -race 全绿
|
2026-09-09 10:23:31 +08:00 |
|
|
|
8c9d96e065
|
feat(media): media.Store 加向量存储与跨模态检索
media.Item 新增 Vec []float64 和 VecModel 字段，视觉嵌入向量以 JSON
TEXT 存库（为什么不存 BLOB：Go 的 json.Marshal 对 []float64 是自然的，
而 SQLite BLOB 是 []byte 多一层序列化；单条最多 23KB，TEXT 够用）。
initSchema 加 ALTER TABLE 迁移 vec/vec_model 两列（幂等）。scanItem
扩展读回。新增 SetVec 和 QueryMedia 方法。
QueryMedia 对所有已嵌入媒体做余弦相似度检索，维度不一致的项自动跳过
——这是跨模态检索的核心：查询可以是图片也可以是文本，被查的媒体库
里每个 item 也有视觉向量，两者在同一空间比对，谁的相似度更高就召回谁。
配套 5 个单测覆盖：基本相似度排序、无向量项被跳过、维度不匹配过滤、
空查询安全、向量持久化正确性。
|
2026-09-07 22:31:39 +08:00 |
|
|
|
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 |
|
|
|
0af38a29c6
|
feat(vector): Vectorizer 接口加 EmbedImage，支持多模态嵌入扩展
Vectorizer 新增可选的 EmbedImage(img []byte, mime string) (Vector, error)：
支持视觉嵌入的实现者（如 CLIP/MobileCLIP）覆写此方法；不支持的
（StaticEmbedder、TFIDFVectorizer）返回 ErrNotSupported 调用方按文本降级。
这是路线 3（完整跨模态检索）的接口基础：后续在 media.Store 里，
Describe 时同时算视觉向量并存库，QueryMedia 做跨模态混合检索。
|
2026-09-07 17:00:29 +08:00 |
|
|
|
b889934bba
|
docs: 同步仓库文档到 v1.1.1，补媒体记忆与接口扩展规则
五处文档此前停在 v1.0.0，而 v1.1.0/v1.1.1 都已发布并在现网运行。
本轮补齐三层记忆的媒体架构、模型工具的媒体参数、通信面 method 数，
以及冻结解除后的替代约束。
## 中英双语 OVERVIEW.md
三层记忆段只写了 Context/Document/Graph 三层，而 v1.1.0 起图片/音频是
三层里的一类节点。补上媒体记忆的架构概要：CAS + 引用计数 GC + 标记格式
（描述文本才是持久语义记忆，blob 是可淘汰的缓存）+ 插件边界贯通。
## 中英双语 ARCHITECTURE.md
- 「记忆工具」表补 `memory_commit`/`doc_commit` 的 `media_digests` 与
`sentence_text`（后者从未暴露给模型，而它是媒体绑定链的必经环节）
- 「三层记忆」段新增媒体记忆子节：CAS 设计表（寻址/完整性/写入原子性/引用/GC）、
标记格式、可选性（`enabled=false` 时整条链路静默退化）
- 「三个通信面」从 51 改为 55 个 method，新增四个 media method 的说明
- 「SDK 四通道」代码示例补媒体注入三方法 + 与 SetToolBlocks 的区别
## plugin-interface-matrix.md
- 状态从「完成 v2」改「完成 v3」，v3 记录 v1.1.1 的接口扩展
- §二 A3 DocMemoryAPI 补 InsertWithMedia
- §二 A4 补三个媒体注入方法 + 为何不能搭 SetToolBlocks 的车
- §二 A5 补 MediaAttachment 类型 + Triple/Doc/TextEvent 的扩展字段
- §六「新获得的能力」补 SetToolBlocks 已落地、媒体入记忆、插件主动发起
带媒体的对话
- §七 冻结检查点补第 5 条（冻结已解除，取代它的是 §九）
- 新增 §九「v1.1.x 的接口扩展规则」：冻结解除后的三条硬约束
（只增不减签名不改 / 新增方法方向 / 模板接线六处失败链）+ 验证方式
（存量插件 17/17、旧产物 4/4 建链、模板断言、压测 -race）
## 为何分立两笔 commit
前一笔（SDK 仓 README + 内核 README）改的是给**插件开发者**看的文本，
本笔改的是给**架构师与维护者**看的技术文档。受众与改动层次不同，
放在同一个 commit 会让追溯时看不出"文档在哪一层跟上了代码"。
|
2026-09-06 15:07:14 +08:00 |
|
|
|
8cd884027f
|
docs: 项目状态与 plan 同步到 v1.1.1，vendored SDK meta 注释对齐 SDK 仓
三处失同步，都会让读者拿到错的现状：
## README / README_EN
「项目状态」段的最新条目还停在 v1.0.0，而 1.1.0 与 1.1.1 都已发布。补上两条，
并把顶部特性摘要与下载段的 Windows 安装器版本号一起更新（那里写死了
`HomeAgent_v1.0.0_*_win64.exe`，照着它去 release 页面找是找不到文件的）。
## plan.md §12.1
标题还是「待用户决策后执行」，而四个决策点早已全部落定并执行完毕。改为已完成，
并记下实际演进已超出当初设想的地方（这些后来都写进了 docs/git-branching.md）：
发布分支改为一个中版本一条、三级通道由 tag 区分、SDK 版本跟随核心中版本且
patch 位恒为 .0、beta 阶段不发 SDK、main 永不作发版分支。
同时修掉一处会误导追溯的陈述：§12.1 原文说 `v1.0.0` tag 指向 feature 分支中间点
`670efcd` 需要重打——那件事早已做完，现在指向 `release/v1.0.x` 上的 `9b92a04`。
## plan.md §12.5
「无 Windows 真机验证」这条仍然成立，但补一句区分：Windows NSIS 安装器从 v1.0.0
起就随每个正式版作为 release 资产发布了。**能打出包 ≠ 包里的共享内存/事件对象在
真机上能跑通**，混为一谈会让人以为这项已经关闭。
## vendored SDK meta
主仓跟踪 `third_party/homeagent-sdk/meta/meta.go`，而该文件在 SDK 仓 main 上刚补了
版本路牌的说明注释。两仓这份文件必须逐字一致——否则下次谁改了哪边说不清，
而它正是「两仓中版本对齐」这条纪律的载体。仅注释差异，无行为变化。
|
2026-09-06 10:56:42 +08:00 |
|
|
|
e4be9667ec
|
chore(meta): main 的版本路牌推到 1.2.0
按 docs/git-branching.md §2.1，main 的 meta.Version 始终是**下一个未发布中版本**。
1.1.x 线正在发布中（release/v1.1.x 承载 v1.1.0 / v1.1.1），所以 main 指向 1.2.0。
它标记「main 正在积攒 1.2 的东西」，不表示 1.2.0 已经存在——1.2.0 没有任何 tag。
已发布的版本号一律看对应的 release/vX.Y.x 分支与 tag。
两仓同步：SDK 仓 main 也是 1.2.0（SDK 版本跟随核心中版本，见 §七.1），
而 release/v1.1.x 上 SDK 定版 1.1.0。
**此 commit 不 cherry-pick 到发布分支**（§五：版本号 bump 不跨分支搬）。
|
2026-09-06 09:54:55 +08:00 |
|
|
|
1b4643089c
|
Merge branch 'feature/sdk-multimodal' — 多模态贯通插件边界
公开 SDK 新增媒体字段与媒体注入接口，内核实现对应 RPC 与桥接层，
text/image/audio 三条输入路径归一成一条 processInput 主干。
同步 docs/git-branching.md：SDK 版本语义、beta 不发 SDK、main 永不作发版分支。
存量插件零改动零重编（17 个 example 类型检查通过）。
|
2026-09-06 09:54:03 +08:00 |
|
|
|
8c6b593a54
|
docs(git): SDK 仓版本语义与发版联动，并明确 main 永不作发版分支
三条此前没写进规范、于是被我在实际操作中做错的规则：
## 一、SDK 版本号跟随核心的中版本，patch 位恒为 .0（新 §七.1）
整条核心 1.1.x 线共用 SDK 1.1.0；只有核心进入 1.2.0 这种中版本跃迁时 SDK 才升。
核心的 patch 位专用于 bugfix 与漏洞修复，这类改动不碰公开 SDK 接口，SDK 版本号
没有理由跟着动。
**为什么不逐位对齐**：SDK 版本号是插件开发者的依赖声明。若核心每发一个 bugfix
就给 SDK 推一个新号，开发者要么被迫跟版、要么怀疑自己版本过时，而接口其实一个
字都没变。让 SDK 号只在**接口可能变化的中版本边界**上跳，开发者只需关心「我在
为哪个中版本写插件」。
因此「两仓版本对齐」在本规范里指**中版本对齐**（核心 1.1.x ↔ SDK 1.1.0），
不是三位全等。核心 1.1.1 配 SDK 1.1.0 就是对齐状态。§四 的措辞同步修正。
## 二、beta 阶段不发 SDK（新 §七.2）
核心的 alpha/beta tag 不伴随 SDK 仓发版：SDK 仓在这一阶段不打 tag、不建 release。
**为什么**：beta 是核心自己的测试阶段，此时 SDK 接口尚未固定。若此刻给 SDK 发版，
插件开发者会照着一个还会变的接口写代码——那是无效开发。接口没定就没有可依赖的
契约，发出去的版本号是一个假承诺。
这条约束的对象是 **SDK 仓的发版动作**，不是核心二进制里有没有 SDK 代码。主仓用
`replace => ./third_party/homeagent-sdk`，任何核心构建都必然含 vendored SDK 源码，
那是构建机制决定的，不在约束范围内。
核心打**正式** tag 时 SDK 才随之发版（§七.3）：SDK 仓也有自己的 `release/vX.Y.x`，
定版为 `X.Y.0`，打 tag、建 release、传 5 平台 plugindev 产物。同一中版本内的后续
核心 patch 不重复发 SDK。
## 三、main 永远不是发版分支（补进 §四）
版本号 bump、打 tag、构建产物、上传附件，全部只在 `release/vX.Y.x` 上做。
**即使某个改动刚合进 main、即使 main 此刻可部署，也不从 main 打 tag。**
main 的版本号是「下一个未发布中版本」的路牌，不是任何一次发布的版本号。
这条本该是 §2.1「main 的 meta.Version 始终是下一个未发布版本」的直接推论，但
只写了状态、没写禁令，于是留下了「main 可部署 ⇒ 可以从 main 发版」的误读空间。
§三 的分支表补上 main 现值 `1.2.0` 与 1.1.x 线的 tag 历史，让路牌语义有实例可对。
## 四、公开接口改动是 feature，不是发布准备（补进 §六）
它必须走 `feature/xxx` → 合回 main → cherry-pick 到发布分支，不允许当成「发布
分支上的 bug 修复」直接提交进 release——发布分支冻结功能（§2.3），而接口是最
典型的功能面。§五 补上这条路径的命令示例，以及 SDK 仓同步发版的命令。
|
2026-09-06 09:52:52 +08:00 |
|
|
|
687e5655bc
|
feat(sdk): 多模态贯通插件边界——公开接口、内核桥接与统一输入主干
记忆系统在 1.1.0 支持了二进制多媒体节点，但那条链路只对**内核自己**开放：
用户在 qq 发图能落进 CAS、能被记忆引用，而插件调 Commit / DocMemory().Insert
交进来的媒体一律无处安放。原因是三层都断着，且**每一层都不报错**。
## 一、公开 SDK：补上媒体的表达能力（全部新增，无签名变更）
- `Triple` += `SentenceText`、`MediaDigests`
- `Doc` += `MediaDigests`、`Attachments`；新增 `MediaAttachment`
- `TextEvent` += `Attachments`
- `DocMemoryAPI` += `InsertWithMedia`
- `IOInjector` += `InjectInputMedia` / `InjectInputMediaSync` / `InjectInterruptMedia`
- `PluginSDK` 补上一直缺失的 `SetToolBlocks` 包装（接口里有、便捷方法里没有）
`MediaAttachment` 一个类型服务两个方向：给 `Data`+`MIME` 是新内容（CAS 按字节
去重），只给 `Digest` 是引用已有内容。读路径**只回元数据不回字节**——一次检索
可能命中几十份媒体，全塞回去会把跨进程消息撑爆。
媒体注入不能搭 `SetToolBlocks` 的车：那个方法只在工具处理函数内部可用，且媒体
要等下一条 tool message 才到模型手上。插件主动发起一轮带媒体的对话、以及中断
注入，需要自己的签名，且媒体在**本轮**就送到模型。
## 二、内核桥接层：原先在静默裁字段
`internal/sdk/memory_impl.go` 此前只搬自己认识的几个字段，其余丢弃且返回 nil：
- 图记忆丢 `Confidence`/`SubjectType`/`ObjectType`/`SentenceText`，又走 `Commit`
而非 `CommitWithMedia`（不回 sentenceIDs）→ 媒体绑定链 `SentenceText → sentences
→ sentence_id → media_refs` 一步都走不通，插件即便按格式写好标记也永远挂不上；
- 知识库 `Query` 只回 ID/Title/Content，`Insert` 只写这三个；`Remove` 不解引用，
于是那些媒体永久处于「被引用」状态，GC 收不掉、磁盘只增不减
（内核的归档路径 `releaseDocMedia` 做了这一步，插件路径漏了同一步）。
规则改为：**内部结构有的字段一律透传**。标记格式处理作为包级私有辅助留在桥接
层自己手里，但必须与内核 `mediaSummaryForEvent` 字节兼容——两边要能互读对方
写下的标记。
标记插入必须在 `ds.Insert` **之前**（向量索引取 `Summary + " " + Content`，
之后补的标记检索不到），引用绑定必须在**之后**（owner_id 是 Insert 生成的 ID）。
## 三、跨进程链路：不接线就是全体外部插件编译失败
`go test` 直接把这一层拍出来了——`procIO does not implement sdk.IOInjector`。
公开接口加方法后，生成模板不跟上，**每个外部插件都编不过**，是硬失败不是软降级。
六处接线：`protocol.go` 四个 method 常量、`capability.go` 能力归属、
`corehandler.go` 四个分派分支、`proc_core.go` 委托、`proc_main.go.tmpl` 模板侧
实现、以及三个测试替身。
## 四、统一输入主干：把模态从「函数选择」降级为「字段」
`processTextInput` / `processMediaInput` 合并为 `processInput`。这个分叉是历史
产物而非设计：`processTextInput` 本来就处理媒体（`bindEventMedia` +
`mediaSummaryForEvent`，与媒体路径尾部完全相同），`process()` 只看
`stageCtx.Extra["media_blocks"]`、根本不认识 `evt.Type`。模态是输入的**属性**，
不是输入的**种类**。
媒体路径由此获得它一直缺的六项：去重、`no_memory`、通道 `Cleaner`、中断语义、
`_consolidation_` 路由、正确的 `EventRawInput`。
最后一项是个真 bug：媒体路径发布 `"content": evt.Payload`（一个 map），而
`webui/handler.go` 断言 `.(string)` → 断言失败、`content == ""`、提前返回。
**用户发的图从来没出现在 WebUI 聊天记录里。**
`media_blocks` 同时接受 `[]agentAPI.ContentBlock` 与 `[]pubsdk.ContentBlock`：
字段一致但 Go 不自动转换，只认一种的后果是另一种被静默丢弃。
## 五、模型可调用的三个工具
`memory_commit` 的 `sentence_text` **从未暴露给模型**，而它是绑定链上的必经环节；
连同 `media_digests` 一起补进 JSON schema 与工具文档。`doc_commit` 加
`media_digests`。`doc_query` 把关联媒体单独一行附在结果末尾（正文按 2000 字截断，
标记通常就在尾部）。
标记由**内核**生成而非插件/模型拼装：要求调用方知道格式，等于让一个拼写错误
静默切断引用绑定，而全链路无人报错。
## 六、WebUI 上传走真实媒体链路
图片/音频读回字节拼 data URL 注入 `media_blocks`（8MB 上限，超限退回按路径处理）。
此前只注入一句「文件已保存到 <路径>」，指望模型自己调 `files_read`——但那返回
文本，图片字节对模型永远不可见。附件类型识别扩展到 audio 并在缺 Content-Type
时按扩展名兜底（判错不只是卡片样式问题，图片被当普通文件就进不了视觉链路）。
## 测试
- `internal/sdk/memory_impl_test.go`（12 例，此前该包**没有任何测试文件**）
- `internal/agent/core/inputunify_test.go`（统一主干 + 双静态类型 + 三工具媒体）
- `third_party/homeagent-sdk/sdk/stress_test.go`（13 例并发压测）
压测抓到两处**真**竞态（不是理论风险）：`PluginSDK` 的 API 字段与 `autoRestart`
无锁，而写方（内核注入 API、插件 `SetAutoRestart`）与读方（插件后台 goroutine
注入、内核 registry 读 `AutoRestart`）天然跨 goroutine。加 `apiMu` 修掉；约定
只在持锁期间取字段值，取完即释放再调用——持锁调用会把 `InjectInputSync` 这类
阻塞到 agent 回复（可达数分钟）的方法与 `SetIOInjector` 串起来，让插件重载卡死。
测试还抓出两个自身缺陷：`bindDocMedia` 把同一份媒体数两次（`AddRef` 幂等所以表
是对的，但日志说「绑定 2 个」而实际 1 条——误导后续排查），以及用单字符实体名
时 `validEntityName` 静默跳过、`Commit` 返回 nil 却什么都没写。
存量插件不需要改一行也不需要重编：新增方法由插件调用、内核实现，不调就不受影响。
17 个 example 插件源码零改动通过类型检查。
|
2026-09-06 09:51:31 +08:00 |
|
|
|
e8d12db871
|
fix(packaging): amd64 GUI 从未走过 electron 缓存，且空壳 node_modules 被当作已安装
干净 worktree 上打包时 GUI 被静默跳过。两个缺陷叠加，都属于「所有外层
检查都通过，只有嵌套的运行时缺失，而没有任何东西喊出来」。
## 一：electron 架构名与 Debian 架构名混用
electron 官方发布物命名用 x64/arm64，Debian 用 amd64/arm64。缓存查找
一直统一用 TAR_ARCH（amd64），于是 electron-v*-linux-x64.zip 永远命中
不到。arm64 两边恰好同名，所以上次修 arm64 GUI 架构污染（743b963）时
这个不一致没暴露。
推论：v1.0.3 的 amd64 GUI 实际是靠「回退到 host node_modules/electron/
dist」这条路组装的，不是走缓存——那条回退只在目标架构 == host 架构时
才允许，恰好成立所以没出错。干净 checkout 里没有完整 node_modules，
回退路径也没有，GUI 就消失了。
修法：单独映射 ELECTRON_ARCH（amd64→x64，arm64→arm64）。
## 二：判 node_modules 目录存在，而非判 electron 包存在
npm install 失败（离线/网络受限）会留下只有一两个条目的空壳
node_modules。原判据 [ ! -d node_modules ] 认为「已安装」，于是跳过
install → ever 读不到版本 → 缓存匹配退化到通配 → host dist 也没有 →
静默跳过 GUI。包名、目录名、变体名全部正确，只是没有 GUI。
修法：判据改为 electron/package.json 是否存在；目录在而包缺失时明确
说明「疑似上次 npm install 未完成」再重试；install 失败给出明确提示
而不是继续往下走。
顺带给 ever 加兜底：读不到已安装版本时从 package.json 的依赖声明取
数字部分（那里是 "^33.0.0" 这类范围，仅用于给缓存匹配一个提示）。
## 验证
干净 worktree（/tmp/rel104，release/v1.0.x）上重跑：
node_modules 存在但 electron 缺失（疑似上次 npm install 未完成）
electron 版本取自 package.json 依赖声明: 33.0.0（非精确）
electron runtime: electron-v33.4.11-linux-x64.zip
GUI built: build/homeagent-gui-linux-amd64 (263M, x86-64)
file -b 确认 electron 二进制为 x86-64，与目标架构一致（该硬校验由
743b963 引入，此处继续生效）。
|
2026-09-05 14:58:30 +08:00 |
|
|
|
aac88ce5ee
|
Merge branch 'feature/memory-media' — 记忆系统支持二进制多媒体节点
四层实现 + 五个缺陷修复。方案 B+C（用户选定）：内容寻址存储 + 描述文本
作为持久语义记忆。
## 四层
L1 CAS（internal/memory/media）
元数据进 SQLite，blob 落盘 blobs/ab/cdef…，.tmp + rename 保证不会把
半写文件当完整内容读。Get 每次重验 digest——CAS 的全部保证都建立在
「文件名 == 内容摘要」上，喂一张损坏的图给模型会得到无法追溯的幻觉。
AddRef 幂等且只在真插入时才涨计数（虚高则 GC 永远不敢清理），
DropRef 用 MAX(0, ref_count-1)。GC 两段式 + minAge 保护刚落盘还没来得及
AddRef 的项；被引用的内容即便超容量也永不删除——宁可超限也不能悬空。
L0/L2 接入（internal/agent/core/mediaref.go）
只捕获 data URL：http(s) 会把一次对话变成一次网络请求（超时/鉴权/SSRF）。
digest 先 stage 后 bind——媒体在 process() 期间被捕获，而承载它的
ContextEvent 要等 process() 返回后才 Append，此刻还没有 owner_id。
归档时先 AddRef 到新 owner 再 DropOwner 旧的：反序会让计数瞬时归零，
并发 GC 会把仍被引用的内容当孤儿清掉。
后台循环（internal/agent/core/medialoop.go）
GC 定时清理让容量上限真正生效（此前 max_mb 注册了却无调用方）。
描述生成走后台而非对话路径：视觉模型一次调用生产实测 9.6s，放在对话里
会给每张图的回复加十几秒，而描述的价值是几个月后还能检索到——这一轮
模型本来就直接看着图。逐条而非批量：批量拿回来是一整段文字，无法可靠
切分回各自的 digest。默认关闭，开启后每 30s 最多 4 条。
L3 图库反查（internal/agent/core/graphmedia.go）
只做引用不建描述节点（方案 A）：图库的实体与关系来自描述文本的 NLP
提取，检索能力已具备；若节点名取自描述，描述重新生成后同一张图会留下
多个语义模糊的节点。媒体实体名用「图片 <短digest>」——digest 不变则
名字不变。CommitWithMedia 新增而非改 Commit 签名（后者有 31 个调用点）。
## 五个缺陷
1. rc.SetMediaStore 从未被调用 → L0→L2 引用转移在生产静默失效
2. 三元组全被实体名校验拒绝时仍释放引用并删文档 → 数据丢失
3. 媒体入 L3 依赖 NLP 提取器碰巧提出合规三元组 → 时好时坏
4. L3 媒体检索没有任何调用方 → 能存进去，agent 拿不出来
5. 两处数据竞争（remotedevice bufio.Writer / agentcli 共享读缓冲）
前四个都是「手工调 API 的单测无法发现」的类型：函数正确，但没接上，
或只在理想输入下正确。第 2 个做了反向验证（回退修复后测试确实 FAIL）。
## 验证
medialive 自动触发链实测（-tags medialive，源/模型/密钥由调用方经环境
变量显式指定）：只注入一个 image 事件，七个阶段全由生产代码自己触发。
真实 claude-opus-5 通过——第二轮不给图，agent 答出
「上：紫罗兰色 #8800DD / 中：蓝色 #0055EE / 下：纯红 #EE0000」。
配阴性对照：不给记忆时不该「记得」，否则阳性用例可能只是模型猜配色。
551 篇生产归档文档干跑：媒体正则零误命中；28 篇文档在旧逻辑下会被删除
而信息并未进图库，新逻辑保留。
全仓 go build / go vet / go test / go test -race 全绿，SDK 冻结 diff = 0。
|
2026-09-05 13:56:57 +08:00 |
|
|
|
a7b54fef7f
|
test(memory): 修正数据丢失回归用例的构造——它被媒体三元组修复本身弄失效了
两个修复之间产生了耦合：TestArchiveColdDocs_KeepsDocWhenGraphWriteEmpty
的前提是「三元组全被 validEntityName 拒绝」，而同批引入的
mediaTriplesFromText 会为正文里的 [image/png <digest>] 标记产出合规的
「图片 <digest>」三元组，于是 ec=4 rc=2、绑定成功、释放引用变成正确行为，
用例的前提消失。
（注意当时 GC 断言并未触发——内容没丢，只是"引用被释放"这条断言不再
适用于该构造。）
改法：正文不再含媒体标记，媒体引用直接 AddRef 挂上。这模拟的是更危险的
组合——文档持有媒体引用，但正文里的媒体标记已在清洗中丢失，于是有引用
要释放却没有句子能承载它。那正是这个守卫要防的情形。
反向验证重做后仍成立：回退守卫 → FAIL（引用被释放 + GC 删掉了本该保留的
内容）；恢复修复 → ok。
教训：只跑针对性测试不足以发现修复之间的耦合。提交前我跑的是
internal/agent/core 与 internal/memory，当时通过是因为缺陷二尚未修完；
两个修复都落地后的第一次全仓回归才暴露它。
|
2026-09-05 12:08:33 +08:00 |
|
|
|
387b28ce09
|
fix(memory): 媒体归档三缺陷——数据丢失、L3 入库不可靠、L3 检索未接线
自动触发链实测（medialive）连续暴露的三个缺陷，全部是「手工调 API 的
单测无法发现」的类型。附带该实测本身。
## 缺陷一：三元组全被拒时仍释放引用并删文档（数据丢失）
archiveColdDocs 只检查 len(triples) > 0 就释放媒体引用、删除文档。
但 Commit 会静默跳过实体名不合法的三元组（validEntityName 要求
2–50 字符），于是「无错但一条也没写进去」真实发生：
[agent] doc→graph: doc_xxx → 0 entities, 0 relations
[media] 文档 doc_xxx 入图库，释放 1 个媒体引用（描述已留在图库）
被记忆引用的内容被 GC 删除了（清 1 条/318 字节）
图库里没有任何句子承载引用，文档也被删，blob 被 GC 回收 → 图片与描述
彻底消失。我在上一层写的注释「Commit 之后引用已挂到 graph_sentence」
是错的：ec=0 rc=0 时它什么也没挂。
修法（用户选定 B+A）：
B. ec==0 && rc==0 时保留文档、跳过归档——归档的实质是「信息从 L2
搬到 L3」，搬不过去就不该删源，下轮再试。
A. bindSentenceMedia 返回实际绑定数，commitTriplesWithMedia 透出为
mediaBound；释放前四路判断（查引用出错→保守不释放／本无引用→无需
释放／mediaBound==0→保留并记录原因／否则释放）。宁可留一条悬空
引用（内容还在，可由后续一致性检查清理）也不能丢内容。
反向验证：旧行为下新测试确实 FAIL，报「引用被释放了」+「GC 删掉了本该
保留的内容」；恢复修复后 PASS。
## 缺陷二：媒体入 L3 依赖 NLP 提取器运气（可靠性）
媒体能否进图库，取决于提取器碰巧从描述文本里提出合规三元组。实测 LLM
的 477 字图片描述只产出「水平 -分割-> 成」，obj 仅 1 字被拒 → 整条媒体
记忆进不了图库。表现为「阶段 5 时好时坏」，取决于描述文本。
但媒体自身的 digest / mime / 描述都是确定的，不该受提取器支配。
新增 parseMediaMarkers + mediaTriplesFromText：从文档正文的媒体标记
直接产出确定三元组，先于 NLP 提取。同一份真实文档由 0 entities 0
relations 变为 ec=4 rc=2 且拿到句子 id。
三个设计点：
- 实体名用「图片 <短digest>」而非描述：描述会被重新生成（换视觉模型、
补描述），若名字取自描述，同一张图会在图谱上留下多个节点。digest
不变则名字不变，长度也天然合规。
- SentenceText 用原始标记段，保证 bindSentenceMedia 的正则必然能反解
到 digest——绑定从概率事件变成确定行为。
- 描述为空时仍产出「类型」三元组：描述是后台异步补的，媒体节点不该
因为还没描述就不存在于图谱。
- summarizeForEntity 按 rune 截断而非字节：按字节切会破坏 UTF-8，
图库里会留下乱码实体名。同时清 Markdown 强调符。
这是过渡方案，用户已定：下个 feature 换多模态嵌入后不再依赖
「描述文本 → 提取三元组 → 图谱节点」这条链路。
## 缺陷三：L3 媒体检索没有任何调用方（接线缺失）
第四层实现的 RecallMediaForSentence / mediaContextForSentences 从未被
调用——媒体能存进 L3、能反查，但 agent 拿不出来。实测第二轮 agent 显式
调了 doc_query，回答「没有找到那张图片的任何记录」。
接两个入口：
- buildMemoryContext（自动注入，每次 LLM 调用都走）
- memory_recall 工具结果末尾（显式查询）
关系行只有实体名和关系类型，看不出「这条记忆当时还带了一张图」，
媒体挂在句子上，必须经 关系→句子→media_refs 反查。
一处折返：最初直接用 injected.Relations 取 sentence_id，测试失败。
Indexer.BuildContext 刻意把 Relations 置 nil（自动注入只给实体索引以省
token，细节留给 memory_recall）。改为用命中的实体名再查一次关系，
深度固定 1——媒体是「这条记忆当时带的图」，顺关系网扩散只会带出无关
媒体并挤占 token。
## medialive 自动触发链实测
internal/agent/core/medialive_test.go，medialive build tag，默认
go test 不收录。源/模型/密钥全部由调用方经环境变量显式指定，缺任何一项
Skip 并列出缺哪个——刻意不提供 fallback，猜一个 base_url 可能打到调用者
机器上不相干的服务，而失败会被误报成「媒体记忆有问题」。
MEDIALIVE_BASE_URL=... MEDIALIVE_API_KEY=... \
MEDIALIVE_MODEL=... MEDIALIVE_ADAPTER=... \
go test -tags medialive ./internal/agent/core/ -run TestMediaLive -v
只注入一个 image 事件，之后七个阶段全由生产代码自己触发：CAS 落盘 →
引用绑定 → 描述生成 → L0→L2 转移 → L2→L3 绑定 → GC 保护 → 第二轮召回。
另有阴性对照：不给记忆时不该「记得」，否则阳性用例的通过可能只是模型
猜常见配色。上游不可用时 Skip 而非假 PASS。
真实 claude-opus-5 实测通过：第二轮不给图，agent 答出
「上：紫罗兰色 #8800DD / 中：蓝色 #0055EE / 下：纯红 #EE0000」。
## 测试
graphmedia_test.go 新增 8 例：数据丢失回归（反向验证过）、mediaBound
计数、媒体标记解析、实体名生成、描述截断、确定性三元组必然可入库、
关系→句子映射、L3 检索接线（自动注入与显式查询两路）。
全仓 go build / go vet / go test 通过，internal/agent/core 与
internal/memory 全绿，SDK 冻结 diff = 0。
|
2026-09-05 12:03:30 +08:00 |
|
|
|
775d9e8a2e
|
fix(memory): core.New 漏接 rc.SetMediaStore，L0→L2 引用转移在生产从未生效
RelevanceContext.transferMediaRefs 依赖 c.mediaStore，而该字段只有
SetMediaStore() 能设置。搜遍全仓非测试代码，调用点为零——core.New() 里
没有，cmd/homed/main.go 里也没有。
上一层（f855893）把 AgentConfig.MediaStore 接到了 Agent.mediaStore，
漏了 rc 这一路。
后果是静默的：Prune 归档时 c.mediaStore 为 nil，transferMediaRefs 直接
return，而携带引用的 ContextEvent 已被归档删除 → 引用永久悬空在
context owner 上、计数永不归零 → 对应 blob 永远不会被 GC 回收。
## 为什么测试没抓到
mediaref_test.go 里我手工调了 rc.SetMediaStore(ms) 才测转移逻辑。
**测试验证了函数正确，没验证它被接上了。** 与 findPluginPID 那次同一
个教训：测了一件不会自然发生的事。
## 顺带全字段审计
写脚本比对 AgentConfig 的 32 个字段与 New() 函数体的引用情况，
确认无第二处漏接。
|
2026-09-05 12:02:34 +08:00 |
|
|
|
968b01f26e
|
fix(plugins): 修复隔离全量测试暴露的两处数据竞争
-go test ./... -race 全仓复验暴露的 7 处 race、5 个失败测试，全部定位。
两处独立缺陷，互不相关。
## 缺陷一（remotedevice，8 处 race）：连接写无串行化
WARNING: DATA RACE
Read at 0x... by goroutine 28:
bufio.(*Writer).Available() / writeFrameHeader / PushData
Previous write at 0x... by goroutine 27:
bufio.(*Writer).Flush() / writeFrame / handleWS
同一连接的 bufio.Writer 被两条并发路径写：
- handleWS 主循环：读到设备帧后回写 hello_ack/bind_ack/pong
- PushJSON/PushData：agent→设备的下发路径，可来自任意 goroutine
bufio.Writer 不是线程安全的。不加锁就在 WriteByte/Flush 上撞——这
不是理论风险，TestWSPushDataAudio 的异步 PushData 与 handleWS 的
hello_ack 回写并发时被 -race 稳定抓到。
修法：wconn 增加 wmu（sync.Mutex），PushJSON/PushData 拿锁后整条
下发（start + N 个 chunk + end）持锁——设备侧按协议串行聚合，中途
被插帧会破坏协议顺序。handleWS 的 hello_ack/bind_ack/pong 也改走
同一把锁（wsWriteLocked 封装，避免调用方绕过）。设备已离线时不回写。
关键点：不能只锁 Push* 不锁 handleWS——那只是把竞争挪了个位置。
## 缺陷二（agentcli，1 处 race）：共享读缓冲被并发读写
WARNING: DATA RACE
Write at 0x... by goroutine 26:
os.File.Read / (*linuxPty).Read / reader
Previous read at 0x... by goroutine 25:
runtime.slicecopy / readLoop
readLoop 创建 buf := make([]byte, ReadBufSize) 传给 reader goroutine
（t.session.Read(buf) 持续覆写），自己又在读到结果后
copy(data, buf[:r.n])——同一缓冲被读写并发。Go 的 pty 读走 OS 层
fd，专门在 reader 写下一段时读，跑 -race 稳定复现。
修法：readResult 携带 data field，reader 每次读完后把数据复制进自己
分配的切片再随结果传递，读取与拷贝之间不再共享任何可变状态。原 buf
保留（仍由 reader 独享用于 OS 读），readLoop 不再从其中 copy。
## 验证
- 两个插件包 -race -count=2 全过
- 全仓 go build / go vet / go test 通过
- 全仓 go test ./... -race：32 包全过，0 DATA RACE，0 FAIL
- SDK 冻结 diff = 0
其中 remotedevice 的 TestScreenseeEndToEnd / TestComputeruseEndToEnd
/ TestClipboardEndToEnd 原本因 race 挂，修后恢复全绿。
|
2026-09-05 07:26:10 +08:00 |
|
|
|
6190a5a587
|
fix(plugins): 修复隔离全量测试暴露的两处数据竞争
-go test ./... -race 全仓复验暴露的 7 处 race、5 个失败测试，全部定位。
两处独立缺陷，互不相关。
## 缺陷一（remotedevice，8 处 race）：连接写无串行化
WARNING: DATA RACE
Read at 0x... by goroutine 28:
bufio.(*Writer).Available() / writeFrameHeader / PushData
Previous write at 0x... by goroutine 27:
bufio.(*Writer).Flush() / writeFrame / handleWS
同一连接的 bufio.Writer 被两条并发路径写：
- handleWS 主循环：读到设备帧后回写 hello_ack/bind_ack/pong
- PushJSON/PushData：agent→设备的下发路径，可来自任意 goroutine
bufio.Writer 不是线程安全的。不加锁就在 WriteByte/Flush 上撞——这
不是理论风险，TestWSPushDataAudio 的异步 PushData 与 handleWS 的
hello_ack 回写并发时被 -race 稳定抓到。
修法：wconn 增加 wmu（sync.Mutex），PushJSON/PushData 拿锁后整条
下发（start + N 个 chunk + end）持锁——设备侧按协议串行聚合，中途
被插帧会破坏协议顺序。handleWS 的 hello_ack/bind_ack/pong 也改走
同一把锁（wsWriteLocked 封装，避免调用方绕过）。设备已离线时不回写。
关键点：不能只锁 Push* 不锁 handleWS——那只是把竞争挪了个位置。
## 缺陷二（agentcli，1 处 race）：共享读缓冲被并发读写
WARNING: DATA RACE
Write at 0x... by goroutine 26:
os.File.Read / (*linuxPty).Read / reader
Previous read at 0x... by goroutine 25:
runtime.slicecopy / readLoop
readLoop 创建 buf := make([]byte, ReadBufSize) 传给 reader goroutine
（t.session.Read(buf) 持续覆写），自己又在读到结果后
copy(data, buf[:r.n])——同一缓冲被读写并发。Go 的 pty 读走 OS 层
fd，专门在 reader 写下一段时读，跑 -race 稳定复现。
修法：readResult 携带 data field，reader 每次读完后把数据复制进自己
分配的切片再随结果传递，读取与拷贝之间不再共享任何可变状态。原 buf
保留（仍由 reader 独享用于 OS 读），readLoop 不再从其中 copy。
## 验证
- 两个插件包 -race -count=2 全过
- 全仓 go build / go vet / go test 通过
- 全仓 go test ./... -race：32 包全过，0 DATA RACE，0 FAIL
- SDK 冻结 diff = 0
其中 remotedevice 的 TestScreenseeEndToEnd / TestComputeruseEndToEnd
/ TestClipboardEndToEnd 原本因 race 挂，修后恢复全绿。
|
2026-09-05 05:53:17 +08:00 |
|
|
|
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 |
|
|
|
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 |
|
