feat(seemedia): 多模态直视插件——让模型一手看图/看视频/听音频 (#6)

* feat(seemedia): 新增多模态直视插件，让模型一手看图/看视频/听音频

## 动机

现有 multimodal（describe_image / transcribe_audio / ocr_image）走的是**二手**路：
插件自己起一次 VLM 子调用，把结果**文字**喂回主模型。省 token、能入记忆正文、
主模型非视觉也能用，但模型看到的是「别人转述的描述」，细节丢失不可逆。

缺的是**一手**路：让模型主动把原始像素/帧/音频投给**自己**去判读。本插件补上。

## 工具（三模态，用户决策 image+video+audio）

- `see_image`：path/digest/url → image_url 块，经 SetToolBlocks 直投主模型
- `see_video`：ffmpeg 抽帧（默认 6 帧，上限 10，对齐内核 modalfallback 约束）
  → 多张 image_url 块一起投；探时长成功走均匀定位抽帧，失败退单遍 thumbnail
- `hear_audio`：path/digest/url → audio_url 块直投

三者都 `ParallelSafe:false`：SetToolBlocks 写的是「当前 call」的块，并发会串台。

## 与 multimodal 并存（用户决策 coexist）

职责分工，不互相取代：
- 要省 token / 要把结论写进记忆 / 主模型不支持该模态 → describe_image（二手文字）
- 要模型亲自判读细节（看清截图、逐帧看操作） → see_*（一手原始媒体）

## 媒体来源（用户决策 path+digest+url 全支持）

- path：设备/工具回传的落盘文件（local_screensee、browser_screenshot、mc 截图…）
- digest：用户上传已入 CAS 的媒体，sdk.Media().Get 取回，不在内核↔插件间传 base64
- url：http(s) 直链；图/音频原样透传（不下载、不入 CAS），视频交 ffmpeg 原生读 http

## 直接进记忆（记忆载体已块化，天然打通）

seemedia 经 SetToolBlocks 注入的块，内核 task.go captureBlockMedia 处**无条件**
落进 CAS 并转成一等记忆块挂到本轮 ContextEvent（「无论直视还是回退，媒体本体都该
进记忆」）。所以一手看到的图/帧**同时**进了记忆，之后能按多模态向量被
doc_query / memory_recall 召回。本插件不写任何入库代码，复用既有块化链路。

★ 边界（刻意取舍）：captureBlockMedia 只对 data URL 入库，http(s) URL 被跳过
（不下载、不入记忆、不算向量，规避 SSRF/超时）。即 path/digest 来源可召回，
url 来源只是模型当场看到但不进记忆。要让 http 媒体长期可召回，先落盘再传 path。

## 形态：内置插件（用户决策 builtin）

与 multimodal 并排 internal/plugins/seemedia，经 all.go init() 注册。代价是延续
「内核进程内读任意本地文件」这个 a02d8b00 本想消除的张力——但 multimodal 已是
内置且同样读 path，保持一致比单独走子进程沙箱更不易让人困惑；日后收紧应两者同搬。

## 判据（可杀变异，实测）

plugin_test.go：
- url 透传且拒 file://（去掉 isHTTPURL 校验 → FAIL）
- path 优先于 digest、url 优先于 path，且 path 命中时不碰 CAS
- 无来源报错且信息可操作（指明 path/digest/url）
- 文件错误带路径、空文件明说「空」
- clampFrames 把帧数夹到 [1,10]、非正回默认（超限不夹 → FAIL）
- 三工具不得声明 ParallelSafe:true（防 SetToolBlocks 串台）

9/9 单测通过；本机 ffmpeg/ffprobe 已就位；全插件 + homed（-tags onnxruntime）
构建通过；internal/plugins 装配冒烟通过。

* test(seemedia): 补集成/压力/变异测试（16 判据，5 变异全杀）

上一个提交只带 9 个纯逻辑单测（来源解析、clamp、MIME）。抽帧是本插件唯一
真正驱动外部进程、且会并发的部分，必须真跑 ffmpeg 压一压：

- 真视频 → 请求 N 帧就拿到 N 帧，每帧校验 PNG 魔数（1/3/6/10 四档）
- ffprobe 置空 → 走单遍兜底仍能拿到帧
- 损坏/非视频文件 → 如实报错，不 panic、不返半成品
- 已取消的 ctx → ffmpeg 必须立刻失败（取消传播真生效）
- 并发 16 路抽帧 → 不串台、不泄漏临时目录（前后计数比对）
- digest 视频 → 真 CAS 取字节落临时文件，cleanup 后必须删掉
- 静态判据：所有子进程必须 exec.CommandContext，不得裸 exec.Command

为什么超时判据从「计时」改成「已取消 ctx」：合成视频抽帧本来就快（~0.1s），
「1ns 超时」和「忽略超时」在计时上分不出——实测这种变异杀不掉，是判据设计
缺陷。改用已取消 ctx 的行为判据（CommandContext 在 ctx 已取消时 Start 即失败）
后，忽略 ctx 的变异被杀。

变异实测（5/5 全 FAIL，还原后全绿）：
  A clampFrames 超限不夹        → TestClampFrames FAIL
  B url 分支去掉 isHTTPURL      → TestResolveMediaURL_URLPassthrough FAIL
  C cleanup 不删临时文件         → TestResolveVideoInput_DigestCleanup FAIL
  D grabFrameAt 忽略 ctx         → TestFrameGrabHonorsCanceledContext FAIL
  E 抽帧数写死 1                 → TestExtractFrames_RealVideoExactCount FAIL

16/16 通过；`-tags onnxruntime` 全量 homed 构建通过，三工具在册。

---------

Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>

internal/plugins/all.go

@@ -14,6 +14,7 @@ import (
 	_ "github.com/JianFeeeee/HomeAgent/internal/plugins/multimodal"
 	_ "github.com/JianFeeeee/HomeAgent/internal/plugins/pluginmgr"
 	_ "github.com/JianFeeeee/HomeAgent/internal/plugins/remotedevice"
+	_ "github.com/JianFeeeee/HomeAgent/internal/plugins/seemedia"
 	_ "github.com/JianFeeeee/HomeAgent/internal/plugins/seq"
 	_ "github.com/JianFeeeee/HomeAgent/internal/plugins/skillmgr"
 	_ "github.com/JianFeeeee/HomeAgent/internal/plugins/timer"

internal/plugins/seemedia/integration_test.go

@@ -0,0 +1,241 @@
+package seemedia
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/JianFeeeee/HomeAgent/internal/memory/media"
+	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+// 真跑 ffmpeg 的集成/压力/变异测试；无 ffmpeg 时自动跳过。
+//
+// 单测（plugin_test.go）钉纯逻辑（来源解析、clamp、MIME）；这里钉真实行为：
+//   - 抽帧真能从一段真视频拿到正确数量的合法 PNG
+//   - 探不到时长时走单遍兜底仍能拿到帧
+//   - 损坏输入如实报错、不 panic
+//   - 已取消的 ctx 必须让 ffmpeg 立刻失败（取消传播真生效）
+//   - 并发 16 路抽帧不串台、不泄漏临时目录
+//   - digest 视频走真 CAS → 临时文件 → cleanup 删文件
+
+// sdkWithVideo 用真 CAS（临时目录）把一段视频字节 Put 进去，返回带媒体面的
+// PluginSDK 与**真实 digest**（真实 CAS 的 key 是内容哈希，直接用它取回）。
+func sdkWithVideo(t *testing.T, raw []byte) (*sdk.PluginSDK, string) {
+	t.Helper()
+	dir, err := os.MkdirTemp("", "seemedia-cas-")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { os.RemoveAll(dir) })
+	store, err := media.New(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	digest, err := store.Put(raw, media.Item{MIME: "video/mp4", Tool: "test"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return sdk.New("seemedia", sdk.SDKConfig{Media: sdk.NewMedia(store)}), digest
+}
+
+func mkTestVideo(t *testing.T, dur int) string {
+	t.Helper()
+	ff, err := exec.LookPath("ffmpeg")
+	if err != nil {
+		t.Skip("无 ffmpeg，跳过集成测试")
+	}
+	out := filepath.Join(t.TempDir(), "clip.mp4")
+	cmd := exec.Command(ff, "-nostdin", "-loglevel", "error",
+		"-f", "lavfi", "-i", fmt.Sprintf("testsrc=duration=%d:size=320x240:rate=10", dur),
+		"-pix_fmt", "yuv420p", out, "-y")
+	if err := cmd.Run(); err != nil {
+		t.Skipf("ffmpeg 造测试视频失败（环境问题，跳过）: %v", err)
+	}
+	return out
+}
+
+func newProbedPlugin(t *testing.T) *Plugin {
+	t.Helper()
+	p := &Plugin{videoFrames: defaultVideoFrames, timeout: 60 * time.Second}
+	p.ffmpeg, _ = exec.LookPath("ffmpeg")
+	p.ffprobe, _ = exec.LookPath("ffprobe")
+	if p.ffmpeg == "" {
+		t.Skip("无 ffmpeg，跳过集成测试")
+	}
+	return p
+}
+
+func isPNG(b []byte) bool {
+	return len(b) >= 8 &&
+		b[0] == 0x89 && b[1] == 'P' && b[2] == 'N' && b[3] == 'G' &&
+		b[4] == 0x0D && b[5] == 0x0A && b[6] == 0x1A && b[7] == 0x0A
+}
+
+func countSeemediaTemp() int {
+	frames, _ := filepath.Glob(filepath.Join(os.TempDir(), "seemedia-frames-*"))
+	vids, _ := filepath.Glob(filepath.Join(os.TempDir(), "seemedia-*.video"))
+	return len(frames) + len(vids)
+}
+
+// ① 真视频 → 请求 N 帧就拿到 N 帧，且每帧都是合法 PNG。
+func TestExtractFrames_RealVideoExactCount(t *testing.T) {
+	p := newProbedPlugin(t)
+	video := mkTestVideo(t, 10)
+
+	for _, n := range []int{1, 3, 6, 10} {
+		frames, err := p.extractFrames(video, n)
+		if err != nil {
+			t.Fatalf("n=%d 抽帧失败: %v", n, err)
+		}
+		if len(frames) != n {
+			t.Errorf("请求 %d 帧，实得 %d 帧", n, len(frames))
+		}
+		for i, f := range frames {
+			if !isPNG(f) {
+				t.Errorf("n=%d 第 %d 帧不是合法 PNG（%d 字节）", n, i, len(f))
+			}
+		}
+	}
+}
+
+// ② 探不到时长（ffprobe 置空）时走单遍兜底，仍能拿到帧。
+func TestExtractFrames_FallbackPathWorks(t *testing.T) {
+	p := newProbedPlugin(t)
+	video := mkTestVideo(t, 6)
+
+	p.ffprobe = "" // 强制走兜底：模拟探时长失败
+	frames, err := p.extractFrames(video, 4)
+	if err != nil {
+		t.Fatalf("兜底路径抽帧失败: %v", err)
+	}
+	if len(frames) == 0 {
+		t.Fatal("兜底路径一帧都没抽到")
+	}
+	for i, f := range frames {
+		if !isPNG(f) {
+			t.Errorf("兜底第 %d 帧不是 PNG", i)
+		}
+	}
+}
+
+// ③ 损坏/非视频文件：如实报错，不 panic、不返回半成品。
+func TestExtractFrames_CorruptInput(t *testing.T) {
+	p := newProbedPlugin(t)
+	bad := filepath.Join(t.TempDir(), "notvideo.mp4")
+	if err := os.WriteFile(bad, []byte("this is definitely not a video"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	frames, err := p.extractFrames(bad, 3)
+	if err == nil && len(frames) > 0 {
+		t.Errorf("损坏输入不应抽出帧，却得到 %d 帧", len(frames))
+	}
+}
+
+// ④ 取消传播真生效：已取消的 ctx 必须让 ffmpeg 立刻失败，而不是照跑。
+//
+// 为什么不计时测 p.timeout：合成视频抽帧本来就快（~0.1s），「1ns 超时」和
+// 「忽略超时」在计时上分不出（此前实测这种变异未被杀，正是判据设计缺陷）。
+// 真正要防的是「完全不用 ctx → 无限挂」，用已取消 ctx 的行为判据来钉：
+// exec.CommandContext 在 ctx 已取消时 Start 即失败；换成 exec.Command 则照跑。
+func TestFrameGrabHonorsCanceledContext(t *testing.T) {
+	p := newProbedPlugin(t)
+	video := mkTestVideo(t, 4)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // 立即取消
+
+	b, err := p.grabFrameAt(ctx, video, 1.0)
+	if err == nil {
+		t.Fatalf("已取消的 ctx 必须让抽帧失败，却成功返回 %d 字节（ffmpeg 未被 ctx 约束）", len(b))
+	}
+}
+
+// ⑤ 压力：并发 16 路抽帧，各自独立临时目录，不串帧、不泄漏临时目录。
+func TestExtractFrames_ConcurrentNoLeak(t *testing.T) {
+	p := newProbedPlugin(t)
+	video := mkTestVideo(t, 8)
+
+	tmpBefore := countSeemediaTemp()
+
+	const workers = 16
+	var wg sync.WaitGroup
+	errs := make(chan error, workers)
+	for i := 0; i < workers; i++ {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			n := (id % 10) + 1
+			frames, err := p.extractFrames(video, n)
+			if err != nil {
+				errs <- fmt.Errorf("worker %d: %w", id, err)
+				return
+			}
+			if len(frames) == 0 {
+				errs <- fmt.Errorf("worker %d: 0 帧", id)
+			}
+		}(i)
+	}
+	wg.Wait()
+	close(errs)
+	for err := range errs {
+		t.Error(err)
+	}
+
+	time.Sleep(200 * time.Millisecond)
+	tmpAfter := countSeemediaTemp()
+	if tmpAfter > tmpBefore {
+		t.Errorf("并发抽帧泄漏临时目录: before=%d after=%d", tmpBefore, tmpAfter)
+	}
+}
+
+// ⑥ digest 视频来源：真 CAS 取字节 → 临时文件 → 抽帧 → cleanup 删文件。
+func TestResolveVideoInput_DigestCleanup(t *testing.T) {
+	p := newProbedPlugin(t)
+	video := mkTestVideo(t, 4)
+	raw, err := os.ReadFile(video)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s, digest := sdkWithVideo(t, raw)
+	p.sdk = s
+
+	input, cleanup, err := p.resolveVideoInput(map[string]interface{}{"digest": digest})
+	if err != nil {
+		t.Fatalf("digest 解析失败: %v", err)
+	}
+	if _, serr := os.Stat(input); serr != nil {
+		t.Fatalf("临时视频文件应存在: %v", serr)
+	}
+	frames, err := p.extractFrames(input, 2)
+	if err != nil || len(frames) == 0 {
+		t.Errorf("从 digest 临时文件抽帧失败: err=%v frames=%d", err, len(frames))
+	}
+	cleanup()
+	if _, serr := os.Stat(input); !os.IsNotExist(serr) {
+		t.Errorf("cleanup 后临时文件应被删除，stat=%v", serr)
+	}
+}
+
+// ⑦ 静态判据：所有 ffmpeg/ffprobe 子进程必须用 exec.CommandContext。
+//
+// CommandContext 是「任何情况下都能被 ctx 中断」的契约；换成 exec.Command
+// 就失去取消能力。这条跨实现有效：谁把 CommandContext 改回 Command，谁就引入
+// 「网络流/坏文件上无限挂」的风险。
+func TestFrameCmdsUseCommandContext(t *testing.T) {
+	src, err := os.ReadFile("plugin.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for i, line := range strings.Split(string(src), "\n") {
+		if strings.Contains(line, "exec.Command(") && !strings.Contains(line, "exec.CommandContext(") {
+			t.Errorf("plugin.go:%d 用裸 exec.Command 跑子进程 —— 必须 exec.CommandContext（ctx 取消才杀得掉）: %s", i+1, strings.TrimSpace(line))
+		}
+	}
+}

internal/plugins/seemedia/plugin.go

@@ -0,0 +1,567 @@
+// Package seemedia 让模型**主动一手**去看图/看视频/听音频。
+//
+// # 与 multimodal 插件的分工（2026-10-11 新增）
+//
+// `multimodal`（describe_image / transcribe_audio / ocr_image）走的是**二手**路：
+// 插件自己起一次 VLM 子调用，把结果**文字**喂回主模型。省 token、能入记忆正文、
+// 主模型非视觉也能用，但模型看到的是「别人转述的描述」，细节丢失不可逆。
+//
+// 本插件走的是**一手**路：把图/帧/音频的字节**直接投给主模型**，经
+// `PluginSDK.SetToolBlocks` → 内核在紧随的 user message 里带上 image_url/audio_url
+// 块（task.go `ConsumeToolBlocks`）。模型是**自己看到**原始像素，而不是读描述。
+//
+// 两者刻意并存（用户 2026-10-11 决策 coexist）：
+//   - 要省 token、要把结论写进记忆、主模型不支持该模态 → describe_image（二手）
+//   - 要模型亲自判读细节（看清一张截图、逐帧看一段操作） → see_image/see_video（一手）
+//
+// # 直视不可用时会怎样（内核已兜底，插件不必关心）
+//
+// 主模型不支持视觉/音频时，内核 `prepareToolBlocks` 会把这些块走回退链批量
+// 转写成文字再并入上下文（modalfallback.go），**不会**把 image_url 静默塞给不支持
+// 的网关（那会被剥离后返回 200，模型答「没看到图」而内核以为成功）。所以本插件
+// 只管「把字节交给内核」，支不支持、要不要回退由内核决定。
+//
+// # 媒体来源（用户决策 path + digest + url 三者都支持）
+//
+//	path   —— 设备/工具回传的落盘文件（local_screensee、browser_screenshot、mc 截图…）
+//	digest —— 用户上传已入 CAS 的媒体，用 sdk.Media().Get 取回，不在内核与插件间传 base64
+//	url    —— http(s) 直链；图/音频原样透传给模型（不下载，不入 CAS，交给上游拉取），
+//	          视频则交给 ffmpeg 直接读取（ffmpeg 原生支持 http 输入）
+//
+// # 媒体入记忆（天然打通，本插件无需自己写库）
+//
+// seemedia 经 SetToolBlocks 注入的块，内核在 task.go `captureBlockMedia` 处**无条件**
+// 落进 CAS 并转成一等记忆块挂到本轮 ContextEvent（「无论直视还是回退转写，媒体
+// 本体都该进记忆」）。所以记忆载体块化之后，一手看到的图/帧**同时**进了记忆，
+// 之后能按多模态向量被 doc_query / memory_recall 召回。本插件不写任何入库代码。
+//
+// ★ 但有一个边界：`captureBlockMedia` 只对 **data URL** 做 CAS 入库，http(s) URL
+// 会被跳过（不下载、不入记忆、不算向量——避免下载引入超时/SSRF）。因此：
+//
+//	path / digest 来源 → 转 data URL → 进记忆块（可召回）
+//	url（http 直链）  → 原样透传给模型看 → 模型看得到，但**不进记忆**
+//
+// 这是刻意取舍，不是缺陷：要让一份 http 媒体长期可召回，应先把它落盘再传 path。
+//
+// # 为什么是内置插件而不是子进程插件（用户决策 builtin）
+//
+// 与 multimodal 并排，形态一致、最省心。代价是延续了「内核进程内读任意本地文件」
+// 这个 a02d8b00 本想消除的张力——但既然 multimodal 已是内置且同样读 path，这里
+// 保持一致比单独走子进程沙箱更不易让人困惑。若日后要收紧，两个插件应一起搬。
+package seemedia
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/JianFeeeee/HomeAgent/internal/plugin"
+	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+const (
+	// defaultVideoFrames 是 see_video 默认抽取的帧数。
+	defaultVideoFrames = 6
+	// maxVideoFrames 是硬上限。对齐内核 modalfallback 的「see_video 一次最多 10 帧」
+	// 约束：帧越多上游越慢、越易超单请求体积限制，回退转写也只处理前若干块。
+	maxVideoFrames = 10
+)
+
+func init() {
+	plugin.RegisterPluginMeta("seemedia", "多模态直视", "See Media")
+	plugin.RegisterFactory("seemedia", func(name string, config map[string]interface{}) (sdk.Plugin, error) {
+		return New(name), nil
+	})
+}
+
+// Plugin 提供 see_image / see_video / hear_audio：把媒体字节直接投给主模型。
+type Plugin struct {
+	name string
+	sdk  *sdk.PluginSDK
+
+	videoFrames int
+	timeout     time.Duration
+	ffmpeg      string // ffmpeg 可执行路径（空=未探测到，see_video 会以 error 上抛）
+	ffprobe     string
+}
+
+// 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
+	p.videoFrames = defaultVideoFrames
+	p.timeout = 120 * time.Second
+
+	s.Settings().RegisterDef(sdk.ConfigDef{
+		Key: "video_frames", Default: strconv.Itoa(defaultVideoFrames), Type: "int",
+		DisplayName: "see_video 抽帧数",
+		Description: fmt.Sprintf("see_video 默认从视频里均匀抽取多少帧投给模型（1-%d）。"+
+			"帧越多模型越能看清过程变化，但上游越慢、越易超体积限制。", maxVideoFrames),
+		Category: "seemedia",
+	})
+	s.Settings().RegisterDef(sdk.ConfigDef{
+		Key: "timeout_seconds", Default: "120", Type: "int",
+		DisplayName: "媒体处理超时（秒）",
+		Description: "单次取媒体/抽帧的时间上限。",
+		Category:    "seemedia",
+	})
+	p.loadSettings()
+
+	// ffmpeg/ffprobe 只在 see_video 时需要；探测结果缓存，缺失时在工具描述里说清。
+	p.ffmpeg, _ = exec.LookPath("ffmpeg")
+	p.ffprobe, _ = exec.LookPath("ffprobe")
+
+	srcParam := map[string]interface{}{
+		"path": map[string]interface{}{
+			"type": "string",
+			"description": "媒体文件路径（设备/工具回传的落盘文件，如 screensee / browser_screenshot 的截图）。" +
+				"path / digest / url 三者给其一。",
+		},
+		"digest": map[string]interface{}{
+			"type":        "string",
+			"description": "媒体在内容寻址库（CAS）里的 digest（用户上传已入库的媒体）。",
+		},
+		"url": map[string]interface{}{
+			"type":        "string",
+			"description": "媒体的 http(s) 直链。图片/音频原样交给模型，视频交给 ffmpeg 读取。",
+		},
+	}
+
+	if err := s.RegisterTool("see_image", sdk.ToolDef{
+		Name: "see_image",
+		Description: "【亲自看图】把一张图片**原样投给你自己**去看——你会在下一步直接看到这张图的真实画面，" +
+			"而不是别人转述的文字描述。需要判读截图、看清图里的细节/布局/颜色时用它。" +
+			"（只想要一段文字描述、或你本身不支持视觉时，用 describe_image 更省。）" +
+			"来源三选一：path / digest / url。",
+		Parameters:   srcObject(srcParam),
+		ParallelSafe: false,
+	}, p.handleSeeImage); err != nil {
+		return err
+	}
+
+	videoDesc := "【亲自看视频】从一段视频里均匀抽若干帧**原样投给你自己**去看，你会直接看到这些画面。" +
+		"适合判读一段操作录屏、监控片段、动图的过程变化。来源三选一：path / digest / url。" +
+		"可选 frames 指定抽帧数（1-" + strconv.Itoa(maxVideoFrames) + "，默认 " + strconv.Itoa(defaultVideoFrames) + "）。"
+	if p.ffmpeg == "" {
+		videoDesc += " ★本机未检测到 ffmpeg，调用会失败；请先安装 ffmpeg。"
+	}
+	if err := s.RegisterTool("see_video", sdk.ToolDef{
+		Name:         "see_video",
+		Description:  videoDesc,
+		Parameters:   p.videoParams(srcParam),
+		ParallelSafe: false,
+	}, p.handleSeeVideo); err != nil {
+		return err
+	}
+
+	if err := s.RegisterTool("hear_audio", sdk.ToolDef{
+		Name: "hear_audio",
+		Description: "【亲自听音频】把一段音频**原样投给你自己**去听，你会直接听到它，" +
+			"而不是读一段转写文字。需要判断语气/音乐/非语音声音时用它。" +
+			"（只想要文字转写、或你本身不支持音频时，用 transcribe_audio 更省。）" +
+			"来源三选一：path / digest / url。",
+		Parameters:   srcObject(srcParam),
+		ParallelSafe: false,
+	}, p.handleHearAudio); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (p *Plugin) Stop() error { return nil }
+
+func srcObject(props map[string]interface{}) map[string]interface{} {
+	return map[string]interface{}{"type": "object", "properties": props}
+}
+
+func (p *Plugin) videoParams(src map[string]interface{}) map[string]interface{} {
+	props := map[string]interface{}{}
+	for k, v := range src {
+		props[k] = v
+	}
+	props["frames"] = map[string]interface{}{
+		"type":        "integer",
+		"description": fmt.Sprintf("可选：抽取帧数（1-%d，默认 %d）。", maxVideoFrames, defaultVideoFrames),
+	}
+	return srcObject(props)
+}
+
+func (p *Plugin) loadSettings() {
+	s := p.sdk.Settings()
+	if s == nil {
+		return
+	}
+	if v, _ := s.Get("video_frames"); v != nil {
+		if n := toInt(v); n > 0 {
+			p.videoFrames = clampFrames(n)
+		}
+	}
+	if v, _ := s.Get("timeout_seconds"); v != nil {
+		if n := toInt(v); n > 0 {
+			p.timeout = time.Duration(n) * time.Second
+		}
+	}
+}
+
+// ── 工具处理 ───────────────────────────────────────────────
+
+func (p *Plugin) handleSeeImage(args map[string]interface{}) (interface{}, error) {
+	url, err := p.resolveMediaURL(args, "image")
+	if err != nil {
+		return nil, err
+	}
+	p.sdk.SetToolBlocks([]sdk.ContentBlock{{
+		Type:     "image_url",
+		ImageURL: &sdk.ImageURL{URL: url, Detail: "auto"},
+	}})
+	return map[string]interface{}{
+		"status": "ok",
+		"note":   "图片已投给你——请在下一步直接查看画面本身（这不是文字描述）。",
+	}, nil
+}
+
+func (p *Plugin) handleHearAudio(args map[string]interface{}) (interface{}, error) {
+	url, err := p.resolveMediaURL(args, "audio")
+	if err != nil {
+		return nil, err
+	}
+	p.sdk.SetToolBlocks([]sdk.ContentBlock{{
+		Type:     "audio_url",
+		AudioURL: &sdk.AudioURL{URL: url},
+	}})
+	return map[string]interface{}{
+		"status": "ok",
+		"note":   "音频已投给你——请在下一步直接聆听（这不是转写文字）。",
+	}, nil
+}
+
+func (p *Plugin) handleSeeVideo(args map[string]interface{}) (interface{}, error) {
+	if p.ffmpeg == "" {
+		return nil, fmt.Errorf("本机未安装 ffmpeg，无法从视频抽帧；请先安装 ffmpeg（apt install ffmpeg 或等价命令）")
+	}
+	n := p.videoFrames
+	if v, ok := args["frames"]; ok {
+		if k := toInt(v); k > 0 {
+			n = clampFrames(k)
+		}
+	}
+
+	input, cleanup, err := p.resolveVideoInput(args)
+	if err != nil {
+		return nil, err
+	}
+	defer cleanup()
+
+	frames, err := p.extractFrames(input, n)
+	if err != nil {
+		return nil, err
+	}
+	if len(frames) == 0 {
+		return nil, fmt.Errorf("未能从视频抽到任何帧（文件可能损坏或不是视频）")
+	}
+
+	blocks := make([]sdk.ContentBlock, 0, len(frames))
+	for _, f := range frames {
+		dataURL := "data:image/png;base64," + base64.StdEncoding.EncodeToString(f)
+		blocks = append(blocks, sdk.ContentBlock{
+			Type:     "image_url",
+			ImageURL: &sdk.ImageURL{URL: dataURL, Detail: "auto"},
+		})
+	}
+	p.sdk.SetToolBlocks(blocks)
+	return map[string]interface{}{
+		"status": "ok",
+		"frames": len(blocks),
+		"note": fmt.Sprintf("已抽取 %d 帧并投给你——请在下一步直接查看这些画面，"+
+			"按时间顺序理解过程变化。", len(blocks)),
+	}, nil
+}
+
+// ── 来源解析 ───────────────────────────────────────────────
+
+// resolveMediaURL 把 path/digest/url 解析成可直接放进 image_url/audio_url 的字符串。
+//
+//	url    → 原样返回（http 直链，交给上游拉取；不下载、不入 CAS）
+//	path   → 读本地文件，转 data URL
+//	digest → 从 CAS 取回字节，转 data URL
+//
+// kind 仅用于在扩展名/元信息都缺失时猜一个兜底 MIME（image 或 audio）。
+func (p *Plugin) resolveMediaURL(args map[string]interface{}, kind string) (string, error) {
+	path := strings.TrimSpace(argStr(args, "path"))
+	digest := strings.TrimSpace(argStr(args, "digest"))
+	rawURL := strings.TrimSpace(argStr(args, "url"))
+
+	switch {
+	case rawURL != "":
+		if !isHTTPURL(rawURL) {
+			return "", fmt.Errorf("url 必须是 http(s) 直链，实际: %q", rawURL)
+		}
+		return rawURL, nil
+
+	case path != "":
+		b, err := os.ReadFile(path)
+		if err != nil {
+			return "", fmt.Errorf("读取文件失败 %s: %w", path, err)
+		}
+		if len(b) == 0 {
+			return "", fmt.Errorf("文件为空: %s", path)
+		}
+		return dataURL(mimeByExtOr(path, kind), b), nil
+
+	case digest != "":
+		if p.sdk.Media() == nil {
+			return "", fmt.Errorf("内容寻址库不可用，无法按 digest 取媒体")
+		}
+		b, err := p.sdk.Media().Get(digest)
+		if err != nil {
+			return "", fmt.Errorf("按 digest 取媒体失败 %s: %w", digest, err)
+		}
+		mime := fallbackMIME(kind)
+		if info, serr := p.sdk.Media().Stat(digest); serr == nil && info.MIME != "" {
+			mime = info.MIME
+		}
+		return dataURL(mime, b), nil
+	}
+	return "", fmt.Errorf("没有可处理的媒体。请传 path（设备/工具回传的文件，如 screensee 的截图）、" +
+		"digest（CAS 里的媒体），或 url（http(s) 直链）三者之一")
+}
+
+// resolveVideoInput 为 see_video 解析出一个 ffmpeg 能读的输入。
+//
+//	url    → 原样交给 ffmpeg（ffmpeg 原生支持 http 输入），无需下载
+//	path   → 直接用该路径
+//	digest → 从 CAS 取字节落到临时文件（ffmpeg 需要可寻址的输入）
+//
+// 返回的 cleanup 负责删掉临时文件（path/url 情形是 no-op）。
+func (p *Plugin) resolveVideoInput(args map[string]interface{}) (input string, cleanup func(), err error) {
+	noop := func() {}
+	path := strings.TrimSpace(argStr(args, "path"))
+	digest := strings.TrimSpace(argStr(args, "digest"))
+	rawURL := strings.TrimSpace(argStr(args, "url"))
+
+	switch {
+	case rawURL != "":
+		if !isHTTPURL(rawURL) {
+			return "", noop, fmt.Errorf("url 必须是 http(s) 直链，实际: %q", rawURL)
+		}
+		return rawURL, noop, nil
+
+	case path != "":
+		if st, e := os.Stat(path); e != nil {
+			return "", noop, fmt.Errorf("视频文件不可读 %s: %w", path, e)
+		} else if st.Size() == 0 {
+			return "", noop, fmt.Errorf("视频文件为空: %s", path)
+		}
+		return path, noop, nil
+
+	case digest != "":
+		if p.sdk.Media() == nil {
+			return "", noop, fmt.Errorf("内容寻址库不可用，无法按 digest 取视频")
+		}
+		b, e := p.sdk.Media().Get(digest)
+		if e != nil {
+			return "", noop, fmt.Errorf("按 digest 取视频失败 %s: %w", digest, e)
+		}
+		f, e := os.CreateTemp("", "seemedia-*.video")
+		if e != nil {
+			return "", noop, fmt.Errorf("创建临时文件失败: %w", e)
+		}
+		if _, e := f.Write(b); e != nil {
+			f.Close()
+			os.Remove(f.Name())
+			return "", noop, fmt.Errorf("写入临时视频失败: %w", e)
+		}
+		f.Close()
+		name := f.Name()
+		return name, func() { os.Remove(name) }, nil
+	}
+	return "", noop, fmt.Errorf("没有可处理的视频。请传 path、digest 或 url 之一")
+}
+
+// ── 抽帧 ───────────────────────────────────────────────────
+
+// extractFrames 从视频里均匀抽 n 帧，返回每帧的 PNG 字节。
+//
+// 策略：先用 ffprobe 探时长，再在 duration*(i+0.5)/n 处逐帧快速定位（-ss 在 -i 前，
+// 关键帧 seek，快）。探时长失败（直播流/损坏头）时退回单遍 fps 滤镜抽前 n 帧。
+func (p *Plugin) extractFrames(input string, n int) ([][]byte, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), p.timeout)
+	defer cancel()
+
+	if dur := p.probeDuration(ctx, input); dur > 0 {
+		var frames [][]byte
+		for i := 0; i < n; i++ {
+			ts := dur * (float64(i) + 0.5) / float64(n)
+			b, err := p.grabFrameAt(ctx, input, ts)
+			if err != nil || len(b) == 0 {
+				continue // 单帧失败不致命：有几帧投几帧
+			}
+			frames = append(frames, b)
+		}
+		if len(frames) > 0 {
+			return frames, nil
+		}
+		// 定位抽帧全失败 → 落到单遍兜底
+	}
+	return p.grabFramesFPS(ctx, input, n)
+}
+
+func (p *Plugin) probeDuration(ctx context.Context, input string) float64 {
+	if p.ffprobe == "" {
+		return 0
+	}
+	out, err := exec.CommandContext(ctx, p.ffprobe,
+		"-v", "error",
+		"-show_entries", "format=duration",
+		"-of", "default=noprint_wrappers=1:nokey=1",
+		input,
+	).Output()
+	if err != nil {
+		return 0
+	}
+	d, _ := strconv.ParseFloat(strings.TrimSpace(string(out)), 64)
+	if d < 0 {
+		return 0
+	}
+	return d
+}
+
+// grabFrameAt 在 ts 秒处抓 1 帧 PNG，输出到 stdout。
+func (p *Plugin) grabFrameAt(ctx context.Context, input string, ts float64) ([]byte, error) {
+	cmd := exec.CommandContext(ctx, p.ffmpeg,
+		"-nostdin", "-loglevel", "error",
+		"-ss", strconv.FormatFloat(ts, 'f', 3, 64),
+		"-i", input,
+		"-frames:v", "1",
+		"-f", "image2pipe", "-c:v", "png",
+		"pipe:1",
+	)
+	var buf bytes.Buffer
+	cmd.Stdout = &buf
+	if err := cmd.Run(); err != nil {
+		return nil, err
+	}
+	return buf.Bytes(), nil
+}
+
+// grabFramesFPS 单遍抽前 n 帧（兜底，用于探不到时长的流）。
+func (p *Plugin) grabFramesFPS(ctx context.Context, input string, n int) ([][]byte, error) {
+	dir, err := os.MkdirTemp("", "seemedia-frames-")
+	if err != nil {
+		return nil, fmt.Errorf("创建临时目录失败: %w", err)
+	}
+	defer os.RemoveAll(dir)
+
+	cmd := exec.CommandContext(ctx, p.ffmpeg,
+		"-nostdin", "-loglevel", "error",
+		"-i", input,
+		"-vf", "thumbnail",
+		"-frames:v", strconv.Itoa(n),
+		filepath.Join(dir, "f-%03d.png"),
+	)
+	if err := cmd.Run(); err != nil {
+		return nil, fmt.Errorf("ffmpeg 抽帧失败: %w", err)
+	}
+	entries, _ := filepath.Glob(filepath.Join(dir, "f-*.png"))
+	var frames [][]byte
+	for _, e := range entries {
+		if b, err := os.ReadFile(e); err == nil && len(b) > 0 {
+			frames = append(frames, b)
+		}
+	}
+	return frames, nil
+}
+
+// ── 纯助手 ─────────────────────────────────────────────────
+
+func clampFrames(n int) int {
+	if n < 1 {
+		return defaultVideoFrames
+	}
+	if n > maxVideoFrames {
+		return maxVideoFrames
+	}
+	return n
+}
+
+func isHTTPURL(s string) bool {
+	return strings.HasPrefix(s, "http://") || strings.HasPrefix(s, "https://")
+}
+
+func dataURL(mime string, b []byte) string {
+	return "data:" + mime + ";base64," + base64.StdEncoding.EncodeToString(b)
+}
+
+func mimeByExtOr(path, kind string) string {
+	if m := mimeByExt(path); m != "" {
+		return m
+	}
+	return fallbackMIME(kind)
+}
+
+func fallbackMIME(kind string) string {
+	if kind == "audio" {
+		return "audio/wav"
+	}
+	return "image/png"
+}
+
+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 ".bmp":
+		return "image/bmp"
+	case ".wav":
+		return "audio/wav"
+	case ".mp3":
+		return "audio/mpeg"
+	case ".m4a", ".aac":
+		return "audio/aac"
+	case ".ogg", ".oga":
+		return "audio/ogg"
+	case ".flac":
+		return "audio/flac"
+	}
+	return ""
+}
+
+func argStr(args map[string]interface{}, key string) string {
+	if v, ok := args[key]; ok {
+		if s, ok := v.(string); ok {
+			return s
+		}
+	}
+	return ""
+}
+
+func toInt(v interface{}) int {
+	switch n := v.(type) {
+	case int:
+		return n
+	case int64:
+		return int(n)
+	case float64:
+		return int(n)
+	case string:
+		i, _ := strconv.Atoi(strings.TrimSpace(n))
+		return i
+	}
+	return 0
+}

internal/plugins/seemedia/plugin_test.go

@@ -0,0 +1,171 @@
+package seemedia
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// seemedia 让模型**一手**看图/看视频/听音频（SetToolBlocks 直投主模型），
+// 与 multimodal（二手文字描述）并存。
+//
+// 这些判据钉住的是**不变量**，不是某次实现：
+//
+//	① 来源解析三条路（url 透传 / path 读盘转 data URL / digest 取 CAS）与优先级
+//	② 没有任何来源时报错，且错误**可操作**（说清传什么）
+//	③ 抽帧数永远被 clamp 到 [1, maxVideoFrames]——对齐内核 modalfallback 的约束
+//	④ 直投工具必须声明 ParallelSafe:false（SetToolBlocks 写的是"当前 call"的块，
+//	   并发多工具会串台）
+
+// ---- ① / ② 来源解析 ----
+
+func TestResolveMediaURL_URLPassthrough(t *testing.T) {
+	p := &Plugin{}
+	got, err := p.resolveMediaURL(map[string]interface{}{"url": "https://x/y.png"}, "image")
+	if err != nil {
+		t.Fatalf("http 直链应原样透传: %v", err)
+	}
+	if got != "https://x/y.png" {
+		t.Errorf("url 应原样返回（不下载、不转 data URL），实际: %q", got)
+	}
+	// 非 http 的 url 要被拒（避免 file:// 之类绕过 path 分支的本地读）
+	if _, err := p.resolveMediaURL(map[string]interface{}{"url": "file:///etc/passwd"}, "image"); err == nil {
+		t.Error("非 http(s) 的 url 必须被拒绝")
+	}
+}
+
+func TestResolveMediaURL_PathWinsOverDigest(t *testing.T) {
+	p := &Plugin{}
+	dir := t.TempDir()
+	fp := filepath.Join(dir, "shot.jpg")
+	if err := os.WriteFile(fp, []byte{0xFF, 0xD8, 0xFF, 1, 2}, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// path 与 digest 同时给：path 优先，且**不碰 CAS**（p.sdk 为 nil 也不该 panic）
+	got, err := p.resolveMediaURL(map[string]interface{}{"path": fp, "digest": "deadbeef"}, "image")
+	if err != nil {
+		t.Fatalf("path 优先时应成功: %v", err)
+	}
+	if !strings.HasPrefix(got, "data:image/jpeg;base64,") {
+		t.Errorf("应按扩展名给 image/jpeg data URL，实际前缀: %.40s", got)
+	}
+	// url 又比 path 优先
+	got2, err := p.resolveMediaURL(map[string]interface{}{"url": "http://a/b", "path": fp}, "image")
+	if err != nil || got2 != "http://a/b" {
+		t.Errorf("url 应比 path 优先，实际: %q err=%v", got2, err)
+	}
+}
+
+func TestResolveMediaURL_NoSourceIsActionable(t *testing.T) {
+	p := &Plugin{}
+	_, err := p.resolveMediaURL(map[string]interface{}{}, "image")
+	if err == nil {
+		t.Fatal("无任何来源时必须报错")
+	}
+	msg := err.Error()
+	for _, want := range []string{"path", "digest", "url"} {
+		if !strings.Contains(msg, want) {
+			t.Errorf("错误信息要指明可传 %s，实际: %v", want, err)
+		}
+	}
+}
+
+func TestResolveMediaURL_FileErrorsSpecific(t *testing.T) {
+	p := &Plugin{}
+	if _, err := p.resolveMediaURL(map[string]interface{}{"path": "/nope/x.jpg"}, "image"); err == nil ||
+		!strings.Contains(err.Error(), "/nope/x.jpg") {
+		t.Errorf("读取失败应带路径，实际: %v", err)
+	}
+	dir := t.TempDir()
+	empty := filepath.Join(dir, "e.png")
+	if err := os.WriteFile(empty, nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := p.resolveMediaURL(map[string]interface{}{"path": empty}, "image"); err == nil ||
+		!strings.Contains(err.Error(), "空") {
+		t.Errorf("空文件应明说「空」，实际: %v", err)
+	}
+}
+
+func TestFallbackMIME(t *testing.T) {
+	if fallbackMIME("audio") != "audio/wav" {
+		t.Error("audio 兜底应为 audio/wav")
+	}
+	if fallbackMIME("image") != "image/png" {
+		t.Error("image 兜底应为 image/png")
+	}
+	// 未知 kind 落到 image（图是最常见的一手媒体）
+	if fallbackMIME("??") != "image/png" {
+		t.Error("未知 kind 应兜底 image/png")
+	}
+}
+
+// ---- ③ 抽帧数 clamp ----
+
+func TestClampFrames(t *testing.T) {
+	cases := map[int]int{
+		-5:  defaultVideoFrames, // 非正数回默认，而不是 0 帧（0 帧=白调一次）
+		0:   defaultVideoFrames,
+		1:   1,
+		6:   6,
+		10:  10,
+		11:  maxVideoFrames, // 超限夹到上限，不放任上游超体积
+		999: maxVideoFrames,
+	}
+	for in, want := range cases {
+		if got := clampFrames(in); got != want {
+			t.Errorf("clampFrames(%d)=%d，期望 %d", in, got, want)
+		}
+	}
+	// 不变量：上限必须 ≥ 默认，否则默认值会被自己夹掉
+	if maxVideoFrames < defaultVideoFrames {
+		t.Fatal("maxVideoFrames 不能小于 defaultVideoFrames")
+	}
+}
+
+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.bmp": "image/bmp",
+		"a.wav": "audio/wav", "a.mp3": "audio/mpeg", "a.flac": "audio/flac",
+		"a.bin": "", "noext": "",
+	} {
+		if got := mimeByExt(p); got != want {
+			t.Errorf("mimeByExt(%q)=%q，期望 %q", p, got, want)
+		}
+	}
+}
+
+func TestIsHTTPURL(t *testing.T) {
+	for s, want := range map[string]bool{
+		"http://a":   true,
+		"https://a":  true,
+		"ftp://a":    false,
+		"file:///x":  false,
+		"/local/x":   false,
+		"data:image": false,
+	} {
+		if got := isHTTPURL(s); got != want {
+			t.Errorf("isHTTPURL(%q)=%v，期望 %v", s, got, want)
+		}
+	}
+}
+
+// ---- ④ 直投工具的并发契约 ----
+//
+// SetToolBlocks 写的是"当前 call"的媒体块（IOManager.SetToolBlocks 无 call_id
+// 时的兼容入口），并发执行多个直投工具会把彼此的块串到一起。所以三个工具都
+// 必须 ParallelSafe:false。这条判据跨实现有效：谁把它改回 true，谁就引入串台。
+func TestSeeToolsAreNotParallelSafe(t *testing.T) {
+	src, err := os.ReadFile("plugin.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(src)
+	// 不得出现 ParallelSafe:true（本插件所有工具都直投，必须串行）
+	if strings.Contains(strings.ReplaceAll(s, " ", ""), "ParallelSafe:true") {
+		t.Error("seemedia 的直投工具不得声明 ParallelSafe:true —— " +
+			"SetToolBlocks 写的是当前 call 的块，并发会串台")
+	}
+}