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
2026-10-06 09:07:18 +08:00
parent 7e4f1058ea
commit a02d8b00a5
16 changed files with 1776 additions and 438 deletions

View 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)
}
}