mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-20 08:58:03 +00:00
feat(sdk): 多模态贯通插件边界——媒体字段、媒体注入接口与并发修复
记忆系统在核心 1.1.0 支持了二进制多媒体节点，但那条链路只对**内核自己**开放： 插件把 Triple / Doc 交进来，媒体一律无处安放，且**不报错**。本版补上公开接口 侧缺失的表达能力。 ## 一、类型与接口（全部新增，无签名变更） - `Triple` += `SentenceText`、`MediaDigests` - `Doc` += `MediaDigests`、`Attachments`；新增 `MediaAttachment` - `TextEvent` += `Attachments` - `DocMemoryAPI` += `InsertWithMedia` - `IOInjector` += `InjectInputMedia` / `InjectInputMediaSync` / `InjectInterruptMedia` - `PluginSDK` 补上一直缺失的 `SetToolBlocks` 包装（接口里有、便捷方法里没有， 插件只能自己去拿 injector） `MediaAttachment` 一个类型服务两个方向：给 `Data`+`MIME` 是新内容（内核按字节 去重），只给 `Digest` 是引用已有内容。读路径**只回元数据不回字节**——一次检索 可能命中几十份媒体，把字节全塞回来会撑爆跨进程消息。 媒体注入为什么不能搭 `SetToolBlocks` 的车：那个方法只在工具处理函数内部可用， 且媒体要等**下一条** tool message 才到模型手上。插件主动发起一轮带媒体的对话、 以及中断注入，需要各自的签名，且媒体在**本轮**就随消息发出。 `Triple.MediaDigests` 非空而 `SentenceText` 为空时，内核会用媒体标记本身充当句子 ——媒体引用挂在句子上，没有句子就无处挂起。插件只需填 digest，标记由内核拼： 要求调用方知道格式，等于让一个拼写错误静默切断引用绑定而全链路无人报错。 ## 二、修掉两处并发竞态 `sdk/stress_test.go` 的 `-race` 实测报 11 处 DATA RACE，收敛到两个字段： 1. **`PluginSDK` 的 API 字段无锁**。写方是内核（加载/重载插件时依次注入 injector、memory、doc、llm…），读方是插件在 `Start()` 里起的后台 goroutine ——轮询、监听、定时器都要拿 injector 往管道注消息。生产表现是插件重载瞬间 偶发崩溃：读到半个接口值就 nil 解引用。 2. **`autoRestart` 标志无锁**。`SetAutoRestart` 的文档用法本身就是「外部连接建好 后再决定能否自动重启」，而连接建立通常在后台 goroutine；内核 registry 在另一个 goroutine 读 `AutoRestart()` 决定崩溃后重启策略。这对读写天然跨 goroutine。 加 `apiMu sync.RWMutex`。关键约定写进注释：**只在持锁期间取字段值，取完立刻 释放再调用**。持锁调用会把 `InjectInputSync`（阻塞到 agent 回复，可达数分钟） 与 `SetIOInjector` 串到一起，让插件重载卡死。 ## 三、压测（sdk/stress_test.go，13 例） SDK 是被多个 goroutine 同时使用的共享对象，单线程单测全绿不代表并发路径成立。 断言的是不变量而非吞吐： - 媒体注入高并发不丢不串——每次调用带唯一 tag，逐条校验文本与图片 URL 配对。 「不串」是重点：若实现里出现任何共享中间状态（把 blocks 暂存到字段再读出）， 高并发下会出现 A 的文本配 B 的图，而两者单独看都「成功」了； - injector 热替换（含替换成 nil，即内核卸载 API 的真实状态）； - stop / onRemove handler 恰好一次——契约是「执行后清空，幂等」，执行两次的后果 从重复写文件到 close 已关闭 channel 直接 panic； - `StageContext` 并发读改写无 lost update（媒体链路让 Extra 成为新热点， 而 map 并发写在 Go 里是直接 fatal，recover 接不住）； - `OwnTools` scope 不跨插件泄漏； - 媒体类型 JSON 往返字节级一致（9 种长度，含 0/1/2/3 与 base64 分组边界） ——`[]byte` 在 JSON 里是 base64，往返不一致意味着图片静默损坏， 要到 CAS 校验 digest 时才发现，那时已无从追查； - `omitempty` 真的生效（读路径不能出现 `"data"` 键）； - nil 依赖全部静默降级不 panic。 ## 四、工具链同步 - `proc_main.go.tmpl`：`procIO` 三个媒体方法、`procDocMemory.InsertWithMedia`。 模板不跟上的后果是**每个外部插件都编不过**（接口未实现），是硬失败； - `proc_runtime_test.go`：方法清单补 `io.injectMedia*` 与 `doc.insertWithMedia`。 漏接线时插件调 `InjectInputMedia` 会静默无效果——模板不发这个 RPC，内核也就 收不到，两边都不报错； - `yaegi/mocksdk`：与公开 SDK 对齐。它此前漂移严重且**没有任何代码对着它编译**， 所以漂移不会被编译器抓到：`Triple` 用的是 `Predicate`，而公开 SDK 一直叫 `Relation` —— 插件在 yaegi 调试期写 `Relation:` 报未知字段，写 `Predicate:` 则 编成 plugin.bin 时报错，两边都不对。 - README 中英双语补媒体接口文档与用法示例。 ## 兼容性 存量插件不需要改一行也不需要重编：新增方法由**插件调用、内核实现**，不调就不 受影响。17 个 example 插件源码零改动通过类型检查；用 SDK 0.9.2 编的旧 plugin.bin 在新内核上直接建链通过（握手校验的是 ProtocolVersion=1，不是 SDK 版本）。 媒体接口需要核心 1.1.1+（更早的核心没有对应 RPC，调用返回 unknown method）。 `CoreVersion` 保持 1.0.0：它是「SDK 能在其上运行」的下限，媒体是可选能力。
This commit is contained in:
JianFeeeee
@ -95,12 +95,17 @@ func TestProcTemplate_CoversAllCoreMethods(t *testing.T) {
|
||||
// IO 注入
|
||||
"io.injectText", "io.injectInterrupt", "io.injectTextNoMem", "io.injectInputSync",
|
||||
"io.setToolBlocks",
|
||||
// 多模态注入（1.1.0 新增）。漏接线的后果是插件调 InjectInputMedia 静默无效果：
|
||||
// 模板不发这个 RPC，内核也就永远收不到，而两边都不报错。
|
||||
"io.injectMedia", "io.injectMediaSync", "io.injectInterruptMedia",
|
||||
// 生命周期
|
||||
"lifecycle.autoRestart",
|
||||
// 图记忆
|
||||
"memory.recall", "memory.commit", "memory.introspect", "memory.merge", "memory.purge",
|
||||
// 文档记忆
|
||||
"doc.query", "doc.insert", "doc.remove", "doc.stats",
|
||||
// 文档媒体（1.1.0 新增）
|
||||
"doc.insertWithMedia",
|
||||
// 知识库
|
||||
"knowledge.search", "knowledge.add", "knowledge.list",
|
||||
// 文本记忆
|
||||
|
||||
@ -490,6 +490,34 @@ func (procIO) SetToolBlocks(blocks []sdk.ContentBlock) {
|
||||
}
|
||||
}
|
||||
|
||||
// 带媒体的注入：插件主动发起一轮带图/音频的对话。
|
||||
// 与 SetToolBlocks 的区别是媒体在**本轮**就到模型手上，而不是等下一条 tool message。
|
||||
func (procIO) InjectInputMedia(s, c, t string, blocks []sdk.ContentBlock) {
|
||||
callCoreVoid("io.injectMedia", map[string]interface{}{
|
||||
"source": s, "channel": c, "text": t, "blocks": blocks,
|
||||
})
|
||||
}
|
||||
|
||||
func (procIO) InjectInputMediaSync(s, c, t string, blocks []sdk.ContentBlock) string {
|
||||
raw, err := callCore("io.injectMediaSync", map[string]interface{}{
|
||||
"source": s, "channel": c, "text": t, "blocks": blocks,
|
||||
})
|
||||
if err != nil {
|
||||
return ""
|
||||
}
|
||||
var r struct {
|
||||
Reply string `json:"reply"`
|
||||
}
|
||||
json.Unmarshal(raw, &r)
|
||||
return r.Reply
|
||||
}
|
||||
|
||||
func (procIO) InjectInterruptMedia(s, c, t string, blocks []sdk.ContentBlock) {
|
||||
callCoreVoid("io.injectInterruptMedia", map[string]interface{}{
|
||||
"source": s, "channel": c, "text": t, "blocks": blocks,
|
||||
})
|
||||
}
|
||||
|
||||
type procMemory struct{}
|
||||
|
||||
func (procMemory) Recall(q []string, d int) ([]sdk.Entity, []sdk.Relation, error) {
|
||||
@ -557,6 +585,26 @@ func (procDocMemory) Query(text string, topK int) []*sdk.Doc {
|
||||
func (procDocMemory) Insert(d *sdk.Doc) error {
|
||||
return callCoreVoid("doc.insert", map[string]interface{}{"doc": d})
|
||||
}
|
||||
|
||||
// InsertWithMedia 写入文档并关联媒体。
|
||||
//
|
||||
// 内核会把 `[mime <短digest>] <描述>` 标记补进 Content 并挂上引用，回传的
|
||||
// doc 带着补好的 Content/ID/MediaDigests——回写进 d 让调用方能拿到这些。
|
||||
func (procDocMemory) InsertWithMedia(d *sdk.Doc, atts []sdk.MediaAttachment) error {
|
||||
raw, err := callCore("doc.insertWithMedia", map[string]interface{}{
|
||||
"doc": d, "attachments": atts,
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
var r struct {
|
||||
Doc *sdk.Doc `json:"doc"`
|
||||
}
|
||||
if json.Unmarshal(raw, &r) == nil && r.Doc != nil {
|
||||
*d = *r.Doc
|
||||
}
|
||||
return nil
|
||||
}
|
||||
func (procDocMemory) Remove(id string) {
|
||||
callCoreVoid("doc.remove", map[string]string{"id": id})
|
||||
}
|
||||
|
||||
@ -95,6 +95,29 @@ type IOInjector interface {
|
||||
InjectInterruptText(source, channel, text string)
|
||||
InjectText(source, channel, text string)
|
||||
InjectTextNoMemory(source, channel, text string)
|
||||
// 1.1.0 媒体注入。与公共 SDK 同构：插件在 yaegi 下调得通的方法，
|
||||
// 编成 plugin.bin 后必须也调得通，否则调试期与真实运行行为不一致。
|
||||
InjectInputMedia(source, channel, text string, blocks []ContentBlock)
|
||||
InjectInputMediaSync(source, channel, text string, blocks []ContentBlock) string
|
||||
InjectInterruptMedia(source, channel, text string, blocks []ContentBlock)
|
||||
SetToolBlocks(blocks []ContentBlock)
|
||||
}
|
||||
|
||||
// ContentBlock 与公共 SDK 同构（OpenAI 多模态内容块格式）。
|
||||
type ContentBlock struct {
|
||||
Type string `json:"type"`
|
||||
Text string `json:"text,omitempty"`
|
||||
ImageURL *ImageURL `json:"image_url,omitempty"`
|
||||
AudioURL *AudioURL `json:"audio_url,omitempty"`
|
||||
}
|
||||
|
||||
type ImageURL struct {
|
||||
URL string `json:"url"`
|
||||
Detail string `json:"detail,omitempty"`
|
||||
}
|
||||
|
||||
type AudioURL struct {
|
||||
URL string `json:"url"`
|
||||
}
|
||||
|
||||
type EventType string
|
||||
@ -159,29 +182,33 @@ type mockSettings struct{ data map[string]interface{} }
|
||||
|
||||
func (s *mockSettings) Get(key string) (interface{}, error) {
|
||||
v, ok := s.data[key]
|
||||
if !ok { return nil, nil }
|
||||
if !ok {
|
||||
return nil, nil
|
||||
}
|
||||
return v, nil
|
||||
}
|
||||
func (s *mockSettings) Set(key string, value interface{}) error { s.data[key] = value; return nil }
|
||||
func (s *mockSettings) List(prefix string) ([]string, error) {
|
||||
var ks []string
|
||||
for k := range s.data {
|
||||
if strings.HasPrefix(k, prefix) { ks = append(ks, k) }
|
||||
if strings.HasPrefix(k, prefix) {
|
||||
ks = append(ks, k)
|
||||
}
|
||||
}
|
||||
return ks, nil
|
||||
}
|
||||
func (s *mockSettings) GetCore(key string) (interface{}, error) { return nil, nil }
|
||||
func (s *mockSettings) SetCore(key string, value interface{}) error { return nil }
|
||||
func (s *mockSettings) ListCore(prefix string) ([]string, error) { return nil, nil }
|
||||
func (s *mockSettings) GetPlugin(p, k string) (interface{}, error) { return nil, nil }
|
||||
func (s *mockSettings) SetPlugin(p, k string, v interface{}) error { return nil }
|
||||
func (s *mockSettings) GetCore(key string) (interface{}, error) { return nil, nil }
|
||||
func (s *mockSettings) SetCore(key string, value interface{}) error { return nil }
|
||||
func (s *mockSettings) ListCore(prefix string) ([]string, error) { return nil, nil }
|
||||
func (s *mockSettings) GetPlugin(p, k string) (interface{}, error) { return nil, nil }
|
||||
func (s *mockSettings) SetPlugin(p, k string, v interface{}) error { return nil }
|
||||
func (s *mockSettings) ListPlugin(p, prefix string) ([]string, error) { return nil, nil }
|
||||
func (s *mockSettings) RegisterDef(def ConfigDef) {
|
||||
logf("config def: %s = %s", def.Key, def.Default)
|
||||
}
|
||||
func (s *mockSettings) Defs(prefix string) []*ConfigDef { return nil }
|
||||
func (s *mockSettings) Dump() map[string]interface{} { return s.data }
|
||||
func (s *mockSettings) Plugins() []string { return nil }
|
||||
func (s *mockSettings) Dump() map[string]interface{} { return s.data }
|
||||
func (s *mockSettings) Plugins() []string { return nil }
|
||||
|
||||
type Entity struct {
|
||||
Name string `json:"name"`
|
||||
@ -195,10 +222,21 @@ type Relation struct {
|
||||
Object string `json:"object"`
|
||||
}
|
||||
|
||||
// Triple 与公共 SDK 同构。
|
||||
//
|
||||
// ❗字段名曾是 `Predicate`，而公共 SDK 一直叫 `Relation`。
|
||||
// yaegi 解释器下插件写 `Relation:` 会报未知字段，写 `Predicate:` 则在
|
||||
// 编成 plugin.bin 时报错——谁都不对。没人发现是因为没有任何代码
|
||||
// 对着 mocksdk 编译，漂移不会被编译器抓到。
|
||||
type Triple struct {
|
||||
Subject string `json:"subject"`
|
||||
Predicate string `json:"predicate"`
|
||||
Object string `json:"object"`
|
||||
Subject string `json:"subject"`
|
||||
Relation string `json:"relation"`
|
||||
Object string `json:"object"`
|
||||
Confidence float64 `json:"confidence,omitempty"`
|
||||
SubjectType string `json:"subject_type,omitempty"`
|
||||
ObjectType string `json:"object_type,omitempty"`
|
||||
SentenceText string `json:"sentence_text,omitempty"`
|
||||
MediaDigests []string `json:"media_digests,omitempty"`
|
||||
}
|
||||
|
||||
type MemoryAPI interface {
|
||||
@ -212,37 +250,57 @@ type MemoryAPI interface {
|
||||
type mockMemory struct{}
|
||||
|
||||
func (mockMemory) Recall(q []string, d int) ([]Entity, []Relation, error) { return nil, nil, nil }
|
||||
func (mockMemory) Commit(t []Triple) error { return nil }
|
||||
func (mockMemory) Introspect() (map[string]interface{}, error) { return map[string]interface{}{}, nil }
|
||||
func (mockMemory) MergeEntities(s, t string) (int, error) { return 0, nil }
|
||||
func (mockMemory) Purge(c map[string]string, m string) (int, error) { return 0, nil }
|
||||
func (mockMemory) Commit(t []Triple) error { return nil }
|
||||
func (mockMemory) Introspect() (map[string]interface{}, error) { return map[string]interface{}{}, nil }
|
||||
func (mockMemory) MergeEntities(s, t string) (int, error) { return 0, nil }
|
||||
func (mockMemory) Purge(c map[string]string, m string) (int, error) { return 0, nil }
|
||||
|
||||
type Doc struct {
|
||||
ID string `json:"id"`
|
||||
Title string `json:"title"`
|
||||
Content string `json:"content"`
|
||||
Source string `json:"source"`
|
||||
// 1.1.0：媒体字段。与公共 SDK 保持同构，否则插件在 yaegi 下跑得通、
|
||||
// 编成 plugin.bin 却编不过（或反之）。
|
||||
MediaDigests []string `json:"media_digests,omitempty"`
|
||||
Attachments []MediaAttachment `json:"attachments,omitempty"`
|
||||
}
|
||||
|
||||
// MediaAttachment 与公共 SDK 同构：写入时给 Data+MIME，引用已有内容时只给 Digest。
|
||||
type MediaAttachment struct {
|
||||
Digest string `json:"digest,omitempty"`
|
||||
MIME string `json:"mime,omitempty"`
|
||||
Data []byte `json:"data,omitempty"`
|
||||
Name string `json:"name,omitempty"`
|
||||
Description string `json:"description,omitempty"`
|
||||
}
|
||||
|
||||
type DocMemoryAPI interface {
|
||||
Query(text string, topK int) []*Doc
|
||||
Insert(doc *Doc) error
|
||||
InsertWithMedia(doc *Doc, attachments []MediaAttachment) error
|
||||
Remove(id string)
|
||||
Stats() map[string]interface{}
|
||||
}
|
||||
|
||||
type mockDocMemory struct{}
|
||||
|
||||
func (mockDocMemory) Query(t string, k int) []*Doc { return nil }
|
||||
func (mockDocMemory) Insert(doc *Doc) error { return nil }
|
||||
func (mockDocMemory) Remove(id string) {}
|
||||
func (mockDocMemory) Stats() map[string]interface{} { return nil }
|
||||
func (mockDocMemory) Query(t string, k int) []*Doc { return nil }
|
||||
func (mockDocMemory) Insert(doc *Doc) error { return nil }
|
||||
func (mockDocMemory) InsertWithMedia(doc *Doc, atts []MediaAttachment) error {
|
||||
logf("doc_insert_with_media: %d 份附件", len(atts))
|
||||
return nil
|
||||
}
|
||||
func (mockDocMemory) Remove(id string) {}
|
||||
func (mockDocMemory) Stats() map[string]interface{} { return nil }
|
||||
|
||||
type TextEvent struct {
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
Role string `json:"role"`
|
||||
Content string `json:"content"`
|
||||
Source string `json:"source"`
|
||||
// 1.1.0：附件。读回时内核从正文标记反解，写入时内核把标记并进正文。
|
||||
Attachments []MediaAttachment `json:"attachments,omitempty"`
|
||||
}
|
||||
|
||||
type TextMemoryAPI interface {
|
||||
@ -305,8 +363,8 @@ type LLMAPI interface {
|
||||
type mockLLM struct{}
|
||||
|
||||
func (mockLLM) ListSources() []string { return nil }
|
||||
func (mockLLM) SetSource(n string) error { return nil }
|
||||
func (mockLLM) CurrentSource() string { return "" }
|
||||
func (mockLLM) SetSource(n string) error { return nil }
|
||||
func (mockLLM) CurrentSource() string { return "" }
|
||||
|
||||
type IOInjectorImpl struct{}
|
||||
|
||||
@ -319,27 +377,40 @@ func (IOInjectorImpl) InjectText(source, channel, text string) {
|
||||
func (IOInjectorImpl) InjectTextNoMemory(source, channel, text string) {
|
||||
logf("inject_text_no_memory: source=%s channel=%s", source, channel)
|
||||
}
|
||||
func (IOInjectorImpl) InjectInputMedia(source, channel, text string, blocks []ContentBlock) {
|
||||
logf("inject_input_media: source=%s channel=%s blocks=%d", source, channel, len(blocks))
|
||||
}
|
||||
func (IOInjectorImpl) InjectInputMediaSync(source, channel, text string, blocks []ContentBlock) string {
|
||||
logf("inject_input_media_sync: source=%s channel=%s blocks=%d", source, channel, len(blocks))
|
||||
return ""
|
||||
}
|
||||
func (IOInjectorImpl) InjectInterruptMedia(source, channel, text string, blocks []ContentBlock) {
|
||||
logf("inject_interrupt_media: source=%s channel=%s blocks=%d", source, channel, len(blocks))
|
||||
}
|
||||
func (IOInjectorImpl) SetToolBlocks(blocks []ContentBlock) {
|
||||
logf("set_tool_blocks: blocks=%d", len(blocks))
|
||||
}
|
||||
|
||||
type PluginSDK struct {
|
||||
Name string
|
||||
mu sync.RWMutex
|
||||
toolDefs map[string]ToolDef
|
||||
toolHandlers map[string]ToolHandler
|
||||
Name string
|
||||
mu sync.RWMutex
|
||||
toolDefs map[string]ToolDef
|
||||
toolHandlers map[string]ToolHandler
|
||||
stageHandlers map[string]StageHandler
|
||||
outChannels map[string]ToolHandler
|
||||
Settings SettingsAPI
|
||||
IO IOInjector
|
||||
outChannels map[string]ToolHandler
|
||||
Settings SettingsAPI
|
||||
IO IOInjector
|
||||
}
|
||||
|
||||
func New(name string) *PluginSDK {
|
||||
return &PluginSDK{
|
||||
Name: name,
|
||||
toolDefs: make(map[string]ToolDef),
|
||||
toolHandlers: make(map[string]ToolHandler),
|
||||
Name: name,
|
||||
toolDefs: make(map[string]ToolDef),
|
||||
toolHandlers: make(map[string]ToolHandler),
|
||||
stageHandlers: make(map[string]StageHandler),
|
||||
outChannels: make(map[string]ToolHandler),
|
||||
Settings: &mockSettings{data: map[string]interface{}{}},
|
||||
IO: IOInjectorImpl{},
|
||||
outChannels: make(map[string]ToolHandler),
|
||||
Settings: &mockSettings{data: map[string]interface{}{}},
|
||||
IO: IOInjectorImpl{},
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user