mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-10-15 12:15:16 +00:00
feat(multimodal): 多模态工具移出内核为内置插件 + get_plugin_tools 收编为内核服务
## 背景 README 第一原则:「内核职责限定在 LLM 编排、记忆管理与知识检索; 所有 IO 能力由插件实现」,而「文件读取」正在 IO 列表里。 describe_image / ocr_image / transcribe_audio 读本地文件却住在内核进程内 ——无沙箱、无能力面、无审计,正是 capability.go 那套权限梯度要防的事。 ## 本次改动 ### 1. 多模态工具移出内核(internal/plugins/multimodal) - 新增内置插件,注册 describe_image / transcribe_audio / ocr_image - 媒体来源支持 path(设备/工具回传,如 screensee 的 file)与 digest(CAS) - 失败一律以 error 上抛,不渲染成普通文本(延续 screensee 的失败传播纪律) - ocr_image 的描述明说「不是专用 OCR 引擎」:它只是用视觉模型读字, 真 OCR 在 internal/nlp 的 ONNX 未接入。名字承诺大于实现会让模型误判精度。 内核侧:删除 media.go 整文件(9 函数,全部零引用)、3 个 dispatch case、 3 个工具定义。 **留在内核**:input 通路(用户直传媒体直接拼进本轮 LLM 请求)—— 那是「输入即上下文」,不是工具调用。 ### 2. get_plugin_tools 收编为内核完整服务 原先它只收 StageHost + IOManager 两处,而三个媒体工具、memory_*、 knowledge_*、spawn_child 等全是内核 buildToolDefs 里直接 append 的 ——一条都数不到。agent 能调这些工具,却调 get_plugin_tools 看不见它们。 - 以 buildToolDefs()(发给模型的那份工具表)为单一真相源 - 新增 builtinToolOwner 显式归属表:内置工具恒为 core - resolveToolPlugin 的下划线前缀猜测限定在「该前缀是已注册插件」时才采纳, 避免 ocr_image→"ocr"、memory_commit→"memory" 这类幽灵归属(7 处调用点依赖它) ## 判据 新增 plugin_tools_service_test.go、multimodal_departed_test.go、 multimodal/plugin_test.go。三个结构判据经变异自证会红: 1. 提示词改回「请使用 describe_image 工具」→ 仍出现该名 ⇒ 红 ★ 这条抓到了真问题:eventloop.go 的媒体提示词仍在叫模型调旧工具名, 而媒体 block 其实已内联给模型,且新工具需要 path/digest(用户直传都没有) ⇒ 模型照做必然失败。已修:改为「已随本消息附上,请直接查看」。 2. 内核为多模态加一个 os.ReadFile → 红(比「名字没出现」更强) 3. core 反向 import 插件 → 红(迁移而非删除,且守住分层) ## 验证 - go build ./... / go vet / go test ./internal/... 全绿 - go test -race ./internal/agent/core/ ./internal/plugins/multimodal/ 无数据竞争 - 部署后:39 插件加载、0 panic/fatal、0 非空 error - 三个工具注册归属为 plugin=multimodal(不是 inferToolPlugin 猜的 describe) - graph.db integrity ok,blocks 2787 / relations 980 未动 - 快照 /home/newqqagent/memory/pre-multimodal-plugin-20261006-090541/ - 二进制备份 /tmp/homed.bak-mmplugin 一并包含此前已验证未提交的三处静默失效修复: - MCP MCPCallResult.IsError 丢失(空结果伪装成功) - DeleteEntity 谎报删除 - screensee 谎报成功 + 截图诊断(尺寸/magic/sha) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@ -318,9 +318,28 @@ func (p *Plugin) handleDevicePush(w http.ResponseWriter, r *http.Request) {
|
||||
|
||||
// describeScreen 用视觉模型描述设备屏幕截图(screensee 回调)。
|
||||
// provider 为空时使用默认 LLM 源;模型不支持视觉时返回友好错误。
|
||||
func (p *Plugin) describeScreen(dataURL string, provider string) string {
|
||||
// describeScreen 把设备回传的屏幕截图交给视觉模型生成描述。
|
||||
//
|
||||
// ★★ 2026-10-05 签名改为 (string, error)(生产日志实证的教训)
|
||||
//
|
||||
// 原实现把 403 等**失败**渲染成一段普通文本返回:
|
||||
//
|
||||
// return fmt.Sprintf("屏幕截图视觉描述失败: %v(当前模型可能不支持图像输入)", err)
|
||||
//
|
||||
// 而调用方把它当作 description 字段、status=ok ⇒ **失败被包装成成功**。
|
||||
// 实测(2026-10-05 13:51):
|
||||
//
|
||||
// {"description":"屏幕截图视觉描述失败: api error 403:
|
||||
// {\"error\":{\"message\":\"model \"gpt-5.6-sol\" is not allowed…"}
|
||||
//
|
||||
// agent 读到的是一段自然语言,看不出这是工具失败,
|
||||
// 于是又发了一次 screensee(换 provider)再失败一次。
|
||||
// 与同一天修掉的 MCP `isError` 丢失是**同一个病**:失败与成功同形。
|
||||
//
|
||||
// ⇒ 失败必须以 error 上抛,文本只留作诊断线索。
|
||||
func (p *Plugin) describeScreen(dataURL string, provider string) (string, error) {
|
||||
if p.sdk == nil || p.sdk.LLM() == nil {
|
||||
return "LLM 不可用,无法描述屏幕内容"
|
||||
return "", fmt.Errorf("LLM 不可用,无法描述屏幕内容")
|
||||
}
|
||||
llm := p.sdk.LLM()
|
||||
req := &sdk.LLMCompletionRequest{
|
||||
@ -337,18 +356,60 @@ func (p *Plugin) describeScreen(dataURL string, provider string) string {
|
||||
if provider != "" {
|
||||
prev := llm.CurrentSource()
|
||||
if err := llm.SetSource(provider); err != nil {
|
||||
log.Printf("[remotedevice] screensee set source %s: %v", provider, err)
|
||||
// ★ 切源失败**不降级**:原来只打一行日志然后继续用当前源,
|
||||
// 而当前源可能与调用方指定的完全不同 ⇒ 模型看到的是
|
||||
// 「另一个源的结果」,却挂在指定源名下。直接报错更诚实。
|
||||
return "", fmt.Errorf("screensee: 切换到指定视觉源 %s 失败: %w", provider, err)
|
||||
} else if prev != "" {
|
||||
defer func() { _ = llm.SetSource(prev) }()
|
||||
}
|
||||
}
|
||||
// ★ 记录本次实际用的是哪个源:排查「为什么描述不对」时,
|
||||
// 第一件要知道的就是它到底是哪个源在回答。
|
||||
usedSource := llm.CurrentSource()
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
|
||||
defer cancel()
|
||||
resp, err := llm.Chat(ctx, req)
|
||||
if err != nil {
|
||||
return fmt.Sprintf("屏幕截图视觉描述失败: %v(当前模型可能不支持图像输入)", err)
|
||||
log.Printf("[remotedevice] screensee 视觉描述失败 source=%s err=%v", usedSource, err)
|
||||
// ★ 2026-10-05:模型名不被接受时,**就地降级到 AUTO 重试一次**。
|
||||
//
|
||||
// 生产实测(13:51):agent 传 provider=visionllm,而那个源的
|
||||
// `model: gpt-5.6-sol` 被 llmsproxy 拒了:
|
||||
//
|
||||
// model "gpt-5.6-sol" is not allowed for this key
|
||||
//
|
||||
// 根因不是「模型不支持图」,而是**那个 key 的 model scope 只有 AUTO**
|
||||
// (/etc/llmsproxy/config.yaml 的 keys[homeagent].models = [AUTO])。
|
||||
// 而同一个 key + base_url 下 `model: AUTO` 实测完全能看图。
|
||||
//
|
||||
// ⇒ 显式模型名不可用时回 AUTO,比把错误抛给 agent 让它反复重试好。
|
||||
// 注意**不覆盖原错误**:两者都返回,由上层看到完整信息。
|
||||
if isModelNotAllowed(err) {
|
||||
log.Printf("[remotedevice] screensee: 源 %s 的模型名不被接受,回退 AUTO 重试", usedSource)
|
||||
if e2 := llm.SetSource("AUTO"); e2 == nil {
|
||||
rctx, rcancel := context.WithTimeout(context.Background(), 120*time.Second)
|
||||
defer rcancel()
|
||||
if rresp, e3 := llm.Chat(rctx, req); e3 == nil && rresp != nil &&
|
||||
strings.TrimSpace(rresp.Content) != "" {
|
||||
log.Printf("[remotedevice] screensee AUTO 回退成功 len=%d", len(rresp.Content))
|
||||
return rresp.Content, nil
|
||||
} else {
|
||||
log.Printf("[remotedevice] screensee AUTO 回退也失败: %v", e3)
|
||||
}
|
||||
} else {
|
||||
log.Printf("[remotedevice] screensee AUTO 回退无法切源: %v", e2)
|
||||
}
|
||||
}
|
||||
// 保留原始错误文本(那是唯一诊断线索),但以 error 形态上抛。
|
||||
return "", fmt.Errorf("屏幕截图视觉描述失败(视觉源 %s,model=%s): %w", usedSource, currentModelOf(p.sdk.Settings(), usedSource), err)
|
||||
}
|
||||
return resp.Content
|
||||
if resp == nil || strings.TrimSpace(resp.Content) == "" {
|
||||
// 空内容与「失败」对模型同样难以区分,不能静默当成结果。
|
||||
return "", fmt.Errorf("屏幕截图视觉描述失败(视觉源 %s): 模型返回空内容", usedSource)
|
||||
}
|
||||
log.Printf("[remotedevice] screensee 视觉描述完成 source=%s len=%d", usedSource, len(resp.Content))
|
||||
return resp.Content, nil
|
||||
}
|
||||
|
||||
func (p *Plugin) Stop() error {
|
||||
@ -366,3 +427,41 @@ func (p *Plugin) Stop() error {
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// isModelNotAllowed 判定错误是不是「这个 key 不许用该模型名」。
|
||||
//
|
||||
// ★ 2026-10-05:llmsproxy 的原文是
|
||||
//
|
||||
// model "gpt-5.6-sol" is not allowed for this key
|
||||
//
|
||||
// (internal/gateway/chat.go 的 model_not_allowed)
|
||||
//
|
||||
// 只认这一类:它与「模型不存在」「key 无效」的处理完全不同 ——
|
||||
// 前者换个模型名/回 AUTO 就能成,后者要动配置或凭证。
|
||||
func isModelNotAllowed(err error) bool {
|
||||
if err == nil {
|
||||
return false
|
||||
}
|
||||
s := err.Error()
|
||||
return strings.Contains(s, "is not allowed for this key") ||
|
||||
strings.Contains(s, "model_not_allowed") ||
|
||||
strings.Contains(s, "is not in this key's model scope")
|
||||
}
|
||||
|
||||
// currentModelOf 取某个源当前配置的模型名(只用于错误信息,便于定位)。
|
||||
//
|
||||
// ★ 拿不到就返回 "":**诊断信息缺失不该阻断主流程**,
|
||||
//
|
||||
// 所以这里不返回 error(内层的 fmt 已经带着原始错误文本了)。
|
||||
func currentModelOf(settings interface {
|
||||
Get(string) (interface{}, error)
|
||||
}, source string) string {
|
||||
if settings == nil {
|
||||
return ""
|
||||
}
|
||||
v, _ := settings.Get("core.llm.sources." + source + ".model")
|
||||
if v == nil {
|
||||
return ""
|
||||
}
|
||||
return fmt.Sprint(v)
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user