|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
653dd34299
|
feat: 插件工具按需拉取(get_plugin_tools) + 设备命令类型拆分(shell-cmd/homeagent-cmd)
1. 提示词去污染: buildToolCatalog 从全量工具定义改为按插件分组摘要
(插件名 + 工具数 + 能力概览), 完整工具定义由新工具 get_plugin_tools(plugin_name)
动态拉取; 新增 executeGetPluginTools 支持按插件过滤 stageHost/io 工具
2. 设备命令类型: device_ctl_cmdrun 的 command 支持前缀区分
- shell-cmd <cmd> -> 设备端执行原生 shell
- homeagent-<cap> -> 设备端 HomeAgent 内置能力(如 camerasue/screensue)
- homeagent-cmd <cap> -> 同上(兼容写法)
PushCmd 增加 cmd_type 字段下发给设备端分发
3. 测试: TestExecuteGetPluginTools 验证按插件拉取/全部摘要/未知插件
|
2026-08-18 09:07:21 +08:00 |
|
|
|
db4844c6c6
|
fix(memory_recall): add jieba keyword extraction for natural language queries
|
2026-07-25 18:27:36 +08:00 |
|
|
|
634c3ff4ad
|
fix: doc_query chronological insert, register cli/webui output channels
- context.go: add InsertByTimestamp for chronological context insertion
- toolcall.go: doc_query uses InsertByTimestamp instead of Append
- agent_tools_test.go: update tests to use payload/type keys
- cli/plugin.go: register output_send__cli channel
- webui/plugin.go: register output_send__webui channel
|
2026-07-25 16:25:06 +08:00 |
|
|
|
85992902d9
|
refactor: split agent.go into 12 files + add mcp_restart_server tool
|
2026-07-22 15:40:27 +08:00 |
|
