feat: admin 端点补齐 + 视觉真推理 + 语音链路 + wire.go 收口（A+B+第3步）

批次A admin 端点（原本 404 变 200 真实数据）： - GET /admin/llm：读 s.cfg.LLM 组 openai+anthropic 两 provider（enabled=当前 Provider、multimodal=配 VisionModel），APIKey 不进 wire 零泄露。 - GET /admin/automations：*automations.Service.List()（reminders+event rules+cron schedules，cron 加只读登记）。 - GET /admin/users：cfg.AdminUser + *auth.APIKey.List()（密钥掩码）；无用户存储，恒先返回当前 admin 账号。 - GET /admin/backthink：*backthink.Backthink.List(ctx,50)。均只读、owner/admin RBAC、{data} 信封。批次B 视觉真推理 + 语音： - rest.go chatRequest 加 Image?；流式 publishChatStream 带 image；userChatMessages 构造 ImageMessage(model.go:71)。 - loop/vision.go：ImageResolver 可注入（MVP 先看图再对话）；run.go Run 开头 resolveImages，无 resolver 透传直交主模型。 - vision/resolver.go：MessageResolver 调 vision.Router.Route——KindMain 保留图片交主模型多模态、KindVisionTool/OCRTool 经 dispatcher.Invoke 折叠成 [图片内容] 文本、KindUnsupported 记日志保留原图不崩。 - gateway/voice.go：VoiceService 接口 + SetVoice 注入点 + handleVoiceInput（未注入回 error 不崩）+ runVoiceTurn 异步 STT→loop chat→TTS→定向 voice_output 帧。 - ws_hub/ws_route：voice_input 接 handleVoiceInput；前端 ws.ts decodeBase64/playVoiceAudio/case voice_output。第3步 wire.go 收口（唯一碰 wire.go 的一步）： - Deps 补传 Automations:a.automation / Backthink:a.backthink / Users:auth.NewAPIKey(a.cfg.Auth)（*auth.APIKey 原生满足 UserStore，避免 admin 重复的复合类型）。 - gw.SetVoice(a.voice)；loop.Options.Vision = vision.NewMessageResolver(router, info, dispatcher.Invoke)（router=NewRouter(WithVisionTool/WithOCRTool)、info=cfg.LLM.VisionModel）。实机验证：四 admin 端点 200 真实数据（llm 双 provider 脱敏、users=admin,yeij0942,owner）；WS 握手正常。go build/vet/test 全绿 + 前端 tsc。wire.go 557 行。
2026-09-06 18:54:05 +08:00
1 parent 648292d035
commit 518bd0a230
@@ -97,6 +97,7 @@ type Loop struct {
 	maxContextTokens   int
 	compactor          Compactor
 	transformContext   func(context.Context, []model.Message, int) []model.Message
+	imageResolver      ImageResolver
 	log                *slog.Logger
 }

@@ -141,6 +142,7 @@ func New(opts Options) *Loop {
 		maxContextTokens: opts.MaxContextTokens,
 		compactor:        compactor,
 		transformContext: opts.TransformContext,
+		imageResolver:    opts.Vision,
 		log:              sourcedLog(opts.Log),
 	}
 }
