Cyrene_v2/internal/runtime/multimodal/vision/router.go

package vision

// Assessment 是模型对自己读图结果的置信度。
//
// Deprecated placeholder（裁决 14.4.1③/14.4.5②）：第二层不再是「结构化自评」，
// 而是主模型自己按需调用视觉/OCR 工具（design/06 §0 第 2 层）。因此
// SelfAssessment 目前没有任何生产者：主模型要复核读图效果时，直接调用
// vision/ocr 工具即可，本包不再要求它吐出一个自评字段。保留该类型只为兼容
// 既有调用面；新代码不要依赖它。
type Assessment string

const (
	// AssessmentUnknown 表示模型未给出自评。
	AssessmentUnknown Assessment = "unknown"
	// AssessmentGood 表示模型对自己的读图结果有信心。
	AssessmentGood Assessment = "good"
	// AssessmentPoor 表示模型判定自己的识别效果差。
	AssessmentPoor Assessment = "poor"
)

// ModelInfo 描述主模型的视觉能力。
type ModelInfo struct {
	// Name 标识模型。
	Name string
	// SupportsVision 报告模型是否接受图像输入。
	SupportsVision bool
	// SelfAssessment 是模型对当前图像的自评置信度。
	// 当 SupportsVision 为真时，它决定是否走第二层工具路由。
	SelfAssessment Assessment
}

// DecisionKind 是选定的分层路由。
type DecisionKind string

const (
	// KindMain 把图像连同上下文一起交给主模型。
	KindMain DecisionKind = "main"
	// KindVisionTool 路由到专用视觉工具，只返回工具
	// 结果，使图像不占用主模型上下文。
	KindVisionTool DecisionKind = "vision_tool"
	// KindOCRTool 路由到 OCR 工具，只返回抽取出的文字。
	KindOCRTool DecisionKind = "ocr_tool"
	// KindUnsupported 表示没有任何路由能处理该图像。
	KindUnsupported DecisionKind = "unsupported"
)

// Decision 是一次路由调用的结果。
type Decision struct {
	// Kind 是选定的路由。
	Kind DecisionKind
	// Tool 指名要调用的视觉或 OCR 工具，当 Kind 为工具路由时设置。
	Tool string
	// Reason 是便于可观测与日志的人类可读说明。
	Reason string
}

// RouteRequest 携带调用方在模型信息之外给出的路由提示。
//
// Deprecated（裁决 14.4.5②）：生产没有任何调用方填充这两个提示 —— 图像是转成
// 文字还是留给主模型，由主模型的能力声明（models.json multimodal）与它自己
// 按需调用视觉/OCR 工具决定，不再靠调用方猜「这张图主要是文字」。字段保留
// 只为兼容既有测试与调用面。
type RouteRequest struct {
	// TextPrimary 表示用户指出图像以文字为主，因此
	// 优先使用 OCR 工具而非通用视觉模型。
	TextPrimary bool
	// MainSelfAssessedPoor 在主模型已自评读图效果
	// 较差、请求走 vision/OCR 工具路由时置位。
	MainSelfAssessedPoor bool
}

// RouterOption 配置 Router。
type RouterOption func(*Router)

// WithVisionTool 绑定已注册的图像理解工具名。
func WithVisionTool(name string) RouterOption {
	return func(r *Router) {
		if name != "" {
			r.visionTool = name
		}
	}
}

// WithOCRTool 绑定已注册的 OCR 工具名。
func WithOCRTool(name string) RouterOption {
	return func(r *Router) {
		if name != "" {
			r.ocrTool = name
		}
	}
}

// Router 实现分层视觉路由策略。它不做任何 I/O；调用方
// 用返回的 Decision 去派发请求。
type Router struct {
	visionTool string
	ocrTool    string
}

// NewRouter 构造 Router。未知（空）的工具名会让对应
// 路由不可用，于是路由器降级为 KindMain 或 KindUnsupported。
func NewRouter(opts ...RouterOption) *Router {
	r := &Router{}
	for _, o := range opts {
		o(r)
	}
	return r
}

// Route 依据目标模型信息与调用方提示，为一次图像请求
// 选出分层路由。顺序为：主模型能看图且
// 未自评较差时直接用它（第一层）；否则用能替换
// 上下文中图像的视觉或 OCR 工具（第二、三层）；再否则
// 没有任何东西能处理该图像时给出 KindUnsupported。
func (r *Router) Route(target ModelInfo, req RouteRequest) Decision {
	poor := target.SelfAssessment == AssessmentPoor || req.MainSelfAssessedPoor
	// 第一层：主模型接受图像且自信，优先使用它。
	if target.SupportsVision && !poor {
		return Decision{
			Kind:   KindMain,
			Reason: "main model supports vision and is confident; use it directly",
		}
	}
	// 用户说明图像以文字为主时优先 OCR。
	if req.TextPrimary && r.ocrTool != "" {
		return Decision{Kind: KindOCRTool, Tool: r.ocrTool, Reason: "image is mainly text; route to OCR"}
	}
	if r.visionTool != "" {
		return Decision{Kind: KindVisionTool, Tool: r.visionTool, Reason: "route to dedicated vision tool"}
	}
	if r.ocrTool != "" {
		return Decision{Kind: KindOCRTool, Tool: r.ocrTool, Reason: "route to OCR tool"}
	}
	// 未绑定任何工具。能看图的主模型仍是唯一选择。
	if target.SupportsVision {
		return Decision{Kind: KindMain, Reason: "no vision/OCR tool bound; keep image with main model"}
	}
	return Decision{Kind: KindUnsupported, Reason: "main model cannot see and no vision/OCR tool is bound"}
}