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:
@ -3,6 +3,7 @@ package mcp
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
"sync"
|
||||
)
|
||||
|
||||
@ -15,10 +16,10 @@ type rpcRequest struct {
|
||||
}
|
||||
|
||||
type rpcResponse struct {
|
||||
JSONRPC string `json:"jsonrpc"`
|
||||
ID int `json:"id"`
|
||||
JSONRPC string `json:"jsonrpc"`
|
||||
ID int `json:"id"`
|
||||
Result *json.RawMessage `json:"result,omitempty"`
|
||||
Error *rpcError `json:"error,omitempty"`
|
||||
Error *rpcError `json:"error,omitempty"`
|
||||
}
|
||||
|
||||
type rpcError struct {
|
||||
@ -39,8 +40,27 @@ type MCPContent struct {
|
||||
Text string `json:"text,omitempty"`
|
||||
}
|
||||
|
||||
// MCPCallResult 是 tools/call 的响应体。
|
||||
//
|
||||
// ★ isError 字段必须声明(2026-10-05 补)。
|
||||
//
|
||||
// 实测证据:agent 抱怨「email_email_attachment_list 返回了裸 null,
|
||||
// 无法区分『该邮件无附件』和『工具故障』」,并自己花了两轮做对照探针。
|
||||
// 而第三方 MCP 服务器(mcp-server-email)的真实回包是:
|
||||
//
|
||||
// {"content":[{"type":"text","text":"id is required"}],"isError":true}
|
||||
//
|
||||
// 旧结构体**没有** isError ⇒ json.Unmarshal 静默丢弃它
|
||||
// ⇒ CallTool 把错误当成普通文本返回 ⇒ **失败与成功对模型完全同形**。
|
||||
//
|
||||
// 这与本项目反复记的「报假成功比报错危险」同型:模型据此无法判断
|
||||
// 该重试、该换参数、还是该放弃,只能反复试探浪费轮次。
|
||||
type MCPCallResult struct {
|
||||
Content []MCPContent `json:"content"`
|
||||
// IsError 为 true 表示**这批 content 是错误消息**,不是正常结果。
|
||||
// MCP 规范里它是 result 内的字段(不是 JSON-RPC 层的 error),
|
||||
// 所以外层 resp.Error 会是 nil —— 不显式读就会当成成功。
|
||||
IsError bool `json:"isError"`
|
||||
}
|
||||
|
||||
// Transport 抽象: 支持 stdio / SSE
|
||||
@ -111,15 +131,27 @@ func (s *Server) CallTool(name string, args map[string]interface{}) (string, err
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("mcp %s tools/call %s: %w", s.name, name, err)
|
||||
}
|
||||
return classifyCallResult(s.name, name, resp)
|
||||
}
|
||||
|
||||
// classifyCallResult 把 tools/call 的响应判成(文本, error)。
|
||||
//
|
||||
// 抽成独立函数是为了让判据能**直接拿真实回包驱动它**,而不必起一个
|
||||
// 真的 MCP 子进程(第三方二进制 + 真实凭证,环境依赖太重)。
|
||||
// 生产路径与判据走的是同一份逻辑。
|
||||
func classifyCallResult(serverName, toolName string, resp *rpcResponse) (string, error) {
|
||||
if resp == nil {
|
||||
return "", fmt.Errorf("mcp %s tools/call %s: 无响应(连接已断开或服务端崩溃)", serverName, toolName)
|
||||
}
|
||||
if resp.Error != nil {
|
||||
return "", fmt.Errorf("mcp %s tools/call %s error: %s", s.name, name, resp.Error.Message)
|
||||
return "", fmt.Errorf("mcp %s tools/call %s error: %s", serverName, toolName, resp.Error.Message)
|
||||
}
|
||||
if resp.Result == nil {
|
||||
return "", nil
|
||||
return "", fmt.Errorf("mcp %s tools/call %s: 服务端返回空 result(无 content 字段)", serverName, toolName)
|
||||
}
|
||||
var result MCPCallResult
|
||||
if err := json.Unmarshal(*resp.Result, &result); err != nil {
|
||||
return "", fmt.Errorf("mcp %s tools/call %s unmarshal: %w", s.name, name, err)
|
||||
return "", fmt.Errorf("mcp %s tools/call %s unmarshal: %w", serverName, toolName, err)
|
||||
}
|
||||
// 拼接所有文本片段
|
||||
var sb string
|
||||
@ -128,6 +160,23 @@ func (s *Server) CallTool(name string, args map[string]interface{}) (string, err
|
||||
sb += c.Text
|
||||
}
|
||||
}
|
||||
// ★ isError=true ⇒ 这是**失败**,必须以 error 形态上抛。
|
||||
//
|
||||
// 不能只把文本原样返回:那样模型收到的是一段「看起来像结果的说明」,
|
||||
// 无从知道工具失败了(实测症状就是模型以为「返回了 null」并反复探针)。
|
||||
// 也不能丢弃错误文本 —— 那正是服务端给的**唯一**诊断线索。
|
||||
if result.IsError {
|
||||
msg := strings.TrimSpace(sb)
|
||||
if msg == "" {
|
||||
msg = "(服务端未给出错误文本)"
|
||||
}
|
||||
return "", fmt.Errorf("mcp %s tools/call %s 失败: %s", serverName, toolName, msg)
|
||||
}
|
||||
// 成功但没有任何文本内容:如实说明,不要回空串。
|
||||
// 空串在工具结果里同样会被模型读成「没有内容」,与失败难以区分。
|
||||
if strings.TrimSpace(sb) == "" {
|
||||
return "", fmt.Errorf("mcp %s tools/call %s 成功但未返回任何文本内容(content 为空)", serverName, toolName)
|
||||
}
|
||||
return sb, nil
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user