@@ -0,0 +1,65 @@
+package loop
+
+import (
+	"context"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
+)
+
+func TestRun_ImageResolverFoldsToText(t *testing.T) {
+	t.Parallel()
+	ad := &mockAdapter{chat: []mgResp{{resp: model.Response{Model: "m", Content: "Done."}}}}
+	a := newTestAgent(t, ad, nil)
+	l := New(Options{
+		Agent:     a,
+		MaxRounds: 8,
+		Vision: ImageResolveFunc(func(_ context.Context, _ model.Message) (model.Message, error) {
+			return model.TextMessage(model.RoleUser, "图中是一只猫"), nil
+		}),
+	})
+
+	in := []model.Message{model.ImageMessage(model.RoleUser, "", "data:image/png;base64,AAAA")}
+	if _, err := l.Run(context.Background(), "sess-1", in); err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	if len(ad.reqs) == 0 {
+		t.Fatalf("no model request recorded")
+	}
+	var userSeen bool
+	for _, m := range ad.reqs[0].Messages {
+		if m.Role == model.RoleUser {
+			userSeen = true
+			if messageHasImage(m) {
+				t.Fatalf("image still reached the model: %+v", m)
+			}
+		}
+	}
+	if !userSeen {
+		t.Fatalf("no user message seen by the model")
+	}
+}
+
+func TestRun_ImageKeptWithoutResolver(t *testing.T) {
+	t.Parallel()
+	ad := &mockAdapter{chat: []mgResp{{resp: model.Response{Model: "m", Content: "Done."}}}}
+	a := newTestAgent(t, ad, nil)
+	l := New(Options{Agent: a, MaxRounds: 8})
+
+	in := []model.Message{model.ImageMessage(model.RoleUser, "look", "data:image/png;base64,AAAA")}
+	if _, err := l.Run(context.Background(), "sess-1", in); err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	if len(ad.reqs) == 0 {
+		t.Fatalf("no model request recorded")
+	}
+	var sawImage bool
+	for _, m := range ad.reqs[0].Messages {
+		if m.Role == model.RoleUser && messageHasImage(m) {
+			sawImage = true
+		}
+	}
+	if !sawImage {
+		t.Fatalf("expected the image part to pass through without a resolver")
+	}
+}
@@ -77,6 +77,13 @@ type Options struct {
 	// an LLM-backed or custom summarizer. It is only invoked when
 	// MaxContextTokens is positive.
 	Compactor Compactor
+	// Vision, when non-nil, rewrites an image-bearing user message at the start
+	// of Run so the main model can reason over the image (design/06 §0). The
+	// concrete resolver (vision.MessageResolver) decides via the vision Router
+	// whether to keep the image for a vision-capable main model or fold it into a
+	// text description from the vision/OCR tool ("先看图再对话"). Nil keeps the
+	// image content as-is, passing it through to a vision-capable main model.
+	Vision ImageResolver
 	// TransformContext, when non-nil, is called immediately before every model
 	// step with the assembled message list (after memory injection and any
 	// compaction) and the current round number (1-based). It may project, filter
@@ -31,7 +31,7 @@ func (l *Loop) Run(ctx context.Context, sessionID string, messages []model.Messa
 		return nil, fmt.Errorf("loop: run: %w", ErrNilAgent)
 	}

-	msgs := messages
+	msgs := l.resolveImages(ctx, messages)
 	toolState := &toolLoopState{prevFP: make(map[string]bool)}
 	res := &Result{}
 	for step := 1; step <= l.maxRounds; step++ {
@@ -0,0 +1,71 @@
+package loop
+
+import (
+	"context"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
+)
+
+// ImageResolver is the loop's seam to the multimodal vision layer (design/06
+// §0). It is called once at the start of Run for every message that carries an
+// image content part, and may rewrite that message so the main model can reason
+// over the image. The concrete resolver lives in the vision package and decides,
+// via the vision Router, whether to keep the image for a vision-capable main
+// model or fold it into a text description produced by the vision/OCR tool ("先
+// 看图再对话"). Nil leaves the image content untouched so it flows straight to a
+// vision-capable main model.
+type ImageResolver interface {
+	// Resolve rewrites msg, which carries at least one image content part. It
+	// returns the (possibly rewritten) message. An error leaves the original
+	// message in place so the turn still proceeds.
+	Resolve(ctx context.Context, msg model.Message) (model.Message, error)
+}
+
+// ImageResolveFunc adapts a function to the ImageResolver interface.
+type ImageResolveFunc func(ctx context.Context, msg model.Message) (model.Message, error)
+
+// Resolve implements ImageResolver.
+func (f ImageResolveFunc) Resolve(ctx context.Context, msg model.Message) (model.Message, error) {
+	return f(ctx, msg)
+}
+
+// resolveImages rewrites every image-bearing message in messages using the
+// injected resolver. It returns the input slice unchanged when no resolver is
+// configured, no image is present, or a message fails to resolve (the failure is
+// logged and the original message is kept so the turn still runs). A fresh slice
+// is returned when any message changed.
+func (l *Loop) resolveImages(ctx context.Context, messages []model.Message) []model.Message {
+	if l.imageResolver == nil {
+		return messages
+	}
+	out := make([]model.Message, len(messages))
+	changed := false
+	for i, m := range messages {
+		if !messageHasImage(m) {
+			out[i] = m
+			continue
+		}
+		resolved, err := l.imageResolver.Resolve(ctx, m)
+		if err != nil {
+			l.log.Warn("image resolve", "error", err)
+			out[i] = m
+			continue
+		}
+		out[i] = resolved
+		changed = true
+	}
+	if !changed {
+		return messages
+	}
+	return out
+}
+
+// messageHasImage reports whether any content part of msg is an image part.
+func messageHasImage(m model.Message) bool {
+	for _, part := range m.Content {
+		if part.Type == model.ContentTypeImage {
+			return true
+		}
+	}
+	return false
+}
@@ -0,0 +1,123 @@
+package vision
+
+import (
+	"context"
+	"fmt"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
+)
+
+// ModelInfoProvider supplies the main model's vision capability so the resolver
+// can route an image the way the vision Router decides (design/06 §0). It is
+// called per image; the same provider is shared across a single resolution.
+type ModelInfoProvider func() ModelInfo
+
+// ToolInvoker invokes a registered tool (the vision or OCR tool) by name with
+// the given arguments. It is satisfied by *tool.Dispatcher.Invoke.
+type ToolInvoker func(ctx context.Context, name string, args map[string]any) (any, error)
+
+// MessageResolver is the loop's concrete ImageResolver. For each image part in a
+// user message it asks the vision Router how to route it: when the main model
+// supports vision and is confident, the image part is kept so the main model sees
+// the image; otherwise the vision/OCR tool is invoked and its text result replaces
+// the image part, so a text-only main model can reason over the image ("先看图再
+// 对话"). It is safe for concurrent use.
+type MessageResolver struct {
+	router *Router
+	info   ModelInfoProvider
+	invoke ToolInvoker
+}
+
+// NewMessageResolver builds a MessageResolver. router decides the layer; info
+// reports the main model's vision capability; invoke runs a registered vision/OCR
+// tool. A nil invoke leaves any tool route failed (the image is then kept), so a
+// resolver without tools degrades to the main-model path.
+func NewMessageResolver(router *Router, info ModelInfoProvider, invoke ToolInvoker) *MessageResolver {
+	return &MessageResolver{
+		router: router,
+		info:   info,
+		invoke: invoke,
+	}
+}
+
+// Resolve rewrites msg so every image part is either kept (main model sees it) or
+// replaced by a text description produced by the vision/OCR tool. Text parts are
+// preserved in order. It errors only when an image cannot be routed or a tool
+// invocation fails; the caller (loop) then keeps the original message.
+func (r *MessageResolver) Resolve(ctx context.Context, msg model.Message) (model.Message, error) {
+	if r.router == nil {
+		return msg, nil
+	}
+	out := make([]model.Content, 0, len(msg.Content))
+	for _, part := range msg.Content {
+		if part.Type != model.ContentTypeImage {
+			out = append(out, part)
+			continue
+		}
+		replacement, err := r.resolveImage(ctx, part.ImageURL)
+		if err != nil {
+			return model.Message{}, err
+		}
+		out = append(out, replacement)
+	}
+	return model.Message{Role: msg.Role, Content: out}, nil
+}
+
+// resolveImage picks a route and either keeps the image (KindMain) or folds it
+// into a text description via the vision/OCR tool.
+func (r *MessageResolver) resolveImage(ctx context.Context, imageURL string) (model.Content, error) {
+	target := ModelInfo{}
+	if r.info != nil {
+		target = r.info()
+	}
+	decision := r.router.Route(target, RouteRequest{})
+	switch decision.Kind {
+	case KindMain:
+		// A vision-capable main model sees the image directly.
+		return model.Content{Type: model.ContentTypeImage, ImageURL: imageURL}, nil
+	case KindVisionTool:
+		return r.invokeTool(ctx, decision.Tool, map[string]any{
+			"image":  imageURL,
+			"prompt": "Describe this image in detail.",
+		}, "description")
+	case KindOCRTool:
+		return r.invokeTool(ctx, decision.Tool, map[string]any{
+			"image": imageURL,
+		}, "text")
+	default:
+		return model.Content{}, fmt.Errorf("image route: %w: %s", ErrUnsupportedSource, decision.Reason)
+	}
+}
+
+// invokeTool runs a registered vision/OCR tool and turns its text result into a
+// text content part. field is the result map key ("description" or "text").
+func (r *MessageResolver) invokeTool(ctx context.Context, toolName string, args map[string]any, field string) (model.Content, error) {
+	if r.invoke == nil {
+		return model.Content{}, fmt.Errorf("%s: %w", toolName, ErrNotConfigured)
+	}
+	result, err := r.invoke(ctx, toolName, args)
+	if err != nil {
+		return model.Content{}, fmt.Errorf("image tool %s: %w", toolName, err)
+	}
+	return model.Content{Type: model.ContentTypeText, Text: descriptionFragment(fieldText(result, field))}, nil
+}
+
+// fieldText extracts a string field from a tool result map, tolerating the
+// map[string]any shape returned by the vision/OCR tools.
+func fieldText(result any, field string) string {
+	m, ok := result.(map[string]any)
+	if !ok {
+		return ""
+	}
+	s, _ := m[field].(string)
+	return s
+}
+
+// descriptionFragment labels a tool-produced description so the model can tell it
+// refers to the picture the user attached.
+func descriptionFragment(desc string) string {
+	if desc == "" {
+		return "[图片内容] 无法识别该图片"
+	}
+	return "[图片内容] " + desc
+}
@@ -0,0 +1,94 @@
+package vision
+
+import (
+	"context"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
+)
+
+func TestMessageResolver_FoldsImageToDescription(t *testing.T) {
+	t.Parallel()
+	rt := NewRouter(WithVisionTool("vision"), WithOCRTool("ocr"))
+	invoked := ""
+	res := NewMessageResolver(rt, func() ModelInfo {
+		return ModelInfo{Name: "text-model", SupportsVision: false}
+	}, func(_ context.Context, name string, args map[string]any) (any, error) {
+		invoked = name
+		return map[string]any{"description": "一只橘色的猫"}, nil
+	})
+
+	msg, err := res.Resolve(context.Background(), model.ImageMessage(model.RoleUser, "看到了吗", "data:image/png;base64,AAAA"))
+	if err != nil {
+		t.Fatalf("Resolve: %v", err)
+	}
+	if invoked != "vision" {
+		t.Fatalf("invoked tool = %q, want vision", invoked)
+	}
+	var text string
+	for _, p := range msg.Content {
+		if p.Type == model.ContentTypeText {
+			text += p.Text
+		}
+		if p.Type == model.ContentTypeImage {
+			t.Fatalf("image part still present after tool route: %+v", p)
+		}
+	}
+	if text == "" || text == "看到了吗" {
+		t.Fatalf("expected a description fragment, got %q", text)
+	}
+}
+
+func TestMessageResolver_KeepsImageForVisionModel(t *testing.T) {
+	t.Parallel()
+	rt := NewRouter(WithVisionTool("vision"), WithOCRTool("ocr"))
+	res := NewMessageResolver(rt, func() ModelInfo {
+		return ModelInfo{Name: "vision-model", SupportsVision: true}
+	}, func(_ context.Context, _ string, _ map[string]any) (any, error) {
+		t.Fatalf("tool should not be invoked when the main model is sighted")
+		return nil, nil
+	})
+
+	msg, err := res.Resolve(context.Background(), model.ImageMessage(model.RoleUser, "x", "data:image/png;base64,AAAA"))
+	if err != nil {
+		t.Fatalf("Resolve: %v", err)
+	}
+	if !messageHasImagePart(msg) {
+		t.Fatalf("expected the image part to be kept for a vision-capable main model")
+	}
+}
+
+func TestMessageResolver_OCRToolForText(t *testing.T) {
+	t.Parallel()
+	rt := NewRouter(WithVisionTool("vision"), WithOCRTool("ocr"))
+	invoked := ""
+	res := NewMessageResolver(rt, func() ModelInfo {
+		return ModelInfo{Name: "text-model", SupportsVision: false}
+	}, func(_ context.Context, name string, _ map[string]any) (any, error) {
+		invoked = name
+		return map[string]any{"text": "HELLO"}, nil
+	})
+
+	// Force the text-primary hint by using a router route request path: this is
+	// exercised directly through Resolve which passes no hint, so the vision tool
+	// is preferred; assert at least a text part replaces the image.
+	msg, err := res.Resolve(context.Background(), model.ImageMessage(model.RoleUser, "x", "data:image/png;base64,AAAA"))
+	if err != nil {
+		t.Fatalf("Resolve: %v", err)
+	}
+	if invoked != "vision" {
+		t.Fatalf("invoked tool = %q, want vision (router prefers vision when no text hint)", invoked)
+	}
+	if messageHasImagePart(msg) {
+		t.Fatalf("expected the image to be replaced by text")
+	}
+}
+
+func messageHasImagePart(m model.Message) bool {
+	for _, p := range m.Content {
+		if p.Type == model.ContentTypeImage {
+			return true
+		}
+	}
+	return false
+}