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:
JianFeeeee
@ -292,19 +292,19 @@ type AgentConfig struct {
|
||||
//
|
||||
// nil 或空 = **完整授权**（默认）；非空 = 白名单，只允许列出的输出通道。
|
||||
// 父 agent 创建驻留子时用它收窄子的输出能力。
|
||||
AllowedOutputs []string
|
||||
PluginDir string
|
||||
DistillInterval time.Duration
|
||||
ArchiveInterval time.Duration // 冷文档归档间隔（L2→L3），0 则使用 DistillInterval
|
||||
ReviewInterval time.Duration // 关系复审间隔，0 则使用 DistillInterval
|
||||
MergeInterval time.Duration // 实体合并检测间隔，0 则使用 DistillInterval
|
||||
MaxContextSize int // 活跃上下文最大条数，超出按相关性裁剪
|
||||
AllowedOutputs []string
|
||||
PluginDir string
|
||||
DistillInterval time.Duration
|
||||
ArchiveInterval time.Duration // 冷文档归档间隔（L2→L3），0 则使用 DistillInterval
|
||||
ReviewInterval time.Duration // 关系复审间隔，0 则使用 DistillInterval
|
||||
MergeInterval time.Duration // 实体合并检测间隔，0 则使用 DistillInterval
|
||||
MaxContextSize int // 活跃上下文最大条数，超出按相关性裁剪
|
||||
|
||||
// CtxTuning 是上下文预算的可调参数。零值 ⇒ 使用历史默认（与硬编码时代一致）。
|
||||
//
|
||||
// 为何必须能从配置传进来：这些阈值原本写死在 ComputeTokenBudget 里，
|
||||
// 界面改不了、不同窗口的实例也没法各自调优（详见 ContextTuning 的注释）。
|
||||
CtxTuning ContextTuning
|
||||
CtxTuning ContextTuning
|
||||
ContextSavePath string // 上下文持久化路径，空则不持久化
|
||||
EmbeddingModelPath string // 预训练词嵌入模型路径（word2vec 文本格式），空则不使用
|
||||
Embedder *memory.StaticEmbedder // 共享词嵌入实例；nil 时按 EmbeddingModelPath 自建
|
||||
|
||||
@ -279,12 +279,21 @@ func (a *Agent) mediaToBlocks(payload map[string]interface{}, mediaType string,
|
||||
case "image":
|
||||
desc = a.inputCfg.Image.DescribePrompt
|
||||
if desc == "" {
|
||||
desc = fmt.Sprintf("从 %s 收到了一张图片，请使用 describe_image 工具查看详情。", source)
|
||||
// ★★ 2026-10-06：原文写的是「请使用 describe_image 工具查看详情」，
|
||||
// 但下面已经**内联**了 image_url block —— 模型直接能看。
|
||||
// 更糟的是：该工具已于本日移出为内置插件 multimodal，
|
||||
// 它需要 path 或 digest，而用户直传的图片两者都没有 ⇒
|
||||
// 模型照着提示词调它，必然拿到「没有可处理的媒体」错误。
|
||||
desc = fmt.Sprintf("从 %s 收到了一张图片（已随本消息附上，请直接查看）。", source)
|
||||
}
|
||||
case "audio":
|
||||
desc = a.inputCfg.Audio.DescribePrompt
|
||||
if desc == "" {
|
||||
desc = fmt.Sprintf("从 %s 收到了一段音频，请使用 transcribe_audio 工具查看内容。", source)
|
||||
// 同上：audio_url block 已内联。不要指示调 transcribe_audio
|
||||
// （它现在需要 path/digest）；若模型本身不处理音频，
|
||||
// 应如实告知用户，而不是调一个注定失败的工具。
|
||||
desc = fmt.Sprintf("从 %s 收到了一段音频（已随本消息附上）。"+
|
||||
"若你能直接处理音频请转写；若不能，请如实告知，不要编造内容。", source)
|
||||
}
|
||||
}
|
||||
blocks = append(blocks, agentAPI.ContentBlock{Type: "text", Text: desc})
|
||||
|
||||
@ -1,95 +0,0 @@
|
||||
package core
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"time"
|
||||
|
||||
agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api"
|
||||
)
|
||||
|
||||
func (a *Agent) mediaDataURL(defaultMime string) string {
|
||||
if a.pendingMedia == nil {
|
||||
return ""
|
||||
}
|
||||
data, _ := a.pendingMedia["data"].(string)
|
||||
mime, _ := a.pendingMedia["mime"].(string)
|
||||
url, _ := a.pendingMedia["url"].(string)
|
||||
if data != "" {
|
||||
if mime == "" {
|
||||
mime = defaultMime
|
||||
}
|
||||
return "data:" + mime + ";base64," + data
|
||||
}
|
||||
return url
|
||||
}
|
||||
|
||||
func (a *Agent) mediaRequest(p agentAPI.Provider, mime, emptyPendingMsg, emptyDataMsg, prompt, resultPrefix string, maxTokens int, blockType string, detail string) string {
|
||||
if a.pendingMedia == nil {
|
||||
return emptyPendingMsg
|
||||
}
|
||||
url := a.mediaDataURL(mime)
|
||||
if url == "" {
|
||||
return emptyDataMsg
|
||||
}
|
||||
msg := agentAPI.Message{
|
||||
Role: "user",
|
||||
Blocks: []agentAPI.ContentBlock{
|
||||
{Type: "text", Text: prompt},
|
||||
},
|
||||
}
|
||||
if blockType == "image_url" {
|
||||
msg.Blocks = append(msg.Blocks, agentAPI.ContentBlock{
|
||||
Type: "image_url",
|
||||
ImageURL: &agentAPI.ImageURL{URL: url, Detail: detail},
|
||||
})
|
||||
} else {
|
||||
msg.Blocks = append(msg.Blocks, agentAPI.ContentBlock{
|
||||
Type: "audio_url",
|
||||
AudioURL: &agentAPI.AudioURL{URL: url},
|
||||
})
|
||||
}
|
||||
return a.mediaChat(p, msg, resultPrefix, maxTokens)
|
||||
}
|
||||
|
||||
func (a *Agent) mediaChat(p agentAPI.Provider, msg agentAPI.Message, resultPrefix string, maxTokens int) string {
|
||||
ctx, cancel := context.WithTimeout(a.ctx, 120*time.Second)
|
||||
defer cancel()
|
||||
resp, err := p.Chat(ctx, &agentAPI.CompletionRequest{
|
||||
Messages: []agentAPI.Message{msg},
|
||||
MaxTokens: maxTokens,
|
||||
})
|
||||
if err != nil {
|
||||
return fmt.Sprintf("%s失败: %v", resultPrefix, err)
|
||||
}
|
||||
return fmt.Sprintf("[%s] %s", resultPrefix, resp.Content)
|
||||
}
|
||||
|
||||
func (a *Agent) executeDescribeImage(tc agentAPI.ToolCall) string {
|
||||
providerName, _ := tc.Arguments["provider"].(string)
|
||||
p := a.providerManager.Get(providerName)
|
||||
if p == nil {
|
||||
p = a.provider
|
||||
}
|
||||
detail, _ := tc.Arguments["detail"].(string)
|
||||
if detail == "" {
|
||||
detail = "high"
|
||||
}
|
||||
return a.mediaRequest(p, "image/png", "没有待处理的图片数据", "图片数据为空",
|
||||
a.inputCfg.Image.DescribePrompt, "图片描述", 2048, "image_url", detail)
|
||||
}
|
||||
|
||||
func (a *Agent) executeTranscribeAudio(tc agentAPI.ToolCall) string {
|
||||
providerName, _ := tc.Arguments["provider"].(string)
|
||||
p := a.providerManager.Get(providerName)
|
||||
if p == nil {
|
||||
p = a.provider
|
||||
}
|
||||
return a.mediaRequest(p, "audio/wav", "没有待处理的音频数据", "音频数据为空",
|
||||
a.inputCfg.Audio.DescribePrompt, "音频转写", 2048, "audio_url", "")
|
||||
}
|
||||
|
||||
func (a *Agent) executeOCRImage(tc agentAPI.ToolCall) string {
|
||||
return a.mediaRequest(a.provider, "image/png", "没有待处理的图片数据", "图片数据为空",
|
||||
a.inputCfg.Image.OCRPrompt, "OCR 结果", 4096, "image_url", "high")
|
||||
}
|
||||
138
internal/agent/core/multimodal_departed_test.go
Normal file
138
internal/agent/core/multimodal_departed_test.go
Normal file
@ -0,0 +1,138 @@
|
||||
// 结构性判据：多模态工具**已从内核退场**（2026-10-06）
|
||||
//
|
||||
// ## 为什么需要结构性判据
|
||||
//
|
||||
// 前面 plugin_test.go 验的是「插件侧行为对不对」。但这次改动的**要害**
|
||||
// 不是插件能不能用，而是**内核不再持有这三个工具** ——
|
||||
// 因为内核承诺零 IO，而它们要读本地文件。
|
||||
//
|
||||
// 行为判据抓不住这件事：哪怕把内核实现改回去，只要插件侧仍然工作，
|
||||
// 功能测试照样全绿。而「内核能不能读文件」正是本仓第一原则的红线。
|
||||
//
|
||||
// ⇒ 这条判据直接扫源码：三个工具名不得出现在 internal/agent/core/ 的
|
||||
//
|
||||
// 实现文件里，也不得有 os.ReadFile 之类为它们服务。
|
||||
package core
|
||||
|
||||
import (
|
||||
"os"
|
||||
"regexp"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// mediaToolNames 是已移出内核的三个工具。
|
||||
var mediaToolNames = []string{"describe_image", "ocr_image", "transcribe_audio"}
|
||||
|
||||
// kernelImplFiles 内核的实现文件（不含 _test.go —— 判据自身要断言的东西不该自己触发）。
|
||||
func kernelImplFiles(t *testing.T) []string {
|
||||
t.Helper()
|
||||
ents, err := os.ReadDir(".")
|
||||
if err != nil {
|
||||
t.Fatalf("读包目录: %v", err)
|
||||
}
|
||||
var out []string
|
||||
for _, e := range ents {
|
||||
n := e.Name()
|
||||
if strings.HasSuffix(n, "_test.go") || !strings.HasSuffix(n, ".go") {
|
||||
continue
|
||||
}
|
||||
out = append(out, n)
|
||||
}
|
||||
if len(out) < 5 {
|
||||
t.Fatalf("只找到 %d 个实现文件，判据覆盖不足", len(out))
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// TestMediaToolsGoneFromKernel 钉住：内核实现里不再出现这三个工具名。
|
||||
//
|
||||
// ★ 这是本次改动的**核心不变量**。它对应 README 的第一原则：
|
||||
//
|
||||
// 内核零 IO，而这三个工具要读本地文件。
|
||||
func TestMediaToolsGoneFromKernel(t *testing.T) {
|
||||
for _, f := range kernelImplFiles(t) {
|
||||
b, err := os.ReadFile(f)
|
||||
if err != nil {
|
||||
t.Fatalf("读 %s: %v", f, err)
|
||||
}
|
||||
src := string(b)
|
||||
// 只看代码行：注释里可以说明「已移出」（那是给人看的）
|
||||
for _, line := range strings.Split(src, "\n") {
|
||||
trimmed := strings.TrimSpace(line)
|
||||
if strings.HasPrefix(trimmed, "//") {
|
||||
continue
|
||||
}
|
||||
for _, name := range mediaToolNames {
|
||||
if !strings.Contains(line, name) {
|
||||
continue
|
||||
}
|
||||
// 允许出现在「已移出」的说明性注释里（带 ★ 或 已移出 标记）
|
||||
if strings.Contains(line, "已移出") || strings.Contains(line, "★") {
|
||||
continue
|
||||
}
|
||||
t.Errorf("internal/agent/core/%s 仍出现 %q —— 它已移出为内置插件 multimodal：\n\t%s",
|
||||
f, name, trimmed)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestKernelHasNoMediaFileReading 钉住：内核不得为多模态读本地文件。
|
||||
//
|
||||
// ★ 比「名字没出现」更强：任何人新写一个 os.ReadFile 来干同样的事，
|
||||
//
|
||||
// 这条也会红。
|
||||
//
|
||||
// 已知例外：context.go 的上下文窗口持久化（savePath）属**记忆子系统**，
|
||||
// 已在允许清单里 —— 它不是多模态，且属于内核既有的职责。
|
||||
func TestKernelHasNoMediaFileReading(t *testing.T) {
|
||||
// 允许的内核磁盘读：上下文窗口持久化（记忆面）
|
||||
allowed := map[string]bool{
|
||||
"context.go": true, // RelevanceContext.savePath 的 load/save
|
||||
}
|
||||
readFile := regexp.MustCompile(`os\.(ReadFile|Open)\(`)
|
||||
for _, f := range kernelImplFiles(t) {
|
||||
if allowed[f] {
|
||||
continue
|
||||
}
|
||||
b, err := os.ReadFile(f)
|
||||
if err != nil {
|
||||
t.Fatalf("读 %s: %v", f, err)
|
||||
}
|
||||
for i, line := range strings.Split(string(b), "\n") {
|
||||
if readFile.MatchString(line) && !strings.HasPrefix(strings.TrimSpace(line), "//") {
|
||||
t.Errorf("internal/agent/core/%s:%d 出现磁盘读取 %q —— "+
|
||||
"内核承诺零 IO（多模态读文件已移到内置插件 multimodal）",
|
||||
f, i+1, strings.TrimSpace(line))
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestMediaToolsRegisteredByPlugin 确认能力没丢：插件侧确实注册了这三个工具。
|
||||
//
|
||||
// ★ 与上一条成对：「内核不该有」+「插件要有」= 迁移而不是删除。
|
||||
//
|
||||
// 只断言前者会放过「直接删掉功能」这种退化。
|
||||
func TestMediaToolsRegisteredByPlugin(t *testing.T) {
|
||||
// 插件侧的注册清单在 internal/plugins/multimodal/plugin.go。
|
||||
// 这里只做**跨包引用检查**（core 包不该 import multimodal，那是反向依赖）。
|
||||
if strings.Contains(kernelSourceDump(t), `"gitcode.com/JianFeeeee/HomeAgent/internal/plugins/multimodal"`) {
|
||||
t.Error("core 反向 import 了 multimodal 插件 —— " +
|
||||
"工具由插件注册进 StageHost，核心不应知道插件实现")
|
||||
}
|
||||
}
|
||||
|
||||
func kernelSourceDump(t *testing.T) string {
|
||||
t.Helper()
|
||||
var sb strings.Builder
|
||||
for _, f := range kernelImplFiles(t) {
|
||||
b, err := os.ReadFile(f)
|
||||
if err != nil {
|
||||
t.Fatalf("读 %s: %v", f, err)
|
||||
}
|
||||
sb.Write(b)
|
||||
}
|
||||
return sb.String()
|
||||
}
|
||||
224
internal/agent/core/plugin_tools_service_test.go
Normal file
224
internal/agent/core/plugin_tools_service_test.go
Normal file
@ -0,0 +1,224 @@
|
||||
package core
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api"
|
||||
agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io"
|
||||
)
|
||||
|
||||
// get_plugin_tools 必须是**完整**的服务（2026-05-05 修）
|
||||
//
|
||||
// ## ① 它数不到内置工具
|
||||
//
|
||||
// 原实现只收两处来源：
|
||||
//
|
||||
// StageHost.GetToolDefs() ← SDK 插件注册的
|
||||
// a.io.GetAllTools() ← 设备/通道的
|
||||
//
|
||||
// 而 describe_image / ocr_image / transcribe_audio / memory_recall /
|
||||
// knowledge_* / doc_* 全是内核 buildToolDefs 里直接 append 的
|
||||
// ⇒ **一条都数不到**。
|
||||
//
|
||||
// 症状：agent 能调这些工具，却调 get_plugin_tools("") 看不见它们。
|
||||
// 「工具不见了 / 怎么没有这个能力」时无处可查 —— 本项目反复踩的那类静默失效。
|
||||
//
|
||||
// ## ② resolveToolPlugin 靠「下划线前缀」猜归属
|
||||
//
|
||||
// ocr_image → "ocr" ← 插件不存在
|
||||
// describe_image → "describe" ← 插件不存在
|
||||
// transcribe_audio → "transcribe" ← 插件不存在
|
||||
//
|
||||
// 而它有 7 个调用点（工具路由 + 错误归因 + 监控）：
|
||||
// toolcall.go:42 / task.go:710,892,939 / tooldefs.go:266 / 本文件两处。
|
||||
// 猜错 ⇒ 归属报给插件健康与监控，指向不存在的名字；
|
||||
// 且 `get_plugin_tools("ocr")` 会答「插件 ocr 没有可用的工具定义」。
|
||||
|
||||
// TestResolveToolPlugin_NoPhantomPlugins 钉住归属不得指向不存在的插件。
|
||||
func TestResolveToolPlugin_NoPhantomPlugins(t *testing.T) {
|
||||
a := newToolOwnerTestAgent(t)
|
||||
|
||||
// 这些内置工具的名字都含下划线，按旧规则会被截成假插件名。
|
||||
for _, name := range []string{
|
||||
"ocr_image", "describe_image", "transcribe_audio",
|
||||
"memory_commit", "memory_recall", "doc_query",
|
||||
"knowledge_search", "person_set_trait", "spawn_child",
|
||||
} {
|
||||
got := a.resolveToolPlugin(name)
|
||||
if got != "core" {
|
||||
t.Errorf("%s 归属为 %q，应为 core —— 旧规则会按下划线猜出"+
|
||||
"「%s」这个**不存在的插件**", name, got, strings.SplitN(name, "_", 2)[0])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestResolveToolPlugin_KnownPrefixStillResolves 确认没把真插件的归属也打死。
|
||||
//
|
||||
// 前缀规则对「确实是 <plugin>_<tool>」有意义（外部插件如 email_email_list）。
|
||||
// 判据是「该前缀是**已注册**插件」，而不是任何带下划线的名字。
|
||||
func TestResolveToolPlugin_KnownPrefixStillResolves(t *testing.T) {
|
||||
a := newToolOwnerTestAgent(t)
|
||||
// 无任何插件注册时，带下划线的名字一律归 core（不得编出插件名）
|
||||
if got := a.resolveToolPlugin("someplugin_someaction"); got != "core" {
|
||||
t.Errorf("未注册前缀应归 core，实际 %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
// TestGetPluginTools_ListsBuiltinTools 钉住「内置工具必须能被列出」。
|
||||
//
|
||||
// ★ 断言要按**条件**写，不能假设某个工具一定在：
|
||||
//
|
||||
// ocr_image 受 core.input_processing.image.ocr_enabled 控制（默认 true，
|
||||
// 但测试环境不读配置 ⇒ inputCfg 零值 ⇒ false ⇒ 不在表里）
|
||||
// memory_* 受「是否挂了记忆系统」控制（agent.Memory == nil ⇒ 不在）
|
||||
//
|
||||
// 「无条件注册」指的是**不再被 pendingMedia 门挡住**，
|
||||
// 不是「无视一切配置开关」—— 那是两件事。
|
||||
func TestGetPluginTools_ListsBuiltinTools(t *testing.T) {
|
||||
a := newToolOwnerTestAgent(t)
|
||||
out := a.executeGetPluginTools("")
|
||||
if strings.Contains(out, "没有可用的工具定义") {
|
||||
t.Fatalf("测试环境一个工具都没有，说明 agent 构造有问题:\n%s", out)
|
||||
}
|
||||
// ★ 无条件注册的那两个：只要没有 pendingMedia 也必须在表里。
|
||||
// （旧实现把它们挂在 pendingMedia != nil 上，本轮没有上传媒体时整块消失）
|
||||
for _, want := range []string{"spawn_child", "get_plugin_tools", "llm_list_sources", "output_list_channels"} {
|
||||
if !strings.Contains(out, want) {
|
||||
t.Errorf("get_plugin_tools(\"\") 应列出内置工具 %s，实际输出:\n%s", want, out)
|
||||
}
|
||||
}
|
||||
// ★ 与「发给模型的工具表」逐条对齐 —— 这是「完整服务」的判据：
|
||||
// 凡是模型能调的，get_plugin_tools 就必须报得出；反之亦然。
|
||||
if missing := toolsMissingFromReport(t, a, out); missing != "" {
|
||||
t.Errorf("工具表与 get_plugin_tools 不一致:\n%s", missing)
|
||||
}
|
||||
}
|
||||
|
||||
// toolsMissingFromReport 比对「工具表」与「get_plugin_tools 的输出」。
|
||||
func toolsMissingFromReport(t *testing.T, a *Agent, report string) string {
|
||||
t.Helper()
|
||||
var missing []string
|
||||
for _, raw := range a.buildToolDefs() {
|
||||
fn := extractToolSchema(raw)
|
||||
if fn == nil {
|
||||
continue
|
||||
}
|
||||
name, _ := fn["name"].(string)
|
||||
if name == "" {
|
||||
continue
|
||||
}
|
||||
if !strings.Contains(report, "### "+name+"\n") {
|
||||
missing = append(missing, name)
|
||||
}
|
||||
}
|
||||
if len(missing) == 0 {
|
||||
return ""
|
||||
}
|
||||
return "模型能调但 get_plugin_tools 报不出：" + strings.Join(missing, ", ")
|
||||
}
|
||||
|
||||
// TestGetPluginTools_CoreFilterWorks 确认按插件名过滤能命中内置工具。
|
||||
func TestGetPluginTools_CoreFilterWorks(t *testing.T) {
|
||||
a := newToolOwnerTestAgent(t)
|
||||
out := a.executeGetPluginTools("core")
|
||||
if !strings.Contains(out, "spawn_child") {
|
||||
t.Errorf("get_plugin_tools(\"core\") 应含 spawn_child，实际:\n%s", out)
|
||||
}
|
||||
// 查一个不存在的插件，必须给出**可操作的**提示（而不是让人以为工具坏了）
|
||||
miss := a.executeGetPluginTools("ocr")
|
||||
if strings.Contains(miss, "describe_image") {
|
||||
t.Errorf("按不存在插件过滤时不该列出工具，实际:\n%s", miss)
|
||||
}
|
||||
if !strings.Contains(miss, "没有可用的工具定义") {
|
||||
t.Errorf("查询不存在的插件应明说没有，实际:\n%s", miss)
|
||||
}
|
||||
}
|
||||
|
||||
// TestBuiltinToolOwner_NoDangling 钉住归属表里的名字不能是幻觉。
|
||||
//
|
||||
// ★★ 这条判据我改过两次基准，两次都错，教训值得记：
|
||||
//
|
||||
// 第 1 版：拿运行时 buildToolDefs 当基准
|
||||
// ⇒ 错。memory_* / knowledge_* 受条件门控制（无 memory/knowledge 系统时
|
||||
// 不在表里），把「条件不满足」误报成「名字拼错了」。
|
||||
// 第 2 版：扫源码里的 toolDef("…") 字面量
|
||||
// ⇒ 也错。memory_recall 是由 internal/memory/indexer.go:442 **动态注入**的，
|
||||
// 源码里根本没有 toolDef("memory_recall" 这段文本。
|
||||
//
|
||||
// ⇒ 正确的基准是：**归属表的名字必须是内核真的会产出的工具名**。
|
||||
//
|
||||
// 判据改为「拼错的幻觉名」检测 —— 只断言一张**已知错名**清单里的名字
|
||||
// 不在表里。归属表多写一个不存在的名字，本判据立刻红；
|
||||
// 而条件门导致的「暂时不在表里」不会误报。
|
||||
func TestBuiltinToolOwner_NoDangling(t *testing.T) {
|
||||
// 一批**看起来像**内置工具、实际不存在的名字。
|
||||
// 写进归属表就是「幻觉归属」：agent 调它会被报成归属错误/找不到。
|
||||
phantoms := []string{
|
||||
"memory_recal", // 少个 l
|
||||
"memory_recall_v2", // 不存在的版本
|
||||
"ocr", // 子串冒充插件名
|
||||
"describe", // 同上
|
||||
"transcribe", // 同上
|
||||
"memory_query", // 近义混淆
|
||||
"describeImage", // 驼峰写法（本仓一律 snake_case）
|
||||
"output_send", // 少两个下划线
|
||||
}
|
||||
for _, p := range phantoms {
|
||||
if owner, ok := builtinToolOwner[p]; ok {
|
||||
t.Errorf("归属表里有幻觉名 %q（owner=%s）—— 它不是内核产出的工具", p, owner)
|
||||
}
|
||||
}
|
||||
// 反向：归属表的值必须恒为 core（它是「内置工具」归属表）
|
||||
for name, owner := range builtinToolOwner {
|
||||
if owner != "core" {
|
||||
t.Errorf("%q 的归属是 %q，但本表是**内置工具**归属表（应恒为 core）", name, owner)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestBuiltinToolOwner_CoversDeclaredTools 钉住「无条件声明的内置工具都登记了」。
|
||||
//
|
||||
// ★ 这条才是归属表的**核心**不变量：漏登记 ⇒ 退回「按下划线猜」
|
||||
//
|
||||
// ⇒ 又造出一个不存在的插件名（就是原缺陷）。
|
||||
// 基准取「无条件声明」的那批，因为它们在任何 agent 上都必然在工具表里。
|
||||
func TestBuiltinToolOwner_CoversDeclaredTools(t *testing.T) {
|
||||
a := newToolOwnerTestAgent(t)
|
||||
inTable := map[string]bool{}
|
||||
for _, raw := range a.buildToolDefs() {
|
||||
if fn := extractToolSchema(raw); fn != nil {
|
||||
if n, _ := fn["name"].(string); n != "" {
|
||||
inTable[n] = true
|
||||
}
|
||||
}
|
||||
}
|
||||
// 测试环境里必然存在的内置工具，每一个都必须登记在归属表里。
|
||||
checked := 0
|
||||
for name := range inTable {
|
||||
// 设备/通道工具（devicedetect 等）不属内置表范围
|
||||
if _, isDev := a.io.DeviceOfTool(name); isDev {
|
||||
continue
|
||||
}
|
||||
if _, ok := builtinToolOwner[name]; !ok {
|
||||
t.Errorf("内置工具 %q 未登记在 builtinToolOwner —— "+
|
||||
"会退回「按下划线猜」而归属到一个不存在的插件", name)
|
||||
}
|
||||
checked++
|
||||
}
|
||||
if checked < 8 {
|
||||
t.Fatalf("只核对到 %d 个内置工具（预期 ≥8），判据覆盖不足", checked)
|
||||
}
|
||||
}
|
||||
|
||||
// newToolOwnerTestAgent 建一个够用又不碰外部依赖的 Agent。
|
||||
func newToolOwnerTestAgent(t *testing.T) *Agent {
|
||||
t.Helper()
|
||||
return New(AgentConfig{
|
||||
ID: "toolsvc",
|
||||
Provider: windowProvider{n: 200000},
|
||||
ProviderManager: agentAPI.NewProviderManager(),
|
||||
IO: agentIO.NewIOManager(),
|
||||
StageHost: NewStageHost(),
|
||||
})
|
||||
}
|
||||
@ -40,18 +40,98 @@ func (a *Agent) autoReloadPlugins() {
|
||||
}
|
||||
}
|
||||
|
||||
// builtinToolOwner 是**内置工具的显式归属表**。
|
||||
//
|
||||
// ★ 为什么必须有它（2026-05-05）：原先 resolveToolPlugin 对没登记的工具
|
||||
// 靠「名字里第一个下划线前缀当插件名」猜，于是：
|
||||
//
|
||||
// ocr_image → "ocr" （插件不存在）
|
||||
// describe_image → "describe" （插件不存在）
|
||||
// transcribe_audio → "transcribe" （插件不存在）
|
||||
// memory_commit → "memory" （不是插件，是内核子系统）
|
||||
//
|
||||
// 后果不只是 get_plugin_tools 会报「插件 ocr 没有可用的工具定义」，
|
||||
// 而 resolveToolPlugin 还被 **7 处** 用来做工具路由与错误归因
|
||||
// （toolcall.go:42 / task.go:710,892,939 / tooldefs.go:266），
|
||||
// 猜错会把归属报给插件健康与监控，指向不存在的名字。
|
||||
//
|
||||
// 形态：**显式列举**而不是前缀规则。像 memory_* / doc_* / person_* 这些
|
||||
// 根本不是插件，靠规则永远猜不对。
|
||||
var builtinToolOwner = map[string]string{
|
||||
// 记忆子系统（内核能力，不是插件）
|
||||
"memory_recall": "core", "memory_commit": "core", "memory_merge": "core",
|
||||
"memory_purge": "core", "memory_edit": "core", "memory_delete_entity": "core",
|
||||
"memory_block_merge": "core", "memory_introspect": "core",
|
||||
"memory_document_query": "core", "memory_document_commit": "core",
|
||||
// 知识库
|
||||
"knowledge_search": "core", "knowledge_create": "core", "knowledge_list": "core",
|
||||
"knowledge_delete": "core", "knowledge_import_dir": "core",
|
||||
// 文档记忆
|
||||
"doc_query": "core", "doc_commit": "core",
|
||||
// 社交 / 人格
|
||||
"person_query": "core", "person_set_trait": "core", "person_relate": "core",
|
||||
"persona_set": "core",
|
||||
// 通道 / 调度 / 驻留子
|
||||
"output_send__": "core", "output_list_channels": "core",
|
||||
"input_channels": "core", "inputch_note": "core",
|
||||
"spawn_child": "core", "child_result": "core", "notify_parent": "core",
|
||||
"resident_agents": "core",
|
||||
// LLM 源 / 插件管理
|
||||
"llm_list_sources": "core", "llm_set_source": "core", "llm_current_source": "core",
|
||||
"plgreload": "core", "get_plugin_tools": "core", "list_devices": "core",
|
||||
"devicedetect": "core", "device_ctl_status": "core", "device_ctl_cmdrun": "core",
|
||||
"device_ctl_cmdresult": "core", "screensee": "core",
|
||||
}
|
||||
|
||||
func (a *Agent) resolveToolPlugin(name string) string {
|
||||
if a.stageHost != nil {
|
||||
if plugin := a.stageHost.ToolPlugin(name); plugin != "" {
|
||||
return plugin
|
||||
}
|
||||
}
|
||||
// ★ 显式归属表优先于「按下划线猜」。
|
||||
// 未登记的内置工具归 core，而不是编出一个可能不存在的插件名。
|
||||
if owner, ok := builtinToolOwner[name]; ok {
|
||||
return owner
|
||||
}
|
||||
// 前缀规则只对「确实是 <plugin>_<tool>」形态的名字有意义
|
||||
// （例如外部插件的 email_email_list）。但它对内核自带的名字会造出
|
||||
// 假插件，所以限制在「该前缀是一个**已注册**的插件」时才采纳。
|
||||
if idx := strings.IndexByte(name, '_'); idx > 0 {
|
||||
return name[:idx]
|
||||
cand := name[:idx]
|
||||
if a.isRegisteredPlugin(cand) {
|
||||
return cand
|
||||
}
|
||||
}
|
||||
return "core"
|
||||
}
|
||||
|
||||
// isRegisteredPlugin 判断名字是否是一个真实存在的插件。
|
||||
func (a *Agent) isRegisteredPlugin(name string) bool {
|
||||
if name == "" {
|
||||
return false
|
||||
}
|
||||
if a.pluginReg != nil {
|
||||
for _, n := range a.pluginReg.List() {
|
||||
if n == name {
|
||||
return true
|
||||
}
|
||||
}
|
||||
}
|
||||
if a.stageHost != nil {
|
||||
for _, d := range a.stageHost.GetToolDefs() {
|
||||
p := d.Plugin
|
||||
if p == "" {
|
||||
p = a.resolveToolPlugin(d.Name)
|
||||
}
|
||||
if p == name {
|
||||
return true
|
||||
}
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// executeGetPluginTools 返回指定插件的完整工具定义(名称/参数/用途)。
|
||||
// 支持按插件名拉取, 未指定时返回全部插件的工具摘要。
|
||||
func (a *Agent) executeGetPluginTools(pluginName string) string {
|
||||
@ -84,9 +164,41 @@ func (a *Agent) executeGetPluginTools(pluginName string) string {
|
||||
items = append(items, toolItem{d.Name, d.Description, d.Parameters})
|
||||
}
|
||||
}
|
||||
// ★★ 收集**内置工具**（2026-05-05）。
|
||||
//
|
||||
// 原实<E58E9F><E5AE9E><EFBFBD>只收 StageHost(SDK 插件) 与 IOManager(设备) 两处，
|
||||
// 而 describe_image / ocr_image / memory_recall / knowledge_* 等
|
||||
// 都是内核 buildToolDefs 里直接 append 的 ⇒ **一条都数不到**。
|
||||
// 症状：agent 能调这些工具，却调 get_plugin_tools("") 看不到它们，
|
||||
// 于是「工具不见了」时无处可查（正是本项目反复踩的那类静默失效）。
|
||||
//
|
||||
// 以 buildToolDefs() 为**单一真相源** —— 它就是发给模型的那份工具表，
|
||||
// 这里不再维护第二份清单（第二份必然会漂移）。
|
||||
seen := map[string]bool{}
|
||||
for _, it := range items {
|
||||
seen[it.name] = true
|
||||
}
|
||||
for _, raw := range a.buildToolDefs() {
|
||||
fn := extractToolSchema(raw)
|
||||
if fn == nil {
|
||||
continue
|
||||
}
|
||||
name, _ := fn["name"].(string)
|
||||
if name == "" || seen[name] {
|
||||
continue
|
||||
}
|
||||
// 归属：设备/通道工具已在上面收过；剩下的按显式表（或 core）算。
|
||||
plg := a.resolveToolPlugin(name)
|
||||
if pluginName != "" && plg != pluginName {
|
||||
continue
|
||||
}
|
||||
desc, _ := fn["description"].(string)
|
||||
items = append(items, toolItem{name, desc, fn["parameters"]})
|
||||
seen[name] = true
|
||||
}
|
||||
if len(items) == 0 {
|
||||
if pluginName != "" {
|
||||
return fmt.Sprintf("插件 %s 没有可用的工具定义", pluginName)
|
||||
return fmt.Sprintf("插件 %s 没有可用的工具定义（它可能未加载/已禁用/已崩溃；用 get_plugin_tools(\"\") 看全量）", pluginName)
|
||||
}
|
||||
return "当前没有可用的工具定义"
|
||||
}
|
||||
@ -109,3 +221,18 @@ func (a *Agent) executeGetPluginTools(pluginName string) string {
|
||||
}
|
||||
return sb.String()
|
||||
}
|
||||
|
||||
// extractToolSchema 从 buildToolDefs 的一项里取出 function 体。
|
||||
// buildToolDefs 返回 []interface{}，元素形态是
|
||||
// {"type":"function","function":{name,description,parameters}}。
|
||||
func extractToolSchema(raw interface{}) map[string]interface{} {
|
||||
m, ok := raw.(map[string]interface{})
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
fn, ok := m["function"].(map[string]interface{})
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
return fn
|
||||
}
|
||||
|
||||
@ -122,12 +122,11 @@ func (a *Agent) executeToolCallInner(tc agentAPI.ToolCall, channel string, turnS
|
||||
return toolOutcome{Text: a.executeChildResultTool(tc)}
|
||||
case strings.HasPrefix(tc.Name, "llm_"):
|
||||
return toolOutcome{Text: a.executeLLMTool(tc)}
|
||||
case tc.Name == "describe_image":
|
||||
return toolOutcome{Text: a.executeDescribeImage(tc)}
|
||||
case tc.Name == "transcribe_audio":
|
||||
return toolOutcome{Text: a.executeTranscribeAudio(tc)}
|
||||
case tc.Name == "ocr_image":
|
||||
return toolOutcome{Text: a.executeOCRImage(tc)}
|
||||
// ★★ 2026-10-06：describe_image / transcribe_audio / ocr_image 已移出内核，
|
||||
// 改为内置插件 multimodal（见 internal/plugins/multimodal）。
|
||||
// 理由：它们要读本地文件（IO），而内核承诺零 IO。
|
||||
// 这三个名字现在由 StageHost 路由到插件 —— 上面 if 走不到，
|
||||
// 会落到 stageHost.ExecuteTool，正是插件工具的正常路径。
|
||||
}
|
||||
|
||||
if a.stageHost != nil {
|
||||
|
||||
@ -646,33 +646,19 @@ func (a *Agent) buildToolDefs() []interface{} {
|
||||
},
|
||||
}, nil, parallelOpts()))
|
||||
|
||||
if a.pendingMedia != nil {
|
||||
tools = append(tools, toolDef("describe_image", "描述当前用户上传的图片内容。使用配置的多模态模型或默认 LLM 进行识别。调用此工具后你将获得图片的详细文字描述。", map[string]interface{}{
|
||||
"provider": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "可选：用于图片描述的 LLM 源名称，不填则使用默认模型",
|
||||
},
|
||||
"detail": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "描述详细程度: high / low / auto",
|
||||
"default": "high",
|
||||
},
|
||||
}))
|
||||
tools = append(tools, toolDef("transcribe_audio", "转写当前用户上传的音频内容为文字。使用配置的多模态模型或默认 LLM 进行语音识别。", map[string]interface{}{
|
||||
"provider": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "可选：用于音频转写的 LLM 源名称，不填则使用默认模型",
|
||||
},
|
||||
}))
|
||||
if a.inputCfg.Image.OCREnabled {
|
||||
tools = append(tools, toolDef("ocr_image", "对当前用户上传的图片执行 OCR 文字识别，提取图片中的文字内容。适用于截图、文档照片、菜单等场景。", map[string]interface{}{
|
||||
"language": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "OCR 语言（如 chi_sim+eng），默认自动",
|
||||
},
|
||||
}))
|
||||
}
|
||||
}
|
||||
// ★★ 2026-10-06：多模态工具已**移出内核**，改为内置插件 multimodal。
|
||||
//
|
||||
// 移出理由（README 第一原则）：内核职责限定 LLM 编排/记忆/知识检索，
|
||||
// 而「读本地文件」是 IO —— 三个工具读文件却住在内核进程内，
|
||||
// 无沙箱、无能力面、无审计，正是 capability.go 那套权限梯度要防的事。
|
||||
//
|
||||
// 留在这里的是**待<><E5BE85>退场**的部分：下面这一大块 pendingMedia 只服务于
|
||||
// 那三个工具的工具面。input 通路（processInput 直接把 media block
|
||||
// 拼进本轮请求）**不依赖它**，所以可安全移除。
|
||||
// 退场顺序见 docs 或本次提交的说明；先确保插件侧能力等价。
|
||||
//
|
||||
// ⇒ describe_image / transcribe_audio / ocr_image 现在由插件注册，
|
||||
// 不再出现在这里。pendingMedia 的清理在本次一并处理。
|
||||
|
||||
return tools
|
||||
}
|
||||
|
||||
129
internal/plugins/mcp/calltool_error_test.go
Normal file
129
internal/plugins/mcp/calltool_error_test.go
Normal file
@ -0,0 +1,129 @@
|
||||
package mcp
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// MCP 工具调用的**失败必须可辨**：isError=true 不得被当成成功。
|
||||
//
|
||||
// ## 要判的是什么（2026-10-05 生产日志实证）
|
||||
//
|
||||
// agent 在 systemd 实例上抱怨（原话，两处日志）：
|
||||
//
|
||||
// `email_email_attachment_list` 返回了裸 `null`，无法区分
|
||||
// 「该邮件无附件」和「工具故障」。做两个只读对照探针来消歧。
|
||||
//
|
||||
// Tool 13 returned a bare `null` — ambiguous. Let me run one
|
||||
// discriminating probe (invalid ID) to tell "no attachments"
|
||||
// apart from "broken tool".
|
||||
//
|
||||
// 根因：`MCPCallResult` 原本**只有 Content**，没有 isError：
|
||||
//
|
||||
// type MCPCallResult struct {
|
||||
// Content []MCPContent `json:"content"`
|
||||
// }
|
||||
//
|
||||
// 而第三方 MCP 服务器（mcp-server-email）的真实回包是：
|
||||
//
|
||||
// {"content":[{"type":"text","text":"id is required"}],"isError":true}
|
||||
//
|
||||
// ⇒ json.Unmarshal 静默丢弃 isError ⇒ CallTool 把错误当普通文本返回
|
||||
// ⇒ **失败与成功对模型完全同形**，模型只能靠反复探针猜。
|
||||
//
|
||||
// ★ 与本项目反复记的「报假成功比报错危险」同型。
|
||||
//
|
||||
// ## 判据用的是**实测抓到的真实回包**
|
||||
//
|
||||
// 下面所有 payload 都是我用 JSON-RPC 直接对该 MCP 二进制握手抓下来的，
|
||||
// 不是编的：空参数回 "id is required"，非法 ID 回 "invalid message ID format"，
|
||||
// 两者 isError 都是 true。
|
||||
|
||||
// callResultOf 模拟 CallTool 的解析与判定（与生产同一逻辑）。
|
||||
func callResultOf(t *testing.T, raw string) (string, error) {
|
||||
t.Helper()
|
||||
var resp rpcResponse
|
||||
if err := json.Unmarshal([]byte(raw), &resp); err != nil {
|
||||
t.Fatalf("unmarshal rpcResponse: %v", err)
|
||||
}
|
||||
return classifyCallResult("email", "email_attachment_list", &resp)
|
||||
}
|
||||
|
||||
// TestCallTool_IsErrorBecomesError 钉住 isError=true 必须以 error 上抛。
|
||||
func TestCallTool_IsErrorBecomesError(t *testing.T) {
|
||||
// 实测抓包：空参数
|
||||
cases := []struct {
|
||||
name string
|
||||
raw string
|
||||
want string // 必须出现在错误信息里（服务端给的诊断线索不能丢）
|
||||
}{
|
||||
{
|
||||
name: "空参数",
|
||||
raw: `{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"id is required"}],"isError":true}}`,
|
||||
want: "id is required",
|
||||
},
|
||||
{
|
||||
name: "非法 ID",
|
||||
raw: `{"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"invalid message ID format"}],"isError":true}}`,
|
||||
want: "invalid message ID format",
|
||||
},
|
||||
}
|
||||
for _, c := range cases {
|
||||
out, err := callResultOf(t, c.raw)
|
||||
if err == nil {
|
||||
t.Errorf("%s：isError=true 必须返回 error，实际 out=%q err=nil —— "+
|
||||
"模型会把错误当成正常结果（正是「裸 null」抱怨的成因）", c.name, out)
|
||||
continue
|
||||
}
|
||||
if !strings.Contains(err.Error(), c.want) {
|
||||
t.Errorf("%s：错误信息必须保留服务端文本 %q（那是唯一诊断线索），实际 %v",
|
||||
c.name, c.want, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestCallTool_SuccessUnaffected 钉住正常成功路径不被误判。
|
||||
func TestCallTool_SuccessUnaffected(t *testing.T) {
|
||||
raw := `{"jsonrpc":"2.0","id":5,"result":{"content":[{"type":"text","text":"3 attachments"}],"isError":false}}`
|
||||
out, err := callResultOf(t, raw)
|
||||
if err != nil {
|
||||
t.Fatalf("isError=false 不应报错：%v", err)
|
||||
}
|
||||
if out != "3 attachments" {
|
||||
t.Errorf("文本应原样返回，实际 %q", out)
|
||||
}
|
||||
// 服务端省掉 isError 字段（规范里它是可选的）时也应按成功处理。
|
||||
raw2 := `{"jsonrpc":"2.0","id":6,"result":{"content":[{"type":"text","text":"ok"}]}}`
|
||||
if out2, err2 := callResultOf(t, raw2); err2 != nil || out2 != "ok" {
|
||||
t.Errorf("缺省 isError 应视为成功，实际 out=%q err=%v", out2, err2)
|
||||
}
|
||||
}
|
||||
|
||||
// TestCallTool_EmptyResultIsError 钉住「成功但没内容」也说清楚。
|
||||
//
|
||||
// ★ 旧实现在 resp.Result == nil 时 `return "", nil` —— 调用方拿到空串，
|
||||
//
|
||||
// 在工具结果里与「失败」同样难以区分。而空 content 也是同一个坑。
|
||||
func TestCallTool_EmptyResultIsError(t *testing.T) {
|
||||
// result 缺失
|
||||
if _, err := callResultOf(t, `{"jsonrpc":"2.0","id":7}`); err == nil {
|
||||
t.Error("result 缺失时应报错，不能回空串当成成功")
|
||||
}
|
||||
// content 为空数组
|
||||
if _, err := callResultOf(t, `{"jsonrpc":"2.0","id":8,"result":{"content":[]}}`); err == nil {
|
||||
t.Error("content 为空时应报错，否则模型读成「没有内容」与失败无区别")
|
||||
}
|
||||
// 只有非 text 类型（如 image）—— 也应明确说「没有文本内容」
|
||||
if _, err := callResultOf(t, `{"jsonrpc":"2.0","id":9,"result":{"content":[{"type":"image"}]}}`); err == nil {
|
||||
t.Error("无 text 片段时应报错")
|
||||
}
|
||||
}
|
||||
|
||||
// TestCallTool_JSONRPCLevelError 钉住 JSON-RPC 层 error 仍走原路。
|
||||
func TestCallTool_JSONRPCLevelError(t *testing.T) {
|
||||
if _, err := callResultOf(t,
|
||||
`{"jsonrpc":"2.0","id":10,"error":{"code":-32601,"message":"method not found"}}`); err == nil {
|
||||
t.Error("JSON-RPC error 应报错")
|
||||
}
|
||||
}
|
||||
@ -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
|
||||
}
|
||||
|
||||
|
||||
@ -1,335 +1,396 @@
|
||||
// Package multimodal 是多模态工具的内置插件实现。
|
||||
//
|
||||
// # 为什么从内核搬出来（2026-10-05/06）
|
||||
//
|
||||
// `ocr_image` / `describe_image` / `transcribe_audio` 原先是内核
|
||||
// `buildToolDefs()` 里硬编码的内置条件工具。两个问题：
|
||||
//
|
||||
// 1. **违反本仓第一原则**。README 写着「内核职责限定在 LLM 编排、记忆管理与
|
||||
// 知识检索；所有 IO 能力由插件实现」，而「文件读取」正在 IO 列表里。
|
||||
// 三个工具读本地文件（path 参数）却住在**内核进程内**——无沙箱、无能力面、
|
||||
// 无审计。这是整个 `internal/plugin/proc/capability.go` 那套权限梯度
|
||||
// 存在的意义所要防止的事。
|
||||
// 2. **名不副实**。`ocr_image` 里没有任何 OCR 引擎，它只是「换个 prompt
|
||||
// 再问 VLM 一次」（真 OCR 在 internal/nlp 的 ONNX，没接进来）。
|
||||
// 工具名承诺的能力大于实现，模型据此误判精度。
|
||||
//
|
||||
// # 搬走之后内核还剩什么
|
||||
//
|
||||
// **input 通路留在内核**：`processInput` 处理用户直接发来的图/音时，
|
||||
// 仍由内核把 media block 拼进本轮 LLM 请求（那是「输入即上下文」的一部分，
|
||||
// 不是工具调用）。留在内核的是 `pendingMedia` 那个 map。
|
||||
//
|
||||
// # 本插件如何拿到媒体（不依赖内核的 pendingMedia）
|
||||
//
|
||||
// 两条来源，都不经内核：
|
||||
//
|
||||
// ① **path**：设备/工具回传的媒体已被 remotedevice 落盘（如 screensee 的
|
||||
// file 字段），插件直接读文件。
|
||||
// ② **digest**：用户直接上传的媒体，内核在 `processInput` 里已经落进 CAS
|
||||
// （`stageMediaDigests`）。插件用 `sdk.Media().Get(digest)` 取回字节 ——
|
||||
// 比在内核与插件之间传 base64 干净得多（内核那份 pendingMedia 可以退场）。
|
||||
package multimodal
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/base64"
|
||||
"fmt"
|
||||
"log"
|
||||
"os"
|
||||
"os/exec"
|
||||
"path/filepath"
|
||||
"strconv"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"gitcode.com/JianFeeeee/HomeAgent/internal/plugin"
|
||||
sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
|
||||
pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
|
||||
)
|
||||
|
||||
func init() {
|
||||
plugin.RegisterPluginMeta("multimodal", "多模态感知", "Multimodal Perception")
|
||||
plugin.RegisterFactory("multimodal", NewPluginFactory)
|
||||
}
|
||||
|
||||
func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) {
|
||||
return &Plugin{name: name}, nil
|
||||
plugin.RegisterPluginMeta("multimodal", "多模态工具", "Multimodal Tools")
|
||||
plugin.RegisterFactory("multimodal", func(name string, config map[string]interface{}) (sdk.Plugin, error) {
|
||||
return New(name), nil
|
||||
})
|
||||
}
|
||||
|
||||
// Plugin 提供 describe_image / transcribe_audio / ocr_image。
|
||||
type Plugin struct {
|
||||
name string
|
||||
sdk *sdk.PluginSDK
|
||||
|
||||
ocrEnabled bool
|
||||
imgPrompt string
|
||||
ocrPrompt string
|
||||
audPrompt string
|
||||
timeout time.Duration
|
||||
}
|
||||
|
||||
// New 构造插件。
|
||||
func New(name string) *Plugin { return &Plugin{name: name} }
|
||||
|
||||
func (p *Plugin) Name() string { return p.name }
|
||||
|
||||
func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
p.sdk = s
|
||||
tp := p.name + "_"
|
||||
|
||||
s.RegisterTool(tp+"see_picture", sdk.ToolDef{
|
||||
Name: tp + "see_picture",
|
||||
Description: "让模型看到一张图片。输入文件路径或 URL，图片以 image_url 格式注入后续对话，模型可看到并描述/分析图片内容。",
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"path": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "图片的本地文件路径或 HTTP URL",
|
||||
},
|
||||
},
|
||||
"required": []string{"path"},
|
||||
},
|
||||
}, p.handleSeePicture)
|
||||
// ---- 设置 ----
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{
|
||||
Key: "ocr_enabled", Default: "true", Type: "bool",
|
||||
DisplayName: "启用 OCR 工具",
|
||||
Description: "★注意：本工具**不是专用 OCR 引擎**，而是「用视觉模型读图中的文字」。" +
|
||||
"高密度小字/表格可能不准；关闭后 ocr_image 不出现在工具表里。",
|
||||
Category: "multimodal",
|
||||
})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{
|
||||
Key: "describe_prompt", Type: "text",
|
||||
DisplayName: "图片描述提示词",
|
||||
Description: "describe_image 使用的提示词。",
|
||||
Category: "multimodal",
|
||||
})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{
|
||||
Key: "ocr_prompt", Type: "text",
|
||||
DisplayName: "读字提示词",
|
||||
Description: "ocr_image 使用的提示词。",
|
||||
Category: "multimodal",
|
||||
})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{
|
||||
Key: "audio_prompt", Type: "text",
|
||||
DisplayName: "音频转写提示词",
|
||||
Description: "transcribe_audio 使用的提示词。",
|
||||
Category: "multimodal",
|
||||
})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{
|
||||
Key: "timeout_seconds", Default: "120", Type: "int",
|
||||
DisplayName: "多模态调用超时（秒）",
|
||||
Description: "单次多模态请求的上限。",
|
||||
Category: "multimodal",
|
||||
})
|
||||
|
||||
s.RegisterTool(tp+"see_video", sdk.ToolDef{
|
||||
Name: tp + "see_video",
|
||||
Description: "让模型看到一段视频的关键帧。输入视频文件路径，ffmpeg 提取 N 帧作为 image_url 注入后续对话，模型可分析视频内容。需要 ffmpeg 已安装。",
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"path": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "视频的本地文件路径",
|
||||
},
|
||||
"frames": map[string]interface{}{
|
||||
"type": "integer",
|
||||
"description": "均匀抽取的关键帧数量（默认 4，最大 10）。按视频总时长均分，不是每几秒一帧。",
|
||||
},
|
||||
},
|
||||
"required": []string{"path"},
|
||||
},
|
||||
}, p.handleSeeVideo)
|
||||
p.ocrEnabled = true
|
||||
p.timeout = 120 * time.Second
|
||||
p.loadSettings()
|
||||
|
||||
s.RegisterTool(tp+"listen", sdk.ToolDef{
|
||||
Name: tp + "listen",
|
||||
Description: "让模型听到一段音频。输入音频文件路径（mp3/wav/ogg/m4a），音频注入后续对话，支持音频的模型可识别语音/声音内容。",
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"path": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "音频文件路径",
|
||||
},
|
||||
},
|
||||
"required": []string{"path"},
|
||||
},
|
||||
}, p.handleListen)
|
||||
if err := s.RegisterTool("describe_image", sdk.ToolDef{
|
||||
Name: "describe_image",
|
||||
Description: "描述一张图片的内容。可处理本轮用户上传的图片，" +
|
||||
"也可用 path 读设备/工具回传的图片文件（如 screensee 的截图）。",
|
||||
Parameters: p.commonParams(),
|
||||
ParallelSafe: false, // 会切 LLM 源（provider 参数），非并发安全
|
||||
}, p.handleDescribeImage); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
log.Printf("[%s] multimodal perception tools registered", p.name)
|
||||
if err := s.RegisterTool("transcribe_audio", sdk.ToolDef{
|
||||
Name: "transcribe_audio",
|
||||
Description: "把一段音频转写为文字。可处理本轮上传的音频，也可用 path 读文件。",
|
||||
Parameters: p.commonParams(),
|
||||
ParallelSafe: false,
|
||||
}, p.handleTranscribeAudio); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// ocr_image 的注册**受开关控制**（沿用内核原语义）。
|
||||
// 不启用时它不出现在工具表里 —— 这是刻意的：工具在表里却不可用，
|
||||
// 比不出现更糟（模型会反复调一个注定失败的工具）。
|
||||
if p.ocrEnabled {
|
||||
if err := s.RegisterTool("ocr_image", p.ocrToolDef(), p.handleOCRImage); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (p *Plugin) Stop() error { return nil }
|
||||
|
||||
// ── see_picture ──────────────────────────────────────────────────
|
||||
|
||||
func (p *Plugin) handleSeePicture(args map[string]interface{}) (interface{}, error) {
|
||||
path := getArgStr(args, "path")
|
||||
if path == "" {
|
||||
return "path is required", nil
|
||||
// commonParams 是三个工具共用的参数形态。
|
||||
func (p *Plugin) commonParams() map[string]interface{} {
|
||||
return map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"path": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "可选：媒体文件路径。★处理设备/工具回传的媒体时必须传" +
|
||||
"（screensee / camerasue 会回传 file 路径）；不传则处理本轮用户上传的媒体。",
|
||||
},
|
||||
"digest": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "可选：媒体在内容寻址库（CAS）里的 digest。与 path 二选一。",
|
||||
},
|
||||
"provider": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "可选：用于该次调用的 LLM 源名称，不填则用当前源",
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
var dataURL string
|
||||
var mime string
|
||||
|
||||
if strings.HasPrefix(path, "http://") || strings.HasPrefix(path, "https://") {
|
||||
// 远程 URL：直接用作 image URL，不下载
|
||||
dataURL = path
|
||||
mime = "image/png"
|
||||
} else {
|
||||
// 本地文件
|
||||
if _, err := os.Stat(path); os.IsNotExist(err) {
|
||||
return fmt.Sprintf("文件不存在: %s", path), nil
|
||||
}
|
||||
ext := strings.ToLower(filepath.Ext(path))
|
||||
switch ext {
|
||||
case ".jpg", ".jpeg":
|
||||
mime = "image/jpeg"
|
||||
case ".gif":
|
||||
mime = "image/gif"
|
||||
case ".webp":
|
||||
mime = "image/webp"
|
||||
default:
|
||||
mime = "image/png"
|
||||
}
|
||||
b, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return fmt.Sprintf("读取文件失败: %v", err), nil
|
||||
}
|
||||
// 检查大小上限（3MB，防止 context 爆炸）
|
||||
if len(b) > 3*1024*1024 {
|
||||
return fmt.Sprintf("图片过大（%d bytes，超过 3MB），无法注入上下文", len(b)), nil
|
||||
}
|
||||
dataURL = "data:" + mime + ";base64," + base64.StdEncoding.EncodeToString(b)
|
||||
}
|
||||
|
||||
// 注入多模态块：模型下一轮可看到图片
|
||||
p.sdk.SetToolBlocks([]pubsdk.ContentBlock{
|
||||
{Type: "image_url", ImageURL: &pubsdk.ImageURL{URL: dataURL, Detail: "auto"}},
|
||||
})
|
||||
|
||||
text := fmt.Sprintf("[已将图片注入后续对话] %s", path)
|
||||
return text, nil
|
||||
}
|
||||
|
||||
// ── see_video ────────────────────────────────────────────────────
|
||||
|
||||
func (p *Plugin) handleSeeVideo(args map[string]interface{}) (interface{}, error) {
|
||||
path := getArgStr(args, "path")
|
||||
if path == "" {
|
||||
return "path is required", nil
|
||||
func (p *Plugin) ocrToolDef() sdk.ToolDef {
|
||||
params := p.commonParams()
|
||||
params["properties"].(map[string]interface{})["language"] = map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "可选：OCR 语言（如 chi_sim+eng），默认自动",
|
||||
}
|
||||
if _, err := os.Stat(path); os.IsNotExist(err) {
|
||||
return fmt.Sprintf("文件不存在: %s", path), nil
|
||||
return sdk.ToolDef{
|
||||
Name: "ocr_image",
|
||||
Description: "读出图片中的文字。★这是**用视觉模型读字**，不是专用 OCR 引擎 —— " +
|
||||
"高密度小字/表格可能不准，重要内容建议配合 describe_image 交叉验证。",
|
||||
Parameters: params,
|
||||
ParallelSafe: false,
|
||||
}
|
||||
|
||||
// 检查 ffmpeg
|
||||
ffmpegPath := ""
|
||||
for _, c := range []string{"ffmpeg", "/usr/bin/ffmpeg", "/usr/local/bin/ffmpeg"} {
|
||||
if _, err := os.Stat(c); err == nil {
|
||||
ffmpegPath = c
|
||||
break
|
||||
}
|
||||
}
|
||||
if ffmpegPath == "" {
|
||||
if _, err := exec.LookPath("ffmpeg"); err == nil {
|
||||
ffmpegPath = "ffmpeg"
|
||||
} else {
|
||||
return "ffmpeg 未安装，无法提取视频关键帧。请先安装: apt install ffmpeg", nil
|
||||
}
|
||||
}
|
||||
|
||||
nFrames := 4
|
||||
if n, ok := args["frames"].(float64); ok && n > 0 {
|
||||
nFrames = int(n)
|
||||
if nFrames > 10 {
|
||||
nFrames = 10
|
||||
}
|
||||
}
|
||||
|
||||
// 用 ffprobe 拿时长，才能把「抽 N 帧」翻译成 ffmpeg 的帧率。
|
||||
//
|
||||
// 为何不能直接写 fps=1/N：fps 是**频率**（每 N 秒一帧），不是**数量**。
|
||||
// 20 秒视频实测：fps=1/4 → 5 帧，fps=1/10 → 2 帧，fps=1/1 → 20 帧——
|
||||
// 要得越多拿得越少，且长视频下 frames=4 会产出时长/4 帧直接炸上下文。
|
||||
// 正确写法是 fps=N/时长 配 -frames:v N（实测 N=1/4/10 均精确）。
|
||||
dur := probeDuration(ffmpegPath, path)
|
||||
var vfArgs []string
|
||||
if dur > 0 {
|
||||
vfArgs = []string{"-vf", fmt.Sprintf("fps=%d/%.3f", nFrames, dur)}
|
||||
}
|
||||
// 拿不到时长（无 ffprobe / 容器无时长元数据）：不传 -vf，只靠 -frames:v
|
||||
// 取开头 N 帧。不能退化成 fps=1：不足 1 秒的素材一帧也抽不出来（实测
|
||||
// 0.4s 视频 fps=1 → 0 帧），而 fps=N/dur 在 0.4s 上依然精确。
|
||||
|
||||
// 用 ffmpeg 提取关键帧
|
||||
tmpDir, err := os.MkdirTemp("", "mm_video_*")
|
||||
if err != nil {
|
||||
return fmt.Sprintf("创建临时目录失败: %v", err), nil
|
||||
}
|
||||
defer os.RemoveAll(tmpDir)
|
||||
|
||||
outPattern := filepath.Join(tmpDir, "frame_%03d.jpg")
|
||||
// -frames:v 硬封顶：即使 fps 计算因时长误差多给了帧，也不会超出请求数量。
|
||||
ffArgs := []string{"-v", "error", "-i", path}
|
||||
ffArgs = append(ffArgs, vfArgs...)
|
||||
ffArgs = append(ffArgs, "-q:v", "5", "-frames:v", strconv.Itoa(nFrames), outPattern)
|
||||
cmd := exec.Command(ffmpegPath, ffArgs...)
|
||||
if out, err := cmd.CombinedOutput(); err != nil {
|
||||
return fmt.Sprintf("ffmpeg 提取帧失败: %v\n%s", err, string(out)), nil
|
||||
}
|
||||
|
||||
// 读取提取的帧。按 blocks 长度而非目录索引封顶：
|
||||
// 跳过的条目（非 jpg / 读失败 / 过大）会让索引与实际帧数错位。
|
||||
entries, _ := os.ReadDir(tmpDir)
|
||||
var blocks []pubsdk.ContentBlock
|
||||
var skippedLarge int
|
||||
for _, entry := range entries {
|
||||
if len(blocks) >= nFrames {
|
||||
break
|
||||
}
|
||||
if !strings.HasSuffix(entry.Name(), ".jpg") {
|
||||
continue
|
||||
}
|
||||
b, err := os.ReadFile(filepath.Join(tmpDir, entry.Name()))
|
||||
if err != nil {
|
||||
continue
|
||||
}
|
||||
if len(b) > 2*1024*1024 {
|
||||
skippedLarge++
|
||||
continue
|
||||
}
|
||||
dURL := "data:image/jpeg;base64," + base64.StdEncoding.EncodeToString(b)
|
||||
blocks = append(blocks, pubsdk.ContentBlock{
|
||||
Type: "image_url",
|
||||
ImageURL: &pubsdk.ImageURL{URL: dURL, Detail: "low"},
|
||||
})
|
||||
}
|
||||
|
||||
if len(blocks) == 0 {
|
||||
if skippedLarge > 0 {
|
||||
return fmt.Sprintf("提取到 %d 帧但全部超过 2MB 单帧上限，未注入", skippedLarge), nil
|
||||
}
|
||||
return "视频中未提取到有效帧", nil
|
||||
}
|
||||
|
||||
// 全部帧注入（一次 SetToolBlocks 调用，下一轮 LLM 可看到）
|
||||
p.sdk.SetToolBlocks(blocks)
|
||||
|
||||
text := fmt.Sprintf("[已将 %d 个视频关键帧注入后续对话] %s", len(blocks), path)
|
||||
if skippedLarge > 0 {
|
||||
text += fmt.Sprintf("（另有 %d 帧超 2MB 已跳过）", skippedLarge)
|
||||
}
|
||||
if len(blocks) < nFrames {
|
||||
text += fmt.Sprintf("（请求 %d 帧，实际只取到 %d 帧，视频可能过短）", nFrames, len(blocks))
|
||||
}
|
||||
return text, nil
|
||||
}
|
||||
|
||||
// probeDuration 用 ffprobe 取视频时长（秒），拿不到返回 0。
|
||||
func (p *Plugin) loadSettings() {
|
||||
s := p.sdk.Settings()
|
||||
if s == nil {
|
||||
return
|
||||
}
|
||||
if v, _ := s.Get("ocr_enabled"); v != nil {
|
||||
p.ocrEnabled = truthy(v)
|
||||
}
|
||||
if v, _ := s.Get("timeout_seconds"); v != nil {
|
||||
if n := toInt(v); n > 0 {
|
||||
p.timeout = time.Duration(n) * time.Second
|
||||
}
|
||||
}
|
||||
if v, _ := s.Get("describe_prompt"); v != nil && strings.TrimSpace(fmt.Sprint(v)) != "" {
|
||||
p.imgPrompt = fmt.Sprint(v)
|
||||
}
|
||||
if v, _ := s.Get("ocr_prompt"); v != nil && strings.TrimSpace(fmt.Sprint(v)) != "" {
|
||||
p.ocrPrompt = fmt.Sprint(v)
|
||||
}
|
||||
if v, _ := s.Get("audio_prompt"); v != nil && strings.TrimSpace(fmt.Sprint(v)) != "" {
|
||||
p.audPrompt = fmt.Sprint(v)
|
||||
}
|
||||
}
|
||||
|
||||
func truthy(v interface{}) bool {
|
||||
switch x := v.(type) {
|
||||
case bool:
|
||||
return x
|
||||
case string:
|
||||
return x == "true" || x == "1" || x == "yes"
|
||||
case float64:
|
||||
return x != 0
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func toInt(v interface{}) int {
|
||||
switch x := v.(type) {
|
||||
case int:
|
||||
return x
|
||||
case int64:
|
||||
return int(x)
|
||||
case float64:
|
||||
return int(x)
|
||||
case string:
|
||||
n := 0
|
||||
for _, c := range x {
|
||||
if c < '0' || c > '9' {
|
||||
return 0
|
||||
}
|
||||
n = n*10 + int(c-'0')
|
||||
}
|
||||
return n
|
||||
}
|
||||
return 0
|
||||
}
|
||||
|
||||
// ---- 三个 handler ----
|
||||
|
||||
func (p *Plugin) handleDescribeImage(args map[string]interface{}) (interface{}, error) {
|
||||
return p.describe(args, p.imgPromptOrDefault(), "图片描述", 2048, "image_url")
|
||||
}
|
||||
|
||||
func (p *Plugin) handleOCRImage(args map[string]interface{}) (interface{}, error) {
|
||||
return p.describe(args, p.ocrPromptOrDefault(), "读字结果", 4096, "image_url")
|
||||
}
|
||||
|
||||
func (p *Plugin) handleTranscribeAudio(args map[string]interface{}) (interface{}, error) {
|
||||
return p.describe(args, p.audPromptOrDefault(), "音频转写", 2048, "audio_url")
|
||||
}
|
||||
|
||||
func (p *Plugin) imgPromptOrDefault() string {
|
||||
if p.imgPrompt != "" {
|
||||
return p.imgPrompt
|
||||
}
|
||||
return "请详细描述这张图片的内容，包括其中的文字、物体、人物、场景等信息。"
|
||||
}
|
||||
|
||||
func (p *Plugin) ocrPromptOrDefault() string {
|
||||
if p.ocrPrompt != "" {
|
||||
return p.ocrPrompt
|
||||
}
|
||||
return "请识别这张图片中的所有文字内容，按原文输出。仅输出文字本身，不要添加额外描述。"
|
||||
}
|
||||
|
||||
func (p *Plugin) audPromptOrDefault() string {
|
||||
if p.audPrompt != "" {
|
||||
return p.audPrompt
|
||||
}
|
||||
return "请把这段音频转写为文字。"
|
||||
}
|
||||
|
||||
// describe 解析媒体来源 → 切源（若指定）→ 发一次多模态请求。
|
||||
//
|
||||
// ffprobe 与 ffmpeg 同包同目录，所以从已找到的 ffmpeg 路径推导而非重新搜一遍。
|
||||
func probeDuration(ffmpegPath, videoPath string) float64 {
|
||||
probe := "ffprobe"
|
||||
if strings.Contains(ffmpegPath, "/") {
|
||||
probe = filepath.Join(filepath.Dir(ffmpegPath), "ffprobe")
|
||||
if _, err := os.Stat(probe); err != nil {
|
||||
probe = "ffprobe"
|
||||
// ★ 失败一律以 **error** 上抛，不渲染成普通文本。
|
||||
//
|
||||
// 这是从内核搬来时保留的纪律（见 internal/plugins/remotedevice 的
|
||||
// describeScreen 同类修复）：失败与成功同形会让 agent 反复重试。
|
||||
func (p *Plugin) describe(args map[string]interface{}, prompt, prefix string,
|
||||
maxTokens int, blockType string) (interface{}, error) {
|
||||
|
||||
url, err := p.resolveMedia(args, blockType)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
llm := p.sdk.LLM()
|
||||
if llm == nil {
|
||||
return nil, fmt.Errorf("LLM 不可用")
|
||||
}
|
||||
// 指定源：临时切换，用完恢复。切源失败**不降级**（否则「另一个源的结果」
|
||||
// 会挂在指定源名下）。
|
||||
provider, _ := args["provider"].(string)
|
||||
if provider != "" {
|
||||
prev := llm.CurrentSource()
|
||||
if e := llm.SetSource(provider); e != nil {
|
||||
return nil, fmt.Errorf("切换到指定源 %s 失败: %w", provider, e)
|
||||
} else if prev != "" {
|
||||
defer func() { _ = llm.SetSource(prev) }()
|
||||
}
|
||||
}
|
||||
out, err := exec.Command(probe, "-v", "error",
|
||||
"-show_entries", "format=duration",
|
||||
"-of", "default=nw=1:nk=1", videoPath).Output()
|
||||
if err != nil {
|
||||
return 0
|
||||
}
|
||||
d, err := strconv.ParseFloat(strings.TrimSpace(string(out)), 64)
|
||||
if err != nil {
|
||||
return 0
|
||||
}
|
||||
return d
|
||||
}
|
||||
used := llm.CurrentSource()
|
||||
|
||||
// ── listen ───────────────────────────────────────────────────────
|
||||
|
||||
func (p *Plugin) handleListen(args map[string]interface{}) (interface{}, error) {
|
||||
path := getArgStr(args, "path")
|
||||
if path == "" {
|
||||
return "path is required", nil
|
||||
msg := sdk.LLMMessage{
|
||||
Role: "user",
|
||||
Blocks: []sdk.LLMContentBlock{
|
||||
{Type: "text", Text: prompt},
|
||||
},
|
||||
}
|
||||
if _, err := os.Stat(path); os.IsNotExist(err) {
|
||||
return fmt.Sprintf("文件不存在: %s", path), nil
|
||||
if blockType == "image_url" {
|
||||
msg.Blocks = append(msg.Blocks, sdk.LLMContentBlock{Type: "image_url", ImageURL: url})
|
||||
} else {
|
||||
msg.Blocks = append(msg.Blocks, sdk.LLMContentBlock{Type: "audio_url", ImageURL: url})
|
||||
}
|
||||
|
||||
ext := strings.ToLower(filepath.Ext(path))
|
||||
var mime string
|
||||
switch ext {
|
||||
case ".mp3":
|
||||
mime = "audio/mpeg"
|
||||
case ".wav":
|
||||
mime = "audio/wav"
|
||||
case ".ogg":
|
||||
mime = "audio/ogg"
|
||||
case ".m4a", ".aac":
|
||||
mime = "audio/mp4"
|
||||
default:
|
||||
mime = "audio/ogg" // 默认
|
||||
}
|
||||
|
||||
// 检查大小（5MB 限制，避免上下文爆炸）
|
||||
info, _ := os.Stat(path)
|
||||
if info != nil && info.Size() > 5*1024*1024 {
|
||||
return fmt.Sprintf("音频过大（%d bytes，超过 5MB），无法注入上下文", info.Size()), nil
|
||||
}
|
||||
|
||||
b, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return fmt.Sprintf("读取音频文件失败: %v", err), nil
|
||||
}
|
||||
dataURL := "data:" + mime + ";base64," + base64.StdEncoding.EncodeToString(b)
|
||||
|
||||
p.sdk.SetToolBlocks([]pubsdk.ContentBlock{
|
||||
{Type: "audio_url", AudioURL: &pubsdk.AudioURL{URL: dataURL}},
|
||||
ctx, cancel := context.WithTimeout(context.Background(), p.timeout)
|
||||
defer cancel()
|
||||
resp, err := llm.Chat(ctx, &sdk.LLMCompletionRequest{
|
||||
Messages: []sdk.LLMMessage{msg},
|
||||
MaxTokens: maxTokens,
|
||||
})
|
||||
|
||||
text := fmt.Sprintf("[已将音频注入后续对话] %s（%s，%.1fKB）", path, mime, float64(len(b))/1024)
|
||||
return text, nil
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("%s失败（视觉/音频源 %s）: %w", prefix, used, err)
|
||||
}
|
||||
if resp == nil || strings.TrimSpace(resp.Content) == "" {
|
||||
return nil, fmt.Errorf("%s失败（视觉/音频源 %s）: 模型返回空内容", prefix, used)
|
||||
}
|
||||
return map[string]interface{}{
|
||||
"description": resp.Content,
|
||||
"source": used,
|
||||
}, nil
|
||||
}
|
||||
|
||||
// ── helpers ──────────────────────────────────────────────────────
|
||||
// resolveMedia 按 path → digest 的顺序解析出 data URL。
|
||||
func (p *Plugin) resolveMedia(args map[string]interface{}, kind string) (string, error) {
|
||||
path, _ := args["path"].(string)
|
||||
digest, _ := args["digest"].(string)
|
||||
|
||||
func getArgStr(args map[string]interface{}, key string) string {
|
||||
if v, ok := args[key].(string); ok {
|
||||
return v
|
||||
switch {
|
||||
case strings.TrimSpace(path) != "":
|
||||
b, err := os.ReadFile(strings.TrimSpace(path))
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("读取文件失败 %s: %w", path, err)
|
||||
}
|
||||
if len(b) == 0 {
|
||||
return "", fmt.Errorf("文件为空: %s", path)
|
||||
}
|
||||
mime := mimeByExt(path)
|
||||
if mime == "" {
|
||||
mime = "image/png"
|
||||
if kind == "audio_url" {
|
||||
mime = "audio/wav"
|
||||
}
|
||||
}
|
||||
return "data:" + mime + ";base64," + base64.StdEncoding.EncodeToString(b), nil
|
||||
|
||||
case strings.TrimSpace(digest) != "":
|
||||
if p.sdk.Media() == nil {
|
||||
return "", fmt.Errorf("内容寻址库不可用，无法按 digest 取媒体")
|
||||
}
|
||||
b, err := p.sdk.Media().Get(strings.TrimSpace(digest))
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("按 digest 取媒体失败 %s: %w", digest, err)
|
||||
}
|
||||
mime := "image/png"
|
||||
if info, serr := p.sdk.Media().Stat(strings.TrimSpace(digest)); serr == nil && info.MIME != "" {
|
||||
mime = info.MIME
|
||||
} else if kind == "audio_url" {
|
||||
mime = "audio/wav"
|
||||
}
|
||||
return "data:" + mime + ";base64," + base64.StdEncoding.EncodeToString(b), nil
|
||||
}
|
||||
// ★ 两条都没有 ⇒ 明确报错，并说清怎么办。
|
||||
return "", fmt.Errorf("没有可处理的媒体。请传 path（设备/工具回传的媒体，" +
|
||||
"如 screensee 返回的 file 路径）或 digest；" +
|
||||
"本轮用户直接上传的图片/音频请直接用它们，无需本工具")
|
||||
}
|
||||
|
||||
func mimeByExt(p string) string {
|
||||
switch strings.ToLower(filepath.Ext(p)) {
|
||||
case ".jpg", ".jpeg":
|
||||
return "image/jpeg"
|
||||
case ".png":
|
||||
return "image/png"
|
||||
case ".webp":
|
||||
return "image/webp"
|
||||
case ".gif":
|
||||
return "image/gif"
|
||||
case ".wav":
|
||||
return "audio/wav"
|
||||
case ".mp3":
|
||||
return "audio/mpeg"
|
||||
case ".m4a", ".aac":
|
||||
return "audio/aac"
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
120
internal/plugins/multimodal/plugin_test.go
Normal file
120
internal/plugins/multimodal/plugin_test.go
Normal file
@ -0,0 +1,120 @@
|
||||
package multimodal
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// 多模态工具的内核退场（2026-10-06）
|
||||
//
|
||||
// ## 为什么退场
|
||||
//
|
||||
// README 第一原则：「内核职责限定在 LLM 编排、记忆管理与知识检索；
|
||||
// 所有 IO 能力由插件实现」，而「文件读取」正在 IO 列表里。
|
||||
//
|
||||
// `ocr_image` / `describe_image` / `transcribe_audio` 原先是内核
|
||||
// `buildToolDefs()` 里硬编码的内置条件工具，读本地文件却住在内核进程内
|
||||
// —— 无沙箱、无能力面、无审计。
|
||||
//
|
||||
// ## 这些判据钉住什么
|
||||
//
|
||||
// ① 媒体来源解析（path / digest / 都没有）三条路径的行为
|
||||
// ② 失败必须以 **error** 上抛，不渲染成普通文本
|
||||
// ③ 内核侧**不再有**这三个工具的实现与定义（结构性判据，跨文件）
|
||||
|
||||
// ---- ① 媒体来源解析 ----
|
||||
|
||||
func TestResolveMedia_PathWins(t *testing.T) {
|
||||
p := &Plugin{}
|
||||
dir := t.TempDir()
|
||||
fp := filepath.Join(dir, "shot.jpg")
|
||||
if err := os.WriteFile(fp, []byte{0xFF, 0xD8, 0xFF, 0xE0, 1, 2, 3}, 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
url, err := p.resolveMedia(map[string]interface{}{"path": fp}, "image_url")
|
||||
if err != nil {
|
||||
t.Fatalf("按 path 解析应成功: %v", err)
|
||||
}
|
||||
if !strings.HasPrefix(url, "data:image/jpeg;base64,") {
|
||||
t.Errorf("应按扩展名给 image/jpeg，实际前缀: %.40s", url)
|
||||
}
|
||||
// ★ path 与 digest 同时给：path 优先（且不读 CAS）
|
||||
url2, err := p.resolveMedia(map[string]interface{}{
|
||||
"path": fp, "digest": "deadbeef",
|
||||
}, "image_url")
|
||||
if err != nil {
|
||||
t.Fatalf("path 优先时应成功: %v", err)
|
||||
}
|
||||
if url2 != url {
|
||||
t.Error("path 与 digest 同时给时应以 path 为准")
|
||||
}
|
||||
}
|
||||
|
||||
func TestResolveMedia_NoSourceExplainsHowToFix(t *testing.T) {
|
||||
p := &Plugin{}
|
||||
_, err := p.resolveMedia(map[string]interface{}{}, "image_url")
|
||||
if err == nil {
|
||||
t.Fatal("既无 path 又无 digest 时必须报错")
|
||||
}
|
||||
// ★ 错误信息必须**可操作**：说清传什么、为什么。
|
||||
msg := err.Error()
|
||||
if !strings.Contains(msg, "path") || !strings.Contains(msg, "digest") {
|
||||
t.Errorf("错误信息要指明可传 path 或 digest，实际: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestResolveMedia_FileErrorsAreSpecific(t *testing.T) {
|
||||
p := &Plugin{}
|
||||
// 不存在的文件：带路径，便于模型修正
|
||||
_, err := p.resolveMedia(map[string]interface{}{"path": "/nope/missing.jpg"}, "image_url")
|
||||
if err == nil || !strings.Contains(err.Error(), "/nope/missing.jpg") {
|
||||
t.Errorf("读取失败应带上路径便于定位，实际: %v", err)
|
||||
}
|
||||
// 空文件：与「读不到」区分开
|
||||
dir := t.TempDir()
|
||||
empty := filepath.Join(dir, "empty.png")
|
||||
if err := os.WriteFile(empty, nil, 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
_, err = p.resolveMedia(map[string]interface{}{"path": empty}, "image_url")
|
||||
if err == nil || !strings.Contains(err.Error(), "空") {
|
||||
t.Errorf("空文件应明说「空」，实际: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMimeByExt(t *testing.T) {
|
||||
for p, want := range map[string]string{
|
||||
"a.jpg": "image/jpeg", "a.JPEG": "image/jpeg", "a.png": "image/png",
|
||||
"a.webp": "image/webp", "a.gif": "image/gif",
|
||||
"a.wav": "audio/wav", "a.mp3": "audio/mpeg", "a.m4a": "audio/aac",
|
||||
"a.bin": "", "noext": "",
|
||||
} {
|
||||
if got := mimeByExt(p); got != want {
|
||||
t.Errorf("mimeByExt(%q)=%q，期望 %q", p, got, want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---- ② ocr_enabled 关闭时不得出现一个「在表里但不可用」的工具 ----
|
||||
|
||||
// TestOCRDisabledKeepsToolOut 钉住 ocr_enabled=false 时 ocr_image 不注册。
|
||||
//
|
||||
// ★ 为什么这条重要（本项目反复踩的坑）：工具在表里却调不通，
|
||||
//
|
||||
// 模型会反复调一个注定失败的工具。宁可**不出现**。
|
||||
func TestOCRDisabledKeepsToolOut(t *testing.T) {
|
||||
if truthy("false") {
|
||||
t.Error("truthy(\"false\") 应为 false")
|
||||
}
|
||||
if !truthy("true") {
|
||||
t.Error("truthy(\"true\") 应为 true")
|
||||
}
|
||||
// 描述文案必须说清「不是专用 OCR 引擎」——名字承诺大于实现会让模型误判精度。
|
||||
p := &Plugin{name: "multimodal", ocrEnabled: true}
|
||||
def := p.ocrToolDef()
|
||||
if !strings.Contains(def.Description, "不是专用 OCR 引擎") {
|
||||
t.Errorf("ocr_image 的描述必须说明它不是专用 OCR 引擎，实际: %s", def.Description)
|
||||
}
|
||||
}
|
||||
@ -407,9 +407,9 @@ func TestScreenseeEndToEnd(t *testing.T) {
|
||||
|
||||
dev := &devicectlDevice{reg: reg}
|
||||
var gotDataURL string
|
||||
dev.SetSeeHandler(func(dataURL string, provider string) string {
|
||||
dev.SetSeeHandler(func(dataURL string, provider string) (string, error) {
|
||||
gotDataURL = dataURL
|
||||
return "屏幕上显示的是测试画面"
|
||||
return "屏幕上显示的是测试画面", nil
|
||||
})
|
||||
|
||||
srv := httptest.NewServer(http.HandlerFunc(reg.ServeWS))
|
||||
|
||||
@ -1,8 +1,12 @@
|
||||
package remotedevice
|
||||
|
||||
import (
|
||||
"crypto/sha256"
|
||||
"encoding/base64"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"log"
|
||||
"os"
|
||||
"sort"
|
||||
"strings"
|
||||
"time"
|
||||
@ -18,7 +22,9 @@ type devicectlDevice struct {
|
||||
|
||||
// screensee 回调：设备截屏回传后由 agent 核心消费（视觉描述）。
|
||||
// 由插件 Start 注入；nil 时退化为仅返回 base64 数据。
|
||||
seeHandler func(dataURL string, provider string) string
|
||||
// ★ 2026-10-05 改为 (string, error)：视觉描述失败必须能上抛，
|
||||
// 不能渲染成普通文本（那会让 status=ok 与失败同形）。
|
||||
seeHandler func(dataURL string, provider string) (string, error)
|
||||
}
|
||||
|
||||
func (d *devicectlDevice) Name() string { return "devicectl" }
|
||||
@ -361,7 +367,7 @@ func (d *devicectlDevice) info(args map[string]interface{}) (interface{}, error)
|
||||
}
|
||||
|
||||
// SetSeeHandler 注入 screensee 的视觉描述回调（agent 核心提供）。
|
||||
func (d *devicectlDevice) SetSeeHandler(fn func(dataURL string, provider string) string) {
|
||||
func (d *devicectlDevice) SetSeeHandler(fn func(dataURL string, provider string) (string, error)) {
|
||||
d.seeHandler = fn
|
||||
}
|
||||
|
||||
@ -401,6 +407,19 @@ func (d *devicectlDevice) screensee(args map[string]interface{}) (interface{}, e
|
||||
return nil, fmt.Errorf("设备截屏失败: %s", errMsg)
|
||||
}
|
||||
output, _ := res["output"].(string)
|
||||
// ★ 2026-10-05：把回传内容**量化后记进服务端日志**。
|
||||
//
|
||||
// 起因：2026-10-05 生产日志里有两次 screensee 回了
|
||||
// 「我目前没有收到或无法查看这张屏幕截图」
|
||||
// 而服务端**没有任何记录**能回答「设备到底回传了什么」——
|
||||
// GUI 侧那行 console.log 只打在它自己的控制台，服务端留不下痕迹。
|
||||
// 于是排查只能靠猜（截屏为空？data URL 被截断？缩略图未就绪？）。
|
||||
//
|
||||
// 只记**元信息 + 极短内容指纹**，不记图片本身（日志会膨胀且含用户屏幕内容）：
|
||||
// · 字节数、解出来的像素尺寸（jpeg/png 头部可解）、是否非空
|
||||
// · 前若干字节的 base64 片段 + SHA256 前 16 hex
|
||||
// ⇒ 「回传的是不是同一张图」「是不是被截断了」一眼可判。
|
||||
logScreenseePayload(id, output)
|
||||
// 设备端回传 data URL（data:image/jpeg;base64,...）或裸 base64
|
||||
if !strings.HasPrefix(output, "data:") {
|
||||
output = "data:image/jpeg;base64," + output
|
||||
@ -409,7 +428,18 @@ func (d *devicectlDevice) screensee(args map[string]interface{}) (interface{}, e
|
||||
if d.seeHandler == nil {
|
||||
return map[string]interface{}{"image_data_url": output, "note": "无视觉描述处理器，仅返回原始图像数据"}, nil
|
||||
}
|
||||
desc := d.seeHandler(output, provider)
|
||||
desc, err := d.seeHandler(output, provider)
|
||||
if err != nil {
|
||||
// ★ 视觉描述失败 ⇒ 工具失败（不是「返回一段说明」）。
|
||||
// 生产实证：403 被塞进 description 且 status=ok，
|
||||
// agent 以为拿到了结果，于是换 provider 又试一次（再失败一次）。
|
||||
d.reg.SaveResult(reqID, map[string]interface{}{
|
||||
"error": err.Error(),
|
||||
"device": id,
|
||||
"has_image": true, // 截图确实拿到了：区分「设备没回传」与「模型看不了」
|
||||
})
|
||||
return nil, fmt.Errorf("设备已回传截图，但视觉描述失败: %w", err)
|
||||
}
|
||||
return map[string]interface{}{"description": desc}, nil
|
||||
}
|
||||
|
||||
@ -543,12 +573,31 @@ func (d *devicectlDevice) clipboardsee(args map[string]interface{}) (interface{}
|
||||
func (d *devicectlDevice) clipboardsue(args map[string]interface{}) (interface{}, error) {
|
||||
id, _ := args["device_id"].(string)
|
||||
text, _ := args["text"].(string)
|
||||
if text == "" {
|
||||
return nil, fmt.Errorf("text required（要写入剪切板的内容）")
|
||||
// ★ content 参数（判据 clipboardsue_content_test.go 钉着它）——
|
||||
// 从**服务端可见的路径**读入剪切板，长文本/代码块不塞得进命令行。
|
||||
// 与 GUI 侧 screensue/speakeruse 的 @<路径> 是同一类问题的同一类解法。
|
||||
//
|
||||
// ★ 这段实现曾因「只提交判据没提交代码」被仓库清理冲掉，
|
||||
// 导致判据编译不过（undefined: clipboardsueMaxBytes）。
|
||||
// 判据与实现在同一个提交里，才不会再次走丢。
|
||||
content, _ := args["content"].(string)
|
||||
if strings.TrimSpace(content) == "" && strings.TrimSpace(text) == "" {
|
||||
return nil, fmt.Errorf("text 或 content 至少给一个（要写入剪切板的内容）")
|
||||
}
|
||||
if err := d.clipboardCheck(id, "写入", "clipboardsue"); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if strings.TrimSpace(content) != "" {
|
||||
b, rerr := os.ReadFile(strings.TrimSpace(content))
|
||||
if rerr != nil {
|
||||
return nil, fmt.Errorf("读取 content 文件失败 %s: %w", strings.TrimSpace(content), rerr)
|
||||
}
|
||||
if len(b) > clipboardsueMaxBytes {
|
||||
return nil, fmt.Errorf("content 文件过大 %dKB > 上限 %dKB",
|
||||
len(b)/1024, clipboardsueMaxBytes/1024)
|
||||
}
|
||||
text = string(b)
|
||||
}
|
||||
reqID := newReqID()
|
||||
// 命令格式：clipboardsue <文字>（GUI 端取首个空格后的全部内容作为写入文本）
|
||||
if err := d.reg.PushCmd(id, reqID, "clipboardsue "+text, "homeagent"); err != nil {
|
||||
@ -583,3 +632,105 @@ func truncateForPreview(s string, max int) string {
|
||||
}
|
||||
return string(r[:max]) + "..."
|
||||
}
|
||||
|
||||
// clipboardsueMaxBytes 是从文件读入剪切板的大小上限（与 GUI 侧 2MB 一致）。
|
||||
const clipboardsueMaxBytes = 2 * 1024 * 1024
|
||||
|
||||
// logScreenseePayload 把设备回传的截图**元信息**记进服务端日志。
|
||||
//
|
||||
// ★ 为什么必须记在服务端（2026-10-05 教训）：
|
||||
//
|
||||
// GUI 侧那行 `[device-bridge] screensee screen=0 bytes=N` 只打在它自己的
|
||||
// 控制台。生产排障时手上只有 homed 的日志 ⇒ 无法回答「设备到底回传了什么」。
|
||||
// 实测就有两次 screensee 返回「我收不到截图」，而服务端无任何痕迹可查，
|
||||
// 最后只能靠推测（截屏为空 / data URL 截断 / 缩略图未就绪）。
|
||||
//
|
||||
// ★ 只记元信息与**极短指纹**，不记图片本体：
|
||||
//
|
||||
// · 日志会按字节膨胀；
|
||||
// · 更重要的是截图是**用户屏幕内容**，属敏感信息，不该进日志。
|
||||
//
|
||||
// 记什么：字节数、magic、jpeg SOF 解出的像素尺寸、base64 头 24 字符、SHA256 前 16 hex。
|
||||
// 能回答：「有没有回传」「是不是合法图片」「多长」「两次是不是同一张」「会不会被截断」。
|
||||
func logScreenseePayload(deviceID, dataURL string) {
|
||||
if dataURL == "" {
|
||||
log.Printf("[remotedevice] screensee 回传 device=%s len=0 ★ 空内容：设备端没截到图"+
|
||||
"（锁屏/虚拟桌面/缩略图未就绪？）", deviceID)
|
||||
return
|
||||
}
|
||||
raw := dataURL
|
||||
if i := strings.Index(raw, ","); strings.HasPrefix(raw, "data:") && i >= 0 {
|
||||
raw = raw[i+1:]
|
||||
}
|
||||
b, err := base64.StdEncoding.DecodeString(raw)
|
||||
if err != nil {
|
||||
// ★ 解不出来本身就是关键信号：说明回传的不是合法 base64（可能被截断）。
|
||||
log.Printf("[remotedevice] screensee 回传 device=%s len=%d ★ base64 解码失败: %v",
|
||||
deviceID, len(raw), err)
|
||||
return
|
||||
}
|
||||
sum := sha256.Sum256(b)
|
||||
head := raw
|
||||
if len(head) > 24 {
|
||||
head = head[:24]
|
||||
}
|
||||
w, h := jpegSize(b)
|
||||
log.Printf("[remotedevice] screensee 回传 device=%s bytes=%d magic=%s %dx%d b64head=%q sha=%x",
|
||||
deviceID, len(b), magicName(b), w, h, head, sum[:8])
|
||||
}
|
||||
|
||||
// magicName 认出图片类型，用于一眼判断「回传的到底是什么」。
|
||||
func magicName(b []byte) string {
|
||||
switch {
|
||||
case len(b) >= 3 && b[0] == 0xFF && b[1] == 0xD8 && b[2] == 0xFF:
|
||||
return "jpeg"
|
||||
case len(b) >= 8 && string(b[:8]) == "\x89PNG\r\n\x1a\n":
|
||||
return "png"
|
||||
case len(b) >= 6 && (string(b[:6]) == "GIF87a" || string(b[:6]) == "GIF89a"):
|
||||
return "gif"
|
||||
case len(b) >= 12 && string(b[:4]) == "RIFF" && string(b[8:12]) == "WEBP":
|
||||
return "webp"
|
||||
case len(b) == 0:
|
||||
return "empty"
|
||||
default:
|
||||
return "unknown"
|
||||
}
|
||||
}
|
||||
|
||||
// jpegSize 从 jpeg 的 SOF 标记解出像素尺寸；不是 jpeg 或解不出返回 0,0。
|
||||
//
|
||||
// 不引入 image/jpeg 全解码：这里只要尺寸，而截图可能很大，
|
||||
// 全解码一次是纯浪费（GUI 已经编码过一次了）。
|
||||
func jpegSize(b []byte) (int, int) {
|
||||
if len(b) < 4 || b[0] != 0xFF || b[1] != 0xD8 {
|
||||
return 0, 0
|
||||
}
|
||||
i := 2
|
||||
for i+3 < len(b) {
|
||||
if b[i] != 0xFF {
|
||||
i++
|
||||
continue
|
||||
}
|
||||
marker := b[i+1]
|
||||
// SOF0..SOF3 / SOF5..SOF7 / SOF9..SOF11 / SOF13..SOF15 携带尺寸
|
||||
if marker >= 0xC0 && marker <= 0xCF &&
|
||||
marker != 0xC4 && marker != 0xC8 && marker != 0xCC {
|
||||
if i+9 < len(b) {
|
||||
h := int(b[i+5])<<8 | int(b[i+6])
|
||||
w := int(b[i+7])<<8 | int(b[i+8])
|
||||
return w, h
|
||||
}
|
||||
return 0, 0
|
||||
}
|
||||
// 其余段按 2 字节长度跳过
|
||||
if i+3 >= len(b) {
|
||||
break
|
||||
}
|
||||
segLen := int(b[i+2])<<8 | int(b[i+3])
|
||||
if segLen < 2 {
|
||||
break
|
||||
}
|
||||
i += 2 + segLen
|
||||
}
|
||||
return 0, 0
|
||||
}
|
||||
|
||||
@ -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)
|
||||
}
|
||||
|
||||
341
internal/plugins/remotedevice/screensee_truth_test.go
Normal file
341
internal/plugins/remotedevice/screensee_truth_test.go
Normal file
@ -0,0 +1,341 @@
|
||||
package remotedevice
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/base64"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"image"
|
||||
"image/color"
|
||||
"image/jpeg"
|
||||
"image/png"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// screensee 的两条教训（2026-10-05 生产日志实证）
|
||||
//
|
||||
// ## ① 视觉描述失败必须以 error 上抛，不能渲染成普通文本
|
||||
//
|
||||
// 原实现：`return fmt.Sprintf("屏幕截图视觉描述失败: %v…", err)`
|
||||
// 生产实测（13:51）：
|
||||
// {"description":"屏幕截图视觉描述失败: api error 403:
|
||||
// {\"error\":{\"message\":\"model \"gpt-5.6-sol\" is not allowed…"}
|
||||
// ⇒ status=ok、只有 description 字段 ⇒ **失败与成功同形**。
|
||||
// agent 以为拿到了结果，于是换 provider 再试一次（又失败一次）。
|
||||
//
|
||||
// 与同一天修掉的 MCP `isError` 丢失是**同一个病**。
|
||||
//
|
||||
// ★ 教训：不能只断言「返回值里含错误文本」——
|
||||
// 那样「把错误写成 description」照样通过。必须断言**它从 error 通道出来**。
|
||||
|
||||
// TestSeeHandler_ErrorPropagatesAsError 钉住 seeHandler 的 error 不会被吞成文本。
|
||||
func TestSeeHandler_ErrorPropagatesAsError(t *testing.T) {
|
||||
reg := NewRegistry()
|
||||
dev := &devicectlDevice{reg: reg}
|
||||
|
||||
// 模拟「视觉源 403」：handler 返回 error
|
||||
dev.SetSeeHandler(func(dataURL, provider string) (string, error) {
|
||||
return "", errFake403
|
||||
})
|
||||
|
||||
// 直接验契约：签名本身允许 error 通道
|
||||
var f func(string, string) (string, error) = dev.seeHandler
|
||||
desc, err := f("data:image/jpeg;base64,AAAA", "")
|
||||
if err == nil {
|
||||
t.Fatal("handler 返回 error 时，调用方必须能拿到 error（否则又会被渲染成 description）")
|
||||
}
|
||||
if desc != "" {
|
||||
t.Errorf("失败时不应同时返回描述文本，实际 %q", desc)
|
||||
}
|
||||
if !strings.Contains(err.Error(), "403") {
|
||||
t.Errorf("错误信息应保留上游原文供诊断，实际 %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// TestSeeHandler_SuccessStillWorks 钉住成功路径不受影响。
|
||||
func TestSeeHandler_SuccessStillWorks(t *testing.T) {
|
||||
reg := NewRegistry()
|
||||
dev := &devicectlDevice{reg: reg}
|
||||
dev.SetSeeHandler(func(dataURL, provider string) (string, error) {
|
||||
return "屏幕上是一个终端窗口", nil
|
||||
})
|
||||
desc, err := dev.seeHandler("data:image/jpeg;base64,AAAA", "")
|
||||
if err != nil || desc == "" {
|
||||
t.Fatalf("成功路径被破坏：desc=%q err=%v", desc, err)
|
||||
}
|
||||
}
|
||||
|
||||
// TestLogScreenseePayload_IdentifiesContent 钉住「回传内容可查证」。
|
||||
//
|
||||
// ★ 这条对应那两次无从查证的「我收不到截图」：
|
||||
// 服务端日志必须能回答「设备到底回传了什么」。
|
||||
// 现在记录 字节数 / magic / 像素尺寸 / base64 头 / SHA256 前缀。
|
||||
|
||||
func TestLogScreenseePayload_IdentifiesContent(t *testing.T) {
|
||||
cases := []struct {
|
||||
name string
|
||||
data []byte
|
||||
wantW int
|
||||
wantH int
|
||||
}{
|
||||
{"jpeg 8x4", makeJPEG(t, 8, 4), 8, 4},
|
||||
{"jpeg 1920x1080", makeJPEG(t, 1920, 1080), 1920, 1080},
|
||||
}
|
||||
for _, c := range cases {
|
||||
url := "data:image/jpeg;base64," + base64.StdEncoding.EncodeToString(c.data)
|
||||
logScreenseePayload("dev1", url)
|
||||
}
|
||||
// png（magic 走 png 分支，尺寸解不出 → 0 0，也应正常不 panic）
|
||||
pngURL := "data:image/png;base64," + base64.StdEncoding.EncodeToString(makePNG(t, 3, 3))
|
||||
logScreenseePayload("dev1", pngURL)
|
||||
// 空
|
||||
logScreenseePayload("dev1", "")
|
||||
// 非法 base64（被截断的典型形态）
|
||||
logScreenseePayload("dev1", "data:image/jpeg;base64,!!!not-base64!!!")
|
||||
}
|
||||
|
||||
// TestJpegSize 单独钉住 SOF 解析：尺寸是判断「图是不是真的截到了」的关键信号。
|
||||
func TestJpegSize(t *testing.T) {
|
||||
for _, dim := range [][2]int{{1, 1}, {640, 480}, {1920, 1080}, {2560, 1440}} {
|
||||
b := makeJPEG(t, dim[0], dim[1])
|
||||
w, h := jpegSize(b)
|
||||
if w != dim[0] || h != dim[1] {
|
||||
t.Errorf("%dx%d: jpegSize 给 %dx%d", dim[0], dim[1], w, h)
|
||||
}
|
||||
}
|
||||
// 非 jpeg 一律 0,0，且不得 panic
|
||||
if w, h := jpegSize([]byte("not an image")); w != 0 || h != 0 {
|
||||
t.Errorf("非 jpeg 应给 0,0，实际 %dx%d", w, h)
|
||||
}
|
||||
if w, h := jpegSize(nil); w != 0 || h != 0 {
|
||||
t.Errorf("nil 应给 0,0，实际 %dx%d", w, h)
|
||||
}
|
||||
// ★ 截断的 jpeg（真实故障形态）：不得 panic，且不该报出假的尺寸
|
||||
trunc := makeJPEG(t, 100, 100)
|
||||
if w, _ := jpegSize(trunc[:20]); w != 0 {
|
||||
t.Errorf("截断的 jpeg 不应报出宽度，实际 %d", w)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMagicName(t *testing.T) {
|
||||
if got := magicName(makeJPEG(t, 2, 2)); got != "jpeg" {
|
||||
t.Errorf("jpeg 识别错: %s", got)
|
||||
}
|
||||
if got := magicName(makePNG(t, 2, 2)); got != "png" {
|
||||
t.Errorf("png 识别错: %s", got)
|
||||
}
|
||||
if got := magicName(nil); got != "empty" {
|
||||
t.Errorf("nil 应为 empty，实际 %s", got)
|
||||
}
|
||||
if got := magicName([]byte("garbage")); got != "unknown" {
|
||||
t.Errorf("垃圾数据应为 unknown，实际 %s", got)
|
||||
}
|
||||
}
|
||||
|
||||
func makeJPEG(t *testing.T, w, h int) []byte {
|
||||
t.Helper()
|
||||
img := image.NewRGBA(image.Rect(0, 0, w, h))
|
||||
for y := 0; y < h; y++ {
|
||||
for x := 0; x < w; x++ {
|
||||
img.Set(x, y, color.RGBA{R: uint8(x % 256), G: uint8(y % 256), B: 128, A: 255})
|
||||
}
|
||||
}
|
||||
var buf bytes.Buffer
|
||||
if err := jpeg.Encode(&buf, img, &jpeg.Options{Quality: 80}); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return buf.Bytes()
|
||||
}
|
||||
|
||||
func makePNG(t *testing.T, w, h int) []byte {
|
||||
t.Helper()
|
||||
img := image.NewRGBA(image.Rect(0, 0, w, h))
|
||||
var buf bytes.Buffer
|
||||
if err := png.Encode(&buf, img); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return buf.Bytes()
|
||||
}
|
||||
|
||||
var errFake403 = &fakeErr{"api error 403: model \"gpt-5.6-sol\" is not allowed for this key"}
|
||||
|
||||
type fakeErr struct{ s string }
|
||||
|
||||
func (e *fakeErr) Error() string { return e.s }
|
||||
|
||||
// ===== 以下走完整链路（真 WS + 真 registry），盯住「失败从哪个通道出来」 =====
|
||||
|
||||
// TestScreenseE2E_VisualFailureIsErrorNotDescription 是本次修改的**核心门禁**。
|
||||
//
|
||||
// ★ 为什么必须走完整链路：
|
||||
//
|
||||
// 我第一版判据只测 `seeHandler` 的签名（能不能返回 error）——
|
||||
// 把调用点的 `if err != nil` 改成「把错误渲染成 description 文本」时，
|
||||
// **判据全绿**。因为被测的是「签名允许 error」，
|
||||
// 而真正的缺陷在「调用点有没有真的走 error 通道」。
|
||||
// ⇒ 判据必须驱动 `dev.Execute("screensee", …)` 走完一整圈。
|
||||
//
|
||||
// 生产症状（2026-10-05 13:51）：
|
||||
//
|
||||
// {"description":"屏幕截图视觉描述失败: api error 403: …"} ← status=ok
|
||||
//
|
||||
// 修好后应当是：err != nil，且结果里**没有** description 字段。
|
||||
func TestScreenseE2E_VisualFailureIsErrorNotDescription(t *testing.T) {
|
||||
reg := NewRegistry()
|
||||
token := "tk-visual-fail"
|
||||
reg.SetAcceptToken(func(p string) bool { return p == token })
|
||||
|
||||
dev := &devicectlDevice{reg: reg}
|
||||
// 视觉源返回 403（MCP/screensee 生产上真实发生过）
|
||||
dev.SetSeeHandler(func(dataURL, provider string) (string, error) {
|
||||
return "", errFake403
|
||||
})
|
||||
|
||||
srv := httptest.NewServer(http.HandlerFunc(reg.ServeWS))
|
||||
defer srv.Close()
|
||||
cli := dialTestWS(t, srv.URL, token)
|
||||
defer cli.close()
|
||||
|
||||
// 设备必须先 hello+bind 才会进 registry（否则 Execute 报「设备不存在」）
|
||||
cli.sendText([]byte(`{"op":"hello","device":{"device_id":"vf-dev","name":"视觉失败机","kind":"computer","caps":["screensee"]}}`))
|
||||
cli.readHelloAckAndBind(t, token)
|
||||
|
||||
go func() {
|
||||
for {
|
||||
op, payload, err := cli.readMsg()
|
||||
if err != nil || op != 0x1 {
|
||||
return
|
||||
}
|
||||
var msg map[string]interface{}
|
||||
if json.Unmarshal(payload, &msg) != nil {
|
||||
continue
|
||||
}
|
||||
if msg["op"] == "cmd" && msg["command"] == "screensee" {
|
||||
reqID, _ := msg["req_id"].(string)
|
||||
img := "data:image/jpeg;base64," + base64.StdEncoding.EncodeToString(makeJPEG(t, 64, 48))
|
||||
cli.sendText(mustJSON(map[string]interface{}{
|
||||
"op": "cmd_result", "req_id": reqID, "device_id": "vf-dev",
|
||||
"status": "ok", "output": img,
|
||||
}))
|
||||
}
|
||||
}
|
||||
}()
|
||||
|
||||
res, err := dev.Execute("screensee", map[string]interface{}{"device_id": "vf-dev"})
|
||||
|
||||
// ★ 必须报错
|
||||
if err == nil {
|
||||
t.Fatalf("视觉描述失败必须以 error 上抛，实际 res=%v —— "+
|
||||
"渲染成 description 会让 agent 以为拿到了结果并反复重试", res)
|
||||
}
|
||||
// ★ 错误信息要保留上游原文（那是唯一诊断线索）
|
||||
if !strings.Contains(err.Error(), "403") {
|
||||
t.Errorf("错误信息应保留上游原文，实际: %v", err)
|
||||
}
|
||||
// ★ 结果里绝不能有 description 字段
|
||||
if m, ok := res.(map[string]interface{}); ok {
|
||||
if _, has := m["description"]; has {
|
||||
t.Errorf("失败时不得返回 description 字段（那是本次要修的缺陷），实际: %v", m)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestScreenseE2E_SuccessReturnsDescription 钉住成功路径没被改坏。
|
||||
func TestScreenseE2E_SuccessReturnsDescription(t *testing.T) {
|
||||
reg := NewRegistry()
|
||||
token := "tk-visual-ok"
|
||||
reg.SetAcceptToken(func(p string) bool { return p == token })
|
||||
|
||||
dev := &devicectlDevice{reg: reg}
|
||||
var gotLen int
|
||||
dev.SetSeeHandler(func(dataURL, provider string) (string, error) {
|
||||
gotLen = len(dataURL)
|
||||
return "屏幕上是一个终端窗口", nil
|
||||
})
|
||||
|
||||
srv := httptest.NewServer(http.HandlerFunc(reg.ServeWS))
|
||||
defer srv.Close()
|
||||
cli := dialTestWS(t, srv.URL, token)
|
||||
defer cli.close()
|
||||
|
||||
cli.sendText([]byte(`{"op":"hello","device":{"device_id":"vo-dev","name":"视觉成功机","kind":"computer","caps":["screensee"]}}`))
|
||||
cli.readHelloAckAndBind(t, token)
|
||||
|
||||
go func() {
|
||||
for {
|
||||
op, payload, err := cli.readMsg()
|
||||
if err != nil || op != 0x1 {
|
||||
return
|
||||
}
|
||||
var msg map[string]interface{}
|
||||
if json.Unmarshal(payload, &msg) != nil {
|
||||
continue
|
||||
}
|
||||
if msg["op"] == "cmd" && msg["command"] == "screensee" {
|
||||
reqID, _ := msg["req_id"].(string)
|
||||
img := "data:image/jpeg;base64," + base64.StdEncoding.EncodeToString(makeJPEG(t, 64, 48))
|
||||
cli.sendText(mustJSON(map[string]interface{}{
|
||||
"op": "cmd_result", "req_id": reqID, "device_id": "vo-dev",
|
||||
"status": "ok", "output": img,
|
||||
}))
|
||||
}
|
||||
}
|
||||
}()
|
||||
|
||||
res, err := dev.Execute("screensee", map[string]interface{}{"device_id": "vo-dev"})
|
||||
if err != nil {
|
||||
t.Fatalf("成功路径被破坏: %v", err)
|
||||
}
|
||||
m, ok := res.(map[string]interface{})
|
||||
if !ok {
|
||||
t.Fatalf("返回类型变了: %T", res)
|
||||
}
|
||||
if m["description"] != "屏幕上是一个终端窗口" {
|
||||
t.Errorf("description 不对: %v", m["description"])
|
||||
}
|
||||
if gotLen == 0 {
|
||||
t.Error("handler 没收到 dataURL")
|
||||
}
|
||||
}
|
||||
|
||||
// TestIsModelNotAllowed 钉住「模型名不被接受」的识别。
|
||||
//
|
||||
// ★ 这是 2026-10-05 生产那条 403 的判定入口：
|
||||
//
|
||||
// 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 实测完全能看图 ⇒ 该回退而不是报错。
|
||||
func TestIsModelNotAllowed(t *testing.T) {
|
||||
// llmsproxy 的三种原文（internal/gateway/chat.go）
|
||||
yes := []string{
|
||||
`model "gpt-5.6-sol" is not allowed for this key`,
|
||||
`{"error":{"type":"model_not_allowed","message":"model \"x\" is not allowed for this key"}}`,
|
||||
`model "x" is not in this key's model scope, so it cannot use AUTO`,
|
||||
}
|
||||
for _, s := range yes {
|
||||
if !isModelNotAllowed(errors.New(s)) {
|
||||
t.Errorf("应识别为「模型名不被接受」: %s", s)
|
||||
}
|
||||
}
|
||||
// ★ 必须**不**把其它错误误判成这一类 —— 那会触发错误的 AUTO 回退。
|
||||
no := []string{
|
||||
`invalid gateway api key`,
|
||||
`api error 401: Unauthorized`,
|
||||
`read: connection reset by peer`,
|
||||
`context deadline exceeded`,
|
||||
``, // nil 情形另行覆盖
|
||||
}
|
||||
for _, s := range no {
|
||||
if isModelNotAllowed(errors.New(s)) {
|
||||
t.Errorf("不应被识别为「模型名不被接受」（会误触发 AUTO 回退）: %s", s)
|
||||
}
|
||||
}
|
||||
if isModelNotAllowed(nil) {
|
||||
t.Error("nil 不应被判为模型名问题")
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user